@orangepro/orangepro-mcp 0.1.0 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 OrangePro (OrangeproAI)
+Copyright (c) 2026 OrangePro
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,328 +1,272 @@
-# OrangePro (`opro`)
+# OrangePro
 
-**Point your coding agent at a pull request and it writes grounded, traceable tests for exactly the code that changed** — local-first, bring-your-own-key, with **no tenant, no repo access, and metadata-only artifacts**.
+**Find the behaviors your tests miss. Generate grounded tests that actually run.**
 
-`opro` builds a lightweight evidence **Knowledge Graph** from a local checkout, finds the behaviors a diff touches, and generates tests that are *grounded* in real symbols, files, and existing tests — so an AI agent stops hallucinating imports and selectors and starts citing evidence. It runs as a **CLI** and an **MCP server**, so Cursor, Claude Code, Codex, or any MCP client can drive it.
+`opro` builds a knowledge graph from your local checkout, maps every behavior in your code, shows which ones are tested and which aren't, and generates integration-level tests grounded in real symbols — not hallucinated imports. Runs as a CLI and an MCP server.
 
-> **Try it in ~60 seconds** (offline, no key needed):
-> ```bash
-> git clone https://github.com/OrangeproAI/orangepro-mcp.git
-> cd orangepro-mcp && npm ci && npm run build && npm link
-> node scripts/demo-local-proof-kit.mjs --repo . --provider deterministic
-> ```
+```bash
+npx @orangepro/orangepro-mcp
+cd /path/to/your/repo
+opro
+```
 
-## What it does
+That's it. You get:
 
 ```
-opro                                       # analyze, optional AI links + flows, report, RTM, agent next actions
-opro start --base main                     # same flow, scoped to a branch/PR diff
-opro start . --generate-coverage           # run repo-native coverage first, then graph + optional AI
-opro analyze . --ai-flows                  # build graph + AI candidate-flow worklist + report
-opro score                                 # how test-ready is this repo? (with reasons)
-opro gaps --limit 10                       # behaviors with weak / missing tests
-opro generate --base main                  # PR-scoped: tests ONLY for what the diff touches
-opro generate --pr 1234                    # check out PR #1234 (gh) and target its diff
-opro generate --changed                    # target the current branch's diff vs main/master
-opro generate --single --limit 3           # whole-repo: top-gap behavior, grounded tests
-opro export --out evidence-pack.json --graph-html   # metadata-only evidence pack + explorer
-opro mcp                                   # run as an MCP server (stdio)
+.orangepro/
+├── behavior-coverage.html   ← open this: interactive gap report
+├── rtm.md                   ← requirements traceability matrix
+└── evidence-pack.json       ← machine-readable metadata export
 ```
 
