willowvibe · harishconti · Mar 15, 2026 · Mar 15, 2026
diff --git a/README.md b/README.md
@@ -47,6 +47,14 @@ pipelineprobe audit --config pipelineprobe.yml
 
 Reports are written to `./reports/` by default.
 
+### ⏱️ 5-Minute Quickstart
+
+Want to see it in action without a local stack? Try our [Quickstart Example](examples/quickstart/README.md):
+```bash
+cd examples/quickstart
+docker compose up --build
+```
+
 ---
 
 ## ⚙️ Configuration
@@ -83,6 +91,15 @@ report:
 | `--config` | Path to config YAML (default: `pipelineprobe.yml`) |
 | `--format` | Override output format: `html`, `json`, or `both` |
 | `--fail-on-critical` | Override the critical issue threshold for CI exits |
+| `--version` | Show version and exit |
+
+### CLI Commands
+
+| Command | Description |
+|---|---|
+| `init` | Initialize a default `pipelineprobe.yml` |
+| `audit` | Run the full audit pipeline |
+| `doctor` | Validate connectivity to source systems |
 
 ---
 
@@ -98,6 +115,31 @@ report:
 
 ---
 
+## 🔄 Standard Workflows
+
+### 1. Local Audit (Internal Teams)
+Identify issues before they hit production. Run `pipelineprobe audit` locally or manually on a dev machine to verify current infra state.
+
+### 2. CI Quality Gate
+Fail your build when critical issues surface. Use the `--fail-on-critical 0` flag to enforce strict standards. See [CI Guide](docs/ci-integration.md).
+
+### 3. Consulting / One-off Audits
+Perfect for external auditors or consultants. Connect to a client's Airflow/Postgres once, run the audit, and provide the polished HTML report as a deliverable.
+
+---
+
+## 🆚 Comparison
+
+How is PipelineProbe different from full observability platforms?
+
+| Feature | Monitoring Tools (Datadog, Monte Carlo) | Quality Libraries (Soda, GE) | **PipelineProbe** |
+|---|---|---|---|
+| **Focus** | Continuous monitoring & alerting | Row-level data validation | Infrastructure & config audit |
+| **Effort** | High (setup agents/SDKs) | Medium (write YAML expectations) | **Zero (read-only API/metastore)** |
+| **Best For** | On-call engineers | Data engineers | **Consultants / Team Leads** |
+
+---
+
 ## 🤖 CI/CD Integration
 
 PipelineProbe can automatically fail your CI pipeline when critical issues exceed your threshold. See [docs/ci-integration.md](docs/ci-integration.md) for GitHub Actions and GitLab CI examples.
@@ -122,6 +164,14 @@ PipelineProbe can automatically fail your CI pipeline when critical issues excee
 
 ---
 
+## 🗺️ Roadmap
+
+- [ ] **v0.2.0**: Prefect and Dagster connectors.
+- [ ] **v0.3.0**: Basic cost insights (scanned bytes for BQ/Snowflake).
+- [ ] **v1.0.0**: Comprehensive data lineage support.
+
+---
+
 ## 🤝 Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get started.

