pretensor 0.1.0a4__tar.gz → 0.2.0__tar.gz

pretensor-0.2.0/.github/ISSUE_TEMPLATE/schema_report.yml

@@ -0,0 +1,122 @@
+name: Schema doesn't match my database
+description: The knowledge graph is missing or misrepresenting tables, columns, keys, or relationships from your database.
+title: "schema: <what's missing or wrong>"
+labels:
+  - bug
+  - triage
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form when Pretensor indexed your database but the resulting graph is **wrong or incomplete** — a table or column is missing, a foreign key or inferred join is wrong, or MCP tools return schema context that doesn't match reality. For crashes and errors, use the bug report form instead.
+
+        **Security vulnerabilities must not be filed as public issues.** See [SECURITY.md](https://github.com/pretensor-ai/pretensor/blob/main/SECURITY.md) and report privately via [GitHub Security Advisories](https://github.com/pretensor-ai/pretensor/security/advisories/new).
+
+  - type: input
+    id: pretensor-version
+    attributes:
+      label: Pretensor version
+      description: Output of `pretensor --version`.
+      placeholder: "0.1.0aN"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: backend
+    attributes:
+      label: Database backend
+      options:
+        - PostgreSQL
+        - MySQL
+        - Snowflake
+        - BigQuery
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: backend-version
+    attributes:
+      label: Database version
+      description: e.g. `PostgreSQL 16.3`, `Snowflake 8.x`.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: problem-kind
+    attributes:
+      label: What is wrong in the graph?
+      options:
+        - Table missing
+        - Column missing
+        - Foreign key missing or wrong
+        - Inferred join / relationship wrong
+        - Wrong metadata (types, row counts, comments)
+        - Search / context returns the wrong schema objects
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Where do you see it?
+      description: The surface where the wrong output shows up.
+      options:
+        - CLI (`pretensor list` / `validate` / `export`)
+        - MCP tool response (`schema`, `context`, `traverse`, ...)
+        - Both
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What the database actually contains
+      description: |
+        The relevant schema as it exists in your database — a sanitized DDL
+        snippet (`CREATE TABLE ...`), an information-schema query result, or a
+        prose description. Redact table/column names if needed, but keep the
+        structure (keys, references) intact.
+      render: sql
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What Pretensor produced instead
+      description: The wrong or missing output — CLI output, MCP tool response JSON, or `pretensor export` fragment.
+      render: shell
+    validations:
+      required: true
+
+  - type: dropdown
+    id: reindex
+    attributes:
+      label: Does a fresh index reproduce it?
+      description: Whether the problem survives a full `pretensor index` (not just `reindex`) into a clean state directory.
+      options:
+        - Yes — reproduced after a fresh full index
+        - No — a fresh index fixed it
+        - Not tried
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Index/reindex logs or additional context
+      description: Output of the indexing run (add `--log-level debug` if possible). Redact secrets, DSNs, and personally identifiable data.
+      render: shell
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-submission checks
+      options:
+        - label: I searched existing issues and did not find a duplicate.
+          required: true
+        - label: I redacted credentials and sensitive schema details from all snippets.
+          required: true

{pretensor-0.1.0a4 → pretensor-0.2.0}/.github/workflows/open-publish-pr.yml

@@ -27,7 +27,12 @@ jobs:
         run: |
           set -euo pipefail
           version="${BRANCH#publish/}"
-          if gh pr view "$BRANCH" --repo "$REPO" --json number >/dev/null 2>&1; then
+          # Only an OPEN PR should count as "already handled": `gh pr view`
+          # on a branch name also resolves closed and merged PRs, so a
+          # re-pushed release branch whose earlier PR was merged would be
+          # skipped and the release would stall with no PR to review.
+          open_count=$(gh pr list --repo "$REPO" --head "$BRANCH" --state open --json number --jq 'length')
+          if [ "$open_count" -gt 0 ]; then
             echo "PR already open for ${BRANCH}."
           else
             gh pr create --repo "$REPO" --base main --head "$BRANCH" \

{pretensor-0.1.0a4 → pretensor-0.2.0}/.github/workflows/release.yml

@@ -133,6 +133,11 @@ jobs:
     # branch and integration there is PR-only by repo policy.
     name: Archive release-gate baselines (open PR)
     needs: [pypi]
+    # Explicit condition: the default success() check looks at the whole
+    # transitive needs chain, so the skipped TestPyPI job on final (non-pre)
+    # releases silently skipped this job even though pypi succeeded. That is
+    # how the v0.1.0 baseline was never archived.
+    if: always() && needs.pypi.result == 'success'
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -151,7 +156,10 @@ jobs:
           TAG: ${{ github.ref_name }}
           GH_TOKEN: ${{ github.token }}
         run: |
-          if git diff --quiet --exit-code tests/benchmark/results/; then
+          # The artifact lands as untracked files in a fresh checkout, so
+          # `git diff` never sees it — check the porcelain status (which
+          # includes untracked paths) instead.
+          if [ -z "$(git status --porcelain tests/benchmark/results/)" ]; then
             echo "No release-gate JSON to archive."
             exit 0
           fi
@@ -171,6 +179,9 @@ jobs:
   github-release:
     name: Create GitHub Release
     needs: [pypi, detect]
+    # Same transitive-skip fix as archive-results: run whenever the publish
+    # itself succeeded, even though TestPyPI was skipped for a final release.
+    if: always() && needs.pypi.result == 'success' && needs.detect.result == 'success'
     runs-on: ubuntu-latest
     permissions:
       contents: write

pretensor-0.2.0/CHANGELOG.md

@@ -0,0 +1,262 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [PEP 440](https://peps.python.org/pep-0440/) versioning.
+
+`0.1.0` is the first non-alpha release: `pip install pretensor` resolves
+to the latest non-prerelease version, and pre-releases published after it
+require `--pre`. Until `1.0.0` ships, the schema and CLI surface can
+still change between minor versions; this changelog tracks what moves
+between releases.
+
+## [0.2.0] - 2026-09-04
+
+### Added
+- The release gate honours a per-release
+  `tests/benchmark/results/<tag>/accepted-regressions.toml`. Each entry names
+  one dataset, level and metric, the value the release ships at, and a
+  reason. The value is a floor, not a waiver: a run that is worse than the
+  accepted value still blocks, and an entry that matches no regression is an
+  error. Deliberate precision/recall trade-offs no longer require bypassing
+  the gate.
+- `pretensor init`, an interactive first-run setup wizard.
+- `pretensor init`'s build-from-parts flow now supports mysql, snowflake,
+  and bigquery in addition to postgres, and a `--dialect` flag to force the
+  dialect instead of inferring it from the DSN.
+- `analyze --all` over repositories configured in config.yaml.
+- Sources can now hold a whole-DSN `url:` reference (e.g. `${DATABASE_URL}`)
+  instead of individual connection fields. `pretensor init` writes one of
+  these automatically when the indexed DSN came from a single environment
+  variable, so `config.yaml` stays safe to commit; `pretensor index --source`
+  and `--all` resolve the reference at run time.
+- Bare `pretensor` (no subcommand) prints a one-line hint to run
+  `pretensor init` when no connections are indexed yet, before showing help.
+- `pretensor init --client <key>` (repeatable, one of `claude-code`,
+  `claude-desktop`, `cursor`) to explicitly register with a detected MCP
+  client under `--yes` or a non-interactive run, since merely detecting a
+  client installed is not consent to write its config.
+- `pretensor init` now detects Claude Desktop on Windows as well
+  (`%APPDATA%\Claude\claude_desktop_config.json`).
+- `pretensor analyze` scans bare `.sql` files, not just SQL embedded in
+  Python source. Each `.sql` file is treated as one high-confidence
+  consumer, with table references unioned across all of its statements.
+
+### Security
+- `pretensor quickstart` now binds its throwaway Postgres to `127.0.0.1:55432`
+  instead of all interfaces. In 0.1.0 the sandbox listened on every interface
+  with the default `postgres:postgres` credentials, and Docker publishes ports
+  past host firewalls, so on a machine with a public IP it was reachable from
+  the internet. If you ran the 0.1.0 quickstart on a server, run
+  `pretensor quickstart --down`, upgrade, and start it again.
+
+### Changed
+- Same-name join inference is gated by how many tables share a column name
+  (`GraphConfig.same_name_max_tables`, default 8). Hub columns shared by more
+  than 8 tables (`customer_id` on every fact table, `date_id` on 40 tables)
+  no longer produce same-name candidates, same-name confidence decays with
+  how widely the name is shared, and a join path is only flagged ambiguous
+  when another path ties its cost. On warehouse-sized schemas this cuts
+  inferred edges and index time by an order of magnitude at the cost of some
+  recall on hub columns. Set `same_name_max_tables` to `null` to restore the
+  ungated behaviour.
+- `analyze --connection` is now optional: it is required unless `--all` is
+  passed. Omitting it without `--all` exits 1 with a runtime message
+  instead of failing argument parsing with a usage error.
+- `pretensor init`'s interactive flow now opens with a summary of everything
+  inferred and a single Yes/No/Customize choice instead of asking a
+  question per item up front. Yes proceeds with no further questions;
+  Customize walks through the same per-item questions as before. After
+  indexing (and after linking a repository), interactive runs offer to add
+  another database connection or repository. When the optional
+  `[embeddings]` extra is installed, the guided flow also asks once,
+  before indexing, whether to compute table embeddings.
+- `analyze --all --json` now emits a single JSON array of per-repository
+  summaries instead of interleaving unparseable "Analyzing <path>" lines
+  between them.
+
+## [0.1.0] - 2026-08-13
+
+### Fixed
+- `pretensor serve` crashed at startup on fresh installs: the unbounded
+  `mcp>=1.0` dependency resolved to the new `mcp` 2.0 major release,
+  whose `Server` API is incompatible. The dependency is now capped to
+  `mcp>=1.0,<2` (2.x support is tracked as follow-up work), and an
+  end-to-end stdio smoke test now exercises the real CLI handshake so a
+  startup-breaking dependency drift fails in CI instead of on users'
+  machines.
+- `pretensor serve` startup errors are printed to stderr instead of
+  stdout. Stdout is the MCP JSON-RPC channel and clients only surface
+  stderr in their logs, so a startup failure looked like a silent
+  disconnect.
+- `pretensor analyze`: statements quoting identifiers with backticks
+  (MySQL, BigQuery `` `project.dataset.table` ``) no longer fail table
+  resolution. The multi-dialect parse retry accepted the first dialect
+  returning any refs, and generic-dialect tokenization of backticks
+  produced garbage names that stopped the retry before the right dialect
+  ran; implausible refs are now treated as a failed parse.
+- `pretensor analyze`: table references resolve case-insensitively when
+  exactly one indexed table matches, so conventional lowercase SQL
+  resolves against Snowflake's uppercase-stored identifiers. Exact
+  matches still win, and ambiguous case-variant twins stay dropped.
+- `pretensor analyze`: MySQL `REPLACE INTO` statements are recognized and
+  classified as writes (sqlglot cannot parse them in any dialect; the
+  pre-parse normalizer rewrites them to `INSERT INTO`, which has the same
+  write-target shape).
+- `pretensor analyze`: SQL-bearing variable detection also matches
+  affixed names (`merge_sql`, `orders_query`, `sql_fetch_users`), not
+  only the exact names `query`/`sql`/`stmt`/`statement`. The is-this-SQL
+  classifier still gates every candidate, so non-SQL strings in such
+  variables are rejected as before.
+- The MCP `cypher` tool no longer leaks a worker thread per timed-out
+  query: all queries now run on one shared, bounded thread pool, and a
+  timeout returns immediately instead of blocking until the runaway
+  query finishes. Under sustained slow-query load the previous
+  per-query executors could accumulate threads without limit.
+
+### Added
+- `pretensor analyze`: scan an application repository for SQL string
+  literals in Python source and link the code that issues them to the
+  indexed tables in the graph. Produces `ExternalConsumer` nodes and
+  `CONSUMES` edges carrying provenance (service, file, line range,
+  read/write op, confidence), written idempotently per scan run with
+  stale rows swept on re-scan. Raw SQL text is never stored: only a
+  `sha256[:16]` fingerprint and the resolved table references. Flags:
+  required `--connection`, `--service`, repeatable `--include` /
+  `--exclude`, `--max-file-bytes`, `--min-confidence`,
+  `--default-schema` (schema assumed for unqualified table names),
+  `--dry-run`, and `--json`. When the graph has no tables for the
+  connection the command errors with a copy-pasteable `pretensor index`
+  hint; it never auto-indexes. A `# noqa: pretensor-analyze` comment on
+  or above a statement opts it out of extraction.
+- `consumers` MCP tool: the external code locations that read or write
+  one table (service, file, line range, op, kind, confidence), from the
+  data produced by `pretensor analyze`. Optional `op` filter and
+  `min_confidence` cutoff.
+- The `impact` MCP tool now attaches a `consumers` list to every
+  reached table. The field is additive. Existing callers that ignore
+  it are unaffected.
+- `pathspec` added to base dependencies (gitignore-aware repository
+  walking for `analyze`).
+
+## [0.1.0a4] - 2026-07-13
+
+### Fixed
+- `pretensor export` no longer crashes with `Parameter database_name not
+  found`. The export query builder bound scope parameters that some node
+  tables' queries never referenced (e.g. the semantic-layer tables), which
+  Kuzu's prepared statements reject; parameters are now built to match
+  exactly the filter each query generates. `export` is also covered by an
+  end-to-end CLI test against a real graph now.
+- `pretensor reindex <name>` with a registry connection name no longer
+  dumps a raw traceback; it exits cleanly and suggests
+  `pretensor reindex --database <name>` when the value matches a known
+  connection.
+- `pretensor quickstart` no longer points `docker compose` at the
+  compose file inside `site-packages`. Snap-confined Docker (the default
+  `snap install docker` on Ubuntu) can't read files under hidden
+  directories in `$HOME`, so a `pipx install` (venv under
+  `~/.local/pipx/venvs/...`) made quickstart fail with an opaque
+  `permission denied` error. Quickstart now copies the compose file and
+  Pagila SQL fixtures into `./.pretensor/quickstart/` (next to the graph
+  output) before invoking compose, and prints a hint about snap Docker +
+  hidden paths if a permission error slips through anyway.
+
+### Added
+- Agent-framework SDK adapters for LangChain, LlamaIndex, and Google ADK,
+  exposing the MCP tools as native framework tools.
+- `pretensor --version` prints the installed package version.
+- CLI flag names unified across subcommands: the workspace directory is
+  `--state-dir` everywhere and the connection selector is `--database`/`-d`
+  everywhere. The previous spellings (`--graph-dir` on `serve`, `--db` on
+  `validate`) keep working as hidden deprecated aliases.
+- `SECURITY.md` with the supported-versions and responsible-disclosure
+  policy.
+- `pretensor benchmark {l1,l2,l3}` CLI scaffolding for the 3-level benchmark
+  harness. Dispatch / I/O wiring only; metric computation and the L3 runners
+  land in follow-up changes. `l1`/`l2` accept `--embeddings`; `l3` accepts
+  `--runner {baseline,pretensor}`, `--model`, and `--seed`.
+- `pretensor benchmark compare --baseline <path> --current <path>
+  [--tolerance <float>]` regression-gate subcommand. Reads two
+  `BenchmarkResult` JSON files, classifies metric changes by direction
+  (`higher_is_better` drops and `lower_is_better` rises beyond tolerance
+  fail), prints a human-readable diff to stderr, and exits `0` on no
+  regression, `1` on regression, `2` on bad input (dataset/level mismatch
+  or malformed JSON).
+- `pretensor.benchmark.results` module: `BenchmarkResult` / `Metric`
+  dataclasses, deterministic `write_json` / `read_json` (sorted keys,
+  indent 2, trailing newline), `compare()` returning a `ComparisonReport`,
+  and `write_csv()` for spreadsheet review.
+
+### Changed
+- The MCP server now reuses one graph connection per database for the
+  lifetime of the server instead of re-opening the graph file (and
+  re-running schema migration probes) on every tool call. A separate
+  `pretensor reindex` run is picked up on server restart, as before.
+
+### Security
+- The MCP `cypher` tool now opens the graph in Kuzu's engine-level
+  read-only mode, so mutations cannot commit even if the statement
+  allowlist were bypassed; the allowlist itself also rejects DDL and
+  file-I/O commands (`COPY`, `EXPORT`, `ATTACH`, `LOAD`, …) explicitly.
+- Encryption keystore and registry writes are atomic and created with
+  owner-only permissions; a warning is printed if an existing keystore is
+  world-readable.
+- MCP tool and resource errors returned to clients are sanitized: the full
+  stack is logged server-side under a correlation id, and the client
+  receives a generic message with that id instead of exception text or
+  filesystem paths.
+
+### Removed
+- MCP `context` tool: removed the deprecated `name` field from column
+  entries: use `column_name`.
+- `scripts/benchmark_graph_rag_nl2sql.py`: unrunnable after the LLM
+  stack was stripped from OSS (imported the since-deleted `suggest_query` MCP
+  tool). The new `pretensor benchmark` CLI covers its namespace.
+- `scripts/e2e_pagila.py`: unrunnable for the same reason (imported deleted
+  `llm_runtime` helpers, `suggest_query_payload`, and the `llm_options` CLI
+  module). The Docker-backed `tests/e2e/` suite is the canonical full-stack
+  E2E path now.
+
+## [0.1.0a3] - 2026-05-03
+
+### Fixed
+- Ship the quickstart assets in the wheel so the documented quickstart
+  runs from a clean `pip install pretensor` (they were missing from the
+  built distribution in earlier alphas).
+
+## [0.1.0a2] - 2026-04-28
+
+### Fixed
+- Ship the `pretensor.skills` package data in the wheel; earlier wheels
+  omitted it, so skill-backed flows failed on a clean install.
+
+## [0.1.0a1] - 2026-04-26
+
+### Added
+- CD pipeline at `.github/workflows/release.yml` that publishes tagged
+  `v*.*.*` versions to PyPI via OIDC trusted publishing, routing
+  prereleases through TestPyPI first.
+- `"Typing :: Typed"` PyPI classifier, pairing the existing
+  `src/pretensor/py.typed` PEP 561 marker with its public advertisement.
+- Release runbook sections in `docs/releases.md` covering publishing,
+  one-time OIDC setup, an optional pre-merge dry-run, cutting a release,
+  and the post-transfer re-point procedure.
+
+### Fixed
+- Drop the embedding dependencies from the `[all-connectors]` extra so it
+  installs only connector drivers, not the heavy ML stack.
+
+## [0.1.0a0] - 2026-04-17
+
+### Added
+- Initial public alpha on PyPI: reserves the `pretensor` name and ships
+  the first published build of the schema-introspection MCP server, CLI,
+  and bundled connectors.
+
+<!--
+When cutting a release, copy the contents of [Unreleased] into a new
+`## [X.Y.Z] - YYYY-MM-DD` section above, then reset [Unreleased] to empty
+subsections (Added / Changed / Deprecated / Removed / Fixed / Security).
+-->

{pretensor-0.1.0a4 → pretensor-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pretensor
-Version: 0.1.0a4
+Version: 0.2.0
 Summary: Pretensor database knowledge graph — Kuzu-backed schema graph from precomputed DB introspection
 Project-URL: Homepage, https://github.com/pretensor-ai/pretensor
 Project-URL: Repository, https://github.com/pretensor-ai/pretensor
@@ -27,7 +27,8 @@ Requires-Dist: cryptography>=42.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: igraph<1,>=0.11
 Requires-Dist: kuzu<1,>=0.7
-Requires-Dist: mcp>=1.0
+Requires-Dist: mcp<2,>=1.0
+Requires-Dist: pathspec>=0.12
 Requires-Dist: pydantic>=2.0
 Requires-Dist: rapidfuzz>=3.0
 Requires-Dist: rich>=13.0
@@ -79,12 +80,12 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/pretensor.svg)](https://pypi.org/project/pretensor/)
 [![CI](https://github.com/pretensor-ai/pretensor/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/pretensor-ai/pretensor/actions/workflows/ci.yml)
 [![Bench](https://github.com/pretensor-ai/pretensor/actions/workflows/bench.yml/badge.svg?branch=main)](https://github.com/pretensor-ai/pretensor/actions/workflows/bench.yml)
-[![Status: Alpha](https://img.shields.io/badge/status-alpha-yellow.svg)](#status)
+[![Status: Beta](https://img.shields.io/badge/status-beta-blue.svg)](#status)
 [![Python: 3.11 | 3.12](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](#prerequisites)
 
 **Pretensor OSS** introspects **PostgreSQL** and **Snowflake**, with optional **BigQuery** connector support, builds a **Kuzu** knowledge graph of tables, columns, foreign keys, inferred joins, and related metadata, and exposes that graph to AI tools through an **MCP** (Model Context Protocol) server. Agents query schema context and search without issuing raw SQL against your graph store.
 
-> **Status: Alpha.** Pretensor is on PyPI as `pretensor` and currently in alpha. CLI flags, MCP tools, and graph schema can still change between alpha versions — pin exact versions until `1.0.0`. See [docs/releases.md](https://github.com/pretensor-ai/pretensor/blob/main/docs/releases.md) for the versioning policy.
+> **Status: Beta.** Pretensor is on PyPI as `pretensor`; `0.1.0` is the first non-alpha release. CLI flags, MCP tools, and graph schema can still change between minor versions. Pin exact versions until `1.0.0`. See [docs/releases.md](https://github.com/pretensor-ai/pretensor/blob/main/docs/releases.md) for the versioning policy.
 
 ## Who is this for
 
@@ -96,7 +97,7 @@ Description-Content-Type: text/markdown
 ## Prerequisites
 
 - **Python 3.11 or 3.12** (3.13 not yet tested).
-- A reachable database for `pretensor index`. Every database driver ships as an extra — PostgreSQL via `pretensor[postgres]`, Snowflake via `pretensor[snowflake]`, BigQuery via `pretensor[bigquery]`.
+- A reachable database for `pretensor index`. Every database driver ships as an extra: PostgreSQL via `pretensor[postgres]`, Snowflake via `pretensor[snowflake]`, BigQuery via `pretensor[bigquery]`.
 
 ## Install
 
@@ -109,7 +110,7 @@ uv pip install 'pretensor[postgres]'
 
 > **Heads-up:** the database drivers are *not* bundled in the base install. A
 > bare `pip install pretensor` installs the CLI and MCP server but **no DB
-> driver** — `pretensor index postgresql://…` will then fail at connect time
+> driver**. `pretensor index postgresql://…` will then fail at connect time
 > with `Postgres connector requires psycopg2. Install the Postgres extra: pip
 > install 'pretensor[postgres]' (or pip install psycopg2-binary).` Install the
 > extra matching your database (`postgres`, `snowflake`, `bigquery`, or
@@ -119,7 +120,7 @@ Optional features are exposed as extras:
 
 | Extra | Adds | Use when |
 |-------|------|----------|
-| `pretensor[postgres]` | `psycopg2-binary` | You're indexing PostgreSQL. **Required** — a bare install has no Postgres driver. |
+| `pretensor[postgres]` | `psycopg2-binary` | You're indexing PostgreSQL. **Required**: a bare install has no Postgres driver. |
 | `pretensor[snowflake]` | `snowflake-sqlalchemy` | You're indexing a Snowflake warehouse. |
 | `pretensor[bigquery]` | `google-cloud-bigquery` | You're indexing BigQuery. |
 | `pretensor[clustering]` | `leidenalg` | You want Leiden community detection during indexing. Without this, Pretensor falls back to igraph Louvain (works, but no resolution tuning). |
@@ -133,22 +134,41 @@ Try it without installing:
 uvx --from pretensor pretensor --help
 ```
 
-> **A note on alpha versions.** Pretensor is in alpha. The plain `pip install pretensor` command picks up the latest alpha because PyPI has no stable release yet. Once `1.0.0` ships, future alphas will require `--pre` (e.g. `pip install --pre pretensor`); pin to a specific version (e.g. `pretensor==<version>`) if you want a deterministic install today — see the [PyPI badge above](https://pypi.org/project/pretensor/) for the latest.
+> **A note on versions.** From `0.1.0` on, plain `pip install pretensor` resolves to the latest non-alpha release, and pre-releases require `--pre` (e.g. `pip install --pre pretensor`). Pin to a specific version (e.g. `pretensor==<version>`) if you want a deterministic install. See the [PyPI badge above](https://pypi.org/project/pretensor/) for the latest.
 
 If you want to hack on Pretensor itself rather than use it, see the contributor setup in [CONTRIBUTING.md](https://github.com/pretensor-ai/pretensor/blob/main/CONTRIBUTING.md) for the `git clone` + `make install` flow.
 
 ## Quickstart
 
 ```bash
-pretensor index postgresql://USER:PASSWORD@HOST:5432/DBNAME
-pretensor serve --config-only   # prints mcpServers JSON for Claude / Cursor
+pip install 'pretensor[postgres]'
+pretensor init
 ```
 
-`serve --config-only` prints the **`mcpServers` JSON** to stdout. Merge the `pretensor` entry into your Claude or Cursor MCP settings — the IDE starts the server automatically. Run `pretensor serve` directly if you prefer a long-running terminal process (config hints go to stderr, keeping stdout clean for JSON-RPC).
+`init` finds your database connection, indexes it, links your code, and registers
+pretensor with Claude or Cursor. Prefer to drive it yourself? Every step is still a
+flag: see [guides/quickstart.md](https://github.com/pretensor-ai/pretensor/blob/main/guides/quickstart.md).
 
-Use **`--state-dir`** on `index` / `reindex` and **`--graph-dir`** on `serve` when overriding the default state directory (`.pretensor`).
+## Scan application code (`analyze`)
 
-**Full guide — install, tools, visibility, reindexing, graph visualization:** [guides/quickstart.md](https://github.com/pretensor-ai/pretensor/blob/main/guides/quickstart.md)
+```bash
+pretensor analyze path/to/service-repo --connection mydb
+```
+
+`analyze` scans a repository's Python (`.py`) and SQL (`.sql`) files: it lifts
+SQL string literals from Python source via the stdlib AST (no code is
+executed) and reads bare `.sql` files whole, resolves each statement's table
+references with sqlglot, and links the issuing code to the matching tables in the graph as
+external consumers: service, file, line range, read/write op, and a confidence
+score. Raw SQL text is never stored, only a fingerprint. The results power the
+`consumers` MCP tool and enrich `impact`, so an agent can answer "which
+services consume this table?" with provenance.
+
+Useful flags: `--service` labels the scanned repo (defaults to the directory
+name), `--default-schema` sets the schema assumed for unqualified table names,
+`--dry-run` previews without writing, `--json` emits a machine-readable
+summary. A `# noqa: pretensor-analyze` comment on or above a statement opts it
+out.
 
 ## MCP tools
 
@@ -159,18 +179,47 @@ Use **`--state-dir`** on `index` / `reindex` and **`--graph-dir`** on `serve` wh
 | `query` | BM25 keyword search over table and entity metadata. Hybrid BM25 + cosine RRF rerank when `[embeddings]` is installed and tables carry vectors. |
 | `semantic_search` | Cosine ranking over indexed `SchemaTable` embeddings. Requires `pretensor[embeddings]`; returns a structured BM25-fallback envelope when the extra is absent or no tables have been embedded. |
 | `cypher` | Read-only Kuzu Cypher for one indexed database; mutating clauses are rejected. |
-| `context` | Full context for one physical table, including columns, joins, lineage, and cluster metadata. Optional `include_similar` arg surfaces cross-cluster nearest neighbors when embeddings are present. |
-| `traverse` | Join paths between two physical tables. When ambiguous and tables carry embeddings, ranks tied paths by embedding similarity. |
-| `impact` | Downstream tables reachable from a table via FK and inferred-join edges. |
+| `context` | Full context for one physical table, including columns, joins, lineage, and cluster metadata. Every relationship carries `confidence` + `source` provenance. Optional `include_similar` arg surfaces cross-cluster nearest neighbors when embeddings are present. |
+| `traverse` | Join paths between two physical tables. Every step carries `confidence` + `source` provenance. When ambiguous and tables carry embeddings, ranks tied paths by embedding similarity. |
+| `impact` | Downstream tables reachable from a table via FK and inferred-join edges. Each reached table carries the external code consumers found by `pretensor analyze`. |
+| `consumers` | External code locations (service, file, line range, read/write op, confidence) that consume one table, from `pretensor analyze`. |
 | `detect_changes` | Compare the live database schema to the last indexed snapshot without mutating the graph. |
 | `compile_metric` | Compile semantic-layer YAML into validated SQL for one indexed database. The error string includes a "did you mean: …" suggestion list when an unresolved metric, table, or column name has close matches. |
 | `validate_sql` | Validate SQL against the indexed graph before execution. |
 
+### Join confidence & provenance
+
+`context` (per relationship) and `traverse` (per path step) both report how a
+join was derived, so an agent can decide how much to trust it before writing
+SQL:
+
+- `confidence` — a `0.0`–`1.0` score. Declared foreign keys always report
+  `1.0`; inferred joins carry the score produced by the pass that found them.
+- `source` — how the join was derived:
+  - `declared_fk` — a real foreign-key constraint in the database. Always
+    confidence `1.0`.
+  - `heuristic` — inferred from naming conventions and column-type overlap.
+  - `llm_inferred` — inferred by an LLM pass over schema metadata.
+  - `embedding` — inferred from vector similarity between column/table
+    descriptions.
+  - `statistical` — a heuristic or LLM candidate whose confidence was
+    re-scored using sampled value overlap; the original hypothesis source is
+    folded into this value once the statistical pass adjusts it.
+  - `entity_link` — cross-database bridge steps in `traverse` derived from a
+    confirmed `SAME_ENTITY` link, not a same-database join.
+- `reasoning` — an optional short, human-readable rationale for inferred
+  joins (absent for declared FKs, where the constraint itself is the
+  rationale).
+
+Agents should prefer `declared_fk` and high-confidence edges when composing
+SQL, and treat sub-`0.5` confidence as speculative — verify with
+`validate_sql` (or inspect `reasoning`) before relying on it.
+
 ## Agent-framework adapters
 
 Agents that don't run over MCP can still reach the graph tools. Pretensor exposes
 `schema`, `context`, `traverse`, `impact`, `query`, and `validate_sql` as native
-tool objects for LangChain, LlamaIndex, and Google ADK — no MCP server process
+tool objects for LangChain, LlamaIndex, and Google ADK. No MCP server process is
 required. The adapters call the same underlying functions the MCP server uses, so
 output is identical.
 
@@ -189,19 +238,20 @@ example per framework.
 
 `src/pretensor/` is organized by subsystem:
 
-- **`connectors/`** — database-specific introspection (PostgreSQL, Snowflake, BigQuery)
-- **`core/`** — Kuzu graph store, schema writing, relationship discovery
-- **`intelligence/`** — deterministic graph intelligence (classification, clustering, join-path precomputation; metric-template code exists but is not part of the default OSS indexing flow)
-- **`mcp/`** — MCP server, tools, resources
-- **`cli/`** — Typer CLI (`index`, `reindex`, `serve`, `list`, `quickstart`, `export`, `validate`, `sync-grants`, `add`, `remove`, plus the `semantic` subcommand group)
+- **`connectors/`**: database-specific introspection (PostgreSQL, Snowflake, BigQuery)
+- **`core/`**: Kuzu graph store, schema writing, relationship discovery
+- **`intelligence/`**: deterministic graph intelligence (classification, clustering, join-path precomputation; metric-template code exists but is not part of the default OSS indexing flow)
+- **`enrichment/`**: optional graph enrichment passes (dbt manifest, `analyze` code scanner)
+- **`mcp/`**: MCP server, tools, resources
+- **`cli/`**: Typer CLI (`init`, `index`, `reindex`, `analyze`, `serve`, `list`, `quickstart`, `export`, `validate`, `sync-grants`, `add`, `remove`, plus the `semantic` subcommand group)
 
 ## Status
 
-Pretensor is in **pre-release development**. Before the first packaged release:
+Pretensor is **early software**:
 
-- The package on PyPI is named `pretensor`. The first stable release will be `1.0.0`; everything before that is alpha. `pip install pretensor` works today because no stable version exists yet — `--pre` will be required once `1.0.0` ships and future alphas resume.
-- There is no SemVer stability guarantee yet, so CLI flags, MCP tools, and graph schema may change between alphas. Pin exact versions.
-- Treat current builds as evaluation software and test upgrades in a staging environment before production use.
+- The package on PyPI is named `pretensor`. `0.1.0` is the first non-alpha release; pre-releases published after it require `--pre` to install.
+- There is no SemVer stability guarantee before `1.0.0`, so CLI flags, MCP tools, and graph schema may still change between releases. Pin exact versions.
+- Test upgrades in a staging environment before production use.
 
 Progress and release notes: [CHANGELOG.md](https://github.com/pretensor-ai/pretensor/blob/main/CHANGELOG.md).
 
@@ -225,4 +275,4 @@ make typecheck # pyright
 
 ## License
 
-MIT — see [LICENSE](https://github.com/pretensor-ai/pretensor/blob/main/LICENSE).
+MIT: see [LICENSE](https://github.com/pretensor-ai/pretensor/blob/main/LICENSE).