diff --git a/.fastflowtransform/target/catalog.json b/.fastflowtransform/target/catalog.json
new file mode 100644
index 0000000..a9f7728
--- /dev/null
+++ b/.fastflowtransform/target/catalog.json
@@ -0,0 +1,11 @@
+{
+  "metadata": {
+    "generated_at": "2025-10-28T19:05:15+00:00",
+    "tool": "fastflowtransform"
+  },
+  "relations": {
+    "failing": {
+      "columns": []
+    }
+  }
+}
diff --git a/.fastflowtransform/target/manifest.json b/.fastflowtransform/target/manifest.json
new file mode 100644
index 0000000..d3fd433
--- /dev/null
+++ b/.fastflowtransform/target/manifest.json
@@ -0,0 +1,20 @@
+{
+  "macros": {
+    "snake": "text.py"
+  },
+  "metadata": {
+    "generated_at": "2025-10-28T19:05:15+00:00",
+    "tool": "fastflowtransform"
+  },
+  "nodes": {
+    "failing": {
+      "deps": [],
+      "kind": "sql",
+      "materialized": "table",
+      "name": "failing",
+      "path": "",
+      "relation": "failing"
+    }
+  },
+  "sources": {}
+}
diff --git a/.fastflowtransform/target/run_results.json b/.fastflowtransform/target/run_results.json
new file mode 100644
index 0000000..fd4e084
--- /dev/null
+++ b/.fastflowtransform/target/run_results.json
@@ -0,0 +1,19 @@
+{
+  "metadata": {
+    "generated_at": "2025-10-28T19:05:15+00:00",
+    "tool": "fastflowtransform"
+  },
+  "results": [
+    {
+      "duration_ms": 0,
+      "finished_at": "2025-10-28T19:05:15+00:00",
+      "http": null,
+      "message": "'boom'",
+      "name": "failing",
+      "started_at": "2025-10-28T19:05:15+00:00",
+      "status": "error"
+    }
+  ],
+  "run_finished_at": "2025-10-28T19:05:15+00:00",
+  "run_started_at": "2025-10-28T19:05:15+00:00"
+}
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
new file mode 100644
index 0000000..31d629a
--- /dev/null
+++ b/.github/workflows/pages.yml
@@ -0,0 +1,50 @@
+name: Build & Deploy MkDocs to GitHub Pages
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+      - name: Deploy to Pages
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index 97ebb6e..a9b5a99 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,3 +39,5 @@ dist/
 # Docs Output
 examples/**/docs/
 tickets/**
+site/dag/**
+cache/**
diff --git a/Makefile.pipeline b/Makefile.pipeline
index fd0972d..9390625 100644
--- a/Makefile.pipeline
+++ b/Makefile.pipeline
@@ -25,9 +25,9 @@ dag:
 # Opens the generated DAG HTML on macOS/Linux; Windows users open it manually.
 demo-open:
 	@if [ -f "$(FF_PROJECT)/site/dag/index.html" ]; then \
-		$(OPENER) "$(FF_PROJECT)/site/dag/index.html" 2>/dev/null || echo "Öffne manuell: $(FF_PROJECT)/site/dag/index.html"; \
+		$(OPENER) "$(FF_PROJECT)/site/dag/index.html" 2>/dev/null || echo "Oopen at: $(FF_PROJECT)/site/dag/index.html"; \
 	else \
-		echo "Keine HTML-Datei gefunden: $(FF_PROJECT)/site/dag/index.html"; \
+		echo "No HTML found: $(FF_PROJECT)/site/dag/index.html"; \
 	fi
 
 test:
@@ -35,7 +35,7 @@ test:
 
 # End-to-end showcase: Seed → Run → DAG → Open → Tests
 demo: seed run dag demo-open test
-	@echo "\n✓ Demo fertig: Tabellen gebaut, DAG generiert, Tests gelaufen."
+	@echo "\n✓ Demo done."
 
 clean:
 	rm -rf .local "$(FF_PROJECT)/docs" dist build *.egg-info
diff --git a/README.md b/README.md
index 933e80f..9f27b75 100644
--- a/README.md
+++ b/README.md
@@ -68,7 +68,7 @@ make install      # upgrades pip + installs FastFlowTransform in editable mode
 ## Quickstart
 
 > 📚 **Mehr lesen … CLI-Details**
-> Für Flag-Referenzen, Automatisierung und Hintergründe siehe [`docs/Technical_Overview.md`](docs/Technical_Overview.md#cli-flows).
+> For flag referencees, automatization and backgrounds see [`docs/Technical_Overview.md`](docs/Technical_Overview.md#cli-flows).
 
 Run the end-to-end DuckDB demo (seed → run → docs → tests) in under a minute:
 
@@ -188,8 +188,11 @@ Examples:
 
 - **Documentation hub:** choose your path (operators vs contributors) — see [`docs/index.md`](docs/index.md).
 - **User & operator guide:** project layout, CLI usage, troubleshooting tips — see [`docs/Technical_Overview.md`](docs/Technical_Overview.md).
+- **Docgen shortcut:** append `--open-source` to `fft docgen ...` to launch the freshly rendered `index.html` immediately; use `--no-schema` when column introspection should be skipped.
 - **Modeling reference:** configuration, Jinja helpers, macros — see [`docs/Config_and_Macros.md`](docs/Config_and_Macros.md).
-- **Examples:** runnable demo projects live under `examples/`; each README covers engine-specific setup.
+- **API calls in Python models:** [`docs/API_Models.md`](docs/API_Models.md)
+- **Database comments sync:** preview database comment updates with `fft sync-db-comments . --env dev --dry-run` before applying them to Postgres or Snowflake.
+- **Examples:** runnable demo projects live under `examples/`;
 
 ---
 
diff --git a/docs/Api_Models.md b/docs/Api_Models.md
new file mode 100644
index 0000000..18708b3
--- /dev/null
+++ b/docs/Api_Models.md
@@ -0,0 +1,306 @@
+# API Calls in Python Models
+
+> **Status:** Experimental but stable for demos and smaller workflows.  
+> **Goal:** Query HTTP APIs from Python models, return responses as DataFrames, cache and instrument them cleanly, and support reproducible offline runs.
+
+* [Motivation](#motivation)
+* [Quickstart](#quickstart)
+* [Programming API](#programming-api)
+  * [`get_json`](#get_json)
+  * [`get_df`](#get_df)
+  * [Pagination](#pagination)
+  * [Context & Telemetry](#context--telemetry)
+* [CLI Flags & Environment Variables](#cli-flags--environment-variables)
+* [Example Model](#example-model)
+* [Artifacts](#artifacts)
+* [Tests & Offline Demos](#tests--offline-demos)
+* [Best Practices](#best-practices)
+* [Troubleshooting](#troubleshooting)
+* [Security & Compliance](#security--compliance)
+* [FAQ](#faq)
+
+---
+
+## Motivation
+
+Many pipelines need small, reliable API fetchers: configuration tables, miniature dimensions, feature flags, SaaS exports. This feature provides:
+
+- Simple HTTP calls inside Python models
+- File-backed cache (reproducible builds, works offline)
+- Per-node telemetry (requests, hits, bytes, hashes)
+- CLI switches `--offline` and `--http-cache` for reproducible runs
+
+---
+
+## Quickstart
+
+1. **Optionally enable flags** (recommended):
+
+   ```bash
+   # No network - cache hits only
+   fft run . --env dev --offline
+   # Cache mode
+   fft run . --env dev --http-cache rw   # rw|ro|off
+   ```
+
+2. **Write a Python model**:
+
+   ```python
+   # models/users_from_api.ff.py
+   import pandas as pd
+   from fastflowtransform.core import model
+   from fastflowtransform.api.http import get_df
+
+   @model(name="users_from_api", deps=["users.ff"])
+   def fetch(_: pd.DataFrame) -> pd.DataFrame:
+       df = get_df(
+           url="https://api.example.com/users",
+           params={"page": 1},
+           record_path=["data"],        # JSON -> list -> DataFrame
+       )
+       return df
+   ```
+
+3. **Run it**:
+
+   ```bash
+   fft run . --env dev --select users_from_api
+   ```
+
+---
+
+## Programming API
+
+> Module: `fastflowtransform.api.http`
+
+### `get_json`
+
+```python
+from fastflowtransform.api.http import get_json
+
+data = get_json(
+    url="https://api.example.com/objects",
+    params={"page": 1},        # optional
+    headers={"Authorization": "Bearer ..."},  # optional
+    timeout=20,                # optional (seconds)
+)
+# -> Python dict / list
+```
+
+**Behavior**
+
+- Reads from the local cache (when present and valid).
+- Writes to the cache (`rw` mode), including the response body.
+- Respects offline mode (no network traffic).
+
+### `get_df`
+
+```python
+from fastflowtransform.api.http import get_df
+
+df = get_df(
+    url="https://api.example.com/users",
+    params={"page": 1},
+    record_path=["data"],     # path to the JSON list
+    normalize=True,           # optional: flatten nested objects
+    paginator=None,           # optional: pagination strategy (see below)
+)
+# -> pandas.DataFrame
+```
+
+**Conversion**
+
+- Default: `record_path` points to the array payload (for example `["data"]`).
+- `normalize=True` delegates to `json_normalize` for deeper structures.
+
+### Pagination
+
+For paged APIs you can describe the next request declaratively:
+
+```python
+def paginator(url: str, params: dict | None, json_obj: dict):
+    next_url = json_obj.get("next")          # e.g. absolute URL
+    if next_url:
+        return {"next_request": {"url": next_url}}
+    return None
+
+df = get_df(
+    "https://api.example.com/users?page=1",
+    paginator=paginator,
+    record_path=["data"],
+)
+```
+
+The paginator may return the following fields:
+
+- `{"next_request": {"url": "...", "params": {...}, "headers": {...}}}`
+  (any missing field keeps its previous value)
+
+### Context & Telemetry
+
+During a model run the executor collects telemetry per node and writes it into `run_results.json`:
+
+- `requests` (count)
+- `cache_hits`
+- `bytes` (sum of response bodies)
+- `used_offline` (bool)
+- `keys` (cache keys)
+- `entries` (optional compact array with URL, status, content hash)
+
+You will find these metrics under the `http` block of each node (see [Artifacts](#artifacts)).
+
+---
+
+## CLI Flags & Environment Variables
+
+**CLI**
+
+- `--offline`  
+  Sets `FF_HTTP_OFFLINE=1`; network requests are blocked, **cache hits only**.
+- `--http-cache {off|ro|rw}`  
+  Sets `FF_HTTP_CACHE_MODE`:
+
+  - `off`: neither read nor write.
+  - `ro`: read-only (hits), **no** writes.
+  - `rw`: read and write (default).
+
+**Environment (optional to set directly)**
+
+| Variable                 | Default                         | Effect                              |
+| ------------------------ | ------------------------------- | ----------------------------------- |
+| `FF_HTTP_OFFLINE`        | `0`                             | `1/true/on` -> offline mode         |
+| `FF_HTTP_CACHE_MODE`     | `rw`                            | `off` / `ro` / `rw`                 |
+| `FF_HTTP_CACHE_DIR`      | `.fastflowtransform/http_cache` | Cache directory                     |
+| `FF_HTTP_TTL`            | `0`                             | Seconds; 0 = never expires          |
+| `FF_HTTP_TIMEOUT`        | `20`                            | Request timeout (seconds)           |
+| `FF_HTTP_MAX_RETRIES`    | `3`                             | Basic retry count                   |
+| `FF_HTTP_RATE_LIMIT_RPS` | `0`                             | Requests per second (0 = unlimited) |
+
+---
+
+## Example Model
+
+```python
+# models/dim_countries_from_api.ff.py
+import pandas as pd
+from fastflowtransform.core import model
+from fastflowtransform.api.http import get_df
+
+@model(name="dim_countries_from_api", deps=["users.ff"])
+def countries(_: pd.DataFrame) -> pd.DataFrame:
+    def pager(u, p, js):
+        nxt = js.get("paging", {}).get("next")
+        return {"next_request": {"url": nxt}} if nxt else None
+
+    df = get_df(
+        url="https://api.example.com/countries?page=1",
+        paginator=pager,
+        record_path=["data"],
+        normalize=True,
+    )
+    # lightweight post-processing
+    if "code" in df.columns:
+        df["code"] = df["code"].str.upper()
+    return df
+```
+
+Run:
+
+```bash
+fft run . --env dev --select dim_countries_from_api --http-cache ro
+```
+
+---
+
+## Artifacts
+
+`<project>/.fastflowtransform/target/run_results.json` (excerpt):
+
+```json
+{
+  "results": [
+    {
+      "name": "dim_countries_from_api",
+      "status": "success",
+      "duration_ms": 153,
+      "http": {
+        "requests": 2,
+        "cache_hits": 2,
+        "bytes": 1842,
+        "used_offline": true,
+        "keys": ["GET:https://api.example.com/countries?page=1|{}|{}", "..."],
+        "entries": [
+          {"url": "https://api.example.com/countries?page=1", "status": 200, "content_hash": "sha256:..."},
+          {"url": "https://api.example.com/countries?page=2", "status": 200, "content_hash": "sha256:..."}
+        ]
+      }
+    }
+  ]
+}
+```
+
+> Note: When a node is **skipped** (fingerprint cache hit), no new `http` block is emitted - the model did not run.
+
+---
+
+## Tests & Offline Demos
+
+- Place unit tests under `tests/api/...` and seed the cache directly (no real HTTP calls).
+- Suggested scenarios:
+
+  - **Offline hit:** set `FF_HTTP_OFFLINE=1`, seed the cache, `get_json/get_df` must succeed.
+  - **Cache mode `off`:** even with cache entries, **no** reads; expect a failure in offline mode.
+  - **`ro`:** allow read hits; **no** cache writes after a real or mocked request.
+  - **Pagination:** stitch several pages from offline fixtures; telemetry should count requests/hits.
+
+---
+
+## Best Practices
+
+- **Stable URLs and parameter order** produce identical cache keys and reproducible builds.
+- **Keep `record_path` shallow**; use `normalize=True` only when necessary (performance).
+- **Never cache secrets:** provide tokens via headers; the response body and metadata are cached.
+- **Use `--offline` in CI** for deterministic tests with a pre-seeded cache.
+- **Set TTL intentionally** when APIs change frequently.
+
+---
+
+## Troubleshooting
+
+- **“offline + cache miss”**  
+  Seed the cache (see tests) or disable offline mode.
+- **“Schema mismatch”**  
+  Harmonize columns after `get_df` (types, missing keys).
+- **“Too many requests”**  
+  Configure `FF_HTTP_RATE_LIMIT_RPS`; make pagination more efficient (larger `page_size`).
+- **“No http block”**  
+  Was the node **skipped** (fingerprint cache)? Or did the model avoid HTTP calls altogether?
+
+---
+
+## Security & Compliance
+
+- **Do not commit secrets** - use environment variables or a secret manager.
+- **PII/GDPR:** verify whether the API returns personal data; minimise retention.
+- **Cache directory:** keep it in `.gitignore`; encrypt or isolate it if necessary.
+
+---
+
+## FAQ
+
+**Q:** Can I call other libraries (for example `requests`, `httpx`) directly?  
+**A:** Yes, but you lose telemetry and caching. The recommended entrypoint is `fastflowtransform.api.http`.
+
+**Q:** How do I add custom headers (for example OAuth)?  
+**A:** Pass `headers={...}`. Store sensitive values in env vars and inject them into your models.
+
+**Q:** Does this work for POST requests?  
+**A:** Release R1 focuses on GET. Please open an issue for POST/PUT support; the design can be extended.
+
+---
+
+**See also:**
+
+- Technical guide: *Developer Guide – Architecture & Internals*
+- Unit tests: `tests/api/test_http_*.py`
+- Runtime & cache: *Parallelism & Cache (v0.3)*
diff --git a/docs/Config_and_Macros.md b/docs/Config_and_Macros.md
index c470ab6..fcef06d 100644
--- a/docs/Config_and_Macros.md
+++ b/docs/Config_and_Macros.md
@@ -97,12 +97,34 @@ def enrich(df: pd.DataFrame) -> pd.DataFrame:
 
 ```yaml
 # sources.yml
-crm:
-  users:
-    identifier: seed_users
-erp:
-  orders:
-    identifier: seed_orders
+version: 2
+
+sources:
+  - name: crm
+    tables:
+      - name: users
+        identifier: seed_users
+  - name: erp
+    tables:
+      - name: orders
+        identifier: seed_orders
+```
+
+Each source can declare defaults such as `schema`, `database`, or `catalog`. Tables may
+override those defaults, add per-engine overrides, or point at files:
+
+```yaml
+  - name: raw
+    schema: staging
+    tables:
+      - name: seed_users
+        identifier: seed_users
+        overrides:
+          postgres:
+            schema: raw
+          databricks_spark:
+            format: delta
+            location: "/mnt/delta/raw/seed_users"
 ```
 
 ---
diff --git a/docs/Data_Quality_Tests.md b/docs/Data_Quality_Tests.md
new file mode 100644
index 0000000..65082d7
--- /dev/null
+++ b/docs/Data_Quality_Tests.md
@@ -0,0 +1,173 @@
+# Data Quality Test Reference
+
+FastFlowTransform exposes a set of built-in data quality checks that you can configure in `project.yml → tests:` and execute with `fft test`. This document lists every supported test, required parameters, and example configurations.
+
+## Usage Overview
+
+```yaml
+# project.yml
+tests:
+  - type: not_null
+    table: users
+    column: id
+    severity: error          # default (omit for error)
+    tags: [batch]
+
+  - type: unique
+    table: users
+    column: email
+    tags: [batch]
+
+  - type: accepted_values
+    table: users
+    column: status
+    values: [active, invited]
+    severity: warn           # warn keeps run green on failure
+
+  - type: row_count_between
+    table: users_enriched
+    min: 1
+    max: 100000
+
+  - type: reconcile_equal
+    name: revenue_vs_bookings  # optional label in summaries
+    tags: [reconcile]
+    left:  { table: fct_revenue,   expr: "sum(amount)" }
+    right: { table: fct_bookings, expr: "sum(expected_amount)" }
+    abs_tolerance: 5.0
+```
+
+Every entry is a single dictionary describing one check. The common keys are:
+
+| Key        | Description |
+|------------|-------------|
+| `type`     | Test kind (see tables below). |
+| `table`    | Target table for table-level checks or display hint for reconciliations. |
+| `column`   | Required for column-scoped checks (`not_null`, `unique`, …). |
+| `severity` | `error` (default) or `warn`. |
+| `tags`     | Optional list of selectors for `fft test --select tag:...`. |
+| `name`     | Optional identifier surfaced in summaries (useful for reconciliations). |
+
+Run all configured checks:
+
+```bash
+fft test . --env dev
+```
+
+Use `--select tag:<name>` to restrict by tags (legacy `--select batch` reads the same tags list). Tests always execute regardless of cache settings.
+
+Each entry produces a summary line. Failures stop the command unless `severity: warn` is set.
+
+## Table-Level Checks
+
+These checks operate on a single table (optionally filtered with `where:`). Unless noted, they require a `column` argument.
+
+### `not_null`
+- **Purpose:** Assert that a column never contains NULLs.
+- **Parameters:**
+  - `column` *(str, required)*
+  - `where` *(str, optional)* — SQL predicate applied before the NULL check.
+- **Failure:** Reports the number of NULL rows and shows the underlying SQL.
+
+### `unique`
+- **Purpose:** Detect duplicates within a column.
+- **Parameters:**
+  - `column` *(str, required)*
+  - `where` *(str, optional)*
+- **Failure:** Indicates how many duplicate groups were found (HAVING count > 1) and shows a sample query.
+
+### `accepted_values`
+- **Purpose:** Ensure every non-NULL value is inside an allowed set.
+- **Parameters:**
+  - `column` *(str, required)*
+  - `values` *(list, required)* — permitted literals (strings are quoted automatically).
+  - `where` *(str, optional)*
+- **Failure:** Shows the number of out-of-set values plus up to five sample values.
+
+### `greater_equal`
+- **Purpose:** Require all values to be greater than or equal to a threshold.
+- **Parameters:**
+  - `column` *(str, required)*
+  - `threshold` *(number, default `0`)*
+- **Failure:** Lists how many rows fell below the threshold.
+
+### `non_negative_sum`
+- **Purpose:** Validate that the sum of a numeric column is not negative.
+- **Parameters:**
+  - `column` *(str, required)*
+- **Failure:** Reports the signed sum when it is negative.
+
+### `row_count_between`
+- **Purpose:** Guard minimum (and optional maximum) row counts for a table.
+- **Parameters:**
+  - `min` *(int, default `1`)*
+  - `max` *(int, optional)* — omit for open-ended upper bounds.
+- **Failure:** Indicates the observed row count when it falls outside `[min, max]`.
+
+### `freshness`
+- **Purpose:** Warn when the latest timestamp is older than an allowed delay.
+- **Parameters:**
+  - `column` *(str, required)* — timestamp column.
+  - `max_delay_minutes` *(int, required)* — permitted staleness.
+- **Failure:** Reports the computed lag in minutes. Uses ANSI-style `DATE_PART` (works on DuckDB/Postgres; extend for other engines as needed).
+
+## Cross-Table Reconciliations
+
+Reconciliation checks compare aggregates or keys across two relations. Their configuration accepts dictionaries describing the left/right side expressions or keys.
+
+### `reconcile_equal`
+- **Purpose:** Compare two scalar expressions with optional tolerances.
+- **Parameters:**
+  - `left`, `right` *(dict, required)* with keys:
+    - `table` *(str, required)*
+    - `expr` *(str, required)* — SQL select expression (e.g. `sum(amount)`).
+    - `where` *(str, optional)*
+  - `abs_tolerance` *(float, optional)* — maximum absolute difference.
+  - `rel_tolerance_pct` *(float, optional)* — maximum relative difference in percent.
+- **Failure:** Displays both values, absolute and relative differences.
+
+### `reconcile_ratio_within`
+- **Purpose:** Constrain the ratio `left/right` within bounds.
+- **Parameters:**
+  - `left`, `right` *(dict, required as above)*
+  - `min_ratio`, `max_ratio` *(float, required)*
+- **Failure:** Shows the computed ratio and expected interval.
+
+### `reconcile_diff_within`
+- **Purpose:** Limit the absolute difference between two aggregates.
+- **Parameters:**
+  - `left`, `right` *(dict, required)*
+  - `max_abs_diff` *(float, required)*
+- **Failure:** Reports the absolute difference when it exceeds `max_abs_diff`.
+
+### `reconcile_coverage`
+- **Purpose:** Ensure every key present in a source table appears in a target table (anti-join zero).
+- **Parameters:**
+  - `source` *(dict, required)* — `table` and `key` column.
+  - `target` *(dict, required)* — `table` and `key` column.
+  - `source_where` *(str, optional)* — filter applied to the source.
+  - `target_where` *(str, optional)* — filter applied to the target.
+- **Failure:** Reports the number of missing keys.
+
+## Severity & Selectors
+
+- `severity: error` (default) makes failures stop the test run with exit code 1.
+- `severity: warn` records the result but keeps the run successful.
+- `selectors:` lets you group checks under named tokens (e.g. `batch`, `streaming`). Use `fft test --select tag:batch` to execute a subset.
+
+## CLI Summary Output
+
+Each executed check produces a line in the summary:
+
+```
+✓ not_null          users.email                     (3ms)
+✖ accepted_values   events.status    values=['new', 'active']   (warn)
+```
+
+Failures include the generated SQL (where available) to simplify debugging. Use `fft test --verbose` for more detail, or `FFT_SQL_DEBUG=1` to log the underlying queries.
+
+## Further Reading
+
+- [`docs/YAML_Tests.md`](YAML_Tests.md) – schema for YAML-defined tests and advanced scenarios.
+- [`fastflowtransform/testing.py`](../src/fastflowtransform/testing.py) – implementation details and helper functions.
+- [`fft test --help`] — command-line switches, selectors, and cache options.
diff --git a/docs/Incremental.md b/docs/Incremental.md
new file mode 100644
index 0000000..527f25b
--- /dev/null
+++ b/docs/Incremental.md
@@ -0,0 +1,66 @@
+# Incremental Models (R1)
+
+This guide explains how to configure incremental models, use `is_incremental()` in SQL, engine compatibility, and schema change policies.
+
+## Quick Start
+
+A minimal incremental model:
+
+```sql
+-- examples/r1_demo/models/fct_events_inc.ff.sql
+{{ config(
+  materialized='incremental',
+  unique_key=['event_id'],
+  on_schema_change='append_new_columns'  -- or 'sync_all_columns'
+) }}
+with src as (
+  select * from {{ source('app', 'events') }}
+  {% if is_incremental() %}
+    where ingested_at > (select coalesce(max(ingested_at), timestamp '1970-01-01') from {{ this.name }})
+  {% endif %}
+)
+select
+  event_id,
+  user_id,
+  event_type,
+  ingested_at,
+  -- evolving column: will appear later
+  meta_json
+from src;
+````
+
+### `is_incremental()`
+
+* Available in SQL templates during rendering.
+* Returns `true` when the model exists and the current `materialized='incremental'` run chooses an incremental path (insert/merge) instead of full rebuild.
+* Typical usage: filter the source to “new” rows only.
+
+### Engine Matrix (MVP)
+
+| Engine             | Incremental Insert | Merge/Upsert | Schema Change Policy |
+| ------------------ | ------------------ | ------------ | -------------------- |
+| DuckDB             | ✅ insert           | 🚧 fallback* | ✅ append new cols    |
+| Postgres           | ✅ insert           | 🚧 fallback* | ✅ append new cols    |
+| BigQuery (classic) | ✅ insert           | 🚧 fallback* | 🚧 best-effort       |
+| BigQuery BigFrames | ✅ insert           | 🚧 fallback* | 🚧 best-effort       |
+| Databricks Spark   | ✅ insert           | 🚧 fallback* | 🚧 best-effort       |
+| Snowflake Snowpark | ✅ insert           | 🚧 fallback* | 🚧 best-effort       |
+
+* Fallback strategy merges by delete-on-keys + insert (best effort) if native merge isn’t wired.
+
+### Schema Change Policies
+
+* `append_new_columns` (default): new columns appear in target if they show up in the select.
+* `sync_all_columns` (planned): attempt to keep type/nullable alignment. Currently not enforced; prefer append in R1.
+
+### End-to-End
+
+```bash
+# Seeds → initial incremental build → run again with filter
+fft seed examples/r1_demo --env dev
+fft run  examples/r1_demo --env dev --select fct_events_inc.ff
+# simulate new data (re-seed or append), then:
+fft run  examples/r1_demo --env dev --select fct_events_inc.ff
+```
+
+**Artifacts:** see `.fastflowtransform/target/{manifest.json, run_results.json, catalog.json}`.
diff --git a/docs/Quickstart.md b/docs/Quickstart.md
new file mode 100644
index 0000000..1c20f12
--- /dev/null
+++ b/docs/Quickstart.md
@@ -0,0 +1,74 @@
+# Quickstart
+
+This guide walks you through creating a minimal FastFlowTransform project from scratch and running it end-to-end.
+
+## 1. Install & bootstrap
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ./fastflowtransform
+fft --help
+```
+
+## 2. Create project layout
+
+```bash
+mkdir -p demo/{models,seeds}
+cat <<'YAML' > demo/sources.yml
+version: 2
+
+sources:
+  - name: raw
+    schema: staging
+    tables:
+      - name: users
+        identifier: seed_users
+YAML
+
+cat <<'CSV' > demo/seeds/seed_users.csv
+id,email
+1,a@example.com
+2,b@example.com
+CSV
+
+cat <<'SQL' > demo/models/users.ff.sql
+{{ config(materialized='table') }}
+select id, email
+from {{ source('raw', 'users') }}
+SQL
+```
+
+## 3. Seed static inputs
+
+```bash
+fft seed demo --profile dev
+```
+
+This materializes the CSV into the configured engine (DuckDB by default) using `seed_users` as the physical table.
+
+## 4. Run the pipeline
+
+```bash
+fft run demo --cache off
+```
+
+You should see log lines similar to `✓ L01 [DUCK] users.ff`. The resulting table lives in the target schema (`staging` in this example).
+
+## 5. Inspect artifacts
+
+- `.fastflowtransform/target/manifest.json` → model graph + sources
+- `.fastflowtransform/target/run_results.json` → run outcomes and durations
+
+## 6. Add more models (optional)
+
+- Reference other models with `{{ ref('model_name') }}`
+- Configure tags or materializations via `{{ config(...) }}` at the top of each SQL file
+
+## 7. Next steps
+
+- Add `project.yml` for reusable `vars:` and metadata
+- Explore `fft docs` to generate HTML documentation
+- Use engine profiles under `profiles.yml` to target Postgres, BigQuery, or Databricks (path-based sources supported via `format` + `location` overrides)
+
+Refer to `docs/Config_and_Macros.md` for advanced configuration options.
diff --git a/docs/State_Selection.md b/docs/State_Selection.md
new file mode 100644
index 0000000..e9590dd
--- /dev/null
+++ b/docs/State_Selection.md
@@ -0,0 +1,39 @@
+
+# State Selection — R1
+
+Build only changed nodes or select by last run results.
+
+## Changed Nodes
+
+- `state:modified` — models that have changed since last cached fingerprint.
+- `state:modified+` — the above plus all downstream dependents.
+
+```bash
+# First run populates cache
+fft run examples/r1_demo --env dev --cache rw
+# Touch files / change SQL → next run:
+fft run examples/r1_demo --env dev --cache rw --select state:modified
+fft run examples/r1_demo --env dev --cache rw --select state:modified+
+````
+
+## Result-based Selection
+
+Use the last `run_results.json`:
+
+* `result:ok`   — successful models (no warnings)
+* `result:warn` — successful but with warnings
+* `result:fail` — alias of `result:error`
+* `result:error`— failed models
+
+```bash
+fft run examples/r1_demo --env dev --select result:error
+```
+
+### Artifacts
+
+```
+examples/r1_demo/.fastflowtransform/target/
+├── manifest.json
+├── run_results.json
+└── catalog.json
+```
\ No newline at end of file
diff --git a/docs/Technical_Overview.md b/docs/Technical_Overview.md
index b4a472e..4206508 100644
--- a/docs/Technical_Overview.md
+++ b/docs/Technical_Overview.md
@@ -1,4 +1,4 @@
-# 🧭 FastFlowTransform – Technical Developer Documentation (v0.1)
+# 🧭 FastFlowTransform – Technical Developer Documentation (v0.4)
 
 > Status: latest updates from your context dump. This document consolidates project structure, architecture, core APIs, error handling, CLI, examples, and roadmap into a print/git-friendly Markdown.
 >
@@ -172,11 +172,31 @@ Targets wrap the CLI commands showcased below. Feel free to copy the pattern int
 
 ### CLI Flows
 
-> 📚 **Mehr lesen … Quickstart & Rezepte**
-> Die Schritt-für-Schritt-Befehle findest du im [`README.md`](../README.md#quickstart). Dort bleibt der vollständige Ablauf gepflegt; dieser Abschnitt fokussiert auf weiterführende Hinweise.
+> 📚 **Need recipes?** The step-by-step walkthrough lives in [`README.md`](../README.md#quickstart); this section highlights additional guidance.
 
-- CLI-Flags und interne Abläufe sind im Abschnitt [CLI Implementation](#cli-implementation) dokumentiert.
-- Beispiele für Automatisierung findest du in den [Makefile Targets](#makefile-targets).
+- CLI flags and internals are documented under [CLI Implementation](#cli-implementation).
+- Automation examples appear in the [Makefile Targets](#makefile-targets).
+
+
+#### HTTP/API in Python models
+See [API calls in Python models](./API_Models.md) for `get_json`/`get_df`, pagination, cache/offline flags.
+
+
+#### DAG & Documentation
+
+- Narrow the graph with `fft dag ... --select <pattern>` (for example `state:modified` or `tag:finance`). Combined with `--html` this produces a focused mini site.
+- Control schema introspection via `--with-schema/--no-schema`. Use `--no-schema` when the executor should avoid fetching column metadata (for example, BigQuery without sufficient permissions).
+- `fft docgen` renders the DAG, model pages, and an optional JSON manifest in one command. Append `--open-source` to open `index.html` in your default browser after rendering.
+
+#### Sync Database Comments
+
+`fft sync-db-comments <project> --env <env>` pushes model and column descriptions from project YAML or Markdown into database comments. The command currently supports Postgres and Snowflake Snowpark:
+
+- Start with `--dry-run` to review the generated `COMMENT` statements.
+- Postgres honors `profiles.yml -> postgres.db_schema` (and any `FF_PG_SCHEMA` override).
+- Snowflake reuses the session or connection exposed by the executor.
+
+If no descriptions are found, the command exits without making changes.
 
 ### Logging & Verbosity
 
@@ -238,6 +258,7 @@ fft run . -vv    # full debug + SQL channel
 Notes:
 - UTests key the cache with `profile="utest"`.
 - Fingerprints include case inputs (CSV content hash / inline rows), so changing inputs invalidates the cache.
+- `--reuse-meta` is currently a reserved flag: it is exposed in the CLI, acts as a no-op today, and will enable future meta-table optimizations.
 
 
 #### Why?
@@ -660,6 +681,8 @@ fft dag . --env dev --html
 fft docgen . --env dev --out site/docs --emit-json site/docs/docs_manifest.json
 ```
 
+Add `--open-source` if you want the default browser to open the rendered `index.html` immediately.
+
 **Descriptions** can be provided in YAML (project.yml) and/or Markdown files. Markdown has higher priority.
 
 YAML in `project.yml`:
@@ -908,9 +931,12 @@ Operational usage lives in [CLI Flows](#cli-flows). This section drills into the
 **Commands:**
 
 - `fft run <project> [--env dev] [--engine ...]`
-- `fft dag <project> [--env dev] [--html]`
-- `fft test <project> [--env dev] [--select batch|streaming]`
+- `fft dag <project> [--env dev] [--html] [--select ...] [--with-schema/--no-schema]`
+- `fft docgen <project> [--env dev] [--out dir] [--emit-json path] [--open-source]`
+- `fft test <project> [--env dev] [--select batch|streaming|tag:...]`
 - `fft seed <project> [--env dev]`
+- `fft sync-db-comments <project> [--env dev] [--dry-run]`
+- `fft utest <project> [--env dev] [--cache off|ro|rw] [--reuse-meta]`
 - `fft --version`
 
 **Key components:**
diff --git a/docs/YAML_Tests.md b/docs/YAML_Tests.md
new file mode 100644
index 0000000..a97f3a4
--- /dev/null
+++ b/docs/YAML_Tests.md
@@ -0,0 +1,54 @@
+# YAML Tests (Schema-bound)
+
+Schema-bound tests live in `models/*.yml` or `models/**/schema.yml` and complement (or replace) `project.yml`-based tests.
+
+## Example
+
+```yaml
+# examples/r1_demo/models/users_enriched.yml
+version: 2
+models:
+  - name: users_enriched
+    description: "Adds gmail flag"
+    columns:
+      - name: id
+        tests:
+          - not_null: { severity: error }
+          - unique
+      - name: email
+        tests:
+          - not_null
+          - accepted_values:
+              values: ["a@example.com","b@example.com","c@gmail.com"]
+              severity: warn
+````
+
+### Severities
+
+* `error` → contributes to failures (exit code 2).
+* `warn` → surfaced in summary as ❕, does not affect exit code.
+
+### Run
+
+```bash
+fft test examples/r1_demo --env dev
+# Select only tests tagged 'reconcile' (if present)
+fft test examples/r1_demo --env dev --select tag:reconcile
+```
+
+### Output (excerpt)
+
+```
+Data Quality Summary
+────────────────────
+✅ not_null           users.id                               (3ms)
+❌ unique             users.id                               (2ms)
+   ↳ [unique] users.id: found 1 duplicate
+❕ accepted_values     users_enriched.email                   (1ms)
+
+Totals
+──────
+✓ passed: 2
+✗ failed: 1
+! warnings: 1
+```
\ No newline at end of file
diff --git a/docs/examples/Environment_Matrix.md b/docs/examples/Environment_Matrix.md
new file mode 100644
index 0000000..57b5132
--- /dev/null
+++ b/docs/examples/Environment_Matrix.md
@@ -0,0 +1,228 @@
+# Environment Matrix (DuckDB-only) — Example
+
+This tiny project demonstrates **per-environment configuration** (dev / stg / prod) while keeping everything on **DuckDB**.
+Each environment uses its **own DuckDB file**, so you can switch environments without changing code.
+
+It also includes a **seed step** (CSV → table) and two minimal models:
+
+* `env_vars.ff` (Python) — echoes which env is active and which DuckDB file is used
+* `hello.ff` (SQL view) — shows how `{{ this.* }}` resolves from the active profile
+* `users.ff` (SQL table) — reads from the seeded CSV table to prove seeding works
+
+---
+
+## What this shows
+
+* Layered environment files: `.env.dev`, `.env.stg`, `.env.prod` (+ optional `*.local` overrides)
+* `profiles.yml` that reads from `env('…')` so connection details live in env files
+* All environments use **DuckDB**, but **different DB files** (e.g. `.local/dev.duckdb`, `.local/stg.duckdb`, …)
+* Seeding CSV → `seed_users` table, then a simple model consuming it
+
+---
+
+## Project layout
+
+```
+examples/env_matrix/
+├─ models/
+│  ├─ env_vars.ff.py          # Python model: shows env + DuckDB file info
+│  └─ users.ff.sql            # SQL table: reads from seeded 'seed_users'
+├─ seeds/
+│  └─ users.csv               # sample data for seeding (-> seed_users)
+├─ profiles.yml               # all envs = DuckDB, different paths
+├─ .env                       # shared defaults (optional)
+├─ .env.dev                   # dev environment vars
+├─ .env.stg                   # stg environment vars
+├─ .env.prod                  # prod environment vars
+├─ .env.dev.local             # private overrides (gitignored; optional)
+├─ .env.stg.local             # private overrides (gitignored; optional)
+├─ .env.prod.local            # private overrides (gitignored; optional)
+└─ Makefile                   # convenience targets (run, seed, dag)
+```
+
+---
+
+## Environment files
+
+Each env file sets a different DuckDB path:
+
+* `.env.dev`
+
+  ```
+  FFT_ACTIVE_ENV=dev
+  FF_ENGINE=duckdb
+  FF_DUCKDB_PATH=.local/env_matrix.dev.duckdb
+  ```
+
+* `.env.stg`
+
+  ```
+  FFT_ACTIVE_ENV=stg
+  FF_ENGINE=duckdb
+  FF_DUCKDB_PATH=.local/env_matrix.stg.duckdb
+  ```
+
+* `.env.prod`
+
+  ```
+  FFT_ACTIVE_ENV=prod
+  FF_ENGINE=duckdb
+  FF_DUCKDB_PATH=.local/env_matrix.prod.duckdb
+  ```
+
+> You can place secrets or machine-local tweaks in `.env.<env>.local` (ignored by git).
+> Optional toggles (if you want verbose SQL logs):
+> `FFT_SQL_DEBUG=1`, `FFT_LOG_JSON=1`
+
+---
+
+## `profiles.yml` (DuckDB for all envs)
+
+```yaml
+default:
+  dev:
+    engine: "{{ env('FF_ENGINE', 'duckdb') }}"
+    duckdb:
+      path: "{{ env('FF_DUCKDB_PATH', ':memory:') }}"
+
+  stg:
+    engine: "{{ env('FF_ENGINE', 'duckdb') }}"
+    duckdb:
+      path: "{{ env('FF_DUCKDB_PATH', ':memory:') }}"
+
+  prod:
+    engine: "{{ env('FF_ENGINE', 'duckdb') }}"
+    duckdb:
+      path: "{{ env('FF_DUCKDB_PATH', ':memory:') }}"
+```
+
+---
+
+## Models
+
+### `models/env_vars.ff.py` (Python)
+
+Returns one row with:
+
+* `active_env_hint` (from `.env.*`),
+* `ff_engine` (should be `duckdb` here),
+* `duckdb_path`, `duckdb_exists`, `duckdb_size_bytes`.
+
+### `models/hello.ff.sql` (SQL view)
+
+Uses `{{ this.materialized }}`, `{{ this.schema }}`, `{{ this.database }}` so you can see what the active profile provides. (The simple `SELECT` is compatible with DuckDB; if you added casts like `::text`, they’re fine in DuckDB too.)
+
+### `models/users.ff.sql` (SQL table)
+
+Reads from the seeded table `seed_users`:
+
+```sql
+{{ config(materialized='table', tags=['demo', 'seed']) }}
+
+select
+  id,
+  email
+from "seed_users";
+```
+
+> If you see an error “table seed_users does not exist”, you **haven’t run `fft seed`** for that environment yet.
+
+---
+
+## Seeds
+
+`seeds/users.csv` is loaded by `fft seed` into a table named `seed_users`.
+(That’s the default naming convention: `users.csv` → `seed_users`.)
+
+---
+
+## Running it
+
+From the repo root:
+
+### Using `uv` directly
+
+**Dev**
+
+```bash
+uv run fft seed examples/env_matrix --env dev
+uv run fft run  examples/env_matrix --env dev
+uv run fft dag  examples/env_matrix --env dev --html
+```
+
+**Staging**
+
+```bash
+uv run fft seed examples/env_matrix --env stg
+uv run fft run  examples/env_matrix --env stg
+```
+
+**Prod**
+
+```bash
+uv run fft seed examples/env_matrix --env prod
+uv run fft run  examples/env_matrix --env prod
+```
+
+### Using the Makefile (inside `examples/env_matrix/`)
+
+```bash
+make run-dev     # runs the DAG on dev
+make run-stg
+make run-prod
+
+make seed-dev    # seed only (dev)
+make seed-stg
+make seed-prod
+
+make dag-dev     # generate HTML DAG for dev
+make clean       # remove .local/, docs/, site/, .fastflowtransform/
+```
+
+> Tip: re-run `fft seed` whenever you switch environments or change `seeds/*.csv`.
+
+---
+
+## Inspecting results
+
+* The **HTML DAG** (after `make dag-dev`) will be at:
+
+  ```
+  examples/env_matrix/site/dag/index.html
+  ```
+* The **artifacts** are under:
+
+  ```
+  examples/env_matrix/.fastflowtransform/target/{manifest.json, run_results.json, catalog.json}
+  ```
+* Query the DuckDB files directly with `duckdb` CLI or `python` + `duckdb` module if you want to peek inside.
+
+---
+
+## Troubleshooting
+
+* **`seed_users` not found**
+  Run `fft seed` for the same environment:
+  `uv run fft seed examples/env_matrix --env dev`
+
+* **No logs showing**
+  Use `-v`/`-vv` and/or `--sql-debug` on the CLI, or set:
+
+  ```
+  FFT_SQL_DEBUG=1
+  FFT_LOG_JSON=1  # optional JSON logs
+  ```
+
+* **Wrong environment picked**
+  Double-check the `--env` flag in your CLI call and ensure the `.env.<env>` file exists.
+
+---
+
+## Clean up
+
+```bash
+make clean              # from examples/env_matrix/
+# or manually:
+rm -rf examples/env_matrix/.local examples/env_matrix/site examples/env_matrix/docs
+rm -rf examples/env_matrix/.fastflowtransform
+```
diff --git a/docs/index.md b/docs/index.md
index e1a678a..735f88c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,13 +5,18 @@ Welcome! This page is your starting point for FastFlowTransform docs. Pick the t
 ---
 
 ## Docs Navigation
-1. **Getting Started** — you are here (`docs/index.md`)
-2. [User Guide](./Technical_Overview.md#part-i--operational-guide)
-3. [Modeling Reference](./Config_and_Macros.md)
-4. [Parallelism & Cache](./Cache_and_Parallelism.md)
-5. [Cross-Table Reconciliations](./Technical_Overview.md#cross-table-reconciliations)
-6. [Auto-Docs & Lineage](./Technical_Overview.md#auto-docs--lineage)
-7. [Developer Guide](./Technical_Overview.md#part-ii--architecture--internals)
+- **Getting Started** — you are here (`docs/index.md`)
+- [User Guide](./Technical_Overview.md#part-i--operational-guide)
+- [Modeling Reference](./Config_and_Macros.md)
+- [Parallelism & Cache](./Cache_and_Parallelism.md)
+- [API calls in Python models](./API_Models.md)
+- [Incremental Models](./Incremental.md)
+- [YAML Tests (Schema-bound)](./YAML_Tests.md)
+- [Data Quality Tests Reference](./Data_Quality_Tests.md)
+- [State Selection (changed & results)](./State_Selection.md)
+- [Cross-Table Reconciliations](./Technical_Overview.md#cross-table-reconciliations)
+- [Auto-Docs & Lineage](./Technical_Overview.md#auto-docs--lineage)
+- [Developer Guide](./Technical_Overview.md#part-ii--architecture--internals)
 
 ## Table of Contents
 
@@ -26,7 +31,7 @@ Welcome! This page is your starting point for FastFlowTransform docs. Pick the t
 
 ### 1. Build & Operate Projects (Data Practitioners)
 
-- **Get set up quickly:** run the DuckDB demo or install locally via the [Quickstart](../README.md#quickstart).
+- **Get set up quickly:** follow the dedicated [Quickstart](Quickstart.md) guide for installation, seeding, and a first run.
 - **Understand the project layout & CLI workflow:** see *Project Layout*, *Makefile Targets*, and *CLI Flows* in the [Technical Overview](Technical_Overview.md#project-layout).
 - **Configure runtimes & profiles:** review executor profiles, environment overrides, and logging options in the [Technical Overview](Technical_Overview.md#profiles--environment-overrides).
 - **Model data quality & troubleshoot runs:** the [Technical Overview](Technical_Overview.md#model-unit-tests-fastflowtransform-utest) covers unit tests, troubleshooting tips, and exit codes.
diff --git a/examples/api_demo/Makefile b/examples/api_demo/Makefile
new file mode 100644
index 0000000..f4e0d63
--- /dev/null
+++ b/examples/api_demo/Makefile
@@ -0,0 +1,164 @@
+.PHONY: demo seed run dag test artifacts incr state-mod state-mod-plus res-error res-warn \
+        clean demo-open \
+        api-run api-offline api-warm api-cache-clear api-show-http api-demo
+
+# --- Config -------------------------------------------------------------------
+
+# DuckDB database file and project path (for the API demo typically examples/api_demo)
+DB ?= .local/demo.duckdb
+PROJECT ?= .
+UV ?= uv
+
+# HTTP wrapper defaults (override per call if needed)
+# Allowed domains are comma-separated (no https://)
+FF_HTTP_ALLOWED_DOMAINS ?= jsonplaceholder.typicode.com,api.github.com
+FF_HTTP_CACHE_DIR ?= .local/http-cache
+FF_HTTP_MAX_RPS ?= 5
+FF_HTTP_MAX_RETRIES ?= 3
+FF_HTTP_TIMEOUT ?= 20
+
+# Detect OS opener (macOS: open, Linux: xdg-open)
+UNAME_S := $(shell uname -s)
+ifeq ($(UNAME_S),Darwin)
+	OPENER := open
+else
+	OPENER := xdg-open
+endif
+
+# --- Shared env for all runs (DuckDB + HTTP) ---------------------------------
+RUN_ENV = FF_ENGINE=duckdb FF_DUCKDB_PATH="$(DB)" \
+          FF_HTTP_ALLOWED_DOMAINS="$(FF_HTTP_ALLOWED_DOMAINS)" \
+          FF_HTTP_CACHE_DIR="$(FF_HTTP_CACHE_DIR)" \
+          FF_HTTP_MAX_RPS="$(FF_HTTP_MAX_RPS)" \
+          FF_HTTP_MAX_RETRIES="$(FF_HTTP_MAX_RETRIES)" \
+          FF_HTTP_TIMEOUT="$(FF_HTTP_TIMEOUT)"
+
+# Engine env
+ifeq ($(ENGINE),duckdb)
+  ENGINE_ENV = FF_ENGINE=duckdb FF_DUCKDB_PATH="$(DB)"
+  ENGINE_TAG = engine:duckdb
+endif
+ifeq ($(ENGINE),postgres)
+  ENGINE_ENV = FF_ENGINE=postgres FF_PG_DSN="$(FF_PG_DSN)" FF_PG_SCHEMA="$(FF_PG_SCHEMA)"
+  ENGINE_TAG = engine:postgres
+endif
+ifeq ($(ENGINE),databricks_spark)
+  ENGINE_ENV = FF_ENGINE=databricks_spark FF_SPARK_MASTER="$(FF_SPARK_MASTER)"
+  ENGINE_TAG = engine:databricks_spark
+endif
+
+# Select only common + this engine; keeps DAG clean and avoids executing foreign variants
+SELECT = tag:example:api_demo,tag:scope:common,tag:$(ENGINE_TAG)
+
+# --- Standard R1 targets ------------------------------------------------------
+
+seed:
+	$(ENGINE_ENV) $(UV) run fft seed "$(PROJECT)" --env dev
+
+run:
+	$(ENGINE_ENV) $(RUN_ENV) $(UV) run fft run "$(PROJECT)" --env dev
+
+test:
+	$(ENGINE_ENV) $(UV) run fft test "$(PROJECT)" --env dev
+
+dag:
+	$(ENGINE_ENV) $(UV) run fft dag  "$(PROJECT)" --env dev --html
+
+artifacts:
+	@echo
+	@echo "== 📦 Artifacts =="
+	@echo "  $(PROJECT)/.fastflowtransform/target/{manifest.json,run_results.json,catalog.json}"
+	@echo "  DAG HTML: $(PROJECT)/site/dag/index.html"
+
+incr:
+	$(RUN_ENV) $(UV) run fft run "$(PROJECT)" --env dev --select fct_events_inc.ff --cache rw || true
+
+state-mod:
+	@if [ -f "$(PROJECT)/models/users.ff.sql" ]; then touch "$(PROJECT)/models/users.ff.sql"; fi
+	$(RUN_ENV) $(UV) run fft run "$(PROJECT)" --env dev --cache rw --select state:modified
+
+state-mod-plus:
+	$(RUN_ENV) $(UV) run fft run "$(PROJECT)" --env dev --cache rw --select state:modified+
+
+res-error:
+	$(RUN_ENV) $(UV) run fft run "$(PROJECT)" --env dev --select result:error || true
+
+res-warn:
+	$(RUN_ENV) $(UV) run fft run "$(PROJECT)" --env dev --select result:warn  || true
+
+pg-seed:
+	FF_ENGINE=postgres FF_PG_DSN="$(FF_PG_DSN)" FF_PG_SCHEMA="$(FF_PG_SCHEMA)" $(UV) run fft seed "$(PROJECT)" --env stg
+
+pg-run:
+	FF_ENGINE=postgres FF_PG_DSN="$(FF_PG_DSN)" FF_PG_SCHEMA="$(FF_PG_SCHEMA)" \
+	FF_HTTP_ALLOWED_DOMAINS="$(FF_HTTP_ALLOWED_DOMAINS)" \
+	FF_HTTP_CACHE_DIR="$(FF_HTTP_CACHE_DIR)" \
+	FF_HTTP_MAX_RPS="$(FF_HTTP_MAX_RPS)" \
+	FF_HTTP_MAX_RETRIES="$(FF_HTTP_MAX_RETRIES)" \
+	FF_HTTP_TIMEOUT="$(FF_HTTP_TIMEOUT)" \
+	$(UV) run fft run  "$(PROJECT)" --env stg
+
+clean:
+	rm -rf .local "$(PROJECT)/docs" dist build *.egg-info .fastflowtransform
+
+demo-open:
+	@if [ -f "$(PROJECT)/site/dag/index.html" ]; then \
+		$(OPENER) "$(PROJECT)/site/dag/index.html" 2>/dev/null || echo "Open manually at: $(PROJECT)/site/dag/index.html"; \
+	else \
+		echo "No HTML found: $(PROJECT)/site/dag/index.html"; \
+	fi
+
+demo: clean
+	@echo "== 🚀 R1 Demo (DuckDB) =="
+	@echo "DB=$(DB)  PROJECT=$(PROJECT)"
+	+$(MAKE) seed
+	+$(MAKE) run
+	+$(MAKE) dag
+	+$(MAKE) test
+	+$(MAKE) artifacts
+	@echo
+	@echo "== 🔁 Incremental Model =="
+	+$(MAKE) incr
+	@echo
+	@echo "== 🧠 State Selection (changed only) =="
+	+$(MAKE) state-mod
+	+$(MAKE) state-mod-plus
+	@echo
+	@echo "== 🧪 Result Selection (from last run_results.json) =="
+	+$(MAKE) res-error
+	+$(MAKE) res-warn
+	@echo
+	@echo "✅ Demo done. Open DAG here: $(PROJECT)/site/dag/index.html"
+	+$(MAKE) demo-open
+
+# --- API-specific convenience targets ----------------------------------------
+
+api-run:
+	$(RUN_ENV) $(UV) run fft run "$(PROJECT)" --env dev --select "kind:python" --cache rw
+
+api-warm:
+	+$(MAKE) api-run
+
+api-offline:
+	$(RUN_ENV) FF_HTTP_OFFLINE=1 $(UV) run fft run "$(PROJECT)" --env dev --select "kind:python" --cache rw
+
+api-cache-clear:
+	rm -rf "$(FF_HTTP_CACHE_DIR)"
+
+api-show-http:
+	@if command -v jq >/dev/null 2>&1; then \
+	  echo "== HTTP snapshots from run_results.json =="; \
+	  jq -r '.results[] | select(.http!=null) | "\(.name): requests=\(.http.requests) cache_hits=\(.http.cache_hits) bytes=\(.http.bytes) offline=\(.http.used_offline)"' \
+	    "$(PROJECT)/.fastflowtransform/target/run_results.json" || true; \
+	else \
+	  echo "Install 'jq' to pretty-print HTTP snapshots from run_results.json."; \
+	fi
+
+api-demo: clean
+	@echo "== 🌐 API Demo (DuckDB) =="
+	@echo "DB=$(DB)  PROJECT=$(PROJECT)"
+	+$(MAKE) run
+	+$(MAKE) dag
+	+$(MAKE) api-show-http || true
+	@echo "✅ API Demo done. Open DAG here: $(PROJECT)/site/dag/index.html"
+	+$(MAKE) demo-open
diff --git a/examples/api_demo/models/common/mart_users_join.ff.sql b/examples/api_demo/models/common/mart_users_join.ff.sql
new file mode 100644
index 0000000..9ee550c
--- /dev/null
+++ b/examples/api_demo/models/common/mart_users_join.ff.sql
@@ -0,0 +1,23 @@
+{{ config(materialized='table', tags=['example:api_demo','scope:common']) }}
+
+{# Choose the producing model by variable. Default is the pandas HTTP version. #}
+{% set api_users_model = var('api_users_model', 'api_users_http') %}
+
+-- Join local seed users with API users by email (demo-only; real keys will differ)
+with a as (
+  select u.id as user_id, u.email
+  from {{ ref('users.ff') }} u
+),
+b as (
+  -- Choose one of the API models:
+  -- select * from {{ ref('api_users_http') }}
+  select * from {{ ref('api_users_requests') }}
+)
+select
+  a.user_id,
+  a.email,
+  b.api_user_id,
+  b.username,
+  b.name
+from a
+left join b on lower(a.email) = lower(b.email);
diff --git a/examples/api_demo/models/common/users.ff.sql b/examples/api_demo/models/common/users.ff.sql
new file mode 100644
index 0000000..639ce2d
--- /dev/null
+++ b/examples/api_demo/models/common/users.ff.sql
@@ -0,0 +1,4 @@
+{{ config(materialized='table', tags=['example:api_demo','scope:common','kind:seed-consumer']) }}
+-- Simple staging table from seed
+select id, email
+from {{ source('crm', 'users') }};
diff --git a/examples/api_demo/models/engines/duckdb/api_users_http.ff.py b/examples/api_demo/models/engines/duckdb/api_users_http.ff.py
new file mode 100644
index 0000000..e75d7bc
--- /dev/null
+++ b/examples/api_demo/models/engines/duckdb/api_users_http.ff.py
@@ -0,0 +1,25 @@
+from fastflowtransform import model
+from fastflowtransform.api.http import get_df
+import pandas as pd
+
+
+@model(
+    name="api_users_http",
+    deps=["users.ff"],  # at least one dependency is required by the executor contract
+)
+def fetch(_: pd.DataFrame) -> pd.DataFrame:
+    """
+    Fetch users from a public demo API using the built-in HTTP wrapper.
+    Pros: caching, offline mode, telemetry in run_results.json.
+    """
+    # Example endpoint (JSON Placeholder); replace with your real API.
+    # For paginated APIs you can add a `paginator` function.
+    df = get_df(
+        url="https://jsonplaceholder.typicode.com/users",
+        record_path=None,  # the outer JSON is already a list
+        normalize=True,  # flatten objects to columns (address.*, company.*)
+    )
+
+    # Keep only a few columns to make joins simpler
+    cols = [c for c in df.columns if c in ("id", "email", "username", "name")]
+    return df[cols].rename(columns={"id": "api_user_id"})
diff --git a/examples/api_demo/models/engines/duckdb/api_users_requests.ff.py b/examples/api_demo/models/engines/duckdb/api_users_requests.ff.py
new file mode 100644
index 0000000..d1b731f
--- /dev/null
+++ b/examples/api_demo/models/engines/duckdb/api_users_requests.ff.py
@@ -0,0 +1,33 @@
+# NOTE: Plain Python variant (requests/httpx). No built-in FFT telemetry or HTTP cache here.
+from fastflowtransform import model
+import pandas as pd
+
+try:
+    import requests  # you can swap this with httpx if you prefer
+except Exception as _e:  # pragma: no cover
+    raise RuntimeError("Please install 'requests' to run this model") from _e
+
+
+@model(
+    name="api_users_requests",
+    deps=["users.ff"],  # keep a dependency for executor contract
+)
+def fetch(_: pd.DataFrame) -> pd.DataFrame:
+    """
+    Fetch users from the same demo API using plain Python code.
+    Pros: ultimate flexibility (custom auth, retry, shaping).
+    Cons: no built-in FFT telemetry or cache (unless you add it manually).
+    """
+    url = "https://jsonplaceholder.typicode.com/users"
+    headers = {
+        # Add your auth headers here if needed:
+        # "Authorization": f"Bearer {os.getenv('MY_TOKEN')}",
+    }
+    resp = requests.get(url, headers=headers, timeout=30)
+    resp.raise_for_status()
+    data = resp.json()  # list[dict]
+
+    # Example shaping
+    df = pd.DataFrame(data)
+    cols = [c for c in df.columns if c in ("id", "email", "username", "name")]
+    return df[cols].rename(columns={"id": "api_user_id"})
diff --git a/examples/api_demo/profiles.yml b/examples/api_demo/profiles.yml
new file mode 100644
index 0000000..1698a40
--- /dev/null
+++ b/examples/api_demo/profiles.yml
@@ -0,0 +1,21 @@
+default:
+  dev:
+    engine: "{{ env('FF_ENGINE' }}"
+
+    # Router variable binds "api_users_model" to the *canonical* model name
+    # We keep the same value for all engines here (api_users_http), but it could differ
+    # (e.g. "api_users_requests" or a parquet loader) per engine in real projects.
+    vars:
+      api_users_model: "api_users_http"
+
+    duckdb:
+      path: "{{ env('FF_DUCKDB_PATH') }}"
+
+    postgres:
+      # Safe default DSN for local dev; override via FF_PG_DSN in CI/Prod
+      dsn: "{{ env('FF_PG_DSN') }}"
+      db_schema: "{{ env('FF_PG_SCHEMA') }}"
+
+    databricks_spark:
+      master: "{{ env('FF_SPARK_MASTER') }}"
+      app_name: "api_demo"
diff --git a/examples/api_demo/project.yml b/examples/api_demo/project.yml
new file mode 100644
index 0000000..b84f5a8
--- /dev/null
+++ b/examples/api_demo/project.yml
@@ -0,0 +1,11 @@
+name: duckdb_api_demo
+version: "0.1"
+
+vars: {}
+
+tests:
+  # Batch‑Tabellen
+  - type: not_null
+    table: mart_users_join
+    column: user_id
+    tags: [batch]
diff --git a/examples/api_demo/seeds/seed_users.csv b/examples/api_demo/seeds/seed_users.csv
new file mode 100644
index 0000000..2acf25f
--- /dev/null
+++ b/examples/api_demo/seeds/seed_users.csv
@@ -0,0 +1,4 @@
+id,email
+1,a@example.com
+2,b@gmail.com
+3,c@gmail.com
diff --git a/examples/api_demo/site/dag/api_users_http.html b/examples/api_demo/site/dag/api_users_http.html
new file mode 100644
index 0000000..d4a491a
--- /dev/null
+++ b/examples/api_demo/site/dag/api_users_http.html
@@ -0,0 +1,261 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>api_users_http – FastFlowTransform</title>
+  <style>
+    :root {
+      --bg:#ffffff; --fg:#0f172a; --muted:#6b7280; --card:#ffffff; --border:#e5e7eb;
+      --chip-sql-bg:#e8f1ff; --chip-sql-fg:#0a1f44;
+      --chip-py-bg:#e9fbf1;  --chip-py-fg:#0b2e1f;
+      --accent:#2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg:#0b0f1a; --fg:#e5e7eb; --muted:#94a3b8; --card:#111827; --border:#1f2937;
+        --chip-sql-bg:#0e1a2c; --chip-sql-fg:#93c5fd;
+        --chip-py-bg:#0f1f15;  --chip-py-fg:#86efac;
+        --accent:#60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .muted { color: var(--muted); }
+    .card { border:1px solid var(--border); background:var(--card); border-radius:14px; padding:16px; }
+    .row { display:grid; gap:16px; grid-template-columns: 1fr; }
+    @media (min-width: 900px) { .row { grid-template-columns: 2fr 1fr; } }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .kv { display:grid; grid-template-columns: 140px 1fr; gap:8px 12px; align-items:start; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .btn { border:1px solid var(--border); background: var(--card); color: var(--fg);
+           padding:6px 10px; border-radius:10px; cursor:pointer; }
+    .btn:hover { border-color: var(--accent); }
+    ul.inline { list-style:none; padding:0; margin:0; }
+    ul.inline li { display:inline; }
+    ul.inline li+li::before { content:", "; }
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    /* Columns table layout */
+    table.cols { width:100%; border-collapse: collapse; table-layout: fixed; }
+    table.cols th, table.cols td { vertical-align: top; }
+    table.cols .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    table.cols .pill { display:inline-block; padding:1px 8px; border-radius:999px; border:1px solid var(--border); font-size:12px; }
+    table.cols .pill.yes { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    table.cols .pill.no  { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    table.cols col.col-name { width: 22%; }
+    table.cols col.col-type { width: 18%; }
+    table.cols col.col-null { width: 12%; }
+    table.cols col.col-desc { width: 28%; }
+    table.cols col.col-lineage { width: 20%; }
+    .desc { overflow-wrap:anywhere; white-space: normal; }
+    /* Lineage chips */
+    .lin-wrap { display:flex; flex-wrap:wrap; gap:6px 10px; }
+    .lineage-item { display:inline-flex; gap:6px; align-items:center; background: rgba(127,127,127,.06); padding:2px 8px; border-radius:10px; margin-bottom:4px; }
+    .badge-direct { background:#eef7ff; color:#0a3a77; border:1px solid #bcd8fb; border-radius:999px; padding:1px 8px; font-size:12px; }
+    .badge-transformed { background:#fff7e8; color:#7a4a00; border:1px solid #f6db9b; border-radius:999px; padding:1px 8px; font-size:12px; }
+  </style>
+</head>
+<body>
+  <p><a href="index.html">← Back to overview</a></p>
+
+  <header style="display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px;">
+    <div>
+      <h1 style="margin:0 0 6px 0; font-size:1.25rem;">
+        api_users_http
+        <span class="badge badge-table">table</span>
+      </h1>
+      <div class="muted">Model Detail • FastFlowTransform</div>
+    </div>
+    <span class="chip py">python</span>
+  </header>
+
+  <div class="row">
+    
+    <section class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
+      <div class="kv">
+        <div class="muted">Materialized</div>
+        <div><span class="badge badge-table">table</span></div>
+
+        <div class="muted">Relation</div>
+        <div><code>api_users_http</code></div>
+
+        <div class="muted">Path</div>
+        <div>
+          <code id="path">/Users/markolekic/Dev/FlowForge/fastflowtransform/examples/duckdb_api_demo/models/api_users_http.ff.py</code>
+          <button class="btn" id="copyPath" style="margin-left:8px;">Copy</button>
+        </div>
+
+        <div class="muted">Dependencies</div>
+        <div>
+          
+            <ul class="inline">
+              
+                <li><a href="users.ff.html">users.ff</a></li>
+              
+            </ul>
+          
+        </div>
+
+        
+        <div class="muted">Referenced by</div>
+        <div>
+          <ul class="inline">
+            
+              <li><a href="mart_users_join.ff.html">mart_users_join.ff</a></li>
+            
+          </ul>
+        </div>
+        
+      </div>
+    </section>
+
+    
+
+    
+    <section class="card">
+      <h2>Columns</h2>
+      <table class="cols">
+        <colgroup>
+          <col class="col-name" />
+          <col class="col-type" />
+          <col class="col-null" />
+          <col class="col-desc" />
+          <col class="col-lineage" />
+        </colgroup>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Nullable</th>
+            <th>Description</th>
+            <th>Lineage</th>
+          </tr>
+        </thead>
+        <tbody>
+          
+          <tr>
+            <td class="mono"><code>api_user_id</code></td>
+            <td class="mono"><code>BIGINT</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                
+                  <span class="mono"><code>?.id</code></span>
+                  
+                    <span class="badge-transformed">transformed</span>
+                  
+                  
+                
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>name</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>username</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>email</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+        </tbody>
+      </table>
+    </section>
+    
+
+    <aside class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
+      <ul style="margin:0 0 0 18px;">
+        <li>The relation is the physical table/view name (mapped via <code>relation_for</code>).</li>
+        <li><code>ref('...')</code> points to other models; <code>source()</code> points to seeds.</li>
+        <li>Python models accept DataFrames (single dependency → DataFrame, more than one → dict of relation to DataFrame).</li>
+      </ul>
+    </aside>
+  </div>
+
+  <script>
+    const btn = document.getElementById('copyPath');
+    btn?.addEventListener('click', async () => {
+      const p = document.getElementById('path')?.textContent ?? '';
+      try {
+        await navigator.clipboard.writeText(p.trim());
+        btn.textContent = 'Copied ✓';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      } catch(e) {
+        btn.textContent = 'Copy failed';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/api_demo/site/dag/api_users_requests.html b/examples/api_demo/site/dag/api_users_requests.html
new file mode 100644
index 0000000..e52fa3d
--- /dev/null
+++ b/examples/api_demo/site/dag/api_users_requests.html
@@ -0,0 +1,261 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>api_users_requests – FastFlowTransform</title>
+  <style>
+    :root {
+      --bg:#ffffff; --fg:#0f172a; --muted:#6b7280; --card:#ffffff; --border:#e5e7eb;
+      --chip-sql-bg:#e8f1ff; --chip-sql-fg:#0a1f44;
+      --chip-py-bg:#e9fbf1;  --chip-py-fg:#0b2e1f;
+      --accent:#2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg:#0b0f1a; --fg:#e5e7eb; --muted:#94a3b8; --card:#111827; --border:#1f2937;
+        --chip-sql-bg:#0e1a2c; --chip-sql-fg:#93c5fd;
+        --chip-py-bg:#0f1f15;  --chip-py-fg:#86efac;
+        --accent:#60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .muted { color: var(--muted); }
+    .card { border:1px solid var(--border); background:var(--card); border-radius:14px; padding:16px; }
+    .row { display:grid; gap:16px; grid-template-columns: 1fr; }
+    @media (min-width: 900px) { .row { grid-template-columns: 2fr 1fr; } }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .kv { display:grid; grid-template-columns: 140px 1fr; gap:8px 12px; align-items:start; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .btn { border:1px solid var(--border); background: var(--card); color: var(--fg);
+           padding:6px 10px; border-radius:10px; cursor:pointer; }
+    .btn:hover { border-color: var(--accent); }
+    ul.inline { list-style:none; padding:0; margin:0; }
+    ul.inline li { display:inline; }
+    ul.inline li+li::before { content:", "; }
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    /* Columns table layout */
+    table.cols { width:100%; border-collapse: collapse; table-layout: fixed; }
+    table.cols th, table.cols td { vertical-align: top; }
+    table.cols .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    table.cols .pill { display:inline-block; padding:1px 8px; border-radius:999px; border:1px solid var(--border); font-size:12px; }
+    table.cols .pill.yes { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    table.cols .pill.no  { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    table.cols col.col-name { width: 22%; }
+    table.cols col.col-type { width: 18%; }
+    table.cols col.col-null { width: 12%; }
+    table.cols col.col-desc { width: 28%; }
+    table.cols col.col-lineage { width: 20%; }
+    .desc { overflow-wrap:anywhere; white-space: normal; }
+    /* Lineage chips */
+    .lin-wrap { display:flex; flex-wrap:wrap; gap:6px 10px; }
+    .lineage-item { display:inline-flex; gap:6px; align-items:center; background: rgba(127,127,127,.06); padding:2px 8px; border-radius:10px; margin-bottom:4px; }
+    .badge-direct { background:#eef7ff; color:#0a3a77; border:1px solid #bcd8fb; border-radius:999px; padding:1px 8px; font-size:12px; }
+    .badge-transformed { background:#fff7e8; color:#7a4a00; border:1px solid #f6db9b; border-radius:999px; padding:1px 8px; font-size:12px; }
+  </style>
+</head>
+<body>
+  <p><a href="index.html">← Back to overview</a></p>
+
+  <header style="display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px;">
+    <div>
+      <h1 style="margin:0 0 6px 0; font-size:1.25rem;">
+        api_users_requests
+        <span class="badge badge-table">table</span>
+      </h1>
+      <div class="muted">Model Detail • FastFlowTransform</div>
+    </div>
+    <span class="chip py">python</span>
+  </header>
+
+  <div class="row">
+    
+    <section class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
+      <div class="kv">
+        <div class="muted">Materialized</div>
+        <div><span class="badge badge-table">table</span></div>
+
+        <div class="muted">Relation</div>
+        <div><code>api_users_requests</code></div>
+
+        <div class="muted">Path</div>
+        <div>
+          <code id="path">/Users/markolekic/Dev/FlowForge/fastflowtransform/examples/duckdb_api_demo/models/api_users_requests.ff.py</code>
+          <button class="btn" id="copyPath" style="margin-left:8px;">Copy</button>
+        </div>
+
+        <div class="muted">Dependencies</div>
+        <div>
+          
+            <ul class="inline">
+              
+                <li><a href="users.ff.html">users.ff</a></li>
+              
+            </ul>
+          
+        </div>
+
+        
+        <div class="muted">Referenced by</div>
+        <div>
+          <ul class="inline">
+            
+              <li><a href="mart_users_join.ff.html">mart_users_join.ff</a></li>
+            
+          </ul>
+        </div>
+        
+      </div>
+    </section>
+
+    
+
+    
+    <section class="card">
+      <h2>Columns</h2>
+      <table class="cols">
+        <colgroup>
+          <col class="col-name" />
+          <col class="col-type" />
+          <col class="col-null" />
+          <col class="col-desc" />
+          <col class="col-lineage" />
+        </colgroup>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Nullable</th>
+            <th>Description</th>
+            <th>Lineage</th>
+          </tr>
+        </thead>
+        <tbody>
+          
+          <tr>
+            <td class="mono"><code>api_user_id</code></td>
+            <td class="mono"><code>BIGINT</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                
+                  <span class="mono"><code>?.id</code></span>
+                  
+                    <span class="badge-transformed">transformed</span>
+                  
+                  
+                
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>name</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>username</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>email</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+        </tbody>
+      </table>
+    </section>
+    
+
+    <aside class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
+      <ul style="margin:0 0 0 18px;">
+        <li>The relation is the physical table/view name (mapped via <code>relation_for</code>).</li>
+        <li><code>ref('...')</code> points to other models; <code>source()</code> points to seeds.</li>
+        <li>Python models accept DataFrames (single dependency → DataFrame, more than one → dict of relation to DataFrame).</li>
+      </ul>
+    </aside>
+  </div>
+
+  <script>
+    const btn = document.getElementById('copyPath');
+    btn?.addEventListener('click', async () => {
+      const p = document.getElementById('path')?.textContent ?? '';
+      try {
+        await navigator.clipboard.writeText(p.trim());
+        btn.textContent = 'Copied ✓';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      } catch(e) {
+        btn.textContent = 'Copy failed';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/api_demo/site/dag/index.html b/examples/api_demo/site/dag/index.html
new file mode 100644
index 0000000..7a50925
--- /dev/null
+++ b/examples/api_demo/site/dag/index.html
@@ -0,0 +1,272 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1"/>
+  <title>FastFlowTransform - DAG & Mini Docs</title>
+
+  <script type="module">
+    import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
+    const prefersDark = window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches;
+    mermaid.initialize({
+      startOnLoad: true,
+      securityLevel: "loose",
+      theme: prefersDark ? "dark" : "default"
+    });
+  </script>
+
+  <style>
+    :root {
+      --bg: #ffffff;
+      --fg: #0f172a;
+      --muted: #6b7280;
+      --card: #ffffff;
+      --border: #e5e7eb;
+      --chip-sql-bg: #e8f1ff;  --chip-sql-fg: #0a1f44;
+      --chip-py-bg:  #e9fbf1;  --chip-py-fg:  #0b2e1f;
+      --accent: #2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #0b0f1a;
+        --fg: #e5e7eb;
+        --muted: #94a3b8;
+        --card: #111827;
+        --border: #1f2937;
+        --chip-sql-bg: #0e1a2c;  --chip-sql-fg: #93c5fd;
+        --chip-py-bg:  #0f1f15;  --chip-py-fg:  #86efac;
+        --accent: #60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    header { display:flex; align-items:center; justify-content:space-between; gap:16px; margin-bottom: 20px; }
+    h1 { font-size: 1.25rem; margin: 0; }
+    .muted { color: var(--muted); }
+
+    .toolbar { display:flex; gap:12px; align-items:center; flex-wrap:wrap; }
+    .input {
+      display:inline-flex; align-items:center; gap:8px;
+      border:1px solid var(--border); background: var(--card); color: var(--fg);
+      padding:8px 10px; border-radius:10px; min-width: 240px;
+    }
+    .btn {
+      border:1px solid var(--border); background: var(--card); color: var(--fg);
+      padding:8px 12px; border-radius:10px; cursor:pointer;
+    }
+    .btn:hover { border-color: var(--accent); }
+
+    .grid { display:grid; gap:24px; grid-template-columns: 2fr 1fr; }
+    @media (max-width: 1100px) { .grid { grid-template-columns: 1fr; } }
+
+    .card { border:1px solid var(--border); background: var(--card); border-radius:14px; padding:16px; }
+    .card h2 { margin:0 0 12px 0; font-size:1rem; }
+
+    .mermaid { overflow:auto; border-radius:12px; }
+    .legend { display:flex; gap:8px; align-items:center; margin-bottom:10px; flex-wrap:wrap; }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    .badge-sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .badge-py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .subline { display:block; margin-top:2px; font-size:12px; color: var(--muted); line-height:1.35; }
+    .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+
+    table { width:100%; border-collapse: collapse; }
+    th, td { padding:8px 10px; border-bottom:1px solid var(--border); text-align:left; font-size:13px; }
+    th { background: rgba(127,127,127,.06); }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .nowrap { white-space: nowrap; }
+  </style>
+</head>
+<body>
+
+  <header>
+    <div>
+      <h1>FastFlowTransform - DAG & Mini Docs</h1>
+      <div class="muted">Mermaid renders automatically (light/dark)</div>
+    </div>
+    <div class="toolbar">
+      <label class="input">
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none"><path d="M21 21l-4.3-4.3M10.5 18a7.5 7.5 0 1 1 0-15 7.5 7.5 0 0 1 0 15Z" stroke="currentColor" stroke-width="2"/></svg>
+        <input id="filter" type="search" placeholder="Filter models…" style="border:0; outline:0; background:transparent; color:inherit; width: 220px;">
+      </label>
+      <button id="copyBtn" class="btn" title="Copy Mermaid source">Copy Mermaid</button>
+    </div>
+  </header>
+
+  <div class="grid">
+    <section class="card">
+      <h2>DAG</h2>
+      <div class="legend">
+        <span class="chip sql">SQL</span>
+        <span class="chip py">Python</span>
+        <span class="muted">•</span>
+        <strong>Materialization:</strong>
+        
+          <span class="badge badge-table">table</span>
+        
+          <span class="badge badge-view">view</span>
+        
+          <span class="badge badge-ephemeral">ephemeral</span>
+        
+          <span class="badge badge-incremental">incremental</span>
+        
+      </div>
+      <div class="mermaid" id="dag">flowchart TD
+  classDef sql fill:#e8f1ff,stroke:#5b8def,color:#0a1f44;
+  classDef py  fill:#e9fbf1,stroke:#2bb673,color:#0b2e1f;
+  api_users_http("api_users_http<br/>(api_users_http)")
+  class api_users_http py;
+  api_users_requests("api_users_requests<br/>(api_users_requests)")
+  class api_users_requests py;
+  mart_users_join_ff["mart_users_join.ff<br/>(mart_users_join)"]
+  class mart_users_join_ff sql;
+  users_ff["users.ff<br/>(users)"]
+  class users_ff sql;
+  users_ff --> mart_users_join_ff
+  api_users_http --> mart_users_join_ff
+  api_users_requests --> mart_users_join_ff
+  users_ff --> api_users_requests
+  users_ff --> api_users_http
+</div>
+    </section>
+
+    <aside class="card">
+      <h2>Models</h2>
+      <table id="models">
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Relation</th>
+            <th>Deps</th>
+            <th>Materialized</th>
+          </tr>
+        </thead>
+        <tbody>
+        
+          <tr>
+            <td class="nowrap">
+              
+              <a href="api_users_http.html"
+                 title="api_users_http">
+                api_users_http
+              </a>
+              
+            </td>
+            <td><span class="chip py">python</span></td>
+            <td><code>api_users_http</code></td>
+            <td class="muted">users.ff</td>
+            <td>
+              <span class="badge badge-table">
+                table
+              </span>
+            </td>
+          </tr>
+        
+          <tr>
+            <td class="nowrap">
+              
+              <a href="api_users_requests.html"
+                 title="api_users_requests">
+                api_users_requests
+              </a>
+              
+            </td>
+            <td><span class="chip py">python</span></td>
+            <td><code>api_users_requests</code></td>
+            <td class="muted">users.ff</td>
+            <td>
+              <span class="badge badge-table">
+                table
+              </span>
+            </td>
+          </tr>
+        
+          <tr>
+            <td class="nowrap">
+              
+              <a href="mart_users_join.ff.html"
+                 title="mart_users_join.ff">
+                mart_users_join.ff
+              </a>
+              
+            </td>
+            <td><span class="chip sql">sql</span></td>
+            <td><code>mart_users_join</code></td>
+            <td class="muted">users.ff, api_users_http, api_users_requests</td>
+            <td>
+              <span class="badge badge-table">
+                table
+              </span>
+            </td>
+          </tr>
+        
+          <tr>
+            <td class="nowrap">
+              
+              <a href="users.ff.html"
+                 title="users.ff">
+                users.ff
+              </a>
+              
+            </td>
+            <td><span class="chip sql">sql</span></td>
+            <td><code>users</code></td>
+            <td class="muted">–</td>
+            <td>
+              <span class="badge badge-table">
+                table
+              </span>
+            </td>
+          </tr>
+        
+        </tbody>
+      </table>
+    </aside>
+
+    <section class="card">
+      <h2>Macros</h2>
+      
+        <p>No macros found.</p>
+      
+    </section>
+  </div>
+
+  <script>
+    // Table filter
+    const filter = document.getElementById('filter');
+    const rows = Array.from(document.querySelectorAll('#models tbody tr'));
+    filter?.addEventListener('input', () => {
+      const q = filter.value.trim().toLowerCase();
+      rows.forEach(tr => {
+        const text = tr.innerText.toLowerCase();
+        tr.style.display = text.includes(q) ? '' : 'none';
+      });
+    });
+
+    // Copy Mermaid
+    const copyBtn = document.getElementById('copyBtn');
+    copyBtn?.addEventListener('click', async () => {
+      try {
+        const src = document.getElementById('dag')?.textContent ?? '';
+        await navigator.clipboard.writeText(src.trim());
+        copyBtn.textContent = 'Copied ✓';
+        setTimeout(() => copyBtn.textContent = 'Copy Mermaid', 1200);
+      } catch(e) {
+        copyBtn.textContent = 'Copy failed';
+        setTimeout(() => copyBtn.textContent = 'Copy Mermaid', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/api_demo/site/dag/mart_users_join.ff.html b/examples/api_demo/site/dag/mart_users_join.ff.html
new file mode 100644
index 0000000..7913056
--- /dev/null
+++ b/examples/api_demo/site/dag/mart_users_join.ff.html
@@ -0,0 +1,282 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>mart_users_join.ff – FastFlowTransform</title>
+  <style>
+    :root {
+      --bg:#ffffff; --fg:#0f172a; --muted:#6b7280; --card:#ffffff; --border:#e5e7eb;
+      --chip-sql-bg:#e8f1ff; --chip-sql-fg:#0a1f44;
+      --chip-py-bg:#e9fbf1;  --chip-py-fg:#0b2e1f;
+      --accent:#2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg:#0b0f1a; --fg:#e5e7eb; --muted:#94a3b8; --card:#111827; --border:#1f2937;
+        --chip-sql-bg:#0e1a2c; --chip-sql-fg:#93c5fd;
+        --chip-py-bg:#0f1f15;  --chip-py-fg:#86efac;
+        --accent:#60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .muted { color: var(--muted); }
+    .card { border:1px solid var(--border); background:var(--card); border-radius:14px; padding:16px; }
+    .row { display:grid; gap:16px; grid-template-columns: 1fr; }
+    @media (min-width: 900px) { .row { grid-template-columns: 2fr 1fr; } }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .kv { display:grid; grid-template-columns: 140px 1fr; gap:8px 12px; align-items:start; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .btn { border:1px solid var(--border); background: var(--card); color: var(--fg);
+           padding:6px 10px; border-radius:10px; cursor:pointer; }
+    .btn:hover { border-color: var(--accent); }
+    ul.inline { list-style:none; padding:0; margin:0; }
+    ul.inline li { display:inline; }
+    ul.inline li+li::before { content:", "; }
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    /* Columns table layout */
+    table.cols { width:100%; border-collapse: collapse; table-layout: fixed; }
+    table.cols th, table.cols td { vertical-align: top; }
+    table.cols .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    table.cols .pill { display:inline-block; padding:1px 8px; border-radius:999px; border:1px solid var(--border); font-size:12px; }
+    table.cols .pill.yes { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    table.cols .pill.no  { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    table.cols col.col-name { width: 22%; }
+    table.cols col.col-type { width: 18%; }
+    table.cols col.col-null { width: 12%; }
+    table.cols col.col-desc { width: 28%; }
+    table.cols col.col-lineage { width: 20%; }
+    .desc { overflow-wrap:anywhere; white-space: normal; }
+    /* Lineage chips */
+    .lin-wrap { display:flex; flex-wrap:wrap; gap:6px 10px; }
+    .lineage-item { display:inline-flex; gap:6px; align-items:center; background: rgba(127,127,127,.06); padding:2px 8px; border-radius:10px; margin-bottom:4px; }
+    .badge-direct { background:#eef7ff; color:#0a3a77; border:1px solid #bcd8fb; border-radius:999px; padding:1px 8px; font-size:12px; }
+    .badge-transformed { background:#fff7e8; color:#7a4a00; border:1px solid #f6db9b; border-radius:999px; padding:1px 8px; font-size:12px; }
+  </style>
+</head>
+<body>
+  <p><a href="index.html">← Back to overview</a></p>
+
+  <header style="display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px;">
+    <div>
+      <h1 style="margin:0 0 6px 0; font-size:1.25rem;">
+        mart_users_join.ff
+        <span class="badge badge-table">table</span>
+      </h1>
+      <div class="muted">Model Detail • FastFlowTransform</div>
+    </div>
+    <span class="chip sql">sql</span>
+  </header>
+
+  <div class="row">
+    
+    <section class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
+      <div class="kv">
+        <div class="muted">Materialized</div>
+        <div><span class="badge badge-table">table</span></div>
+
+        <div class="muted">Relation</div>
+        <div><code>mart_users_join</code></div>
+
+        <div class="muted">Path</div>
+        <div>
+          <code id="path">/Users/markolekic/Dev/FlowForge/fastflowtransform/examples/duckdb_api_demo/models/mart_users_join.ff.sql</code>
+          <button class="btn" id="copyPath" style="margin-left:8px;">Copy</button>
+        </div>
+
+        <div class="muted">Dependencies</div>
+        <div>
+          
+            <ul class="inline">
+              
+                <li><a href="users.ff.html">users.ff</a></li>
+              
+                <li><a href="api_users_http.html">api_users_http</a></li>
+              
+                <li><a href="api_users_requests.html">api_users_requests</a></li>
+              
+            </ul>
+          
+        </div>
+
+        
+      </div>
+    </section>
+
+    
+
+    
+    <section class="card">
+      <h2>Columns</h2>
+      <table class="cols">
+        <colgroup>
+          <col class="col-name" />
+          <col class="col-type" />
+          <col class="col-null" />
+          <col class="col-desc" />
+          <col class="col-lineage" />
+        </colgroup>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Nullable</th>
+            <th>Description</th>
+            <th>Lineage</th>
+          </tr>
+        </thead>
+        <tbody>
+          
+          <tr>
+            <td class="mono"><code>user_id</code></td>
+            <td class="mono"><code>BIGINT</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                
+                  <span class="mono"><code>?.id</code></span>
+                  
+                    <span class="badge-direct">direct</span>
+                  
+                  
+                
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>email</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                
+                  <span class="mono"><code>?.email</code></span>
+                  
+                    <span class="badge-direct">direct</span>
+                  
+                  
+                
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>api_user_id</code></td>
+            <td class="mono"><code>BIGINT</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>username</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>name</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+        </tbody>
+      </table>
+    </section>
+    
+
+    <aside class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
+      <ul style="margin:0 0 0 18px;">
+        <li>The relation is the physical table/view name (mapped via <code>relation_for</code>).</li>
+        <li><code>ref('...')</code> points to other models; <code>source()</code> points to seeds.</li>
+        <li>Python models accept DataFrames (single dependency → DataFrame, more than one → dict of relation to DataFrame).</li>
+      </ul>
+    </aside>
+  </div>
+
+  <script>
+    const btn = document.getElementById('copyPath');
+    btn?.addEventListener('click', async () => {
+      const p = document.getElementById('path')?.textContent ?? '';
+      try {
+        await navigator.clipboard.writeText(p.trim());
+        btn.textContent = 'Copied ✓';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      } catch(e) {
+        btn.textContent = 'Copy failed';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/api_demo/site/dag/users.ff.html b/examples/api_demo/site/dag/users.ff.html
new file mode 100644
index 0000000..ae430a3
--- /dev/null
+++ b/examples/api_demo/site/dag/users.ff.html
@@ -0,0 +1,227 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>users.ff – FastFlowTransform</title>
+  <style>
+    :root {
+      --bg:#ffffff; --fg:#0f172a; --muted:#6b7280; --card:#ffffff; --border:#e5e7eb;
+      --chip-sql-bg:#e8f1ff; --chip-sql-fg:#0a1f44;
+      --chip-py-bg:#e9fbf1;  --chip-py-fg:#0b2e1f;
+      --accent:#2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg:#0b0f1a; --fg:#e5e7eb; --muted:#94a3b8; --card:#111827; --border:#1f2937;
+        --chip-sql-bg:#0e1a2c; --chip-sql-fg:#93c5fd;
+        --chip-py-bg:#0f1f15;  --chip-py-fg:#86efac;
+        --accent:#60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .muted { color: var(--muted); }
+    .card { border:1px solid var(--border); background:var(--card); border-radius:14px; padding:16px; }
+    .row { display:grid; gap:16px; grid-template-columns: 1fr; }
+    @media (min-width: 900px) { .row { grid-template-columns: 2fr 1fr; } }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .kv { display:grid; grid-template-columns: 140px 1fr; gap:8px 12px; align-items:start; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .btn { border:1px solid var(--border); background: var(--card); color: var(--fg);
+           padding:6px 10px; border-radius:10px; cursor:pointer; }
+    .btn:hover { border-color: var(--accent); }
+    ul.inline { list-style:none; padding:0; margin:0; }
+    ul.inline li { display:inline; }
+    ul.inline li+li::before { content:", "; }
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    /* Columns table layout */
+    table.cols { width:100%; border-collapse: collapse; table-layout: fixed; }
+    table.cols th, table.cols td { vertical-align: top; }
+    table.cols .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    table.cols .pill { display:inline-block; padding:1px 8px; border-radius:999px; border:1px solid var(--border); font-size:12px; }
+    table.cols .pill.yes { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    table.cols .pill.no  { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    table.cols col.col-name { width: 22%; }
+    table.cols col.col-type { width: 18%; }
+    table.cols col.col-null { width: 12%; }
+    table.cols col.col-desc { width: 28%; }
+    table.cols col.col-lineage { width: 20%; }
+    .desc { overflow-wrap:anywhere; white-space: normal; }
+    /* Lineage chips */
+    .lin-wrap { display:flex; flex-wrap:wrap; gap:6px 10px; }
+    .lineage-item { display:inline-flex; gap:6px; align-items:center; background: rgba(127,127,127,.06); padding:2px 8px; border-radius:10px; margin-bottom:4px; }
+    .badge-direct { background:#eef7ff; color:#0a3a77; border:1px solid #bcd8fb; border-radius:999px; padding:1px 8px; font-size:12px; }
+    .badge-transformed { background:#fff7e8; color:#7a4a00; border:1px solid #f6db9b; border-radius:999px; padding:1px 8px; font-size:12px; }
+  </style>
+</head>
+<body>
+  <p><a href="index.html">← Back to overview</a></p>
+
+  <header style="display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px;">
+    <div>
+      <h1 style="margin:0 0 6px 0; font-size:1.25rem;">
+        users.ff
+        <span class="badge badge-table">table</span>
+      </h1>
+      <div class="muted">Model Detail • FastFlowTransform</div>
+    </div>
+    <span class="chip sql">sql</span>
+  </header>
+
+  <div class="row">
+    
+    <section class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
+      <div class="kv">
+        <div class="muted">Materialized</div>
+        <div><span class="badge badge-table">table</span></div>
+
+        <div class="muted">Relation</div>
+        <div><code>users</code></div>
+
+        <div class="muted">Path</div>
+        <div>
+          <code id="path">/Users/markolekic/Dev/FlowForge/fastflowtransform/examples/duckdb_api_demo/models/users.ff.sql</code>
+          <button class="btn" id="copyPath" style="margin-left:8px;">Copy</button>
+        </div>
+
+        <div class="muted">Dependencies</div>
+        <div>
+          
+            <span class="muted">–</span>
+          
+        </div>
+
+        
+        <div class="muted">Referenced by</div>
+        <div>
+          <ul class="inline">
+            
+              <li><a href="api_users_http.html">api_users_http</a></li>
+            
+              <li><a href="api_users_requests.html">api_users_requests</a></li>
+            
+              <li><a href="mart_users_join.ff.html">mart_users_join.ff</a></li>
+            
+          </ul>
+        </div>
+        
+      </div>
+    </section>
+
+    
+
+    
+    <section class="card">
+      <h2>Columns</h2>
+      <table class="cols">
+        <colgroup>
+          <col class="col-name" />
+          <col class="col-type" />
+          <col class="col-null" />
+          <col class="col-desc" />
+          <col class="col-lineage" />
+        </colgroup>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Nullable</th>
+            <th>Description</th>
+            <th>Lineage</th>
+          </tr>
+        </thead>
+        <tbody>
+          
+          <tr>
+            <td class="mono"><code>id</code></td>
+            <td class="mono"><code>BIGINT</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                
+                  <span class="mono"><code>?.id</code></span>
+                  
+                    <span class="badge-direct">direct</span>
+                  
+                  
+                
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>email</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                
+                  <span class="mono"><code>?.email</code></span>
+                  
+                    <span class="badge-direct">direct</span>
+                  
+                  
+                
+              
+            </td>
+          </tr>
+          
+        </tbody>
+      </table>
+    </section>
+    
+
+    <aside class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
+      <ul style="margin:0 0 0 18px;">
+        <li>The relation is the physical table/view name (mapped via <code>relation_for</code>).</li>
+        <li><code>ref('...')</code> points to other models; <code>source()</code> points to seeds.</li>
+        <li>Python models accept DataFrames (single dependency → DataFrame, more than one → dict of relation to DataFrame).</li>
+      </ul>
+    </aside>
+  </div>
+
+  <script>
+    const btn = document.getElementById('copyPath');
+    btn?.addEventListener('click', async () => {
+      const p = document.getElementById('path')?.textContent ?? '';
+      try {
+        await navigator.clipboard.writeText(p.trim());
+        btn.textContent = 'Copied ✓';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      } catch(e) {
+        btn.textContent = 'Copy failed';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/api_demo/sources.yml b/examples/api_demo/sources.yml
new file mode 100644
index 0000000..84e04d5
--- /dev/null
+++ b/examples/api_demo/sources.yml
@@ -0,0 +1,7 @@
+version: 2
+
+sources:
+  - name: crm
+    tables:
+      - name: users
+        identifier: seed_users     # will be materialized via `fft seed`
diff --git a/examples/env_matrix/.fastflowtransform/cache/prod-duckdb.json b/examples/env_matrix/.fastflowtransform/cache/prod-duckdb.json
new file mode 100644
index 0000000..9eacacd
--- /dev/null
+++ b/examples/env_matrix/.fastflowtransform/cache/prod-duckdb.json
@@ -0,0 +1,9 @@
+{
+  "engine": "duckdb",
+  "entries": {
+    "env_vars.ff": "f7ef95030b8fe43c52bd748deb4fb8061c41d9f384b5b34a49ff69203cde4d82",
+    "users.ff": "11705124b10bc738b123f525e164f81d909972b29651b4b86153c8edba18bde1"
+  },
+  "profile": "prod",
+  "version": 1
+}
\ No newline at end of file
diff --git a/examples/env_matrix/.fastflowtransform/target/catalog.json b/examples/env_matrix/.fastflowtransform/target/catalog.json
new file mode 100644
index 0000000..743d3df
--- /dev/null
+++ b/examples/env_matrix/.fastflowtransform/target/catalog.json
@@ -0,0 +1,51 @@
+{
+  "metadata": {
+    "generated_at": "2025-10-28T18:36:20+00:00",
+    "tool": "fastflowtransform"
+  },
+  "relations": {
+    "env_vars": {
+      "columns": [
+        {
+          "dtype": "VARCHAR",
+          "name": "active_env_hint",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "ff_engine",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "duckdb_path",
+          "nullable": true
+        },
+        {
+          "dtype": "BOOLEAN",
+          "name": "duckdb_exists",
+          "nullable": true
+        },
+        {
+          "dtype": "BIGINT",
+          "name": "duckdb_size_bytes",
+          "nullable": true
+        }
+      ]
+    },
+    "users": {
+      "columns": [
+        {
+          "dtype": "BIGINT",
+          "name": "id",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "email",
+          "nullable": true
+        }
+      ]
+    }
+  }
+}
diff --git a/examples/env_matrix/.fastflowtransform/target/manifest.json b/examples/env_matrix/.fastflowtransform/target/manifest.json
new file mode 100644
index 0000000..473bc66
--- /dev/null
+++ b/examples/env_matrix/.fastflowtransform/target/manifest.json
@@ -0,0 +1,53 @@
+{
+  "macros": {},
+  "metadata": {
+    "generated_at": "2025-10-28T18:36:20+00:00",
+    "tool": "fastflowtransform"
+  },
+  "nodes": {
+    "env_vars.ff": {
+      "deps": [],
+      "kind": "python",
+      "materialized": "table",
+      "name": "env_vars.ff",
+      "path": "models/env_vars.ff.py",
+      "relation": "env_vars"
+    },
+    "users.ff": {
+      "deps": [],
+      "kind": "sql",
+      "materialized": "table",
+      "name": "users.ff",
+      "path": "models/users.ff.sql",
+      "relation": "users"
+    }
+  },
+  "sources": {
+    "raw": {
+      "seed_users": {
+        "base": {
+          "catalog": null,
+          "database": null,
+          "dataset": null,
+          "format": null,
+          "identifier": "seed_users",
+          "location": null,
+          "options": {},
+          "project": null,
+          "schema": "raw"
+        },
+        "overrides": {
+          "databricks_spark": {
+            "format": "delta",
+            "location": "/mnt/delta/raw/seed_users",
+            "options": {}
+          },
+          "postgres": {
+            "options": {},
+            "schema": "main"
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/examples/env_matrix/.fastflowtransform/target/run_results.json b/examples/env_matrix/.fastflowtransform/target/run_results.json
new file mode 100644
index 0000000..a9adfc8
--- /dev/null
+++ b/examples/env_matrix/.fastflowtransform/target/run_results.json
@@ -0,0 +1,28 @@
+{
+  "metadata": {
+    "generated_at": "2025-10-28T18:36:20+00:00",
+    "tool": "fastflowtransform"
+  },
+  "results": [
+    {
+      "duration_ms": 5,
+      "finished_at": "2025-10-28T18:36:20+00:00",
+      "http": null,
+      "message": null,
+      "name": "env_vars.ff",
+      "started_at": "2025-10-28T18:36:20+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 2,
+      "finished_at": "2025-10-28T18:36:20+00:00",
+      "http": null,
+      "message": null,
+      "name": "users.ff",
+      "started_at": "2025-10-28T18:36:20+00:00",
+      "status": "success"
+    }
+  ],
+  "run_finished_at": "2025-10-28T18:36:20+00:00",
+  "run_started_at": "2025-10-28T18:36:20+00:00"
+}
diff --git a/examples/env_matrix/Makefile b/examples/env_matrix/Makefile
new file mode 100644
index 0000000..ab4d5ad
--- /dev/null
+++ b/examples/env_matrix/Makefile
@@ -0,0 +1,78 @@
+.PHONY: seed-dev seed-stg seed-prod run-dev run-stg run-prod dag-dev clean \
+        demo-dev demo-stg demo-prod demo artifacts
+
+PROJECT ?= .
+UV ?= uv
+
+seed-dev:
+	$(UV) run fft seed "$(PROJECT)" --env dev
+
+seed-stg:
+	$(UV) run fft seed "$(PROJECT)" --env stg
+
+seed-prod:
+	$(UV) run fft seed "$(PROJECT)" --env prod
+
+run-dev:
+	$(UV) run fft run "$(PROJECT)" --env dev
+
+run-stg:
+	$(UV) run fft run "$(PROJECT)" --env stg
+
+run-prod:
+	$(UV) run fft run "$(PROJECT)" --env prod
+
+dag-dev:
+	$(UV) run fft dag "$(PROJECT)" --env dev --html
+
+dag-stg:
+	$(UV) run fft dag "$(PROJECT)" --env stg --html
+
+dag-prod:
+	$(UV) run fft dag "$(PROJECT)" --env prod --html
+
+test-dev:
+	$(UV) run fft test $(PROJECT) --env dev
+
+test-stg:
+	$(UV) run fft test $(PROJECT) --env stg
+
+test-prod:
+	$(UV) run fft test $(PROJECT) --env prod
+
+clean:
+	rm -rf .local "$(PROJECT)/docs" "$(PROJECT)/site" .fastflowtransform
+
+# --- Convenience: show common artifacts path quickly
+artifacts:
+	@echo
+	@echo "== 📦 Artifacts =="
+	@echo "  $(PROJECT)/.fastflowtransform/target/{manifest.json,run_results.json,catalog.json}"
+	@echo "  DAG HTML (if generated): $(PROJECT)/site/dag/index.html"
+
+# --- One-shot demos per environment -----------------------------------------
+
+demo-dev: clean seed-dev run-dev test-dev dag-dev artifacts
+	@echo
+	@echo "✅ Demo (dev) complete. Open DAG here (if generated): $(PROJECT)/site/dag/index.html"
+
+demo-stg: clean seed-stg run-stg test-stg dag-stg artifacts
+	@echo
+	@echo "✅ Demo (stg) complete."
+
+demo-prod: clean seed-prod run-prod test-prod dag-prod artifacts
+	@echo
+	@echo "✅ Demo (prod) complete."
+
+# --- Generic demo with ENV selector (dev|stg|prod) ---------------------------
+
+ENV ?= dev
+
+demo:
+	@echo "== 🚀 Demo ENV=$(ENV) PROJECT=$(PROJECT) =="
+	@case "$(ENV)" in \
+		dev)  $(MAKE) demo-dev  ;; \
+		stg)  $(MAKE) demo-stg  ;; \
+		prod) $(MAKE) demo-prod ;; \
+		*) echo "Unknown ENV=$(ENV). Use dev|stg|prod."; exit 1 ;; \
+	esac
diff --git a/examples/env_matrix/models/env_vars.ff.py b/examples/env_matrix/models/env_vars.ff.py
new file mode 100644
index 0000000..646b969
--- /dev/null
+++ b/examples/env_matrix/models/env_vars.ff.py
@@ -0,0 +1,46 @@
+# models/env_vars.ff.py
+# Purpose: Minimal, engine-agnostic Python model that echoes which environment
+#          variables are active for the current run. Optimized for the
+#          "all-DuckDB" setup (dev/stg/prod each point to a different file).
+
+from __future__ import annotations
+import os
+import pathlib
+import pandas as pd
+
+from fastflowtransform import model  # your existing decorator
+
+
+@model(
+    name="env_vars.ff",
+    tags=["demo", "env"],
+    kind="python",
+    meta={"materialized": "table"},
+)
+def build(_: pd.DataFrame | None) -> pd.DataFrame:
+    """
+    Return a single-row DataFrame showing the key environment variables
+    for the DuckDB-only setup.
+
+    Columns:
+      - active_env_hint: optional marker from your .env.<env> file (if you set FFT_ACTIVE_ENV).
+      - ff_engine: should be "duckdb" for all environments in this demo.
+      - duckdb_path: the DB file path in use for the active environment.
+      - duckdb_exists: whether that file currently exists on disk.
+      - duckdb_size_bytes: file size if it exists (0 otherwise).
+    """
+    duck_path = os.getenv("FF_DUCKDB_PATH", "")
+    p = pathlib.Path(duck_path)
+    exists = bool(p and p.exists())
+    size = int(p.stat().st_size) if exists else 0
+
+    row = {
+        "active_env_hint": os.getenv(
+            "FFT_ACTIVE_ENV"
+        ),  # set in .env.dev/.env.stg/.env.prod (optional)
+        "ff_engine": os.getenv("FF_ENGINE", "duckdb"),
+        "duckdb_path": duck_path,
+        "duckdb_exists": exists,
+        "duckdb_size_bytes": size,
+    }
+    return pd.DataFrame([row])
diff --git a/examples/env_matrix/models/users.ff.sql b/examples/env_matrix/models/users.ff.sql
new file mode 100644
index 0000000..47c2f46
--- /dev/null
+++ b/examples/env_matrix/models/users.ff.sql
@@ -0,0 +1,5 @@
+{{ config(materialized='table', tags=['demo', 'env', 'seed']) }}
+select
+  id,
+  email
+from {{ source('raw', 'seed_users') }}
diff --git a/examples/env_matrix/profiles.yml b/examples/env_matrix/profiles.yml
new file mode 100644
index 0000000..f9a04a6
--- /dev/null
+++ b/examples/env_matrix/profiles.yml
@@ -0,0 +1,15 @@
+default:
+  dev:
+    engine: "{{ env('FF_ENGINE') }}"
+    duckdb:
+      path: "{{ env('FF_DUCKDB_PATH') }}"
+
+  stg:
+    engine: "{{ env('FF_ENGINE') }}"
+    duckdb:
+      path: "{{ env('FF_DUCKDB_PATH') }}"
+
+  prod:
+    engine: "{{ env('FF_ENGINE') }}"
+    duckdb:
+      path: "{{ env('FF_DUCKDB_PATH') }}"
diff --git a/examples/env_matrix/project.yml b/examples/env_matrix/project.yml
new file mode 100644
index 0000000..502a0b7
--- /dev/null
+++ b/examples/env_matrix/project.yml
@@ -0,0 +1,17 @@
+name: duckdb_api_demo
+version: "0.1"
+
+vars: {}
+
+tests:
+  # Batch‑Tabellen
+  - type: accepted_values
+    table: env_vars
+    column: ff_engine
+    values: [duckdb]
+    tags: [batch]
+
+  - type: row_count_between
+    table: users
+    min: 1
+    tags: [batch]
diff --git a/examples/env_matrix/seeds/raw/seed_users.csv b/examples/env_matrix/seeds/raw/seed_users.csv
new file mode 100644
index 0000000..6622ba4
--- /dev/null
+++ b/examples/env_matrix/seeds/raw/seed_users.csv
@@ -0,0 +1,4 @@
+id,email,username,name
+1,alice@example.com,alice,Alice Wonderland
+2,bob@example.com,bob,Bob Builder
+3,carol@example.com,carol,Carol Singer
diff --git a/examples/env_matrix/seeds/schema.yml b/examples/env_matrix/seeds/schema.yml
new file mode 100644
index 0000000..3ff84e8
--- /dev/null
+++ b/examples/env_matrix/seeds/schema.yml
@@ -0,0 +1,7 @@
+targets:
+  raw/seed_users:
+    schema: raw
+    table: seed_users          # optional Rename
+    schema_by_engine:     # optional
+      postgres: main
+      duckdb: raw
diff --git a/examples/env_matrix/site/dag/env_vars.ff.html b/examples/env_matrix/site/dag/env_vars.ff.html
new file mode 100644
index 0000000..5605883
--- /dev/null
+++ b/examples/env_matrix/site/dag/env_vars.ff.html
@@ -0,0 +1,262 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>env_vars.ff – FastFlowTransform</title>
+  <style>
+    :root {
+      --bg:#ffffff; --fg:#0f172a; --muted:#6b7280; --card:#ffffff; --border:#e5e7eb;
+      --chip-sql-bg:#e8f1ff; --chip-sql-fg:#0a1f44;
+      --chip-py-bg:#e9fbf1;  --chip-py-fg:#0b2e1f;
+      --accent:#2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg:#0b0f1a; --fg:#e5e7eb; --muted:#94a3b8; --card:#111827; --border:#1f2937;
+        --chip-sql-bg:#0e1a2c; --chip-sql-fg:#93c5fd;
+        --chip-py-bg:#0f1f15;  --chip-py-fg:#86efac;
+        --accent:#60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .muted { color: var(--muted); }
+    .card { border:1px solid var(--border); background:var(--card); border-radius:14px; padding:16px; }
+    .row { display:grid; gap:16px; grid-template-columns: 1fr; }
+    @media (min-width: 900px) { .row { grid-template-columns: 2fr 1fr; } }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .kv { display:grid; grid-template-columns: 140px 1fr; gap:8px 12px; align-items:start; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .btn { border:1px solid var(--border); background: var(--card); color: var(--fg);
+           padding:6px 10px; border-radius:10px; cursor:pointer; }
+    .btn:hover { border-color: var(--accent); }
+    ul.inline { list-style:none; padding:0; margin:0; }
+    ul.inline li { display:inline; }
+    ul.inline li+li::before { content:", "; }
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    /* Columns table layout */
+    table.cols { width:100%; border-collapse: collapse; table-layout: fixed; }
+    table.cols th, table.cols td { vertical-align: top; }
+    table.cols .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    table.cols .pill { display:inline-block; padding:1px 8px; border-radius:999px; border:1px solid var(--border); font-size:12px; }
+    table.cols .pill.yes { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    table.cols .pill.no  { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    table.cols col.col-name { width: 22%; }
+    table.cols col.col-type { width: 18%; }
+    table.cols col.col-null { width: 12%; }
+    table.cols col.col-desc { width: 28%; }
+    table.cols col.col-lineage { width: 20%; }
+    .desc { overflow-wrap:anywhere; white-space: normal; }
+    /* Lineage chips */
+    .lin-wrap { display:flex; flex-wrap:wrap; gap:6px 10px; }
+    .lineage-item { display:inline-flex; gap:6px; align-items:center; background: rgba(127,127,127,.06); padding:2px 8px; border-radius:10px; margin-bottom:4px; }
+    .badge-direct { background:#eef7ff; color:#0a3a77; border:1px solid #bcd8fb; border-radius:999px; padding:1px 8px; font-size:12px; }
+    .badge-transformed { background:#fff7e8; color:#7a4a00; border:1px solid #f6db9b; border-radius:999px; padding:1px 8px; font-size:12px; }
+  </style>
+</head>
+<body>
+  <p><a href="index.html">← Back to overview</a></p>
+
+  <header style="display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px;">
+    <div>
+      <h1 style="margin:0 0 6px 0; font-size:1.25rem;">
+        env_vars.ff
+        <span class="badge badge-table">table</span>
+      </h1>
+      <div class="muted">Model Detail • FastFlowTransform</div>
+    </div>
+    <span class="chip py">python</span>
+  </header>
+
+  <div class="row">
+    
+    <section class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
+      <div class="kv">
+        <div class="muted">Materialized</div>
+        <div><span class="badge badge-table">table</span></div>
+
+        <div class="muted">Relation</div>
+        <div><code>env_vars</code></div>
+
+        <div class="muted">Path</div>
+        <div>
+          <code id="path">/Users/markolekic/Dev/FlowForge/fastflowtransform/examples/env_matrix/models/env_vars.ff.py</code>
+          <button class="btn" id="copyPath" style="margin-left:8px;">Copy</button>
+        </div>
+
+        <div class="muted">Dependencies</div>
+        <div>
+          
+            <span class="muted">–</span>
+          
+        </div>
+
+        
+      </div>
+    </section>
+
+    
+
+    
+    <section class="card">
+      <h2>Columns</h2>
+      <table class="cols">
+        <colgroup>
+          <col class="col-name" />
+          <col class="col-type" />
+          <col class="col-null" />
+          <col class="col-desc" />
+          <col class="col-lineage" />
+        </colgroup>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Nullable</th>
+            <th>Description</th>
+            <th>Lineage</th>
+          </tr>
+        </thead>
+        <tbody>
+          
+          <tr>
+            <td class="mono"><code>active_env_hint</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>ff_engine</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>duckdb_path</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>duckdb_exists</code></td>
+            <td class="mono"><code>BOOLEAN</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>duckdb_size_bytes</code></td>
+            <td class="mono"><code>BIGINT</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+        </tbody>
+      </table>
+    </section>
+    
+
+    <aside class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
+      <ul style="margin:0 0 0 18px;">
+        <li>The relation is the physical table/view name (mapped via <code>relation_for</code>).</li>
+        <li><code>ref('...')</code> points to other models; <code>source()</code> points to seeds.</li>
+        <li>Python models accept DataFrames (single dependency → DataFrame, more than one → dict of relation to DataFrame).</li>
+      </ul>
+    </aside>
+  </div>
+
+  <script>
+    const btn = document.getElementById('copyPath');
+    btn?.addEventListener('click', async () => {
+      const p = document.getElementById('path')?.textContent ?? '';
+      try {
+        await navigator.clipboard.writeText(p.trim());
+        btn.textContent = 'Copied ✓';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      } catch(e) {
+        btn.textContent = 'Copy failed';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/env_matrix/site/dag/index.html b/examples/env_matrix/site/dag/index.html
new file mode 100644
index 0000000..ef240f3
--- /dev/null
+++ b/examples/env_matrix/site/dag/index.html
@@ -0,0 +1,225 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1"/>
+  <title>FastFlowTransform - DAG & Mini Docs</title>
+
+  <script type="module">
+    import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
+    const prefersDark = window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches;
+    mermaid.initialize({
+      startOnLoad: true,
+      securityLevel: "loose",
+      theme: prefersDark ? "dark" : "default"
+    });
+  </script>
+
+  <style>
+    :root {
+      --bg: #ffffff;
+      --fg: #0f172a;
+      --muted: #6b7280;
+      --card: #ffffff;
+      --border: #e5e7eb;
+      --chip-sql-bg: #e8f1ff;  --chip-sql-fg: #0a1f44;
+      --chip-py-bg:  #e9fbf1;  --chip-py-fg:  #0b2e1f;
+      --accent: #2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #0b0f1a;
+        --fg: #e5e7eb;
+        --muted: #94a3b8;
+        --card: #111827;
+        --border: #1f2937;
+        --chip-sql-bg: #0e1a2c;  --chip-sql-fg: #93c5fd;
+        --chip-py-bg:  #0f1f15;  --chip-py-fg:  #86efac;
+        --accent: #60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    header { display:flex; align-items:center; justify-content:space-between; gap:16px; margin-bottom: 20px; }
+    h1 { font-size: 1.25rem; margin: 0; }
+    .muted { color: var(--muted); }
+
+    .toolbar { display:flex; gap:12px; align-items:center; flex-wrap:wrap; }
+    .input {
+      display:inline-flex; align-items:center; gap:8px;
+      border:1px solid var(--border); background: var(--card); color: var(--fg);
+      padding:8px 10px; border-radius:10px; min-width: 240px;
+    }
+    .btn {
+      border:1px solid var(--border); background: var(--card); color: var(--fg);
+      padding:8px 12px; border-radius:10px; cursor:pointer;
+    }
+    .btn:hover { border-color: var(--accent); }
+
+    .grid { display:grid; gap:24px; grid-template-columns: 2fr 1fr; }
+    @media (max-width: 1100px) { .grid { grid-template-columns: 1fr; } }
+
+    .card { border:1px solid var(--border); background: var(--card); border-radius:14px; padding:16px; }
+    .card h2 { margin:0 0 12px 0; font-size:1rem; }
+
+    .mermaid { overflow:auto; border-radius:12px; }
+    .legend { display:flex; gap:8px; align-items:center; margin-bottom:10px; flex-wrap:wrap; }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    .badge-sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .badge-py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .subline { display:block; margin-top:2px; font-size:12px; color: var(--muted); line-height:1.35; }
+    .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+
+    table { width:100%; border-collapse: collapse; }
+    th, td { padding:8px 10px; border-bottom:1px solid var(--border); text-align:left; font-size:13px; }
+    th { background: rgba(127,127,127,.06); }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .nowrap { white-space: nowrap; }
+  </style>
+</head>
+<body>
+
+  <header>
+    <div>
+      <h1>FastFlowTransform - DAG & Mini Docs</h1>
+      <div class="muted">Mermaid renders automatically (light/dark)</div>
+    </div>
+    <div class="toolbar">
+      <label class="input">
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none"><path d="M21 21l-4.3-4.3M10.5 18a7.5 7.5 0 1 1 0-15 7.5 7.5 0 0 1 0 15Z" stroke="currentColor" stroke-width="2"/></svg>
+        <input id="filter" type="search" placeholder="Filter models…" style="border:0; outline:0; background:transparent; color:inherit; width: 220px;">
+      </label>
+      <button id="copyBtn" class="btn" title="Copy Mermaid source">Copy Mermaid</button>
+    </div>
+  </header>
+
+  <div class="grid">
+    <section class="card">
+      <h2>DAG</h2>
+      <div class="legend">
+        <span class="chip sql">SQL</span>
+        <span class="chip py">Python</span>
+        <span class="muted">•</span>
+        <strong>Materialization:</strong>
+        
+          <span class="badge badge-table">table</span>
+        
+          <span class="badge badge-view">view</span>
+        
+          <span class="badge badge-ephemeral">ephemeral</span>
+        
+          <span class="badge badge-incremental">incremental</span>
+        
+      </div>
+      <div class="mermaid" id="dag">flowchart TD
+  classDef sql fill:#e8f1ff,stroke:#5b8def,color:#0a1f44;
+  classDef py  fill:#e9fbf1,stroke:#2bb673,color:#0b2e1f;
+  env_vars_ff("env_vars.ff<br/>(env_vars)")
+  class env_vars_ff py;
+  users_ff["users.ff<br/>(users)"]
+  class users_ff sql;
+</div>
+    </section>
+
+    <aside class="card">
+      <h2>Models</h2>
+      <table id="models">
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Relation</th>
+            <th>Deps</th>
+            <th>Materialized</th>
+          </tr>
+        </thead>
+        <tbody>
+        
+          <tr>
+            <td class="nowrap">
+              
+              <a href="env_vars.ff.html"
+                 title="env_vars.ff">
+                env_vars.ff
+              </a>
+              
+            </td>
+            <td><span class="chip py">python</span></td>
+            <td><code>env_vars</code></td>
+            <td class="muted">–</td>
+            <td>
+              <span class="badge badge-table">
+                table
+              </span>
+            </td>
+          </tr>
+        
+          <tr>
+            <td class="nowrap">
+              
+              <a href="users.ff.html"
+                 title="users.ff">
+                users.ff
+              </a>
+              
+            </td>
+            <td><span class="chip sql">sql</span></td>
+            <td><code>users</code></td>
+            <td class="muted">–</td>
+            <td>
+              <span class="badge badge-table">
+                table
+              </span>
+            </td>
+          </tr>
+        
+        </tbody>
+      </table>
+    </aside>
+
+    <section class="card">
+      <h2>Macros</h2>
+      
+        <p>No macros found.</p>
+      
+    </section>
+  </div>
+
+  <script>
+    // Table filter
+    const filter = document.getElementById('filter');
+    const rows = Array.from(document.querySelectorAll('#models tbody tr'));
+    filter?.addEventListener('input', () => {
+      const q = filter.value.trim().toLowerCase();
+      rows.forEach(tr => {
+        const text = tr.innerText.toLowerCase();
+        tr.style.display = text.includes(q) ? '' : 'none';
+      });
+    });
+
+    // Copy Mermaid
+    const copyBtn = document.getElementById('copyBtn');
+    copyBtn?.addEventListener('click', async () => {
+      try {
+        const src = document.getElementById('dag')?.textContent ?? '';
+        await navigator.clipboard.writeText(src.trim());
+        copyBtn.textContent = 'Copied ✓';
+        setTimeout(() => copyBtn.textContent = 'Copy Mermaid', 1200);
+      } catch(e) {
+        copyBtn.textContent = 'Copy failed';
+        setTimeout(() => copyBtn.textContent = 'Copy Mermaid', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/env_matrix/site/dag/users.ff.html b/examples/env_matrix/site/dag/users.ff.html
new file mode 100644
index 0000000..7a9026f
--- /dev/null
+++ b/examples/env_matrix/site/dag/users.ff.html
@@ -0,0 +1,214 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>users.ff – FastFlowTransform</title>
+  <style>
+    :root {
+      --bg:#ffffff; --fg:#0f172a; --muted:#6b7280; --card:#ffffff; --border:#e5e7eb;
+      --chip-sql-bg:#e8f1ff; --chip-sql-fg:#0a1f44;
+      --chip-py-bg:#e9fbf1;  --chip-py-fg:#0b2e1f;
+      --accent:#2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg:#0b0f1a; --fg:#e5e7eb; --muted:#94a3b8; --card:#111827; --border:#1f2937;
+        --chip-sql-bg:#0e1a2c; --chip-sql-fg:#93c5fd;
+        --chip-py-bg:#0f1f15;  --chip-py-fg:#86efac;
+        --accent:#60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .muted { color: var(--muted); }
+    .card { border:1px solid var(--border); background:var(--card); border-radius:14px; padding:16px; }
+    .row { display:grid; gap:16px; grid-template-columns: 1fr; }
+    @media (min-width: 900px) { .row { grid-template-columns: 2fr 1fr; } }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .kv { display:grid; grid-template-columns: 140px 1fr; gap:8px 12px; align-items:start; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .btn { border:1px solid var(--border); background: var(--card); color: var(--fg);
+           padding:6px 10px; border-radius:10px; cursor:pointer; }
+    .btn:hover { border-color: var(--accent); }
+    ul.inline { list-style:none; padding:0; margin:0; }
+    ul.inline li { display:inline; }
+    ul.inline li+li::before { content:", "; }
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    /* Columns table layout */
+    table.cols { width:100%; border-collapse: collapse; table-layout: fixed; }
+    table.cols th, table.cols td { vertical-align: top; }
+    table.cols .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    table.cols .pill { display:inline-block; padding:1px 8px; border-radius:999px; border:1px solid var(--border); font-size:12px; }
+    table.cols .pill.yes { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    table.cols .pill.no  { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    table.cols col.col-name { width: 22%; }
+    table.cols col.col-type { width: 18%; }
+    table.cols col.col-null { width: 12%; }
+    table.cols col.col-desc { width: 28%; }
+    table.cols col.col-lineage { width: 20%; }
+    .desc { overflow-wrap:anywhere; white-space: normal; }
+    /* Lineage chips */
+    .lin-wrap { display:flex; flex-wrap:wrap; gap:6px 10px; }
+    .lineage-item { display:inline-flex; gap:6px; align-items:center; background: rgba(127,127,127,.06); padding:2px 8px; border-radius:10px; margin-bottom:4px; }
+    .badge-direct { background:#eef7ff; color:#0a3a77; border:1px solid #bcd8fb; border-radius:999px; padding:1px 8px; font-size:12px; }
+    .badge-transformed { background:#fff7e8; color:#7a4a00; border:1px solid #f6db9b; border-radius:999px; padding:1px 8px; font-size:12px; }
+  </style>
+</head>
+<body>
+  <p><a href="index.html">← Back to overview</a></p>
+
+  <header style="display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px;">
+    <div>
+      <h1 style="margin:0 0 6px 0; font-size:1.25rem;">
+        users.ff
+        <span class="badge badge-table">table</span>
+      </h1>
+      <div class="muted">Model Detail • FastFlowTransform</div>
+    </div>
+    <span class="chip sql">sql</span>
+  </header>
+
+  <div class="row">
+    
+    <section class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
+      <div class="kv">
+        <div class="muted">Materialized</div>
+        <div><span class="badge badge-table">table</span></div>
+
+        <div class="muted">Relation</div>
+        <div><code>users</code></div>
+
+        <div class="muted">Path</div>
+        <div>
+          <code id="path">/Users/markolekic/Dev/FlowForge/fastflowtransform/examples/env_matrix/models/users.ff.sql</code>
+          <button class="btn" id="copyPath" style="margin-left:8px;">Copy</button>
+        </div>
+
+        <div class="muted">Dependencies</div>
+        <div>
+          
+            <span class="muted">–</span>
+          
+        </div>
+
+        
+      </div>
+    </section>
+
+    
+
+    
+    <section class="card">
+      <h2>Columns</h2>
+      <table class="cols">
+        <colgroup>
+          <col class="col-name" />
+          <col class="col-type" />
+          <col class="col-null" />
+          <col class="col-desc" />
+          <col class="col-lineage" />
+        </colgroup>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Nullable</th>
+            <th>Description</th>
+            <th>Lineage</th>
+          </tr>
+        </thead>
+        <tbody>
+          
+          <tr>
+            <td class="mono"><code>id</code></td>
+            <td class="mono"><code>BIGINT</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                
+                  <span class="mono"><code>?.id</code></span>
+                  
+                    <span class="badge-direct">direct</span>
+                  
+                  
+                
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>email</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                
+                  <span class="mono"><code>?.email</code></span>
+                  
+                    <span class="badge-direct">direct</span>
+                  
+                  
+                
+              
+            </td>
+          </tr>
+          
+        </tbody>
+      </table>
+    </section>
+    
+
+    <aside class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
+      <ul style="margin:0 0 0 18px;">
+        <li>The relation is the physical table/view name (mapped via <code>relation_for</code>).</li>
+        <li><code>ref('...')</code> points to other models; <code>source()</code> points to seeds.</li>
+        <li>Python models accept DataFrames (single dependency → DataFrame, more than one → dict of relation to DataFrame).</li>
+      </ul>
+    </aside>
+  </div>
+
+  <script>
+    const btn = document.getElementById('copyPath');
+    btn?.addEventListener('click', async () => {
+      const p = document.getElementById('path')?.textContent ?? '';
+      try {
+        await navigator.clipboard.writeText(p.trim());
+        btn.textContent = 'Copied ✓';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      } catch(e) {
+        btn.textContent = 'Copy failed';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/env_matrix/sources.yml b/examples/env_matrix/sources.yml
new file mode 100644
index 0000000..cac9e94
--- /dev/null
+++ b/examples/env_matrix/sources.yml
@@ -0,0 +1,14 @@
+version: 2
+
+sources:
+  - name: raw
+    schema: raw
+    tables:
+      - name: seed_users
+        identifier: seed_users
+        overrides:
+          postgres:
+            schema: main
+          databricks_spark:
+            format: delta
+            location: "/mnt/delta/raw/seed_users"
diff --git a/examples/events_users_duckdb/.fastflowtransform/cache/dev-duckdb.json b/examples/events_users_duckdb/.fastflowtransform/cache/dev-duckdb.json
new file mode 100644
index 0000000..8319263
--- /dev/null
+++ b/examples/events_users_duckdb/.fastflowtransform/cache/dev-duckdb.json
@@ -0,0 +1,10 @@
+{
+  "engine": "duckdb",
+  "entries": {
+    "fct_events_inc.ff": "9b48a28e3100c719dedfe953a49ae7ba9b88a7f7d983a4a2dc7065cf0b7124d9",
+    "users.ff": "dbd191f9ad5ada230f5099832f5f8c91b4c905a7a800330d282ab854777c4622",
+    "users_enriched": "670800d172c85bb405ed1bab65ffc8e723fd98f442ebe64bd9c92e17fc19cb8f"
+  },
+  "profile": "dev",
+  "version": 1
+}
\ No newline at end of file
diff --git a/examples/events_users_duckdb/.fastflowtransform/target/catalog.json b/examples/events_users_duckdb/.fastflowtransform/target/catalog.json
new file mode 100644
index 0000000..10194f5
--- /dev/null
+++ b/examples/events_users_duckdb/.fastflowtransform/target/catalog.json
@@ -0,0 +1,70 @@
+{
+  "metadata": {
+    "generated_at": "2025-10-27T16:43:12+00:00",
+    "tool": "fastflowtransform"
+  },
+  "relations": {
+    "fct_events_inc": {
+      "columns": [
+        {
+          "dtype": "BIGINT",
+          "name": "event_id",
+          "nullable": true
+        },
+        {
+          "dtype": "BIGINT",
+          "name": "user_id",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "event_type",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "ingested_at",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "meta_json",
+          "nullable": true
+        }
+      ]
+    },
+    "users": {
+      "columns": [
+        {
+          "dtype": "BIGINT",
+          "name": "id",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "email",
+          "nullable": true
+        }
+      ]
+    },
+    "users_enriched": {
+      "columns": [
+        {
+          "dtype": "BIGINT",
+          "name": "id",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "email",
+          "nullable": true
+        },
+        {
+          "dtype": "BOOLEAN",
+          "name": "is_gmail",
+          "nullable": true
+        }
+      ]
+    }
+  }
+}
diff --git a/examples/events_users_duckdb/.fastflowtransform/target/manifest.json b/examples/events_users_duckdb/.fastflowtransform/target/manifest.json
new file mode 100644
index 0000000..0f84982
--- /dev/null
+++ b/examples/events_users_duckdb/.fastflowtransform/target/manifest.json
@@ -0,0 +1,45 @@
+{
+  "macros": {},
+  "metadata": {
+    "generated_at": "2025-10-27T16:43:12+00:00",
+    "tool": "fastflowtransform"
+  },
+  "nodes": {
+    "fct_events_inc.ff": {
+      "deps": [],
+      "kind": "sql",
+      "materialized": "incremental",
+      "name": "fct_events_inc.ff",
+      "path": "models/fct_events_inc.ff.sql",
+      "relation": "fct_events_inc"
+    },
+    "users.ff": {
+      "deps": [],
+      "kind": "sql",
+      "materialized": "table",
+      "name": "users.ff",
+      "path": "models/users.ff.sql",
+      "relation": "users"
+    },
+    "users_enriched": {
+      "deps": [
+        "users.ff"
+      ],
+      "kind": "python",
+      "materialized": "table",
+      "name": "users_enriched",
+      "path": "models/users_enriched.ff.py",
+      "relation": "users_enriched"
+    }
+  },
+  "sources": {
+    "app": {
+      "events": {
+        "identifier": "seed_events_initial"
+      },
+      "users": {
+        "identifier": "seed_users"
+      }
+    }
+  }
+}
diff --git a/examples/events_users_duckdb/.fastflowtransform/target/run_results.json b/examples/events_users_duckdb/.fastflowtransform/target/run_results.json
new file mode 100644
index 0000000..9a8cdd6
--- /dev/null
+++ b/examples/events_users_duckdb/.fastflowtransform/target/run_results.json
@@ -0,0 +1,34 @@
+{
+  "metadata": {
+    "generated_at": "2025-10-27T16:43:12+00:00",
+    "tool": "fastflowtransform"
+  },
+  "results": [
+    {
+      "duration_ms": 4,
+      "finished_at": "2025-10-27T16:43:12+00:00",
+      "message": null,
+      "name": "fct_events_inc.ff",
+      "started_at": "2025-10-27T16:43:12+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 1,
+      "finished_at": "2025-10-27T16:43:12+00:00",
+      "message": null,
+      "name": "users.ff",
+      "started_at": "2025-10-27T16:43:12+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 0,
+      "finished_at": "2025-10-27T16:43:12+00:00",
+      "message": null,
+      "name": "users_enriched",
+      "started_at": "2025-10-27T16:43:12+00:00",
+      "status": "success"
+    }
+  ],
+  "run_finished_at": "2025-10-27T16:43:12+00:00",
+  "run_started_at": "2025-10-27T16:43:12+00:00"
+}
diff --git a/examples/events_users_duckdb/Makefile b/examples/events_users_duckdb/Makefile
new file mode 100644
index 0000000..dec2227
--- /dev/null
+++ b/examples/events_users_duckdb/Makefile
@@ -0,0 +1,86 @@
+.PHONY: demo seed run dag test artifacts incr state-mod state-mod-plus res-error res-warn clean
+
+DB ?= .local/demo.duckdb
+PROJECT ?= .
+UV ?= uv
+
+# Detect OS opener (macOS: open, Linux: xdg-open)
+UNAME_S := $(shell uname -s)
+ifeq ($(UNAME_S),Darwin)
+	OPENER := open
+else
+	OPENER := xdg-open
+endif
+
+seed:
+	FF_ENGINE=duckdb FF_DUCKDB_PATH="$(DB)" $(UV) run fft seed "$(PROJECT)" --env dev
+
+run:
+	FF_ENGINE=duckdb FF_DUCKDB_PATH="$(DB)" $(UV) run fft run "$(PROJECT)" --env dev
+
+test:
+	FF_ENGINE=duckdb FF_DUCKDB_PATH="$(DB)" $(UV) run fft test "$(PROJECT)" --env dev
+
+dag:
+	FF_ENGINE=duckdb FF_DUCKDB_PATH="$(DB)" $(UV) run fft dag  "$(PROJECT)" --env dev --html
+
+artifacts:
+	@echo
+	@echo "== 📦 Artifacts =="
+	@echo "  $(PROJECT)/.fastflowtransform/target/{manifest.json,run_results.json,catalog.json}"
+	@echo "  DAG HTML: $(PROJECT)/site/dag/index.html"
+
+incr:
+	$(UV) run fft run "$(PROJECT)" --env dev --select fct_events_inc.ff --cache rw || true
+
+state-mod:
+	@if [ -f "$(PROJECT)/models/users.ff.sql" ]; then touch "$(PROJECT)/models/users.ff.sql"; fi
+	FF_ENGINE=duckdb $(UV) run fft run "$(PROJECT)" --env dev --cache rw --select state:modified
+
+state-mod-plus:
+	FF_ENGINE=duckdb $(UV) run fft run "$(PROJECT)" --env dev --cache rw --select state:modified+
+
+res-error:
+	FF_ENGINE=duckdb $(UV) run fft run "$(PROJECT)" --env dev --select result:error || true
+
+res-warn:
+	FF_ENGINE=duckdb $(UV) run fft run "$(PROJECT)" --env dev --select result:warn  || true
+
+pg-seed:
+	FF_ENGINE=postgres FF_PG_DSN="$(FF_PG_DSN)" FF_PG_SCHEMA="$(FF_PG_SCHEMA)" $(UV) run fft seed "$(PROJECT)" --env stg
+
+pg-run:
+	FF_ENGINE=postgres FF_PG_DSN="$(FF_PG_DSN)" FF_PG_SCHEMA="$(FF_PG_SCHEMA)" $(UV) run fft run  "$(PROJECT)" --env stg
+
+clean:
+	rm -rf .local "$(PROJECT)/docs" dist build *.egg-info .fastflowtransform
+
+demo-open:
+	@if [ -f "$(PROJECT)/site/dag/index.html" ]; then \
+		$(OPENER) "$(PROJECT)/site/dag/index.html" 2>/dev/null || echo "Open manually at: $(PROJECT)/site/dag/index.html"; \
+	else \
+		echo "No HTML found: $(PROJECT)/site/dag/index.html"; \
+	fi
+
+demo: clean
+	@echo "== 🚀 R1 Demo (DuckDB) =="
+	@echo "DB=$(DB)  PROJECT=$(PROJECT)"
+	+$(MAKE) seed
+	+$(MAKE) run
+	+$(MAKE) dag
+	+$(MAKE) test
+	+$(MAKE) artifacts
+	@echo
+	@echo "== 🔁 Incremental Model =="
+	+$(MAKE) incr
+	@echo
+	@echo "== 🧠 State Selection (changed only) =="
+	+$(MAKE) state-mod
+	+$(MAKE) state-mod-plus
+	@echo
+	@echo "== 🧪 Result Selection (from last run_results.json) =="
+	+$(MAKE) res-error
+	+$(MAKE) res-warn
+	@echo
+	@echo "✅ Demo done. Open DAG here: $(PROJECT)/site/dag/index.html"
+	+$(MAKE) demo-open
diff --git a/examples/events_users_duckdb/README.md b/examples/events_users_duckdb/README.md
new file mode 100644
index 0000000..6e079dd
--- /dev/null
+++ b/examples/events_users_duckdb/README.md
@@ -0,0 +1,50 @@
+# R1 Demo
+
+Minimal project showing:
+- Incremental model (`fct_events_inc.ff.sql`)
+- YAML tests (`models/users_enriched.yml`)
+- State selection (`state:modified`, `result:*`)
+
+## DuckDB (local)
+
+```bash
+make -C examples/r1_demo seed
+make -C examples/r1_demo run
+make -C examples/r1_demo dag
+````
+
+Incremental-only:
+
+```bash
+make -C examples/r1_demo inc
+```
+
+## Postgres (optional)
+
+Set `FF_PG_DSN` and `FF_PG_SCHEMA`, then:
+
+```bash
+make -C examples/r1_demo pg-seed
+make -C examples/r1_demo pg-run
+```
+
+## Expected Artifacts
+
+```
+examples/r1_demo/.fastflowtransform/target/
+├── manifest.json
+├── run_results.json
+└── catalog.json
+```
+
+## Sample Output (excerpt)
+
+```
+✔ L00 [DUCK] users.ff (120ms)
+✔ L01 [DUCK] users_enriched (35ms)
+✔ L01 [DUCK] fct_events_inc.ff (41ms)
+
+Data Quality Summary
+────────────────────
+✅ not_null           users.email                        (2ms)
+❕ accepted_values    users_enriched.email               (1ms)
\ No newline at end of file
diff --git a/examples/events_users_duckdb/models/fct_events_inc.ff.sql b/examples/events_users_duckdb/models/fct_events_inc.ff.sql
new file mode 100644
index 0000000..02916fb
--- /dev/null
+++ b/examples/events_users_duckdb/models/fct_events_inc.ff.sql
@@ -0,0 +1,24 @@
+{{ config(
+  materialized='incremental',
+  unique_key=['event_id'],
+  on_schema_change='append_new_columns',
+  tags=['fact','incremental']
+) }}
+with base as (
+  select *
+  from {{ source('app','events') }}
+  {% if is_incremental() %}
+    where cast(ingested_at as timestamp)
+         > coalesce(
+             (select max(cast(ingested_at as timestamp)) from {{ this }}),
+             timestamp '1970-01-01'
+           )
+  {% endif %}
+)
+select
+  event_id,
+  user_id,
+  event_type,
+  ingested_at,
+  meta_json
+from base;
\ No newline at end of file
diff --git a/examples/events_users_duckdb/models/users.ff.sql b/examples/events_users_duckdb/models/users.ff.sql
new file mode 100644
index 0000000..5283037
--- /dev/null
+++ b/examples/events_users_duckdb/models/users.ff.sql
@@ -0,0 +1,3 @@
+{{ config(materialized='table', tags=['staging']) }}
+select id, email
+from {{ source('app','users') }};
\ No newline at end of file
diff --git a/examples/events_users_duckdb/models/users_enriched.ff.py b/examples/events_users_duckdb/models/users_enriched.ff.py
new file mode 100644
index 0000000..383e3fc
--- /dev/null
+++ b/examples/events_users_duckdb/models/users_enriched.ff.py
@@ -0,0 +1,13 @@
+from fastflowtransform import model
+import pandas as pd
+
+
+@model(
+    name="users_enriched",
+    deps=["users.ff"],
+    require={"users": {"id", "email"}},
+)
+def enrich(df: pd.DataFrame) -> pd.DataFrame:
+    out = df.copy()
+    out["is_gmail"] = out["email"].str.endswith("@gmail.com")
+    return out
diff --git a/examples/events_users_duckdb/models/users_enriched.yml b/examples/events_users_duckdb/models/users_enriched.yml
new file mode 100644
index 0000000..a113bbe
--- /dev/null
+++ b/examples/events_users_duckdb/models/users_enriched.yml
@@ -0,0 +1,15 @@
+version: 2
+models:
+  - name: users_enriched
+    description: "Adds gmail flag"
+    columns:
+      - name: id
+        tests:
+          - not_null: { severity: error }
+          - unique
+      - name: email
+        tests:
+          - not_null
+          - accepted_values:
+              values: ["a@example.com","b@gmail.com","c@gmail.com"]
+              severity: warn
\ No newline at end of file
diff --git a/examples/events_users_duckdb/profiles.yml b/examples/events_users_duckdb/profiles.yml
new file mode 100644
index 0000000..50de7b1
--- /dev/null
+++ b/examples/events_users_duckdb/profiles.yml
@@ -0,0 +1,10 @@
+dev:
+  engine: duckdb
+  duckdb:
+    path: .local/demo.duckdb
+
+stg:
+  engine: postgres
+  postgres:
+    dsn: postgresql+psycopg://postgres:postgres@localhost:5432/ffdb
+    db_schema: public
\ No newline at end of file
diff --git a/examples/events_users_duckdb/project.yml b/examples/events_users_duckdb/project.yml
new file mode 100644
index 0000000..99a4f07
--- /dev/null
+++ b/examples/events_users_duckdb/project.yml
@@ -0,0 +1,8 @@
+vars:
+  run_date: "2025-01-01"
+
+tests:
+  - type: not_null
+    table: users
+    column: email
+    tags: [batch]
\ No newline at end of file
diff --git a/examples/events_users_duckdb/seeds/seed_events_initial.csv b/examples/events_users_duckdb/seeds/seed_events_initial.csv
new file mode 100644
index 0000000..87c320f
--- /dev/null
+++ b/examples/events_users_duckdb/seeds/seed_events_initial.csv
@@ -0,0 +1,3 @@
+event_id,user_id,event_type,ingested_at,meta_json
+100,1,signup,2025-01-01T00:00:00Z,"{}"
+101,2,purchase,2025-01-01T00:05:00Z,"{}"
\ No newline at end of file
diff --git a/examples/events_users_duckdb/seeds/seed_users.csv b/examples/events_users_duckdb/seeds/seed_users.csv
new file mode 100644
index 0000000..f423042
--- /dev/null
+++ b/examples/events_users_duckdb/seeds/seed_users.csv
@@ -0,0 +1,4 @@
+id,email
+1,a@example.com
+2,b@gmail.com
+3,c@gmail.com
\ No newline at end of file
diff --git a/examples/events_users_duckdb/site/dag/fct_events_inc.ff.html b/examples/events_users_duckdb/site/dag/fct_events_inc.ff.html
new file mode 100644
index 0000000..bb2b563
--- /dev/null
+++ b/examples/events_users_duckdb/site/dag/fct_events_inc.ff.html
@@ -0,0 +1,262 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>fct_events_inc.ff – FastFlowTransform</title>
+  <style>
+    :root {
+      --bg:#ffffff; --fg:#0f172a; --muted:#6b7280; --card:#ffffff; --border:#e5e7eb;
+      --chip-sql-bg:#e8f1ff; --chip-sql-fg:#0a1f44;
+      --chip-py-bg:#e9fbf1;  --chip-py-fg:#0b2e1f;
+      --accent:#2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg:#0b0f1a; --fg:#e5e7eb; --muted:#94a3b8; --card:#111827; --border:#1f2937;
+        --chip-sql-bg:#0e1a2c; --chip-sql-fg:#93c5fd;
+        --chip-py-bg:#0f1f15;  --chip-py-fg:#86efac;
+        --accent:#60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .muted { color: var(--muted); }
+    .card { border:1px solid var(--border); background:var(--card); border-radius:14px; padding:16px; }
+    .row { display:grid; gap:16px; grid-template-columns: 1fr; }
+    @media (min-width: 900px) { .row { grid-template-columns: 2fr 1fr; } }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .kv { display:grid; grid-template-columns: 140px 1fr; gap:8px 12px; align-items:start; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .btn { border:1px solid var(--border); background: var(--card); color: var(--fg);
+           padding:6px 10px; border-radius:10px; cursor:pointer; }
+    .btn:hover { border-color: var(--accent); }
+    ul.inline { list-style:none; padding:0; margin:0; }
+    ul.inline li { display:inline; }
+    ul.inline li+li::before { content:", "; }
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    /* Columns table layout */
+    table.cols { width:100%; border-collapse: collapse; table-layout: fixed; }
+    table.cols th, table.cols td { vertical-align: top; }
+    table.cols .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    table.cols .pill { display:inline-block; padding:1px 8px; border-radius:999px; border:1px solid var(--border); font-size:12px; }
+    table.cols .pill.yes { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    table.cols .pill.no  { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    table.cols col.col-name { width: 22%; }
+    table.cols col.col-type { width: 18%; }
+    table.cols col.col-null { width: 12%; }
+    table.cols col.col-desc { width: 28%; }
+    table.cols col.col-lineage { width: 20%; }
+    .desc { overflow-wrap:anywhere; white-space: normal; }
+    /* Lineage chips */
+    .lin-wrap { display:flex; flex-wrap:wrap; gap:6px 10px; }
+    .lineage-item { display:inline-flex; gap:6px; align-items:center; background: rgba(127,127,127,.06); padding:2px 8px; border-radius:10px; margin-bottom:4px; }
+    .badge-direct { background:#eef7ff; color:#0a3a77; border:1px solid #bcd8fb; border-radius:999px; padding:1px 8px; font-size:12px; }
+    .badge-transformed { background:#fff7e8; color:#7a4a00; border:1px solid #f6db9b; border-radius:999px; padding:1px 8px; font-size:12px; }
+  </style>
+</head>
+<body>
+  <p><a href="index.html">← Back to overview</a></p>
+
+  <header style="display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px;">
+    <div>
+      <h1 style="margin:0 0 6px 0; font-size:1.25rem;">
+        fct_events_inc.ff
+        <span class="badge badge-incremental">incremental</span>
+      </h1>
+      <div class="muted">Model Detail • FastFlowTransform</div>
+    </div>
+    <span class="chip sql">sql</span>
+  </header>
+
+  <div class="row">
+    
+    <section class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
+      <div class="kv">
+        <div class="muted">Materialized</div>
+        <div><span class="badge badge-incremental">incremental</span></div>
+
+        <div class="muted">Relation</div>
+        <div><code>fct_events_inc</code></div>
+
+        <div class="muted">Path</div>
+        <div>
+          <code id="path">/Users/markolekic/Dev/FlowForge/fastflowtransform/examples/events_users_duckdb/models/fct_events_inc.ff.sql</code>
+          <button class="btn" id="copyPath" style="margin-left:8px;">Copy</button>
+        </div>
+
+        <div class="muted">Dependencies</div>
+        <div>
+          
+            <span class="muted">–</span>
+          
+        </div>
+
+        
+      </div>
+    </section>
+
+    
+
+    
+    <section class="card">
+      <h2>Columns</h2>
+      <table class="cols">
+        <colgroup>
+          <col class="col-name" />
+          <col class="col-type" />
+          <col class="col-null" />
+          <col class="col-desc" />
+          <col class="col-lineage" />
+        </colgroup>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Nullable</th>
+            <th>Description</th>
+            <th>Lineage</th>
+          </tr>
+        </thead>
+        <tbody>
+          
+          <tr>
+            <td class="mono"><code>event_id</code></td>
+            <td class="mono"><code>BIGINT</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>user_id</code></td>
+            <td class="mono"><code>BIGINT</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>event_type</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>ingested_at</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>meta_json</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+        </tbody>
+      </table>
+    </section>
+    
+
+    <aside class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
+      <ul style="margin:0 0 0 18px;">
+        <li>The relation is the physical table/view name (mapped via <code>relation_for</code>).</li>
+        <li><code>ref('...')</code> points to other models; <code>source()</code> points to seeds.</li>
+        <li>Python models accept DataFrames (single dependency → DataFrame, more than one → dict of relation to DataFrame).</li>
+      </ul>
+    </aside>
+  </div>
+
+  <script>
+    const btn = document.getElementById('copyPath');
+    btn?.addEventListener('click', async () => {
+      const p = document.getElementById('path')?.textContent ?? '';
+      try {
+        await navigator.clipboard.writeText(p.trim());
+        btn.textContent = 'Copied ✓';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      } catch(e) {
+        btn.textContent = 'Copy failed';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/events_users_duckdb/site/dag/index.html b/examples/events_users_duckdb/site/dag/index.html
new file mode 100644
index 0000000..e438d5a
--- /dev/null
+++ b/examples/events_users_duckdb/site/dag/index.html
@@ -0,0 +1,247 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1"/>
+  <title>FastFlowTransform - DAG & Mini Docs</title>
+
+  <script type="module">
+    import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
+    const prefersDark = window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches;
+    mermaid.initialize({
+      startOnLoad: true,
+      securityLevel: "loose",
+      theme: prefersDark ? "dark" : "default"
+    });
+  </script>
+
+  <style>
+    :root {
+      --bg: #ffffff;
+      --fg: #0f172a;
+      --muted: #6b7280;
+      --card: #ffffff;
+      --border: #e5e7eb;
+      --chip-sql-bg: #e8f1ff;  --chip-sql-fg: #0a1f44;
+      --chip-py-bg:  #e9fbf1;  --chip-py-fg:  #0b2e1f;
+      --accent: #2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #0b0f1a;
+        --fg: #e5e7eb;
+        --muted: #94a3b8;
+        --card: #111827;
+        --border: #1f2937;
+        --chip-sql-bg: #0e1a2c;  --chip-sql-fg: #93c5fd;
+        --chip-py-bg:  #0f1f15;  --chip-py-fg:  #86efac;
+        --accent: #60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    header { display:flex; align-items:center; justify-content:space-between; gap:16px; margin-bottom: 20px; }
+    h1 { font-size: 1.25rem; margin: 0; }
+    .muted { color: var(--muted); }
+
+    .toolbar { display:flex; gap:12px; align-items:center; flex-wrap:wrap; }
+    .input {
+      display:inline-flex; align-items:center; gap:8px;
+      border:1px solid var(--border); background: var(--card); color: var(--fg);
+      padding:8px 10px; border-radius:10px; min-width: 240px;
+    }
+    .btn {
+      border:1px solid var(--border); background: var(--card); color: var(--fg);
+      padding:8px 12px; border-radius:10px; cursor:pointer;
+    }
+    .btn:hover { border-color: var(--accent); }
+
+    .grid { display:grid; gap:24px; grid-template-columns: 2fr 1fr; }
+    @media (max-width: 1100px) { .grid { grid-template-columns: 1fr; } }
+
+    .card { border:1px solid var(--border); background: var(--card); border-radius:14px; padding:16px; }
+    .card h2 { margin:0 0 12px 0; font-size:1rem; }
+
+    .mermaid { overflow:auto; border-radius:12px; }
+    .legend { display:flex; gap:8px; align-items:center; margin-bottom:10px; flex-wrap:wrap; }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    .badge-sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .badge-py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .subline { display:block; margin-top:2px; font-size:12px; color: var(--muted); line-height:1.35; }
+    .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+
+    table { width:100%; border-collapse: collapse; }
+    th, td { padding:8px 10px; border-bottom:1px solid var(--border); text-align:left; font-size:13px; }
+    th { background: rgba(127,127,127,.06); }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .nowrap { white-space: nowrap; }
+  </style>
+</head>
+<body>
+
+  <header>
+    <div>
+      <h1>FastFlowTransform - DAG & Mini Docs</h1>
+      <div class="muted">Mermaid renders automatically (light/dark)</div>
+    </div>
+    <div class="toolbar">
+      <label class="input">
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none"><path d="M21 21l-4.3-4.3M10.5 18a7.5 7.5 0 1 1 0-15 7.5 7.5 0 0 1 0 15Z" stroke="currentColor" stroke-width="2"/></svg>
+        <input id="filter" type="search" placeholder="Filter models…" style="border:0; outline:0; background:transparent; color:inherit; width: 220px;">
+      </label>
+      <button id="copyBtn" class="btn" title="Copy Mermaid source">Copy Mermaid</button>
+    </div>
+  </header>
+
+  <div class="grid">
+    <section class="card">
+      <h2>DAG</h2>
+      <div class="legend">
+        <span class="chip sql">SQL</span>
+        <span class="chip py">Python</span>
+        <span class="muted">•</span>
+        <strong>Materialization:</strong>
+        
+          <span class="badge badge-table">table</span>
+        
+          <span class="badge badge-view">view</span>
+        
+          <span class="badge badge-ephemeral">ephemeral</span>
+        
+          <span class="badge badge-incremental">incremental</span>
+        
+      </div>
+      <div class="mermaid" id="dag">flowchart TD
+  classDef sql fill:#e8f1ff,stroke:#5b8def,color:#0a1f44;
+  classDef py  fill:#e9fbf1,stroke:#2bb673,color:#0b2e1f;
+  fct_events_inc_ff["fct_events_inc.ff<br/>(fct_events_inc)"]
+  class fct_events_inc_ff sql;
+  users_ff["users.ff<br/>(users)"]
+  class users_ff sql;
+  users_enriched("users_enriched<br/>(users_enriched)")
+  class users_enriched py;
+  users_ff --> users_enriched
+</div>
+    </section>
+
+    <aside class="card">
+      <h2>Models</h2>
+      <table id="models">
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Relation</th>
+            <th>Deps</th>
+            <th>Materialized</th>
+          </tr>
+        </thead>
+        <tbody>
+        
+          <tr>
+            <td class="nowrap">
+              
+              <a href="fct_events_inc.ff.html"
+                 title="fct_events_inc.ff">
+                fct_events_inc.ff
+              </a>
+              
+            </td>
+            <td><span class="chip sql">sql</span></td>
+            <td><code>fct_events_inc</code></td>
+            <td class="muted">–</td>
+            <td>
+              <span class="badge badge-incremental">
+                incremental
+              </span>
+            </td>
+          </tr>
+        
+          <tr>
+            <td class="nowrap">
+              
+              <a href="users.ff.html"
+                 title="users.ff">
+                users.ff
+              </a>
+              
+            </td>
+            <td><span class="chip sql">sql</span></td>
+            <td><code>users</code></td>
+            <td class="muted">–</td>
+            <td>
+              <span class="badge badge-table">
+                table
+              </span>
+            </td>
+          </tr>
+        
+          <tr>
+            <td class="nowrap">
+              
+              <a href="users_enriched.html"
+                 title="users_enriched">
+                users_enriched
+              </a>
+              
+            </td>
+            <td><span class="chip py">python</span></td>
+            <td><code>users_enriched</code></td>
+            <td class="muted">users.ff</td>
+            <td>
+              <span class="badge badge-table">
+                table
+              </span>
+            </td>
+          </tr>
+        
+        </tbody>
+      </table>
+    </aside>
+
+    <section class="card">
+      <h2>Macros</h2>
+      
+        <p>No macros found.</p>
+      
+    </section>
+  </div>
+
+  <script>
+    // Table filter
+    const filter = document.getElementById('filter');
+    const rows = Array.from(document.querySelectorAll('#models tbody tr'));
+    filter?.addEventListener('input', () => {
+      const q = filter.value.trim().toLowerCase();
+      rows.forEach(tr => {
+        const text = tr.innerText.toLowerCase();
+        tr.style.display = text.includes(q) ? '' : 'none';
+      });
+    });
+
+    // Copy Mermaid
+    const copyBtn = document.getElementById('copyBtn');
+    copyBtn?.addEventListener('click', async () => {
+      try {
+        const src = document.getElementById('dag')?.textContent ?? '';
+        await navigator.clipboard.writeText(src.trim());
+        copyBtn.textContent = 'Copied ✓';
+        setTimeout(() => copyBtn.textContent = 'Copy Mermaid', 1200);
+      } catch(e) {
+        copyBtn.textContent = 'Copy failed';
+        setTimeout(() => copyBtn.textContent = 'Copy Mermaid', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/events_users_duckdb/site/dag/users.ff.html b/examples/events_users_duckdb/site/dag/users.ff.html
new file mode 100644
index 0000000..83e6158
--- /dev/null
+++ b/examples/events_users_duckdb/site/dag/users.ff.html
@@ -0,0 +1,223 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>users.ff – FastFlowTransform</title>
+  <style>
+    :root {
+      --bg:#ffffff; --fg:#0f172a; --muted:#6b7280; --card:#ffffff; --border:#e5e7eb;
+      --chip-sql-bg:#e8f1ff; --chip-sql-fg:#0a1f44;
+      --chip-py-bg:#e9fbf1;  --chip-py-fg:#0b2e1f;
+      --accent:#2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg:#0b0f1a; --fg:#e5e7eb; --muted:#94a3b8; --card:#111827; --border:#1f2937;
+        --chip-sql-bg:#0e1a2c; --chip-sql-fg:#93c5fd;
+        --chip-py-bg:#0f1f15;  --chip-py-fg:#86efac;
+        --accent:#60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .muted { color: var(--muted); }
+    .card { border:1px solid var(--border); background:var(--card); border-radius:14px; padding:16px; }
+    .row { display:grid; gap:16px; grid-template-columns: 1fr; }
+    @media (min-width: 900px) { .row { grid-template-columns: 2fr 1fr; } }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .kv { display:grid; grid-template-columns: 140px 1fr; gap:8px 12px; align-items:start; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .btn { border:1px solid var(--border); background: var(--card); color: var(--fg);
+           padding:6px 10px; border-radius:10px; cursor:pointer; }
+    .btn:hover { border-color: var(--accent); }
+    ul.inline { list-style:none; padding:0; margin:0; }
+    ul.inline li { display:inline; }
+    ul.inline li+li::before { content:", "; }
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    /* Columns table layout */
+    table.cols { width:100%; border-collapse: collapse; table-layout: fixed; }
+    table.cols th, table.cols td { vertical-align: top; }
+    table.cols .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    table.cols .pill { display:inline-block; padding:1px 8px; border-radius:999px; border:1px solid var(--border); font-size:12px; }
+    table.cols .pill.yes { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    table.cols .pill.no  { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    table.cols col.col-name { width: 22%; }
+    table.cols col.col-type { width: 18%; }
+    table.cols col.col-null { width: 12%; }
+    table.cols col.col-desc { width: 28%; }
+    table.cols col.col-lineage { width: 20%; }
+    .desc { overflow-wrap:anywhere; white-space: normal; }
+    /* Lineage chips */
+    .lin-wrap { display:flex; flex-wrap:wrap; gap:6px 10px; }
+    .lineage-item { display:inline-flex; gap:6px; align-items:center; background: rgba(127,127,127,.06); padding:2px 8px; border-radius:10px; margin-bottom:4px; }
+    .badge-direct { background:#eef7ff; color:#0a3a77; border:1px solid #bcd8fb; border-radius:999px; padding:1px 8px; font-size:12px; }
+    .badge-transformed { background:#fff7e8; color:#7a4a00; border:1px solid #f6db9b; border-radius:999px; padding:1px 8px; font-size:12px; }
+  </style>
+</head>
+<body>
+  <p><a href="index.html">← Back to overview</a></p>
+
+  <header style="display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px;">
+    <div>
+      <h1 style="margin:0 0 6px 0; font-size:1.25rem;">
+        users.ff
+        <span class="badge badge-table">table</span>
+      </h1>
+      <div class="muted">Model Detail • FastFlowTransform</div>
+    </div>
+    <span class="chip sql">sql</span>
+  </header>
+
+  <div class="row">
+    
+    <section class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
+      <div class="kv">
+        <div class="muted">Materialized</div>
+        <div><span class="badge badge-table">table</span></div>
+
+        <div class="muted">Relation</div>
+        <div><code>users</code></div>
+
+        <div class="muted">Path</div>
+        <div>
+          <code id="path">/Users/markolekic/Dev/FlowForge/fastflowtransform/examples/events_users_duckdb/models/users.ff.sql</code>
+          <button class="btn" id="copyPath" style="margin-left:8px;">Copy</button>
+        </div>
+
+        <div class="muted">Dependencies</div>
+        <div>
+          
+            <span class="muted">–</span>
+          
+        </div>
+
+        
+        <div class="muted">Referenced by</div>
+        <div>
+          <ul class="inline">
+            
+              <li><a href="users_enriched.html">users_enriched</a></li>
+            
+          </ul>
+        </div>
+        
+      </div>
+    </section>
+
+    
+
+    
+    <section class="card">
+      <h2>Columns</h2>
+      <table class="cols">
+        <colgroup>
+          <col class="col-name" />
+          <col class="col-type" />
+          <col class="col-null" />
+          <col class="col-desc" />
+          <col class="col-lineage" />
+        </colgroup>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Nullable</th>
+            <th>Description</th>
+            <th>Lineage</th>
+          </tr>
+        </thead>
+        <tbody>
+          
+          <tr>
+            <td class="mono"><code>id</code></td>
+            <td class="mono"><code>BIGINT</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                
+                  <span class="mono"><code>?.id</code></span>
+                  
+                    <span class="badge-direct">direct</span>
+                  
+                  
+                
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>email</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                
+                  <span class="mono"><code>?.email</code></span>
+                  
+                    <span class="badge-direct">direct</span>
+                  
+                  
+                
+              
+            </td>
+          </tr>
+          
+        </tbody>
+      </table>
+    </section>
+    
+
+    <aside class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
+      <ul style="margin:0 0 0 18px;">
+        <li>The relation is the physical table/view name (mapped via <code>relation_for</code>).</li>
+        <li><code>ref('...')</code> points to other models; <code>source()</code> points to seeds.</li>
+        <li>Python models accept DataFrames (single dependency → DataFrame, more than one → dict of relation to DataFrame).</li>
+      </ul>
+    </aside>
+  </div>
+
+  <script>
+    const btn = document.getElementById('copyPath');
+    btn?.addEventListener('click', async () => {
+      const p = document.getElementById('path')?.textContent ?? '';
+      try {
+        await navigator.clipboard.writeText(p.trim());
+        btn.textContent = 'Copied ✓';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      } catch(e) {
+        btn.textContent = 'Copy failed';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/events_users_duckdb/site/dag/users_enriched.html b/examples/events_users_duckdb/site/dag/users_enriched.html
new file mode 100644
index 0000000..8fca7e0
--- /dev/null
+++ b/examples/events_users_duckdb/site/dag/users_enriched.html
@@ -0,0 +1,232 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>users_enriched – FastFlowTransform</title>
+  <style>
+    :root {
+      --bg:#ffffff; --fg:#0f172a; --muted:#6b7280; --card:#ffffff; --border:#e5e7eb;
+      --chip-sql-bg:#e8f1ff; --chip-sql-fg:#0a1f44;
+      --chip-py-bg:#e9fbf1;  --chip-py-fg:#0b2e1f;
+      --accent:#2563eb;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg:#0b0f1a; --fg:#e5e7eb; --muted:#94a3b8; --card:#111827; --border:#1f2937;
+        --chip-sql-bg:#0e1a2c; --chip-sql-fg:#93c5fd;
+        --chip-py-bg:#0f1f15;  --chip-py-fg:#86efac;
+        --accent:#60a5fa;
+      }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 24px; background: var(--bg); color: var(--fg);
+           font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .muted { color: var(--muted); }
+    .card { border:1px solid var(--border); background:var(--card); border-radius:14px; padding:16px; }
+    .row { display:grid; gap:16px; grid-template-columns: 1fr; }
+    @media (min-width: 900px) { .row { grid-template-columns: 2fr 1fr; } }
+    .chip { font-size:12px; padding:2px 10px; border-radius:999px; border:1px solid var(--border); }
+    .chip.sql { background: var(--chip-sql-bg); color: var(--chip-sql-fg); }
+    .chip.py  { background: var(--chip-py-bg);  color: var(--chip-py-fg);  }
+    .kv { display:grid; grid-template-columns: 140px 1fr; gap:8px 12px; align-items:start; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    .btn { border:1px solid var(--border); background: var(--card); color: var(--fg);
+           padding:6px 10px; border-radius:10px; cursor:pointer; }
+    .btn:hover { border-color: var(--accent); }
+    ul.inline { list-style:none; padding:0; margin:0; }
+    ul.inline li { display:inline; }
+    ul.inline li+li::before { content:", "; }
+    .badge { font: 12px/1.6 system-ui, sans-serif; padding: 2px 8px; border-radius: 999px; border: 1px solid transparent; }
+    .badge-table { background:#eef7ff; color:#0a3a77; border-color:#bcd8fb; }
+    .badge-view { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    .badge-ephemeral { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    /* Columns table layout */
+    table.cols { width:100%; border-collapse: collapse; table-layout: fixed; }
+    table.cols th, table.cols td { vertical-align: top; }
+    table.cols .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; }
+    table.cols .pill { display:inline-block; padding:1px 8px; border-radius:999px; border:1px solid var(--border); font-size:12px; }
+    table.cols .pill.yes { background:#eefcf4; color:#0b5d2a; border-color:#bdebcf; }
+    table.cols .pill.no  { background:#fff7e8; color:#7a4a00; border-color:#f6db9b; }
+    table.cols col.col-name { width: 22%; }
+    table.cols col.col-type { width: 18%; }
+    table.cols col.col-null { width: 12%; }
+    table.cols col.col-desc { width: 28%; }
+    table.cols col.col-lineage { width: 20%; }
+    .desc { overflow-wrap:anywhere; white-space: normal; }
+    /* Lineage chips */
+    .lin-wrap { display:flex; flex-wrap:wrap; gap:6px 10px; }
+    .lineage-item { display:inline-flex; gap:6px; align-items:center; background: rgba(127,127,127,.06); padding:2px 8px; border-radius:10px; margin-bottom:4px; }
+    .badge-direct { background:#eef7ff; color:#0a3a77; border:1px solid #bcd8fb; border-radius:999px; padding:1px 8px; font-size:12px; }
+    .badge-transformed { background:#fff7e8; color:#7a4a00; border:1px solid #f6db9b; border-radius:999px; padding:1px 8px; font-size:12px; }
+  </style>
+</head>
+<body>
+  <p><a href="index.html">← Back to overview</a></p>
+
+  <header style="display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px;">
+    <div>
+      <h1 style="margin:0 0 6px 0; font-size:1.25rem;">
+        users_enriched
+        <span class="badge badge-table">table</span>
+      </h1>
+      <div class="muted">Model Detail • FastFlowTransform</div>
+    </div>
+    <span class="chip py">python</span>
+  </header>
+
+  <div class="row">
+    
+    <section class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
+      <div class="kv">
+        <div class="muted">Materialized</div>
+        <div><span class="badge badge-table">table</span></div>
+
+        <div class="muted">Relation</div>
+        <div><code>users_enriched</code></div>
+
+        <div class="muted">Path</div>
+        <div>
+          <code id="path">/Users/markolekic/Dev/FlowForge/fastflowtransform/examples/events_users_duckdb/models/users_enriched.ff.py</code>
+          <button class="btn" id="copyPath" style="margin-left:8px;">Copy</button>
+        </div>
+
+        <div class="muted">Dependencies</div>
+        <div>
+          
+            <ul class="inline">
+              
+                <li><a href="users.ff.html">users.ff</a></li>
+              
+            </ul>
+          
+        </div>
+
+        
+      </div>
+    </section>
+
+    
+
+    
+    <section class="card">
+      <h2>Columns</h2>
+      <table class="cols">
+        <colgroup>
+          <col class="col-name" />
+          <col class="col-type" />
+          <col class="col-null" />
+          <col class="col-desc" />
+          <col class="col-lineage" />
+        </colgroup>
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Nullable</th>
+            <th>Description</th>
+            <th>Lineage</th>
+          </tr>
+        </thead>
+        <tbody>
+          
+          <tr>
+            <td class="mono"><code>id</code></td>
+            <td class="mono"><code>BIGINT</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>email</code></td>
+            <td class="mono"><code>VARCHAR</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                <span class="muted">unknown</span>
+              
+            </td>
+          </tr>
+          
+          <tr>
+            <td class="mono"><code>is_gmail</code></td>
+            <td class="mono"><code>BOOLEAN</code></td>
+            <td>
+              
+                <span class="pill yes">yes</span>
+              
+            </td>
+            <td class="desc">
+              
+                —
+              
+            </td>
+            <td class="desc">
+              
+                
+                  <span class="mono"><code>?.email</code></span>
+                  
+                    <span class="badge-direct">direct</span>
+                  
+                  
+                
+              
+            </td>
+          </tr>
+          
+        </tbody>
+      </table>
+    </section>
+    
+
+    <aside class="card">
+      <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
+      <ul style="margin:0 0 0 18px;">
+        <li>The relation is the physical table/view name (mapped via <code>relation_for</code>).</li>
+        <li><code>ref('...')</code> points to other models; <code>source()</code> points to seeds.</li>
+        <li>Python models accept DataFrames (single dependency → DataFrame, more than one → dict of relation to DataFrame).</li>
+      </ul>
+    </aside>
+  </div>
+
+  <script>
+    const btn = document.getElementById('copyPath');
+    btn?.addEventListener('click', async () => {
+      const p = document.getElementById('path')?.textContent ?? '';
+      try {
+        await navigator.clipboard.writeText(p.trim());
+        btn.textContent = 'Copied ✓';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      } catch(e) {
+        btn.textContent = 'Copy failed';
+        setTimeout(() => btn.textContent = 'Copy', 1200);
+      }
+    });
+  </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/examples/events_users_duckdb/sources.yml b/examples/events_users_duckdb/sources.yml
new file mode 100644
index 0000000..296aa75
--- /dev/null
+++ b/examples/events_users_duckdb/sources.yml
@@ -0,0 +1,9 @@
+version: 2
+
+sources:
+  - name: app
+    tables:
+      - name: users
+        identifier: seed_users
+      - name: events
+        identifier: seed_events_initial
diff --git a/examples/postgres/.fastflowtransform/cache/stg-postgres.json b/examples/postgres/.fastflowtransform/cache/stg-postgres.json
index b1a6262..20a7672 100644
--- a/examples/postgres/.fastflowtransform/cache/stg-postgres.json
+++ b/examples/postgres/.fastflowtransform/cache/stg-postgres.json
@@ -1,11 +1,11 @@
 {
   "engine": "postgres",
   "entries": {
-    "mart_orders_enriched": "fc41294d6967cfcf3c9b7d2c5405210d9383e5538747f7f13bc16c96cc8754c5",
-    "mart_users.ff": "6a61e68266d9151e9c473340ee93ccb70146b0079371bae889e4c8313b40a8b8",
-    "orders.ff": "b45347dd5ad3adbf1637e637fb32e27b766995549c7b1ae4d9412a8ff1b0d375",
-    "users.ff": "68dbd147dcca21a36d04f031499eb8977a6fae8659873189b2a3169e560cb81e",
-    "users_enriched": "cf5157127bd1c72c6942a54049acd61ee8817782920534c274b4261783ceda4b"
+    "mart_orders_enriched": "6599c52b248c143c13a9cf4daaab3b646685f10ba50cd9477e62791b3ae3071b",
+    "mart_users.ff": "68aa5a370f7fc55b669f87134e7ceaf959d3ee4d5a563e75ae83392709b085ce",
+    "orders.ff": "351176593a9a5e231aa860af35e1dab4e3d7070cc25cfd13a49e415214051358",
+    "users.ff": "78ff9f7baa9b7b5617dbb3081fdb8a61d19a637ad6a8874862a91051b31ef646",
+    "users_enriched": "bbbee5bef3591988a2d6cb27fd561ac6d6f719f74dec668903e28e74e85fbd63"
   },
   "profile": "stg",
   "version": 1
diff --git a/examples/postgres/.fastflowtransform/target/catalog.json b/examples/postgres/.fastflowtransform/target/catalog.json
new file mode 100644
index 0000000..28dcb5f
--- /dev/null
+++ b/examples/postgres/.fastflowtransform/target/catalog.json
@@ -0,0 +1,23 @@
+{
+  "metadata": {
+    "generated_at": "2025-10-28T19:05:08+00:00",
+    "tool": "fastflowtransform"
+  },
+  "relations": {
+    "mart_orders_enriched": {
+      "columns": []
+    },
+    "mart_users": {
+      "columns": []
+    },
+    "orders": {
+      "columns": []
+    },
+    "users": {
+      "columns": []
+    },
+    "users_enriched": {
+      "columns": []
+    }
+  }
+}
diff --git a/examples/postgres/.fastflowtransform/target/manifest.json b/examples/postgres/.fastflowtransform/target/manifest.json
new file mode 100644
index 0000000..503cc94
--- /dev/null
+++ b/examples/postgres/.fastflowtransform/target/manifest.json
@@ -0,0 +1,88 @@
+{
+  "macros": {},
+  "metadata": {
+    "generated_at": "2025-10-28T19:05:08+00:00",
+    "tool": "fastflowtransform"
+  },
+  "nodes": {
+    "mart_orders_enriched": {
+      "deps": [
+        "orders.ff",
+        "users_enriched"
+      ],
+      "kind": "python",
+      "materialized": "table",
+      "name": "mart_orders_enriched",
+      "path": "models/mart_orders_enriched.ff.py",
+      "relation": "mart_orders_enriched"
+    },
+    "mart_users.ff": {
+      "deps": [
+        "users_enriched"
+      ],
+      "kind": "sql",
+      "materialized": "table",
+      "name": "mart_users.ff",
+      "path": "models/mart_users.ff.sql",
+      "relation": "mart_users"
+    },
+    "orders.ff": {
+      "deps": [],
+      "kind": "sql",
+      "materialized": "table",
+      "name": "orders.ff",
+      "path": "models/orders.ff.sql",
+      "relation": "orders"
+    },
+    "users.ff": {
+      "deps": [],
+      "kind": "sql",
+      "materialized": "table",
+      "name": "users.ff",
+      "path": "models/users.ff.sql",
+      "relation": "users"
+    },
+    "users_enriched": {
+      "deps": [
+        "users.ff"
+      ],
+      "kind": "python",
+      "materialized": "table",
+      "name": "users_enriched",
+      "path": "models/users_enrich.ff.py",
+      "relation": "users_enriched"
+    }
+  },
+  "sources": {
+    "crm": {
+      "orders": {
+        "base": {
+          "catalog": null,
+          "database": null,
+          "dataset": null,
+          "format": null,
+          "identifier": "seed_orders",
+          "location": null,
+          "options": {},
+          "project": null,
+          "schema": null
+        },
+        "overrides": {}
+      },
+      "users": {
+        "base": {
+          "catalog": null,
+          "database": null,
+          "dataset": null,
+          "format": null,
+          "identifier": "seed_users",
+          "location": null,
+          "options": {},
+          "project": null,
+          "schema": null
+        },
+        "overrides": {}
+      }
+    }
+  }
+}
diff --git a/examples/postgres/.fastflowtransform/target/run_results.json b/examples/postgres/.fastflowtransform/target/run_results.json
new file mode 100644
index 0000000..e1f3625
--- /dev/null
+++ b/examples/postgres/.fastflowtransform/target/run_results.json
@@ -0,0 +1,55 @@
+{
+  "metadata": {
+    "generated_at": "2025-10-28T19:05:08+00:00",
+    "tool": "fastflowtransform"
+  },
+  "results": [
+    {
+      "duration_ms": 0,
+      "finished_at": "2025-10-28T19:05:08+00:00",
+      "http": null,
+      "message": null,
+      "name": "mart_orders_enriched",
+      "started_at": "2025-10-28T19:05:08+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 0,
+      "finished_at": "2025-10-28T19:05:08+00:00",
+      "http": null,
+      "message": null,
+      "name": "mart_users.ff",
+      "started_at": "2025-10-28T19:05:08+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 0,
+      "finished_at": "2025-10-28T19:05:08+00:00",
+      "http": null,
+      "message": null,
+      "name": "orders.ff",
+      "started_at": "2025-10-28T19:05:08+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 0,
+      "finished_at": "2025-10-28T19:05:08+00:00",
+      "http": null,
+      "message": null,
+      "name": "users.ff",
+      "started_at": "2025-10-28T19:05:08+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 0,
+      "finished_at": "2025-10-28T19:05:08+00:00",
+      "http": null,
+      "message": null,
+      "name": "users_enriched",
+      "started_at": "2025-10-28T19:05:08+00:00",
+      "status": "success"
+    }
+  ],
+  "run_finished_at": "2025-10-28T19:05:08+00:00",
+  "run_started_at": "2025-10-28T19:05:08+00:00"
+}
diff --git a/examples/postgres/site/dag/index.html b/examples/postgres/site/dag/index.html
index 2aa6c49..25ed4ac 100644
--- a/examples/postgres/site/dag/index.html
+++ b/examples/postgres/site/dag/index.html
@@ -118,6 +118,8 @@ <h2>DAG</h2>
         
           <span class="badge badge-ephemeral">ephemeral</span>
         
+          <span class="badge badge-incremental">incremental</span>
+        
       </div>
       <div class="mermaid" id="dag">flowchart TD
   classDef sql fill:#e8f1ff,stroke:#5b8def,color:#0a1f44;
diff --git a/examples/postgres/sources.yml b/examples/postgres/sources.yml
index 398a587..5366a46 100644
--- a/examples/postgres/sources.yml
+++ b/examples/postgres/sources.yml
@@ -1,5 +1,9 @@
-crm:
-  users:
-    identifier: seed_users
-  orders:
-    identifier: seed_orders
+version: 2
+
+sources:
+  - name: crm
+    tables:
+      - name: users
+        identifier: seed_users
+      - name: orders
+        identifier: seed_orders
diff --git a/examples/simple_duckdb/.fastflowtransform/cache/dev-duckdb.json b/examples/simple_duckdb/.fastflowtransform/cache/dev-duckdb.json
index c745d0b..6826995 100644
--- a/examples/simple_duckdb/.fastflowtransform/cache/dev-duckdb.json
+++ b/examples/simple_duckdb/.fastflowtransform/cache/dev-duckdb.json
@@ -1,14 +1,14 @@
 {
   "engine": "duckdb",
   "entries": {
-    "ephemeral_ids.ff": "915b339016411eae1c33bf4a0d377ae9d95f55576dce9b137abb357907c4e40a",
-    "mart_orders_enriched": "6459daee02b149168dec749e8e78f61dccaa9b0c510dd1e6d1825502a778e03e",
-    "mart_users.ff": "2a06558561f91b8a6e9fe39edfb4c4abb5155d40ba62a0150485315b351fdde3",
-    "orders.ff": "dbd1c47c35fbf9f43f492262a365aa70cbc989df3dd35dcdfcba70c691da4133",
-    "users.ff": "2c9afcf9cc8abcbe4bf14edbe4f56b2e2efe634ef01d100e2e2aa4145110cbf5",
-    "users_enriched": "edb574dc070b5b698531fa8c002d199c01b3b8342571b2bef1d958c33066914f",
-    "v_users.ff": "9b736079070f114cd1dfd1305e4c3a0a59af45c16d8f746590f860104707ccc5",
-    "v_users_enriched.ff": "f50fed4d50fbf407a4c56a4d3a89cba9e040e0686c4fd09f37dfd7203f81aca5"
+    "ephemeral_ids.ff": "f36221b3fb6961430bffa420c97ed12a5ae2e9b92ec39acd18e74086814e4868",
+    "mart_orders_enriched": "5b99b9c7cafe7ce175c64eccecd245ef72cd40093a63c892b2e9fcedb64d6e6f",
+    "mart_users.ff": "14a922bedfa7d2eaa3b7f6a8a2e9fbc624d8a29a8d14689197b917540964a74d",
+    "orders.ff": "ffbbec879b95932afaead84df0b5bad425ced5068168d955faa29a3b49c24306",
+    "users.ff": "e16d945f4def7ce8bcb110ef25cca35c30626e4de80faf7d02aa39adaf4fe759",
+    "users_enriched": "8e9d55b46133f51e2eae0d68a2c3ae8a4c787b5e562279245309b64773f3b44b",
+    "v_users.ff": "4ecdbcaee200abfc46568a666aad308ca206120f1f9f55b15619ddc3683fd4d5",
+    "v_users_enriched.ff": "e92842ccc13ae2c0c2f1d84616bc6de8b382896eafbde178f9a986ab531a8dbc"
   },
   "profile": "dev",
   "version": 1
diff --git a/examples/simple_duckdb/.fastflowtransform/target/catalog.json b/examples/simple_duckdb/.fastflowtransform/target/catalog.json
new file mode 100644
index 0000000..75cbf5b
--- /dev/null
+++ b/examples/simple_duckdb/.fastflowtransform/target/catalog.json
@@ -0,0 +1,179 @@
+{
+  "metadata": {
+    "generated_at": "2025-10-28T19:05:02+00:00",
+    "tool": "fastflowtransform"
+  },
+  "relations": {
+    "ephemeral_ids": {
+      "columns": []
+    },
+    "mart_orders_enriched": {
+      "columns": [
+        {
+          "dtype": "BIGINT",
+          "name": "order_id",
+          "nullable": true
+        },
+        {
+          "dtype": "BIGINT",
+          "name": "user_id",
+          "nullable": true
+        },
+        {
+          "dtype": "DOUBLE",
+          "name": "amount",
+          "nullable": true
+        },
+        {
+          "dtype": "BIGINT",
+          "name": "id",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "email",
+          "nullable": true
+        },
+        {
+          "dtype": "TIMESTAMP",
+          "name": "signup_ts",
+          "nullable": true
+        },
+        {
+          "dtype": "BOOLEAN",
+          "name": "is_gmail",
+          "nullable": true
+        },
+        {
+          "dtype": "BOOLEAN",
+          "name": "valid_amt",
+          "nullable": true
+        }
+      ]
+    },
+    "mart_users": {
+      "columns": [
+        {
+          "dtype": "BIGINT",
+          "name": "id",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "email",
+          "nullable": true
+        },
+        {
+          "dtype": "BOOLEAN",
+          "name": "is_gmail",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "email_domain",
+          "nullable": true
+        }
+      ]
+    },
+    "orders": {
+      "columns": [
+        {
+          "dtype": "BIGINT",
+          "name": "order_id",
+          "nullable": true
+        },
+        {
+          "dtype": "BIGINT",
+          "name": "user_id",
+          "nullable": true
+        },
+        {
+          "dtype": "DOUBLE",
+          "name": "amount",
+          "nullable": true
+        }
+      ]
+    },
+    "users": {
+      "columns": [
+        {
+          "dtype": "BIGINT",
+          "name": "id",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "email",
+          "nullable": true
+        },
+        {
+          "dtype": "DATE",
+          "name": "signup_ts",
+          "nullable": true
+        }
+      ]
+    },
+    "users_enriched": {
+      "columns": [
+        {
+          "dtype": "BIGINT",
+          "name": "id",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "email",
+          "nullable": true
+        },
+        {
+          "dtype": "TIMESTAMP",
+          "name": "signup_ts",
+          "nullable": true
+        },
+        {
+          "dtype": "BOOLEAN",
+          "name": "is_gmail",
+          "nullable": true
+        }
+      ]
+    },
+    "v_users": {
+      "columns": [
+        {
+          "dtype": "BIGINT",
+          "name": "id",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "email",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "email_upper",
+          "nullable": true
+        }
+      ]
+    },
+    "v_users_enriched": {
+      "columns": [
+        {
+          "dtype": "BIGINT",
+          "name": "id",
+          "nullable": true
+        },
+        {
+          "dtype": "VARCHAR",
+          "name": "email",
+          "nullable": true
+        },
+        {
+          "dtype": "BOOLEAN",
+          "name": "is_gmail",
+          "nullable": true
+        }
+      ]
+    }
+  }
+}
diff --git a/examples/simple_duckdb/.fastflowtransform/target/manifest.json b/examples/simple_duckdb/.fastflowtransform/target/manifest.json
new file mode 100644
index 0000000..cfd2773
--- /dev/null
+++ b/examples/simple_duckdb/.fastflowtransform/target/manifest.json
@@ -0,0 +1,126 @@
+{
+  "macros": {
+    "nz": "models/macros/util.sql",
+    "on_or_before": "models/macros/util.sql",
+    "sql_email_domain": "models/macros_py/sql_helpers.py",
+    "upper_col": "models/macros/util.sql"
+  },
+  "metadata": {
+    "generated_at": "2025-10-28T19:05:02+00:00",
+    "tool": "fastflowtransform"
+  },
+  "nodes": {
+    "ephemeral_ids.ff": {
+      "deps": [
+        "users.ff"
+      ],
+      "kind": "sql",
+      "materialized": "ephemeral",
+      "name": "ephemeral_ids.ff",
+      "path": "models/ephemeral_ids.ff.sql",
+      "relation": "ephemeral_ids"
+    },
+    "mart_orders_enriched": {
+      "deps": [
+        "orders.ff",
+        "users_enriched"
+      ],
+      "kind": "python",
+      "materialized": "table",
+      "name": "mart_orders_enriched",
+      "path": "models/mart_orders_enriched.ff.py",
+      "relation": "mart_orders_enriched"
+    },
+    "mart_users.ff": {
+      "deps": [
+        "users_enriched"
+      ],
+      "kind": "sql",
+      "materialized": "table",
+      "name": "mart_users.ff",
+      "path": "models/mart_users.ff.sql",
+      "relation": "mart_users"
+    },
+    "orders.ff": {
+      "deps": [],
+      "kind": "sql",
+      "materialized": "table",
+      "name": "orders.ff",
+      "path": "models/orders.ff.sql",
+      "relation": "orders"
+    },
+    "users.ff": {
+      "deps": [],
+      "kind": "sql",
+      "materialized": "table",
+      "name": "users.ff",
+      "path": "models/users.ff.sql",
+      "relation": "users"
+    },
+    "users_enriched": {
+      "deps": [
+        "users.ff"
+      ],
+      "kind": "python",
+      "materialized": "table",
+      "name": "users_enriched",
+      "path": "models/users_enriched.ff.py",
+      "relation": "users_enriched"
+    },
+    "v_users.ff": {
+      "deps": [
+        "ephemeral_ids.ff",
+        "users.ff"
+      ],
+      "kind": "sql",
+      "materialized": "view",
+      "name": "v_users.ff",
+      "path": "models/v_users.ff.sql",
+      "relation": "v_users"
+    },
+    "v_users_enriched.ff": {
+      "deps": [
+        "users_enriched"
+      ],
+      "kind": "sql",
+      "materialized": "view",
+      "name": "v_users_enriched.ff",
+      "path": "models/v_users_enriched.ff.sql",
+      "relation": "v_users_enriched"
+    }
+  },
+  "sources": {
+    "crm": {
+      "users": {
+        "base": {
+          "catalog": null,
+          "database": null,
+          "dataset": null,
+          "format": null,
+          "identifier": "seed_users",
+          "location": null,
+          "options": {},
+          "project": null,
+          "schema": null
+        },
+        "overrides": {}
+      }
+    },
+    "erp": {
+      "orders": {
+        "base": {
+          "catalog": null,
+          "database": null,
+          "dataset": null,
+          "format": null,
+          "identifier": "seed_orders",
+          "location": null,
+          "options": {},
+          "project": null,
+          "schema": null
+        },
+        "overrides": {}
+      }
+    }
+  }
+}
diff --git a/examples/simple_duckdb/.fastflowtransform/target/run_results.json b/examples/simple_duckdb/.fastflowtransform/target/run_results.json
new file mode 100644
index 0000000..0f5c774
--- /dev/null
+++ b/examples/simple_duckdb/.fastflowtransform/target/run_results.json
@@ -0,0 +1,82 @@
+{
+  "metadata": {
+    "generated_at": "2025-10-28T19:05:02+00:00",
+    "tool": "fastflowtransform"
+  },
+  "results": [
+    {
+      "duration_ms": 0,
+      "finished_at": "2025-10-28T19:05:02+00:00",
+      "http": null,
+      "message": null,
+      "name": "ephemeral_ids.ff",
+      "started_at": "2025-10-28T19:05:02+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 1,
+      "finished_at": "2025-10-28T19:05:02+00:00",
+      "http": null,
+      "message": null,
+      "name": "mart_orders_enriched",
+      "started_at": "2025-10-28T19:05:02+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 1,
+      "finished_at": "2025-10-28T19:05:02+00:00",
+      "http": null,
+      "message": null,
+      "name": "mart_users.ff",
+      "started_at": "2025-10-28T19:05:02+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 4,
+      "finished_at": "2025-10-28T19:05:02+00:00",
+      "http": null,
+      "message": null,
+      "name": "orders.ff",
+      "started_at": "2025-10-28T19:05:02+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 1,
+      "finished_at": "2025-10-28T19:05:02+00:00",
+      "http": null,
+      "message": null,
+      "name": "users.ff",
+      "started_at": "2025-10-28T19:05:02+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 1,
+      "finished_at": "2025-10-28T19:05:02+00:00",
+      "http": null,
+      "message": null,
+      "name": "users_enriched",
+      "started_at": "2025-10-28T19:05:02+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 2,
+      "finished_at": "2025-10-28T19:05:02+00:00",
+      "http": null,
+      "message": null,
+      "name": "v_users.ff",
+      "started_at": "2025-10-28T19:05:02+00:00",
+      "status": "success"
+    },
+    {
+      "duration_ms": 2,
+      "finished_at": "2025-10-28T19:05:02+00:00",
+      "http": null,
+      "message": null,
+      "name": "v_users_enriched.ff",
+      "started_at": "2025-10-28T19:05:02+00:00",
+      "status": "success"
+    }
+  ],
+  "run_finished_at": "2025-10-28T19:05:02+00:00",
+  "run_started_at": "2025-10-28T19:05:02+00:00"
+}
diff --git a/examples/simple_duckdb/site/dag/index.html b/examples/simple_duckdb/site/dag/index.html
index feb098d..0402a3a 100644
--- a/examples/simple_duckdb/site/dag/index.html
+++ b/examples/simple_duckdb/site/dag/index.html
@@ -118,6 +118,8 @@ <h2>DAG</h2>
         
           <span class="badge badge-ephemeral">ephemeral</span>
         
+          <span class="badge badge-incremental">incremental</span>
+        
       </div>
       <div class="mermaid" id="dag">flowchart TD
   classDef sql fill:#e8f1ff,stroke:#5b8def,color:#0a1f44;
diff --git a/examples/simple_duckdb/site/dag/mart_orders_enriched.html b/examples/simple_duckdb/site/dag/mart_orders_enriched.html
index 1cf0946..135623b 100644
--- a/examples/simple_duckdb/site/dag/mart_orders_enriched.html
+++ b/examples/simple_duckdb/site/dag/mart_orders_enriched.html
@@ -114,197 +114,6 @@ <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
     
 
     
-    <section class="card">
-      <h2>Columns</h2>
-      <table class="cols">
-        <colgroup>
-          <col class="col-name" />
-          <col class="col-type" />
-          <col class="col-null" />
-          <col class="col-desc" />
-          <col class="col-lineage" />
-        </colgroup>
-        <thead>
-          <tr>
-            <th>Name</th>
-            <th>Type</th>
-            <th>Nullable</th>
-            <th>Description</th>
-            <th>Lineage</th>
-          </tr>
-        </thead>
-        <tbody>
-          
-          <tr>
-            <td class="mono"><code>order_id</code></td>
-            <td class="mono"><code>BIGINT</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                <span class="muted">unknown</span>
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>user_id</code></td>
-            <td class="mono"><code>BIGINT</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                <span class="muted">unknown</span>
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>amount</code></td>
-            <td class="mono"><code>DOUBLE</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                <span class="muted">unknown</span>
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>id</code></td>
-            <td class="mono"><code>BIGINT</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                <span class="muted">unknown</span>
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>email</code></td>
-            <td class="mono"><code>VARCHAR</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                <span class="muted">unknown</span>
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>signup_ts</code></td>
-            <td class="mono"><code>TIMESTAMP</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                <span class="muted">unknown</span>
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>is_gmail</code></td>
-            <td class="mono"><code>BOOLEAN</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                <span class="muted">unknown</span>
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>valid_amt</code></td>
-            <td class="mono"><code>BOOLEAN</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.amount</code></span>
-                  
-                    <span class="badge-transformed">transformed</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-        </tbody>
-      </table>
-    </section>
-    
 
     <aside class="card">
       <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
diff --git a/examples/simple_duckdb/site/dag/mart_users.ff.html b/examples/simple_duckdb/site/dag/mart_users.ff.html
index 96e6119..e05750f 100644
--- a/examples/simple_duckdb/site/dag/mart_users.ff.html
+++ b/examples/simple_duckdb/site/dag/mart_users.ff.html
@@ -112,135 +112,6 @@ <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
     
 
     
-    <section class="card">
-      <h2>Columns</h2>
-      <table class="cols">
-        <colgroup>
-          <col class="col-name" />
-          <col class="col-type" />
-          <col class="col-null" />
-          <col class="col-desc" />
-          <col class="col-lineage" />
-        </colgroup>
-        <thead>
-          <tr>
-            <th>Name</th>
-            <th>Type</th>
-            <th>Nullable</th>
-            <th>Description</th>
-            <th>Lineage</th>
-          </tr>
-        </thead>
-        <tbody>
-          
-          <tr>
-            <td class="mono"><code>id</code></td>
-            <td class="mono"><code>BIGINT</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.id</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>email</code></td>
-            <td class="mono"><code>VARCHAR</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.email</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>is_gmail</code></td>
-            <td class="mono"><code>BOOLEAN</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.is_gmail</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>email_domain</code></td>
-            <td class="mono"><code>VARCHAR</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.?</code></span>
-                  
-                    <span class="badge-transformed">transformed</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-        </tbody>
-      </table>
-    </section>
-    
 
     <aside class="card">
       <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
diff --git a/examples/simple_duckdb/site/dag/orders.ff.html b/examples/simple_duckdb/site/dag/orders.ff.html
index ea79885..b0d38ac 100644
--- a/examples/simple_duckdb/site/dag/orders.ff.html
+++ b/examples/simple_duckdb/site/dag/orders.ff.html
@@ -117,109 +117,6 @@ <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
     
 
     
-    <section class="card">
-      <h2>Columns</h2>
-      <table class="cols">
-        <colgroup>
-          <col class="col-name" />
-          <col class="col-type" />
-          <col class="col-null" />
-          <col class="col-desc" />
-          <col class="col-lineage" />
-        </colgroup>
-        <thead>
-          <tr>
-            <th>Name</th>
-            <th>Type</th>
-            <th>Nullable</th>
-            <th>Description</th>
-            <th>Lineage</th>
-          </tr>
-        </thead>
-        <tbody>
-          
-          <tr>
-            <td class="mono"><code>order_id</code></td>
-            <td class="mono"><code>BIGINT</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.order_id</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>user_id</code></td>
-            <td class="mono"><code>BIGINT</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.user_id</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>amount</code></td>
-            <td class="mono"><code>DOUBLE</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.amount</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-        </tbody>
-      </table>
-    </section>
-    
 
     <aside class="card">
       <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
diff --git a/examples/simple_duckdb/site/dag/users.ff.html b/examples/simple_duckdb/site/dag/users.ff.html
index 7f342a2..848fc92 100644
--- a/examples/simple_duckdb/site/dag/users.ff.html
+++ b/examples/simple_duckdb/site/dag/users.ff.html
@@ -132,109 +132,6 @@ <h2 style="margin:0 0 10px 0; font-size:1rem;">Description</h2>
     
 
     
-    <section class="card">
-      <h2>Columns</h2>
-      <table class="cols">
-        <colgroup>
-          <col class="col-name" />
-          <col class="col-type" />
-          <col class="col-null" />
-          <col class="col-desc" />
-          <col class="col-lineage" />
-        </colgroup>
-        <thead>
-          <tr>
-            <th>Name</th>
-            <th>Type</th>
-            <th>Nullable</th>
-            <th>Description</th>
-            <th>Lineage</th>
-          </tr>
-        </thead>
-        <tbody>
-          
-          <tr>
-            <td class="mono"><code>id</code></td>
-            <td class="mono"><code>BIGINT</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                <p>Primary key.</p>
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.id</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>email</code></td>
-            <td class="mono"><code>VARCHAR</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                <p>User email address.</p>
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.email</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>signup_ts</code></td>
-            <td class="mono"><code>DATE</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.?</code></span>
-                  
-                    <span class="badge-transformed">transformed</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-        </tbody>
-      </table>
-    </section>
-    
 
     <aside class="card">
       <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
diff --git a/examples/simple_duckdb/site/dag/users_enriched.html b/examples/simple_duckdb/site/dag/users_enriched.html
index 9ac8776..85888e3 100644
--- a/examples/simple_duckdb/site/dag/users_enriched.html
+++ b/examples/simple_duckdb/site/dag/users_enriched.html
@@ -136,117 +136,6 @@ <h2 style="margin:0 0 10px 0; font-size:1rem;">Description</h2>
     
 
     
-    <section class="card">
-      <h2>Columns</h2>
-      <table class="cols">
-        <colgroup>
-          <col class="col-name" />
-          <col class="col-type" />
-          <col class="col-null" />
-          <col class="col-desc" />
-          <col class="col-lineage" />
-        </colgroup>
-        <thead>
-          <tr>
-            <th>Name</th>
-            <th>Type</th>
-            <th>Nullable</th>
-            <th>Description</th>
-            <th>Lineage</th>
-          </tr>
-        </thead>
-        <tbody>
-          
-          <tr>
-            <td class="mono"><code>id</code></td>
-            <td class="mono"><code>BIGINT</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                <span class="muted">unknown</span>
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>email</code></td>
-            <td class="mono"><code>VARCHAR</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                <span class="muted">unknown</span>
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>signup_ts</code></td>
-            <td class="mono"><code>TIMESTAMP</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                <span class="muted">unknown</span>
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>is_gmail</code></td>
-            <td class="mono"><code>BOOLEAN</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                <p>True if email ends with @gmail.com</p>
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.email</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-        </tbody>
-      </table>
-    </section>
-    
 
     <aside class="card">
       <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
diff --git a/examples/simple_duckdb/site/dag/v_users.ff.html b/examples/simple_duckdb/site/dag/v_users.ff.html
index ba80e5f..8b54164 100644
--- a/examples/simple_duckdb/site/dag/v_users.ff.html
+++ b/examples/simple_duckdb/site/dag/v_users.ff.html
@@ -114,109 +114,6 @@ <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
     
 
     
-    <section class="card">
-      <h2>Columns</h2>
-      <table class="cols">
-        <colgroup>
-          <col class="col-name" />
-          <col class="col-type" />
-          <col class="col-null" />
-          <col class="col-desc" />
-          <col class="col-lineage" />
-        </colgroup>
-        <thead>
-          <tr>
-            <th>Name</th>
-            <th>Type</th>
-            <th>Nullable</th>
-            <th>Description</th>
-            <th>Lineage</th>
-          </tr>
-        </thead>
-        <tbody>
-          
-          <tr>
-            <td class="mono"><code>id</code></td>
-            <td class="mono"><code>BIGINT</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.id</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>email</code></td>
-            <td class="mono"><code>VARCHAR</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.email</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>email_upper</code></td>
-            <td class="mono"><code>VARCHAR</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.email</code></span>
-                  
-                    <span class="badge-transformed">transformed</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-        </tbody>
-      </table>
-    </section>
-    
 
     <aside class="card">
       <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
diff --git a/examples/simple_duckdb/site/dag/v_users_enriched.ff.html b/examples/simple_duckdb/site/dag/v_users_enriched.ff.html
index efd44b0..d25fc93 100644
--- a/examples/simple_duckdb/site/dag/v_users_enriched.ff.html
+++ b/examples/simple_duckdb/site/dag/v_users_enriched.ff.html
@@ -112,109 +112,6 @@ <h2 style="margin:0 0 10px 0; font-size:1rem;">Metadata</h2>
     
 
     
-    <section class="card">
-      <h2>Columns</h2>
-      <table class="cols">
-        <colgroup>
-          <col class="col-name" />
-          <col class="col-type" />
-          <col class="col-null" />
-          <col class="col-desc" />
-          <col class="col-lineage" />
-        </colgroup>
-        <thead>
-          <tr>
-            <th>Name</th>
-            <th>Type</th>
-            <th>Nullable</th>
-            <th>Description</th>
-            <th>Lineage</th>
-          </tr>
-        </thead>
-        <tbody>
-          
-          <tr>
-            <td class="mono"><code>id</code></td>
-            <td class="mono"><code>BIGINT</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.id</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>email</code></td>
-            <td class="mono"><code>VARCHAR</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.email</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-          <tr>
-            <td class="mono"><code>is_gmail</code></td>
-            <td class="mono"><code>BOOLEAN</code></td>
-            <td>
-              
-                <span class="pill yes">yes</span>
-              
-            </td>
-            <td class="desc">
-              
-                —
-              
-            </td>
-            <td class="desc">
-              
-                
-                  <span class="mono"><code>?.is_gmail</code></span>
-                  
-                    <span class="badge-direct">direct</span>
-                  
-                  
-                
-              
-            </td>
-          </tr>
-          
-        </tbody>
-      </table>
-    </section>
-    
 
     <aside class="card">
       <h2 style="margin:0 0 10px 0; font-size:1rem;">Tips</h2>
diff --git a/examples/simple_duckdb/sources.yml b/examples/simple_duckdb/sources.yml
index afd9772..40975cf 100644
--- a/examples/simple_duckdb/sources.yml
+++ b/examples/simple_duckdb/sources.yml
@@ -1,6 +1,11 @@
-crm:
-  users:
-    identifier: seed_users
-erp:
-  orders:
-    identifier: seed_orders
+version: 2
+
+sources:
+  - name: crm
+    tables:
+      - name: users
+        identifier: seed_users
+  - name: erp
+    tables:
+      - name: orders
+        identifier: seed_orders
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..33abcaf
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,58 @@
+site_name: FastFlowTransform
+site_description: Documentation for the FastFlowTransform project
+site_url: https://MirrorsAndMisdirections.github.io/FastFlowTransform/
+repo_url: https://github.com/MirrorsAndMisdirections/FastFlowTransform
+repo_name: MirrorsAndMisdirections/FastFlowTransform
+
+theme:
+  name: material
+  language: en
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.sections
+    - navigation.top
+    - content.code.copy
+    - search.suggest
+    - search.highlight
+  icon:
+    repo: fontawesome/brands/github
+  # Optional Branding (aktiviere bei Bedarf):
+  # logo: assets/logo.png
+  # favicon: assets/favicon.png
+  # palette:
+  #   - scheme: default
+  #     primary: indigo
+  #     accent: indigo
+
+nav:
+  - Home: index.md
+  - Technical Overview: Technical_Overview.md
+  - API & Models: Api_Models.md
+  - Configuration & Macros: Config_and_Macros.md
+  - Cache & Parallelism: Cache_and_Parallelism.md
+  - Incremental Processing: Incremental.md
+  - State Selection: State_Selection.md
+  - YAML Tests: YAML_Tests.md
+  - Examples:
+      - Environment Matrix: examples/Environment_Matrix.md
+
+markdown_extensions:
+  - admonition
+  - codehilite
+  - toc:
+      permalink: true
+  - pymdownx.superfences
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.magiclink
+
+plugins:
+  - search
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/MirrorsAndMisdirections
diff --git a/pyproject.toml b/pyproject.toml
index e858fee..c858a5d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,6 +36,7 @@ dependencies = [
   "snowflake>=1.8.0",
   "snowflake-snowpark-python>=1.40.0",
   "bigframes>=2.24.0",
+  "httpx>=0.28.1",
 ]
 
 [project.optional-dependencies]
@@ -46,6 +47,9 @@ dev = [
   "pre-commit==3.*",
   "pandas-stubs>=2.1",
   "types-PyYAML>=6.0.12",
+  "mkdocs>=1.6",
+  "mkdocs-material>=9.5",
+  "pymdown-extensions>=10.0",
 ]
 
 [project.urls]
@@ -95,7 +99,7 @@ known-third-party = ["duckdb", "pandas"]
 combine-as-imports = true
 
 [tool.ruff.lint.pylint]
-max-args = 12
+max-args = 15
 max-returns = 8
 max-branches = 20
 max-statements = 60
diff --git a/site/dag/dag.mmd b/site/dag/dag.mmd
deleted file mode 100644
index 9c48c4c..0000000
--- a/site/dag/dag.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-  classDef sql fill:#e8f1ff,stroke:#5b8def,color:#0a1f44;
-  classDef py  fill:#e9fbf1,stroke:#2bb673,color:#0b2e1f;
-  m_ff["m.ff<br/>(m)"]
-  class m_ff sql;
diff --git a/src/fastflowtransform/api/__init__.py b/src/fastflowtransform/api/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/fastflowtransform/api/context.py b/src/fastflowtransform/api/context.py
new file mode 100644
index 0000000..08937da
--- /dev/null
+++ b/src/fastflowtransform/api/context.py
@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import contextvars
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "_HttpStats",
+    "_clear_http_ctx",
+    "_get_http_ctx",
+    "record",
+    "reset_for_node",
+    "snapshot",
+]
+
+
+@dataclass
+class _HttpStats:
+    """
+    Per-context HTTP telemetry.
+
+    Attributes
+    ----------
+    node : Optional[str]
+        Current model/node name the HTTP calls belong to.
+    requests : int
+        Number of HTTP requests performed in this context.
+    cache_hits : int
+        Number of requests served from cache.
+    bytes : int
+        Total response bytes seen.
+    hashes : List[str]
+        Content hashes (deduplicated by consecutive repeats).
+    keys : List[str]
+        Stable IO keys (deduplicated by consecutive repeats).
+    used_offline : bool
+        True if at least one response was served from offline cache.
+    """
+
+    node: str | None = None
+    requests: int = 0
+    cache_hits: int = 0
+    bytes: int = 0
+    hashes: list[str] = field(default_factory=list)
+    keys: list[str] = field(default_factory=list)  # stable IO keys for debugging/FP
+    used_offline: bool = False
+
+    def reset_for_node(self, node_name: str) -> None:
+        """Reset statistics and set the current node name."""
+        self.node = node_name
+        self.requests = 0
+        self.cache_hits = 0
+        self.bytes = 0
+        self.hashes.clear()
+        self.keys.clear()
+        self.used_offline = False
+
+    def snapshot(self) -> dict[str, Any]:
+        """Return a plain dict snapshot of the current counters."""
+        return {
+            "node": self.node,
+            "requests": self.requests,
+            "cache_hits": self.cache_hits,
+            "bytes": self.bytes,
+            "used_offline": self.used_offline,
+            "content_hashes": list(self.hashes),
+            "keys": list(self.keys),
+        }
+
+
+_ctx: contextvars.ContextVar[_HttpStats | None] = contextvars.ContextVar(
+    "_ff_http_ctx", default=None
+)
+
+
+def _get_http_ctx() -> _HttpStats:
+    """
+    Return the per-context stats object, creating and storing it on first use.
+    Safe to call from any thread/task; each context gets its own instance.
+    """
+    ctx = _ctx.get()
+    if ctx is None:
+        ctx = _HttpStats()
+        _ctx.set(ctx)
+    return ctx
+
+
+def _clear_http_ctx() -> None:
+    """Clear the per-context stats instance (useful in tests)."""
+    _ctx.set(None)
+
+
+# ----- Module-level convenience wrappers (callable without touching the instance) -----
+
+
+def reset_for_node(node_name: str) -> None:
+    """
+    Reset the current context stats and set the node name.
+    Equivalent to: _get_http_ctx().reset_for_node(node_name)
+    """
+    _get_http_ctx().reset_for_node(node_name)
+
+
+def record(
+    io_key: str,
+    content_hash: str,
+    cache_hit: bool,
+    byte_len: int,
+    used_offline: bool,
+) -> None:
+    """
+    Record a single HTTP IO event into the current context.
+
+    Parameters
+    ----------
+    io_key : str
+        Stable IO cache key or identifier.
+    content_hash : str
+        Hash of the content (used for diagnostics).
+    cache_hit : bool
+        Whether the response came from cache.
+    byte_len : int
+        Number of response bytes (>= 0).
+    used_offline : bool
+        Whether the response was served in offline mode.
+    """
+    stats = _get_http_ctx()
+    stats.requests += 1
+    if cache_hit:
+        stats.cache_hits += 1
+    stats.bytes += int(byte_len or 0)
+
+    # Deduplicate consecutive repeats while preserving order.
+    if io_key and (not stats.keys or stats.keys[-1] != io_key):
+        stats.keys.append(io_key)
+    if content_hash and (not stats.hashes or stats.hashes[-1] != content_hash):
+        stats.hashes.append(content_hash)
+
+    stats.used_offline = bool(used_offline)
+
+
+def snapshot() -> dict[str, Any]:
+    """
+    Return a snapshot dict of the current context. If the context is not yet
+    initialized, return an empty/default snapshot instead of raising.
+    """
+    s = _ctx.get()
+    if s is None:
+        return {
+            "node": None,
+            "requests": 0,
+            "cache_hits": 0,
+            "bytes": 0,
+            "used_offline": False,
+            "content_hashes": [],
+            "keys": [],
+        }
+    return s.snapshot()
diff --git a/src/fastflowtransform/api/http.py b/src/fastflowtransform/api/http.py
new file mode 100644
index 0000000..c15ac46
--- /dev/null
+++ b/src/fastflowtransform/api/http.py
@@ -0,0 +1,358 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import random
+import time
+from collections.abc import Callable, Sequence
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+from urllib.parse import urlparse
+
+import httpx as _HTTP
+import pandas as pd
+
+from fastflowtransform.api import context as _ctx
+from fastflowtransform.api.rate_limit import init_rate_limiter
+
+# ---- Config via ENV (optional; sensible defaults) -----------------------
+_DEF_CACHE_DIR = os.getenv("FF_HTTP_CACHE_DIR", ".fastflowtransform/http_cache")
+_DEF_TTL = int(os.getenv("FF_HTTP_TTL", "0") or 0)  # seconds; 0 = no default TTL
+_DEF_TIMEOUT = float(os.getenv("FF_HTTP_TIMEOUT", "20"))
+_DEF_MAX_RETRIES = int(os.getenv("FF_HTTP_MAX_RETRIES", "3"))
+_DEF_RATE_RPS = float(os.getenv("FF_HTTP_RATE_LIMIT_RPS", "0") or 0)  # 0 = unlimited
+_OFFLINE = os.getenv("FF_HTTP_OFFLINE", "0").lower() in {"1", "true", "yes", "on"}
+_CACHE_MODE = (os.getenv("FF_HTTP_CACHE_MODE", "rw") or "rw").lower()  # "off" | "ro" | "rw"
+_CAP = max(_DEF_RATE_RPS, 1.0)
+_ALLOWED = {
+    d.strip().lower()
+    for d in (os.getenv("FF_HTTP_ALLOWED_DOMAINS", "") or "").split(",")
+    if d.strip()
+}
+
+
+# ---- rate limiter (process-wide token bucket) ----------------------
+init_rate_limiter(capacity=_CAP, rps=_DEF_RATE_RPS)
+
+
+# ---- helpers ------------------------------------------------------------
+_MASK_KEYS = {"authorization", "x-api-key", "apikey", "api_key", "token", "secret", "password"}
+
+
+def _mask_headers(h: dict | None) -> dict:
+    out: dict[str, Any] = {}
+    for k, v in (h or {}).items():
+        if str(k).lower() in _MASK_KEYS:
+            out[k] = "***"
+        else:
+            out[k] = v
+    return out
+
+
+def _domain_ok(url: str) -> bool:
+    if not _ALLOWED:
+        return True
+    try:
+        netloc = urlparse(url).netloc.split("@")[-1].split(":")[0].lower()
+        return any(netloc == d or netloc.endswith("." + d) for d in _ALLOWED)
+    except Exception:
+        return True
+
+
+@dataclass
+class _CacheEntry:
+    meta_path: Path
+    body_path: Path
+    key: str
+
+
+def _cache_key(method: str, url: str, params: dict | None, headers: dict | None) -> str:
+    norm = {
+        "method": method.upper(),
+        "url": url,
+        "params": params or {},
+        "headers": _mask_headers(headers or {}),
+    }
+    blob = json.dumps(norm, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
+    return hashlib.sha256(blob.encode("utf-8")).hexdigest()
+
+
+def _cache_entry(key: str) -> _CacheEntry:
+    base = Path(_DEF_CACHE_DIR)
+    base.mkdir(parents=True, exist_ok=True)
+    return _CacheEntry(meta_path=base / f"{key}.json", body_path=base / f"{key}.bin", key=key)
+
+
+def _content_hash(b: bytes) -> str:
+    return "sha256:" + hashlib.sha256(b).hexdigest()
+
+
+def _read_cache(key: str, ttl: int | None) -> tuple[dict | None, bytes | None, bool]:
+    if _CACHE_MODE == "off":
+        return None, None, False
+    ce = _cache_entry(key)
+    if not ce.meta_path.exists() or not ce.body_path.exists():
+        return None, None, False
+    try:
+        meta = json.loads(ce.meta_path.read_text(encoding="utf-8"))
+        body = ce.body_path.read_bytes()
+    except Exception:
+        return None, None, False
+    # TTL check
+    if ttl and ttl > 0:
+        age = int(time.time()) - int(meta.get("ts", 0))
+        if age > ttl:
+            return None, None, False
+    return meta, body, True
+
+
+def _write_cache(key: str, status: int, headers: dict, body: bytes, url: str) -> dict:
+    if _CACHE_MODE == "ro":
+        return {
+            "ts": int(time.time()),
+            "status": status,
+            "headers": headers,
+            "content_hash": _content_hash(body),
+            "url": url,
+        }
+    ce = _cache_entry(key)
+    meta = {
+        "ts": int(time.time()),
+        "status": status,
+        "headers": headers,
+        "content_hash": _content_hash(body),
+        "url": url,
+    }
+    ce.meta_path.write_text(
+        json.dumps(meta, sort_keys=True, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    ce.body_path.write_bytes(body)
+    return meta
+
+
+def _http_request(
+    method: str,
+    url: str,
+    *,
+    params: dict | None = None,
+    headers: dict | None = None,
+    timeout: float | None = None,
+) -> tuple[int, dict, bytes]:
+    """Send HTTP request using httpx/requests/urllib; return (status, headers, body)."""
+    with _HTTP.Client(timeout=timeout or _DEF_TIMEOUT, follow_redirects=True) as c:
+        r = c.request(method.upper(), url, params=params, headers=headers)
+        return int(r.status_code), dict(r.headers), bytes(r.content)
+
+
+def _backoff_sleep(i: int) -> None:
+    # exponential + jitter
+    base = min(2**i, 30)
+    time.sleep(base + random.random() * 0.3 * base)
+
+
+# ---- Public API ---------------------------------------------------------
+def get(
+    url: str,
+    *,
+    params: dict | None = None,
+    headers: dict | None = None,
+    ttl: int | None = None,
+    paginator: Callable[[str, dict | None, dict], dict | None] | None = None,
+    timeout: float | None = None,
+) -> bytes:
+    """
+    Raw GET with optional FS cache and simple pagination.
+    If paginator is provided, it should return
+    {"next_request": {"url": "...", "params": {...}}} or None.
+    """
+    if not _domain_ok(url):
+        raise RuntimeError(f"HTTP domain not allowed by FF_HTTP_ALLOWED_DOMAINS: {url}")
+
+    ttl = _DEF_TTL if ttl is None else ttl
+    headers = dict(headers or {})
+
+    def _one(method: str, url_: str, params_: dict | None) -> tuple[bytes, dict]:
+        key = _cache_key(method, url_, params_, headers)
+        meta, body, hit = _read_cache(key, ttl)
+        if hit:
+            # meta can be None -> normalize to empty dict before accessing .get
+            meta_dict = meta or {}
+            _ctx.record(
+                key, meta_dict.get("content_hash", ""), True, len(body or b""), used_offline=True
+            )
+            return body or b"", meta_dict
+        if _OFFLINE:
+            raise RuntimeError(f"HTTP offline mode - cache miss for {url_}")
+
+        tries = max(_DEF_MAX_RETRIES, 1)
+        for i in range(tries):
+            status, resp_headers, resp_body = _http_request(
+                method, url_, params=params_, headers=headers, timeout=timeout
+            )
+            if status in (429, 500, 502, 503, 504) and i < tries - 1:
+                # honor Retry-After (seconds) if present
+                ra = resp_headers.get("Retry-After")
+                if ra:
+                    try:
+                        time.sleep(float(ra))
+                    except Exception:
+                        _backoff_sleep(i)
+                else:
+                    _backoff_sleep(i)
+                continue
+            # write cache for any success or 304
+            http_status_200 = 200
+            http_status_300 = 300
+            http_status_304 = 304
+            if http_status_200 <= status < http_status_300 or status == http_status_304:
+                meta = _write_cache(key, status, resp_headers, resp_body, url_)
+                _ctx.record(
+                    key, meta.get("content_hash", ""), False, len(resp_body), used_offline=False
+                )
+                return resp_body, meta
+            raise RuntimeError(f"HTTP {status} for {url_}")
+        # should not reach
+        raise RuntimeError(f"HTTP error after retries for {url_}")
+
+    body, _ = _one("GET", url, params)
+    if not paginator:
+        return body
+
+    # paginate: concatenated bytes are not helpful
+    # → collect JSON pages and join later in get_json/get_df
+    # Here we just return the first page; get_json/get_df implement paging across JSON.
+    return body
+
+
+def get_json(
+    url: str,
+    *,
+    params: dict | None = None,
+    headers: dict | None = None,
+    ttl: int | None = None,
+    paginator: Callable[[str, dict | None, dict], dict | None] | None = None,
+    timeout: float | None = None,
+) -> Any:
+    """GET returning parsed JSON. If paginator is provided, it follows pages via callback."""
+    ttl = _DEF_TTL if ttl is None else ttl
+    headers = dict(headers or {})
+
+    def _load_one(u: str, p: dict | None) -> tuple[Any, dict]:
+        raw = get(u, params=p, headers=headers, ttl=ttl, paginator=None, timeout=timeout)
+        try:
+            js = json.loads(raw.decode("utf-8"))
+        except Exception:
+            js = json.loads(raw)  # if already str
+        return js, {}
+
+    pages: list[Any] = []
+    u, p = url, params
+    while True:
+        js, _ = _load_one(u, p)
+        pages.append(js)
+        if paginator is None:
+            break
+        nxt = paginator(u, p, js)
+        if not nxt:
+            break
+        req = nxt.get("next_request")
+        if not req:
+            break
+        u = req.get("url") or u
+        p = req.get("params")
+    return pages[0] if paginator is None else pages
+
+
+MetaEntry = str | list[str]
+MetaArgIn = Sequence[str | Sequence[str]] | None
+MetaParamOut = str | list[MetaEntry] | None
+
+
+def get_df(
+    url: str,
+    *,
+    params: dict | None = None,
+    headers: dict | None = None,
+    ttl: int | None = None,
+    paginator: Callable[[str, dict | None, dict], dict | None] | None = None,
+    json_path: list[str] | None = None,
+    record_path: Sequence[str] | None = None,
+    meta: MetaArgIn | None = None,
+    dtype: dict[str, str] | None = None,
+    timeout: float | None = None,
+    normalize: bool = False,
+) -> pd.DataFrame:
+    """
+    GET JSON and normalize into a DataFrame using pandas.json_normalize.
+    If `paginator` is provided, concatenates pages over the same normalization logic.
+
+    Parameters
+    ----------
+    record_path : Sequence[str] | None
+        Path to the list in the JSON to be normalized.
+    meta : Sequence[str | Sequence[str]] | None
+        Columns to include as metadata (top-level keys or nested paths).
+    """
+
+    def _extract(obj: Any) -> Any:
+        """Follow json_path (if provided) into nested JSON."""
+        cur = obj
+        for k in json_path or []:
+            cur = cur.get(k) if isinstance(cur, dict) else None
+        return cur
+
+    def _coerce_meta(m: MetaArgIn) -> MetaParamOut:
+        """
+        Return a value whose static type is exactly:
+            str | list[str | list[str]] | None
+        """
+        if m is None:
+            return None
+        # Build a list whose element type is (str | list[str])
+        out: list[MetaEntry] = []
+        for elem in m:
+            if isinstance(elem, str):
+                out.append(elem)  # str
+            else:
+                out.append(list(elem))  # Sequence[str] -> list[str]
+        return out  # list[MetaEntry] == list[str | list[str]]
+
+    def _to_df(js: Any) -> pd.DataFrame:
+        base = _extract(js)
+        base = base if base is not None else js
+        if record_path:
+            rp = list(record_path) if record_path else None
+            meta_param = _coerce_meta(meta)
+            df = pd.json_normalize(base, record_path=rp, meta=meta_param)
+        # if it's a list of dicts
+        elif isinstance(base, list):
+            df = pd.json_normalize(base, sep=".") if normalize else pd.DataFrame(base)
+        else:
+            df = pd.json_normalize(base, sep=".") if normalize else pd.json_normalize(base)
+        if dtype:
+            # Use DataFrame.astype with a mapping to avoid Series.astype overload issues.
+            try:
+                df = df.astype(cast(Any, dict(dtype)), copy=False)
+            except Exception:
+                # Best-effort fallback, still via DataFrame.astype (no Series.astype)
+                for col, dt in dtype.items():
+                    with suppress(Exception):
+                        df = df.astype({col: cast(Any, dt)}, copy=False)
+        return df
+
+    if paginator is None:
+        js = get_json(url, params=params, headers=headers, ttl=ttl, timeout=timeout)
+        return _to_df(js)
+
+    pages = get_json(
+        url, params=params, headers=headers, ttl=ttl, paginator=paginator, timeout=timeout
+    )
+    frames = []
+    for js in pages if isinstance(pages, list) else [pages]:
+        frames.append(_to_df(js))
+    if not frames:
+        return pd.DataFrame()
+    return pd.concat(frames, ignore_index=True)
diff --git a/src/fastflowtransform/api/rate_limit.py b/src/fastflowtransform/api/rate_limit.py
new file mode 100644
index 0000000..b8cbd83
--- /dev/null
+++ b/src/fastflowtransform/api/rate_limit.py
@@ -0,0 +1,112 @@
+# api/rate_limit.py
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from threading import Lock
+from time import monotonic
+
+__all__ = ["TokenBucket", "init_rate_limiter", "rate_limit", "reset", "set_params", "try_consume"]
+
+
+@dataclass
+class TokenBucket:
+    """Thread-safe token bucket with blocking wait."""
+
+    capacity: float
+    refill_per_sec: float
+    _tokens: float = 0.0
+    _last_refill: float = field(default_factory=monotonic)
+    _lock: Lock = field(default_factory=Lock, repr=False)
+
+    def _refill(self, now: float) -> None:
+        dt = now - self._last_refill
+        if dt <= 0:
+            return
+        self._tokens = min(self.capacity, self._tokens + dt * self.refill_per_sec)
+        self._last_refill = now
+
+    def wait(self, cost: float = 1.0) -> None:
+        """Block until at least `cost` tokens are available, then consume them."""
+        if self.refill_per_sec <= 0 or self.capacity <= 0:
+            return  # disabled
+        while True:
+            with self._lock:
+                now = monotonic()
+                self._refill(now)
+                if self._tokens >= cost:
+                    self._tokens -= cost
+                    return
+                missing = cost - self._tokens
+                to_sleep = missing / max(self.refill_per_sec, 1e-9)
+                self._tokens = 0.0
+            time.sleep(max(to_sleep, 0.0))
+
+    def try_consume(self, cost: float = 1.0) -> bool:
+        """Attempt to consume `cost` tokens without blocking."""
+        if self.refill_per_sec <= 0 or self.capacity <= 0:
+            return True  # disabled → always allow
+        with self._lock:
+            now = monotonic()
+            self._refill(now)
+            if self._tokens >= cost:
+                self._tokens -= cost
+                return True
+            return False
+
+
+# ---- Module state holder (avoids `global` by mutating attributes) ----
+
+
+@dataclass
+class _State:
+    rl: TokenBucket | None = None
+
+
+_STATE = _State()
+
+
+def init_rate_limiter(capacity: float, rps: float) -> None:
+    """
+    Initialize the module-level token bucket. If capacity<=0 or rps<=0, disables the limiter.
+    """
+    _STATE.rl = (
+        None if capacity <= 0 or rps <= 0 else TokenBucket(capacity=capacity, refill_per_sec=rps)
+    )
+
+
+def set_params(capacity: float | None = None, rps: float | None = None) -> None:
+    """
+    Update parameters. Rebuilds the bucket to apply new settings (keeps behavior simple).
+    If not initialized and both values are provided (and >0), initializes it.
+    """
+    rl = _STATE.rl
+    if rl is None:
+        if capacity and rps and capacity > 0 and rps > 0:
+            _STATE.rl = TokenBucket(capacity=capacity, refill_per_sec=rps)
+        return
+    cap = capacity if capacity is not None else rl.capacity
+    rate = rps if rps is not None else rl.refill_per_sec
+    _STATE.rl = None if cap <= 0 or rate <= 0 else TokenBucket(capacity=cap, refill_per_sec=rate)
+
+
+def rate_limit(cost: float = 1.0) -> None:
+    """
+    Block until `cost` tokens are available. No-op if limiter is disabled/uninitialized.
+    """
+    rl = _STATE.rl
+    if rl is not None:
+        rl.wait(cost)
+
+
+def try_consume(cost: float = 1.0) -> bool:
+    """
+    Non-blocking: returns True if tokens were consumed; True as well if disabled/uninitialized.
+    """
+    rl = _STATE.rl
+    return True if rl is None else rl.try_consume(cost)
+
+
+def reset() -> None:
+    """Test helper: clear the limiter state (no globals)."""
+    _STATE.rl = None
diff --git a/src/fastflowtransform/artifacts.py b/src/fastflowtransform/artifacts.py
new file mode 100644
index 0000000..2e849dc
--- /dev/null
+++ b/src/fastflowtransform/artifacts.py
@@ -0,0 +1,242 @@
+# fastflowtransform/artifacts.py
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from fastflowtransform.core import REGISTRY, relation_for
+
+# ---------- Paths ----------
+
+
+def _target_dir(project_dir: Path) -> Path:
+    """Return artifact target directory under the project."""
+    d = (project_dir / ".fastflowtransform" / "target").resolve()
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _rel(p: Path, base: Path) -> str:
+    """Return path p relative to base as posix string."""
+    try:
+        return p.resolve().relative_to(base.resolve()).as_posix()
+    except Exception:
+        return p.name
+
+
+def _rel_safe(p_like: Any, base: Path) -> str:
+    """
+    Best-effort relative path rendering.
+    Accepts None/str/Path; returns empty string on None or conversion failure.
+    """
+    if p_like is None:
+        return ""
+    try:
+        if isinstance(p_like, Path):
+            return _rel(p_like, base)
+        # Try to coerce strings / os.PathLike to Path
+        return _rel(Path(str(p_like)), base)
+    except Exception:
+        try:
+            return str(p_like) if p_like is not None else ""
+        except Exception:
+            return ""
+
+
+def _iso_now() -> str:
+    """UTC timestamp with seconds precision."""
+    return datetime.now(UTC).isoformat(timespec="seconds")
+
+
+def _json_dump(path: Path, obj: Any) -> None:
+    """
+    Write JSON deterministically (sorted keys) with a trailing newline.
+    Pretty-print by default (indent=2). Set FFT_ARTIFACTS_PRETTY=0 to use compact form.
+    """
+    pretty_env = os.getenv("FFT_ARTIFACTS_PRETTY", "1").lower()
+    pretty = pretty_env not in {"0", "false", "no"}
+    if pretty:
+        txt = json.dumps(obj, sort_keys=True, ensure_ascii=False, indent=2)
+    else:
+        txt = json.dumps(obj, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
+    path.write_text(txt + "\n", encoding="utf-8")
+
+
+# ---------- MANIFEST ----------
+
+
+def write_manifest(project_dir: Path) -> Path:
+    """
+    Write manifest.json with minimal compatibility:
+      - nodes: {name, path, deps, materialized, relation, kind}
+      - macros: {name -> path}
+      - sources: verbatim REGISTRY.sources
+      - generated_at
+    """
+    project_dir = Path(project_dir)
+    out_dir = _target_dir(project_dir)
+    manifest_path = out_dir / "manifest.json"
+
+    nodes = {}
+    for name, node in sorted(REGISTRY.nodes.items(), key=lambda x: x[0]):
+        nodes[name] = {
+            "name": name,
+            "kind": node.kind,
+            # Be resilient to stubbed Nodes in tests (path may be None)
+            "path": _rel_safe(getattr(node, "path", None), project_dir),
+            "deps": sorted(list(node.deps or [])),
+            "materialized": (node.meta or {}).get("materialized", "table"),
+            "relation": relation_for(name),
+        }
+
+    macros = {}
+    for mname, mpath in sorted(REGISTRY.macros.items(), key=lambda x: x[0]):
+        macros[mname] = _rel_safe(mpath, project_dir)
+
+    data = {
+        "metadata": {
+            "tool": "fastflowtransform",
+            "generated_at": _iso_now(),
+        },
+        "nodes": nodes,
+        "macros": macros,
+        "sources": REGISTRY.sources or {},
+    }
+    _json_dump(manifest_path, data)
+    return manifest_path
+
+
+# ---------- RUN RESULTS ----------
+
+
+@dataclass
+class RunNodeResult:
+    name: str
+    status: str  # "success" | "error" | "skipped"
+    started_at: str
+    finished_at: str
+    duration_ms: int
+    message: str | None = None
+    http: dict | None = None
+
+
+def write_run_results(
+    project_dir: Path,
+    *,
+    started_at: str,
+    finished_at: str,
+    node_results: list[RunNodeResult],
+) -> Path:
+    """
+    Write run_results.json containing run envelope and per-node results.
+    """
+    project_dir = Path(project_dir)
+    out_dir = _target_dir(project_dir)
+    results_path = out_dir / "run_results.json"
+
+    data = {
+        "metadata": {"tool": "fastflowtransform", "generated_at": _iso_now()},
+        "run_started_at": started_at,
+        "run_finished_at": finished_at,
+        "results": [asdict(nr) for nr in sorted(node_results, key=lambda r: r.name)],
+    }
+    _json_dump(results_path, data)
+    return results_path
+
+
+# ---------- CATALOG ----------
+
+
+def _duckdb_columns(con: Any, table: str) -> list[dict[str, Any]]:
+    """Return column metadata for a DuckDB table, with robust fallback."""
+    # Prefer information_schema with a schema filter for reliability
+    sql_info = """
+      select column_name as name, data_type as dtype, is_nullable
+      from information_schema.columns
+      where table_schema in ('main','temp')
+        and lower(table_name)=lower(?)
+      order by ordinal_position
+    """
+    rows = con.execute(sql_info, [table]).fetchall()
+    if rows:
+        return [{"name": r[0], "dtype": r[1], "nullable": str(r[2]).lower() == "yes"} for r in rows]
+
+    # Fallback: PRAGMA table_info(<ident>) — quote identifier safely
+    # DuckDB pragma returns: cid, name, type, notnull, dflt_value, pk
+    def _q_ident(ident: str) -> str:
+        return '"' + ident.replace('"', '""') + '"'
+
+    pragma_sql = f"PRAGMA table_info({_q_ident(table)})"
+    rows2 = con.execute(pragma_sql).fetchall()
+    out: list[dict[str, Any]] = []
+    for r in rows2:
+        name = r[1]
+        dtype = r[2]
+        nullable = r[3] == 0  # notnull == 0 → nullable True
+        out.append({"name": name, "dtype": dtype, "nullable": nullable})
+    return out
+
+
+def _postgres_columns(con: Any, table: str, schema: str | None = None) -> list[dict[str, Any]]:
+    sch = schema or "public"
+    sql = """
+      select column_name, data_type, is_nullable
+      from information_schema.columns
+      where table_schema=%s and lower(table_name)=lower(%s)
+      order by ordinal_position
+    """
+    rows = con.execute(sql, (sch, table)).fetchall()
+    return [{"name": r[0], "dtype": r[1], "nullable": (r[2] == "YES")} for r in rows]
+
+
+def _try_columns_for(executor: Any, table: str) -> list[dict[str, Any]]:
+    """
+    Best-effort column introspection for known engines. Returns [] if unsupported.
+    """
+    con = getattr(executor, "con", None)
+    # DuckDB detection (robust): class/module name contains 'duckdb'
+    try:
+        if con and "duckdb" in getattr(con.__class__, "__module__", "").lower():
+            return _duckdb_columns(con, table)
+    except Exception:
+        # Never raise from catalog collection — return empty and let caller proceed
+        return []
+    # Postgres via psycopg connection inside executor (optional)
+    try:
+        schema = getattr(executor, "schema", None)
+        if con and hasattr(con, "execute") and hasattr(con, "fetchall"):
+            return _postgres_columns(con, table, schema=schema)
+    except Exception:
+        pass
+    return []
+
+
+def write_catalog(project_dir: Path, executor: Any) -> Path:
+    """
+    Write catalog.json:
+      - relations: map of relation -> {columns:[{name,dtype,nullable}]}
+    """
+    project_dir = Path(project_dir)
+    out_dir = _target_dir(project_dir)
+    catalog_path = out_dir / "catalog.json"
+
+    relations: dict[str, Any] = {}
+    rel_names = sorted([relation_for(n) for n in REGISTRY.nodes])
+    for rel in rel_names:
+        # Per-relation guard: introspection must never break artifact emission
+        try:
+            cols = _try_columns_for(executor, rel)
+        except Exception:
+            cols = []
+        relations[rel] = {"columns": cols}
+
+    data = {
+        "metadata": {"tool": "fastflowtransform", "generated_at": _iso_now()},
+        "relations": relations,
+    }
+    _json_dump(catalog_path, data)
+    return catalog_path
diff --git a/src/fastflowtransform/cache.py b/src/fastflowtransform/cache.py
index 6d966cd..c8749f8 100644
--- a/src/fastflowtransform/cache.py
+++ b/src/fastflowtransform/cache.py
@@ -1,6 +1,9 @@
 # src/fastflowtransform/cache.py
 from __future__ import annotations
 
+import builtins
+import hashlib
+import inspect
 import json
 import os
 import tempfile
@@ -9,7 +12,11 @@
 from pathlib import Path
 from typing import Any
 
-from .core import relation_for
+import yaml
+from jinja2 import Environment
+
+from .core import REGISTRY, relation_for
+from .dag import topo_sort
 from .meta import relation_exists as _relation_exists_engine
 
 
@@ -86,6 +93,100 @@ def update_many(self, fps: Mapping[str, str]) -> None:
         for k, v in fps.items():
             self.entries[k] = v
 
+    # ------------------------ read-only fingerprint computation ------------------------
+    def _env_ctx_blob(self) -> str:
+        """
+        Build a stable JSON blob for environment context used in the fingerprint:
+          - engine (from cache instance)
+          - profile (from cache instance)
+          - all FF_* environment variables (key+value)
+          - normalized sources.yml (best-effort)
+        """
+        ff_env = {k: v for k, v in os.environ.items() if k.startswith("FF_")}
+        try:
+            src_norm = yaml.safe_dump(REGISTRY.sources or {}, sort_keys=True)
+        except Exception:
+            src_norm = ""
+        payload = {
+            "engine": self.engine,
+            "profile": self.profile,
+            "ff_env": ff_env,
+            "sources": src_norm,
+        }
+        return json.dumps(payload, sort_keys=True)
+
+    def compute_current(self, env: Environment, executor: Any) -> dict[str, str]:
+        """
+        Compute CURRENT fingerprints for all registered nodes (read-only).
+        Uses the documented formula:
+          - SQL: rendered SQL (via executor.render_sql to mirror real run)
+          - Python: function source (inspect.getsource) with file-content fallback
+          - env_ctx blob (engine/profile/FF_* vars/sources.yml)
+          - dependency fingerprints chained downstream
+        Does NOT write to disk.
+        """
+        env_ctx_blob = self._env_ctx_blob()
+
+        # Preload sources for SQL / Python
+        sql_render: dict[str, str] = {}
+        py_src: dict[str, str] = {}
+
+        for name, node in REGISTRY.nodes.items():
+            if node.kind == "sql":
+                try:
+                    # Render with same substitutions as in run()
+                    sql_render[name] = executor.render_sql(node, env)
+                except Exception:
+                    # Fallback: raw template content to still capture file changes
+                    try:
+                        raw = node.path.read_text(encoding="utf-8") if node.path else ""
+                    except Exception:
+                        raw = ""
+                    sql_render[name] = raw
+            else:
+                func = REGISTRY.py_funcs.get(name)
+                src = ""
+                if func is not None:
+                    try:
+                        src = inspect.getsource(func)
+                    except Exception:
+                        try:
+                            src = node.path.read_text(encoding="utf-8") if node.path else ""
+                        except Exception:
+                            src = ""
+                py_src[name] = src
+
+        def _hash(parts: list[str]) -> str:
+            h = hashlib.sha256()
+            for part in parts:
+                h.update(part.encode("utf-8"))
+                h.update(b"\x00")
+            return h.hexdigest()
+
+        current: dict[str, str] = {}
+        order = topo_sort(REGISTRY.nodes)
+        for name in order:
+            node = REGISTRY.nodes[name]
+            dep_fps = [current[d] for d in (node.deps or []) if d in current]
+            if node.kind == "sql":
+                blob = ["sql", name, sql_render.get(name, ""), env_ctx_blob, *dep_fps]
+            else:
+                blob = ["py", name, py_src.get(name, ""), env_ctx_blob, *dep_fps]
+            current[name] = _hash(blob)
+        return current
+
+    def modified_set(self, env: Environment, executor: Any) -> builtins.set[str]:
+        """
+        Return the set of nodes whose CURRENT fingerprint differs from saved cache.
+        Missing saved entries count as modified.
+        """
+        # Ensure we have the saved entries loaded
+        if not self.entries:
+            self.load()
+        current = self.compute_current(env, executor)
+        modified = {n for n, fp in current.items() if self.entries.get(n) != fp}
+        return modified
+
 
 # ------------------------ artifact existence helpers ------------------------
 
diff --git a/src/fastflowtransform/cli/__init__.py b/src/fastflowtransform/cli/__init__.py
index e06278e..542ee2c 100644
--- a/src/fastflowtransform/cli/__init__.py
+++ b/src/fastflowtransform/cli/__init__.py
@@ -1,14 +1,11 @@
+# fastflowtransform/cli/__init__.py
 from __future__ import annotations
 
 import typer
 
 from fastflowtransform import __version__
 from fastflowtransform.cache import FingerprintCache
-from fastflowtransform.dag import levels as dag_levels, topo_sort
-from fastflowtransform.docs import render_site
-from fastflowtransform.run_executor import ScheduleResult, schedule
-
-from .bootstrap import (
+from fastflowtransform.cli.bootstrap import (
     CLIContext,
     _die,
     _get_test_con,
@@ -19,16 +16,15 @@
     _resolve_profile,
     _resolve_project_path,
 )
-from .dag_cmd import dag, register as _register_dag
-from .docgen_cmd import docgen, register as _register_docgen
-from .docs_utils import (
+from fastflowtransform.cli.dag_cmd import dag, register as _register_dag
+from fastflowtransform.cli.docgen_cmd import docgen, register as _register_docgen
+from fastflowtransform.cli.docs_utils import (
     _build_docs_manifest,
     _infer_sql_ref_aliases,
     _resolve_dag_out_dir,
     _strip_html,
 )
-from .logging_utils import LOG, SQL_LOG, _setup_logging
-from .options import (
+from fastflowtransform.cli.options import (
     CacheMode,
     CacheOpt,
     CaseOpt,
@@ -52,20 +48,20 @@
     VarsOpt,
     WithSchemaOpt,
 )
-from .run import (
+from fastflowtransform.cli.run import (
     _RunEngine,
     register as _register_run,
     run,
 )
-from .seed_cmd import register as _register_seed, seed
-from .selectors import (
+from fastflowtransform.cli.seed_cmd import register as _register_seed, seed
+from fastflowtransform.cli.selectors import (
     _build_predicates,
     _compile_selector,
     _parse_select,
     _selected_subgraph_names,
     _selector,
 )
-from .sync_db_comments_cmd import (
+from fastflowtransform.cli.sync_db_comments_cmd import (
     _pg_fq_table,
     _pg_quote_ident,
     _sf_fq_table,
@@ -76,8 +72,12 @@
     register as _register_sync_db_comments,
     sync_db_comments,
 )
-from .test_cmd import DQResult, register as _register_test, test
-from .utest_cmd import register as _register_utest, utest
+from fastflowtransform.cli.test_cmd import DQResult, register as _register_test, test
+from fastflowtransform.cli.utest_cmd import register as _register_utest, utest
+from fastflowtransform.dag import levels as dag_levels, topo_sort
+from fastflowtransform.docs import render_site
+from fastflowtransform.logging import echo, setup_from_cli_flags
+from fastflowtransform.run_executor import ScheduleResult, schedule
 
 app = typer.Typer(
     name="fft",
@@ -89,7 +89,7 @@
 
 def _version_callback(value: bool | None) -> None:
     if value:
-        typer.echo(__version__)
+        echo(__version__)
         raise typer.Exit()
 
 
@@ -107,8 +107,16 @@ def main(
         0, "--verbose", "-v", count=True, help="Increase verbosity (-v: INFO, -vv: DEBUG)"
     ),
     quiet: int = typer.Option(0, "--quiet", "-q", count=True, help="Reduce verbosity (-q: ERROR)"),
+    sql_debug: bool = typer.Option(False, "--sql-debug", help="Enable SQL debug logging"),
+    log_json: bool = typer.Option(False, "--log-json", help="Emit logs as JSON"),
 ) -> None:
-    _setup_logging(verbose, quiet)
+    setup_from_cli_flags(
+        verbose=verbose,
+        quiet=quiet,
+        json=log_json,
+        sql_debug=sql_debug,
+        to_stderr=False,
+    )
 
 
 _register_run(app)
@@ -121,8 +129,6 @@ def main(
 
 
 __all__ = [
-    "LOG",
-    "SQL_LOG",
     "CLIContext",
     "CacheMode",
     "CacheOpt",
diff --git a/src/fastflowtransform/cli/__main__.py b/src/fastflowtransform/cli/__main__.py
new file mode 100644
index 0000000..3bdbe0e
--- /dev/null
+++ b/src/fastflowtransform/cli/__main__.py
@@ -0,0 +1,3 @@
+from . import app
+
+app()
diff --git a/src/fastflowtransform/cli/bootstrap.py b/src/fastflowtransform/cli/bootstrap.py
index 62d4577..1707a43 100644
--- a/src/fastflowtransform/cli/bootstrap.py
+++ b/src/fastflowtransform/cli/bootstrap.py
@@ -1,16 +1,19 @@
+# fastflowtransform/cli/bootstrap.py
 from __future__ import annotations
 
 from collections.abc import Callable
+from contextlib import suppress
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, NoReturn, cast
 
 import typer
 import yaml
+from dotenv import load_dotenv
 from jinja2 import Environment
 
 from fastflowtransform.core import REGISTRY
-from fastflowtransform.errors import DependencyNotFoundError, ProfileConfigError
+from fastflowtransform.errors import DependencyNotFoundError
 from fastflowtransform.executors import (
     BigQueryBFExecutor,
     BigQueryExecutor,
@@ -21,6 +24,8 @@
 )
 from fastflowtransform.executors._shims import BigQueryConnShim, SAConnShim
 from fastflowtransform.executors.base import BaseExecutor
+from fastflowtransform.incremental import run_or_dispatch
+from fastflowtransform.logging import echo
 from fastflowtransform.settings import (
     EngineType,
     EnvSettings,
@@ -69,7 +74,7 @@ def _resolve_project_path(project_arg: str) -> Path:
 
 
 def _die(msg: str, code: int = 1) -> NoReturn:
-    typer.echo(f"\n❌ {msg}")
+    echo(f"\n❌ {msg}")
     raise typer.Exit(code)
 
 
@@ -78,7 +83,7 @@ def _load_project_and_env(project_arg: str) -> tuple[Path, Environment]:
     try:
         REGISTRY.load_project(proj)
     except DependencyNotFoundError as e:
-        typer.echo(str(e))
+        echo(str(e))
         raise typer.Exit(1) from e
 
     jenv = REGISTRY.env
@@ -87,6 +92,32 @@ def _load_project_and_env(project_arg: str) -> tuple[Path, Environment]:
     return proj, cast(Environment, jenv)
 
 
+def _load_dotenv_layered(project_dir: Path, env_name: str) -> None:
+    """
+    Load .env in layers (lowest to highest precedence):
+      1) <repo>/.env
+      2) <project>/.env
+      3) <project>/.env.local
+      4) <project>/.env.<env_name>
+      5) <project>/.env.<env_name>.local
+    """
+
+    def _safe_load(p: Path, override: bool) -> None:
+        with suppress(Exception):
+            load_dotenv(dotenv_path=p, override=override)
+
+    # 1) Repo root defaults
+    _safe_load(Path.cwd() / ".env", override=False)
+    # 2) Project defaults
+    _safe_load(project_dir / ".env", override=True)
+    # 3) Project local (gitignored)
+    _safe_load(project_dir / ".env.local", override=True)
+    # 4) Env-specific
+    _safe_load(project_dir / f".env.{env_name}", override=True)
+    # 5) Env-specific local (gitignored)
+    _safe_load(project_dir / f".env.{env_name}.local", override=True)
+
+
 def _resolve_profile(
     env_name: str, engine: EngineType | None, proj: Path
 ) -> tuple[EnvSettings, Profile]:
@@ -95,10 +126,83 @@ def _resolve_profile(
         env = env.model_copy(update={"ENGINE": engine})
     try:
         prof = _resolve_profile_impl(proj, env_name, env)
-        return env, prof
-    except ProfileConfigError as e:
-        typer.echo(f"❌ {e}")
-        raise typer.Exit(1) from e
+    except Exception as exc:
+        raise typer.BadParameter(f"Failed to resolve profile '{env_name}': {exc}") from exc
+
+    engine_name = getattr(prof, "engine", None)
+    if not engine_name:
+        raise typer.BadParameter(
+            f"Profile '{env_name}' does not define an engine. "
+            "Add one to profiles.yml or pass --engine."
+        )
+
+    return env, prof
+
+
+def _validate_profile_params(env_name: str, prof: Profile) -> None:
+    def _fail(msg: str) -> None:
+        raise typer.BadParameter(f"Profile '{env_name}' invalid for engine '{prof.engine}': {msg}")
+
+    if prof.engine == "duckdb":
+        path = getattr(prof.duckdb, "path", None)
+        if not isinstance(path, str) or not path.strip():
+            _fail("duckdb.path must be set (profiles.yml → duckdb.path or env FF_DUCKDB_PATH).")
+        return
+
+    if prof.engine == "postgres":
+        dsn = getattr(prof.postgres, "dsn", None)
+        schema = getattr(prof.postgres, "db_schema", None)
+        if not dsn or not isinstance(dsn, str) or not dsn.strip():
+            _fail("postgres.dsn must be set (profiles.yml → postgres.dsn or env FF_PG_DSN).")
+        if schema is None or (isinstance(schema, str) and not schema.strip()):
+            _fail(
+                "postgres.db_schema must be set (profiles.yml "
+                "→ postgres.db_schema or env FF_PG_SCHEMA)."
+            )
+        return
+
+    if prof.engine == "bigquery":
+        dataset = getattr(prof.bigquery, "dataset", None)
+        if not dataset or not isinstance(dataset, str) or not dataset.strip():
+            _fail(
+                "bigquery.dataset must be set (profiles.yml "
+                "→ bigquery.dataset or env FF_BQ_DATASET)."
+            )
+        return
+
+    if prof.engine == "databricks_spark":
+        master = getattr(prof.databricks_spark, "master", None)
+        app_name = getattr(prof.databricks_spark, "app_name", None)
+        if not isinstance(master, str) or not master.strip():
+            _fail(
+                "databricks_spark.master must be set (profiles.yml "
+                "→ databricks_spark.master or env FF_DBR_MASTER)."
+            )
+        if not isinstance(app_name, str) or not app_name.strip():
+            _fail(
+                "databricks_spark.app_name must be set (profiles.yml "
+                "→ databricks_spark.app_name or env FF_DBR_APPNAME)."
+            )
+        return
+
+    if prof.engine == "snowflake_snowpark":
+        sf = prof.snowflake_snowpark
+        required = {
+            "account": "snowflake_snowpark.account",
+            "user": "snowflake_snowpark.user",
+            "password": "snowflake_snowpark.password",
+            "warehouse": "snowflake_snowpark.warehouse",
+            "database": "snowflake_snowpark.database",
+            "db_schema": "snowflake_snowpark.db_schema",
+        }
+        missing = [label for attr, label in required.items() if not getattr(sf, attr, None)]
+        if missing:
+            joined = ", ".join(missing)
+            _fail(f"{joined} must be set (profiles.yml → snowflake_snowpark.* or env FF_SF_*).")
+        return
+
+    if prof.engine is None:
+        _fail("engine not specified.")
 
 
 def _prepare_context(
@@ -107,9 +211,12 @@ def _prepare_context(
     engine: EngineType | None,
     vars_opt: list[str] | None,
 ) -> CLIContext:
-    proj, jenv = _load_project_and_env(project_arg)
+    proj_raw, jenv = _load_project_and_env(project_arg)
+    proj = Path(proj_raw)
+    _load_dotenv_layered(proj, env_name)
     REGISTRY.set_cli_vars(_parse_cli_vars(vars_opt or []))
     env_settings, prof = _resolve_profile(env_name, engine, proj)
+    _validate_profile_params(env_name, prof)
     return CLIContext(project=proj, jinja_env=jenv, env_settings=env_settings, profile=prof)
 
 
@@ -157,14 +264,14 @@ def _make_executor(prof: Profile, jenv: Environment) -> tuple[Any, Callable, Cal
     ex: BaseExecutor
     if prof.engine == "duckdb":
         ex = DuckExecutor(db_path=prof.duckdb.path)
-        return ex, (lambda n: ex.run_sql(n, jenv)), ex.run_python
+        return ex, (lambda n: run_or_dispatch(ex, n, jenv)), ex.run_python
 
     if prof.engine == "postgres":
         if prof.postgres.dsn is None:
             raise RuntimeError("Postgres DSN must be set")
 
         ex = PostgresExecutor(dsn=prof.postgres.dsn, schema=prof.postgres.db_schema)
-        return ex, (lambda n: ex.run_sql(n, jenv)), ex.run_python
+        return ex, (lambda n: run_or_dispatch(ex, n, jenv)), ex.run_python
 
     if prof.engine == "bigquery":
         if prof.bigquery.dataset is None:
@@ -182,14 +289,14 @@ def _make_executor(prof: Profile, jenv: Environment) -> tuple[Any, Callable, Cal
                 dataset=prof.bigquery.dataset,
                 location=prof.bigquery.location,
             )
-        return ex, (lambda n: ex.run_sql(n, jenv)), ex.run_python
+        return ex, (lambda n: run_or_dispatch(ex, n, jenv)), ex.run_python
 
     if prof.engine == "databricks_spark":
         ex = DatabricksSparkExecutor(
             master=prof.databricks_spark.master,
             app_name=prof.databricks_spark.app_name,
         )
-        return ex, (lambda n: ex.run_sql(n, jenv)), ex.run_python
+        return ex, (lambda n: run_or_dispatch(ex, n, jenv)), ex.run_python
 
     if prof.engine == "snowflake_snowpark":
         cfg = {
@@ -203,7 +310,7 @@ def _make_executor(prof: Profile, jenv: Environment) -> tuple[Any, Callable, Cal
         if prof.snowflake_snowpark.role:
             cfg["role"] = prof.snowflake_snowpark.role
         ex = SnowflakeSnowparkExecutor(cfg)
-        return ex, (lambda n: ex.run_sql(n, jenv)), ex.run_python
+        return ex, (lambda n: run_or_dispatch(ex, n, jenv)), ex.run_python
 
     _die(f"Unbekannter Engine-Typ: {getattr(prof, 'engine', None)}", code=1)
     raise AssertionError("unreachable")
diff --git a/src/fastflowtransform/cli/dag_cmd.py b/src/fastflowtransform/cli/dag_cmd.py
index 01d3227..c0af63e 100644
--- a/src/fastflowtransform/cli/dag_cmd.py
+++ b/src/fastflowtransform/cli/dag_cmd.py
@@ -1,17 +1,10 @@
 from __future__ import annotations
 
-import logging
-
 import typer
 
-from fastflowtransform.core import REGISTRY
-from fastflowtransform.dag import mermaid
-from fastflowtransform.docs import render_site
-
-from .bootstrap import _prepare_context
-from .docs_utils import _resolve_dag_out_dir
-from .logging_utils import LOG
-from .options import (
+from fastflowtransform.cli.bootstrap import _prepare_context
+from fastflowtransform.cli.docs_utils import _resolve_dag_out_dir
+from fastflowtransform.cli.options import (
     EngineOpt,
     EnvOpt,
     HtmlOpt,
@@ -21,7 +14,11 @@
     VarsOpt,
     WithSchemaOpt,
 )
-from .selectors import _compile_selector
+from fastflowtransform.cli.selectors import _compile_selector
+from fastflowtransform.core import REGISTRY
+from fastflowtransform.dag import mermaid
+from fastflowtransform.docs import render_site
+from fastflowtransform.logging import echo, echo_debug
 
 
 def dag(
@@ -51,15 +48,14 @@ def dag(
             render_site(dag_out, filtered_nodes, executor=ex, with_schema=with_schema)
         except TypeError:
             render_site(dag_out, filtered_nodes, executor=ex)
-        typer.echo(f"HTML-DAG written to {dag_out / 'index.html'}")
+        echo(f"HTML-DAG written to {dag_out / 'index.html'}")
     else:
         mm = mermaid(filtered_nodes)
         mmd = dag_out / "dag.mmd"
         mmd.write_text(mm, encoding="utf-8")
-        typer.echo(f"Mermaid DAG written to {dag_out}")
+        echo(f"Mermaid DAG written to {dag_out}")
 
-    if LOG.isEnabledFor(logging.INFO):
-        typer.echo(f"Profile: {env_name} | Engine: {ctx.profile.engine}")
+    echo_debug(f"Profile: {env_name} | Engine: {ctx.profile.engine}")
 
 
 def register(app: typer.Typer) -> None:
diff --git a/src/fastflowtransform/cli/docgen_cmd.py b/src/fastflowtransform/cli/docgen_cmd.py
index 54c6b03..fa6588e 100644
--- a/src/fastflowtransform/cli/docgen_cmd.py
+++ b/src/fastflowtransform/cli/docgen_cmd.py
@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import json
-import logging
 import webbrowser
 from contextlib import suppress
 from pathlib import Path
@@ -9,19 +8,18 @@
 
 import typer
 
-from fastflowtransform.core import REGISTRY
-from fastflowtransform.docs import render_site
-
-from .bootstrap import _prepare_context
-from .docs_utils import _build_docs_manifest, _resolve_dag_out_dir
-from .logging_utils import LOG
-from .options import (
+from fastflowtransform.cli.bootstrap import _prepare_context
+from fastflowtransform.cli.docs_utils import _build_docs_manifest, _resolve_dag_out_dir
+from fastflowtransform.cli.options import (
     EngineOpt,
     EnvOpt,
     OutOpt,
     ProjectArg,
     VarsOpt,
 )
+from fastflowtransform.core import REGISTRY
+from fastflowtransform.docs import render_site
+from fastflowtransform.logging import echo, echo_debug
 
 
 def docgen(
@@ -47,7 +45,7 @@ def docgen(
     dag_out.mkdir(parents=True, exist_ok=True)
 
     render_site(dag_out, REGISTRY.nodes, executor=ex)
-    typer.echo(f"HTML docs written to {dag_out / 'index.html'}")
+    echo(f"HTML docs written to {dag_out / 'index.html'}")
 
     if emit_json is not None:
         manifest = _build_docs_manifest(
@@ -59,15 +57,14 @@ def docgen(
         emit_json = emit_json.resolve()
         emit_json.parent.mkdir(parents=True, exist_ok=True)
         emit_json.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
-        typer.echo(f"Docs manifest JSON written to {emit_json}")
+        echo(f"Docs manifest JSON written to {emit_json}")
 
     if open_source:
         index_path = (dag_out / "index.html").as_uri()
         with suppress(Exception):
             webbrowser.open(index_path, new=2)
 
-    if LOG.isEnabledFor(logging.INFO):
-        typer.echo(f"Profile: {env_name} | Engine: {ctx.profile.engine}")
+    echo_debug(f"Profile: {env_name} | Engine: {ctx.profile.engine}")
 
 
 def register(app: typer.Typer) -> None:
diff --git a/src/fastflowtransform/cli/logging_utils.py b/src/fastflowtransform/cli/logging_utils.py
index 1820b74..f9fa9f2 100644
--- a/src/fastflowtransform/cli/logging_utils.py
+++ b/src/fastflowtransform/cli/logging_utils.py
@@ -1,35 +1,36 @@
-from __future__ import annotations
-
-import logging
-import os
-
-LOG = logging.getLogger("fastflowtransform")
-SQL_LOG = logging.getLogger("fastflowtransform.sql")
-
-
-def _setup_logging(verbose: int, quiet: int) -> None:
-    """
-    Map verbosity to levels:
-      -q        → ERROR
-       (default)→ WARNING
-      -v        → INFO
-      -vv       → DEBUG
-    Also wires the SQL channel and keeps FFT_SQL_DEBUG compatibility.
-    """
-    eff_level_threshold = 2
-    eff = max(min(verbose - quiet, 2), -1)
-    lvl = {-1: logging.ERROR, 0: logging.WARNING, 1: logging.INFO, 2: logging.DEBUG}[eff]
-
-    logging.basicConfig(level=lvl, format="%(levelname)s %(message)s")
-    LOG.setLevel(lvl)
-
-    sql_debug_env = os.getenv("FFT_SQL_DEBUG") == "1"
-    SQL_LOG.setLevel(
-        logging.DEBUG if (eff >= eff_level_threshold or sql_debug_env) else logging.WARNING
-    )
-
-    if eff >= eff_level_threshold and not sql_debug_env:
-        os.environ.setdefault("FFT_SQL_DEBUG", "1")
-
-
-__all__ = ["LOG", "SQL_LOG", "_setup_logging"]
+# fastflowtransform/cli/logging_utils.py
+# from __future__ import annotations
+
+# import logging
+# import os
+
+# from fastflowtransform.logging import get_logger, setup_logging as _setup_pkg_logging
+
+# # retained names so other code keeps working
+# LOG = get_logger("cli")
+# SQL_LOG = get_logger("sql")
+
+# def _setup_logging(verbose: int, quiet: int) -> None:
+#     """
+#     CLI entrypoint config. Verbosity/quiet map to stdlib levels.
+#     """
+#     # base: WARNING; -v INFO; -vv DEBUG; -q ERROR
+#     verbose_debug_level = 2
+#     level = logging.WARNING
+#     if quiet >= 1:
+#         level = logging.ERROR
+#     elif verbose == 1:
+#         level = logging.INFO
+#     elif verbose >= verbose_debug_level:
+#         level = logging.DEBUG
+
+#     # Env-controlled toggles
+#     sql_debug_env = os.getenv("FFT_SQL_DEBUG", "").lower() in ("1", "true", "yes", "on")
+#     json_env = os.getenv("FFT_LOG_JSON", "").lower() in ("1", "true", "yes", "on")
+
+#     # Use package-wide setup (human console by default)
+#     _setup_pkg_logging(
+#         level=level,
+#         json=json_env,
+#         propagate_sql=(verbose >= verbose_debug_level) or sql_debug_env,
+#     )
diff --git a/src/fastflowtransform/cli/options.py b/src/fastflowtransform/cli/options.py
index 9a5387a..013c781 100644
--- a/src/fastflowtransform/cli/options.py
+++ b/src/fastflowtransform/cli/options.py
@@ -94,6 +94,31 @@
 ]
 
 
+# ────────────── HTTP / API Flags ──────────────
+class HttpCacheMode(str, Enum):
+    OFF = "off"  # keine Cache-Nutzung
+    RO = "ro"  # read-only: nur lesen, keine Writes
+    RW = "rw"  # read-write (Default-Verhalten)
+
+
+OfflineOpt = Annotated[
+    bool,
+    typer.Option(
+        "--offline",
+        help="HTTP offline mode: verbietet Netz-Zugriffe in API-Modellen (nur Cache-Hits erlaubt).",
+    ),
+]
+
+HttpCacheOpt = Annotated[
+    HttpCacheMode | None,
+    typer.Option(
+        "--http-cache",
+        help="HTTP-Cache-Modus für API-Modelle: off | ro | rw.",
+        case_sensitive=False,
+    ),
+]
+
+
 class CacheMode(str, Enum):
     RW = "rw"  # read-write: skip on hit, write on build
     RO = "ro"  # read-only: skip on hit, build on miss (no writes)
diff --git a/src/fastflowtransform/cli/run.py b/src/fastflowtransform/cli/run.py
index 530a7d3..5c35205 100644
--- a/src/fastflowtransform/cli/run.py
+++ b/src/fastflowtransform/cli/run.py
@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import logging
 import os
 import textwrap
 import threading
@@ -8,42 +7,57 @@
 from collections.abc import Callable
 from contextlib import suppress
 from dataclasses import dataclass, field
+from datetime import UTC, datetime
 from typing import Any
 
 import typer
 
-from fastflowtransform.cache import FingerprintCache, can_skip_node
-from fastflowtransform.core import REGISTRY, relation_for
-from fastflowtransform.dag import levels as dag_levels
-from fastflowtransform.fingerprint import (
-    EnvCtx,
-    build_env_ctx,
-    fingerprint_py,
-    fingerprint_sql,
-    get_function_source,
+from fastflowtransform.artifacts import (
+    RunNodeResult,
+    write_catalog,
+    write_manifest,
+    write_run_results,
 )
-from fastflowtransform.log_queue import LogQueue
-from fastflowtransform.meta import ensure_meta_table
-from fastflowtransform.run_executor import ScheduleResult, schedule
-
-from .bootstrap import _prepare_context
-from .logging_utils import LOG
-from .options import (
+from fastflowtransform.cache import FingerprintCache, can_skip_node
+from fastflowtransform.cli.bootstrap import CLIContext, _prepare_context
+from fastflowtransform.cli.options import (
     CacheMode,
     CacheOpt,
     EngineOpt,
     EnvOpt,
     ExcludeOpt,
+    HttpCacheOpt,
     JobsOpt,
     KeepOpt,
     NoCacheOpt,
+    OfflineOpt,
     ProjectArg,
     RebuildAllOpt,
     RebuildOnlyOpt,
     SelectOpt,
     VarsOpt,
 )
-from .selectors import _compile_selector, _parse_select, _selected_subgraph_names
+from fastflowtransform.core import REGISTRY, relation_for
+from fastflowtransform.dag import levels as dag_levels
+from fastflowtransform.fingerprint import (
+    EnvCtx,
+    build_env_ctx,
+    fingerprint_py,
+    fingerprint_sql,
+    get_function_source,
+)
+from fastflowtransform.incremental import run_or_dispatch as run_sql_with_incremental
+from fastflowtransform.log_queue import LogQueue
+from fastflowtransform.logging import bind_context, bound_context, clear_context, echo, warn
+from fastflowtransform.meta import ensure_meta_table
+from fastflowtransform.run_executor import ScheduleResult, schedule
+
+from .selectors import (
+    _compile_selector,
+    _parse_select,
+    _selected_subgraph_names,
+    augment_with_state_modified,
+)
 
 
 @dataclass
@@ -59,10 +73,10 @@ class _RunEngine:
     env_ctx: EnvCtx = field(init=False)
     computed_fps: dict[str, str] = field(default_factory=dict, init=False)
     fps_lock: threading.Lock = field(default_factory=threading.Lock, init=False)
+    http_snaps: dict[str, dict] = field(default_factory=dict, init=False)
 
     def __post_init__(self) -> None:
-        if LOG.isEnabledFor(logging.INFO):
-            typer.echo(f"Profile: {self.env_name} | Engine: {self.ctx.profile.engine}")
+        echo(f"Profile: {self.env_name} | Engine: {self.ctx.profile.engine}")
         self.shared = self.ctx.make_executor()
         with suppress(Exception):
             ensure_meta_table(self.shared[0])
@@ -81,18 +95,23 @@ def __post_init__(self) -> None:
     def _get_runner(self) -> tuple[Any, Callable, Callable]:
         if getattr(self.tls, "runner", None) is None:
             ex, run_sql_shared, run_py_shared = self.shared
-            run_sql_fn, run_py_fn = run_sql_shared, run_py_shared
+            run_sql_wrapped, run_py_wrapped = run_sql_shared, run_py_shared
             if self.ctx.profile.engine == "duckdb" and hasattr(ex, "clone"):
                 try:
-                    ex = ex.clone()
+                    db_path = getattr(ex, "db_path", None)
+                    clone_needed = not (isinstance(db_path, str) and db_path.strip() == ":memory:")
+                    if clone_needed:
+                        ex = ex.clone()
 
-                    def run_sql_fn(n):
-                        return ex.run_sql(n, self.ctx.jinja_env)
+                    def _run_sql_duckdb(n):
+                        # Planner: intercept incremental materializations
+                        return run_sql_with_incremental(ex, n, self.ctx.jinja_env)
 
-                    run_py_fn = ex.run_python
+                    run_sql_wrapped = _run_sql_duckdb
+                    run_py_wrapped = ex.run_python
                 except Exception:
                     pass
-            self.tls.runner = (ex, run_sql_fn, run_py_fn)
+            self.tls.runner = (ex, run_sql_wrapped, run_py_wrapped)
         return self.tls.runner
 
     def _maybe_fingerprint(self, node: Any, ex: Any) -> str | None:
@@ -138,6 +157,11 @@ def run_node(self, name: str) -> None:
                     self.computed_fps[name] = cand_fp
                 with suppress(Exception):
                     ex.on_node_built(node, relation_for(name), cand_fp)
+            # HTTP snapshot (stored in node.meta by the executor)
+            with suppress(Exception):
+                snap = (getattr(node, "meta", {}) or {}).get("_http_snapshot")
+                if snap:
+                    self.http_snaps[name] = snap
             return
 
         cand_fp = self._maybe_fingerprint(node, ex)
@@ -162,6 +186,11 @@ def run_node(self, name: str) -> None:
                 self.computed_fps[name] = cand_fp
             with suppress(Exception):
                 ex.on_node_built(node, relation_for(name), cand_fp)
+        # HTTP snapshot (stored in node.meta by the executor)
+        with suppress(Exception):
+            snap = (getattr(node, "meta", {}) or {}).get("_http_snapshot")
+            if snap:
+                self.http_snaps[name] = snap
 
     @staticmethod
     def before(_name: str, lvl_idx: int | None = None) -> None:
@@ -171,7 +200,7 @@ def before(_name: str, lvl_idx: int | None = None) -> None:
     def on_error(name: str, err: BaseException) -> None:
         _node = REGISTRY.get_node(name)
         if isinstance(err, KeyError):
-            typer.echo(
+            echo(
                 _error_block(
                     f"Model failed: {name} (KeyError)",
                     _pretty_exc(err),
@@ -185,7 +214,7 @@ def on_error(name: str, err: BaseException) -> None:
         body = _pretty_exc(err)
         if os.getenv("FFT_TRACE") == "1":
             body += "\n\n" + traceback.format_exc()
-        typer.echo(_error_block(f"Model failed: {name}", body, "• See cause above."))
+        echo(_error_block(f"Model failed: {name}", body, "• See cause above."))
         raise typer.Exit(1) from err
 
     def persist_on_success(self, result: ScheduleResult) -> None:
@@ -197,12 +226,12 @@ def persist_on_success(self, result: ScheduleResult) -> None:
     def print_timings(result: ScheduleResult) -> None:
         if not result.per_node_s:
             return
-        typer.echo("\nRuntime per model")
-        typer.echo("─────────────────")
+        echo("\nRuntime per model")
+        echo("─────────────────")
         for name in sorted(result.per_node_s, key=lambda k: k):
             ms = int(result.per_node_s[name] * 1000)
-            typer.echo(f"• {name:<30} {ms:>6} ms")
-        typer.echo(f"\nTotal runtime: {result.total_s:.3f}s")
+            echo(f"• {name:<30} {ms:>6} ms")
+        echo(f"\nTotal runtime: {result.total_s:.3f}s")
 
 
 def _pretty_exc(e: BaseException) -> str:
@@ -213,7 +242,7 @@ def _error_block(title: str, body: str, hint: str | None = None) -> str:
     border = "─" * 70
     lines = [f"✖ {title}", "", textwrap.dedent(body).rstrip()]
     if hint:
-        lines = ["", "Hints:", textwrap.dedent(hint).rstrip()]
+        lines += ["", "Hints:", textwrap.dedent(hint).rstrip()]
     text = "│ \n│ ".join("\n".join(lines).splitlines())
     return f"\n┌{border}\n{text}\n└{border}\n"
 
@@ -224,105 +253,222 @@ def _normalize_node_names_or_warn(names: list[str] | None) -> set[str]:
         try:
             out.add(REGISTRY.get_node(tok).name)
         except KeyError:
-            LOG.warning(f"Unknown model in --rebuild: {tok}")
+            warn(f"Unknown model in --rebuild: {tok}")
     return out
 
 
-def run(
-    project: ProjectArg = ".",
-    env_name: EnvOpt = "dev",
-    engine: EngineOpt = None,
-    vars: VarsOpt = None,
-    select: SelectOpt = None,
-    exclude: ExcludeOpt = None,
-    jobs: JobsOpt = 1,
-    keep_going: KeepOpt = False,
-    cache: CacheOpt = CacheMode.RW,
-    no_cache: NoCacheOpt = False,
-    rebuild: RebuildAllOpt = False,
-    rebuild_only: RebuildOnlyOpt = None,
-) -> None:
+def _abbr(e: str) -> str:
+    mapping = {
+        "duckdb": "DUCK",
+        "postgres": "PG",
+        "bigquery": "BQ",
+        "databricks_spark": "SPK",
+        "snowflake_snowpark": "SNOW",
+    }
+    return mapping.get(e, e.upper()[:4])
+
+
+# ----------------- helpers (run function) -----------------
+
+
+def _build_engine_ctx(project, env_name, engine, vars, cache, no_cache):
     ctx = _prepare_context(project, env_name, engine, vars)
     cache_mode = CacheMode.OFF if no_cache else cache
+    engine_ = _RunEngine(
+        ctx=ctx, pred=None, env_name=env_name, cache_mode=cache_mode, force_rebuild=set()
+    )
+    return ctx, engine_
+
 
-    _, raw_pred = _compile_selector(select)
-    raw_selected: list[str] = [k for k, v in REGISTRY.nodes.items() if raw_pred(v)]
+def _select_predicate_and_raw(
+    executor_engine: _RunEngine, ctx: CLIContext, select: SelectOpt
+) -> tuple[list[str], Callable[[Any], bool], list[str]]:
+    select_tokens = _parse_select(select or [])
+    base_tokens = [t for t in select_tokens if not t.startswith("state:modified")]
+    _, base_pred = _compile_selector(base_tokens)
 
-    wanted: set[str] = _selected_subgraph_names(
+    select_pred = base_pred
+    if select_tokens and any(t.startswith("state:modified") for t in select_tokens):
+        executor = executor_engine.shared[0]
+        modified_set = executor_engine.cache.modified_set(ctx.jinja_env, executor)
+        select_pred = augment_with_state_modified(select_tokens, base_pred, modified_set)
+
+    raw_selected = [k for k, v in REGISTRY.nodes.items() if select_pred(v)]
+    return select_tokens, select_pred, raw_selected
+
+
+def _wanted_names(
+    select_tokens: list[str], exclude: ExcludeOpt, raw_selected: list[str]
+) -> set[str]:
+    return _selected_subgraph_names(
         REGISTRY.nodes,
-        select_tokens=select,
+        select_tokens=select_tokens,
         exclude_tokens=exclude,
+        seed_names=set(raw_selected),
     )
 
-    rebuild_only_names = _normalize_node_names_or_warn(rebuild_only)
 
-    explicit_targets: list[str] = []
+def _explicit_targets(
+    rebuild_only: RebuildOnlyOpt, rebuild: bool, select: SelectOpt, raw_selected: list[str]
+) -> list[str]:
+    rebuild_only_names = _normalize_node_names_or_warn(rebuild_only)
     if rebuild_only_names:
-        explicit_targets = [n for n in (rebuild_only or []) if n in REGISTRY.nodes]
-    elif rebuild and select:
-        explicit_targets = raw_selected
+        return [n for n in (rebuild_only or []) if n in REGISTRY.nodes]
+    if rebuild and select:
+        return raw_selected
+    return []
+
 
+def _maybe_exit_if_empty(wanted: set[str], explicit_targets: list[str]) -> None:
     if not wanted and not explicit_targets:
         typer.secho(
-            "Nothing to run (empty selection after applying --select/--exclude).",
-            fg="yellow",
+            "Nothing to run (empty selection after applying --select/--exclude).", fg="yellow"
         )
         raise typer.Exit(0)
 
+
+def _compute_force_rebuild(
+    explicit_targets: list[str], rebuild: bool, wanted: set[str]
+) -> set[str]:
     if explicit_targets:
-        force_rebuild = set(explicit_targets)
-    elif rebuild:
-        force_rebuild = set(wanted)
-    else:
-        force_rebuild = set()
+        return set(explicit_targets)
+    if rebuild:
+        return set(wanted)
+    return set()
 
+
+def _levels_for_run(explicit_targets: list[str], wanted: set[str]) -> list[list[str]]:
     if explicit_targets:
-        lvls = [explicit_targets]
-    else:
-        sub_nodes = {k: v for k, v in REGISTRY.nodes.items() if k in wanted}
-        lvls = dag_levels(sub_nodes)
+        return [explicit_targets]
+    sub_nodes = {k: v for k, v in REGISTRY.nodes.items() if k in wanted}
+    return dag_levels(sub_nodes)
 
-    engine_ = _RunEngine(
-        ctx=ctx,
-        pred=None,
-        env_name=env_name,
-        cache_mode=cache_mode,
-        force_rebuild=force_rebuild,
-    )
 
+def _run_schedule(engine_, lvls, jobs, keep_going, ctx):
     logq = LogQueue()
+    started_at = datetime.now(UTC).isoformat(timespec="seconds")
 
-    def _abbr(e: str) -> str:
-        mapping = {
-            "duckdb": "DUCK",
-            "postgres": "PG",
-            "bigquery": "BQ",
-            "databricks_spark": "SPK",
-            "snowflake_snowpark": "SNOW",
-        }
-        return mapping.get(e, e.upper()[:4])
-
-    result: ScheduleResult = schedule(
+    bind_context(run_id=started_at)
+
+    def _run_node_with_ctx(name: str) -> None:
+        with bound_context(node=name):
+            engine_.run_node(name)
+
+    result = schedule(
         lvls,
         jobs=jobs,
         fail_policy="keep_going" if keep_going else "fail_fast",
-        run_node=engine_.run_node,
+        run_node=_run_node_with_ctx,
         before=engine_.before,
         on_error=None,
         logger=logq,
         engine_abbr=_abbr(ctx.profile.engine),
         name_width=28,
     )
+
+    finished_at = datetime.now(UTC).isoformat(timespec="seconds")
+    return result, logq, started_at, finished_at
+
+
+def _write_artifacts(
+    ctx: CLIContext, result: ScheduleResult, started_at: str, finished_at: str, engine_: _RunEngine
+) -> None:
+    write_manifest(ctx.project)
+
+    node_results: list[RunNodeResult] = []
+    failed = result.failed or {}
+    all_names = set(result.per_node_s.keys()) | set(failed.keys())
+
+    for name in sorted(all_names):
+        dur_s = float(result.per_node_s.get(name, 0.0))
+        status = "error" if name in failed else "success"
+        msg = str(failed.get(name)) if name in failed else None
+        node_results.append(
+            RunNodeResult(
+                name=name,
+                status=status,
+                started_at=started_at,
+                finished_at=finished_at,
+                duration_ms=int(dur_s * 1000),
+                message=msg,
+                http=engine_.http_snaps.get(name),
+            )
+        )
+
+    write_run_results(
+        ctx.project, started_at=started_at, finished_at=finished_at, node_results=node_results
+    )
+
+
+def _attempt_catalog(ctx: CLIContext) -> None:
+    try:
+        execu, _, _ = ctx.make_executor()
+        write_catalog(ctx.project, execu)
+    except Exception:
+        pass
+
+
+def _emit_logs_and_errors(logq: LogQueue, result: ScheduleResult, engine_: _RunEngine) -> None:
     for line in logq.drain():
-        typer.echo(line)
+        echo(line)
     if result.failed:
         for name, err in result.failed.items():
             engine_.on_error(name, err)
+
+
+# ----------------- run function -----------------
+
+
+def run(
+    project: ProjectArg = ".",
+    env_name: EnvOpt = "dev",
+    engine: EngineOpt = None,
+    vars: VarsOpt = None,
+    select: SelectOpt = None,
+    exclude: ExcludeOpt = None,
+    jobs: JobsOpt = 1,
+    keep_going: KeepOpt = False,
+    cache: CacheOpt = CacheMode.RW,
+    no_cache: NoCacheOpt = False,
+    rebuild: RebuildAllOpt = False,
+    rebuild_only: RebuildOnlyOpt = None,
+    offline: OfflineOpt = False,
+    http_cache: HttpCacheOpt = None,
+) -> None:
+    # _ensure_logging()
+    # HTTP/API-Flags → ENV, damit fastflowtransform.api.http sie liest
+    if offline:
+        os.environ["FF_HTTP_OFFLINE"] = "1"
+    if http_cache:
+        os.environ["FF_HTTP_CACHE_MODE"] = str(
+            http_cache.value if hasattr(http_cache, "value") else http_cache
+        )
+
+    ctx, engine_ = _build_engine_ctx(project, env_name, engine, vars, cache, no_cache)
+    bind_context(engine=ctx.profile.engine, env=env_name)
+
+    select_tokens, _, raw_selected = _select_predicate_and_raw(engine_, ctx, select)
+    wanted = _wanted_names(select_tokens=select_tokens, exclude=exclude, raw_selected=raw_selected)
+
+    explicit_targets = _explicit_targets(rebuild_only, rebuild, select, raw_selected)
+    _maybe_exit_if_empty(wanted, explicit_targets)
+
+    engine_.force_rebuild = _compute_force_rebuild(explicit_targets, rebuild, wanted)
+    lvls = _levels_for_run(explicit_targets, wanted)
+
+    result, logq, started_at, finished_at = _run_schedule(engine_, lvls, jobs, keep_going, ctx)
+
+    _write_artifacts(ctx, result, started_at, finished_at, engine_)
+    _attempt_catalog(ctx)
+    _emit_logs_and_errors(logq, result, engine_)
+
     if result.failed:
         raise typer.Exit(1)
+
     engine_.persist_on_success(result)
     engine_.print_timings(result)
-    typer.echo("✓ Done")
+    echo("✓ Done")
+    clear_context()
 
 
 def register(app: typer.Typer) -> None:
diff --git a/src/fastflowtransform/cli/seed_cmd.py b/src/fastflowtransform/cli/seed_cmd.py
index ebea43c..444f02e 100644
--- a/src/fastflowtransform/cli/seed_cmd.py
+++ b/src/fastflowtransform/cli/seed_cmd.py
@@ -2,10 +2,26 @@
 
 import typer
 
-from fastflowtransform.seeding import seed_project
+from fastflowtransform.cli.bootstrap import _prepare_context
+from fastflowtransform.cli.options import EngineOpt, EnvOpt, ProjectArg, VarsOpt
+from fastflowtransform.logging import echo
+from fastflowtransform.seeding import _human_int, seed_project
 
-from .bootstrap import _prepare_context
-from .options import EngineOpt, EnvOpt, ProjectArg, VarsOpt
+# def seed(
+#     project: ProjectArg = ".",
+#     env_name: EnvOpt = "dev",
+#     engine: EngineOpt = None,
+#     vars: VarsOpt = None,
+# ) -> None:
+#     ctx = _prepare_context(project, env_name, engine, vars)
+#     execu, _, _ = ctx.make_executor()
+
+#     schema: str | None = None
+#     if ctx.profile.engine == "postgres":
+#         schema = ctx.profile.postgres.db_schema
+
+#     n = seed_project(ctx.project, execu, schema)
+#     echo(f"✓ Seeded {n} table(s)")
 
 
 def seed(
@@ -14,15 +30,22 @@ def seed(
     engine: EngineOpt = None,
     vars: VarsOpt = None,
 ) -> None:
+    """
+    High-level entry to run seeding for a project:
+      1) Prepare the runtime context and executor.
+      2) Resolve per-file targets using seeds/schema.yml.
+      3) Materialize each seed via the engine-specific path.
+    """
     ctx = _prepare_context(project, env_name, engine, vars)
     execu, _, _ = ctx.make_executor()
 
-    schema: str | None = None
-    if ctx.profile.engine == "postgres":
-        schema = ctx.profile.postgres.db_schema
+    # You can still pass a global default schema; per-file CFG will override it.
+    default_schema: str | None = None
+    if getattr(ctx.profile, "engine", None) == "postgres":
+        default_schema = getattr(getattr(ctx.profile, "postgres", None), "db_schema", None)
 
-    n = seed_project(ctx.project, execu, schema)
-    typer.echo(f"✓ Seeded {n} table(s)")
+    n = seed_project(ctx.project, execu, default_schema)
+    echo(f"✓ Seeded {_human_int(n)} table(s)")
 
 
 def register(app: typer.Typer) -> None:
diff --git a/src/fastflowtransform/cli/selectors.py b/src/fastflowtransform/cli/selectors.py
index 8a89a37..65b6776 100644
--- a/src/fastflowtransform/cli/selectors.py
+++ b/src/fastflowtransform/cli/selectors.py
@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 import fnmatch
+import json
 from collections.abc import Callable, Iterable
 from typing import Any, cast
 
-from fastflowtransform.core import relation_for
+from fastflowtransform.core import REGISTRY, relation_for
 
 
 def _parse_select(parts: list[str]) -> list[str]:
@@ -29,20 +30,89 @@ def _build_predicates(tokens: list[str]) -> list[Callable[[Any], bool]]:
       - tag:<tag> : matches Node.meta['tags'] (list or str)
       - type:<view|table|ephemeral> : matches Node.meta['materialized'] (default 'table')
       - kind:<sql|python> : matches Node.kind
+      - result:<ok|error|fail|warn> : matches last run_results.json
     AND across tokens.
     """
     preds: list[Callable[[Any], bool]] = []
+    # --- Lazy loader for run_results.json (cached per call) ---
+    results_cache: dict[str, set[str]] | None = None
+
+    def _load_result_sets() -> dict[str, set[str]]:
+        """
+        Load last run_results.json and build name-sets:
+          ok:    status == 'success'
+          error: status == 'error'
+          fail:  synonym for error
+          warn:  warnings>0 OR 'warn' in message (best-effort)
+        If file is missing/corrupt, all sets are empty.
+        """
+        nonlocal results_cache
+        if results_cache is not None:
+            return results_cache
+        ok: set[str] = set()
+        err: set[str] = set()
+        wrn: set[str] = set()
+        try:
+            proj = REGISTRY.get_project_dir()
+            path = proj / ".fastflowtransform" / "target" / "run_results.json"
+            data = json.loads(path.read_text(encoding="utf-8"))
+            for r in data.get("results") or []:
+                name = r.get("name")
+                status = (r.get("status") or "").lower()
+                message = (r.get("message") or "") or ""
+                warnings = r.get("warnings", 0)
+                if not name or not isinstance(name, str):
+                    continue
+                if status == "success":
+                    ok.add(name)
+                elif status == "error":
+                    err.add(name)
+                # best-effort warning detection
+                if (isinstance(warnings, int) and warnings > 0) or (
+                    isinstance(message, str) and "warn" in message.lower()
+                ):
+                    wrn.add(name)
+        except Exception:
+            # No file or malformed → empty sets
+            pass
+        # Define "ok" as success **without** warnings:
+        ok_no_warn = ok - wrn
+        results_cache = {
+            "ok": ok_no_warn,
+            "error": err,
+            "fail": set(err),
+            "warn": wrn,
+        }
+        return results_cache
+
     for tok in tokens:
+        if tok.startswith("result:"):
+            want = tok.split(":", 1)[1].lower()
+            # normalize aliases
+            if want not in {"ok", "error", "fail", "warn"}:
+                # Unknown result token → match nothing (don't raise)
+                preds.append(lambda _n: False)
+                continue
+
+            def _p_result(n, w=want):
+                sets = _load_result_sets()
+                # default to empty set if missing
+                names = sets.get(w) or set()
+                return n.name in names
+
+            preds.append(_p_result)
+            continue
+
         if tok.startswith("tag:"):
             want = tok.split(":", 1)[1]
 
-            def _p(n, w=want):
+            def _p_tag(n, w=want):
                 tags = (getattr(n, "meta", {}) or {}).get("tags")
                 if isinstance(tags, list):
                     return w in tags
                 return tags == w
 
-            preds.append(_p)
+            preds.append(_p_tag)
         elif tok.startswith("type:"):
             want = tok.split(":", 1)[1]
             preds.append(
@@ -67,18 +137,66 @@ def _p(n, w=want):
     return preds
 
 
+def _downstream_closure(names: set[str]) -> set[str]:
+    """Return names plus all downstream nodes (transitively)."""
+    # Build reverse edges: dep -> [dependents]
+    rev: dict[str, list[str]] = {}
+    for n, node in REGISTRY.nodes.items():
+        for d in node.deps or []:
+            rev.setdefault(d, []).append(n)
+    out = set(names)
+    frontier = list(names)
+    while frontier:
+        cur = frontier.pop()
+        for nxt in rev.get(cur, []):
+            if nxt not in out:
+                out.add(nxt)
+                frontier.append(nxt)
+    return out
+
+
 def _compile_selector(
     select_opt: list[str] | None,
 ) -> tuple[list[str], Callable[[Any], bool]]:
-    """Normalize `--select` values and return tokens plus predicate."""
+    """Normalize `--select` values and return (tokens, base_predicate).
+    NOTE: state:modified logic is handled at command layer via augment_with_state_modified().
+    """
     tokens = _parse_select(select_opt or [])
-    return tokens, _selector(_build_predicates(tokens))
+    preds = _build_predicates(tokens)
+    return tokens, _selector(preds)
+
+
+def augment_with_state_modified(
+    tokens: list[str],
+    base_pred: Callable[[Any], bool],
+    modified: set[str],
+) -> Callable[[Any], bool]:
+    """
+    Combine a base predicate with state:modified tokens.
+    - 'state:modified'    → filter to modified only
+    - 'state:modified+'   → filter to modified union downstream(modified)
+    - Combined with other tokens → logical AND with base predicate
+    """
+    if not any(t.startswith("state:modified") for t in tokens):
+        return base_pred
+
+    plus = any(t.startswith("state:modified+") for t in tokens)
+    state_set = set(modified)
+    if plus:
+        state_set = _downstream_closure(state_set)
+
+    other_tokens = [t for t in tokens if not t.startswith("state:modified")]
+    if not other_tokens:
+        return lambda n: n.name in state_set
+    return lambda n: (n.name in state_set) and base_pred(n)
 
 
 def _selected_subgraph_names(
     nodes: dict[str, Any],
     select_tokens: list[str] | None,
     exclude_tokens: list[str] | None,
+    *,
+    seed_names: set[str] | None = None,
 ) -> set[str]:
     """
     Compute the reduced set of node names to execute:
@@ -95,7 +213,10 @@ def _selected_subgraph_names(
     _, ex_pred = _compile_selector(exclude_tokens or [])
 
     all_names = set(nodes.keys())
-    seeds = {n for n in all_names if (sel_pred(nodes[n]) if select_tokens else True)}
+    if seed_names is not None:
+        seeds = {n for n in seed_names if n in all_names}
+    else:
+        seeds = {n for n in all_names if (sel_pred(nodes[n]) if select_tokens else True)}
     if not seeds:
         return set()
 
diff --git a/src/fastflowtransform/cli/sync_db_comments_cmd.py b/src/fastflowtransform/cli/sync_db_comments_cmd.py
index 687f45c..a4f72c6 100644
--- a/src/fastflowtransform/cli/sync_db_comments_cmd.py
+++ b/src/fastflowtransform/cli/sync_db_comments_cmd.py
@@ -6,12 +6,11 @@
 import typer
 from sqlalchemy import text as sa_text
 
+from fastflowtransform.cli.bootstrap import _prepare_context
+from fastflowtransform.cli.options import EngineOpt, EnvOpt, ProjectArg, VarsOpt
 from fastflowtransform.core import REGISTRY, relation_for
 from fastflowtransform.docs import _collect_columns, read_docs_metadata
-
-from .bootstrap import _prepare_context
-from .logging_utils import LOG
-from .options import EngineOpt, EnvOpt, ProjectArg, VarsOpt
+from fastflowtransform.logging import echo, error
 
 
 def _strip_html_for_comment(s: str | None) -> str:
@@ -53,9 +52,9 @@ def _sync_comments_postgres(
             statements.append(f"COMMENT ON COLUMN {fqtn}.{col} IS {_sql_literal(txt)};")
 
     if dry_run:
-        typer.echo("\n-- DRY RUN: Planned Postgres COMMENT statements --")
+        echo("\n-- DRY RUN: Planned Postgres COMMENT statements --")
         for s in statements:
-            typer.echo(s)
+            echo(s)
         return
 
     if not hasattr(execu, "engine"):
@@ -70,9 +69,9 @@ def _sync_comments_postgres(
                 applied += 1
             except Exception as e:
                 failed += 1
-                LOG.error("Failed to apply comment: %s  (%s: %s)", s, type(e).__name__, e)
+                error("Failed to apply comment: %s  (%s: %s)", s, type(e).__name__, e)
 
-    typer.echo(f"✓ Postgres comments applied: {applied} (failed: {failed})")
+    echo(f"✓ Postgres comments applied: {applied} (failed: {failed})")
 
 
 def _sf_fq_table(schema: str | None, relation: str) -> str:
@@ -98,9 +97,9 @@ def _sync_comments_snowflake(
             statements.append(f"COMMENT ON COLUMN {fqtn}.{col} IS {lit}")
 
     if dry_run:
-        typer.echo("\n-- DRY RUN: Planned Snowflake COMMENT statements --")
+        echo("\n-- DRY RUN: Planned Snowflake COMMENT statements --")
         for s in statements:
-            typer.echo(s + ";")
+            echo(s + ";")
         return
 
     applied, failed = 0, 0
@@ -117,12 +116,12 @@ def _run_sql(stmt: str) -> None:
             applied += 1
         except Exception as e:
             failed += 1
-            LOG.error("Failed to apply comment: %s  (%s: %s)", stmt, type(e).__name__, e)
+            error("Failed to apply comment: %s  (%s: %s)", stmt, type(e).__name__, e)
 
     for s in statements:
         _run_sql(s)
 
-    typer.echo(f"✓ Snowflake comments applied: {applied} (failed: {failed})")
+    echo(f"✓ Snowflake comments applied: {applied} (failed: {failed})")
 
 
 def sync_db_comments(
diff --git a/src/fastflowtransform/cli/test_cmd.py b/src/fastflowtransform/cli/test_cmd.py
index 58fb71b..92d91eb 100644
--- a/src/fastflowtransform/cli/test_cmd.py
+++ b/src/fastflowtransform/cli/test_cmd.py
@@ -11,18 +11,21 @@
 import yaml
 
 from fastflowtransform import testing
-from fastflowtransform.core import REGISTRY
-from fastflowtransform.dag import topo_sort
-
-from .bootstrap import _get_test_con, _prepare_context
-from .options import (
+from fastflowtransform.cli.bootstrap import _get_test_con, _prepare_context
+from fastflowtransform.cli.options import (
     EngineOpt,
     EnvOpt,
     ProjectArg,
     SelectOpt,
     VarsOpt,
 )
-from .selectors import _compile_selector
+from fastflowtransform.cli.selectors import _compile_selector
+from fastflowtransform.core import REGISTRY
+from fastflowtransform.dag import topo_sort
+from fastflowtransform.errors import ModelExecutionError
+from fastflowtransform.logging import echo
+from fastflowtransform.schema_loader import Severity, TestSpec, load_schema_tests
+from fastflowtransform.test_registry import TESTS
 
 
 @dataclass
@@ -33,6 +36,22 @@ class DQResult:
     ok: bool
     msg: str | None
     ms: int
+    severity: Severity = "error"
+    param_str: str = ""
+    example_sql: str | None = None
+
+
+def _print_model_error_block(node_name: str, relation: str, message: str, sql: str | None) -> None:
+    header = "┌" + "─" * 70
+    footer = "└" + "─" * 70
+    echo(header)
+    echo(f"│ Model: {node_name}  (relation: {relation})")
+    echo(f"│ Error: {message}")
+    if sql:
+        echo("│ SQL (tail):")
+        for line in sql.splitlines():
+            echo("│   " + line)
+    echo(footer)
 
 
 def _execute_models(
@@ -51,13 +70,17 @@ def _execute_models(
             (run_sql if node.kind == "sql" else run_py)(node)
         except Exception as exc:
             if on_error is None:
-                raise
+                # Convert known domain error to friendly output
+                if isinstance(exc, ModelExecutionError):
+                    _print_model_error_block(exc.node_name, exc.relation, str(exc), exc.sql_snippet)
+                    raise typer.Exit(1) from exc
+                raise Exception from exc
             on_error(name, node, exc)
 
 
 def _maybe_print_marker(con: Any) -> None:
     if os.getenv("FFT_SQL_DEBUG") == "1":
-        typer.echo(getattr(con, "marker", "NO_SHIM"))
+        echo(getattr(con, "marker", "NO_SHIM"))
 
 
 def _run_models(
@@ -85,60 +108,109 @@ def _is_legacy_test_token(tokens: list[str]) -> bool:
 
 
 def _apply_legacy_tag_filter(
-    tests: list[dict], tokens: list[str], *, legacy_token: bool
-) -> list[dict]:
+    tests: list[Any], tokens: list[str], *, legacy_token: bool
+) -> list[Any]:
     if not legacy_token:
         return tests
     legacy_tag = tokens[0]
 
-    def has_tag(t: dict) -> bool:
-        tags = t.get("tags") or []
-        return (legacy_tag in tags) if isinstance(tags, list) else (legacy_tag == tags)
+    def has_tag(t: Any) -> bool:
+        # Dict (altes Format)
+        if isinstance(t, dict):
+            tags = t.get("tags") or []
+            return (legacy_tag in tags) if isinstance(tags, list) else (legacy_tag == tags)
+        # TestSpec (neues Schema)
+        if isinstance(t, TestSpec):
+            return legacy_tag in (t.tags or [])
+        return False
 
     return [t for t in tests if has_tag(t)]
 
 
-def _run_dq_tests(con: Any, tests: Iterable[dict]) -> list[DQResult]:
+def _run_dq_tests(con: Any, tests: Iterable[Any]) -> list[DQResult]:
     results: list[DQResult] = []
     for t in tests:
-        kind = t["type"]
-        table: str | None = None
-        col: str | None = None
-        if kind.startswith("reconcile_"):
-            if "left" in t and "right" in t:
-                lt = (t.get("left") or {}).get("table")
-                rt = (t.get("right") or {}).get("table")
-                table = f"{lt} ⇔ {rt}"
-            elif "source" in t and "target" in t:
-                st = (t.get("source") or {}).get("table")
-                tt = (t.get("target") or {}).get("table")
-                table = f"{st} ⇒ {tt}"
-            else:
-                table = "<reconcile>"
+        severity: Severity
+        if isinstance(t, TestSpec):
+            kind = t.type
+            col = t.column
+            severity = t.severity
+            params: dict[str, Any] = t.params or {}
+            display_table = t.table
+            table_for_exec = t.table
         else:
-            table = t.get("table")
-            if not isinstance(table, str) or not table:
-                raise typer.BadParameter("Missing or invalid 'table' in test config")
+            kind = t["type"]
+            _sev = str(t.get("severity", "error")).lower()
+            severity = "warn" if _sev == "warn" else "error"
+            params = dict(t)
             col = t.get("column")
+            if kind.startswith("reconcile_"):
+                if isinstance(t.get("left"), dict) and isinstance(t.get("right"), dict):
+                    lt = (t.get("left") or {}).get("table")
+                    rt = (t.get("right") or {}).get("table")
+                    display_table = f"{lt} ⇔ {rt}"
+                elif isinstance(t.get("source"), dict) and isinstance(t.get("target"), dict):
+                    st = (t.get("source") or {}).get("table")
+                    tt = (t.get("target") or {}).get("table")
+                    display_table = f"{st} ⇒ {tt}"
+                else:
+                    display_table = "<reconcile>"
+                table_for_exec = t.get("table")
+            else:
+                table_for_exec = t.get("table")
+                if not isinstance(table_for_exec, str) or not table_for_exec:
+                    raise typer.BadParameter("Missing or invalid 'table' in test config")
+                display_table = table_for_exec
 
+        # Dispatch via registry if available; otherwise fallback to legacy map
         t0 = time.perf_counter()
-        ok, msg = _exec_test_kind(con, kind, t, table, col)
+        if kind in TESTS:
+            ok, msg, example = TESTS[kind](con, table_for_exec, col, params)
+        else:
+            ok, msg = _exec_test_kind(con, kind, params, table_for_exec, col)
+            example = None
         ms = int((time.perf_counter() - t0) * 1000)
 
-        results.append(DQResult(kind=kind, table=table, column=col, ok=ok, msg=msg, ms=ms))
+        # Build short parameter display for the summary line
+        param_str = _format_params_for_summary(kind, params)
+
+        results.append(
+            DQResult(
+                kind=kind,
+                table=str(display_table),
+                column=col,
+                ok=ok,
+                msg=msg,
+                ms=ms,
+                severity=severity,
+                param_str=param_str,
+                example_sql=example,
+            )
+        )
     return results
 
 
 def _exec_test_kind(con: Any, kind: str, t: dict, table: Any, col: Any) -> tuple[bool, str | None]:
+    # Guard for column-required tests in legacy path
+    def _need_col() -> str:
+        if not isinstance(col, str) or not col:
+            raise typer.BadParameter(f"Test '{kind}' requires a non-empty 'column' parameter")
+        return col
+
     try_map = {
-        "not_null": lambda: testing.not_null(con, table, col),
-        "unique": lambda: testing.unique(con, table, col),
-        "greater_equal": lambda: testing.greater_equal(con, table, col, t.get("threshold", 0)),
-        "non_negative_sum": lambda: testing.non_negative_sum(con, table, col),
+        "not_null": lambda: testing.not_null(con, table, _need_col()),
+        "unique": lambda: testing.unique(con, table, _need_col()),
+        "greater_equal": lambda: testing.greater_equal(
+            con, table, _need_col(), t.get("threshold", 0)
+        ),
+        "non_negative_sum": lambda: testing.non_negative_sum(con, table, _need_col()),
         "row_count_between": lambda: testing.row_count_between(
             con, table, t.get("min", 1), t.get("max")
         ),
-        "freshness": lambda: testing.freshness(con, table, col, t["max_delay_minutes"]),
+        "freshness": lambda: testing.freshness(con, table, _need_col(), t["max_delay_minutes"]),
+        "accepted_values": lambda: testing.accepted_values(
+            con, table, col, values=t.get("values", []), where=t.get("where")
+        ),
         "reconcile_equal": lambda: testing.reconcile_equal(
             con,
             t["left"],
@@ -183,21 +255,57 @@ def _exec_test_kind(con: Any, kind: str, t: dict, table: Any, col: Any) -> tuple
 
 def _print_summary(results: list[DQResult]) -> None:
     passed = sum(1 for r in results if r.ok)
-    failed = len(results) - passed
+    failed = sum((not r.ok) and (r.severity != "warn") for r in results)
+    warned = sum((not r.ok) and (r.severity == "warn") for r in results)
 
-    typer.echo("\nData Quality Summary")
-    typer.echo("────────────────────")
+    echo("\nData Quality Summary")
+    echo("────────────────────")
     for r in results:
-        mark = "✅" if r.ok else "❌"
+        mark = "✅" if r.ok else "❕" if r.severity == "warn" else "❌"
         scope = f"{r.table}" + (f".{r.column}" if r.column else "")
-        typer.echo(f"{mark} {r.kind:<18} {scope:<40} ({r.ms}ms)")
+        kind_with_params = f"{r.kind}"
+        if r.param_str:
+            kind_with_params += f" {r.param_str}"
+        echo(f"{mark} {kind_with_params:<28} {scope:<40} ({r.ms}ms)")
         if not r.ok and r.msg:
-            typer.echo(f"   ↳ {r.msg}")
-
-    typer.echo("\nTotals")
-    typer.echo("──────")
-    typer.echo(f"✓ passed: {passed}")
-    typer.echo(f"✗ failed: {failed}")
+            echo(f"   ↳ {r.msg}")
+        if not r.ok and r.example_sql:
+            echo(f"   ↳ e.g. SQL: {r.example_sql}")
+
+    echo("\nTotals")
+    echo("──────")
+    echo(f"✓ passed: {passed}")
+    if warned:
+        echo(f"! warned: {warned}")
+    echo(f"✗ failed: {failed}")
+
+
+def _format_params_for_summary(kind: str, params: dict[str, Any]) -> str:
+    """Format a short, readable parameter snippet for the summary line."""
+    if not params:
+        return ""
+    # Common keys first for stable display
+    keys = []
+    if "column" in params:
+        keys.append("column")
+    if "values" in params:
+        keys.append("values")
+    if "where" in params:
+        keys.append("where")
+    # Add remaining keys deterministically
+    for k in sorted(params.keys()):
+        if k not in keys and k not in ("type", "table", "severity", "tags"):
+            keys.append(k)
+    parts: list[str] = []
+    for k in keys:
+        v = params.get(k)
+        preview_len = 4
+        if k == "values" and isinstance(v, list):
+            preview = v if len(v) <= preview_len else [*v[:3], "…"]
+            parts.append(f"values={preview}")
+        elif v is not None:
+            parts.append(f"{k}={v}")
+    return "(" + ", ".join(parts) + ")" if parts else ""
 
 
 def test(
@@ -207,6 +315,7 @@ def test(
     vars: VarsOpt = None,
     select: SelectOpt = None,
 ) -> None:
+    # _ensure_logging()
     ctx = _prepare_context(project, env_name, engine, vars)
     tokens, pred = _compile_selector(select)
     has_model_matches = any(pred(node) for node in REGISTRY.nodes.values())
@@ -217,9 +326,14 @@ def test(
     _maybe_print_marker(con)
 
     model_pred = (lambda _n: True) if legacy_tag_only else pred
+    # Run models; if a model fails, show friendly error then exit(1).
     _run_models(model_pred, run_sql, run_py)
 
-    tests = _load_tests(ctx.project)
+    # 1) project.yml tests
+    tests: list[Any] = _load_tests(ctx.project)
+    # 2) schema YAML tests
+    tests.extend(load_schema_tests(ctx.project))
+    # 3) optional legacy tagfilter (e.g., "batch")
     tests = _apply_legacy_tag_filter(tests, tokens, legacy_token=legacy_tag_only)
     if not tests:
         typer.secho("No tests configured.", fg="bright_black")
@@ -228,7 +342,8 @@ def test(
     results = _run_dq_tests(con, tests)
     _print_summary(results)
 
-    failed = sum(not r.ok for r in results)
+    # Exit code: count only ERROR fails
+    failed = sum((not r.ok) and (r.severity != "warn") for r in results)
     raise typer.Exit(code=2 if failed > 0 else 0)
 
 
diff --git a/src/fastflowtransform/cli/utest_cmd.py b/src/fastflowtransform/cli/utest_cmd.py
index c7a08c1..97e8f43 100644
--- a/src/fastflowtransform/cli/utest_cmd.py
+++ b/src/fastflowtransform/cli/utest_cmd.py
@@ -2,10 +2,8 @@
 
 import typer
 
-from fastflowtransform.utest import discover_unit_specs, run_unit_specs
-
-from .bootstrap import _prepare_context
-from .options import (
+from fastflowtransform.cli.bootstrap import _prepare_context
+from fastflowtransform.cli.options import (
     CaseOpt,
     EngineOpt,
     EnvOpt,
@@ -17,6 +15,8 @@
     UTestCacheOpt,
     VarsOpt,
 )
+from fastflowtransform.logging import echo
+from fastflowtransform.utest import discover_unit_specs, run_unit_specs
 
 
 def utest(
@@ -35,7 +35,7 @@ def utest(
 
     specs = discover_unit_specs(ctx.project, path=path, only_model=model)
     if not specs:
-        typer.echo("ℹ️  No unit tests found (tests/unit/*.yml).")  # noqa: RUF001
+        echo("ℹ️  No unit tests found (tests/unit/*.yml).")  # noqa: RUF001
         raise typer.Exit(0)
 
     failures = run_unit_specs(
diff --git a/src/fastflowtransform/core.py b/src/fastflowtransform/core.py
index 55e2e22..c940518 100644
--- a/src/fastflowtransform/core.py
+++ b/src/fastflowtransform/core.py
@@ -5,7 +5,7 @@
 import importlib.util
 import re
 import types
-from collections.abc import Callable, Iterable
+from collections.abc import Callable, Iterable, Mapping
 from contextlib import suppress
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -17,6 +17,247 @@
 
 from .errors import DependencyNotFoundError, ModuleLoadError
 
+_SOURCE_CFG_FIELDS = {
+    "identifier",
+    "schema",
+    "database",
+    "catalog",
+    "project",
+    "dataset",
+    "location",
+    "format",
+    "options",
+}
+
+
+def _compact_cfg(cfg: Mapping[str, Any]) -> dict[str, Any]:
+    cleaned: dict[str, Any] = {}
+    for key, value in cfg.items():
+        if key == "options":
+            if value:
+                cleaned[key] = dict(value)
+            continue
+        if value is not None:
+            cleaned[key] = value
+    return cleaned
+
+
+def _normalize_options(value: Any, *, field_path: str) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, Mapping):
+        return {str(k): v for k, v in value.items()}
+    raise ValueError(f"sources.yml → {field_path}: expected mapping, got {type(value).__name__}")
+
+
+def _pick_source_fields(
+    data: Mapping[str, Any] | None,
+    base: Mapping[str, Any] | None,
+    *,
+    field_path: str,
+) -> dict[str, Any]:
+    """Return a dict limited to the supported source configuration fields."""
+
+    data = data or {}
+    base = base or {}
+    out: dict[str, Any] = {k: base.get(k) for k in _SOURCE_CFG_FIELDS}
+    for key, value in data.items():
+        if key not in _SOURCE_CFG_FIELDS:
+            continue
+        if key == "options":
+            base_opts = out.get("options") or {}
+            incoming = _normalize_options(value, field_path=f"{field_path}.options")
+            merged = dict(base_opts)
+            merged.update(incoming)
+            out["options"] = merged
+        else:
+            out[key] = value
+
+    if "options" not in out or out["options"] is None:
+        out["options"] = {}
+    return out
+
+
+def _normalize_engine_overrides(
+    overrides: Mapping[str, Any] | None,
+    *,
+    field_path: str,
+) -> dict[str, dict[str, Any]]:
+    if overrides is None:
+        return {}
+    if not isinstance(overrides, Mapping):
+        raise ValueError(
+            f"sources.yml → {field_path}: overrides must be a mapping of engine -> config"
+        )
+
+    normalized: dict[str, dict[str, Any]] = {}
+    for engine, cfg in overrides.items():
+        if cfg is None:
+            normalized[str(engine)] = {}
+            continue
+        if not isinstance(cfg, Mapping):
+            raise ValueError(
+                f"sources.yml → {field_path}[{engine!r}]: "
+                "expected mapping, got {type(cfg).__name__}"
+            )
+        picked = _pick_source_fields(cfg, None, field_path=f"{field_path}[{engine!r}]")
+        normalized[str(engine)] = _compact_cfg(picked)
+    return normalized
+
+
+def _merge_source_configs(base: Mapping[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in override.items():
+        if key == "options":
+            opts = dict(merged.get("options") or {})
+            opts.update(value or {})
+            merged["options"] = opts
+        else:
+            merged[key] = value
+    if "options" not in merged or merged["options"] is None:
+        merged["options"] = {}
+    return merged
+
+
+def _combine_engine_overrides(
+    source_overrides: Mapping[str, dict[str, Any]],
+    table_overrides: Mapping[str, dict[str, Any]],
+) -> dict[str, dict[str, Any]]:
+    engines = set(source_overrides) | set(table_overrides)
+    combined: dict[str, dict[str, Any]] = {}
+    for engine in engines:
+        combined[engine] = _merge_source_configs(
+            source_overrides.get(engine, {}),
+            table_overrides.get(engine, {}),
+        )
+    return combined
+
+
+def resolve_source_entry(
+    entry: Mapping[str, Any], engine: str | None, *, default_identifier: str | None = None
+) -> dict[str, Any]:
+    base = entry.get("base") if isinstance(entry, Mapping) else None
+    if not isinstance(base, Mapping):
+        base = {}
+
+    cfg = dict(base)
+    cfg.setdefault("identifier", None)
+    cfg.setdefault("schema", None)
+    cfg.setdefault("database", None)
+    cfg.setdefault("catalog", None)
+    cfg.setdefault("project", None)
+    cfg.setdefault("dataset", None)
+    cfg.setdefault("location", None)
+    cfg.setdefault("format", None)
+    cfg.setdefault("options", {})
+
+    overrides = entry.get("overrides") if isinstance(entry, Mapping) else None
+    if isinstance(overrides, Mapping):
+        for wildcard_key in ("*", "default", "any"):
+            if wildcard_key in overrides:
+                cfg = _merge_source_configs(cfg, overrides[wildcard_key])
+        if engine and engine in overrides:
+            cfg = _merge_source_configs(cfg, overrides[engine])
+
+    ident = cfg.get("identifier")
+    if (ident is None or ident == "") and not cfg.get("location"):
+        if default_identifier:
+            cfg["identifier"] = default_identifier
+        else:
+            raise KeyError("Source configuration missing identifier or location")
+
+    return cfg
+
+
+def _parse_sources_yaml(raw: Any) -> dict[str, dict[str, dict[str, Any]]]:
+    if not raw:
+        return {}
+    if not isinstance(raw, Mapping):
+        raise ValueError("sources.yml must be a mapping with keys 'version' and 'sources'.")
+
+    version = raw.get("version")
+    version_no = 2
+    if version != version_no:
+        raise ValueError("sources.yml → version: Only '2' is supported.")
+
+    entries = raw.get("sources")
+    if entries is None:
+        return {}
+    if not isinstance(entries, Iterable):
+        raise ValueError("sources.yml → sources: expected a list of source declarations.")
+
+    normalized: dict[str, dict[str, dict[str, Any]]] = {}
+    for idx, entry in enumerate(entries):
+        if not isinstance(entry, Mapping):
+            raise ValueError(
+                f"sources.yml → sources[{idx}]: expected mapping, got {type(entry).__name__}."
+            )
+
+        src_name = entry.get("name")
+        if not src_name or not isinstance(src_name, str):
+            raise ValueError(f"sources.yml → sources[{idx}]: missing 'name'.")
+
+        if src_name in normalized:
+            raise ValueError(f"sources.yml: duplicate source '{src_name}'.")
+
+        src_defaults = _pick_source_fields(entry, None, field_path=f"sources[{idx}]")
+        src_overrides = _normalize_engine_overrides(
+            entry.get("overrides"), field_path=f"sources[{idx}].overrides"
+        )
+
+        tables = entry.get("tables")
+        if tables is None:
+            raise ValueError(f"sources.yml → sources[{idx}]: missing 'tables' list.")
+        if not isinstance(tables, Iterable):
+            raise ValueError(
+                f"sources.yml → sources[{idx}].tables: expected list, got {type(tables).__name__}."
+            )
+
+        group: dict[str, dict[str, Any]] = {}
+        for t_idx, table in enumerate(tables):
+            if not isinstance(table, Mapping):
+                raise ValueError(
+                    f"sources.yml → sources[{idx}].tables[{t_idx}]: "
+                    f"expected mapping, got {type(table).__name__}."
+                )
+
+            tbl_name = table.get("name")
+            if not tbl_name or not isinstance(tbl_name, str):
+                raise ValueError(f"sources.yml → sources[{idx}].tables[{t_idx}]: missing 'name'.")
+
+            if tbl_name in group:
+                raise ValueError(
+                    f"sources.yml → source '{src_name}': duplicate table '{tbl_name}'."
+                )
+
+            base_cfg = _pick_source_fields(
+                table, src_defaults, field_path=f"sources[{idx}].tables[{t_idx}]"
+            )
+            if not base_cfg.get("identifier") and not base_cfg.get("location"):
+                base_cfg["identifier"] = tbl_name
+
+            table_overrides = _normalize_engine_overrides(
+                table.get("overrides"),
+                field_path=f"sources[{idx}].tables[{t_idx}].overrides",
+            )
+            overrides = _combine_engine_overrides(src_overrides, table_overrides)
+
+            entry_meta = {
+                "description": table.get("description"),
+                "columns": table.get("columns"),
+                "meta": table.get("meta"),
+            }
+
+            group[tbl_name] = {
+                "base": base_cfg,
+                "overrides": overrides,
+                **{k: v for k, v in entry_meta.items() if v is not None},
+            }
+
+        normalized[src_name] = group
+
+    return normalized
+
 
 @dataclass
 class Node:
@@ -92,12 +333,16 @@ def load_project(self, project_dir: Path) -> None:
         self._load_macros(models_dir)
         self._load_py_macros(models_dir)
 
-        # load sources
+        # load sources (version 2 schema)
         src_path = project_dir / "sources.yml"
-        self.sources = (
-            yaml.safe_load(src_path.read_text(encoding="utf-8")) if src_path.exists() else {}
-        )
-        self.sources = self.sources or {}
+        if src_path.exists():
+            raw_sources = yaml.safe_load(src_path.read_text(encoding="utf-8"))
+            try:
+                self.sources = _parse_sources_yaml(raw_sources)
+            except ValueError as exc:
+                raise ValueError(f"Failed to parse sources.yml: {exc}") from exc
+        else:
+            self.sources = {}
 
         # load project.yml (vars)
         proj_path = project_dir / "project.yml"
diff --git a/src/fastflowtransform/decorators.py b/src/fastflowtransform/decorators.py
index 8aabcc2..9635f00 100644
--- a/src/fastflowtransform/decorators.py
+++ b/src/fastflowtransform/decorators.py
@@ -18,6 +18,9 @@ class HasFFMeta(Protocol[P, R_co]):
     __ff_deps__: list[str]
     __ff_require__: Any
     __ff_path__: Path
+    __ff_tags__: list[str]
+    __ff_kind__: str
+    __ff_meta__: dict[str, Any]
 
     def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R_co: ...
 
@@ -50,7 +53,11 @@ def _normalize_require(deps: list[str], require: Any | None) -> dict[str, set[st
 def model(
     name: str | None = None,
     deps: Sequence[str] | None = None,
-    require: Any | None = None,  # <-- NEW: required columns
+    require: Any | None = None,
+    *,
+    tags: Sequence[str] | None = None,
+    kind: str = "python",
+    meta: Mapping[str, Any] | None = None,
 ) -> Callable[[Callable[P, R_co]], HasFFMeta[P, R_co]]:
     """
     Decorator to register a Python model.
@@ -62,10 +69,14 @@ def model(
             - Single dependency: Iterable[str] of required columns from that dependency.
             - Multiple dependencies: Mapping[dep_name, Iterable[str]]
               (dep_name = logical name or physical relation).
+        tags: Optional tags for selection (e.g. ['demo','env']).
+        kind: Logical kind; defaults to 'python' (useful for selectors kind:python).
+        meta: Arbitrary metadata, e.g. {'materialized': 'table'|'view'|'incremental'}.
     """
 
     def deco(func: Callable[P, R_co]) -> HasFFMeta[P, R_co]:
         f_any = cast(Any, func)
+
         fname = name or f_any.__name__
         fdeps = list(deps) if deps is not None else []
 
@@ -78,6 +89,10 @@ def deco(func: Callable[P, R_co]) -> HasFFMeta[P, R_co]:
         f_any.__ff_require__ = req_norm  # useful for tooling/loaders
         REGISTRY.py_requires[fname] = req_norm  # executors read this directly
 
+        f_any.__ff_tags__ = list(tags) if tags else []
+        f_any.__ff_kind__ = kind or "python"
+        f_any.__ff_meta__ = dict(meta) if meta else {}
+
         # Determine the source path (better error message if it fails)
         src: str | None = inspect.getsourcefile(func)
         if src is None:
diff --git a/src/fastflowtransform/docs.py b/src/fastflowtransform/docs.py
index f04b89a..0fec0de 100644
--- a/src/fastflowtransform/docs.py
+++ b/src/fastflowtransform/docs.py
@@ -151,10 +151,13 @@ def _get_project_dir() -> Path | None:
 
 
 def _materialization_legend() -> dict[str, dict[str, str]]:
+    # Add 'incremental' to avoid UndefinedError in templates that render badges
+    # for materialization types (index & model pages).
     return {
         "table": {"label": "table", "class": "badge-table"},
         "view": {"label": "view", "class": "badge-view"},
         "ephemeral": {"label": "ephemeral", "class": "badge-ephemeral"},
+        "incremental": {"label": "incremental", "class": "badge-incremental"},
     }
 
 
@@ -315,12 +318,25 @@ def _render_model_pages(
     for m in models:
         phys = relation_for(m.name)
         cols = cols_by_table.get(phys, [])
+
+        # Provide a 'this' context for templates that expect it.
+        # Matches what SQL-rendering exposes: name, materialized,
+        # (schema/database best-effort), and 'incremental'.
+        this_ctx = {
+            "name": phys,
+            "materialized": m.materialized,
+            "schema": None,  # optional: could derive from executor if you want
+            "database": None,  # optional: could derive from executor if you want
+            "incremental": (str(m.materialized).lower() == "incremental"),
+        }
+
         html = tmpl.render(
             m=m,
             used_by=used_by.get(m.name, []),
             cols=cols,
             macros=macros,
             materialization_legend=materialization_legend,
+            this=this_ctx,
         )
         (out_dir / f"{_safe_filename(m.name)}.html").write_text(html, encoding="utf-8")
 
@@ -366,201 +382,6 @@ def render_site(
     )
 
 
-# def render_site(
-#     out_dir: Path,
-#     nodes: dict[str, Node],
-#     executor: Any | None = None,
-#     *,
-#     with_schema: bool = True,
-# ) -> None:
-#     out_dir.mkdir(parents=True, exist_ok=True)
-
-#     # Load templates bundled with the package
-#     tmpl_dir = Path(__file__).parent / "templates"
-#     env = Environment(
-#         loader=FileSystemLoader([str(tmpl_dir)]),
-#         autoescape=select_autoescape(["html", "xml"]),
-#     )
-
-#     # 1) Mermaid source from dag.mermaid (avoid duplication)
-#     mermaid_src = dag_mermaid(nodes)
-
-#     # 2) Optional docs metadata from project + markdown (Descriptions)
-#     proj_dir: Path | None = None
-#     if hasattr(REGISTRY, "get_project_dir"):
-#         try:
-#             proj_dir = REGISTRY.get_project_dir()
-#         except Exception:
-#             proj_dir = None
-#     docs_meta = read_docs_metadata(proj_dir) if proj_dir else {"models": {}, "columns": {}}
-
-#     # 3) Model data for table/detail pages
-#     models = [
-#         ModelDoc(
-#             name=n.name,
-#             kind=n.kind,
-#             path=str(n.path),
-#             relation=relation_for(n.name),
-#             deps=list(n.deps or []),
-#             materialized=(getattr(n, "meta", {}) or {}).get("materialized", "table"),
-#             description_html=None,
-#             description_short=None,
-#         )
-#         for n in nodes.values()
-#     ]
-#     models.sort(key=lambda m: m.name)
-
-#     materialization_legend = {
-#         "table": {"label": "table", "class": "badge-table"},
-#         "view": {"label": "view", "class": "badge-view"},
-#         "ephemeral": {"label": "ephemeral", "class": "badge-ephemeral"},
-#     }
-
-#     # Build macro inventory BEFORE rendering index
-#     macro_list: list[dict[str, str]] = []
-#     for name, p in getattr(REGISTRY, "macros", {}).items():
-#         mp = Path(p)
-#         rel = mp.name
-#         kind = "python" if p.suffix.lower() == ".py" else "sql"
-#         if proj_dir:
-#             try:
-#                 rel = str(mp.relative_to(proj_dir))
-#             except Exception:
-#                 rel = mp.name
-#         macro_list.append({"name": name, "path": rel, "kind": kind})
-#     macro_list.sort(key=lambda x: (x["kind"], x["name"]))
-
-#     # 4) Collect columns (schema) and enrich with descriptions
-#     index_tmpl = env.get_template("index.html.j2")
-#     cols_by_table = _collect_columns(executor) if (executor and with_schema) else {}
-
-#     # Enrich models with descriptions (already merged: Markdown > YAML)
-#     for m in models:
-#         model_meta = (
-#             (docs_meta.get("models", {}) or {}).get(m.name, {})
-#             if isinstance(docs_meta, dict)
-#             else {}
-#         )
-
-#         # --- Model description (HTML already) ---
-#         desc_html = model_meta.get("description_html")
-#         m.description_html = desc_html
-#         desc_char_limit = 160
-#         if desc_html:
-#             short = _strip_html(desc_html)
-#             m.description_short = (
-#                 (short[:desc_char_limit] + "…") if len(short) > desc_char_limit else short
-#             )
-#         else:
-#             m.description_short = None
-
-#         # --- Column descriptions (HTML) ---
-#         # Priority: docs/columns/<relation>/<column>.md  >  YAML under docs.models[model].columns
-#         rel_desc_map = (docs_meta.get("columns", {}) or {}).get(m.relation, {})
-#         mdl_desc_map = model_meta.get("columns") or {}
-
-#         if with_schema and (m.relation in cols_by_table):
-#             for c in cols_by_table[m.relation]:
-#                 # Both maps contain HTML already; no extra rendering here
-#                 c.description_html = rel_desc_map.get(c.name) or mdl_desc_map.get(c.name)
-
-#         # ---- Column lineage (best-effort)
-#         inferred_lineage: dict[str, list[dict[str, Any]]] = {}
-#         try:
-#             if m.kind == "sql" and executor is not None:
-#                 # Render SQL and infer FROM/JOIN alias map + select expressions
-#                 try:
-#                     rendered = executor.render_sql(
-#                         REGISTRY.nodes[m.name],
-#                         REGISTRY.env,
-#                         ref_resolver=lambda nm: executor._resolve_ref(nm, REGISTRY.env),
-#                         source_resolver=executor._resolve_source,
-#                     )
-#                 except Exception:
-#                     rendered = None
-
-#                 if rendered:
-#                     # Heuristic inference
-#                     inferred = infer_sql_lineage(rendered)
-#                     # Optional comment-based overrides
-#                     overrides = parse_sql_lineage_overrides(rendered)
-#                     inferred_lineage = merge_lineage(inferred, overrides)
-
-#             elif m.kind == "python":
-#                 func = getattr(REGISTRY, "py_funcs", {}).get(m.name)
-#                 inferred_lineage = infer_py_lineage(func)
-#         except Exception:
-#             inferred_lineage = {}
-
-#         # YAML overrides for lineage (if present) win over inference
-#         try:
-#             model_meta = (
-#                 (docs_meta.get("models", {}) or {}).get(m.name, {})
-#                 if isinstance(docs_meta, dict)
-#                 else {}
-#             )
-#             ylin = model_meta.get("lineage") if isinstance(model_meta, dict) else None
-#             if isinstance(ylin, dict):
-#                 # Normalize YAML shape
-#                 norm: dict[str, list[dict[str, Any]]] = {}
-#                 for out_col, spec in ylin.items():
-#                     # Expect: { from: [{table:.., column:..}], transformed: bool }
-#                     items: list[dict[str, Any]] = []
-#                     sources = spec.get("from", []) if isinstance(spec, dict) else []
-#                     transformed_flag = (
-#                         bool(spec.get("transformed")) if isinstance(spec, dict) else False
-#                     )
-#                     for s in sources:
-#                         if isinstance(s, dict) and "table" in s and "column" in s:
-#                             items.append(
-#                                 {
-#                                     "from_relation": s["table"],
-#                                     "from_column": s["column"],
-#                                     "transformed": transformed_flag,
-#                                 }
-#                             )
-#                     if items:
-#                         norm[out_col] = items
-#                 if norm:
-#                     inferred_lineage = merge_lineage(inferred_lineage, norm)
-#         except Exception:
-#             pass
-
-#         # Attach lineage to columns (if we know the schema)
-#         if with_schema and (m.relation in cols_by_table) and inferred_lineage:
-#             for c in cols_by_table[m.relation]:
-#                 if c.name in inferred_lineage:
-#                     c.lineage = inferred_lineage[c.name]
-
-#     index_html = index_tmpl.render(
-#         mermaid_src=Markup(mermaid_src),
-#         models=models,
-#         materialization_legend=materialization_legend,
-#         macros=macro_list,  # ← HIER reinreichen
-#     )
-#     (out_dir / "index.html").write_text(index_html, encoding="utf-8")
-
-#     rev: dict[str, list[str]] = {n: [] for n in nodes}
-#     for n in nodes.values():
-#         for d in n.deps or []:
-#             if d in rev:
-#                 rev[d].append(n.name)
-
-#     # 5) One detail page per model (pass descriptions + column descriptions)
-#     model_tmpl = env.get_template("model.html.j2")
-#     for m in models:
-#         phys = relation_for(m.name)
-#         cols = cols_by_table.get(phys, [])
-#         html = model_tmpl.render(
-#             m=m,
-#             used_by=sorted(rev.get(m.name, [])),
-#             cols=cols,
-#             macros=macro_list,
-#             materialization_legend=materialization_legend,
-#         )
-#         (out_dir / f"{_safe_filename(m.name)}.html").write_text(html, encoding="utf-8")
-
-
 @dataclass
 class ColumnInfo:
     name: str
diff --git a/src/fastflowtransform/errors.py b/src/fastflowtransform/errors.py
index 3c51c7f..7fe7de4 100644
--- a/src/fastflowtransform/errors.py
+++ b/src/fastflowtransform/errors.py
@@ -84,3 +84,15 @@ class ProfileConfigError(FastFlowTransformError):
     def __init__(self, message: str):
         # keep to a single line for CLI readability
         super().__init__(message.replace("\n", " ").strip())
+
+
+class ModelExecutionError(Exception):
+    """Raised when a model fails to execute/render on the engine.
+    Carries friendly context for CLI formatting.
+    """
+
+    def __init__(self, node_name: str, relation: str, message: str, sql_snippet: str | None = None):
+        self.node_name = node_name
+        self.relation = relation
+        self.sql_snippet = sql_snippet
+        super().__init__(message)
diff --git a/src/fastflowtransform/executors/_shims.py b/src/fastflowtransform/executors/_shims.py
index 269359b..1cc0e28 100644
--- a/src/fastflowtransform/executors/_shims.py
+++ b/src/fastflowtransform/executors/_shims.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import re
 from collections.abc import Iterable, Sequence
 from typing import Any
 
@@ -43,10 +44,33 @@ def execute(self, sql_or_stmts: Any) -> Any:
         raise TypeError(f"Unsupported sql argument type for BigQuery shim: {type(sql_or_stmts)}")
 
 
+_RE_PG_COR_TABLE = re.compile(
+    r"""^\s*create\s+or\s+replace\s+table\s+
+        (?P<ident>(?:"[^"]+"|\w+)(?:\.(?:"[^"]+"|\w+))?)   # optional schema + ident
+        \s+as\s+(?P<body>.*)$
+    """,
+    re.IGNORECASE | re.DOTALL | re.VERBOSE,
+)
+
+
+def _rewrite_pg_create_or_replace_table(sql: str) -> str:
+    """
+    Rewrite 'CREATE OR REPLACE TABLE t AS <body>' into
+    'DROP TABLE IF EXISTS t CASCADE; CREATE TABLE t AS <body>' for Postgres.
+    Leave all other SQL untouched.
+    """
+    m = _RE_PG_COR_TABLE.match(sql or "")
+    if not m:
+        return sql
+    ident = m.group("ident").strip()
+    body = m.group("body").strip().rstrip(";\n\t ")
+    return f"DROP TABLE IF EXISTS {ident} CASCADE; CREATE TABLE {ident} AS {body}"
+
+
 class SAConnShim:
     """
     Compatibility layer so fastflowtransform.testing can call executor.con.execute(...)
-    against SQLAlchemy engines (Postgres, etc.).
+    against SQLAlchemy engines (Postgres, etc.). Adds PG-safe DDL rewrites.
     """
 
     marker = "PG_SHIM"
@@ -55,41 +79,42 @@ def __init__(self, engine: Engine, schema: str | None = None):
         self._engine = engine
         self._schema = schema
 
-    def _exec_one(self, conn: Any, stmt: Any) -> Any:
-        statement_tuple_len = 2
+    def _exec_one(self, conn: Any, stmt: Any, params: dict | None = None) -> Any:
+        # tuple (sql, params)
+        statement_len = 2
         if (
             isinstance(stmt, tuple)
-            and len(stmt) == statement_tuple_len
+            and len(stmt) == statement_len
             and isinstance(stmt[0], str)
             and isinstance(stmt[1], dict)
         ):
-            return conn.execute(text(stmt[0]), stmt[1])
+            return self._exec_one(conn, stmt[0], stmt[1])
+
+        # sqlalchemy expression
         if isinstance(stmt, ClauseElement):
             return conn.execute(stmt)
+
+        # plain string (apply rewrite, then possibly split into multiple statements)
         if isinstance(stmt, str):
-            return conn.execute(text(stmt))
+            rewritten = _rewrite_pg_create_or_replace_table(stmt)
+            parts = [p.strip() for p in rewritten.split(";") if p.strip()]
+            res = None
+            for i, part in enumerate(parts):
+                res = conn.execute(text(part), params if (i == len(parts) - 1) else None)
+            return res
+
+        # iterable of statements -> sequential execution
         if isinstance(stmt, Iterable) and not isinstance(stmt, (bytes, bytearray, str)):
             res = None
             for s in stmt:
                 res = self._exec_one(conn, s)
             return res
-        raise TypeError(f"Unsupported statement type in shim: {type(stmt)} → {stmt!r}")
+
+        # fallback
+        return self._exec_one(conn, str(stmt))
 
     def execute(self, sql: Any) -> Any:
         with self._engine.begin() as conn:
-            sql_tuple_len = 2
             if self._schema:
                 conn.execute(text(f'SET LOCAL search_path = "{self._schema}"'))
-            if isinstance(sql, (str, ClauseElement)) or (
-                isinstance(sql, tuple)
-                and len(sql) == sql_tuple_len
-                and isinstance(sql[0], str)
-                and isinstance(sql[1], dict)
-            ):
-                return self._exec_one(conn, sql)
-            if isinstance(sql, Iterable) and not isinstance(sql, (bytes, bytearray, str)):
-                res = None
-                for item in sql:
-                    res = self._exec_one(conn, item)
-                return res
-            raise TypeError(f"Unsupported sql argument type: {type(sql)} → {sql!r}")
+            return self._exec_one(conn, sql)
diff --git a/src/fastflowtransform/executors/base.py b/src/fastflowtransform/executors/base.py
index 643f16f..4c891df 100644
--- a/src/fastflowtransform/executors/base.py
+++ b/src/fastflowtransform/executors/base.py
@@ -2,24 +2,47 @@
 from __future__ import annotations
 
 import contextvars
-import logging
-import os
 import re
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Iterable
+from contextlib import suppress
 from pathlib import Path
 from typing import Any, TypeVar
 
 from jinja2 import Environment
 from pandas import DataFrame as _PDDataFrame
 
-from fastflowtransform.core import REGISTRY, Node, relation_for
+from fastflowtransform.api import context as _http_ctx
+from fastflowtransform.core import REGISTRY, Node, relation_for, resolve_source_entry
+from fastflowtransform.errors import ModelExecutionError
+from fastflowtransform.logging import echo_debug
 from fastflowtransform.validation import validate_required_columns
 
 # Frame type (pandas.DataFrame, pyspark.sql.DataFrame, snowflake.snowpark.DataFrame, ...)
 TFrame = TypeVar("TFrame")
 
 
+class _ThisProxy:
+    """
+    Jinja-kompatibler Proxy für {{ this }}:
+    - Als String verwendbar ({{ this }}) -> physischer Relationsname.
+    - Attribute verfügbar ({{ this.name }}, {{ this.materialized }}, ...)
+    """
+
+    def __init__(self, relation: str, materialized: str, schema: str | None, database: str | None):
+        self.name = relation  # Back-compat: {{ this.name }}
+        self.relation = relation  # Alias, falls jemand {{ this.relation }} nutzt
+        self.materialized = materialized
+        self.schema = schema
+        self.database = database
+
+    def __str__(self) -> str:
+        return self.name
+
+    def __repr__(self) -> str:
+        return f"_ThisProxy(name={self.name!r})"
+
+
 class BaseExecutor[TFrame](ABC):
     """
     Shared workflow for SQL rendering and Python models.
@@ -74,6 +97,23 @@ def _var(key: str, default: Any = None) -> Any:
 
             env.globals["var"] = _var
 
+        # ---- is_incremental() builtin
+        # True iff materialization is 'incremental' AND the target relation already exists.
+        if "is_incremental" not in env.globals:
+
+            def _is_incremental() -> bool:
+                try:
+                    mat = (getattr(node, "meta", {}) or {}).get("materialized", "table")
+                    if mat != "incremental":
+                        return False
+                    rel = relation_for(node.name)
+                    return bool(self.exists_relation(rel))
+                except Exception:
+                    # Be conservative: if anything is off, treat as non-incremental.
+                    return False
+
+            env.globals["is_incremental"] = _is_incremental
+
         raw = Path(node.path).read_text(encoding="utf-8")
         tmpl = env.from_string(raw)
 
@@ -81,23 +121,32 @@ def _default_ref(name: str) -> str:
             return relation_for(name)
 
         def _default_source(source_name: str, table_name: str) -> str:
-            cfg = REGISTRY.sources.get(source_name, {}).get(table_name)
-            if not cfg:
+            group = REGISTRY.sources.get(source_name)
+            if not group:
+                raise KeyError(f"Unknown source {source_name}.{table_name}")
+            entry = group.get(table_name)
+            if not entry:
                 raise KeyError(f"Unknown source {source_name}.{table_name}")
+            cfg = resolve_source_entry(entry, self.engine_name, default_identifier=table_name)
+            if cfg.get("location"):
+                raise KeyError(
+                    "Path-based sources require executor context; "
+                    "default resolver cannot handle them."
+                )
             identifier = cfg.get("identifier")
             if not identifier:
                 raise KeyError(f"Source {source_name}.{table_name} missing identifier")
             return identifier
 
         _RENDER_CFG.set({})
-        # expose 'this' to the template
-        this_obj = {
-            "name": relation_for(node.name),
-            "materialized": (getattr(node, "meta", {}) or {}).get("materialized", "table"),
-            # best-effort: these are engine-specific and may be None
-            "schema": getattr(self, "schema", None) or getattr(self, "dataset", None),
-            "database": getattr(self, "database", None) or getattr(self, "project", None),
-        }
+
+        # expose 'this' to the template: Proxy-Objekt, das wie String wirkt
+        this_obj = _ThisProxy(
+            relation_for(node.name),
+            (getattr(node, "meta", {}) or {}).get("materialized", "table"),
+            getattr(self, "schema", None) or getattr(self, "dataset", None),
+            getattr(self, "database", None) or getattr(self, "project", None),
+        )
 
         sql = tmpl.render(
             ref=ref_resolver or _default_ref,
@@ -113,46 +162,79 @@ def _default_source(source_name: str, table_name: str) -> str:
 
     def run_sql(self, node: Node, env: Environment) -> None:
         """
-        Shared orchestration for SQL models. Subclasses implement quoting and DDL via hooks.
-
-        Flow:
-          1. Set up ref()/source() resolvers (with ephemeral inlining)
-          2. Render the SQL template
-          3. Strip leading config blocks
-          4. Skip materialisation for ephemeral models
-          5. Extract the SELECT body and let the executor materialise it
+        Orchestrate SQL models:
+          1) Render Jinja (ref/source/this) and strip leading {{ config(...) }}.
+          2) If the SQL is full DDL (CREATE …), execute it verbatim (passthrough).
+          3) Otherwise, normalize to CREATE OR REPLACE {TABLE|VIEW} AS <body>.
+             The body is CTE-aware (keeps WITH … SELECT … intact).
+        On failure, raise ModelExecutionError with a helpful snippet.
         """
-
-        sql = self.render_sql(
+        sql_rendered = self.render_sql(
             node,
             env,
             ref_resolver=lambda name: self._resolve_ref(name, env),
             source_resolver=self._resolve_source,
         )
-        sql = self._strip_leading_config(sql).strip()
+        sql = self._strip_leading_config(sql_rendered).strip()
 
         materialization = (node.meta or {}).get("materialized", "table")
         if materialization == "ephemeral":
             return
 
-        select_body = self._first_select_body(sql).rstrip(" ;\n\t")
+        # 1) Direct DDL passthrough (CREATE [OR REPLACE] {TABLE|VIEW} …)
+        if self._looks_like_direct_ddl(sql):
+            try:
+                self._execute_sql_direct(sql, node)
+                return
+            except NotImplementedError:
+                # Engine doesn't implement direct DDL → fall back to normalized materialization.
+                pass
+            except Exception as e:
+                raise ModelExecutionError(
+                    node_name=node.name,
+                    relation=relation_for(node.name),
+                    message=str(e),
+                    sql_snippet=sql,
+                ) from e
+
+        # 2) Normalized materialization path (CTE-safe body)
+        body = self._selectable_body(sql).rstrip(" ;\n\t")
         target_sql = self._format_relation_for_ref(node.name)
-        self._apply_sql_materialization(node, target_sql, select_body, materialization)
+
+        # Centralized SQL preview logging (applies to ALL engines)
+        preview = (
+            f"=== MATERIALIZE ===\n"
+            f"-- model: {node.name}\n"
+            f"-- materialized: {materialization}\n"
+            f"-- target: {target_sql}\n"
+            f"{body}\n"
+        )
+        echo_debug(preview)
+
+        try:
+            self._apply_sql_materialization(node, target_sql, body, materialization)
+        except Exception as e:
+            preview = f"-- materialized={materialization}\n-- target={target_sql}\n{body}"
+            raise ModelExecutionError(
+                node_name=node.name,
+                relation=relation_for(node.name),
+                message=str(e),
+                sql_snippet=preview,
+            ) from e
 
     # --- Helpers for materialization & ephemeral inlining (instance methods) ---
     def _first_select_body(self, sql: str) -> str:
         """
-        Extrahiert den 'SELECT …' Teil aus einem SQL-String, damit wir ihn in
-        CREATE VIEW/TABLE … AS <body> einfügen können. Falls kein SELECT gefunden
-        wird, geben wir den Original-String zurück.
+        Fallback: extract the substring starting at the first SELECT token.
+        If no SELECT is found, return the original string unchanged.
+        Prefer using _selectable_body() which is CTE-aware.
         """
         m = re.search(r"\bselect\b", sql, flags=re.I | re.S)
         return sql[m.start() :] if m else sql
 
     def _strip_leading_config(self, sql: str) -> str:
         """
-        Entfernt eine führende Jinja-Zeile/Block {{ config(...) }} vom SQL,
-        damit der Executor saubere DDL/DML bekommt.
+        Remove a leading Jinja {{ config(...) }} so the engine receives clean SQL.
         """
         return re.sub(
             r"^\s*\{\{\s*config\s*\(.*?\)\s*\}\}\s*",
@@ -161,52 +243,132 @@ def _strip_leading_config(self, sql: str) -> str:
             flags=re.I | re.S,
         )
 
+    def _strip_leading_sql_comments(self, sql: str) -> tuple[str, int]:
+        """
+        Remove *only* leading SQL comments and blank lines, return (trimmed_sql, start_idx).
+
+        Supports:
+          -- single line comments
+          /* block comments */
+        """
+        # Match chain of: whitespace, comment, whitespace, comment, ...
+        # Using DOTALL so block comments spanning lines are handled.
+        pat = re.compile(
+            r"""^\s*(?:
+                                --[^\n]*\n        # line comment
+                              | /\*.*?\*/\s*      # block comment
+                             )*""",
+            re.VERBOSE | re.DOTALL,
+        )
+        m = pat.match(sql)
+        start = m.end() if m else 0
+        return sql[start:], start
+
+    def _selectable_body(self, sql: str) -> str:
+        """
+        Return a valid SELECT-able body for CREATE … AS:
+
+          - If the statement starts (after comments/blank lines) with a CTE (WITH …),
+            return from the WITH onward.
+          - If it starts with SELECT, return from SELECT onward.
+          - Otherwise, fall back to the first SELECT heuristic.
+        """
+        # Keep original for fallback, but check after stripping comments
+        s0 = sql
+        s, offset = self._strip_leading_sql_comments(sql)
+        s_ws = s.lstrip()  # in case comments left some spaces
+        head = s_ws[:6].lower()
+
+        if s_ws.startswith(("with ", "with\n", "with\t")):
+            # Return from the start of this WITH (preserve exactly s_ws form)
+            # Compute index into original string to retain original casing beyond comments
+            idx = s.find(s_ws)
+            return sql[offset + (idx if idx >= 0 else 0) :].lstrip()
+
+        if head.startswith("select"):
+            idx = s.find(s_ws)
+            return sql[offset + (idx if idx >= 0 else 0) :].lstrip()
+
+        # Fallback: first SELECT anywhere in the statement
+        return self._first_select_body(s0)
+
+    def _looks_like_direct_ddl(self, sql: str) -> bool:
+        """
+        True if the rendered SQL starts with CREATE (TABLE|VIEW) so it should be
+        executed verbatim as a user-provided DDL statement.
+        """
+        head = sql.lstrip().lower()
+        return (
+            head.startswith("create table")
+            or head.startswith("create view")
+            or head.startswith("create or replace")
+        )
+
+    def _execute_sql_direct(self, sql: str, node: Node) -> None:
+        """
+        Execute a full CREATE … statement as-is. Default: use `self.con.execute(sql)`.
+        Engines can override this for custom dispatch. If not available, raise
+        NotImplementedError so the caller can fall back to normalized materialization.
+        """
+        con = getattr(self, "con", None)
+        if con is None or not hasattr(con, "execute"):
+            raise NotImplementedError("Direct DDL execution is not implemented for this executor.")
+        con.execute(sql)
+
     def _render_ephemeral_sql(self, name: str, env: Environment) -> str:
         """
-        Rendert das SQL für ein 'ephemeral' Modell und gibt eine Subquery
-        als String '( ... )' zurück. Diese Methode respektiert rekursiv
-        weitere 'ephemeral'-Refs.
+        Render the SQL for an 'ephemeral' model and return it as a parenthesized
+        subquery. This is CTE-safe: we keep the full WITH…SELECT… statement and
+        only strip the leading {{ config(...) }} and trailing semicolons.
         """
-        # Node lookup (unterstützt optional REGISTRY.get_node aliasing)
         node = REGISTRY.get_node(name) if hasattr(REGISTRY, "get_node") else REGISTRY.nodes[name]
 
         raw = Path(node.path).read_text(encoding="utf-8")
         tmpl = env.from_string(raw)
 
-        # ref() → bei 'ephemeral' rekursiv inline, sonst physischer Relationsname
         sql = tmpl.render(
             ref=lambda n: self._resolve_ref(n, env),
             source=self._resolve_source,
+            this=_ThisProxy(
+                relation_for(node.name),
+                (getattr(node, "meta", {}) or {}).get("materialized", "table"),
+                getattr(self, "schema", None) or getattr(self, "dataset", None),
+                getattr(self, "database", None) or getattr(self, "project", None),
+            ),
         )
+        # Remove a leading config block and keep the full, CTE-capable statement
         sql = self._strip_leading_config(sql).strip()
-        body = self._first_select_body(sql).rstrip(" ;\n\t")
+        body = self._selectable_body(sql).rstrip(" ;\n\t")
         return f"(\n{body}\n)"
 
     # ---------- Python models ----------
     def run_python(self, node: Node) -> None:
         func = REGISTRY.py_funcs[node.name]
         deps = REGISTRY.nodes[node.name].deps or []
-        if not deps:
-            raise ValueError(f"Python-Modell '{node.name}' hat keine Dependencies (erwarte ≥1).")
+        if _http_ctx is not None:
+            with suppress(Exception):
+                _http_ctx.reset_for_node(node.name)
 
         # Load inputs
-        if len(deps) == 1:
+        arg: Any
+        if len(deps) == 0:
+            arg = None
+        elif len(deps) == 1:
             rel = relation_for(deps[0])
             df_in: TFrame = self._read_relation(rel, node, deps)
-            self._log_dep(node.name, rel, df_in)
-            arg: Any = df_in  # TFrame
+            arg = df_in  # TFrame
         else:
             frames: dict[str, TFrame] = {}
             for dep in deps:
                 rel = relation_for(dep)
                 f = self._read_relation(rel, node, deps)
-                self._log_dep(node.name, rel, f)
                 frames[rel] = f
             arg = frames  # dict[str, TFrame]
 
         # Validate required columns / structure (frame specific)
         requires = REGISTRY.py_requires.get(node.name, {})
-        self._validate_required(node.name, arg, requires)
+        if deps:
+            self._validate_required(node.name, arg, requires)
 
         # Execute the model
         out = func(arg)
@@ -225,6 +387,13 @@ def run_python(self, node: Node) -> None:
         else:
             self._materialize_relation(target, out, node)
 
+        if _http_ctx is not None:
+            try:
+                snap = _http_ctx.snapshot()
+                (node.meta or {}).update({"_http_snapshot": snap})
+            except Exception:
+                pass
+
     # -------- Python model view helpers (shared) --------
     def _py_view_backing_name(self, relation: str) -> str:
         """
@@ -294,17 +463,30 @@ def _resolve_ref(self, name: str, env: Environment) -> str:
         return self._format_relation_for_ref(name)
 
     def _resolve_source(self, source_name: str, table_name: str) -> str:
-        cfg = REGISTRY.sources.get(source_name, {}).get(table_name)
-        if not cfg or "identifier" not in cfg:
-            raise KeyError(f"Unknown source {source_name}.{table_name}")
-        return self._format_source_reference(cfg, source_name, table_name)
+        group = REGISTRY.sources.get(source_name)
+        if not group:
+            known = ", ".join(sorted(REGISTRY.sources.keys())) or "<none>"
+            raise KeyError(f"Unknown source '{source_name}'. Known sources: {known}")
+
+        entry = group.get(table_name)
+        if not entry:
+            known_tables = ", ".join(sorted(group.keys())) or "<none>"
+            raise KeyError(
+                f"Unknown source table '{source_name}.{table_name}'. Known tables: {known_tables}"
+            )
 
-    # ---------- Logging ----------
-    def _log_dep(self, node_name: str, rel: str, frame: TFrame) -> None:
-        sql_log = logging.getLogger("fastflowtransform.sql")
-        if sql_log.isEnabledFor(logging.DEBUG) or (os.getenv("FFT_SQL_DEBUG") == "1"):
-            cols = ", ".join(self._columns_of(frame))
-            sql_log.debug(f"py:{node_name} dep {rel} cols=[{cols}]")
+        engine_key = self.engine_name
+        try:
+            cfg = resolve_source_entry(entry, engine_key, default_identifier=table_name)
+        except KeyError as exc:
+            raise KeyError(
+                f"Source {source_name}.{table_name} missing "
+                f"identifier/location for engine '{engine_key}'"
+            ) from exc
+
+        cfg = dict(cfg)
+        cfg.setdefault("options", {})
+        return self._format_source_reference(cfg, source_name, table_name)
 
     # ---------- Abstrakte Frame-Hooks ----------
     @abstractmethod
@@ -349,3 +531,37 @@ def on_node_built(self, node: Node, relation: str, fingerprint: str) -> None:
         Default: no-op.
         """
         return
+
+    # ── Incremental API ───────────────────────────────────────────────
+    def exists_relation(self, relation: str) -> bool:  # pragma: no cover - abstract
+        """Returns True if physical relation exists (table/view)."""
+        raise NotImplementedError
+
+    def create_table_as(self, relation: str, select_sql: str) -> None:  # pragma: no cover
+        """CREATE TABLE AS SELECT …"""
+        raise NotImplementedError
+
+    def incremental_insert(self, relation: str, select_sql: str) -> None:  # pragma: no cover
+        """INSERT-only (Append)."""
+        raise NotImplementedError
+
+    def incremental_merge(
+        self, relation: str, select_sql: str, unique_key: list[str]
+    ) -> None:  # pragma: no cover
+        """Best-effort UPSERT; Default fallback via staging delete+insert."""
+        raise NotImplementedError
+
+    def alter_table_sync_schema(
+        self, relation: str, select_sql: str, *, mode: str = "append_new_columns"
+    ) -> None:  # pragma: no cover
+        """
+        Optional: Additive schema synchronisation. 'mode' = append_new_columns|sync_all_columns.
+        Default implementation: No-Op.
+        """
+        return None
+
+    ENGINE_NAME: str = "generic"
+
+    @property
+    def engine_name(self) -> str:
+        return getattr(self, "ENGINE_NAME", "generic")
diff --git a/src/fastflowtransform/executors/bigquery_bf_exec.py b/src/fastflowtransform/executors/bigquery_bf_exec.py
index 30fcf32..e7175aa 100644
--- a/src/fastflowtransform/executors/bigquery_bf_exec.py
+++ b/src/fastflowtransform/executors/bigquery_bf_exec.py
@@ -9,10 +9,11 @@
 from google.api_core.exceptions import BadRequest, NotFound
 from google.cloud import bigquery
 
-from ..core import Node, relation_for
-from ._bigquery_mixin import BigQueryIdentifierMixin
-from ._shims import BigQueryConnShim
-from .base import BaseExecutor
+from fastflowtransform.core import Node, relation_for
+from fastflowtransform.executors._bigquery_mixin import BigQueryIdentifierMixin
+from fastflowtransform.executors._shims import BigQueryConnShim
+from fastflowtransform.executors.base import BaseExecutor
+from fastflowtransform.meta import ensure_meta_table, upsert_meta
 
 if TYPE_CHECKING:
     from bigframes.dataframe import DataFrame as BFDataFrame
@@ -21,6 +22,8 @@
 
 
 class BigQueryBFExecutor(BigQueryIdentifierMixin, BaseExecutor[BFDataFrame]):
+    ENGINE_NAME = "bigquery_batch"
+
     def __init__(self, project: str, dataset: str, location: str | None = None):
         self.project = project
         self.dataset = dataset
@@ -74,6 +77,16 @@ def _materialize_relation(self, relation: str, df: BFDataFrame, node: Node) -> N
             "Erwarte df.to_gbq(...) oder df.materialize(...)."
         )
 
+    # ---- Meta hook ----
+    def on_node_built(self, node: Node, relation: str, fingerprint: str) -> None:
+        """Mirror DuckDB/PG: write/update _ff_meta after successful build."""
+        try:
+            ensure_meta_table(self)
+            upsert_meta(self, node.name, relation, fingerprint, "bigquery")
+        except Exception:
+            # Best-effort: meta must not break the run
+            pass
+
     def _validate_required(
         self, node_name: str, inputs: Any, requires: dict[str, set[str]]
     ) -> None:
@@ -132,9 +145,15 @@ def _format_relation_for_ref(self, name: str) -> str:
     def _format_source_reference(
         self, cfg: dict[str, Any], source_name: str, table_name: str
     ) -> str:
-        ident = cfg["identifier"]
-        proj = cfg.get("project", self.project)
-        dset = cfg.get("dataset", self.dataset)
+        if cfg.get("location"):
+            raise NotImplementedError("BigQuery executor does not support path-based sources.")
+
+        ident = cfg.get("identifier")
+        if not ident:
+            raise KeyError(f"Source {source_name}.{table_name} missing identifier")
+
+        proj = cfg.get("project") or cfg.get("database") or cfg.get("catalog") or self.project
+        dset = cfg.get("dataset") or cfg.get("schema") or self.dataset
         return self._qualified_identifier(ident, project=proj, dataset=dset)
 
     def _apply_sql_materialization(
@@ -169,3 +188,115 @@ def _create_or_replace_view_from_table(
             f"CREATE OR REPLACE VIEW {view_id} AS SELECT * FROM {back_id}",
             location=self.location,
         ).result()
+
+    # ── Incremental API (feature parity with DuckDB/PG) ──────────────────
+    def exists_relation(self, relation: str) -> bool:
+        """Check presence in TABLES or VIEWS information schema."""
+        proj = self.project
+        dset = self.dataset
+        rel = relation
+        q = f"""
+        SELECT 1
+        FROM `{proj}.{dset}.INFORMATION_SCHEMA.TABLES`
+        WHERE LOWER(table_name)=LOWER(@rel)
+        UNION ALL
+        SELECT 1
+        FROM `{proj}.{dset}.INFORMATION_SCHEMA.VIEWS`
+        WHERE LOWER(table_name)=LOWER(@rel)
+        LIMIT 1
+        """
+        job = self.client.query(
+            q,
+            job_config=bigquery.QueryJobConfig(
+                query_parameters=[bigquery.ScalarQueryParameter("rel", "STRING", rel)]
+            ),
+            location=self.location,
+        )
+        return bool(list(job.result()))
+
+    def create_table_as(self, relation: str, select_sql: str) -> None:
+        """CTAS with cleaned SELECT body (no trailing semicolons)."""
+        self._ensure_dataset()
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        target = self._qualified_identifier(relation, project=self.project, dataset=self.dataset)
+        self.client.query(
+            f"CREATE TABLE {target} AS {body}",
+            location=self.location,
+        ).result()
+
+    def incremental_insert(self, relation: str, select_sql: str) -> None:
+        """INSERT INTO with cleaned SELECT body."""
+        self._ensure_dataset()
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        target = self._qualified_identifier(relation, project=self.project, dataset=self.dataset)
+        self.client.query(
+            f"INSERT INTO {target} {body}",
+            location=self.location,
+        ).result()
+
+    def incremental_merge(self, relation: str, select_sql: str, unique_key: list[str]) -> None:
+        """
+        Portable fallback in BigQuery (without full MERGE):
+          - DELETE collisions via WHERE EXISTS against the cleaned SELECT body
+          - INSERT all rows from the body
+        Executed as two statements to keep error surfaces clean.
+        """
+        self._ensure_dataset()
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        target = self._qualified_identifier(relation, project=self.project, dataset=self.dataset)
+        pred = " AND ".join([f"t.{k}=s.{k}" for k in unique_key]) or "FALSE"
+
+        # DELETE … WHERE EXISTS (SELECT 1 FROM (body) s WHERE pred)
+        delete_sql = f"""
+        DELETE FROM {target} t
+        WHERE EXISTS (SELECT 1 FROM ({body}) s WHERE {pred})
+        """
+        self.client.query(delete_sql, location=self.location).result()
+
+        # INSERT new rows
+        insert_sql = f"INSERT INTO {target} SELECT * FROM ({body})"
+        self.client.query(insert_sql, location=self.location).result()
+
+    def alter_table_sync_schema(
+        self, relation: str, select_sql: str, *, mode: str = "append_new_columns"
+    ) -> None:
+        """
+        Best-effort additive schema sync:
+          - infer select schema via dry-run (schema on QueryJob)
+          - add missing columns as NULLABLE with inferred type
+        """
+        if mode not in {"append_new_columns", "sync_all_columns"}:
+            return
+
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        # Infer target schema from the query (no data read)
+        probe_job = self.client.query(
+            f"SELECT * FROM ({body}) WHERE 1=0",
+            job_config=bigquery.QueryJobConfig(dry_run=False, use_query_cache=False),
+            location=self.location,
+        )
+        probe_job.result()
+        select_fields = {f.name: f for f in (probe_job.schema or [])}
+
+        # Existing table schema
+        table_ref = f"{self.project}.{self.dataset}.{relation}"
+        try:
+            tbl = self.client.get_table(table_ref)
+        except NotFound:
+            return
+        existing_cols = {f.name for f in (tbl.schema or [])}
+
+        to_add = [name for name in select_fields if name not in existing_cols]
+        if not to_add:
+            return
+
+        target = self._qualified_identifier(relation, project=self.project, dataset=self.dataset)
+        for col in to_add:
+            bf = select_fields[col]
+            # Use BigQuery standard SQL type string (e.g., STRING, INT64, BOOL, FLOAT64, …)
+            typ = str(bf.field_type) if hasattr(bf, "field_type") else "STRING"
+            # Nullable by default
+            self.client.query(
+                f"ALTER TABLE {target} ADD COLUMN {col} {typ}",
+                location=self.location,
+            ).result()
diff --git a/src/fastflowtransform/executors/bigquery_exec.py b/src/fastflowtransform/executors/bigquery_exec.py
index a6c636d..57a058d 100644
--- a/src/fastflowtransform/executors/bigquery_exec.py
+++ b/src/fastflowtransform/executors/bigquery_exec.py
@@ -10,15 +10,15 @@
 from google.cloud.bigquery import Client, LoadJobConfig
 
 from fastflowtransform.core import Node, relation_for
+from fastflowtransform.executors._bigquery_mixin import BigQueryIdentifierMixin
+from fastflowtransform.executors._shims import BigQueryConnShim
+from fastflowtransform.executors.base import BaseExecutor
 from fastflowtransform.meta import ensure_meta_table, upsert_meta
 
-from ._bigquery_mixin import BigQueryIdentifierMixin
-from ._shims import BigQueryConnShim
-from .base import BaseExecutor
-
 
 # ---- Executor --------------------------------------------------------------
 class BigQueryExecutor(BigQueryIdentifierMixin, BaseExecutor[pd.DataFrame]):
+    ENGINE_NAME = "bigquery"
     """
     BigQuery executor (pandas DataFrames).
     ENV/Profiles typically use:
@@ -95,15 +95,20 @@ def _format_relation_for_ref(self, name: str) -> str:
     def _format_source_reference(
         self, cfg: dict[str, Any], source_name: str, table_name: str
     ) -> str:
-        ident = cfg["identifier"]
-        proj = cfg.get("project", self.project)
-        dset = cfg.get("dataset", self.dataset)
+        if cfg.get("location"):
+            raise NotImplementedError("BigQuery executor does not support path-based sources.")
+
+        ident = cfg.get("identifier")
+        if not ident:
+            raise KeyError(f"Source {source_name}.{table_name} missing identifier")
+
+        proj = cfg.get("project") or cfg.get("database") or cfg.get("catalog") or self.project
+        dset = cfg.get("dataset") or cfg.get("schema") or self.dataset
         return self._qualified_identifier(ident, project=proj, dataset=dset)
 
     def _apply_sql_materialization(
         self, node: Node, target_sql: str, select_body: str, materialization: str
     ) -> None:
-        self._ensure_dataset()
         self._ensure_dataset()
         try:
             super()._apply_sql_materialization(node, target_sql, select_body, materialization)
@@ -147,3 +152,116 @@ def on_node_built(self, node: Node, relation: str, fingerprint: str) -> None:
             upsert_meta(self, node.name, relation, fingerprint, "bigquery")
         except Exception:
             pass
+
+    # ── Incremental API (parity with DuckDB/PG) ───────────────────────────
+    def exists_relation(self, relation: str) -> bool:
+        """
+        Check presence in INFORMATION_SCHEMA for tables/views.
+        """
+        proj = self.project
+        dset = self.dataset
+        rel = relation
+        q = f"""
+        SELECT 1
+        FROM `{proj}.{dset}.INFORMATION_SCHEMA.TABLES`
+        WHERE LOWER(table_name)=LOWER(@rel)
+        UNION ALL
+        SELECT 1
+        FROM `{proj}.{dset}.INFORMATION_SCHEMA.VIEWS`
+        WHERE LOWER(table_name)=LOWER(@rel)
+        LIMIT 1
+        """
+        job = self.client.query(
+            q,
+            job_config=bigquery.QueryJobConfig(
+                query_parameters=[bigquery.ScalarQueryParameter("rel", "STRING", rel)]
+            ),
+            location=self.location,
+        )
+        return bool(list(job.result()))
+
+    def create_table_as(self, relation: str, select_sql: str) -> None:
+        """
+        CREATE TABLE AS with cleaned SELECT body (no trailing semicolons).
+        """
+        self._ensure_dataset()
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        target = self._qualified_identifier(relation, project=self.project, dataset=self.dataset)
+        self.client.query(
+            f"CREATE TABLE {target} AS {body}",
+            location=self.location,
+        ).result()
+
+    def incremental_insert(self, relation: str, select_sql: str) -> None:
+        """
+        INSERT INTO with cleaned SELECT body.
+        """
+        self._ensure_dataset()
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        target = self._qualified_identifier(relation, project=self.project, dataset=self.dataset)
+        self.client.query(
+            f"INSERT INTO {target} {body}",
+            location=self.location,
+        ).result()
+
+    def incremental_merge(self, relation: str, select_sql: str, unique_key: list[str]) -> None:
+        """
+        Portable fallback without native MERGE:
+          - DELETE collisions via WHERE EXISTS against the cleaned SELECT body
+          - INSERT new rows from the same body
+        """
+        self._ensure_dataset()
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        target = self._qualified_identifier(relation, project=self.project, dataset=self.dataset)
+        pred = " AND ".join([f"t.{k}=s.{k}" for k in unique_key]) or "FALSE"
+
+        delete_sql = f"""
+        DELETE FROM {target} t
+        WHERE EXISTS (SELECT 1 FROM ({body}) s WHERE {pred})
+        """
+        self.client.query(delete_sql, location=self.location).result()
+
+        insert_sql = f"INSERT INTO {target} SELECT * FROM ({body})"
+        self.client.query(insert_sql, location=self.location).result()
+
+    def alter_table_sync_schema(
+        self, relation: str, select_sql: str, *, mode: str = "append_new_columns"
+    ) -> None:
+        """
+        Best-effort additive schema sync:
+          - infer select schema via LIMIT 0 query
+          - add missing columns as NULLABLE using inferred BigQuery types
+        """
+        if mode not in {"append_new_columns", "sync_all_columns"}:
+            return
+        self._ensure_dataset()
+
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        # Infer schema using a no-row query (lets BigQuery type the expressions)
+        probe = self.client.query(
+            f"SELECT * FROM ({body}) WHERE 1=0",
+            job_config=bigquery.QueryJobConfig(dry_run=False, use_query_cache=False),
+            location=self.location,
+        )
+        probe.result()
+        out_fields = {f.name: f for f in (probe.schema or [])}
+
+        # Existing table schema
+        table_ref = f"{self.project}.{self.dataset}.{relation}"
+        try:
+            tbl = self.client.get_table(table_ref)
+        except NotFound:
+            return
+        existing_cols = {f.name for f in (tbl.schema or [])}
+
+        to_add = [name for name in out_fields if name not in existing_cols]
+        if not to_add:
+            return
+        target = self._qualified_identifier(relation, project=self.project, dataset=self.dataset)
+        for col in to_add:
+            f = out_fields[col]
+            typ = str(f.field_type) if hasattr(f, "field_type") else "STRING"
+            self.client.query(
+                f"ALTER TABLE {target} ADD COLUMN {col} {typ}",
+                location=self.location,
+            ).result()
diff --git a/src/fastflowtransform/executors/databricks_spark_exec.py b/src/fastflowtransform/executors/databricks_spark_exec.py
index 79f28f9..66074b9 100644
--- a/src/fastflowtransform/executors/databricks_spark_exec.py
+++ b/src/fastflowtransform/executors/databricks_spark_exec.py
@@ -5,16 +5,22 @@
 from typing import Any
 
 from pyspark.sql import DataFrame as SDF, SparkSession
+from pyspark.sql.types import DataType
 
-from ..core import Node, relation_for
-from .base import BaseExecutor
+from fastflowtransform.core import Node, relation_for
+from fastflowtransform.executors.base import BaseExecutor
+from fastflowtransform.meta import ensure_meta_table, upsert_meta
 
 
 class DatabricksSparkExecutor(BaseExecutor[SDF]):
+    ENGINE_NAME = "databricks_spark"
     """Spark/Databricks executor without pandas: Python models operate on Spark DataFrames."""
 
     def __init__(self, master: str = "local[*]", app_name: str = "fastflowtransform"):
         self.spark = SparkSession.builder.master(master).appName(app_name).getOrCreate()
+        # Lightweight testing shim so tests can call executor.con.execute("SQL")
+        self.con = _SparkConnShim(self.spark)
+        self._registered_path_sources: dict[str, dict[str, Any]] = {}
 
     # ---------- Frame hooks (required) ----------
     def _read_relation(self, relation: str, node: Node, deps: Iterable[str]) -> SDF:
@@ -87,9 +93,42 @@ def _format_relation_for_ref(self, name: str) -> str:
     def _format_source_reference(
         self, cfg: dict[str, Any], source_name: str, table_name: str
     ) -> str:
-        ident = cfg["identifier"]
-        db = cfg.get("database")
-        return f"{self._q_ident(db)}.{self._q_ident(ident)}" if db else self._q_ident(ident)
+        location = cfg.get("location")
+        identifier = cfg.get("identifier")
+
+        if location:
+            alias = identifier or f"__ff_src_{source_name}_{table_name}"
+            fmt = cfg.get("format")
+            if not fmt:
+                raise KeyError(
+                    f"Source {source_name}.{table_name} requires 'format' when using a location"
+                )
+
+            options = dict(cfg.get("options") or {})
+            descriptor = {
+                "location": location,
+                "format": fmt,
+                "options": options,
+            }
+            existing = self._registered_path_sources.get(alias)
+            if existing != descriptor:
+                reader = self.spark.read.format(fmt)
+                if options:
+                    reader = reader.options(**options)
+                df = reader.load(location)
+                df.createOrReplaceTempView(alias)
+                self._registered_path_sources[alias] = descriptor
+            return self._q_ident(alias)
+
+        if not identifier:
+            raise KeyError(f"Source {source_name}.{table_name} missing identifier")
+
+        catalog = cfg.get("catalog") or cfg.get("database")
+        schema = cfg.get("schema")
+        parts = [p for p in (catalog, schema, identifier) if p]
+        if not parts:
+            parts = [identifier]
+        return ".".join(self._q_ident(str(part)) for part in parts)
 
     def _create_or_replace_view(self, target_sql: str, select_body: str, node: Node) -> None:
         self.spark.sql(f"CREATE OR REPLACE VIEW {target_sql} AS {select_body}")
@@ -101,3 +140,126 @@ def _create_or_replace_view_from_table(
         self, view_name: str, backing_table: str, node: Node
     ) -> None:
         self.spark.sql(f"CREATE OR REPLACE VIEW `{view_name}` AS SELECT * FROM `{backing_table}`")
+
+    # ---- Meta hook ----
+    def on_node_built(self, node: Node, relation: str, fingerprint: str) -> None:
+        """After successful materialization, upsert _ff_meta (best-effort)."""
+        try:
+            ensure_meta_table(self)
+            upsert_meta(self, node.name, relation, fingerprint, "databricks_spark")
+        except Exception:
+            pass
+
+    # ── Incremental API (parity) ─────────────────────────────────────────
+    def exists_relation(self, relation: str) -> bool:
+        """Check whether a table/view exists (optionally qualified with database)."""
+        db, tbl = _split_db_table(relation)
+        if db:
+            return bool(self.spark.catalog._jcatalog.tableExists(db, tbl))
+        return self.spark.catalog.tableExists(tbl)
+
+    def create_table_as(self, relation: str, select_sql: str) -> None:
+        """CREATE TABLE AS with cleaned SELECT body."""
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        self.spark.sql(f"CREATE TABLE {relation} AS {body}")
+
+    def incremental_insert(self, relation: str, select_sql: str) -> None:
+        """INSERT INTO with cleaned SELECT body."""
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        self.spark.sql(f"INSERT INTO {relation} {body}")
+
+    def incremental_merge(self, relation: str, select_sql: str, unique_key: list[str]) -> None:
+        """
+        Try Delta MERGE (Databricks typical). If MERGE fails (non-Delta), fallback to full replace.
+        """
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        pred = " AND ".join([f"t.{k}=s.{k}" for k in unique_key]) or "FALSE"
+        try:
+            # Use inline subquery as source; SET * / INSERT * requires Delta ≥ 1.2 / Spark ≥ 3.4.
+            self.spark.sql(
+                f"""
+                MERGE INTO {relation} AS t
+                USING ({body}) AS s
+                ON {pred}
+                WHEN MATCHED THEN UPDATE SET *
+                WHEN NOT MATCHED THEN INSERT *
+                """
+            )
+        except Exception:
+            # Fallback: Full replace is safer across lake formats
+            self.spark.sql(f"CREATE OR REPLACE TABLE {relation} AS {body}")
+
+    def alter_table_sync_schema(
+        self, relation: str, select_sql: str, *, mode: str = "append_new_columns"
+    ) -> None:
+        """
+        Best-effort additive schema sync:
+          - infer select schema via LIMIT 0
+          - add missing columns as STRING (safe default)
+        """
+        if mode not in {"append_new_columns", "sync_all_columns"}:
+            return
+        # Target schema
+        try:
+            target_df = self.spark.table(relation)
+        except Exception:
+            return
+        existing = {f.name for f in target_df.schema.fields}
+        # Output schema from the SELECT
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        probe = self.spark.sql(f"SELECT * FROM ({body}) q LIMIT 0")
+        to_add = [f for f in probe.schema.fields if f.name not in existing]
+        if not to_add:
+            return
+
+        # Map types best-effort (Spark SQL types); default STRING
+        def _spark_sql_type(dt: DataType) -> str:
+            # Use simple, portable mapping for documentation UIs & broad compatibility
+            return (
+                getattr(dt, "simpleString", lambda: "string")().upper()
+                if hasattr(dt, "simpleString")
+                else "STRING"
+            )
+
+        cols_sql = ", ".join([f"`{f.name}` {_spark_sql_type(f.dataType)}" for f in to_add])
+        self.spark.sql(f"ALTER TABLE {relation} ADD COLUMNS ({cols_sql})")
+
+
+# ────────────────────────── local helpers / shim ──────────────────────────
+class _SparkResult:
+    """Tiny result shim to mimic duckdb/psycopg fetch API in tests."""
+
+    def __init__(self, rows: list[tuple]):
+        self._rows = rows
+
+    def fetchall(self) -> list[tuple]:
+        return self._rows
+
+    def fetchone(self) -> tuple | None:
+        return self._rows[0] if self._rows else None
+
+
+class _SparkConnShim:
+    """Provide .execute(sql) with fetch* for test utilities."""
+
+    def __init__(self, spark: SparkSession):
+        self._spark = spark
+
+    def execute(self, sql: str, params: Any | None = None) -> _SparkResult:
+        if params:
+            # Minimal positional param interpolation for tests is intentionally not implemented.
+            # All internal calls use plain SQL strings for Spark.
+            raise NotImplementedError("SparkConnShim does not support parametrized SQL")
+        df = self._spark.sql(sql)
+        rows = [tuple(r) for r in df.collect()]
+        return _SparkResult(rows)
+
+
+def _split_db_table(qualified: str) -> tuple[str | None, str]:
+    """Split 'db.table' → (db, table); backticks allowed. Returns (None, name) if unqualified."""
+    s = qualified.strip("`")
+    parts = s.split(".")
+    part_len = 2
+    if len(parts) >= part_len:
+        return parts[-2], parts[-1]
+    return None, s
diff --git a/src/fastflowtransform/executors/duckdb_exec.py b/src/fastflowtransform/executors/duckdb_exec.py
index 4798eb0..3a97f58 100644
--- a/src/fastflowtransform/executors/duckdb_exec.py
+++ b/src/fastflowtransform/executors/duckdb_exec.py
@@ -11,16 +11,17 @@
 from duckdb import CatalogException
 
 from fastflowtransform.core import Node, relation_for
+from fastflowtransform.executors.base import BaseExecutor
 from fastflowtransform.meta import ensure_meta_table, upsert_meta
 
-from .base import BaseExecutor
-
 
 def _q(ident: str) -> str:
     return '"' + ident.replace('"', '""') + '"'
 
 
 class DuckExecutor(BaseExecutor[pd.DataFrame]):
+    ENGINE_NAME = "duckdb"
+
     def __init__(self, db_path: str = ":memory:"):
         if db_path and db_path != ":memory:" and "://" not in db_path:
             with suppress(Exception):
@@ -78,7 +79,27 @@ def _format_relation_for_ref(self, name: str) -> str:
     def _format_source_reference(
         self, cfg: dict[str, Any], source_name: str, table_name: str
     ) -> str:
-        return _q(cfg["identifier"])
+        location = cfg.get("location")
+        if location:
+            raise NotImplementedError("DuckDB executor does not support path-based sources yet.")
+
+        identifier = cfg.get("identifier")
+        if not identifier:
+            raise KeyError(f"Source {source_name}.{table_name} missing identifier")
+
+        parts = [
+            p
+            for p in (
+                cfg.get("catalog") or cfg.get("database"),
+                cfg.get("schema"),
+                identifier,
+            )
+            if p
+        ]
+        if not parts:
+            parts = [identifier]
+
+        return ".".join(_q(str(part)) for part in parts)
 
     def _create_or_replace_view(self, target_sql: str, select_body: str, node: Node) -> None:
         self.con.execute(f"create or replace view {target_sql} as {select_body}")
@@ -97,3 +118,70 @@ def on_node_built(self, node: Node, relation: str, fingerprint: str) -> None:
             upsert_meta(self, node.name, relation, fingerprint, "duckdb")
         except Exception:
             pass
+
+    # ── Incremental API ────────────────────────────────────────────────────
+    def exists_relation(self, relation: str) -> bool:
+        sql = """
+          select 1
+          from information_schema.tables
+          where table_schema in ('main','temp')
+            and lower(table_name) = lower(?)
+          limit 1
+        """
+        res = self.con.execute(sql, [relation]).fetchone()
+        return bool(res)
+
+    def create_table_as(self, relation: str, select_sql: str) -> None:
+        # Use only the SELECT body and strip trailing semicolons for safety.
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        self.con.execute(f"create table {relation} as {body}")
+
+    def incremental_insert(self, relation: str, select_sql: str) -> None:
+        # Ensure the inner SELECT is clean (no trailing semicolon; SELECT body only).
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        self.con.execute(f"insert into {relation} {body}")
+
+    def incremental_merge(self, relation: str, select_sql: str, unique_key: list[str]) -> None:
+        """
+        Fallback strategy:
+          - Staging-CTE: data from SELECT
+          - Delete-Merge: delete collisions in target
+          - Insert all staging rows
+        """
+        keys_pred = " AND ".join([f"t.{k}=s.{k}" for k in unique_key])
+        # Clean inner SELECT for CTE: remove trailing semicolon and keep only SELECT body
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        sql = f"""
+        with src as ({body})
+        delete from {relation} t using src s where {keys_pred};
+        insert into {relation} select * from src;
+        """
+        self.con.execute(sql)
+
+    def alter_table_sync_schema(
+        self, relation: str, select_sql: str, *, mode: str = "append_new_columns"
+    ) -> None:
+        """
+        Best-effort: add new columns with inferred type.
+        """
+        # Probe: empty projection from the SELECT (cleaned to avoid parser issues).
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        probe = self.con.execute(f"select * from ({body}) as q limit 0")
+        cols = [c[0] for c in probe.description or []]
+        # vorhandene Spalten
+        existing = {
+            r[0]
+            for r in self.con.execute(
+                "select column_name from information_schema.columns "
+                + "where lower(table_name)=lower(?)",
+                [relation],
+            ).fetchall()
+        }
+        add = [c for c in cols if c not in existing]
+        for c in add:
+            # Typ heuristisch: typeof aus einer CAST-Probe; fallback VARCHAR
+            try:
+                # Versuche Typ aus Expression abzuleiten (best effort)
+                self.con.execute(f"alter table {relation} add column {c} varchar")
+            except Exception:
+                self.con.execute(f"alter table {relation} add column {c} varchar")
diff --git a/src/fastflowtransform/executors/postgres_exec.py b/src/fastflowtransform/executors/postgres_exec.py
index ed453b6..189d803 100644
--- a/src/fastflowtransform/executors/postgres_exec.py
+++ b/src/fastflowtransform/executors/postgres_exec.py
@@ -4,21 +4,25 @@
 
 import pandas as pd
 from sqlalchemy import create_engine, text
-from sqlalchemy.engine import Engine
+from sqlalchemy.engine import Connection, Engine
 from sqlalchemy.exc import ProgrammingError, SQLAlchemyError
 
 from fastflowtransform.core import Node, relation_for
-from fastflowtransform.errors import ProfileConfigError
+from fastflowtransform.errors import ModelExecutionError, ProfileConfigError
 from fastflowtransform.executors._shims import SAConnShim
 from fastflowtransform.executors.base import BaseExecutor
 from fastflowtransform.meta import ensure_meta_table, upsert_meta
 
 
 class PostgresExecutor(BaseExecutor[pd.DataFrame]):
+    ENGINE_NAME = "postgres"
+
     def __init__(self, dsn: str, schema: str | None = None):
         """
-        dsn e.g.: postgresql+psycopg://user:pass@localhost:5432/dbname
-        schema: default schema for reads/writes (if sources.yml does not define one)
+        Initialize Postgres executor.
+
+        dsn     e.g.: postgresql+psycopg://user:pass@localhost:5432/dbname
+        schema  default schema for reads/writes (also used for search_path)
         """
         if not dsn:
             raise ProfileConfigError(
@@ -41,6 +45,26 @@ def _qualified(self, relname: str, schema: str | None = None) -> str:
             return f"{self._q_ident(sch)}.{self._q_ident(relname)}"
         return self._q_ident(relname)
 
+    def _set_search_path(self, conn: Connection | SAConnShim) -> None:
+        if self.schema:
+            conn.execute(text(f"SET LOCAL search_path = {self._q_ident(self.schema)}"))
+
+    def _extract_select_like(self, sql_or_body: str) -> str:
+        """
+        Normalize a SELECT/CTE body:
+        - Accept full statements and strip everything before the first WITH/SELECT.
+        - Strip trailing semicolons/whitespace.
+        """
+        s = (sql_or_body or "").lstrip()
+        lower = s.lower()
+        pos_with = lower.find("with")
+        pos_select = lower.find("select")
+        if pos_with == -1 and pos_select == -1:
+            return s.rstrip(";\n\t ")
+        start = min([p for p in (pos_with, pos_select) if p != -1])
+        return s[start:].rstrip(";\n\t ")
+
+    # ---------- IO ----------
     def _read_relation(self, relation: str, node: Node, deps: Iterable[str]) -> pd.DataFrame:
         qualified = self._qualified(relation)
         try:
@@ -48,8 +72,8 @@ def _read_relation(self, relation: str, node: Node, deps: Iterable[str]) -> pd.D
                 if self.schema:
                     conn.execute(text(f'SET LOCAL search_path = "{self.schema}"'))
                 return pd.read_sql_query(text(f"select * from {qualified}"), conn)
-        except ProgrammingError:
-            raise
+        except ProgrammingError as e:
+            raise e
 
     def _materialize_relation(self, relation: str, df: pd.DataFrame, node: Node) -> None:
         try:
@@ -61,20 +85,24 @@ def _materialize_relation(self, relation: str, df: pd.DataFrame, node: Node) ->
                 schema=self.schema,
                 method="multi",
             )
-        except SQLAlchemyError:
-            # ... bestehende Fehleraufbereitung
-            raise
+        except SQLAlchemyError as e:
+            raise ModelExecutionError(
+                node_name=node.name, relation=self._qualified(relation), message=str(e)
+            ) from e
 
+    # ---------- Python view helper ----------
     def _create_or_replace_view_from_table(
         self, view_name: str, backing_table: str, node: Node
     ) -> None:
         q_view = self._qualified(view_name)
         q_back = self._qualified(backing_table)
-        with self.engine.begin() as c:
-            if self.schema:
-                c.execute(text(f'SET LOCAL search_path = "{self.schema}"'))
-            c.execute(text(f"DROP VIEW IF EXISTS {q_view} CASCADE"))
-            c.execute(text(f"CREATE OR REPLACE VIEW {q_view} AS SELECT * FROM {q_back}"))
+        try:
+            with self.engine.begin() as c:
+                self._set_search_path(c)
+                c.execute(text(f"DROP VIEW IF EXISTS {q_view} CASCADE"))
+                c.execute(text(f"CREATE OR REPLACE VIEW {q_view} AS SELECT * FROM {q_back}"))
+        except Exception as e:
+            raise ModelExecutionError(node.name, q_view, str(e)) from e
 
     def _frame_name(self) -> str:
         return "pandas"
@@ -86,24 +114,44 @@ def _format_relation_for_ref(self, name: str) -> str:
     def _format_source_reference(
         self, cfg: dict[str, Any], source_name: str, table_name: str
     ) -> str:
-        ident = cfg["identifier"]
-        src_schema = cfg.get("schema")
-        return self._qualified(ident, schema=src_schema)
+        if cfg.get("location"):
+            raise NotImplementedError("Postgres executor does not support path-based sources.")
+
+        ident = cfg.get("identifier")
+        if not ident:
+            raise KeyError(f"Source {source_name}.{table_name} missing identifier")
+
+        relation = self._qualified(ident, schema=cfg.get("schema"))
+        database = cfg.get("database") or cfg.get("catalog")
+        if database:
+            return f"{self._q_ident(database)}.{relation}"
+        return relation
 
     def _create_or_replace_view(self, target_sql: str, select_body: str, node: Node) -> None:
-        with self.engine.begin() as conn:
-            if self.schema:
-                conn.execute(text(f"SET LOCAL search_path = {self._q_ident(self.schema)}"))
-            conn.execute(text(f"DROP VIEW IF EXISTS {target_sql} CASCADE"))
-            conn.execute(text(f"CREATE OR REPLACE VIEW {target_sql} AS {select_body}"))
+        try:
+            with self.engine.begin() as conn:
+                self._set_search_path(conn)
+                conn.execute(text(f"DROP VIEW IF EXISTS {target_sql} CASCADE"))
+                conn.execute(text(f"CREATE OR REPLACE VIEW {target_sql} AS {select_body}"))
+        except Exception as e:
+            preview = f"-- target={target_sql}\n{select_body}"
+            raise ModelExecutionError(node.name, target_sql, str(e), sql_snippet=preview) from e
 
     def _create_or_replace_table(self, target_sql: str, select_body: str, node: Node) -> None:
-        with self.engine.begin() as conn:
-            if self.schema:
-                conn.execute(text(f"SET LOCAL search_path = {self._q_ident(self.schema)}"))
-            conn.execute(text(f"DROP TABLE IF EXISTS {target_sql} CASCADE"))
-            conn.execute(text(f"CREATE TABLE {target_sql} AS {select_body}"))
-
+        """
+        Postgres does NOT support 'CREATE OR REPLACE TABLE'.
+        Use DROP TABLE IF EXISTS + CREATE TABLE AS, and accept CTE bodies.
+        """
+        try:
+            with self.engine.begin() as conn:
+                self._set_search_path(conn)
+                conn.execute(text(f"DROP TABLE IF EXISTS {target_sql} CASCADE"))
+                conn.execute(text(f"CREATE TABLE {target_sql} AS {select_body}"))
+        except Exception as e:
+            preview = f"-- target={target_sql}\n{select_body}"
+            raise ModelExecutionError(node.name, target_sql, str(e), sql_snippet=preview) from e
+
+    # ---------- meta ----------
     def on_node_built(self, node: Node, relation: str, fingerprint: str) -> None:
         """
         Write/update _ff_meta in the current schema after a successful build.
@@ -113,3 +161,80 @@ def on_node_built(self, node: Node, relation: str, fingerprint: str) -> None:
             upsert_meta(self, node.name, relation, fingerprint, "postgres")
         except Exception:
             pass
+
+    # ── Incremental API ────────────────────────────────────────────────────
+    def exists_relation(self, relation: str) -> bool:
+        """
+        Return True if a table OR view exists for 'relation' in current schema.
+        """
+        sql = text(
+            """
+            select 1
+            from information_schema.tables
+            where table_schema = current_schema()
+              and lower(table_name) = lower(:t)
+            union all
+            select 1
+            from information_schema.views
+            where table_schema = current_schema()
+              and lower(table_name) = lower(:t)
+            limit 1
+            """
+        )
+        with self.engine.begin() as con:
+            return bool(con.execute(sql, {"t": relation}).fetchone())
+
+    def create_table_as(self, relation: str, select_sql: str) -> None:
+        body = self._extract_select_like(select_sql)
+        qrel = self._qualified(relation)
+        with self.engine.begin() as con:
+            self._set_search_path(con)
+            con.execute(text(f"create table {qrel} as {body}"))
+
+    def incremental_insert(self, relation: str, select_sql: str) -> None:
+        body = self._extract_select_like(select_sql)
+        qrel = self._qualified(relation)
+        with self.engine.begin() as con:
+            self._set_search_path(con)
+            con.execute(text(f"insert into {qrel} {body}"))
+
+    def incremental_merge(self, relation: str, select_sql: str, unique_key: list[str]) -> None:
+        """
+        Portable fallback: staging + delete + insert.
+        """
+        body = self._extract_select_like(select_sql)
+        qrel = self._qualified(relation)
+        pred = " AND ".join([f"t.{k}=s.{k}" for k in unique_key])
+        with self.engine.begin() as con:
+            self._set_search_path(con)
+            con.execute(text(f"create temporary table ff_stg as {body}"))
+            try:
+                con.execute(text(f"delete from {qrel} t using ff_stg s where {pred}"))
+                con.execute(text(f"insert into {qrel} select * from ff_stg"))
+            finally:
+                con.execute(text("drop table if exists ff_stg"))
+
+    def alter_table_sync_schema(
+        self, relation: str, select_sql: str, *, mode: str = "append_new_columns"
+    ) -> None:
+        """
+        Add new columns present in SELECT but missing on target (as text).
+        """
+        body = self._extract_select_like(select_sql)
+        qrel = self._qualified(relation)
+        with self.engine.begin() as con:
+            self._set_search_path(con)
+            cols = [r[0] for r in con.execute(text(f"select * from ({body}) q limit 0"))]
+            existing = {
+                r[0]
+                for r in con.execute(
+                    text(
+                        "select column_name from information_schema.columns "
+                        "where table_schema = current_schema() and lower(table_name)=lower(:t)"
+                    ),
+                    {"t": relation},
+                ).fetchall()
+            }
+            add = [c for c in cols if c not in existing]
+            for c in add:
+                con.execute(text(f'alter table {qrel} add column "{c}" text'))
diff --git a/src/fastflowtransform/executors/snowflake_snowpark_exec.py b/src/fastflowtransform/executors/snowflake_snowpark_exec.py
index 5d948a3..b63b21e 100644
--- a/src/fastflowtransform/executors/snowflake_snowpark_exec.py
+++ b/src/fastflowtransform/executors/snowflake_snowpark_exec.py
@@ -6,11 +6,13 @@
 
 from snowflake.snowpark import DataFrame as SNDF, Session
 
-from ..core import Node, relation_for
-from .base import BaseExecutor
+from fastflowtransform.core import Node, relation_for
+from fastflowtransform.executors.base import BaseExecutor
+from fastflowtransform.meta import ensure_meta_table, upsert_meta
 
 
 class SnowflakeSnowparkExecutor(BaseExecutor[SNDF]):
+    ENGINE_NAME = "snowflake_snowpark"
     """Snowflake executor operating on Snowpark DataFrames (no pandas)."""
 
     def __init__(self, cfg: dict):
@@ -18,6 +20,8 @@ def __init__(self, cfg: dict):
         self.session = Session.builder.configs(cfg).create()
         self.database = cfg["database"]
         self.schema = cfg["schema"]
+        # Provide a tiny testing shim so tests can call executor.con.execute("SQL")
+        self.con = _SFCursorShim(self.session)
 
     # ---------- Helpers ----------
     def _q(self, s: str) -> str:
@@ -92,9 +96,19 @@ def _format_relation_for_ref(self, name: str) -> str:
     def _format_source_reference(
         self, cfg: dict[str, Any], source_name: str, table_name: str
     ) -> str:
-        ident = cfg["identifier"]
-        db = cfg.get("database", self.database)
-        sch = cfg.get("schema", self.schema)
+        if cfg.get("location"):
+            raise NotImplementedError("Snowflake executor does not support path-based sources.")
+
+        ident = cfg.get("identifier")
+        if not ident:
+            raise KeyError(f"Source {source_name}.{table_name} missing identifier")
+
+        db = cfg.get("database") or cfg.get("catalog") or self.database
+        sch = cfg.get("schema") or self.schema
+        if not db or not sch:
+            raise KeyError(
+                f"Source {source_name}.{table_name} missing database/schema for Snowflake"
+            )
         return f"{self._q(db)}.{self._q(sch)}.{self._q(ident)}"
 
     def _create_or_replace_view(self, target_sql: str, select_body: str, node: Node) -> None:
@@ -109,3 +123,116 @@ def _create_or_replace_view_from_table(
         view_id = self._qualified(view_name)
         back_id = self._qualified(backing_table)
         self.session.sql(f"CREATE OR REPLACE VIEW {view_id} AS SELECT * FROM {back_id}").collect()
+
+    # ---- Meta hook ----
+    def on_node_built(self, node: Node, relation: str, fingerprint: str) -> None:
+        """After successful materialization, upsert _ff_meta (best-effort)."""
+        try:
+            ensure_meta_table(self)
+            upsert_meta(self, node.name, relation, fingerprint, "snowflake_snowpark")
+        except Exception:
+            pass
+
+    # ── Incremental API (parity with DuckDB/PG) ──────────────────────────
+    def exists_relation(self, relation: str) -> bool:
+        """Check existence via information_schema.tables."""
+        db = self._q(self.database)
+        q = f"""
+          select 1
+          from {db}.information_schema.tables
+          where table_schema = {self._q(self.schema)}
+            and lower(table_name) = lower({self._q(relation)})
+          limit 1
+        """
+        try:
+            return bool(self.session.sql(q).collect())
+        except Exception:
+            return False
+
+    def create_table_as(self, relation: str, select_sql: str) -> None:
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        self.session.sql(f"CREATE OR REPLACE TABLE {self._qualified(relation)} AS {body}").collect()
+
+    def incremental_insert(self, relation: str, select_sql: str) -> None:
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        self.session.sql(f"INSERT INTO {self._qualified(relation)} {body}").collect()
+
+    def incremental_merge(self, relation: str, select_sql: str, unique_key: list[str]) -> None:
+        """
+        Portable fallback without explicit column list:
+          - WITH src AS (<body>)
+          - DELETE ... USING src ...
+          - INSERT ... SELECT * FROM src
+        This avoids Snowflake MERGE column listing complexity.
+        """
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        pred = " AND ".join([f"t.{k}=s.{k}" for k in unique_key]) or "FALSE"
+        qrel = self._qualified(relation)
+        sql = f"""
+        WITH src AS ({body})
+        DELETE FROM {qrel} AS t USING src AS s WHERE {pred};
+        INSERT INTO {qrel} SELECT * FROM src;
+        """
+        self.session.sql(sql).collect()
+
+    def alter_table_sync_schema(
+        self, relation: str, select_sql: str, *, mode: str = "append_new_columns"
+    ) -> None:
+        """
+        Best-effort additive schema sync:
+          - infer SELECT schema via LIMIT 0
+          - add missing columns as STRING
+        """
+        if mode not in {"append_new_columns", "sync_all_columns"}:
+            return
+        qrel = self._qualified(relation)
+        try:
+            existing = {
+                r[0]
+                for r in self.session.sql(
+                    f"""
+                select column_name
+                from {self._q(self.database)}.information_schema.columns
+                where table_schema={self._q(self.schema)}
+                  and lower(table_name)=lower({self._q(relation)})
+                """
+                ).collect()
+            }
+        except Exception:
+            existing = set()
+        # Probe SELECT columns
+        body = self._first_select_body(select_sql).strip().rstrip(";\n\t ")
+        probe = self.session.sql(f"SELECT * FROM ({body}) q WHERE 1=0")
+        probe_cols = list(probe.schema.names)
+        to_add = [c for c in probe_cols if c not in existing]
+        if not to_add:
+            return
+        cols_sql = ", ".join(f"{self._q(c)} STRING" for c in to_add)
+        self.session.sql(f"ALTER TABLE {qrel} ADD COLUMN {cols_sql}").collect()
+
+
+# ────────────────────────── local testing shim ───────────────────────────
+class _SFCursorShim:
+    """Very small shim to expose .execute(...).fetch* for tests."""
+
+    def __init__(self, session: Session):
+        self._session = session
+
+    def execute(self, sql: str, params: Any | None = None) -> _SFResult:
+        if params:
+            # Parametrized SQL not needed in our internal calls
+            raise NotImplementedError("Snowflake shim does not support parametrized SQL")
+        rows = self._session.sql(sql).collect()
+        as_tuples = [tuple(getattr(r, k) for k in r.asDict()) for r in rows] if rows else []
+        return _SFResult(as_tuples)
+
+
+class _SFResult:
+    def __init__(self, rows: list[tuple]):
+        self._rows = rows
+
+    def fetchall(self) -> list[tuple]:
+        return self._rows
+
+    def fetchone(self) -> tuple | None:
+        return self._rows[0] if self._rows else None
diff --git a/src/fastflowtransform/incremental.py b/src/fastflowtransform/incremental.py
new file mode 100644
index 0000000..8c2cab6
--- /dev/null
+++ b/src/fastflowtransform/incremental.py
@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from contextlib import suppress
+from typing import Any
+
+from sqlalchemy import text as _sa_text
+
+from fastflowtransform.core import relation_for
+from fastflowtransform.errors import ModelExecutionError
+
+
+def _normalize_unique_key(val: Any) -> list[str]:
+    if val is None:
+        return []
+    if isinstance(val, str):
+        s = val.strip()
+        return [s] if s else []
+    if isinstance(val, (list, tuple)):
+        out: list[str] = []
+        for x in val:
+            if isinstance(x, str) and x.strip():
+                out.append(x.strip())
+        return out
+    return []
+
+
+def _get_on_schema_change(meta: dict | None) -> str:
+    v = (meta or {}).get("on_schema_change") or "ignore"
+    v = str(v).strip().lower()
+    if v not in {"ignore", "append_new_columns", "sync_all_columns"}:
+        return "ignore"
+    return v
+
+
+# ---------- Helper ----------
+
+
+def _exec_sql(exe: Any, sql: str) -> None:
+    """Best-effort SQL execution across engines (DuckDB/PG/Snowflake/BQ shims)."""
+    if hasattr(exe, "con") and hasattr(exe.con, "execute"):  # DuckDB
+        exe.con.execute(sql)
+        return
+    if hasattr(exe, "engine"):  # SQLAlchemy Engine
+        with exe.engine.begin() as conn:
+            conn.execute(_sa_text(sql))
+        return
+    if hasattr(exe, "execute"):  # BigQuery-like shim
+        exe.execute(sql)
+        return
+    if hasattr(exe, "run_sql_raw"):
+        exe.run_sql_raw(sql)
+        return
+    raise RuntimeError("No suitable raw-SQL execution path on executor")
+
+
+def _safe_exists(executor: Any, relation: Any) -> bool:
+    try:
+        return bool(executor.exists_relation(relation))
+    except Exception:
+        return False
+
+
+def _env_with_incremental(jenv: Any, is_incr: bool) -> Any:
+    _overlay = getattr(jenv, "overlay", None)
+    env = _overlay() if callable(_overlay) else None
+    if env is None:
+
+        class _EnvShim:
+            def __init__(self, base):
+                self._base = base
+                self.globals = dict(getattr(base, "globals", {}))
+
+            def __getattr__(self, name):
+                return getattr(self._base, name)
+
+        env = _EnvShim(jenv)
+    getattr(env, "globals", {}).update({"is_incremental": lambda: is_incr})
+    return env
+
+
+def _render_sql_safe(executor: Any, node: Any, env: Any) -> str:
+    try:
+        return executor.render_sql(
+            node,
+            env,
+            ref_resolver=lambda nm: executor._resolve_ref(nm, env),
+            source_resolver=executor._resolve_source,
+        )
+    except Exception:
+        return executor.render_sql(node, env)
+
+
+def _wrap_and_raise_factory(node_name: str, relation: Any, rendered_sql: str | None) -> Callable:
+    def _wrap_and_raise(e: Exception) -> None:
+        tail = rendered_sql[-600:].strip() if rendered_sql else None
+        msg = f"{e.__class__.__name__}: {e}"
+        raise ModelExecutionError(node_name, relation, msg, sql_snippet=tail) from e
+
+    return _wrap_and_raise
+
+
+def _maybe_schema_sync(executor: Any, relation: Any, rendered_sql: str, policy: str) -> None:
+    if policy in {"append_new_columns", "sync_all_columns"} and hasattr(
+        executor, "alter_table_sync_schema"
+    ):
+        with suppress(Exception):
+            executor.alter_table_sync_schema(relation, rendered_sql, mode=policy)
+
+
+def _create_table_as_or_replace(executor: Any, relation: Any, rendered_sql: str) -> None:
+    try:
+        executor.create_table_as(relation, rendered_sql)
+    except Exception:
+        _exec_sql(executor, f"create or replace table {relation} as {rendered_sql}")
+
+
+UniqueKey = str | Sequence[str] | None
+
+
+def _merge_or_insert_with_fallback(
+    executor: Any,
+    relation: Any,
+    rendered_sql: str,
+    unique_key: UniqueKey,
+) -> None:
+    if unique_key:
+        # auf Liste normalisieren
+        if isinstance(unique_key, str):
+            keys: list[str] = [unique_key]
+        else:
+            keys = list(unique_key)  # Sequence[str] -> List[str]
+
+        try:
+            # merge mit Keys
+            executor.incremental_merge(relation, rendered_sql, keys)
+            return
+        except Exception:
+            _exec_sql(executor, f"create or replace table {relation} as {rendered_sql}")
+            return
+
+    # kein unique_key -> insert
+    try:
+        executor.incremental_insert(relation, rendered_sql)
+    except Exception:
+        _exec_sql(executor, f"create or replace table {relation} as {rendered_sql}")
+
+
+# ---------- Run or dispatch ----------
+
+
+def run_or_dispatch(executor: Any, node: Any, jenv: Any) -> None:
+    """
+    Wrapper für executor.run_sql(...):
+    - fängt materialized='incremental' ab und plant nenewu/merge/insert.
+    - sonst Delegation an executor.
+    """
+    meta = getattr(node, "meta", {}) or {}
+    materialized = meta.get("materialized", "table")
+
+    if materialized != "incremental":
+        try:
+            return executor.run_sql(node, jenv)
+        except Exception as e:
+            rel = relation_for(node.name)
+            msg = f"{e.__class__.__name__}: {e}"
+            raise ModelExecutionError(node.name, rel, msg, sql_snippet=None) from e
+
+    relation = relation_for(node.name)
+    exists = _safe_exists(executor, relation)
+    env = _env_with_incremental(jenv, exists)
+    rendered_sql = _render_sql_safe(executor, node, env)
+    wrap_and_raise = _wrap_and_raise_factory(node.name, relation, rendered_sql)
+
+    unique_key = _normalize_unique_key(meta.get("unique_key"))
+    schema_policy = _get_on_schema_change(meta)
+
+    if not exists:
+        try:
+            _create_table_as_or_replace(executor, relation, rendered_sql)
+        except Exception as e:
+            wrap_and_raise(e)
+        return
+
+    # exists -> inkrementeller Pfad
+    _maybe_schema_sync(executor, relation, rendered_sql, schema_policy)
+    try:
+        _merge_or_insert_with_fallback(executor, relation, rendered_sql, unique_key)
+    except Exception as e:
+        wrap_and_raise(e)
diff --git a/src/fastflowtransform/logging.py b/src/fastflowtransform/logging.py
new file mode 100644
index 0000000..16d2a42
--- /dev/null
+++ b/src/fastflowtransform/logging.py
@@ -0,0 +1,301 @@
+# fastflowtransform/logging.py
+from __future__ import annotations
+
+import contextvars
+import json
+
+# IMPORTANT: avoid clashing with this module name
+import logging as _logging
+import os
+import sys
+from collections.abc import Generator, Iterable
+from contextlib import contextmanager
+from logging import LogRecord
+from typing import Any
+
+import typer
+
+# -----------------------------------------------------------------------------
+# Context (enriched into log records) and runtime flags
+# -----------------------------------------------------------------------------
+_run_id: contextvars.ContextVar[str | None] = contextvars.ContextVar("ff_run_id", default=None)
+_engine: contextvars.ContextVar[str | None] = contextvars.ContextVar("ff_engine", default=None)
+_env: contextvars.ContextVar[str | None] = contextvars.ContextVar("ff_env", default=None)
+_node: contextvars.ContextVar[str | None] = contextvars.ContextVar("ff_node", default=None)
+
+_dbg: contextvars.ContextVar[bool] = contextvars.ContextVar("ff_dbg", default=False)
+_sqldbg: contextvars.ContextVar[bool] = contextvars.ContextVar("ff_sqldbg", default=False)
+
+
+def bind_context(
+    *,
+    run_id: str | None = None,
+    engine: str | None = None,
+    env: str | None = None,
+    node: str | None = None,
+) -> None:
+    """Bind fields that get injected into every record."""
+    if run_id is not None:
+        _run_id.set(run_id)
+    if engine is not None:
+        _engine.set(engine)
+    if env is not None:
+        _env.set(env)
+    if node is not None:
+        _node.set(node)
+
+
+def clear_context() -> None:
+    """Clear all bound fields."""
+    _run_id.set(None)
+    _engine.set(None)
+    _env.set(None)
+    _node.set(None)
+
+
+@contextmanager
+def bound_context(
+    *,
+    run_id: str | None = None,
+    engine: str | None = None,
+    env: str | None = None,
+    node: str | None = None,
+) -> Generator[None, None, None]:
+    """
+    Temporarily bind (or override) selected fields.
+    Only 'node' is auto-cleared on exit; other fields persist unless you pass new values.
+    """
+    prev = (_run_id.get(), _engine.get(), _env.get(), _node.get())
+    try:
+        bind_context(run_id=run_id, engine=engine, env=env, node=node)
+        yield
+    finally:
+        # restore previous values; keep run_id/engine/env stable if you want by not overriding
+        _run_id.set(prev[0])
+        _engine.set(prev[1])
+        _env.set(prev[2])
+        _node.set(prev[3])
+
+
+def set_flags(*, debug: bool | None = None, sql_debug: bool | None = None) -> None:
+    """Set runtime flags (thread/task-local)."""
+    if debug is not None:
+        _dbg.set(bool(debug))
+    if sql_debug is not None:
+        _sqldbg.set(bool(sql_debug))
+
+
+def is_debug_enabled() -> bool:
+    return _dbg.get() or get_logger().isEnabledFor(_logging.DEBUG)
+
+
+def is_sql_debug_enabled() -> bool:
+    if _sqldbg.get():
+        return True
+    if os.getenv("FFT_SQL_DEBUG", "").lower() in ("1", "true", "yes", "on"):
+        return True
+    return get_logger("sql").isEnabledFor(_logging.DEBUG)
+
+
+# -----------------------------------------------------------------------------
+# Formatters and filter
+# -----------------------------------------------------------------------------
+class _CtxFilter(_logging.Filter):
+    def filter(self, record: LogRecord) -> bool:  # inject context
+        record.ff_run_id = _run_id.get()
+        record.ff_engine = _engine.get()
+        record.ff_env = _env.get()
+        record.ff_node = _node.get()
+        return True
+
+
+class _ConsoleFormatter(_logging.Formatter):
+    # Example:
+    # 2025-10-28 10:15:12 INFO [DUCK dev users.ff] fastflowtransform.run: message
+    _fmt = "%(asctime)s %(levelname)s [%(ff_engine)s %(ff_env)s %(ff_node)s] %(name)s: %(message)s"
+    _date = "%Y-%m-%d %H:%M:%S"
+
+    def __init__(self) -> None:
+        super().__init__(self._fmt, self._date)
+
+
+class _JsonFormatter(_logging.Formatter):
+    def format(self, record: LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S"),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+            "ff": {
+                "run_id": getattr(record, "ff_run_id", None),
+                "engine": getattr(record, "ff_engine", None),
+                "env": getattr(record, "ff_env", None),
+                "node": getattr(record, "ff_node", None),
+            },
+        }
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False)
+
+
+# -----------------------------------------------------------------------------
+# Setup (one place to configure everything)
+# -----------------------------------------------------------------------------
+def setup(
+    *,
+    level: int = _logging.INFO,
+    json: bool = False,
+    to_stderr: bool = False,
+    propagate_sql: bool = False,
+) -> None:
+    """
+    Configure the 'fastflowtransform' logging tree.
+    Idempotent: previous console handlers installed by this function are removed.
+    """
+    root = get_logger()  # 'fastflowtransform'
+    root.setLevel(level)
+
+    # Remove previous console handlers we installed
+    for h in list(root.handlers):
+        try:
+            if h.get_name() == "ff_console":
+                root.removeHandler(h)
+        except Exception:
+            # get_name gibt es ab 3.8 - fallback über .name
+            if getattr(h, "name", None) == "ff_console":
+                root.removeHandler(h)
+
+    handler = _logging.StreamHandler(sys.stderr if to_stderr else sys.stdout)
+    handler.set_name("ff_console")
+    handler.setFormatter(_JsonFormatter() if json else _ConsoleFormatter())
+    handler.addFilter(_CtxFilter())
+    root.addHandler(handler)
+
+    # SQL channel inherits formatter/sink via propagation
+    sql = get_logger("sql")
+    sql.setLevel(_logging.DEBUG if propagate_sql else level)
+    sql.propagate = True
+
+    # Also ensure a NullHandler at import-time on the root package
+    _logging.getLogger("fastflowtransform").addHandler(_logging.NullHandler())
+
+
+def setup_from_cli_flags(
+    *,
+    verbose: int = 0,
+    quiet: int = 0,
+    json: bool = False,
+    sql_debug: bool = False,
+    to_stderr: bool = False,
+) -> None:
+    """
+    Convenience for CLI:
+      quiet >=1 → ERROR
+      verbose=0 → WARNING
+      verbose=1 → INFO
+      verbose>=2 → DEBUG
+    """
+    verbose_debug_level = 2
+    level = _logging.WARNING
+    if quiet >= 1:
+        level = _logging.ERROR
+    elif verbose == 1:
+        level = _logging.INFO
+    elif verbose >= verbose_debug_level:
+        level = _logging.DEBUG
+
+    env_sql = os.getenv("FFT_SQL_DEBUG", "").lower() in ("1", "true", "yes", "on")
+    setup(
+        level=level,
+        json=json,
+        to_stderr=to_stderr,
+        propagate_sql=(sql_debug or env_sql or verbose >= verbose_debug_level),
+    )
+    set_flags(
+        debug=(verbose >= verbose_debug_level),
+        sql_debug=(sql_debug or env_sql or verbose >= verbose_debug_level),
+    )
+
+
+# -----------------------------------------------------------------------------
+# Public helpers (single import point)
+# -----------------------------------------------------------------------------
+def get_logger(name: str | None = None) -> _logging.Logger:
+    """
+    Return a namespaced logger under 'fastflowtransform'.
+    get_logger()          → 'fastflowtransform'
+    get_logger("sql")     → 'fastflowtransform.sql'
+    get_logger("cli.run") → 'fastflowtransform.cli.run'
+    """
+    base = "fastflowtransform"
+    return _logging.getLogger(base if not name else f"{base}.{name}")
+
+
+def echo(*args: Any, **kwargs: Any) -> None:
+    """
+    Thin passthrough to typer.echo(...).
+
+    Usage:
+        echo("hello")
+        echo("to stderr", err=True)
+        echo("no newline", nl=False)
+        echo("colored", color=True)
+    """
+    typer.echo(*args, **kwargs)
+
+
+def echo_debug(*args: Any, **kwargs: Any) -> None:
+    """
+    Like typer.echo(...), but only emits when `fastflowtransform` logger is in DEBUG.
+
+    Usage:
+        echo_debug("SQL preview:", sql_text)
+        echo_debug("to stderr only in debug", err=True)
+    """
+    logger = _logging.getLogger("fastflowtransform")
+    if logger.isEnabledFor(_logging.DEBUG):
+        typer.echo(*args, **kwargs)
+
+
+def info(msg: str, *args: Any, **kwargs: Any) -> None:
+    get_logger("app").info(msg, *args, **kwargs)
+
+
+def warn(msg: str, *args: Any, **kwargs: Any) -> None:
+    get_logger("app").warning(msg, *args, **kwargs)
+
+
+def error(msg: str, *args: Any, **kwargs: Any) -> None:
+    get_logger("app").error(msg, *args, **kwargs)
+
+
+def debug(msg: str, *args: Any, **kwargs: Any) -> None:
+    """General debug; gated by runtime flag OR logger level."""
+    if is_debug_enabled():
+        get_logger("app").debug(msg, *args, **kwargs)
+
+
+def dprint(*parts: Any) -> None:
+    """
+    Lightweight stdout debugging; useful for quick probes during dev.
+    Only prints when general debug is enabled.
+    """
+    if is_debug_enabled():
+        print("[DBG]", *parts, file=sys.stdout)
+
+
+def sql_debug(msg: str, *args: Any, **kwargs: Any) -> None:
+    """Single-line SQL debug; appears only when SQL debug is enabled."""
+    if is_sql_debug_enabled():
+        get_logger("sql").debug(msg, *args, **kwargs)
+
+
+def sql_block(title: str, lines: Iterable[str] | str) -> None:
+    """Pretty multi-line SQL preview gated by SQL debug."""
+    if not is_sql_debug_enabled():
+        return
+    body = lines.rstrip() if isinstance(lines, str) else "\n".join(str(x) for x in lines).rstrip()
+    if title:
+        get_logger("sql").debug("%s\n%s", title, body)
+    else:
+        get_logger("sql").debug("%s", body)
diff --git a/src/fastflowtransform/schema_loader.py b/src/fastflowtransform/schema_loader.py
new file mode 100644
index 0000000..2091352
--- /dev/null
+++ b/src/fastflowtransform/schema_loader.py
@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+
+# ---- Public datatypes -------------------------------------------------------
+
+Severity = Literal["error", "warn"]
+
+
+@dataclass(frozen=True)
+class TestSpec:
+    """
+    Normalisierte Test-Spezifikation für die CLI.
+    Beispiel: not_null(users_enriched.email), unique(users_enriched.id),
+              accepted_values(users_enriched.email, values=[...]) …
+    """
+
+    type: str  # "not_null" | "unique" | "accepted_values" | …
+    table: str
+    column: str | None = None
+    params: dict[str, Any] = field(default_factory=dict)
+    severity: Severity = "error"
+    tags: list[str] = field(default_factory=list)
+
+    def __post_init__(self):
+        if self.params is None:
+            object.__setattr__(self, "params", {})
+        if self.tags is None:
+            object.__setattr__(self, "tags", [])
+
+
+# ---- Loader -----------------------------------------------------------------
+
+
+def load_schema_tests(project_dir: Path) -> list[TestSpec]:
+    """
+    Lädt dbt-ähnliche Schema-YAMLs (version: 2) unter models/**.yml (& schema.yml),
+    und gibt normalisierte TestSpec-Objekte zurück.
+    """
+    project_dir = Path(project_dir)
+    models_dir = project_dir / "models"
+    if not models_dir.exists():
+        return []
+
+    files: list[Path] = []
+    for p in models_dir.rglob("*.yml"):
+        files.append(p)
+    # Deduplicate
+    files = sorted(set(files))
+
+    specs: list[TestSpec] = []
+    version = 2
+    for yml in files:
+        try:
+            data = yaml.safe_load(yml.read_text(encoding="utf-8")) or {}
+        except Exception:
+            continue
+        if (data or {}).get("version") != version:
+            continue
+        for model in data.get("models") or []:
+            name = str(model.get("name") or "").strip()
+            if not name:
+                continue
+            table = name[:-3] if name.endswith(".ff") else name
+            # Column-Tests
+            for col in model.get("columns") or []:
+                col_name = str(col.get("name") or "").strip()
+                if not col_name:
+                    continue
+                for test_entry in col.get("tests") or []:
+                    _expand_test_entry(
+                        specs, table, col_name, test_entry, default_tags=model.get("tags") or []
+                    )
+            # Model-level tests (optional
+            for test_entry in model.get("tests") or []:
+                _expand_test_entry(
+                    specs, table, None, test_entry, default_tags=model.get("tags") or []
+                )
+    return specs
+
+
+def _normalize_severity(val: Any) -> Severity:
+    """
+    Normalize arbitrary user input to a Severity literal ("error"|"warn").
+    Defaults to "error" for unknown values.
+    """
+    s = str(val).lower() if val is not None else "error"
+    return "warn" if s == "warn" else "error"
+
+
+def _expand_test_entry(
+    out: list[TestSpec],
+    table: str,
+    column: str | None,
+    test_entry: Any,
+    default_tags: list[str],
+) -> None:
+    """
+    test_entry kann sein:
+      - "unique"
+      - {"unique": {severity: "warn", ...}}
+      - {"accepted_values": {values: [...], severity: "error"}}
+    """
+    if isinstance(test_entry, str):
+        t = test_entry
+        params: dict[str, Any] = {}
+    elif isinstance(test_entry, dict) and len(test_entry) == 1:
+        t, params = next(iter(test_entry.items()))
+        params = params or {}
+    else:
+        return
+
+    severity = _normalize_severity(params.pop("severity", "error"))
+    tags = list(default_tags or [])
+    # Optional: test-specific tags
+    if "tags" in params and isinstance(params["tags"], list):
+        tags.extend([str(x) for x in params.pop("tags")])
+
+    out.append(
+        TestSpec(
+            type=str(t),
+            table=table,
+            column=column,
+            params=params,
+            severity=severity,
+            tags=tags,
+        )
+    )
diff --git a/src/fastflowtransform/seeding.py b/src/fastflowtransform/seeding.py
index 446c2c3..06a10d0 100644
--- a/src/fastflowtransform/seeding.py
+++ b/src/fastflowtransform/seeding.py
@@ -1,16 +1,27 @@
 # src/fastflowtransform/seeding.py
 from __future__ import annotations
 
+import math
 import uuid
+from contextlib import suppress
 from pathlib import Path
-from typing import Any
+from time import perf_counter
+from typing import Any, NamedTuple
 
 import duckdb as _dd
 import pandas as pd
 import yaml
 
+from fastflowtransform.logging import echo
+
+# If you use this in a CLI, your code elsewhere should provide _prepare_context.
+
+
+# ----------------------------- File I/O & Schema (dtypes) -----------------------------
+
 
 def _read_seed_file(path: Path) -> pd.DataFrame:
+    """Read a seed file (.csv, .parquet, .pq) into a pandas DataFrame."""
     if path.suffix.lower() == ".csv":
         return pd.read_csv(path)
     if path.suffix.lower() in (".parquet", ".pq"):
@@ -19,62 +30,299 @@ def _read_seed_file(path: Path) -> pd.DataFrame:
 
 
 def _apply_schema(df: pd.DataFrame, table: str, schema_cfg: dict | None) -> pd.DataFrame:
+    """
+    Apply optional pandas dtypes from seeds/schema.yml for a given table key.
+    Expected structure:
+      dtypes:
+        <table_key>:
+          col_a: string
+          col_b: int64
+    Soft-fails on casting errors to avoid blocking loads.
+    """
     if not schema_cfg:
         return df
-    cfg = schema_cfg.get(table) or {}
-    dtypes: dict[str, str] = cfg.get("dtypes") or {}
-    if dtypes:
-        # Apply pandas dtypes, ignore unknown columns
-        cast_map = {col: dtype for col, dtype in dtypes.items() if col in df.columns}
-        try:
-            return df.astype(cast_map)
-        except Exception:
-            # Soft-fail: load the data instead of aborting - logging might be useful here
-            pass
-    return df
+    cfg = schema_cfg.get("dtypes") or {}
+    dtypes: dict[str, str] = cfg.get(table) or {}
+    if not dtypes:
+        return df
+
+    cast_map = {col: dtype for col, dtype in dtypes.items() if col in df.columns}
+    try:
+        return df.astype(cast_map)
+    except Exception:
+        # Prefer loading data over failing the run; you may log a warning here.
+        return df
+
+
+# -------------------------------- Identifier utilities --------------------------------
+
+
+def _dq(ident: str) -> str:
+    """Double-quote an SQL identifier (DuckDB/Postgres compatible)."""
+    return '"' + ident.replace('"', '""') + '"'
+
+
+def _is_qualified(name: str) -> bool:
+    """Return True if the provided table name appears to be schema-qualified."""
+    return "." in name
+
+
+def _qualify(table: str, schema: str | None) -> str:
+    """
+    Return a safely quoted, optionally schema-qualified identifier.
+    - Respects already-qualified names like raw.users or "raw"."users".
+    - Quotes each identifier part individually.
+    """
+    if _is_qualified(table):
+        return ".".join(_dq(p) for p in table.split("."))
+    if schema:
+        return f"{_dq(schema)}.{_dq(table)}"
+    return _dq(table)
+
+
+# -------------------------------- Pretty echo helpers ---------------------------------
+
+
+def _human_int(n: int) -> str:
+    """Format integers with thin-space grouping (12 345)."""
+    return f"{n:,}".replace(",", " ")
+
+
+def _human_bytes(n: int) -> str:
+    """Coarse byte-size formatting for user hints."""
+    mb_threshold = 1024
+    if n < mb_threshold:
+        return f"{n} B"
+    units = ["KB", "MB", "GB", "TB", "PB"]
+    exp = min(int(math.log(n, 1024)), len(units))
+    val = n / (1024**exp)
+    unit = units[exp - 1] if exp > 0 else "KB"
+    return f"{val:.1f} {unit}"
+
+
+def _echo_seed_line(
+    full_name: str,
+    rows: int,
+    cols: int,
+    engine: str,
+    ms: int,
+    created_schema: bool = False,
+    action: str = "replaced",
+    extra: str | None = None,
+) -> None:
+    """
+    Emit a single pretty seed log line, e.g.:
+      — ✓ raw.users • 12 345x6 • 1.2 MB • 138 ms [duckdb] (+schema)
+    """
+    size_hint: str | None = None
+    with suppress(Exception):
+        # Heuristic: 8 bytes per cell. Good enough as a hint, not exact.
+        size_hint = _human_bytes(rows * max(cols, 1) * 8)
+
+    parts = [
+        f"✓ {full_name}",
+        f"{_human_int(rows)}×{cols}",  # Noqa RUF001
+        *([size_hint] if size_hint else []),
+        f"{ms} ms",
+        f"[{engine}]",
+        *(["(+schema)"] if created_schema else []),
+        *([extra] if extra else []),
+    ]
+    echo("— " + " • ".join(parts))
+
+
+# ------------------------------ Target resolution (CFG) -------------------------------
+
+
+class SeedTarget(NamedTuple):
+    """Resolved seed target (schema, table)."""
+
+    schema: str | None
+    table: str
+
+
+def _engine_name_from_executor(executor: Any) -> str:
+    """Infer a human/CFG-facing engine name from the executor object."""
+    eng = getattr(executor, "engine", None)
+    if eng is not None:
+        name = getattr(getattr(eng, "dialect", None), "name", None)
+        if name:
+            return str(name)
+    if getattr(executor, "con", None) is not None:
+        return "duckdb"
+    return "unknown"
+
+
+def _seed_id(seeds_dir: Path, path: Path) -> str:
+    """
+    Build a unique seed ID from the path relative to `seeds/`, without the extension.
+    Examples:
+      seeds/raw/users.csv      -> "raw/users"
+      seeds/staging/users.parquet -> "staging/users"
+      seeds/users.csv          -> "users"
+    """
+    rel = path.relative_to(seeds_dir)
+    return rel.with_suffix("").as_posix()
+
+
+def _resolve_schema_and_table_by_cfg(
+    seed_id: str,
+    stem: str,
+    schema_cfg: dict | None,
+    executor: Any,
+    default_schema: str | None,
+) -> tuple[str | None, str]:
+    """
+    Resolve (schema, table) using seeds/schema.yml with a clear priority:
+      1) targets[<seed_id>] (recommended; path-based ID e.g. "raw/users")
+      2) targets[<seed_id with dots>] (optional convenience; "raw.users")
+      3) targets[<stem>] (legacy; only safe if the stem is unique)
+      4) default_schema (profile/executor-supplied)
+    Supports:
+      targets:
+        raw/users:
+          schema: raw
+          table: users
+          schema_by_engine:
+            postgres: raw
+            duckdb: main
+    """
+    schema = default_schema
+    table = stem
+    if not schema_cfg:
+        return schema, table
+
+    targets: dict[str, dict] = schema_cfg.get("targets") or {}
+    engine = _engine_name_from_executor(executor)
+
+    entry = targets.get(seed_id)
+    if not entry:
+        entry = targets.get(seed_id.replace("/", "."))  # optional "raw.users" key
+
+    # stem-based only if present (uniqueness checked by caller)
+    if not entry and stem in targets:
+        entry = targets[stem]
+
+    if not entry:
+        return schema, table
+
+    table = entry.get("table", table)
+    by_engine = entry.get("schema_by_engine") or {}
+    schema = by_engine.get(engine, entry.get("schema", schema))
+    return schema, table
+
+
+# ------------------------------ Materialization (engines) ------------------------------
 
 
 def materialize_seed(
     table: str, df: pd.DataFrame, executor: Any, schema: str | None = None
 ) -> None:
     """
-    Engine-agnostic materialization:
-    - DuckDB: register + CREATE OR REPLACE TABLE
-    - Postgres/SA-Engines: pandas.to_sql(..., if_exists='replace', schema=...)
+    Materialize a DataFrame as a database table across engines.
+
+    DuckDB:
+      - Registers a temporary view for the DataFrame and performs
+        CREATE OR REPLACE TABLE <schema>.<table> AS SELECT * FROM <tmp>.
+      - Ensures CREATE SCHEMA IF NOT EXISTS when requested.
+
+    SQLAlchemy engines (e.g., Postgres):
+      - Uses pandas.DataFrame.to_sql(if_exists='replace', schema=schema).
+
+    Raises:
+      RuntimeError if no supported executor connection is detected.
     """
-    # DuckDB (robust detection)
+    # DuckDB path (robust detection)
     con = getattr(executor, "con", None)
     if con is not None:
         try:
             is_duck_con = isinstance(con, _dd.DuckDBPyConnection)
         except Exception:
-            # Fallback: treat as "duckdb-like" when register/execute exist
             is_duck_con = all(hasattr(con, m) for m in ("register", "execute"))
+
         if is_duck_con:
+            full_name = _qualify(table, schema)
+            created_schema = False
+            if schema and not _is_qualified(table):
+                con.execute(f"create schema if not exists {_dq(schema)}")
+                created_schema = True
+
+            t0 = perf_counter()
             tmp = f"_ff_seed_{uuid.uuid4().hex[:8]}"
             con.register(tmp, df)
-            con.execute(f"create or replace table {table} as select * from {tmp}")
             try:
-                con.unregister(tmp)  # duckdb >= 0.8
-            except Exception:
-                con.execute(f"drop view if exists {tmp}")
+                con.execute(f"create or replace table {full_name} as select * from {_dq(tmp)}")
+            finally:
+                try:
+                    con.unregister(tmp)  # duckdb >= 0.8
+                except Exception:
+                    con.execute(f"drop view if exists {_dq(tmp)}")
+            dt_ms = int((perf_counter() - t0) * 1000)
+
+            _echo_seed_line(
+                full_name=full_name,
+                rows=len(df),
+                cols=df.shape[1],
+                engine="duckdb",
+                ms=dt_ms,
+                created_schema=created_schema,
+                action="replaced",
+            )
             return
 
-    # SQLAlchemy-Engine?
+    # SQLAlchemy Engine path
     eng = getattr(executor, "engine", None)
     if eng is not None and "sqlalchemy" in eng.__class__.__module__:
+        t0 = perf_counter()
         df.to_sql(table, eng, if_exists="replace", index=False, schema=schema, method="multi")
+        dt_ms = int((perf_counter() - t0) * 1000)
+        dialect = getattr(getattr(eng, "dialect", None), "name", "sqlalchemy")
+        _echo_seed_line(
+            full_name=_qualify(table, schema),
+            rows=len(df),
+            cols=df.shape[1],
+            engine=dialect,
+            ms=dt_ms,
+            created_schema=False,
+            action="replaced",
+        )
         return
 
-    # Fallback: try feeding executor.execute(sql) with VALUES statements (for small seeds)
-    # (Optional - usually not needed if handled above)
+    # Fallback (not implemented): you could emit VALUES via executor.execute(sql) for tiny seeds.
     raise RuntimeError("No compatible executor connection for seeding found.")
 
 
+# ----------------------------------- Seeding runner -----------------------------------
+
+
 def seed_project(project_dir: Path, executor: Any, default_schema: str | None = None) -> int:
     """
-    Load every file under <project>/seeds/*.{csv,parquet} and write it as a table
-    (file name becomes table name). Returns the number of seeds loaded.
+    Load every seed file under <project>/seeds recursively and materialize it.
+
+    Supports configuration in seeds/schema.yml:
+      - targets:
+          <seed-id>:                 # e.g., "raw/users" (path-based, recommended)
+            schema: <schema-name>    # global target schema
+            table: <table-name>      # optional rename
+            schema_by_engine:        # optional engine overrides
+              postgres: raw
+              duckdb: main
+      - dtypes:
+          <table-key>:
+            column_a: string
+            column_b: int64
+
+    Resolution priority for (schema, table):
+      1) targets[<seed-id>]  (e.g., "raw/users")
+      2) targets[<seed-id with dots>] (e.g., "raw.users")
+      3) targets[<stem>] (*only* if stem is unique)
+      4) executor.schema or default_schema
+
+    Returns:
+      Number of successfully materialized seed tables.
+
+    Raises:
+      ValueError if schema.yml uses a plain stem key while multiple files share that stem.
     """
     seeds_dir = project_dir / "seeds"
     if not seeds_dir.exists():
@@ -85,15 +333,49 @@ def seed_project(project_dir: Path, executor: Any, default_schema: str | None =
     if schema_file.exists():
         schema_cfg = yaml.safe_load(schema_file.read_text(encoding="utf-8"))
 
+    # Collect seed files recursively to allow folder-based schema conventions.
+    paths: list[Path] = [
+        p
+        for p in sorted(seeds_dir.rglob("*"))
+        if p.is_file() and p.suffix.lower() in (".csv", ".parquet", ".pq")
+    ]
+    if not paths:
+        return 0
+
+    # Check for ambiguous stems (same filename in different folders).
+    stem_counts: dict[str, int] = {}
+    for p in paths:
+        stem_counts[p.stem] = stem_counts.get(p.stem, 0) + 1
+
     count = 0
-    for path in sorted(seeds_dir.iterdir()):
-        if path.suffix.lower() not in (".csv", ".parquet", ".pq"):
-            continue
-        table = path.stem  # e.g. seed_users
+    for path in paths:
+        seedid = _seed_id(seeds_dir, path)
+        stem = path.stem
+
+        # Default schema may come from executor or caller.
+        base_schema = getattr(executor, "schema", None) or default_schema
+        schema, table = _resolve_schema_and_table_by_cfg(
+            seedid, stem, schema_cfg, executor, base_schema
+        )
+
+        # If schema.yml uses a bare stem while that stem exists multiple times,
+        # force disambiguation.
+        if (
+            schema_cfg
+            and (schema_cfg.get("targets") or {}).get(stem)
+            and stem_counts.get(stem, 0) > 1
+        ):
+            raise ValueError(
+                f'Seed stem "{stem}" appears multiple times. '
+                f"Please configure using the path-based seed ID "
+                f'(e.g., "{seedid}") in seeds/schema.yml.'
+            )
+
         df = _read_seed_file(path)
+        # Use the resolved *table* key for dtypes (allows rename-aware dtype mapping in cfg).
         df = _apply_schema(df, table, schema_cfg)
-        # Schema only for engines that need it (PG). DuckDB ignores it in materialize_seed.
-        schema = getattr(executor, "schema", None) or default_schema
+
         materialize_seed(table, df, executor, schema=schema)
         count += 1
+
     return count
diff --git a/src/fastflowtransform/settings.py b/src/fastflowtransform/settings.py
index ce11560..c029f65 100644
--- a/src/fastflowtransform/settings.py
+++ b/src/fastflowtransform/settings.py
@@ -122,6 +122,15 @@ class EnvSettings(BaseSettings):
     SF_DATABASE: str | None = None
     SF_SCHEMA: str | None = None
 
+    # --- HTTP / API (optional) ---
+    HTTP_CACHE_DIR: str | None = None  # maps to FF_HTTP_CACHE_DIR
+    HTTP_TTL: int | None = None  # FF_HTTP_TTL
+    HTTP_TIMEOUT: int | None = None  # FF_HTTP_TIMEOUT
+    HTTP_MAX_RETRIES: int | None = None  # FF_HTTP_MAX_RETRIES
+    HTTP_RATE_LIMIT_RPS: float | None = None  # FF_HTTP_RATE_LIMIT_RPS
+    HTTP_OFFLINE: int | None = None  # FF_HTTP_OFFLINE (1/0)
+    HTTP_ALLOWED_DOMAINS: str | None = None  # FF_HTTP_ALLOWED_DOMAINS (csv)
+
 
 def load_project_config(project_dir: Path) -> ProjectConfig:
     cfg_path = project_dir / "project.yml"
@@ -143,128 +152,6 @@ def load_profiles(project_dir: Path) -> dict:
 
 
 # ---------- Resolver ----------
-# def resolve_profile(project_dir: Path, env_name: str, env: EnvSettings) -> Profile:
-#     profiles: dict[str, dict[str, Any]] = load_profiles(project_dir)  # type: ignore[name-defined]
-#     raw: dict[str, Any] = (
-#         profiles.get(env_name)
-#         or profiles.get("default")
-#         or {"engine": "duckdb", "duckdb": {"path": ":memory:"}}
-#     )
-
-#     # --------------------------
-#     # 1) Apply ENV overrides before parsing
-#     # --------------------------
-
-#     # Engine-Override
-#     if env.ENGINE:
-#         raw["engine"] = env.ENGINE
-
-#     eng = str(raw.get("engine", "duckdb")).lower()
-
-#     # DuckDB
-#     if eng == "duckdb":
-#         raw.setdefault("duckdb", {})
-#         if env.DUCKDB_PATH is not None:
-#             raw["duckdb"]["path"] = env.DUCKDB_PATH
-
-#     # Postgres
-#     elif eng == "postgres":
-#         raw.setdefault("postgres", {})
-#         if env.PG_DSN:
-#             raw["postgres"]["dsn"] = env.PG_DSN
-#         if env.PG_SCHEMA:
-#             raw["postgres"]["db_schema"] = env.PG_SCHEMA
-
-#     # BigQuery (pandas or BigFrames; flag in config)
-#     elif eng == "bigquery":
-#         raw.setdefault("bigquery", {})
-#         if env.BQ_PROJECT is not None:
-#             raw["bigquery"]["project"] = env.BQ_PROJECT
-#         if env.BQ_DATASET:
-#             raw["bigquery"]["dataset"] = env.BQ_DATASET
-#         if env.BQ_LOCATION is not None:
-#             raw["bigquery"]["location"] = env.BQ_LOCATION
-#         # optional ENV flag for BigFrames
-#         uf = os.getenv("FF_BQ_USE_BIGFRAMES")
-#         if uf is not None:
-#             raw["bigquery"]["use_bigframes"] = uf.lower() in ("1", "true", "yes", "on")
-
-#     # Databricks Spark (local or via Connect)
-#     elif eng == "databricks_spark":
-#         raw.setdefault("databricks_spark", {})
-#         if env.DBR_MASTER is not None:
-#             raw["databricks_spark"]["master"] = env.DBR_MASTER
-#         if env.DBR_APPNAME is not None:
-#             raw["databricks_spark"]["app_name"] = env.DBR_APPNAME
-#         # optionally set additional fields (connect params) via env here
-
-#     # Snowflake Snowpark
-#     elif eng == "snowflake_snowpark":
-#         raw.setdefault("snowflake_snowpark", {})
-#         # Important: field name is consistently "schema" (not "db_schema")
-#         if env.SF_ACCOUNT:
-#             raw["snowflake_snowpark"]["account"] = env.SF_ACCOUNT
-#         if env.SF_USER:
-#             raw["snowflake_snowpark"]["user"] = env.SF_USER
-#         if env.SF_PASSWORD:
-#             raw["snowflake_snowpark"]["password"] = env.SF_PASSWORD
-#         if env.SF_WAREHOUSE:
-#             raw["snowflake_snowpark"]["warehouse"] = env.SF_WAREHOUSE
-#         if env.SF_DATABASE:
-#             raw["snowflake_snowpark"]["database"] = env.SF_DATABASE
-#         if env.SF_SCHEMA:
-#             raw["snowflake_snowpark"]["schema"] = env.SF_SCHEMA
-#         if env.SF_ROLE is not None:
-#             raw["snowflake_snowpark"]["role"] = env.SF_ROLE
-
-#     # --------------------------
-#     # 2) Parse via discriminated union
-#     # --------------------------
-#     prof: Profile = TypeAdapter(Profile).validate_python(raw)
-
-#     # --------------------------
-#     # 3) Sanity checks per engine
-#     # --------------------------
-#     if prof.engine == "postgres":
-#         if not prof.postgres.dsn:
-#             raise ProfileConfigError(
-#                 "Postgres profile missing DSN. "
-#                 + "Hint: set profiles.yml → postgres.dsn or env FF_PG_DSN."
-#             )
-#         if prof.postgres.db_schema == "":
-#             raise ProfileConfigError(
-#                 "Postgres profile has empty schema. "
-#                 + "Hint: set profiles.yml → postgres.db_schema or env FF_PG_SCHEMA."
-#             )
-
-#     elif prof.engine == "bigquery":
-#         if not prof.bigquery.dataset:
-#             raise ProfileConfigError(
-#                 "BigQuery profile missing dataset. "
-#                 + "Hint: set profiles.yml → bigquery.dataset or env FF_BQ_DATASET."
-#             )
-#         # project can come via ADC → no hard failure, only optional hint
-
-#     elif prof.engine == "snowflake_snowpark":
-#         sf = prof.snowflake_snowpark
-#         missing = [
-#             k
-#             for k in ("account", "user", "password", "warehouse", "database", "schema")
-#             if not getattr(sf, k)
-#         ]
-#         if missing:
-#             miss = ", ".join(missing)
-#             raise ProfileConfigError(
-#                 f"Snowflake profile missing: {miss}. "
-#                 + "Hint: set profiles.yml → snowflake_snowpark.* or env FF_SF_*."
-#             )
-
-#     # databricks_spark: usually fine (local[*]); additional checks optional
-
-#     return prof
-
-
-# ---------- Resolver (schlank) ----------
 def resolve_profile(project_dir: Path, env_name: str, env: EnvSettings) -> Profile:
     profiles: dict[str, dict[str, Any]] = load_profiles(project_dir)
     raw: dict[str, Any] = (
diff --git a/src/fastflowtransform/test_registry.py b/src/fastflowtransform/test_registry.py
new file mode 100644
index 0000000..3997314
--- /dev/null
+++ b/src/fastflowtransform/test_registry.py
@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from fastflowtransform import testing
+
+
+class Runner(Protocol):
+    """Callable signature for a generic test runner.
+
+    Returns:
+        ok: Whether the test passed.
+        message: Optional human-friendly message (usually set on failure).
+        example_sql: Optional example SQL (shown in summary on failure).
+    """
+
+    def __call__(
+        self, con: Any, table: str, column: str | None, params: dict[str, Any]
+    ) -> tuple[bool, str | None, str | None]: ...
+
+
+def _sql_list(values: list[Any]) -> str:
+    """Render a simple SQL literal list, portable enough for DuckDB/Postgres/BigQuery."""
+
+    def lit(v: Any) -> str:
+        if v is None:
+            return "NULL"
+        if isinstance(v, (int, float)):
+            return str(v)
+        s = str(v).replace("'", "''")
+        return f"'{s}'"
+
+    return ", ".join(lit(v) for v in (values or []))
+
+
+def run_not_null(
+    con: Any, table: str, column: str | None, params: dict[str, Any]
+) -> tuple[bool, str | None, str | None]:
+    where = params.get("where")
+    example = f"select count(*) from {table} where {column} is null" + (
+        f" and ({where})" if where else ""
+    )
+    if column is None:
+        # Column is required for not_null
+        return False, "missing required parameter: column", example
+    col = column
+    try:
+        testing.not_null(con, table, col, where=where)
+        return True, None, example
+    except testing.TestFailure as e:
+        return False, str(e), example
+
+
+def run_unique(
+    con: Any, table: str, column: str | None, params: dict[str, Any]
+) -> tuple[bool, str | None, str | None]:
+    where = params.get("where")
+    example = (
+        f"select {column} as key, count(*) c from {table}"
+        + (f" where ({where})" if where else "")
+        + " group by 1 having count(*) > 1 limit 5"
+    )
+    if column is None:
+        return False, "missing required parameter: column", example
+    col = column
+    try:
+        testing.unique(con, table, col, where=where)
+        return True, None, example
+    except testing.TestFailure as e:
+        return False, str(e), example
+
+
+def run_accepted_values(
+    con: Any, table: str, column: str | None, params: dict[str, Any]
+) -> tuple[bool, str | None, str | None]:
+    values = params.get("values") or []
+    where = params.get("where")
+    in_list = _sql_list(values)
+    example = (
+        f"select distinct {column} from {table} "
+        + f"where {column} is not null and {column} not in ({in_list})"
+        + (f" and ({where})" if where else "")
+        + " limit 5"
+    )
+    if column is None:
+        return False, "missing required parameter: column", example
+    col = column
+    try:
+        testing.accepted_values(con, table, col, values=values, where=where)
+        return True, None, example
+    except testing.TestFailure as e:
+        return False, str(e), example
+
+
+# Public registry (extensible).
+TESTS: dict[str, Runner] = {
+    "not_null": run_not_null,
+    "unique": run_unique,
+    "accepted_values": run_accepted_values,  # NEW
+    # "relationships": run_relationships,    # (later)
+}
diff --git a/src/fastflowtransform/testing.py b/src/fastflowtransform/testing.py
index 6e8e234..bce36fc 100644
--- a/src/fastflowtransform/testing.py
+++ b/src/fastflowtransform/testing.py
@@ -1,8 +1,6 @@
 # src/fastflowtransform/testing.py
 from __future__ import annotations
 
-import logging
-import os
 from collections.abc import Iterable, Sequence
 from typing import Any, cast
 
@@ -10,15 +8,7 @@
 from sqlalchemy.engine import Connection as _SAConn
 from sqlalchemy.sql.elements import ClauseElement
 
-# ===== Debug toggle =====================================================
-
-
-def _dprint(*a):
-    if logging.getLogger("fastflowtransform.sql").isEnabledFor(logging.DEBUG) or (
-        os.getenv("FFT_SQL_DEBUG") == "1"
-    ):
-        print("[DQ]", *a)
-
+from fastflowtransform.logging import dprint
 
 # ===== Execution helpers (consistent for DuckDB / Postgres / BigQuery) ==
 
@@ -36,7 +26,7 @@ def _exec(con: Any, sql: Any) -> Any:
     """
     # 1) Direct delegation to existing con.execute (e.g. DuckDB, our PG/BQ shims)
     if hasattr(con, "execute"):
-        _dprint("con.execute <-", _pretty_sql(sql))
+        dprint("con.execute <-", _pretty_sql(sql))
         try:
             if isinstance(con, _SAConn) or "sqlalchemy" in type(con).__module__:
                 sql_tuple_len = 2
@@ -65,13 +55,13 @@ def _exec_one(c: Any, stmt: Any) -> Any:
             and isinstance(stmt[0], str)
             and isinstance(stmt[1], dict)
         ):
-            _dprint("run (sql, params):", stmt[0], stmt[1])
+            dprint("run (sql, params):", stmt[0], stmt[1])
             return c.execute(text(stmt[0]), stmt[1])
         if isinstance(stmt, ClauseElement):
-            _dprint("run ClauseElement")
+            dprint("run ClauseElement")
             return c.execute(stmt)
         if isinstance(stmt, str):
-            _dprint("run sql:", stmt)
+            dprint("run sql:", stmt)
             return c.execute(text(stmt))
         # Sequences (recursive)
         if isinstance(stmt, Iterable) and not isinstance(stmt, (bytes, bytearray, str)):
@@ -123,67 +113,106 @@ def _pretty_sql(sql: Any) -> str:
     return repr(sql)
 
 
+def _sql_list(values: list) -> str:
+    def lit(v):
+        if v is None:
+            return "NULL"
+        if isinstance(v, (int, float)):
+            return str(v)
+        s = str(v).replace("'", "''")
+        return f"'{s}'"
+
+    return ", ".join(lit(v) for v in values)
+
+
+def accepted_values(
+    con: Any, table: str, column: str, *, values: list, where: str | None = None
+) -> bool:
+    """
+    Checks that all non-NULL values of table.column are in the set 'values'.
+    """
+    in_list = _sql_list(values or [])
+    sql = f"select count(*) from {table} where {column} is not null and {column} not in ({in_list})"
+    if where:
+        sql += f" and ({where})"
+    n = _scalar(con, sql)
+    if int(n or 0) > 0:
+        # Beispielwerte zeigen
+        sample_sql = (
+            f"select distinct {column} "
+            f"from {table} "
+            f"where {column} is not null and {column} not in ({in_list})"
+        )
+        if where:
+            sample_sql += f" and ({where})"
+        sample_sql += " limit 5"
+        rows = [r[0] for r in _exec(con, sample_sql).fetchall()]
+        raise TestFailure(f"{table}.{column} has {n} value(s) outside accepted set; e.g. {rows}")
+    return True
+
+
 # ===== Tests ==============================================================
 
 
 class TestFailure(Exception):
-    """Error class for data-quality checks."""
+    """Raised when a data-quality check fails."""
 
+    # Prevent pytest from collecting this as a test when imported into a test module.
+    __test__ = False
     pass
 
 
 def _wrap_db_error(
     check: str, table: str, column: str | None, sql: str, err: Exception
 ) -> TestFailure:
-    msg = [f"[{check}] Fehler in {table}{('.' + column) if column else ''}"]
-    msg.append(f"DB-Fehler: {type(err).__name__}: {err}")
+    msg = [f"[{check}] Error in {table}{('.' + column) if column else ''}"]
+    msg.append(f"DB-Error: {type(err).__name__}: {err}")
     # Common Postgres/SQLAlchemy hints
     txt = str(err).lower()
     if "undefinedcolumn" in txt and "having" in sql.lower():
-        msg.append(
-            "Hinweis: Postgres erlaubt Alias-Nutzung im HAVING nicht. "
-            "Lösung: Alias außerhalb verwenden (Subquery) oder die Bedingung "
-            "in WHERE der äußeren Abfrage prüfen."
-        )
+        msg.append("Note: Postgres does not permit alias usage in HAVING statement.")
     if "f405" in txt or "textual sql expression" in txt:
-        msg.append("Hinweis: SQLAlchemy 2.0 verlangt text('...') für rohe SQL-Strings.")
+        msg.append("Note: SQLAlchemy 2.0 requires text('...') for raw SQL stings.")
     msg.append("SQL:\n" + sql.strip())
     return TestFailure("\n".join(msg))
 
 
-def not_null(con: Any, table: str, column: str) -> None:
+def not_null(con: Any, table: str, column: str, where: str | None = None) -> None:
+    """Fails if any non-filtered row has NULL in `column`."""
     sql = f"select count(*) from {table} where {column} is null"
+    if where:
+        sql += f" and ({where})"
     try:
         c = _scalar(con, sql)
     except Exception as e:
         raise _wrap_db_error("not_null", table, column, sql, e) from e
     c = _scalar(con, sql)
-    _dprint("not_null:", sql, "=>", c)
+    dprint("not_null:", sql, "=>", c)
     if c and c != 0:
-        _fail("not_null", table, column, sql, f"hat {c} NULL-Werte")
+        _fail("not_null", table, column, sql, f"has {c} NULL-values")
 
 
-def unique(con: Any, table: str, column: str) -> None:
+def unique(con: Any, table: str, column: str, where: str | None = None) -> None:
+    """Fails if any duplicate appears in `column` within the (optionally) filtered set."""
     sql = (
-        "select count(*) from ("
-        f"  select {column}, count(*) as c"
-        f"  from {table}"
-        "  group by 1"
-        ") t where c > 1"
+        "select count(*) from (select {col} as v, "
+        "count(*) as c from {tbl}{w} group by 1 having count(*) > 1) as q"
     )
+    w = f" where ({where})" if where else ""
+    sql = sql.format(col=column, tbl=table, w=w)
     try:
         c = _scalar(con, sql)
     except Exception as e:
         raise _wrap_db_error("unique", table, column, sql, e) from e
-    _dprint("unique:", sql, "=>", c)
+    dprint("unique:", sql, "=>", c)
     if c and c != 0:
-        _fail("unique", table, column, sql, f"enthält {c} Duplikate")
+        _fail("unique", table, column, sql, f"contains {c} duplicates")
 
 
 def greater_equal(con: Any, table: str, column: str, threshold: float = 0.0) -> None:
     sql = f"select count(*) from {table} where {column} < {threshold}"
     c = _scalar(con, sql)
-    _dprint("greater_equal:", sql, "=>", c)
+    dprint("greater_equal:", sql, "=>", c)
     if c and c != 0:
         raise TestFailure(f"{table}.{column} has {c} values < {threshold}")
 
@@ -191,7 +220,7 @@ def greater_equal(con: Any, table: str, column: str, threshold: float = 0.0) ->
 def non_negative_sum(con: Any, table: str, column: str) -> None:
     sql = f"select coalesce(sum({column}),0) from {table}"
     s = _scalar(con, sql)
-    _dprint("non_negative_sum:", sql, "=>", s)
+    dprint("non_negative_sum:", sql, "=>", s)
     if s is not None and s < 0:
         raise TestFailure(f"sum({table}.{column}) is negative: {s}")
 
@@ -199,7 +228,7 @@ def non_negative_sum(con: Any, table: str, column: str) -> None:
 def row_count_between(con: Any, table: str, min_rows: int = 1, max_rows: int | None = None) -> None:
     sql = f"select count(*) from {table}"
     c = _scalar(con, sql)
-    _dprint("row_count_between:", sql, "=>", c)
+    dprint("row_count_between:", sql, "=>", c)
     if c is None or c < min_rows:
         raise TestFailure(f"{table} has too few rows: {c} < {min_rows}")
     if max_rows is not None and c > max_rows:
@@ -209,11 +238,11 @@ def row_count_between(con: Any, table: str, min_rows: int = 1, max_rows: int | N
 def freshness(con: Any, table: str, ts_col: str, max_delay_minutes: int) -> None:
     # Straightforward for DuckDB/PG; BQ would need a TIMESTAMPDIFF variant.
     sql = f"select date_part('epoch', now() - max({ts_col})) / 60.0 as delay_min from {table}"
-    # Note: DuckDB has different date_diff signatures; for DuckDB-only you could use:
+    # Note: DuckDB has different date_diff signatures; for DuckDB-only might use:
     # sql_duckdb =
     # f\"\"\"select date_diff('minute', max({ts_col}), now()) as delay_min from {table}\"\"\"
     delay = _scalar(con, sql)
-    _dprint("freshness:", sql, "=>", delay)
+    dprint("freshness:", sql, "=>", delay)
     if delay is None or delay > max_delay_minutes:
         raise TestFailure(
             f"freshness of {table}.{ts_col} too old: {delay} min > {max_delay_minutes} min"
@@ -226,7 +255,7 @@ def freshness(con: Any, table: str, ts_col: str, max_delay_minutes: int) -> None
 def _scalar_where(con: Any, table: str, expr: str, where: str | None = None) -> Any:
     """Return the first scalar from `SELECT {expr} FROM {table} [WHERE ...]`."""
     sql = f"select {expr} from {table}" + (f" where {where}" if where else "")
-    _dprint("reconcile:", sql)
+    dprint("reconcile:", sql)
     return _scalar(con, sql)
 
 
@@ -316,6 +345,6 @@ def reconcile_coverage(
       where t.k is null
     """
     missing = _scalar(con, sql)
-    _dprint("reconcile_coverage:", sql, "=>", missing)
+    dprint("reconcile_coverage:", sql, "=>", missing)
     if missing and missing != 0:
         raise TestFailure(f"Coverage failed: {missing} source keys missing in target")
diff --git a/tests/api/test_http_cache_modes.py b/tests/api/test_http_cache_modes.py
new file mode 100644
index 0000000..fd19f63
--- /dev/null
+++ b/tests/api/test_http_cache_modes.py
@@ -0,0 +1,66 @@
+import importlib
+import json
+from pathlib import Path
+
+import pytest
+
+from fastflowtransform.api import http
+
+
+def _seed_cache(http_mod, cache_dir: Path, url: str, params: dict | None, body_obj) -> None:
+    key = http_mod._cache_key("GET", url, params, headers={})
+    body = json.dumps(body_obj, ensure_ascii=False).encode("utf-8")
+    http_mod._write_cache(key, 200, {}, body, url)
+
+
+def test_http_cache_mode_off_disables_cache(monkeypatch, tmp_path):
+    """
+    Mode=off: the cache is ignored; in offline mode this raises because
+    the network is blocked and the cache is unavailable.
+    """
+    monkeypatch.setenv("FF_HTTP_OFFLINE", "1")
+    monkeypatch.setenv("FF_HTTP_CACHE_DIR", str(tmp_path))
+    monkeypatch.setenv("FF_HTTP_CACHE_MODE", "off")
+
+    importlib.reload(http)
+
+    # Populate the cache anyway; it must not be read
+    url = "https://api.example.com/ping"
+    params = None
+    _seed_cache(http, Path(tmp_path), url, params, {"ok": True})
+
+    with pytest.raises(RuntimeError) as e:
+        http.get_json(url, params=params)
+    assert "offline" in str(e.value).lower() and "cache miss" in str(e.value).lower()
+
+
+def test_http_cache_mode_ro_does_not_write(monkeypatch, tmp_path):
+    """
+    Mode=ro: reads are allowed, writes are forbidden.
+    Patch the actual request and ensure no cache file is created.
+    """
+    monkeypatch.setenv("FF_HTTP_OFFLINE", "0")
+    monkeypatch.setenv("FF_HTTP_CACHE_DIR", str(tmp_path))
+    monkeypatch.setenv("FF_HTTP_CACHE_MODE", "ro")
+
+    importlib.reload(http)
+
+    # No cache present; the request is patched
+    url = "https://api.example.com/echo"
+    params = {"q": "x"}
+
+    def fake_http_request(method, u, *, params=None, headers=None, timeout=None):
+        body = json.dumps({"data": [{"id": 1}]}, ensure_ascii=False).encode("utf-8")
+        return 200, {}, body
+
+    # Monkeypatch the internal request helper
+    monkeypatch.setattr(http, "_http_request", fake_http_request)
+
+    # Before the call: no files present
+    assert not any(Path(tmp_path).iterdir())
+
+    out = http.get_json(url, params=params)
+    assert out == {"data": [{"id": 1}]}
+
+    # After the call: still no files (read-only mode blocks writes)
+    assert not any(Path(tmp_path).iterdir())
diff --git a/tests/api/test_http_offline_cache.py b/tests/api/test_http_offline_cache.py
new file mode 100644
index 0000000..a8dcd81
--- /dev/null
+++ b/tests/api/test_http_offline_cache.py
@@ -0,0 +1,41 @@
+import importlib
+import json
+from pathlib import Path
+
+from fastflowtransform.api import context as ctx, http
+
+
+def _seed_cache(http_mod, cache_dir: Path, url: str, params: dict | None, body_obj) -> None:
+    """
+    Create a valid cache entry for the (GET, url, params) combination.
+    """
+    key = http_mod._cache_key("GET", url, params, headers={})
+    body = json.dumps(body_obj, ensure_ascii=False).encode("utf-8")
+    http_mod._write_cache(key, 200, {}, body, url)
+
+
+def test_get_json_offline_cache_hit_records_stats(monkeypatch, tmp_path):
+    # Set ENV variables and reload the module so it picks them up
+    monkeypatch.setenv("FF_HTTP_OFFLINE", "1")
+    monkeypatch.setenv("FF_HTTP_CACHE_DIR", str(tmp_path))
+    # Cache mode does not matter here; rw is the default
+    importlib.reload(http)
+
+    url = "https://api.example.com/users"
+    params = {"page": 1}
+    payload = {"data": [{"id": 1, "email": "a@example.com"}]}
+    _seed_cache(http, Path(tmp_path), url, params, payload)
+
+    # Initialize telemetry context for the node (same as the executor does)
+    ctx.reset_for_node("unit_node")
+
+    out = http.get_json(url, params=params)
+    assert out == payload  # exactly the payload stored in the cache
+
+    snap = ctx.snapshot()
+    # Exactly one request, one cache hit, offline true, bytes greater than zero
+    assert snap["requests"] == 1
+    assert snap["cache_hits"] == 1
+    assert snap["used_offline"] is True
+    assert snap["bytes"] > 0
+    assert isinstance(snap["keys"], list) and len(snap["keys"]) == 1
diff --git a/tests/api/test_http_pagination_df.py b/tests/api/test_http_pagination_df.py
new file mode 100644
index 0000000..aeb5ee1
--- /dev/null
+++ b/tests/api/test_http_pagination_df.py
@@ -0,0 +1,54 @@
+import importlib
+import json
+from pathlib import Path
+
+import pandas as pd
+
+from fastflowtransform.api import context as ctx, http
+
+
+def _seed_cache(http_mod, cache_dir: Path, url: str, params: dict | None, body_obj) -> None:
+    key = http_mod._cache_key("GET", url, params, headers={})
+    body = json.dumps(body_obj, ensure_ascii=False).encode("utf-8")
+    http_mod._write_cache(key, 200, {}, body, url)
+
+
+def test_get_df_pagination_concatenates(monkeypatch, tmp_path):
+    """
+    get_df with a paginator joins two offline pages correctly.
+    """
+    monkeypatch.setenv("FF_HTTP_OFFLINE", "1")
+    monkeypatch.setenv("FF_HTTP_CACHE_DIR", str(tmp_path))
+    # Mode rw (default) can read; offline plus cache hit makes the choice irrelevant
+    importlib.reload(http)
+
+    url1 = "https://api.example.com/users?page=1"
+    url2 = "https://api.example.com/users?page=2"
+
+    page1 = {"data": [{"id": 1, "email": "a@x"}, {"id": 2, "email": "b@x"}], "next": url2}
+    page2 = {"data": [{"id": 3, "email": "c@x"}], "next": None}
+
+    # Seed the cache the same way get_json/get_df access it (params
+    # usually None when the query string is baked in)
+    _seed_cache(http, Path(tmp_path), url1, None, page1)
+    _seed_cache(http, Path(tmp_path), url2, None, page2)
+
+    ctx.reset_for_node("unit_pager")
+
+    def paginator(u: str, p: dict | None, js: dict):
+        nxt = js.get("next")
+        return {"next_request": {"url": nxt}} if nxt else None
+
+    df = http.get_df(url1, paginator=paginator, record_path=["data"])
+    assert isinstance(df, pd.DataFrame)
+    # Expected: three rows, IDs 1..3
+    expected_df_len = 3
+    assert len(df) == expected_df_len
+    assert set(df["id"].tolist()) == {1, 2, 3}
+
+    snap = ctx.snapshot()
+    # Two pages -> 2 requests, 2 hits
+    request_count = 2
+    cache_hit_count = 2
+    assert snap["requests"] == request_count
+    assert snap["cache_hits"] == cache_hit_count
diff --git a/tests/artifacts/test_catalog_duckdb.py b/tests/artifacts/test_catalog_duckdb.py
new file mode 100644
index 0000000..b12ac59
--- /dev/null
+++ b/tests/artifacts/test_catalog_duckdb.py
@@ -0,0 +1,24 @@
+import json
+from pathlib import Path
+
+from fastflowtransform.artifacts import write_catalog
+from fastflowtransform.core import REGISTRY
+from fastflowtransform.executors.duckdb_exec import DuckExecutor
+
+
+def test_catalog_duckdb(tmp_path: Path):
+    (tmp_path / "models").mkdir(parents=True)
+    (tmp_path / "models" / "t.ff.sql").write_text(
+        "create or replace table t as select 1::int as id, 'x'::varchar as email", encoding="utf-8"
+    )
+    (tmp_path / "sources.yml").write_text("{}", encoding="utf-8")
+    REGISTRY.load_project(tmp_path)
+    env = REGISTRY.get_env()
+    ex = DuckExecutor(":memory:")
+    ex.run_sql(REGISTRY.get_node("t.ff"), env)
+
+    p = write_catalog(tmp_path, ex)
+    data = json.loads(p.read_text(encoding="utf-8"))
+    assert "relations" in data
+    cols = {c["name"] for c in data["relations"]["t"]["columns"]}
+    assert {"id", "email"}.issubset(cols)
diff --git a/tests/artifacts/test_manifest.py b/tests/artifacts/test_manifest.py
new file mode 100644
index 0000000..34a397b
--- /dev/null
+++ b/tests/artifacts/test_manifest.py
@@ -0,0 +1,21 @@
+import json
+from pathlib import Path
+
+from fastflowtransform.artifacts import write_manifest
+from fastflowtransform.core import REGISTRY
+
+
+def test_manifest_minimal(tmp_path: Path):
+    (tmp_path / "models").mkdir(parents=True)
+    (tmp_path / "models" / "m.ff.sql").write_text("select 1 as x", encoding="utf-8")
+    (tmp_path / "sources.yml").write_text("{}", encoding="utf-8")
+
+    REGISTRY.load_project(tmp_path)
+    p = write_manifest(tmp_path)
+    data = json.loads(p.read_text(encoding="utf-8"))
+    assert "nodes" in data and "manifest.json" in p.name
+    n = data["nodes"]["m.ff"]
+    assert n["relation"] == "m"
+    assert n["path"] == "models/m.ff.sql"
+    # sorted & deterministic keys (spot check)
+    assert list(sorted(data["nodes"].keys())) == list(data["nodes"].keys())
diff --git a/tests/artifacts/test_run_result.py b/tests/artifacts/test_run_result.py
new file mode 100644
index 0000000..becc04e
--- /dev/null
+++ b/tests/artifacts/test_run_result.py
@@ -0,0 +1,30 @@
+import json
+from pathlib import Path
+
+from fastflowtransform.artifacts import RunNodeResult, write_run_results
+
+
+def test_run_results_written(tmp_path: Path):
+    started = "2025-01-01T00:00:00+00:00"
+    finished = "2025-01-01T00:01:00+00:00"
+    results = [
+        RunNodeResult(
+            name="b.ff",
+            status="success",
+            started_at=started,
+            finished_at=finished,
+            duration_ms=1000,
+        ),
+        RunNodeResult(
+            name="a.ff",
+            status="skipped",
+            started_at=started,
+            finished_at=finished,
+            duration_ms=0,
+            message=None,
+        ),
+    ]
+    p = write_run_results(tmp_path, started_at=started, finished_at=finished, node_results=results)
+    data = json.loads(p.read_text(encoding="utf-8"))
+    names = [r["name"] for r in data["results"]]
+    assert names == ["a.ff", "b.ff"]  # sorted by name
diff --git a/tests/cli/test_summary_params_and_sql.py b/tests/cli/test_summary_params_and_sql.py
new file mode 100644
index 0000000..1ffe869
--- /dev/null
+++ b/tests/cli/test_summary_params_and_sql.py
@@ -0,0 +1,42 @@
+import io
+import sys
+
+from fastflowtransform.cli.test_cmd import DQResult, _print_summary
+
+
+def test_prints_params_and_example_sql():
+    buf = io.StringIO()
+    old = sys.stdout
+    sys.stdout = buf
+    try:
+        _print_summary(
+            [
+                DQResult(
+                    kind="accepted_values",
+                    table="users",
+                    column="email",
+                    ok=False,
+                    msg="x",
+                    ms=4,
+                    severity="error",
+                    param_str="(values=['a','b'], where=flag=1)",
+                    example_sql=(
+                        "select distinct email from users where email not in ('a','b') limit 5"
+                    ),
+                ),
+                DQResult(
+                    kind="not_null",
+                    table="users",
+                    column="id",
+                    ok=True,
+                    msg=None,
+                    ms=1,
+                    severity="error",
+                ),
+            ]
+        )
+    finally:
+        sys.stdout = old
+    out = buf.getvalue()
+    assert "(values=" in out and "where=" in out
+    assert "e.g. SQL:" in out
diff --git a/tests/cli/test_test_cmd_output_marks.py b/tests/cli/test_test_cmd_output_marks.py
new file mode 100644
index 0000000..9b4a830
--- /dev/null
+++ b/tests/cli/test_test_cmd_output_marks.py
@@ -0,0 +1,35 @@
+import io
+import sys
+
+from fastflowtransform.cli.test_cmd import DQResult, _print_summary
+
+
+def test_output_marks_and_totals():
+    results = [
+        DQResult(
+            kind="not_null", table="t", column="c1", ok=True, msg=None, ms=3, severity="error"
+        ),
+        DQResult(kind="unique", table="t", column="c2", ok=False, msg="dup", ms=2, severity="warn"),
+        DQResult(
+            kind="greater_equal",
+            table="t",
+            column="c3",
+            ok=False,
+            msg="bad",
+            ms=1,
+            severity="error",
+        ),
+    ]
+    buf = io.StringIO()
+    old_stdout = sys.stdout
+    sys.stdout = buf
+    try:
+        _print_summary(results)
+    finally:
+        sys.stdout = old_stdout
+    out = buf.getvalue()
+    assert "✅ not_null" in out
+    assert "❕ unique" in out  # warn fail
+    assert "❌ greater_equal" in out  # error fail
+    assert "! warned:" in out
+    assert "✗ failed:" in out
diff --git a/tests/cli/test_test_cmd_schema_merge.py b/tests/cli/test_test_cmd_schema_merge.py
new file mode 100644
index 0000000..64c57bc
--- /dev/null
+++ b/tests/cli/test_test_cmd_schema_merge.py
@@ -0,0 +1,70 @@
+from pathlib import Path
+
+from fastflowtransform.cli.test_cmd import _apply_legacy_tag_filter, _run_dq_tests
+from fastflowtransform.core import REGISTRY
+from fastflowtransform.executors.duckdb_exec import DuckExecutor
+from fastflowtransform.schema_loader import load_schema_tests
+
+
+def test_merge_project_yaml_and_schema_yaml(tmp_path: Path):
+    # Projekt + Modell
+    (tmp_path / "models").mkdir(parents=True)
+    (tmp_path / "sources.yml").write_text("{}", encoding="utf-8")
+    (tmp_path / "project.yml").write_text(
+        """
+tests:
+  - type: not_null
+    table: users
+    column: id
+    tags: [legacy]
+""",
+        encoding="utf-8",
+    )
+    (tmp_path / "models" / "users.ff.sql").write_text(
+        "create or replace table users as select 1 as id, 'x@example.com' as email",
+        encoding="utf-8",
+    )
+    (tmp_path / "models" / "users.yml").write_text(
+        """
+version: 2
+models:
+  - name: users.ff
+    tags: [schema]
+    columns:
+      - name: email
+        tests:
+          - accepted_values:
+              values: ["x@example.com"]
+              severity: warn
+""",
+        encoding="utf-8",
+    )
+
+    # Build
+    REGISTRY.load_project(tmp_path)
+    env = REGISTRY.get_env()
+    ex = DuckExecutor(":memory:")
+    ex.run_sql(REGISTRY.get_node("users.ff"), env)
+
+    # Sammeln
+    legacy = [
+        {
+            "type": "not_null",
+            "table": "users",
+            "column": "id",
+            "severity": "error",
+            "tags": ["legacy"],
+        }
+    ]
+    schema_specs = load_schema_tests(tmp_path)
+
+    # Legacy-Tagfilter (nur 'legacy')
+    legacy_only = _apply_legacy_tag_filter(legacy + schema_specs, ["legacy"], legacy_token=True)
+    res_legacy = _run_dq_tests(ex.con, legacy_only)
+    assert all(r.ok for r in res_legacy)
+
+    # Schema-Tagfilter (nur 'schema')
+    schema_only = _apply_legacy_tag_filter(legacy + schema_specs, ["schema"], legacy_token=True)
+    res_schema = _run_dq_tests(ex.con, schema_only)
+    # accepted_values mit passendem Wert -> ok (WARN-Fail wäre egal, hier aber grün)
+    assert all(r.ok or r.severity == "warn" for r in res_schema)
diff --git a/tests/common/fixtures.py b/tests/common/fixtures.py
index 08cb734..7d596c5 100644
--- a/tests/common/fixtures.py
+++ b/tests/common/fixtures.py
@@ -1,14 +1,41 @@
+# tests/common/fixtures.py
 import os
 from contextlib import suppress
 from pathlib import Path
 
 import psycopg
 import pytest
+from jinja2 import Environment, FileSystemLoader, select_autoescape
 from psycopg import sql
 
+from fastflowtransform.core import REGISTRY
 from tests.common.utils import ROOT, run
 
 
+# ---- Jinja Env ----
+@pytest.fixture(scope="session")
+def jinja_env():
+    """
+    Minimal Jinja2 rnvironment for rendering-tests.
+    """
+    env = Environment(
+        loader=FileSystemLoader(["."]),
+        autoescape=select_autoescape([]),
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+
+    env.globals.setdefault("is_incremental", lambda: False)
+    env.globals.setdefault("this", None)
+    env.globals.setdefault(
+        "var",
+        lambda k, default=None: (
+            (getattr(REGISTRY, "vars", {}) or {}).get(k, default) if REGISTRY else default
+        ),
+    )
+    return env
+
+
 # ---- DuckDB ----
 @pytest.fixture(scope="session")
 def duckdb_project():
diff --git a/tests/executors/duckdb/test_ephemeral_inlining.py b/tests/executors/duckdb/test_ephemeral_inlining.py
index 9671c15..b91f33d 100644
--- a/tests/executors/duckdb/test_ephemeral_inlining.py
+++ b/tests/executors/duckdb/test_ephemeral_inlining.py
@@ -30,7 +30,18 @@ def test_ephemeral_inlining_end_to_end(tmp_path: Path):
     # sources.yml
     _w(
         proj / "sources.yml",
-        "crm:\n  users:\n    identifier: seed_users\ncore:\n  base:\n    identifier: base\n",
+        """version: 2
+
+sources:
+  - name: crm
+    tables:
+      - name: users
+        identifier: seed_users
+  - name: core
+    tables:
+      - name: base
+        identifier: base
+""",
     )
 
     # models
diff --git a/tests/integration/test_artifacts_e2e.py b/tests/integration/test_artifacts_e2e.py
new file mode 100644
index 0000000..b5dde23
--- /dev/null
+++ b/tests/integration/test_artifacts_e2e.py
@@ -0,0 +1,52 @@
+import json
+from pathlib import Path
+
+from fastflowtransform.artifacts import (
+    RunNodeResult,
+    write_catalog,
+    write_manifest,
+    write_run_results,
+)
+from fastflowtransform.core import REGISTRY
+from fastflowtransform.executors.duckdb_exec import DuckExecutor
+
+
+def test_artifacts_all_written(tmp_path: Path):
+    # Project
+    (tmp_path / "models").mkdir(parents=True)
+    (tmp_path / "models" / "m.ff.sql").write_text(
+        "create or replace table m as select 1 as id", encoding="utf-8"
+    )
+    (tmp_path / "sources.yml").write_text("{}", encoding="utf-8")
+    REGISTRY.load_project(tmp_path)
+    env = REGISTRY.get_env()
+    ex = DuckExecutor(":memory:")
+    ex.run_sql(REGISTRY.get_node("m.ff"), env)
+
+    # Manifest
+    mp = write_manifest(tmp_path)
+    assert mp.exists()
+
+    # Catalog
+    cp = write_catalog(tmp_path, ex)
+    assert cp.exists()
+
+    # Run results
+    rp = write_run_results(
+        tmp_path,
+        started_at="2025-01-01T00:00:00+00:00",
+        finished_at="2025-01-01T00:00:10+00:00",
+        node_results=[
+            RunNodeResult(
+                name="m.ff",
+                status="success",
+                started_at="2025-01-01T00:00:00+00:00",
+                finished_at="2025-01-01T00:00:01+00:00",
+                duration_ms=1000,
+            )
+        ],
+    )
+    assert rp.exists()
+    # sanity check
+    data = json.loads(rp.read_text(encoding="utf-8"))
+    assert data["results"][0]["name"] == "m.ff"
diff --git a/tests/integration/test_incremental_duckdb_smoke.py b/tests/integration/test_incremental_duckdb_smoke.py
new file mode 100644
index 0000000..274b760
--- /dev/null
+++ b/tests/integration/test_incremental_duckdb_smoke.py
@@ -0,0 +1,7 @@
+from tests.common.utils import run
+
+
+def test_incremental_smoke_duckdb(duckdb_project, duckdb_env):
+    # Expects model with materialized='incremental'
+    res = run(["fft", "run", str(duckdb_project), "--env", "dev"], duckdb_env)
+    assert res.returncode == 0
diff --git a/tests/integration/test_schema_yaml_basic.py b/tests/integration/test_schema_yaml_basic.py
new file mode 100644
index 0000000..a7f55d8
--- /dev/null
+++ b/tests/integration/test_schema_yaml_basic.py
@@ -0,0 +1,50 @@
+from pathlib import Path
+
+import pytest
+
+from fastflowtransform.cli.test_cmd import _apply_legacy_tag_filter, _run_dq_tests
+from fastflowtransform.core import REGISTRY
+from fastflowtransform.executors.duckdb_exec import DuckExecutor
+from fastflowtransform.schema_loader import load_schema_tests
+
+
+@pytest.mark.duckdb
+def test_schema_yaml_runs_basic_checks(tmp_path: Path):
+    (tmp_path / "models").mkdir(parents=True)
+    (tmp_path / "sources.yml").write_text("{}", encoding="utf-8")
+    (tmp_path / "models" / "users.ff.sql").write_text(
+        "create or replace table users as select 1 as id, 'a@example.com' as email",
+        encoding="utf-8",
+    )
+    (tmp_path / "models" / "users.yml").write_text(
+        """
+version: 2
+models:
+  - name: users.ff
+    tags: [batch]
+    columns:
+      - name: id
+        tests:
+          - not_null
+          - unique
+      - name: email
+        tests:
+          - accepted_values:
+              values: ["a@example.com","b@example.com"]
+              severity: warn
+""",
+        encoding="utf-8",
+    )
+
+    REGISTRY.load_project(tmp_path)
+    env = REGISTRY.get_env()
+    ex = DuckExecutor(":memory:")
+    ex.run_sql(REGISTRY.get_node("users.ff"), env)
+
+    specs = load_schema_tests(tmp_path)
+    specs = _apply_legacy_tag_filter(specs, ["batch"], legacy_token=True)
+
+    results = _run_dq_tests(ex.con, specs)
+
+    error_fails = [r for r in results if (not r.ok) and r.severity != "warn"]
+    assert error_fails == []
diff --git a/tests/integration/test_schema_yaml_registry_mix.py b/tests/integration/test_schema_yaml_registry_mix.py
new file mode 100644
index 0000000..6e5888d
--- /dev/null
+++ b/tests/integration/test_schema_yaml_registry_mix.py
@@ -0,0 +1,45 @@
+from pathlib import Path
+
+import pytest
+
+from fastflowtransform.cli.test_cmd import _run_dq_tests
+from fastflowtransform.core import REGISTRY
+from fastflowtransform.executors.duckdb_exec import DuckExecutor
+from fastflowtransform.schema_loader import load_schema_tests
+
+
+@pytest.mark.duckdb
+def test_mix_multiple_tests_per_column(tmp_path: Path):
+    (tmp_path / "models").mkdir(parents=True)
+    (tmp_path / "sources.yml").write_text("{}", encoding="utf-8")
+    (tmp_path / "models" / "u.ff.sql").write_text(
+        "create or replace table u as select 1 as id, "
+        "'x@example.com' as email union all select 1, 'bad@x.com'",
+        encoding="utf-8",
+    )
+    (tmp_path / "models" / "u.yml").write_text(
+        """
+version: 2
+models:
+  - name: u.ff
+    columns:
+      - name: id
+        tests: [unique]        # will fail
+      - name: email
+        tests:
+          - not_null
+          - accepted_values:   # will fail
+              values: ["x@example.com"]
+              severity: error
+        """,
+        encoding="utf-8",
+    )
+    REGISTRY.load_project(tmp_path)
+    env = REGISTRY.get_env()
+    ex = DuckExecutor(":memory:")
+    ex.run_sql(REGISTRY.get_node("u.ff"), env)
+    specs = load_schema_tests(tmp_path)
+    res = _run_dq_tests(ex.con, specs)
+    # Both should fail with error severity
+    assert any((not r.ok) and r.kind == "unique" for r in res)
+    assert any((not r.ok) and r.kind == "accepted_values" for r in res)
diff --git a/tests/integration/test_state_modified_integration.py b/tests/integration/test_state_modified_integration.py
new file mode 100644
index 0000000..a15cb34
--- /dev/null
+++ b/tests/integration/test_state_modified_integration.py
@@ -0,0 +1,69 @@
+import time
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from fastflowtransform.cli import app
+
+
+def test_state_modified_and_plus(tmp_path: Path):
+    (tmp_path / "models").mkdir(parents=True)
+    (tmp_path / "sources.yml").write_text("{}", encoding="utf-8")
+    (tmp_path / "models" / "a.ff.sql").write_text("select 1 as x", encoding="utf-8")
+    (tmp_path / "models" / "b.ff.sql").write_text(
+        "select * from {{ ref('a.ff') }}", encoding="utf-8"
+    )
+
+    # First run to populate cache/meta
+    runner = CliRunner()
+    env = {"FF_ENGINE": "duckdb", "FF_DUCKDB_PATH": ":memory:"}
+    res1 = runner.invoke(
+        app, ["run", str(tmp_path), "--env", "dev", "--engine", "duckdb", "--cache", "rw"], env=env
+    )
+    assert res1.exit_code == 0
+
+    # Touch 'a.ff.sql' to cause fingerprint change
+    p_a = tmp_path / "models" / "a.ff.sql"
+    p_a.write_text("select 2 as x", encoding="utf-8")
+    time.sleep(0.01)  # ensure mtime change on coarse FS
+
+    # state:modified should select only 'a.ff'
+    res2 = runner.invoke(
+        app,
+        [
+            "run",
+            str(tmp_path),
+            "--env",
+            "dev",
+            "--engine",
+            "duckdb",
+            "--cache",
+            "rw",
+            "--select",
+            "state:modified",
+        ],
+        env=env,
+    )
+    assert res2.exit_code == 0
+    out2 = res2.output
+    assert "a.ff" in out2
+    # state:modified+ should include downstream 'b.ff'
+    res3 = runner.invoke(
+        app,
+        [
+            "run",
+            str(tmp_path),
+            "--env",
+            "dev",
+            "--engine",
+            "duckdb",
+            "--cache",
+            "rw",
+            "--select",
+            "state:modified+",
+        ],
+        env=env,
+    )
+    assert res3.exit_code == 0
+    out3 = res3.output
+    assert "a.ff" in out3 and "b.ff" in out3
diff --git a/tests/render/test_this_proxy.py b/tests/render/test_this_proxy.py
new file mode 100644
index 0000000..66ed6d7
--- /dev/null
+++ b/tests/render/test_this_proxy.py
@@ -0,0 +1,17 @@
+# tests/render/test_this_proxy.py
+from pathlib import Path
+
+from jinja2 import Environment
+
+from fastflowtransform.core import Node
+from fastflowtransform.executors.duckdb_exec import DuckExecutor
+
+
+def test_this_string_and_name(tmp_path: Path):
+    p = tmp_path / "m.ff.sql"
+    p.write_text("select '{{ this }}' as a, '{{ this.name }}' as b", encoding="utf-8")
+    node = Node(name="m.ff", kind="sql", path=p)
+    env = Environment()
+    ex = DuckExecutor()
+    sql = ex.render_sql(node, env).strip().lower()
+    assert sql == "select 'm' as a, 'm' as b"
diff --git a/tests/render/test_this_relation.py b/tests/render/test_this_relation.py
new file mode 100644
index 0000000..42e1fca
--- /dev/null
+++ b/tests/render/test_this_relation.py
@@ -0,0 +1,32 @@
+# tests/render/test_this_relation.py
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from fastflowtransform.core import Node
+from fastflowtransform.executors.duckdb_exec import DuckExecutor
+
+
+def _env_for_tests() -> Environment:
+    return Environment(
+        loader=FileSystemLoader(["."]),
+        autoescape=select_autoescape([]),
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+
+
+def test_this_renders_physical_relation(tmp_path):
+    # Arrange: Minimal SQL-Model, das nur `{{ this }}` rendert
+    sql_path = tmp_path / "m.ff.sql"
+    sql_path.write_text("select '{{ this }}' as rel\n", encoding="utf-8")
+
+    node = Node(name="m.ff", kind="sql", path=sql_path)
+
+    env = _env_for_tests()
+    ex = DuckExecutor()  # nur für render_sql(), DB wird nicht genutzt
+
+    # Act
+    rendered = ex.render_sql(node, env).strip()
+
+    # Assert
+    # Erwartet: physischer Name ist 'm' (relation_for("m.ff"))
+    assert rendered.lower() == "select 'm' as rel"
diff --git a/tests/schema/test_schema_loader.py b/tests/schema/test_schema_loader.py
new file mode 100644
index 0000000..5d4d5e0
--- /dev/null
+++ b/tests/schema/test_schema_loader.py
@@ -0,0 +1,35 @@
+from pathlib import Path
+
+from fastflowtransform.schema_loader import load_schema_tests
+
+
+def test_parse_schema_yaml_column_tests(tmp_path: Path):
+    (tmp_path / "models").mkdir(parents=True)
+    (tmp_path / "models" / "users_enriched.yml").write_text(
+        """
+version: 2
+models:
+  - name: users_enriched
+    tags: [batch]
+    description: "Adds gmail flag"
+    columns:
+      - name: id
+        tests:
+          - not_null: { severity: error }
+          - unique
+      - name: email
+        tests:
+          - not_null
+          - accepted_values:
+              values: ["a@example.com", "b@example.com"]
+              severity: warn
+""",
+        encoding="utf-8",
+    )
+    specs = load_schema_tests(tmp_path)
+    kinds = [(s.type, s.column, s.severity, tuple(sorted(s.tags))) for s in specs]
+    assert ("not_null", "id", "error", ("batch",)) in kinds
+    assert ("unique", "id", "error", ("batch",)) in kinds
+    assert ("not_null", "email", "error", ("batch",)) in kinds
+    assert ("accepted_values", "email", "warn", ("batch",)) in kinds
+    assert all(s.table == "users_enriched" for s in specs)
diff --git a/tests/selectors/test_state_modified_unit.py b/tests/selectors/test_state_modified_unit.py
new file mode 100644
index 0000000..758d232
--- /dev/null
+++ b/tests/selectors/test_state_modified_unit.py
@@ -0,0 +1,18 @@
+from pathlib import Path
+
+from fastflowtransform.cli.selectors import _downstream_closure
+from fastflowtransform.core import REGISTRY, Node
+
+
+def test_downstream_closure_simple():
+    REGISTRY.nodes.clear()
+    REGISTRY.nodes.update(
+        {
+            "a.ff": Node("a.ff", "sql", path=Path("dummy"), deps=[]),
+            "b.ff": Node("b.ff", "sql", path=Path("dummy"), deps=["a.ff"]),
+            "c.ff": Node("c.ff", "sql", path=Path("dummy"), deps=["b.ff"]),
+            "x.ff": Node("x.ff", "sql", path=Path("dummy"), deps=[]),
+        }
+    )
+    ds = _downstream_closure({"a.ff"})
+    assert ds == {"a.ff", "b.ff", "c.ff"}
diff --git a/tests/test_registry/test_dispatch.py b/tests/test_registry/test_dispatch.py
new file mode 100644
index 0000000..f3d5ae9
--- /dev/null
+++ b/tests/test_registry/test_dispatch.py
@@ -0,0 +1,16 @@
+from fastflowtransform.executors.duckdb_exec import DuckExecutor
+from fastflowtransform.test_registry import TESTS
+
+
+def test_registry_not_null_and_unique_and_params_and_sql():
+    ex = DuckExecutor(":memory:")
+    ex.con.execute("create table t(id int, email varchar)")
+    ex.con.execute("insert into t values (1,'a@example.com'),(1,'b@example.com'),(2,null)")
+
+    ok1, msg1, sql1 = TESTS["not_null"](ex.con, "t", "email", {})
+    assert not ok1 and "is null" in (msg1 or "").lower()
+    assert "select count(*) from t where email is null" in (sql1 or "").lower()
+
+    ok2, msg2, sql2 = TESTS["unique"](ex.con, "t", "id", {})
+    assert not ok2 and "duplicate" in (msg2 or "").lower()
+    assert "group by 1 having count(*) > 1" in (sql2 or "").lower()
diff --git a/tests/testing/test_accepted_values_unit.py b/tests/testing/test_accepted_values_unit.py
new file mode 100644
index 0000000..4de3492
--- /dev/null
+++ b/tests/testing/test_accepted_values_unit.py
@@ -0,0 +1,17 @@
+import pytest
+
+from fastflowtransform.executors.duckdb_exec import DuckExecutor
+from fastflowtransform.testing import TestFailure, accepted_values
+
+
+def test_accepted_values_pass_and_fail():
+    ex = DuckExecutor(":memory:")
+    ex.con.execute("create table t(id int, email varchar)")
+    ex.con.execute("insert into t values (1,'a@example.com'),(2,'b@example.com')")
+    # Pass
+    assert accepted_values(ex.con, "t", "email", values=["a@example.com", "b@example.com"]) is True
+    # Fail
+    ex.con.execute("insert into t values (3,'bad@example.com')")
+    with pytest.raises(TestFailure) as e:
+        accepted_values(ex.con, "t", "email", values=["a@example.com", "b@example.com"])
+    assert "outside accepted set" in str(e.value)
diff --git a/tests/unit/test_fingerprint.py b/tests/unit/test_fingerprint.py
index af90672..7decb83 100644
--- a/tests/unit/test_fingerprint.py
+++ b/tests/unit/test_fingerprint.py
@@ -3,7 +3,9 @@
 
 from pathlib import Path
 
-from fastflowtransform.core import Node
+import yaml
+
+from fastflowtransform.core import Node, _parse_sources_yaml
 from fastflowtransform.fingerprint import (
     EnvCtx,
     build_env_ctx,
@@ -16,9 +18,19 @@
 
 
 def test_sources_normalization_stable():
-    a = {"crm": {"users": {"identifier": "seed_users"}, "orders": {"identifier": "seed_orders"}}}
-    b = {"crm": {"orders": {"identifier": "seed_orders"}, "users": {"identifier": "seed_users"}}}
-    assert normalized_sources_blob(a) == normalized_sources_blob(b)
+    doc = """version: 2
+
+sources:
+  - name: crm
+    tables:
+      - name: users
+        identifier: seed_users
+      - name: orders
+        identifier: seed_orders
+"""
+    parsed = _parse_sources_yaml(yaml.safe_load(doc))
+    reordered = {"crm": {"orders": parsed["crm"]["orders"], "users": parsed["crm"]["users"]}}
+    assert normalized_sources_blob(parsed) == normalized_sources_blob(reordered)
 
 
 def test_env_ctx_respects_selected_env_keys(monkeypatch):
diff --git a/tests/unit/test_incremental_planner.py b/tests/unit/test_incremental_planner.py
new file mode 100644
index 0000000..dddc1d7
--- /dev/null
+++ b/tests/unit/test_incremental_planner.py
@@ -0,0 +1,64 @@
+from types import SimpleNamespace
+
+from fastflowtransform.incremental import run_or_dispatch
+
+
+class FakeEx:
+    def __init__(self):
+        self.sql = None
+        self.ctas = 0
+        self.ins = 0
+        self.mrg = 0
+        self.exists = False
+
+    def exists_relation(self, r):
+        return self.exists
+
+    def render_sql(self, node, env, ref_resolver=None, source_resolver=None):
+        return "select 1 as id"
+
+    def _resolve_ref(self, nm, env):
+        return nm
+
+    def _resolve_source(self, *a, **k):
+        return "src"
+
+    def create_table_as(self, r, sql):
+        self.ctas += 1
+        self.sql = sql
+
+    def incremental_insert(self, r, sql):
+        self.ins += 1
+        self.sql = sql
+
+    def incremental_merge(self, r, sql, keys):
+        self.mrg += 1
+        self.sql = sql
+
+    def run_sql(self, node, env):
+        self.sql = "plain"
+
+
+def test_incremental_cold_runs_ctas(jinja_env):
+    node = SimpleNamespace(name="m", kind="sql", meta={"materialized": "incremental"})
+    ex = FakeEx()
+    run_or_dispatch(ex, node, jinja_env)
+    assert ex.ctas == 1 and ex.ins == 0 and ex.mrg == 0
+
+
+def test_incremental_warm_insert_without_key(jinja_env):
+    node = SimpleNamespace(name="m", kind="sql", meta={"materialized": "incremental"})
+    ex = FakeEx()
+    ex.exists = True
+    run_or_dispatch(ex, node, jinja_env)
+    assert ex.ins == 1 and ex.mrg == 0
+
+
+def test_incremental_warm_merge_with_key(jinja_env):
+    node = SimpleNamespace(
+        name="m", kind="sql", meta={"materialized": "incremental", "unique_key": "id"}
+    )
+    ex = FakeEx()
+    ex.exists = True
+    run_or_dispatch(ex, node, jinja_env)
+    assert ex.mrg == 1
diff --git a/tests/unit/test_result_selector.py b/tests/unit/test_result_selector.py
new file mode 100644
index 0000000..1490765
--- /dev/null
+++ b/tests/unit/test_result_selector.py
@@ -0,0 +1,193 @@
+# tests/unit/test_result_selector.py
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from fastflowtransform.cli.selectors import _compile_selector
+from fastflowtransform.core import REGISTRY, Node
+
+
+def _write_run_results(base: Path, results: list[dict]) -> None:
+    tgt = base / ".fastflowtransform" / "target"
+    tgt.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "metadata": {"tool": "fastflowtransform", "generated_at": "2025-01-01T00:00:00Z"},
+        "run_started_at": "2025-01-01T00:00:00Z",
+        "run_finished_at": "2025-01-01T00:00:01Z",
+        "results": results,
+    }
+    (tgt / "run_results.json").write_text(
+        json.dumps(payload, ensure_ascii=False, sort_keys=True), encoding="utf-8"
+    )
+
+
+@pytest.fixture(autouse=True)
+def clean_registry():
+    # Ensure each test starts with a clean registry
+    REGISTRY.nodes.clear()
+    REGISTRY.py_funcs.clear()
+    REGISTRY.py_requires.clear()
+    REGISTRY.macros.clear()
+    REGISTRY.sources = {}
+    REGISTRY.project_vars = {}
+    REGISTRY.cli_vars = {}
+    yield
+    REGISTRY.nodes.clear()
+
+
+def test_result_tokens_ok_error_fail_warn(tmp_path: Path):
+    # Minimal project structure so selectors can resolve project dir
+    (tmp_path / "models").mkdir(parents=True)
+    REGISTRY.project_dir = tmp_path  # allow selectors to find .fastflowtransform/target
+
+    # Register minimal nodes (paths are dummies; selectors don't read files)
+    REGISTRY.nodes.update(
+        {
+            "ok_node": Node("ok_node", "sql", path=tmp_path / "models" / "ok.sql", deps=[]),
+            "err_node": Node("err_node", "sql", path=tmp_path / "models" / "err.sql", deps=[]),
+            "warn_node": Node("warn_node", "sql", path=tmp_path / "models" / "warn.sql", deps=[]),
+            "other": Node("other", "sql", path=tmp_path / "models" / "other.sql", deps=[]),
+        }
+    )
+
+    # Simulate a previous run with one success, one error, one success+warning
+    _write_run_results(
+        tmp_path,
+        results=[
+            {
+                "name": "ok_node",
+                "status": "success",
+                "started_at": "2025-01-01T00:00:00Z",
+                "finished_at": "2025-01-01T00:00:00Z",
+                "duration_ms": 5,
+            },
+            {
+                "name": "err_node",
+                "status": "error",
+                "started_at": "2025-01-01T00:00:00Z",
+                "finished_at": "2025-01-01T00:00:00Z",
+                "duration_ms": 7,
+                "message": "boom",
+            },
+            {
+                "name": "warn_node",
+                "status": "success",
+                "started_at": "2025-01-01T00:00:00Z",
+                "finished_at": "2025-01-01T00:00:00Z",
+                "duration_ms": 3,
+                # Either of these should trigger "warn" detection. We'll set both for clarity.
+                "message": "WARN: threshold crossed",
+                "warnings": 1,
+            },
+        ],
+    )
+
+    # result:ok
+    _, pred = _compile_selector(["result:ok"])
+    assert pred(REGISTRY.nodes["ok_node"])
+    assert not pred(REGISTRY.nodes["err_node"])
+    assert not pred(REGISTRY.nodes["warn_node"])
+
+    # result:error
+    _, pred = _compile_selector(["result:error"])
+    assert pred(REGISTRY.nodes["err_node"])
+    assert not pred(REGISTRY.nodes["ok_node"])
+    assert not pred(REGISTRY.nodes["warn_node"])
+
+    # result:fail (alias for error)
+    _, pred = _compile_selector(["result:fail"])
+    assert pred(REGISTRY.nodes["err_node"])
+    assert not pred(REGISTRY.nodes["ok_node"])
+
+    # result:warn
+    _, pred = _compile_selector(["result:warn"])
+    assert pred(REGISTRY.nodes["warn_node"])
+    assert not pred(REGISTRY.nodes["ok_node"])
+    assert not pred(REGISTRY.nodes["err_node"])
+
+    # Combination: result:ok + nameglob
+    _, pred = _compile_selector(["result:ok", "ok_*"])
+    assert pred(REGISTRY.nodes["ok_node"])
+    assert not pred(REGISTRY.nodes["warn_node"])
+    assert not pred(REGISTRY.nodes["err_node"])
+
+    # Unknown token: result:maybe
+    _, pred = _compile_selector(["result:maybe"])
+    assert not pred(REGISTRY.nodes["ok_node"])
+    assert not pred(REGISTRY.nodes["err_node"])
+    assert not pred(REGISTRY.nodes["warn_node"])
+
+
+def test_result_tokens_without_file_are_noops(tmp_path: Path):
+    (tmp_path / "models").mkdir(parents=True)
+    REGISTRY.project_dir = tmp_path
+
+    REGISTRY.nodes.update(
+        {
+            "a": Node("a", "sql", path=tmp_path / "models" / "a.sql", deps=[]),
+            "b": Node("b", "sql", path=tmp_path / "models" / "b.sql", deps=[]),
+        }
+    )
+
+    for token in ("result:ok", "result:error", "result:fail", "result:warn"):
+        _, pred = _compile_selector([token])
+        assert not pred(REGISTRY.nodes["a"])
+        assert not pred(REGISTRY.nodes["b"])
+
+
+def test_result_tokens_coexist_with_other_filters(tmp_path: Path):
+    (tmp_path / "models").mkdir(parents=True)
+    REGISTRY.project_dir = tmp_path
+
+    REGISTRY.nodes.update(
+        {
+            "alpha": Node(
+                "alpha",
+                "sql",
+                path=tmp_path / "models" / "alpha.sql",
+                deps=[],
+                meta={"tags": ["core"]},
+            ),
+            "beta": Node(
+                "beta",
+                "sql",
+                path=tmp_path / "models" / "beta.sql",
+                deps=[],
+                meta={"tags": ["extra"]},
+            ),
+        }
+    )
+
+    _write_run_results(
+        tmp_path,
+        results=[
+            {
+                "name": "alpha",
+                "status": "success",
+                "started_at": "2025-01-01T00:00:00Z",
+                "finished_at": "2025-01-01T00:00:00Z",
+                "duration_ms": 1,
+            },
+            {
+                "name": "beta",
+                "status": "error",
+                "started_at": "2025-01-01T00:00:00Z",
+                "finished_at": "2025-01-01T00:00:00Z",
+                "duration_ms": 2,
+                "message": "boom",
+            },
+        ],
+    )
+
+    # result:ok AND tag:core → only alpha
+    _, pred = _compile_selector(["result:ok", "tag:core"])
+    assert pred(REGISTRY.nodes["alpha"])
+    assert not pred(REGISTRY.nodes["beta"])
+
+    # result:error AND tag:extra → only beta
+    _, pred = _compile_selector(["result:error", "tag:extra"])
+    assert pred(REGISTRY.nodes["beta"])
+    assert not pred(REGISTRY.nodes["alpha"])
diff --git a/tests/unit/test_sources_parser.py b/tests/unit/test_sources_parser.py
new file mode 100644
index 0000000..3ecf1ed
--- /dev/null
+++ b/tests/unit/test_sources_parser.py
@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import yaml
+
+from fastflowtransform.core import _parse_sources_yaml, resolve_source_entry
+
+
+def test_parse_sources_and_overrides_merge():
+    doc = """version: 2
+
+sources:
+  - name: raw
+    schema: staging
+    overrides:
+      databricks_spark:
+        schema: bronze
+    tables:
+      - name: users
+        identifier: seed_users
+        overrides:
+          databricks_spark:
+            format: delta
+            location: "/mnt/delta/raw/users"
+"""
+
+    parsed = _parse_sources_yaml(yaml.safe_load(doc))
+    entry = parsed["raw"]["users"]
+
+    default_cfg = resolve_source_entry(entry, "duckdb")
+    assert default_cfg["identifier"] == "seed_users"
+    assert default_cfg["schema"] == "staging"
+    assert default_cfg["location"] is None
+
+    spark_cfg = resolve_source_entry(entry, "databricks_spark")
+    assert spark_cfg["schema"] == "bronze"
+    assert spark_cfg["format"] == "delta"
+    assert spark_cfg["location"] == "/mnt/delta/raw/users"
+
+
+def test_wildcard_override_applied_before_engine_specific():
+    doc = """version: 2
+
+sources:
+  - name: crm
+    tables:
+      - name: users
+        identifier: seed_users
+        overrides:
+          "*":
+            schema: shared
+          postgres:
+            schema: analytics
+"""
+
+    parsed = _parse_sources_yaml(yaml.safe_load(doc))
+    entry = parsed["crm"]["users"]
+
+    duck_cfg = resolve_source_entry(entry, "duckdb")
+    assert duck_cfg["schema"] == "shared"
+
+    pg_cfg = resolve_source_entry(entry, "postgres")
+    assert pg_cfg["schema"] == "analytics"
+
+
+def test_missing_identifier_falls_back_to_table_name():
+    doc = """version: 2
+
+sources:
+  - name: ext
+    tables:
+      - name: events
+        overrides:
+          postgres:
+            schema: external
+"""
+
+    parsed = _parse_sources_yaml(yaml.safe_load(doc))
+    entry = parsed["ext"]["events"]
+
+    pg_cfg = resolve_source_entry(entry, "postgres", default_identifier="events")
+    assert pg_cfg["identifier"] == "events"
diff --git a/uv.lock b/uv.lock
index ecdcb11..5d45621 100644
--- a/uv.lock
+++ b/uv.lock
@@ -124,6 +124,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/78/b6/6307fbef88d9b5ee7421e68d78a9f162e0da4900bc5f5793f6d3d0e34fb8/annotated_types-0.7.0-py3-none-any.whl", hash = "sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc8131bcb4eebe8849b8e5c773f3a1c582a53", size = 13643, upload-time = "2024-05-20T21:33:24.1Z" },
 ]
 
+[[package]]
+name = "anyio"
+version = "4.11.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "idna" },
+    { name = "sniffio" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c6/78/7d432127c41b50bccba979505f272c16cbcadcc33645d5fa3a738110ae75/anyio-4.11.0.tar.gz", hash = "sha256:82a8d0b81e318cc5ce71a5f1f8b5c4e63619620b63141ef8c995fa0db95a57c4", size = 219094, upload-time = "2025-09-23T09:19:12.58Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/15/b3/9b1a8074496371342ec1e796a96f99c82c945a339cd81a8e73de28b4cf9e/anyio-4.11.0-py3-none-any.whl", hash = "sha256:0287e96f4d26d4149305414d4e3bc32f0dcd0862365a4bddea19d7a1ec38c4fc", size = 109097, upload-time = "2025-09-23T09:19:10.601Z" },
+]
+
 [[package]]
 name = "asn1crypto"
 version = "1.5.1"
@@ -160,6 +174,29 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/3a/2a/7cc015f5b9f5db42b7d48157e23356022889fc354a2813c15934b7cb5c0e/attrs-25.4.0-py3-none-any.whl", hash = "sha256:adcf7e2a1fb3b36ac48d97835bb6d8ade15b8dcce26aba8bf1d14847b57a3373", size = 67615, upload-time = "2025-10-06T13:54:43.17Z" },
 ]
 
+[[package]]
+name = "babel"
+version = "2.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/6b/d52e42361e1aa00709585ecc30b3f9684b3ab62530771402248b1b1d6240/babel-2.17.0.tar.gz", hash = "sha256:0c54cffb19f690cdcc52a3b50bcbf71e07a808d1c80d549f2459b9d2cf0afb9d", size = 9951852, upload-time = "2025-02-01T15:17:41.026Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/b8/3fe70c75fe32afc4bb507f75563d39bc5642255d1d94f1f23604725780bf/babel-2.17.0-py3-none-any.whl", hash = "sha256:4d0b53093fdfb4b21c92b5213dba5a1b23885afa8383709427046b21c366e5f2", size = 10182537, upload-time = "2025-02-01T15:17:37.39Z" },
+]
+
+[[package]]
+name = "backrefs"
+version = "5.9"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/eb/a7/312f673df6a79003279e1f55619abbe7daebbb87c17c976ddc0345c04c7b/backrefs-5.9.tar.gz", hash = "sha256:808548cb708d66b82ee231f962cb36faaf4f2baab032f2fbb783e9c2fdddaa59", size = 5765857, upload-time = "2025-06-22T19:34:13.97Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/19/4d/798dc1f30468134906575156c089c492cf79b5a5fd373f07fe26c4d046bf/backrefs-5.9-py310-none-any.whl", hash = "sha256:db8e8ba0e9de81fcd635f440deab5ae5f2591b54ac1ebe0550a2ca063488cd9f", size = 380267, upload-time = "2025-06-22T19:34:05.252Z" },
+    { url = "https://files.pythonhosted.org/packages/55/07/f0b3375bf0d06014e9787797e6b7cc02b38ac9ff9726ccfe834d94e9991e/backrefs-5.9-py311-none-any.whl", hash = "sha256:6907635edebbe9b2dc3de3a2befff44d74f30a4562adbb8b36f21252ea19c5cf", size = 392072, upload-time = "2025-06-22T19:34:06.743Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/12/4f345407259dd60a0997107758ba3f221cf89a9b5a0f8ed5b961aef97253/backrefs-5.9-py312-none-any.whl", hash = "sha256:7fdf9771f63e6028d7fee7e0c497c81abda597ea45d6b8f89e8ad76994f5befa", size = 397947, upload-time = "2025-06-22T19:34:08.172Z" },
+    { url = "https://files.pythonhosted.org/packages/10/bf/fa31834dc27a7f05e5290eae47c82690edc3a7b37d58f7fb35a1bdbf355b/backrefs-5.9-py313-none-any.whl", hash = "sha256:cc37b19fa219e93ff825ed1fed8879e47b4d89aa7a1884860e2db64ccd7c676b", size = 399843, upload-time = "2025-06-22T19:34:09.68Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/24/b29af34b2c9c41645a9f4ff117bae860291780d73880f449e0b5d948c070/backrefs-5.9-py314-none-any.whl", hash = "sha256:df5e169836cc8acb5e440ebae9aad4bf9d15e226d3bad049cf3f6a5c20cc8dc9", size = 411762, upload-time = "2025-06-22T19:34:11.037Z" },
+    { url = "https://files.pythonhosted.org/packages/41/ff/392bff89415399a979be4a65357a41d92729ae8580a66073d8ec8d810f98/backrefs-5.9-py39-none-any.whl", hash = "sha256:f48ee18f6252b8f5777a22a00a09a85de0ca931658f1dd96d4406a34f3748c60", size = 380265, upload-time = "2025-06-22T19:34:12.405Z" },
+]
+
 [[package]]
 name = "bigframes"
 version = "2.24.0"
@@ -689,6 +726,7 @@ dependencies = [
     { name = "bigframes" },
     { name = "duckdb" },
     { name = "google-cloud-bigquery" },
+    { name = "httpx" },
     { name = "jinja2" },
     { name = "pandas" },
     { name = "psycopg", extra = ["binary"] },
@@ -706,9 +744,12 @@ dependencies = [
 
 [package.optional-dependencies]
 dev = [
+    { name = "mkdocs" },
+    { name = "mkdocs-material" },
     { name = "mypy" },
     { name = "pandas-stubs" },
     { name = "pre-commit" },
+    { name = "pymdown-extensions" },
     { name = "pytest" },
     { name = "ruff" },
     { name = "types-pyyaml" },
@@ -725,7 +766,10 @@ requires-dist = [
     { name = "bigframes", specifier = ">=2.24.0" },
     { name = "duckdb", specifier = ">=1.0" },
     { name = "google-cloud-bigquery", specifier = ">=3.25" },
+    { name = "httpx", specifier = ">=0.28.1" },
     { name = "jinja2", specifier = ">=3.1" },
+    { name = "mkdocs", marker = "extra == 'dev'", specifier = ">=1.6" },
+    { name = "mkdocs-material", marker = "extra == 'dev'", specifier = ">=9.5" },
     { name = "mypy", marker = "extra == 'dev'", specifier = "==1.18.*" },
     { name = "pandas", specifier = ">=2.0" },
     { name = "pandas-stubs", marker = "extra == 'dev'", specifier = ">=2.1" },
@@ -734,6 +778,7 @@ requires-dist = [
     { name = "psycopg2-binary", specifier = ">=2.9" },
     { name = "pydantic", specifier = ">=2.8" },
     { name = "pydantic-settings", specifier = ">=2.4" },
+    { name = "pymdown-extensions", marker = "extra == 'dev'", specifier = ">=10.0" },
     { name = "pyspark", specifier = ">=4.0.1" },
     { name = "pytest", marker = "extra == 'dev'", specifier = "==8.4.*" },
     { name = "python-dotenv", specifier = ">=1.0" },
@@ -936,6 +981,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0b/70/d5cd0696eff08e62fdbdebe5b46527facb4e7220eabe0ac6225efab50168/geopandas-1.1.1-py3-none-any.whl", hash = "sha256:589e61aaf39b19828843df16cb90234e72897e2579be236f10eee0d052ad98e8", size = 338365, upload-time = "2025-06-26T21:04:55.139Z" },
 ]
 
+[[package]]
+name = "ghp-import"
+version = "2.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "python-dateutil" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d9/29/d40217cbe2f6b1359e00c6c307bb3fc876ba74068cbab3dde77f03ca0dc4/ghp-import-2.1.0.tar.gz", hash = "sha256:9c535c4c61193c2df8871222567d7fd7e5014d835f97dc7b7439069e2413d343", size = 10943, upload-time = "2022-05-02T15:47:16.11Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f7/ec/67fbef5d497f86283db54c22eec6f6140243aae73265799baaaa19cd17fb/ghp_import-2.1.0-py3-none-any.whl", hash = "sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619", size = 11034, upload-time = "2022-05-02T15:47:14.552Z" },
+]
+
 [[package]]
 name = "google-api-core"
 version = "2.25.2"
@@ -1261,6 +1318,43 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d8/ad/6f414bb0b36eee20d93af6907256f208ffcda992ae6d3d7b6a778afe31e6/grpcio_status-1.75.1-py3-none-any.whl", hash = "sha256:f681b301be26dcf7abf5c765d4a22e4098765e1a65cbdfa3efca384edf8e4e3c", size = 14428, upload-time = "2025-09-26T09:12:55.516Z" },
 ]
 
+[[package]]
+name = "h11"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
+]
+
+[[package]]
+name = "httpcore"
+version = "1.0.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz", hash = "sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8", size = 85484, upload-time = "2025-04-24T22:06:22.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
+]
+
+[[package]]
+name = "httpx"
+version = "0.28.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "certifi" },
+    { name = "httpcore" },
+    { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz", hash = "sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc", size = 141406, upload-time = "2024-12-06T15:37:23.222Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" },
+]
+
 [[package]]
 name = "humanize"
 version = "4.13.0"
@@ -1460,6 +1554,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/80/be/3578e8afd18c88cdf9cb4cffde75a96d2be38c5a903f1ed0ceec061bd09e/kiwisolver-1.4.9-cp314-cp314t-win_arm64.whl", hash = "sha256:4a48a2ce79d65d363597ef7b567ce3d14d68783d2b2263d98db3d9477805ba32", size = 70260, upload-time = "2025-08-10T21:27:36.606Z" },
 ]
 
+[[package]]
+name = "markdown"
+version = "3.9"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/8d/37/02347f6d6d8279247a5837082ebc26fc0d5aaeaf75aa013fcbb433c777ab/markdown-3.9.tar.gz", hash = "sha256:d2900fe1782bd33bdbbd56859defef70c2e78fc46668f8eb9df3128138f2cb6a", size = 364585, upload-time = "2025-09-04T20:25:22.885Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/70/ae/44c4a6a4cbb496d93c6257954260fe3a6e91b7bed2240e5dad2a717f5111/markdown-3.9-py3-none-any.whl", hash = "sha256:9f4d91ed810864ea88a6f32c07ba8bee1346c0cc1f6b1f9f6c822f2a9667d280", size = 107441, upload-time = "2025-09-04T20:25:21.784Z" },
+]
+
 [[package]]
 name = "markdown-it-py"
 version = "4.0.0"
@@ -1610,6 +1713,84 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
 ]
 
+[[package]]
+name = "mergedeep"
+version = "1.3.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/3a/41/580bb4006e3ed0361b8151a01d324fb03f420815446c7def45d02f74c270/mergedeep-1.3.4.tar.gz", hash = "sha256:0096d52e9dad9939c3d975a774666af186eda617e6ca84df4c94dec30004f2a8", size = 4661, upload-time = "2021-02-05T18:55:30.623Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/19/04f9b178c2d8a15b076c8b5140708fa6ffc5601fb6f1e975537072df5b2a/mergedeep-1.3.4-py3-none-any.whl", hash = "sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307", size = 6354, upload-time = "2021-02-05T18:55:29.583Z" },
+]
+
+[[package]]
+name = "mkdocs"
+version = "1.6.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "ghp-import" },
+    { name = "jinja2" },
+    { name = "markdown" },
+    { name = "markupsafe" },
+    { name = "mergedeep" },
+    { name = "mkdocs-get-deps" },
+    { name = "packaging" },
+    { name = "pathspec" },
+    { name = "pyyaml" },
+    { name = "pyyaml-env-tag" },
+    { name = "watchdog" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bc/c6/bbd4f061bd16b378247f12953ffcb04786a618ce5e904b8c5a01a0309061/mkdocs-1.6.1.tar.gz", hash = "sha256:7b432f01d928c084353ab39c57282f29f92136665bdd6abf7c1ec8d822ef86f2", size = 3889159, upload-time = "2024-08-30T12:24:06.899Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/22/5b/dbc6a8cddc9cfa9c4971d59fb12bb8d42e161b7e7f8cc89e49137c5b279c/mkdocs-1.6.1-py3-none-any.whl", hash = "sha256:db91759624d1647f3f34aa0c3f327dd2601beae39a366d6e064c03468d35c20e", size = 3864451, upload-time = "2024-08-30T12:24:05.054Z" },
+]
+
+[[package]]
+name = "mkdocs-get-deps"
+version = "0.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mergedeep" },
+    { name = "platformdirs" },
+    { name = "pyyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/98/f5/ed29cd50067784976f25ed0ed6fcd3c2ce9eb90650aa3b2796ddf7b6870b/mkdocs_get_deps-0.2.0.tar.gz", hash = "sha256:162b3d129c7fad9b19abfdcb9c1458a651628e4b1dea628ac68790fb3061c60c", size = 10239, upload-time = "2023-11-20T17:51:09.981Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9f/d4/029f984e8d3f3b6b726bd33cafc473b75e9e44c0f7e80a5b29abc466bdea/mkdocs_get_deps-0.2.0-py3-none-any.whl", hash = "sha256:2bf11d0b133e77a0dd036abeeb06dec8775e46efa526dc70667d8863eefc6134", size = 9521, upload-time = "2023-11-20T17:51:08.587Z" },
+]
+
+[[package]]
+name = "mkdocs-material"
+version = "9.6.22"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "babel" },
+    { name = "backrefs" },
+    { name = "colorama" },
+    { name = "jinja2" },
+    { name = "markdown" },
+    { name = "mkdocs" },
+    { name = "mkdocs-material-extensions" },
+    { name = "paginate" },
+    { name = "pygments" },
+    { name = "pymdown-extensions" },
+    { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5f/5d/317e37b6c43325cb376a1d6439df9cc743b8ee41c84603c2faf7286afc82/mkdocs_material-9.6.22.tar.gz", hash = "sha256:87c158b0642e1ada6da0cbd798a3389b0bc5516b90e5ece4a0fb939f00bacd1c", size = 4044968, upload-time = "2025-10-15T09:21:15.409Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cc/82/6fdb9a7a04fb222f4849ffec1006f891a0280825a20314d11f3ccdee14eb/mkdocs_material-9.6.22-py3-none-any.whl", hash = "sha256:14ac5f72d38898b2f98ac75a5531aaca9366eaa427b0f49fc2ecf04d99b7ad84", size = 9206252, upload-time = "2025-10-15T09:21:12.175Z" },
+]
+
+[[package]]
+name = "mkdocs-material-extensions"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/79/9b/9b4c96d6593b2a541e1cb8b34899a6d021d208bb357042823d4d2cabdbe7/mkdocs_material_extensions-1.3.1.tar.gz", hash = "sha256:10c9511cea88f568257f960358a467d12b970e1f7b2c0e5fb2bb48cab1928443", size = 11847, upload-time = "2023-11-22T19:09:45.208Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl", hash = "sha256:adff8b62700b25cb77b53358dad940f3ef973dd6db797907c49e3c2ef3ab4e31", size = 8728, upload-time = "2023-11-22T19:09:43.465Z" },
+]
+
 [[package]]
 name = "multidict"
 version = "6.7.0"
@@ -1840,6 +2021,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl", hash = "sha256:29572ef2b1f17581046b3a2227d5c611fb25ec70ca1ba8554b24b0e69331a484", size = 66469, upload-time = "2025-04-19T11:48:57.875Z" },
 ]
 
+[[package]]
+name = "paginate"
+version = "0.5.7"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ec/46/68dde5b6bc00c1296ec6466ab27dddede6aec9af1b99090e1107091b3b84/paginate-0.5.7.tar.gz", hash = "sha256:22bd083ab41e1a8b4f3690544afb2c60c25e5c9a63a30fa2f483f6c60c8e5945", size = 19252, upload-time = "2024-08-25T14:17:24.139Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/90/96/04b8e52da071d28f5e21a805b19cb9390aa17a47462ac87f5e2696b9566d/paginate-0.5.7-py2.py3-none-any.whl", hash = "sha256:b885e2af73abcf01d9559fd5216b57ef722f8c42affbb63942377668e35c7591", size = 13746, upload-time = "2024-08-25T14:17:22.55Z" },
+]
+
 [[package]]
 name = "pandas"
 version = "2.3.3"
@@ -2467,6 +2657,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/61/ad/689f02752eeec26aed679477e80e632ef1b682313be70793d798c1d5fc8f/PyJWT-2.10.1-py3-none-any.whl", hash = "sha256:dcdd193e30abefd5debf142f9adfcdd2b58004e644f25406ffaebd50bd98dacb", size = 22997, upload-time = "2024-11-28T03:43:27.893Z" },
 ]
 
+[[package]]
+name = "pymdown-extensions"
+version = "10.16.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown" },
+    { name = "pyyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/55/b3/6d2b3f149bc5413b0a29761c2c5832d8ce904a1d7f621e86616d96f505cc/pymdown_extensions-10.16.1.tar.gz", hash = "sha256:aace82bcccba3efc03e25d584e6a22d27a8e17caa3f4dd9f207e49b787aa9a91", size = 853277, upload-time = "2025-07-28T16:19:34.167Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e4/06/43084e6cbd4b3bc0e80f6be743b2e79fbc6eed8de9ad8c629939fa55d972/pymdown_extensions-10.16.1-py3-none-any.whl", hash = "sha256:d6ba157a6c03146a7fb122b2b9a121300056384eafeec9c9f9e584adfdb2a32d", size = 266178, upload-time = "2025-07-28T16:19:31.401Z" },
+]
+
 [[package]]
 name = "pyogrio"
 version = "0.11.1"
@@ -2686,6 +2889,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" },
 ]
 
+[[package]]
+name = "pyyaml-env-tag"
+version = "1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pyyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/2e/79c822141bfd05a853236b504869ebc6b70159afc570e1d5a20641782eaa/pyyaml_env_tag-1.1.tar.gz", hash = "sha256:2eb38b75a2d21ee0475d6d97ec19c63287a7e140231e4214969d0eac923cd7ff", size = 5737, upload-time = "2025-05-13T15:24:01.64Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/11/432f32f8097b03e3cd5fe57e88efb685d964e2e5178a48ed61e841f7fdce/pyyaml_env_tag-1.1-py3-none-any.whl", hash = "sha256:17109e1a528561e32f026364712fee1264bc2ea6715120891174ed1b980d2e04", size = 4722, upload-time = "2025-05-13T15:23:59.629Z" },
+]
+
 [[package]]
 name = "requests"
 version = "2.32.5"
@@ -2855,6 +3070,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" },
 ]
 
+[[package]]
+name = "sniffio"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a2/87/a6771e1546d97e7e041b6ae58d80074f81b7d5121207425c964ddf5cfdbd/sniffio-1.3.1.tar.gz", hash = "sha256:f4324edc670a0f49750a81b895f35c3adb843cca46f0530f79fc1babb23789dc", size = 20372, upload-time = "2024-02-25T23:20:04.057Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235, upload-time = "2024-02-25T23:20:01.196Z" },
+]
+
 [[package]]
 name = "snowflake"
 version = "1.8.0"
@@ -3149,6 +3373,30 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/27/73/d9a94da0e9d470a543c1b9d3ccbceb0f59455983088e727b8a1824ed90fb/virtualenv-20.35.3-py3-none-any.whl", hash = "sha256:63d106565078d8c8d0b206d48080f938a8b25361e19432d2c9db40d2899c810a", size = 5981061, upload-time = "2025-10-10T21:23:30.433Z" },
 ]
 
+[[package]]
+name = "watchdog"
+version = "6.0.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/db/7d/7f3d619e951c88ed75c6037b246ddcf2d322812ee8ea189be89511721d54/watchdog-6.0.0.tar.gz", hash = "sha256:9ddf7c82fda3ae8e24decda1338ede66e1c99883db93711d8fb941eaa2d8c282", size = 131220, upload-time = "2024-11-01T14:07:13.037Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/39/ea/3930d07dafc9e286ed356a679aa02d777c06e9bfd1164fa7c19c288a5483/watchdog-6.0.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:bdd4e6f14b8b18c334febb9c4425a878a2ac20efd1e0b231978e7b150f92a948", size = 96471, upload-time = "2024-11-01T14:06:37.745Z" },
+    { url = "https://files.pythonhosted.org/packages/12/87/48361531f70b1f87928b045df868a9fd4e253d9ae087fa4cf3f7113be363/watchdog-6.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c7c15dda13c4eb00d6fb6fc508b3c0ed88b9d5d374056b239c4ad1611125c860", size = 88449, upload-time = "2024-11-01T14:06:39.748Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/7e/8f322f5e600812e6f9a31b75d242631068ca8f4ef0582dd3ae6e72daecc8/watchdog-6.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6f10cb2d5902447c7d0da897e2c6768bca89174d0c6e1e30abec5421af97a5b0", size = 89054, upload-time = "2024-11-01T14:06:41.009Z" },
+    { url = "https://files.pythonhosted.org/packages/68/98/b0345cabdce2041a01293ba483333582891a3bd5769b08eceb0d406056ef/watchdog-6.0.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:490ab2ef84f11129844c23fb14ecf30ef3d8a6abafd3754a6f75ca1e6654136c", size = 96480, upload-time = "2024-11-01T14:06:42.952Z" },
+    { url = "https://files.pythonhosted.org/packages/85/83/cdf13902c626b28eedef7ec4f10745c52aad8a8fe7eb04ed7b1f111ca20e/watchdog-6.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:76aae96b00ae814b181bb25b1b98076d5fc84e8a53cd8885a318b42b6d3a5134", size = 88451, upload-time = "2024-11-01T14:06:45.084Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/c4/225c87bae08c8b9ec99030cd48ae9c4eca050a59bf5c2255853e18c87b50/watchdog-6.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a175f755fc2279e0b7312c0035d52e27211a5bc39719dd529625b1930917345b", size = 89057, upload-time = "2024-11-01T14:06:47.324Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/c7/ca4bf3e518cb57a686b2feb4f55a1892fd9a3dd13f470fca14e00f80ea36/watchdog-6.0.0-py3-none-manylinux2014_aarch64.whl", hash = "sha256:7607498efa04a3542ae3e05e64da8202e58159aa1fa4acddf7678d34a35d4f13", size = 79079, upload-time = "2024-11-01T14:06:59.472Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/51/d46dc9332f9a647593c947b4b88e2381c8dfc0942d15b8edc0310fa4abb1/watchdog-6.0.0-py3-none-manylinux2014_armv7l.whl", hash = "sha256:9041567ee8953024c83343288ccc458fd0a2d811d6a0fd68c4c22609e3490379", size = 79078, upload-time = "2024-11-01T14:07:01.431Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/57/04edbf5e169cd318d5f07b4766fee38e825d64b6913ca157ca32d1a42267/watchdog-6.0.0-py3-none-manylinux2014_i686.whl", hash = "sha256:82dc3e3143c7e38ec49d61af98d6558288c415eac98486a5c581726e0737c00e", size = 79076, upload-time = "2024-11-01T14:07:02.568Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/cc/da8422b300e13cb187d2203f20b9253e91058aaf7db65b74142013478e66/watchdog-6.0.0-py3-none-manylinux2014_ppc64.whl", hash = "sha256:212ac9b8bf1161dc91bd09c048048a95ca3a4c4f5e5d4a7d1b1a7d5752a7f96f", size = 79077, upload-time = "2024-11-01T14:07:03.893Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/3b/b8964e04ae1a025c44ba8e4291f86e97fac443bca31de8bd98d3263d2fcf/watchdog-6.0.0-py3-none-manylinux2014_ppc64le.whl", hash = "sha256:e3df4cbb9a450c6d49318f6d14f4bbc80d763fa587ba46ec86f99f9e6876bb26", size = 79078, upload-time = "2024-11-01T14:07:05.189Z" },
+    { url = "https://files.pythonhosted.org/packages/62/ae/a696eb424bedff7407801c257d4b1afda455fe40821a2be430e173660e81/watchdog-6.0.0-py3-none-manylinux2014_s390x.whl", hash = "sha256:2cce7cfc2008eb51feb6aab51251fd79b85d9894e98ba847408f662b3395ca3c", size = 79077, upload-time = "2024-11-01T14:07:06.376Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/e8/dbf020b4d98251a9860752a094d09a65e1b436ad181faf929983f697048f/watchdog-6.0.0-py3-none-manylinux2014_x86_64.whl", hash = "sha256:20ffe5b202af80ab4266dcd3e91aae72bf2da48c0d33bdb15c66658e685e94e2", size = 79078, upload-time = "2024-11-01T14:07:07.547Z" },
+    { url = "https://files.pythonhosted.org/packages/07/f6/d0e5b343768e8bcb4cda79f0f2f55051bf26177ecd5651f84c07567461cf/watchdog-6.0.0-py3-none-win32.whl", hash = "sha256:07df1fdd701c5d4c8e55ef6cf55b8f0120fe1aef7ef39a1c6fc6bc2e606d517a", size = 79065, upload-time = "2024-11-01T14:07:09.525Z" },
+    { url = "https://files.pythonhosted.org/packages/db/d9/c495884c6e548fce18a8f40568ff120bc3a4b7b99813081c8ac0c936fa64/watchdog-6.0.0-py3-none-win_amd64.whl", hash = "sha256:cbafb470cf848d93b5d013e2ecb245d4aa1c8fd0504e863ccefa32445359d680", size = 79070, upload-time = "2024-11-01T14:07:10.686Z" },
+    { url = "https://files.pythonhosted.org/packages/33/e8/e40370e6d74ddba47f002a32919d91310d6074130fe4e17dabcafc15cbf1/watchdog-6.0.0-py3-none-win_ia64.whl", hash = "sha256:a1914259fa9e1454315171103c6a30961236f508b9b623eae470268bbcc6a22f", size = 79067, upload-time = "2024-11-01T14:07:11.845Z" },
+]
+
 [[package]]
 name = "wcwidth"
 version = "0.2.14"