diff --git a/docs/bugs.md b/docs/bugs.md
new file mode 100644
index 0000000..9fa2c35
--- /dev/null
+++ b/docs/bugs.md
@@ -0,0 +1,213 @@
+This is a solid, well-structured repo. The architecture matches the spec perfectly and most of the code is production-quality. Here's the full audit — bugs first, then improvements.
+
+***
+
+## 🔴 Bugs (Will Break at Runtime)
+
+### Bug 1 — `asyncio.run()` inside an already-running event loop crashes
+**File:** `pipelineprobe/connectors/postgres.py` line `get_stats_sync()`
+
+`asyncio.run()` throws `RuntimeError: This event loop is already running` if PipelineProbe is ever called from an async context (FastAPI, Jupyter, any async test runner). This is a latent crash waiting to happen.
+
+**Fix:** Replace the async/sync split entirely. `asyncpg` is overkill for a one-shot audit query. Use `psycopg2` synchronously:
+
+```python
+import logging
+from typing import Any, Dict, List
+
+import psycopg2
+import psycopg2.extras
+
+from pipelineprobe.config import WarehouseConfig
+
+logger = logging.getLogger(__name__)
+
+class PostgresConnector:
+ def __init__(self, config: WarehouseConfig):
+ self.config = config
+
+ def get_stats_sync(self) -> List[Dict[str, Any]]:
+ try:
+ conn = psycopg2.connect(self.config.dsn)
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute("""
+ SELECT
+ t.schemaname,
+ t.relname AS tablename,
+ t.n_live_tup AS row_count,
+ EXISTS (
+ SELECT 1 FROM information_schema.columns c
+ WHERE c.table_schema = t.schemaname
+ AND c.table_name = t.relname
+ AND c.column_name IN ('updated_at', 'created_at')
+ ) AS has_timestamps
+ FROM pg_stat_user_tables t
+ ORDER BY t.n_live_tup DESC
+ LIMIT 50
+ """)
+ return [dict(r) for r in cur.fetchall()]
+ except Exception as e:
+ logger.error("Error connecting to Postgres: %s", e)
+ return []
+ finally:
+ if conn:
+ conn.close()
+```
+
+Also update `pyproject.toml` — remove `asyncpg`, add `psycopg2-binary`.
+
+***
+
+### Bug 2 — `config.py`: `AirflowConfig` field is `base_url` but `init` command writes `url`
+**File:** `pipelineprobe/config.py` line 8 vs `cli.py` `init` command
+
+`AirflowConfig` defines `base_url` as the field name, but the `init` command generates a YAML stub with key `url`. When a user runs `pipelineprobe init` then `pipelineprobe audit`, the `base_url` field gets its default (`http://localhost:8080`) instead of their value because the YAML key doesn't match.
+
+**Fix in `cli.py` init command** — change the generated YAML:
+```yaml
+orchestrator:
+ base_url: "http://localhost:8080" # ← was "url:"
+ username: "admin"
+```
+
+***
+
+### Bug 3 — `cli.py`: `postgres_tables` hardcoded context key doesn't work for BigQuery/Snowflake rules
+**File:** `pipelineprobe/cli.py` line 66
+
+```python
+"postgres_tables": warehouse_tables, # Backwards compatible context key
+```
+
+The comment says "backwards compatible" but `postgres_rules.py` reads from `postgres_tables` key while BigQuery and Snowflake also return their data into the same key. This is fine for now — but the `postgres_rules.py` rule will fire on BigQuery/Snowflake data with misleading Postgres-specific recommendations (e.g. "consider partitioning" using Postgres terminology on a BigQuery table).
+
+**Fix:** Use a neutral key and pass warehouse type to the context:
+```python
+context = {
+ "airflow_dags": airflow_dags,
+ "airflow_tasks": airflow_tasks,
+ "dbt_models": dbt_models,
+ "warehouse_tables": warehouse_tables, # ← neutral key
+ "warehouse_type": cfg.warehouse.type, # ← pass type for rule conditions
+}
+```
+Update `postgres_rules.py` to read `warehouse_tables` and guard with `if context.get("warehouse_type") == "postgres"`.
+
+***
+
+### Bug 4 — `dbt.py`: manifest path is double-joined
+**File:** `pipelineprobe/connectors/dbt.py` lines 16–17
+
+```python
+manifest_path = project_dir / self.config.manifest_path
+```
+
+`DbtConfig` defaults:
+```python
+project_dir: str = "./analytics"
+manifest_path: str = "target/manifest.json"
+```
+
+So the resolved path becomes `./analytics/target/manifest.json`. But many users set `project_dir` to the dbt project root AND `manifest_path` to a full relative path from CWD like `./analytics/target/manifest.json`. This causes a double-join. The config field name `manifest_path` implies it's already a full path, not relative to `project_dir`.
+
+**Fix:** Make `manifest_path` and `run_results_path` absolute-or-CWD-relative, not relative to `project_dir`:
+```python
+manifest_path = Path(self.config.manifest_path)
+run_results_path = Path(self.config.run_results_path)
+```
+Update defaults in `DbtConfig` to `"./analytics/target/manifest.json"` to match the original intent, and update the generated `init` YAML accordingly.
+
+***
+
+### Bug 5 — `airflow_rules.py`: `check_stale_dags` uses `.days` which truncates — misses sub-day staleness
+**File:** `pipelineprobe/rules/airflow_rules.py` line 93
+
+```python
+days_since = (now - end_time_aware).days
+```
+
+`timedelta.days` is the integer day component only — it **does not round**. A DAG that last succeeded 6 days and 23 hours ago returns `.days == 6`, not 7, so it never triggers the `> 7` check. Use `total_seconds()` instead:
+
+```python
+days_since = (now - end_time_aware).total_seconds() / 86400
+if days_since > stale_threshold_days:
+```
+
+***
+
+## 🟡 Issues That Will Cause Confusion
+
+### Issue 1 — `pyproject.toml` likely missing `asyncpg` / `python-dateutil` / `snowflake-connector-python` as explicit deps
+The connectors import `asyncpg`, `dateutil`, and `snowflake.connector` but without seeing `pyproject.toml` contents fully, these are often missed. Verify the `[project.dependencies]` section includes:
+```toml
+dependencies = [
+ "typer>=0.9",
+ "httpx>=0.27",
+ "pydantic>=2.0",
+ "pydantic-settings>=2.0",
+ "pyyaml>=6.0",
+ "jinja2>=3.1",
+ "python-dateutil>=2.8",
+ "psycopg2-binary>=2.9", # after fixing Bug 1
+ "snowflake-connector-python>=3.0",
+ "google-cloud-bigquery>=3.0",
+]
+```
+
+***
+
+### Issue 2 — `cli.py`: `fail_on_critical` default is `5` in config but `0` in `init` YAML
+`ReportConfig` defaults `fail_on_critical: int = 5` but the `init` command generates `fail_on_critical: 0`. A user who runs `init`, gets the YAML, and doesn't edit it will find the audit **always fails on any critical issue**. The defaults should be consistent — pick `5` in both places.
+
+***
+
+### Issue 3 — `renderer.py`: `report.html` template missing — `TemplateNotFound` at runtime
+The `renderer.py` loads `report.html` from `pipelineprobe/templates/` but the `templates/` directory exists — if `report.html` is empty or missing, every audit run fails at the last step with a Jinja2 `TemplateNotFound` error. Verify the template file exists and has actual HTML. If it's a stub, even a minimal one like this is enough to unblock users:
+
+```html
+
+
+PipelineProbe Report
+
+ Score: {{ summary.score }}/100
+ Critical: {{ summary.critical_count }} | Warnings: {{ summary.warning_count }}
+ {% for issue in issues %}
+
+
{{ issue.summary }}
+
{{ issue.recommendation }}
+