diff --git a/docs/bugs.md b/docs/bugs.md
diff --git a/docs/bugs_improvements.md b/docs/bugs_improvements.md
@@ -0,0 +1,81 @@
+Right now PipelineProbe is structurally solid and safe to run; the next step is to make it “drop‑in usable” with great UX and examples rather than more core code changes.  
+
+## 1. Make setup truly plug‑and‑play
+
+1. Add a minimal “quickstart” example project:
+   - Tiny docker‑compose with: Airflow + Postgres + a toy dbt project + PipelineProbe container.
+   - One command: `docker compose up` and a README section: “Run your first audit in 5 minutes”.  
+   - This is what converts visitors into actual users; all successful CLI tools do this. [dev](https://dev.to/wesen/14-great-tips-to-make-amazing-cli-applications-3gp3)
+
+2. Harden config UX:
+   - Document all CLI flags and YAML fields in README (table: field, type, default, env override).  
+   - In `--help`, add 2–3 concrete example invocations (local, CI, different warehouses). [fuchsia](https://fuchsia.dev/fuchsia-src/development/api/cli_help)
+
+## 2. Document the “golden workflows”
+
+Write 3 short “How to use” flows in README, with copy‑paste commands:
+
+1. Local check on existing stack:
+   - `pip install pipelineprobe`  
+   - `pipelineprobe init`  
+   - Edit YAML with Airflow URL, dbt paths, Postgres DSN.  
+   - `pipelineprobe audit --format html` → open report.
+
+2. CI usage (GitHub Actions):
+   - Full example workflow that runs `pipelineprobe audit` on schedule and uploads HTML as an artifact.
+   - Show how `fail_on_critical` gates merges.
+
+3. Consulting / one‑off audit:
+   - “Clone client repo / connect to their Airflow, run, send them the HTML report + your notes.”  
+   - This positions it as a billable tool for you, not just OSS.
+
+These should match the core journeys described in good CLI design docs (usage + examples, not just API). [fuchsia](https://fuchsia.dev/fuchsia-src/development/api/cli_help)
+
+## 3. Tighten positioning vs other tools
+
+In README, add one short section “How PipelineProbe is different” referencing common open‑source data‑quality / observability tools (Great Expectations, Soda, dbt tests) as context. [decube](https://www.decube.io/post/why-apache-airflow-is-not-the-best-tool-for-data-quality-checks)
+
+Small table:
+
+- Column: “Tool”, “What it focuses on”, “Where PipelineProbe fits”.
+- Emphasise: “Point‑in‑time infra audit on top of Airflow + dbt + warehouse; read‑only, zero code change”. [willowvibe-web.vercel](https://willowvibe-web.vercel.app)
+
+This makes it clear you’re not competing directly with full observability stacks, but giving a quick audit lens.
+
+## 4. Improve CLI ergonomics
+
+A couple of small but high‑impact changes:
+
+1. Add `--version` and `pipelineprobe --help` output examples in README. [github](https://github.com/arturtamborski/cli-best-practices)
+2. Add a `pipelineprobe doctor` (future, can stub now):
+   - Validates connectivity to Airflow/dbt/warehouse and prints “what will be checked” without running full rules.
+3. Exit codes:
+   - Already: non‑zero when `critical_count > fail_on_critical`.  
+   - Document the mapping (0 OK, 1 threshold breached, maybe 2 config error) so teams can wire it into CI policies. [github](https://github.com/arturtamborski/cli-best-practices)
+
+## 5. Add “marketing‑grade” output for real usage
+
+Your HTML report now looks good; push it over the line as client‑ready:
+
+- Add one small section summarizing:
+  - “Top 3 actions to take this week” – choose the first 3 `critical`/`warning` issues sorted by severity and maybe category.  
+- Include environment metadata at the top:
+  - Airflow base URL (obfuscated host), warehouse type, and dbt target name (already in config; just pass into template).  
+- Add a “generated with `pipelineprobe vX.Y.Z`” footer, to reinforce the tool name.
+
+This turns the report into something you can screenshot in blog posts and client decks.
+
+## 6. Release hygiene
+
+Before calling it “practically usable” for strangers:
+
+1. Tag a `v0.1.0` GitHub release.
+2. Publish to PyPI so `pip install pipelineprobe` works.  
+3. Add a short “Roadmap” section: next items could be:
+   - Dagster/Prefect connector
+   - BigQuery/Snowflake‑specific warehouse rules
+   - Basic cost insights (top tables by scanned bytes where available). [atlan](https://atlan.com/open-source-data-quality-tools/)
+
+That gives users confidence it’s maintained and lets you talk about it publicly (LinkedIn, Reddit, r/dataengineering, etc.) with a clean story.
+
+If you want, next step we can design that quickstart `docker-compose.yml` plus a tiny dbt example so someone can get from zero to a working HTML report on their laptop with copy‑paste only.
diff --git a/examples/quickstart/README.md b/examples/quickstart/README.md
@@ -0,0 +1,28 @@
+# PipelineProbe Quickstart
+
+Run a full data pipeline audit in under 5 minutes using this example environment.
+
+## What's inside?
+- **Apache Airflow**: Pre-loaded with example DAGs.
+- **Postgres**: Serving as both the Airflow backend and a sample warehouse.
+- **PipelineProbe**: Automatically audits the stack and generates a report.
+
+## Prerequisites
+- Docker and Docker Compose installed.
+
+## Run the Audit
+
+1. **Start the environment**:
+   ```bash
+   docker compose up --build
+   ```
+
+2. **Wait for completion**:
+   PipelineProbe will wait for Airflow to start, run the audit, and then exit.
+
+3. **View the report**:
+   Once the `pipelineprobe` container finished, check the generated report in:
+   `./reports/pipelineprobe-report.html`
+
+## How it works
+The `docker-compose.yml` mounts this directory into the PipelineProbe container. It uses the pre-configured `pipelineprobe.yml` to connect to the internal Docker network services (`airflow:8080` and `postgres:5432`).
diff --git a/examples/quickstart/dbt_project/dbt_project.yml b/examples/quickstart/dbt_project/dbt_project.yml
diff --git a/examples/quickstart/docker-compose.yml b/examples/quickstart/docker-compose.yml
@@ -0,0 +1,41 @@
+version: '3.8'
+
+services:
+  postgres:
+    image: postgres:13
+    environment:
+      - POSTGRES_USER=airflow
+      - POSTGRES_PASSWORD=airflow
+      - POSTGRES_DB=airflow
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U airflow"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  airflow:
+    image: apache/airflow:2.7.1
+    environment:
+      - AIRFLOW__DATABASE__SQL_ALCHEMY_CONN=postgresql+psycopg2://airflow:airflow@postgres/airflow
+      - AIRFLOW__CORE__EXECUTOR=LocalExecutor
+      - AIRFLOW__CORE__LOAD_EXAMPLES=True
+      - AIRFLOW__API__AUTH_BACKENDS=airflow.api.auth.backend.basic_auth
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "8080:8080"
+    command: standalone
+
+  pipelineprobe:
+    build: ../../
+    volumes:
+      - .:/app/quickstart
+    environment:
+      - PIPELINEPROBE_AIRFLOW_PASSWORD=admin
+    depends_on:
+      airflow:
+        condition: service_started
+    command: audit --config /app/quickstart/pipelineprobe.yml --format both