governor-audit 0.0.1__tar.gz

governor_audit-0.0.1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: governor-audit
+Version: 0.0.1
+Summary: Read-only BigQuery cost-audit tool — single-user, gcloud ADC only, no GCS / no GitHub / no dbt installation.
+Author-email: Simple Machines <hello@simplemachines.co.nz>
+Maintainer-email: Simple Machines <hello@simplemachines.co.nz>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/simple-machines/governor
+Project-URL: Repository, https://github.com/simple-machines/governor
+Project-URL: Issues, https://github.com/simple-machines/governor/issues
+Project-URL: Documentation, https://github.com/simple-machines/governor/tree/main/specs/141-production-audit
+Project-URL: Changelog, https://github.com/simple-machines/governor/releases?q=audit-
+Keywords: bigquery,cost-optimization,dbt,audit,data-engineering,warehouse
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: governor-core==0.7.29
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: uvicorn>=0.30.6
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: google-cloud-bigquery>=3.20.0
+Requires-Dist: google-auth>=2.30.0
+
+# governor-audit
+
+Read-only BigQuery cost-audit tool for single-user production audits.
+
+> **Posture**: Single-user. gcloud ADC only. No GCS, no GitHub, no service-account JSON, no dbt installation, no shadow validation. The only thing it talks to over the network is BigQuery — and only to query `INFORMATION_SCHEMA.JOBS_BY_PROJECT`.
+
+## When to use this vs. the other governor packages
+
+- **`governor-audit`** (this package): you have read access to a prod BigQuery project. You want a fast cost audit + detection findings without touching the dbt source code, running dbt, or setting up cloud infrastructure.
+- **`governor-cli`**: you have the dbt project source on your machine and want to run dbt + propose fixes locally.
+- **`governor-web`**: you operate the platform; you want shared infrastructure (GCS-backed manifests, GitHub PRs, scheduled syncs) for a team.
+
+## What you get
+
+- **Dashboard** — Total / Build / Consumption / Flagged spend KPI cards, top-20 spenders bar chart, paginated cost-drivers table with click-to-sort columns and a per-row issue count.
+- **Detection engine** — every enabled rule from `governor_core.opportunities.rules` (partition_pruning, shuffle_spill, slot_contention, join_explosion, dead_cte, dead_column, dead_window_expression, redundant_order_by, unused_aggregation_output, unused_join) runs on each cached job; opportunities feed the Active Issues pane.
+- **Job detail** — full SQL viewer with expand / copy buttons, metadata panes, and the list of detection-rule findings for that job.
+- **Settings** — Account (gcloud principal + ADC probe), Appearance (light / dark / system), AI / LLM (provider, model, params — reviewer code lands in v0.0.2), Detection Rules (per-rule enable/disable).
+- **Reset cache** — wipe everything `INFORMATION_SCHEMA` collected without losing your config.
+
+## Quickstart
+
+```sh
+gcloud auth application-default login
+uv tool install governor-audit
+governor-audit init --project prod-warehouse-123 --region us
+governor-audit scan --days 30
+governor-audit start
+# open http://localhost:8765
+```
+
+The web UI exposes the same actions as the CLI plus the dashboard / settings views. After the first `init` you can do everything from the browser.
+
+See [the spec's quickstart](../../specs/141-production-audit/quickstart.md) for the full first-audit walkthrough.
+
+## Architecture
+
+- **Storage**: SQLite at `~/.governor-audit/state.db` via `governor_core.db.sqlite_compat`.
+- **Auth**: gcloud Application Default Credentials only — `google.auth.default()`. No service-account JSON. No browser OAuth.
+- **Workload classification**: manifest-free heuristic — dbt-originated CTAS / MERGE / INSERT / UPDATE / DELETE → `build`; non-dbt SELECT → `consumption`; ambiguous → `other`. Driven by the `/* {"app": "dbt"` comment-prefix the dbt-bigquery adapter prepends.
+- **Loopback only**: the FastAPI app rejects any request whose `Host:` header isn't a localhost variant. Not a public service.
+
+See [spec 141](../../specs/141-production-audit/) for the complete spec set:
+
+- [spec.md](../../specs/141-production-audit/spec.md) — feature spec
+- [plan.md](../../specs/141-production-audit/plan.md) — implementation plan
+- [data-model.md](../../specs/141-production-audit/data-model.md) — schemas
+- [contracts/cli.md](../../specs/141-production-audit/contracts/cli.md) — CLI contract
+- [contracts/web-routes.md](../../specs/141-production-audit/contracts/web-routes.md) — web routes contract
+
+## Versioning
+
+`governor-audit` ships on its own version track, decoupled from the cloud bundle (`governor-core` / `governor-web` / `governor-cli` / `governor-bq`). Audit `v0.0.1` and cloud `v0.7.x` coexist. See [scripts/release-audit.sh](../../scripts/release-audit.sh) for the release flow.
+
+## License
+
+MIT.

governor_audit-0.0.1/README.md

@@ -0,0 +1,57 @@
+# governor-audit
+
+Read-only BigQuery cost-audit tool for single-user production audits.
+
+> **Posture**: Single-user. gcloud ADC only. No GCS, no GitHub, no service-account JSON, no dbt installation, no shadow validation. The only thing it talks to over the network is BigQuery — and only to query `INFORMATION_SCHEMA.JOBS_BY_PROJECT`.
+
+## When to use this vs. the other governor packages
+
+- **`governor-audit`** (this package): you have read access to a prod BigQuery project. You want a fast cost audit + detection findings without touching the dbt source code, running dbt, or setting up cloud infrastructure.
+- **`governor-cli`**: you have the dbt project source on your machine and want to run dbt + propose fixes locally.
+- **`governor-web`**: you operate the platform; you want shared infrastructure (GCS-backed manifests, GitHub PRs, scheduled syncs) for a team.
+
+## What you get
+
+- **Dashboard** — Total / Build / Consumption / Flagged spend KPI cards, top-20 spenders bar chart, paginated cost-drivers table with click-to-sort columns and a per-row issue count.
+- **Detection engine** — every enabled rule from `governor_core.opportunities.rules` (partition_pruning, shuffle_spill, slot_contention, join_explosion, dead_cte, dead_column, dead_window_expression, redundant_order_by, unused_aggregation_output, unused_join) runs on each cached job; opportunities feed the Active Issues pane.
+- **Job detail** — full SQL viewer with expand / copy buttons, metadata panes, and the list of detection-rule findings for that job.
+- **Settings** — Account (gcloud principal + ADC probe), Appearance (light / dark / system), AI / LLM (provider, model, params — reviewer code lands in v0.0.2), Detection Rules (per-rule enable/disable).
+- **Reset cache** — wipe everything `INFORMATION_SCHEMA` collected without losing your config.
+
+## Quickstart
+
+```sh
+gcloud auth application-default login
+uv tool install governor-audit
+governor-audit init --project prod-warehouse-123 --region us
+governor-audit scan --days 30
+governor-audit start
+# open http://localhost:8765
+```
+
+The web UI exposes the same actions as the CLI plus the dashboard / settings views. After the first `init` you can do everything from the browser.
+
+See [the spec's quickstart](../../specs/141-production-audit/quickstart.md) for the full first-audit walkthrough.
+
+## Architecture
+
+- **Storage**: SQLite at `~/.governor-audit/state.db` via `governor_core.db.sqlite_compat`.
+- **Auth**: gcloud Application Default Credentials only — `google.auth.default()`. No service-account JSON. No browser OAuth.
+- **Workload classification**: manifest-free heuristic — dbt-originated CTAS / MERGE / INSERT / UPDATE / DELETE → `build`; non-dbt SELECT → `consumption`; ambiguous → `other`. Driven by the `/* {"app": "dbt"` comment-prefix the dbt-bigquery adapter prepends.
+- **Loopback only**: the FastAPI app rejects any request whose `Host:` header isn't a localhost variant. Not a public service.
+
+See [spec 141](../../specs/141-production-audit/) for the complete spec set:
+
+- [spec.md](../../specs/141-production-audit/spec.md) — feature spec
+- [plan.md](../../specs/141-production-audit/plan.md) — implementation plan
+- [data-model.md](../../specs/141-production-audit/data-model.md) — schemas
+- [contracts/cli.md](../../specs/141-production-audit/contracts/cli.md) — CLI contract
+- [contracts/web-routes.md](../../specs/141-production-audit/contracts/web-routes.md) — web routes contract
+
+## Versioning
+
+`governor-audit` ships on its own version track, decoupled from the cloud bundle (`governor-core` / `governor-web` / `governor-cli` / `governor-bq`). Audit `v0.0.1` and cloud `v0.7.x` coexist. See [scripts/release-audit.sh](../../scripts/release-audit.sh) for the release flow.
+
+## License
+
+MIT.

governor_audit-0.0.1/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["governor_audit*"]
+
+[tool.setuptools.package-data]
+governor_audit = [
+  "web/templates/*.html",
+  "web/templates/**/*.html",
+  "web/static/**/*",
+]
+
+[project]
+name = "governor-audit"
+version = "0.0.1"
+description = "Read-only BigQuery cost-audit tool — single-user, gcloud ADC only, no GCS / no GitHub / no dbt installation."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+authors = [{name = "Simple Machines", email = "hello@simplemachines.co.nz"}]
+maintainers = [{name = "Simple Machines", email = "hello@simplemachines.co.nz"}]
+keywords = ["bigquery", "cost-optimization", "dbt", "audit", "data-engineering", "warehouse"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Environment :: Web Environment",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Database",
+  "Topic :: Office/Business :: Financial",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: System :: Monitoring",
+]
+
+# governor-core is a sibling package in this monorepo. Until it is
+# published to PyPI, end-user installs from PyPI need a `--find-links`
+# pointing at the GitHub release wheels — see scripts/release-audit.sh.
+# When governor-core lands on PyPI this pin Just Works for `pip install`.
+dependencies = [
+  "governor-core==0.7.29",
+  "typer>=0.12.0",
+  "rich>=13.0.0",
+  "fastapi>=0.115.0",
+  "jinja2>=3.1.0",
+  "uvicorn>=0.30.6",
+  "pydantic>=2.0.0",
+  "google-cloud-bigquery>=3.20.0",
+  "google-auth>=2.30.0",
+]
+
+[project.scripts]
+governor-audit = "governor_audit.cli.app:app"
+
+[project.urls]
+Homepage = "https://github.com/simple-machines/governor"
+Repository = "https://github.com/simple-machines/governor"
+Issues = "https://github.com/simple-machines/governor/issues"
+Documentation = "https://github.com/simple-machines/governor/tree/main/specs/141-production-audit"
+Changelog = "https://github.com/simple-machines/governor/releases?q=audit-"

governor_audit-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

governor_audit-0.0.1/src/governor_audit/__init__.py

@@ -0,0 +1,20 @@
+"""governor-audit — read-only production audit tool.
+
+Single-user CLI that audits a production dbt deployment using only
+``gcloud`` Application Default Credentials, a user-supplied GCP project
++ region, and a ``manifest.json`` uploaded from the user's dev
+environment. Queries production BigQuery ``INFORMATION_SCHEMA.JOBS``
+for historical job data, runs the existing ``governor-core`` detection
+rules, and surfaces findings with code-location pointers from the
+manifest.
+
+This package is read-only by design: no PR creation, no shadow
+validation, no LLM solution generation in v1. See spec 141 for the
+full posture.
+"""
+
+from __future__ import annotations
+
+from governor_audit.version import get_app_version
+
+__version__ = get_app_version()

governor_audit-0.0.1/src/governor_audit/auth/adc.py

@@ -0,0 +1,158 @@
+"""gcloud Application Default Credentials probe.
+
+Single read-only check that proves the user can read INFORMATION_SCHEMA
+in the configured project + region. Returns a typed result so the
+caller (init / doctor / scan) can render the right message.
+
+This module never logs the credential bytes — only the principal email
+(``client_email``-equivalent for service accounts; user email for ADC
+sessions) and a sanitised version of any BigQuery error.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class ProbeStatus(str, Enum):
+    OK = "ok"
+    ADC_MISSING = "adc_missing"  # No credentials at all (DefaultCredentialsError)
+    ADC_INVALID = "adc_invalid"  # Credentials present but rejected (RefreshError)
+    IAM_INSUFFICIENT = "iam_insufficient"  # 403 from BigQuery — needs role grant
+    REGION_UNKNOWN = "region_unknown"  # 404 region/dataset not found
+    UNKNOWN = "unknown"  # Some other Google API error — message included verbatim
+
+
+@dataclass(frozen=True)
+class ProbeResult:
+    status: ProbeStatus
+    principal: str | None  # Email of the active gcloud principal, when known.
+    message: str  # Human-readable, safe to log/print. No credentials.
+
+    @property
+    def ok(self) -> bool:
+        return self.status is ProbeStatus.OK
+
+
+_REQUIRED_IAM_HINT = (
+    "Required: roles/bigquery.resourceViewer + roles/bigquery.jobUser "
+    "on the project (or a custom role granting bigquery.jobs.list and "
+    "bigquery.tables.get on INFORMATION_SCHEMA.SCHEMATA)."
+)
+
+_GCLOUD_LOGIN_HINT = "Run: gcloud auth application-default login"
+
+
+def _principal_email_from_credentials(creds: Any) -> str | None:
+    """Try to extract a usable identity from the credentials object.
+    Returns ``None`` if we can't (no exception — best-effort)."""
+    return (
+        getattr(creds, "service_account_email", None)
+        or getattr(creds, "_service_account_email", None)
+        or getattr(creds, "_target_principal", None)
+        or getattr(creds, "_quota_project_id", None)
+    )
+
+
+def probe_adc(project_id: str, region: str) -> ProbeResult:
+    """Run one read-only INFORMATION_SCHEMA query as a permission check.
+
+    The query is intentionally minimal:
+
+        SELECT 1 FROM `<project>.region-<region>`.INFORMATION_SCHEMA.SCHEMATA
+        LIMIT 1
+
+    It's billed as a metadata query (typically free or fractions of a
+    cent). Any successful response means the user can read the project
+    in the requested region.
+    """
+    # Imports are lazy so the module can be imported in environments
+    # that don't have google-cloud-bigquery installed (e.g. running the
+    # config schema tests in isolation).
+    try:
+        from google.api_core import exceptions as gcp_exc
+        from google.auth import default as google_auth_default
+        from google.auth.exceptions import (
+            DefaultCredentialsError,
+            RefreshError,
+        )
+        from google.cloud import bigquery
+    except ImportError as exc:
+        return ProbeResult(
+            status=ProbeStatus.UNKNOWN,
+            principal=None,
+            message=f"google-cloud-bigquery not importable: {exc}",
+        )
+
+    # Step 1 — find ADC at all.
+    try:
+        credentials, _ = google_auth_default(
+            scopes=["https://www.googleapis.com/auth/cloud-platform"],
+        )
+    except DefaultCredentialsError as exc:
+        return ProbeResult(
+            status=ProbeStatus.ADC_MISSING,
+            principal=None,
+            message=f"No Application Default Credentials found. {_GCLOUD_LOGIN_HINT}. ({exc})",
+        )
+
+    principal = _principal_email_from_credentials(credentials)
+
+    # Step 2 — issue the probe query.
+    try:
+        client = bigquery.Client(project=project_id, credentials=credentials)
+        query = (
+            f"SELECT 1 FROM `{project_id}.region-{region}`.INFORMATION_SCHEMA.SCHEMATA "
+            "LIMIT 1"
+        )
+        job = client.query(query)
+        # Materialise to force the API call; we don't care about the rows.
+        list(job.result(max_results=1))
+    except RefreshError as exc:
+        return ProbeResult(
+            status=ProbeStatus.ADC_INVALID,
+            principal=principal,
+            message=(
+                f"Credentials present but rejected by Google. "
+                f"{_GCLOUD_LOGIN_HINT}. ({exc})"
+            ),
+        )
+    except gcp_exc.Forbidden as exc:
+        return ProbeResult(
+            status=ProbeStatus.IAM_INSUFFICIENT,
+            principal=principal,
+            message=(
+                f"Permission denied on project {project_id!r}. "
+                f"{_REQUIRED_IAM_HINT} ({exc.reason or exc})"
+            ),
+        )
+    except gcp_exc.NotFound as exc:
+        return ProbeResult(
+            status=ProbeStatus.REGION_UNKNOWN,
+            principal=principal,
+            message=(
+                f"Region {region!r} or project {project_id!r} not found by "
+                f"BigQuery. Check the region matches a real BigQuery location "
+                f"(e.g. 'us', 'australia-southeast1'). ({exc})"
+            ),
+        )
+    except gcp_exc.GoogleAPIError as exc:
+        return ProbeResult(
+            status=ProbeStatus.UNKNOWN,
+            principal=principal,
+            message=f"BigQuery API error during ADC probe: {exc}",
+        )
+
+    return ProbeResult(
+        status=ProbeStatus.OK,
+        principal=principal,
+        message=(
+            f"OK — authenticated{' as ' + principal if principal else ''}, "
+            f"INFORMATION_SCHEMA reachable in {project_id}/{region}."
+        ),
+    )
+
+
+__all__ = ["ProbeStatus", "ProbeResult", "probe_adc"]

governor_audit-0.0.1/src/governor_audit/cli/app.py

@@ -0,0 +1,55 @@
+"""Top-level Typer app for the ``governor-audit`` CLI.
+
+Exposed via the ``governor-audit`` entry point declared in pyproject.toml.
+Each command lives in its own module under ``cli/commands/`` so the app
+file stays small and the per-command logic can be exercised in isolation.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from governor_audit.cli.commands import init as _init
+from governor_audit.cli.commands import scan as _scan
+from governor_audit.cli.commands import status as _status
+from governor_audit.version import get_app_version
+
+app = typer.Typer(
+    name="governor-audit",
+    no_args_is_help=True,
+    add_completion=False,
+    help=(
+        "Read-only BigQuery + dbt cost-audit tool. Single-user, gcloud "
+        "ADC only, no GCS / no GitHub / no dbt. See `governor-audit init --help` "
+        "to get started."
+    ),
+)
+
+app.command(name="init")(_init.init_command)
+app.command(name="scan")(_scan.scan_command)
+app.command(name="status")(_status.status_command)
+
+
+@app.callback(invoke_without_command=True)
+def _root(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Print the package version and exit.",
+        is_eager=True,
+    ),
+) -> None:
+    if version:
+        Console().print(f"governor-audit {get_app_version()}")
+        raise typer.Exit(0)
+    if ctx.invoked_subcommand is None:
+        # No subcommand and no --version → show help and exit 0.
+        Console().print(ctx.get_help())
+        raise typer.Exit(0)
+
+
+if __name__ == "__main__":
+    app()

governor_audit-0.0.1/src/governor_audit/cli/commands/init.py

@@ -0,0 +1,165 @@
+"""``governor-audit init`` — configure the audit target.
+
+Per [contracts/cli.md § init](../../../../specs/141-production-audit/contracts/cli.md#init).
+Argument names, exit codes, and message format are part of the
+user-facing contract.
+
+**v2 change**: no ``--manifest`` argument. The package never reads a
+manifest. ``--dbt-only-default`` added so the user can persist their
+preferred default for the per-scan ``--dbt-only`` flag.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from governor_audit.auth.adc import ProbeStatus, probe_adc
+from governor_audit.config.loader import (
+    ConfigNotFoundError,
+    load_config,
+    save_config,
+)
+from governor_audit.config.schema import (
+    DEFAULT_LOOKBACK_DAYS,
+    DEFAULT_MAX_SCAN_BYTES,
+    DEFAULT_PORT,
+    AuditConfig,
+    ScanDefaults,
+    WebUIConfig,
+)
+
+EXIT_OK = 0
+EXIT_GENERIC = 1
+EXIT_BAD_ARGS = 2
+EXIT_ADC_MISSING = 3
+EXIT_CONFIG_CONFLICT = 4
+EXIT_IAM_INSUFFICIENT = 6
+
+
+def init_command(
+    project: Annotated[
+        str,
+        typer.Option(
+            "--project", help="GCP project ID being audited.", show_default=False
+        ),
+    ],
+    region: Annotated[
+        str,
+        typer.Option(
+            "--region",
+            help="BigQuery region (e.g. 'us', 'australia-southeast1').",
+            show_default=False,
+        ),
+    ],
+    port: Annotated[
+        int,
+        typer.Option("--port", help="Local web UI port.", min=1024, max=65535),
+    ] = DEFAULT_PORT,
+    max_scan_bytes: Annotated[
+        int,
+        typer.Option(
+            "--max-scan-bytes",
+            help="BigQuery dry-run cost cap (bytes-billed). Default 10 GB.",
+            min=1_000_000,
+        ),
+    ] = DEFAULT_MAX_SCAN_BYTES,
+    lookback_days: Annotated[
+        int,
+        typer.Option(
+            "--lookback-days",
+            help="Default --days for `scan` when not specified.",
+            min=1,
+            max=365,
+        ),
+    ] = DEFAULT_LOOKBACK_DAYS,
+    dbt_only_default: Annotated[
+        bool,
+        typer.Option(
+            "--dbt-only-default/--all-jobs-default",
+            help=(
+                "Default value of --dbt-only for `scan` when not passed. "
+                "When True, scans narrow to queries starting with "
+                "/* {\"app\": \"dbt\". Per-scan override always wins."
+            ),
+        ),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force/--no-force",
+            help="Overwrite an existing config when fields conflict.",
+        ),
+    ] = False,
+) -> None:
+    """Configure governor-audit against a project / region."""
+    console = Console()
+
+    # Step 1 — refuse to silently overwrite a conflicting config.
+    if not force:
+        try:
+            existing = load_config()
+        except ConfigNotFoundError:
+            existing = None
+        if existing is not None:
+            conflicts: list[str] = []
+            if existing.gcp_project_id != project:
+                conflicts.append(
+                    f"  gcp_project_id: {existing.gcp_project_id!r} → {project!r}"
+                )
+            if existing.bigquery_region.lower() != region.lower():
+                conflicts.append(
+                    f"  bigquery_region: {existing.bigquery_region!r} → {region!r}"
+                )
+            if conflicts:
+                console.print(
+                    "[bold red]Existing config conflicts with the new arguments:[/]\n"
+                    + "\n".join(conflicts)
+                    + "\n\nRe-run with --force to overwrite, or use "
+                    "`governor-audit config <key> <value>` for a single field."
+                )
+                raise typer.Exit(EXIT_CONFIG_CONFLICT)
+
+    # Step 2 — probe ADC against the requested project + region.
+    console.print(f"Probing ADC against {project} / {region}…")
+    probe = probe_adc(project, region)
+    if probe.status is ProbeStatus.ADC_MISSING:
+        console.print(f"[bold red]✗[/] {probe.message}")
+        raise typer.Exit(EXIT_ADC_MISSING)
+    if probe.status is ProbeStatus.IAM_INSUFFICIENT:
+        console.print(f"[bold red]✗[/] {probe.message}")
+        raise typer.Exit(EXIT_IAM_INSUFFICIENT)
+    if probe.status is ProbeStatus.REGION_UNKNOWN:
+        console.print(f"[bold red]✗[/] {probe.message}")
+        raise typer.Exit(EXIT_BAD_ARGS)
+    if not probe.ok:
+        console.print(f"[bold red]✗[/] ADC probe failed: {probe.message}")
+        raise typer.Exit(EXIT_GENERIC)
+    console.print(
+        f"[green]✓[/] ADC verified — authenticated"
+        f"{' as ' + probe.principal if probe.principal else ''}"
+    )
+
+    # Step 3 — write config.
+    config = AuditConfig.model_validate({
+        "gcp_project_id": project,
+        "bigquery_region": region,
+        "scan_defaults": ScanDefaults(
+            lookback_days=lookback_days,
+            max_scan_bytes=max_scan_bytes,
+            dbt_only=dbt_only_default,
+        ),
+        "web_ui": WebUIConfig(port=port),
+    })
+    saved_path = save_config(config)
+    console.print(f"[green]✓[/] Config written to {saved_path}\n")
+
+    # Step 4 — friendly hint.
+    console.print("Next: run a scan")
+    if dbt_only_default:
+        console.print("  [cyan]governor-audit scan[/]  [dim](dbt-only by default)[/]")
+    else:
+        console.print("  [cyan]governor-audit scan[/]")
+        console.print("  [cyan]governor-audit scan --dbt-only[/]  [dim](narrow to dbt-originated jobs)[/]")