-Add `--json` to any read command for machine output. Run `opro help` for the full reference.
-
-## Quickstart — your first Proven
-
-**"Proven" counts only a real test that kills a targeted mutant of a behavior.** Two things follow, and they surprise people:
-
-- **You need a BYOK model key to reach Proven** — it's what generates the test. `export OPENAI_API_KEY=…` (or `ANTHROPIC_API_KEY=…`). No key → no generated tests → `Proven 0`, and OrangePro tells you so.
-- **`Proven 0` on a fresh `opro analyze` is normal, not broken.** It means no proof has run yet. Static tests and associations show as **Associated signal**, never Proven, until a real test kills a targeted mutant. That's the whole trust model — nothing is labeled Proven on faith.
-
-**The intended path is one ask, not a command sequence.** In Cursor / Claude Code / Codex with the OrangePro MCP, tell your agent to cover a behavior — it runs `orangepro_generate_tests`, writes and runs the test, then `orangepro_prove`, and the behavior turns Proven. See [Use with your coding agent](#use-with-your-coding-agent-the-headline-workflow) for the exact setup.
-
-Open `.orangepro/behavior-coverage.html` and click any behavior to see its evidence tier and exactly what to do next.
-
-## Languages supported
+---
 
-OrangePro reports behavioral gaps, not “unit test count.” Coverage is reported as
-separate behavior-status lanes — never blended into one proof number. Public
-glossary:
-
-- **Dynamically Proven** (shown as "Dynamically Proven" in the report, CLI, and RTM) — a dynamic targeted-proof ledger certificate closed for the behavior: baseline green, target mutated, same test failed at an assertion, and the target was not mocked. OrangePro maps the whole repo statically, then dynamically proves only the top few eligible behaviors per run (default 5, raise with `--auto-limit`); everything else stays a static signal, never Proven.
-- **Runtime-covered** — the repo's own coverage tool executed the code. This is actual runtime coverage, but not assertion-level proof.
-- **Static Associated signal** — a name, path, import, or structural match links a test to the code. Useful for triage, but not semantic proof and never counted as Dynamically Proven. The HTML report labels this tier **Statically Linked**.
-- **No integration signal** — no direct static test signal was found yet. This does not mean “untested”; broad integration/e2e coverage may exist without mapping one-to-one to a symbol. In the HTML report this tier is shown as **Reachable Untested** (the symbol appears in a static flow from an entry point) or **No Signal** (no test or static-flow signal yet) — a display-only split that changes no classification.
-
-OrangePro can ingest Go coverprofiles, JS/TS `lcov.info`, Python `coverage.xml`
-from coverage.py/pytest-cov, and Java JaCoCo XML. `opro coverage --generate`
-auto-runs Go coverage, repo-defined JS/TS coverage scripts, pytest-cov XML, and
-Maven/Gradle JaCoCo where the repo has the standard local tooling installed.
-
-| Language | Symbol extraction | Generated tests | Runtime coverage | Static assertion candidates |
-|---|---:|---:|---:|---:|
-| TypeScript / JavaScript | ✓ | ✓ Jest/Vitest/AVA/etc. | ✓ `lcov.info` | ✓ strongest support |
-| Go | ✓ | ✓ same-package `*_test.go` | ✓ coverprofile | ✓ limited shapes |
-| Python | ✓ | ✓ pytest drafts + marker-aware run hints | ✓ coverage.py / pytest-cov XML | ✓ limited pytest assert shapes |
-| Java | ✓ | ✓ JUnit 4/5 drafts + run hints | ✓ JaCoCo XML | ✓ limited JUnit assert shapes |
-
-> **Static assertion candidates are strongest for TypeScript/JavaScript.** “Strongest support” does not mean public Proven; it means TS/JS has the most complete deterministic static association resolver today. Public Proven is stricter and requires the dynamic targeted-proof ledger certificate. **Runtime coverage** is a first-class signal for Go, Java, Python, and TS/JS. Runtime-covered, static candidates, and associated signals never move the Proven percentage.
-
-Extraction is language-agnostic (tree-sitter), so more languages are additive — a config entry plus a grammar.
-
-### Open-source proof snapshot
-
-These numbers are a reproducible snapshot, not a universal benchmark. They come from
-the fresh-history public export of this repo at `5de25ca`, with AI disabled and no
-runtime coverage generation:
+## Install
 
 ```bash
-node scripts/export-public-local-repo.mjs /tmp/orangepro-public
-opro start /tmp/orangepro-public --no-ai
-```
+# No install needed (npx)
+npx @orangepro/orangepro-mcp
 
-| Signal | Count |
-|---|---:|
-| Files scanned | 344 |
-| Eligible behaviors | 258 |
-| Static assertion candidates | 133 (51.6%) |
-| Runtime-covered | 0 *(coverage generation was not run for this snapshot)* |
-| Associated signal | 91 |
-| No integration signal | 34 |
+# Or global install
+npm install -g @orangepro/orangepro-mcp
 
-This snapshot predates the dynamic-Proven gate, so those 133 rows are static
-assertion candidates, not public Proven. `Runtime-covered` and `Associated signal`
-also remain separate lanes and never move the Proven percentage.
-
-## Test cases we generate
-
-Generation is **evidence-gated** — a category is produced only when the graph has supporting evidence for it, never padded with generic filler. The categories:
-
-| Category | What it targets |
-|----------|-----------------|
-| **Happy path** | The primary expected behavior |
-| **Validation error** | Bad/invalid input handling |
-| **Edge case** | Boundaries, empty/null, limits, concurrency, retries |
-| **Integration flow** | Multi-step behavior across components |
-| **Security / privacy** | Authz, sensitive-data, injection-style concerns |
-| **Regression** | Pinning a previously-broken behavior |
-
-Each generated test carries its **grounding** (the real files/symbols/tests it cites) and **run hints** (where to put it, how to run it), so an agent can write it, run it, and report pass/fail.
-
-For runnable Python and Go output, the local validator must be able to call the normal language tools on your PATH (`python3` for pytest syntax checks, `gofmt` for Go syntax checks). If a generated body cannot be validated, OrangePro returns it as a grounded draft with no run command instead of pretending it is runnable.
-
-## Use with your coding agent (the headline workflow)
-
-The agent already has shell access, so `opro` prepares the graph/RTM and then generates test **code** with run hints — the agent writes the file, runs it, and reports back. `opro` itself never writes source/test files into your repo and never runs commands.
-
-Run `opro` first in the repo. It writes `.orangepro/behavior-coverage.html`, `.orangepro/rtm.md`, and next actions. If a real model provider is configured through your environment, local `.env.provider.local` / `.env.local` / `.env`, or `opro setup`, weak AI grounding and AI-suggested candidate flows run automatically; otherwise the deterministic artifacts are still produced and AI is clearly skipped.
-
-Report commands default to `.orangepro/`, but explicit `--out` paths can point at another local review/artifact directory, for example `opro rtm --format json --out /tmp/orangepro-run/rtm.json`.
+# Or from source
+git clone https://github.com/OrangeproAI/orangepro-mcp.git
+cd orangepro-mcp && npm ci && npm run build && npm link
+```
 
-For large repos, `opro start` prints a preflight breakdown before long work starts. It shows the biggest top-level directories, suggests focused scopes such as `opro start server/public --generate-coverage`, and still offers `opro start . --generate-coverage --no-ai` for a full deterministic local graph.
+---
 
-On large repos, the AI grounding lane is budgeted instead of sending the whole symbol catalog to the model. OrangePro shortlists product CodeSymbols per behavior, batches requests, and records partial progress in `.orangepro/ai/links.json`. These links are weak suggestions for generation only; they never change Proven coverage. Tune the automatic pass with:
+## Use with your coding agent
 
-| Env | Default | Meaning |
-|---|---:|---|
-| `ORANGEPRO_AI_LINK_MAX_BEHAVIORS` | `80` | Maximum behavior gaps processed in one AI-link run |
-| `ORANGEPRO_AI_LINK_SYMBOLS_PER_BEHAVIOR` | `40` | Product CodeSymbol shortlist size per behavior |
-| `ORANGEPRO_AI_LINK_MAX_PROMPT_TOKENS` | `30000` | Approximate prompt token ceiling per batch |
+OrangePro runs as an MCP server. Any MCP-compatible agent (Cursor, Claude Code, Codex, Copilot, OpenCode) can drive it.
 
-For a wider one-off link run, use `opro ai-links --max-behaviors 300 --symbols-per-behavior 50 --max-prompt-tokens 30000` followed by `opro ai-links --apply`. For explicit candidate-flow discovery outside `opro start`, use `opro analyze --ai-flows` or the lower-level `opro ai-flows && opro ai-flows --apply`.
+### Setup
 
-For Codex, install the plugin when it is available in your configured marketplace:
+Add to your client's MCP config:
 
-```bash
-codex plugin add orangepro
+```json
+{
+  "mcpServers": {
+    "orangepro-local": {
+      "command": "npx",
+      "args": ["-y", "-p", "@orangepro/orangepro-mcp@latest", "opro", "mcp"]
+    }
+  }
+}
 ```
 
-Until OrangePro is accepted into a default marketplace, add this repo as a Codex marketplace and install from it:
+| Client | Config location |
+|--------|----------------|
+| Claude Code | `.mcp.json` or `~/.claude.json` |
+| Cursor | `~/.cursor/mcp.json` or Settings → MCP |
+| Codex | MCP config printed by `opro agent --client codex`; plugin install after OrangePro is listed in a configured marketplace |
+| VS Code / Copilot | MCP settings |
+
+### The workflow
+
+Tell your agent:
+
+> "Use `orangepro_start`, then `orangepro_generate_tests` with base_ref=main. Write each test to its suggested_path, run it, and report pass/fail."
+
+The agent writes the test, runs it, calls `orangepro_prove`, and the behavior turns Dynamically Proven. One prompt, full loop.
+
+### MCP tools (18 total)
+
+| Tool | What it does |
+|------|--------------|
+| `orangepro_start` | One-command setup: analyze + report + next actions |
+| `orangepro_analyze_sources` | Build/refresh the evidence graph |
+| `orangepro_generate_tests` | Generate grounded tests for gaps |
+| `orangepro_prove` | Run mutation-kill oracle on a behavior |
+| `orangepro_prove_loop` | Setup commands + dynamic proof + report refresh for one behavior |
+| `orangepro_find_test_gaps` | List behaviors with weak/missing tests, ranked by risk |
+| `orangepro_graph_score` | Graph readiness score (0–100) |
+| `orangepro_status` | Workspace state without generating anything |
+| `orangepro_doctor` | Recommend next evidence to improve quality |
+| `orangepro_rtm` | Requirements traceability matrix |
+| `orangepro_stats` | Aggregate statistics |
+| `orangepro_changed_impact` | What a diff touches (requires git + base ref) |
+| `orangepro_record_run` | Record a test run result |
+| `orangepro_explain_test` | Explain why a test was generated |
+| `orangepro_export_evidence_pack` | Export metadata-only evidence pack |
+| `orangepro_update_graph` | Incremental graph update |
+| `orangepro_ai_links` | Weak behavior→symbol suggestions (optional AI) |
+| `orangepro_ai_flows` | Candidate flow discovery (optional AI) |
+
+---
+
+## CLI reference
 
 ```bash
-codex plugin marketplace add OrangeproAI/orangepro-mcp --sparse .agents/plugins --sparse plugins/orangepro
-codex plugin add orangepro@orangepro
+opro                          # analyze + report + agent next actions
+opro start --base main        # same, scoped to a branch diff
+opro analyze                  # build the evidence graph
+opro score                    # graph readiness (0–100)
+opro gaps --limit 10          # top 10 untested behaviors
+opro generate --base main     # tests for PR diff
+opro generate --single        # top gap, whole repo
+opro prove                    # mutation-kill oracle (use the prove_run args returned by generate)
+opro rtm                      # traceability matrix
+opro export                   # metadata-only evidence pack
+opro mcp                      # run as MCP server (stdio)
+opro doctor                   # what evidence to add next
+opro coverage                 # ingest runtime coverage
 ```
 
-For maintainer-local development before npm publishing, use the personal marketplace entry:
+Add `--json` to any read command for machine output. Run `opro help` for the full reference.
 
-```bash
-codex plugin add orangepro@personal
-```
+---
 
-For Claude Code, add the OrangePro marketplace and install the bundled MCP plugin:
+## PR workflow
 
-```text
-/plugin marketplace add OrangeproAI/orangepro-mcp
-/plugin install orangepro@orangepro
-/reload-plugins
+```bash
+opro generate --base main              # tests for what this branch changed
+opro generate --pr 1234                # checks out PR #1234 — mutates your working tree; needs gh + confirmation (prefer --base)
+opro generate --changed                # current branch diff vs main
 ```
 
-For Cursor, install OrangePro from the Cursor Marketplace when listed. Until then, use the bundled Cursor plugin at `plugins/orangepro` for local testing, or add the MCP server manually from [docs/agents/cursor.md](docs/agents/cursor.md).
+Each generated test includes:
+- **Grounding** — the real files, symbols, and existing tests it cites
+- **Run hints** — where to write it, how to run it
+- **Scenario bucket + technique** — what failure mode it targets and how
 
-Run `opro agent --client claude-code|cursor|codex|opencode` to print a client-ready MCP config and copy-paste agent instructions for clients that do not install plugins yet. See [docs/agent-workflow.md](docs/agent-workflow.md) for the full write/run/report loop and the per-agent install notes:
+---
 
-- [Codex](docs/agents/codex.md)
-- [Claude Code](docs/agents/claude-code.md)
-- [Cursor](docs/agents/cursor.md)
-- [OpenCode](docs/agents/opencode.md)
-- [VS Code / Copilot](docs/agents/vscode.md)
+## Test categories
 
-### Public plugin publishing checklist
+Generation is evidence-gated. A category is produced only when the graph has supporting evidence — never padded with generic filler. These are the public local generation buckets. The broader concern taxonomy used by planning prompts is not a public coverage taxonomy and does not change report tiers.
 
-Before announcing plugin installs publicly:
+| Category | What it targets |
+|----------|-----------------|
+| Happy path | Primary expected behavior |
+| Validation error | Bad/invalid input handling |
+| Edge case | Boundaries, empty/null, concurrency, retries |
+| Integration flow | Multi-step behavior across services |
+| Security / privacy | Auth, injection, data leakage |
+| Regression | Pinning a previously-broken behavior |
 
-1. Publish the npm package with the `opro` bin: `npm publish --access public`.
-2. Create the fresh-history public export and verify it has one commit, no private history, and no private artifacts.
-3. Codex: keep `.agents/plugins/marketplace.json` + `plugins/orangepro`; the repo marketplace install works from this public repo. The bare `codex plugin add orangepro` path requires OrangePro to be present in a configured/default Codex marketplace.
-4. Claude Code: keep `.claude-plugin/marketplace.json` + `plugins/orangepro`; users can add this repo as a Claude plugin marketplace. Directory-style discovery requires submitting/listing the marketplace through Claude's plugin ecosystem.
-5. Cursor: keep `plugins/orangepro/.cursor-plugin/plugin.json`, `rules/`, and `.mcp.json`; submit the same plugin bundle to the Cursor Marketplace when ready.
-6. OpenCode / VS Code: publish the documented MCP config snippets using `npx -y -p @orangepro/orangepro-mcp@latest opro mcp`.
-7. Smoke each install path in a clean repo and confirm `orangepro_start` works with no pinned model and no committed key.
+---
 
-**On a pull request**, point your agent at the changed code:
+## Evidence tiers
 
-```
-You (to your agent):  "Use orangepro_start, then use orangepro_generate_tests with base_ref=main.
-                       Write each
-                       test to its suggested_path, run it, and report pass/fail."
-```
+Every behavior gets exactly one tier. Nothing is labeled "tested" on faith.
 
-The `orangepro_generate_tests` tool returns, per test: the body, the **grounding** it used (real files/symbols/tests it cites), `run_hints` (a `suggested_path` next to the linked test + a `run_command` like `npx jest …`), and an `agent_workflow`:
+| Tier | What it means | How you get there |
+|------|---------------|------------------|
+| **Dynamically Proven** | A real test kills a targeted mutant of this behavior | `opro prove` after writing/running a test |
+| **Runtime-covered** | Coverage tool executed this code | `opro start --generate-coverage` |
+| **Statically Linked** | Import/name/structural match links a test to this code | Automatic during analysis |
+| **No Signal** | Nothing tests this behavior yet | — |
 
-1. Write each test body to its `suggested_path`.
-2. Run its `run_command` (or the repo's own `npm test` / `pytest`).
-3. After a pass, call the returned `prove_run` args so OrangePro can dynamically prove the target. `record_run` is static diagnostics only.
-4. Report pass/fail + stack traces, and propose fixes.
+> **"Dynamically Proven 0" is normal on first run.** Static analysis always runs. Dynamic proof requires running tests against targeted mutations. That's the trust model — nothing is Dynamically Proven until a real test kills a real mutant.
 
-Generation never fabricates a PR: a non-git checkout, a missing base ref, or a docs-only diff returns structured guidance (`not_a_git_repo` / `missing_base_ref` / `no_diff` / `no_code_changes`), never invented tests.
+---
 
-## Why it's safe to run
+## Language support
 
-- **No stored source.** Source is read in-process to ground analysis/generation. When model generation is enabled, redacted source excerpts may be sent to your configured BYOK provider; OrangePro does not upload repos to an OrangePro tenant and does not store raw source in local artifacts.
-- **No source/test writes.** It never writes source or test files into your repo. The only writes are workspace metadata under `.orangepro/` — analyze from a throwaway directory for zero writes inside the target checkout.
-- **Metadata-only exports.** The evidence pack and graph HTML carry file paths, names, hashes, frameworks, provenance, and scores — **not** raw source, prompts, scoring weights, or ranking traces. Generated test bodies are opt-in (`export --include-generated-bodies`).
-- **Your keys stay yours.** Model keys are read from the environment at call time and never written into the graph, config, or pack.
+OrangePro separates static mapping, generated tests, runtime coverage, and dynamic proof. Those are different confidence bars.
 
-## Trust-loop smoke
+| Language | Static behavior extraction | Generated tests | Runtime coverage | Dynamic proof |
+|----------|:--------------------------:|:---------------:|:----------------:|:-------------:|
+| TypeScript / JavaScript | ✓ | ✓ Jest / Vitest / Mocha / AVA-style drafts | ✓ lcov.info | ✓ Vitest / Jest / Mocha |
+| Python | ✓ | ✓ pytest | ✓ coverage.py / pytest-cov XML | ✓ pytest |
+| Go | ✓ | ✓ same-package `*_test.go` | ✓ coverprofile | ✓ `go test` |
+| Java | ✓ | ✓ JUnit 4/5 | ✓ JaCoCo XML | ✓ Maven/JUnit |
+| Kotlin, Rust, PHP, C#, Ruby, Swift, C, C++ | ✓ static behavior extraction | planned | planned where standard coverage exists | planned proof profiles |
 
-After `npm run build`, run the repeatable gap-fill smoke:
+Static mapping works across many languages through tree-sitter and repo metadata. Dynamic proof is deliberately narrower: each language needs a runner, mutation locator, sandbox profile, and false-proof regressions before it can mint Dynamically Proven.
 
-```bash
-node scripts/smoke-gap-fill-loop.mjs
-```
+---
 
-It creates a disposable TypeScript/Vitest repo with an unproven behavior, confirms
-the row starts at `No integration signal`, writes a real assertion test, then runs
-`opro prove` to execute the dynamic targeted-proof oracle. The row becomes
-`Reproven (this run)` only after baseline-green → mutant assertion-fail closes a
-metadata-only ledger certificate. This is the smallest local proof that OrangePro's
-public Proven number moves because a real dynamic kill happened, not because an
-LLM or static matcher claimed coverage.
+## Model setup (BYOK)
 
-## Install
+Analysis, scoring, and proof need no model key. Generation does.
 
-```bash
-git clone https://github.com/OrangeproAI/orangepro-mcp.git
-cd orangepro-mcp
-npm ci
-npm run build      # compiles the CLI to dist/local/cli.js
-npm link           # one-time: puts the `opro` command on your PATH
-```
-
-Prefer not to link? Every `opro <command>` is equivalent to `node dist/local/cli.js <command>`.
-
-## Model selection (BYOK)
-
-Generation uses **your** model key. Pick one provider; with none set, auto-detect order is **OpenAI-compatible → Ollama → Anthropic**.
-
-| Provider | Env |
-|---|---|
-| OpenAI-compatible | `OPENAI_API_KEY`, optional `OPENAI_BASE_URL`, `OPENAI_MODEL` |
-| Anthropic | `ANTHROPIC_API_KEY`, optional `ANTHROPIC_MODEL`, `ANTHROPIC_BASE_URL` |
-| Ollama (local, no key) | `OLLAMA_BASE_URL`, optional `OLLAMA_MODEL` |
+| Provider | Environment variable |
+|----------|---------------------|
+| OpenAI-compatible | `OPENAI_API_KEY` (optional: `OPENAI_BASE_URL`, `OPENAI_MODEL`) |
+| Anthropic | `ANTHROPIC_API_KEY` (optional: `ANTHROPIC_MODEL`) |
+| Ollama (local, no key) | `OLLAMA_BASE_URL` (optional: `OLLAMA_MODEL`) |
 
-`--provider openai|anthropic|ollama|deterministic` and `--model <name>` override the env. With `OPENAI_API_KEY` set and no explicit model, OrangePro defaults to `gpt-4.1` for generation quality. Run **`opro setup`** once to pick a provider + model interactively (saved to `.orangepro/config.json`; **keys stay in your env, never saved**), or just run `opro generate` with no provider in a terminal and it prompts you. Newer OpenAI reasoning models (`gpt-5*`, o-series) work automatically.
+Auto-detect order: OpenAI → Ollama → Anthropic. Override with `--provider` and `--model`.
 
-For local agent runs, you may also put provider values in `.env.provider.local`, `.env.local`, or `.env` in the repo/workspace. OrangePro reads only provider-related keys from those files at runtime; real environment variables override file values, and keys are never written to graph, RTM, HTML, or export artifacts.
+Run `opro setup` to configure interactively. Keys stay in your environment — never written to graph, config, or artifacts.
 
-**No silent fallback.** With no key set, `generate` returns setup guidance and produces **no tests**. The offline deterministic stand-in is opt-in only (`--provider deterministic`). Analyze, score, gaps, and export never need a model.
+---
 
-> Use a strong current model for real evaluation. Cheaper/smaller models may be fine for smoke tests, but they produce more draft or non-runnable tests on real repos.
+## AI candidate lanes
 
-## Current Language Support
+With a provider key, OrangePro can stage weak AI behavior→symbol links and AI-suggested candidate flows. These are ready for local use as review/generation worklists, but they are not evidence:
 
-OrangePro separates **what it can parse**, **what it can prove**, and **what it can generate/run**. Those are intentionally different bars.
+- AI links appear as `AI-linked` suggestions.
+- AI flows are stored separately from deterministic flows.
+- Neither lane changes Dynamically Proven, Runtime-covered, Statically Linked, denominator counts, or evidence tiers.
 
-| Capability | Current status |
-|---|---|
-| Product/test/config/doc parsing | TypeScript/JavaScript, Python, Go, Java, Kotlin, Rust, PHP, C#, Ruby, Swift, C, C++, Markdown/config metadata |
-| Structural associations | Broad non-TS graph signals: imports/calls/test naming/framework/package signals stay **Associated signal**, never Proven |
-| Static assertion candidates | TypeScript/JavaScript (strongest deterministic confirmer), plus limited exact-resolved shapes for Go, Python, and Java can mint hard `COVERS`/`TESTED_BY` graph edges for diagnostics. These render as **Associated signal**, not public Proven. Public Proven requires a dynamic targeted-proof ledger certificate from `opro prove`. |
-| Runnable generated tests | TypeScript/JavaScript (including AVA), Python (marker-aware pytest hints), Go, and Java (JUnit 4/5), with framework/path/run hints and safe draft fallback when the output cannot be validated |
-| Runtime coverage ingestion | Go coverprofiles, JS/TS `lcov.info`, Python `coverage.xml`, Java JaCoCo XML. Go, repo-defined JS/TS coverage scripts, pytest-cov XML, and Maven/Gradle JaCoCo can be generated locally with `--generate-coverage` when the repo's normal test tooling is installed. |
-| AI grounding | Optional weak `AI-linked` behavior→symbol suggestions and AI-suggested candidate flow worklists. These guide generation/review but **do not** change Proven coverage, deterministic flow counts, or tiers. |
+Use them when you want the agent to find likely service-boundary flows faster; ignore them when you want a deterministic-only report.
 
-Coming next:
+---
 
-- Listing OrangePro in the public Codex/Claude/Cursor/OpenCode plugin marketplaces (bundled plugins and a publishing checklist already ship in this repo — see the install steps above).
-- More deterministic proof recall for non-TS/Go languages, only when false-confirm tests make it safe.
+## How it works
 
-## MCP setup (any client)
+OrangePro separates **analysis** (what your code does) from **proof** (whether tests actually verify it).
 
-`opro` runs as a standard MCP server over stdio. Add this block to your client's MCP config (only the file location differs per client):
-
-```json
-{
-  "mcpServers": {
-    "orangepro-local": {
-      "command": "node",
-      "args": ["/absolute/path/to/orangepro-mcp/dist/local/cli.js", "mcp"],
-      "env": {}
-    }
-  }
-}
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│  Your Code  │ ──► │  Knowledge   │ ──► │  Evidence   │
+│  (any lang) │     │    Graph     │     │   Tiers     │
+└─────────────┘     └──────────────┘     └─────────────┘
+                           │
+                    ┌──────┴──────┐
+                    ▼             ▼
+             ┌───────────┐  ┌──────────┐
+             │ Gap Report│  │ Generate │
+             │ + Risks   │  │  Tests   │
+             └───────────┘  └──────────┘
 ```
 
-Provider keys and model defaults are inherited from the agent process environment, `.env.provider.local` / `.env.local` / `.env`, or `opro setup`. Add `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OLLAMA_BASE_URL`, or a model env var to the client config only if that client does not inherit your shell. OrangePro does not pin a model in the MCP config.
-
-| Client | Config location |
-|--------|-----------------|
-| Claude Code | project `.mcp.json` or `~/.claude.json` |
-| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) · `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
-| Cursor | `~/.cursor/mcp.json` (or Settings → MCP) |
-| Codex / OpenCode / Cline / Continue / Windsurf / other | that client's MCP / `mcpServers` settings |
-
-**Tools.** *Start here*: `orangepro_start`. *Baseline* (no diff/PR needed): `orangepro_analyze_sources`, `orangepro_status`, `orangepro_graph_score`, `orangepro_doctor`, `orangepro_find_test_gaps`, `orangepro_rtm`, `orangepro_generate_tests`, `orangepro_prove`, `orangepro_record_run`, `orangepro_stats`, `orangepro_explain_test`, `orangepro_export_evidence_pack`. *Diff/PR* (require a git repo + real diff vs a base): `orangepro_changed_impact`. *Optional AI lanes*: `orangepro_ai_links` for weak behavior↔symbol suggestions, `orangepro_ai_flows` for candidate flow worklists.
+| Phase | What happens | Needs a model key? |
+|-------|-------------|-------------------|
+| **Analyze** | AST walk → behaviors, flows, evidence tiers | No |
+| **Score** | Graph readiness score (0–100) with reasons | No |
+| **Generate** | Grounded tests for top gaps, per-behavior | Yes (BYOK) |
+| **Prove** | Mutation-kill oracle confirms test actually breaks if behavior changes | No |
 
-## How grounding works
+---
 
-`generate` targets one behavior at a time (the top gap, your `--target`, or what a diff touches) and produces up to `--limit` tests, each in a different scenario bucket when the evidence supports it — `happy_path`, `validation_error`, `edge_case`, `integration_flow`, `security_privacy`, `regression`. A bucket is never padded with a smoke test; each test reports its bucket and **cites the evidence it used**. Imports are reconstructed from the repo's own linked test for that area when one exists, rather than guessed.
+## Privacy
 
-- **Evidence pack** (`export`): a strict-schema JSON pack (+ Markdown summary) of facts, provenance, evidence strength, grounding, and score metadata — no prompts, weights, traces, or raw source. Test bodies excluded unless `--include-generated-bodies`.
-- **Graph explorer**: a self-contained, **offline** HTML view written to `.orangepro/graph.html` by default (`--no-graph-html` to skip). Click a symbol to see the files, tests, behaviors, and provenance behind it — the visual "why these tests are grounded." Tabs: Gap Heatmap · Connectivity Graph · All Behaviors.
+- **No stored source.** Reads code in-process. Never uploads to an OrangePro server.
+- **No source mutation.** Never edits your existing files. Writes metadata to `.orangepro/`.
+- **Metadata-only exports.** File paths, names, hashes, scores — not raw source.
+- **Your keys stay yours.** Read from env at call time, never persisted.
 
-<details>
-<summary><b>Comparison mode</b></summary>
+---
 
-`opro generate` can compare a prompt-only baseline with the graph-grounded output using the same selected model. The comparison report is local-only and helps show whether the evidence graph improved the result on your repo. Use `opro generate --single` for the normal shipping workflow: one graph-grounded output, persisted to the graph.
+## What's on the hosted platform
 
-</details>
+This repo is the free local tool. The [OrangePro platform](https://orangepro.ai) adds:
 
-## What's deferred (hosted platform)
+- Persistent knowledge graph across PRs and repos
+- Managed dynamic proof at scale (larger budgets, CI workers, service setup profiles)
+- PR/CI policy gates over Dynamically Proven, Runtime-covered, and risk deltas
+- Jira / Confluence / TestRail / OpenAPI enrichment
+- Cross-repo intelligence and recurring-flow memory
+- Production incident correlation and regression targeting
+- Full test lifecycle management and team dashboards
 
-This kit is the local adoption surface. The hosted OrangePro platform owns: tenant-scale lifecycle Knowledge Graph, verified unknown-to-known grounding, multi-source memory, scoring gates, retrieval/ranking, repo writing (safe patch workflow), source promotion, clean reproducible CI runs, and the full product workflow. Also deferred here: Jira/Confluence/TestRail/OpenAPI enrichers, Docker/watch mode, PDF/DOCX export.
+---
 
-## Development
+## Contributing
 
 ```bash
-npm run build      # compile to dist/
-npm test           # vitest
-npm run typecheck  # type check without emitting
-npm run local -- analyze .          # run the CLI via tsx in dev
-node scripts/smoke-local.mjs        # offline end-to-end smoke test
+npm run build       # compile to dist/
+npm test            # vitest
+npm run typecheck   # type check without emitting
 ```
 
-Deep reference: [docs/local-proof-kit.md](docs/local-proof-kit.md). Development helpers are source-checkout utilities; the published package includes only the `opro` / `orangepro-local` runtime, this README, LICENSE, and public docs.
+See [docs/local-proof-kit.md](docs/local-proof-kit.md) for the full development reference.
 
 ## License
 
-[MIT](LICENSE) © OrangePro (OrangeproAI)
+[MIT](LICENSE) © OrangePro