Complete CodeRAG portfolio readiness

README.md

@@ -4,15 +4,15 @@
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-CodeRAG is a verified codebase context engine for agents and developers. It indexes repositories, retrieves grounded code context, verifies citations against retrieved chunks, and exposes the results through CLI, REST, MCP, and a local web UI. It is not an autonomous coding agent and does not edit repositories.
+CodeRAG is a verified codebase context engine for agents and developers. It indexes repositories, retrieves grounded code context, verifies citations against indexed snapshot evidence, and exposes the results through CLI, REST, MCP, and a local web UI. It is not an autonomous coding agent and does not edit repositories.
 
 ## 🚀 Quick Start
 
 ```bash
 # Install
 pip install code-rag-me
 
-# Configure (get free API key from https://console.groq.com/keys)
+# Configure a cloud provider key, or skip generation with MODEL_PROFILE=retrieval-only
 coderag setup
 
 # Start web interface
@@ -21,6 +21,17 @@ coderag serve
 
 Open http://localhost:8000 to use the web interface.
 
+### Minimal verified local flow
+
+```bash
+coderag index https://github.com/pallets/markupsafe
+coderag repos --format json
+coderag context-pack <repo-id-or-prefix> "escape function" --format json
+coderag query <repo-id-or-prefix> "What does MarkupSafe's escape function do? Cite the relevant source lines." --format json
+```
+
+Expected completion signal: the query response has `grounded: true`, non-empty `citations`, non-empty `citation_verifications`, and evidence chunks. Use `MODEL_PROFILE=retrieval-only` for retrieval/context-pack workflows that must not require an LLM key.
+
 ### Claude Desktop Integration (MCP)
 
 ```bash
@@ -30,11 +41,11 @@ coderag mcp-install
 # Restart Claude Desktop
 ```
 
-Now you can use CodeRAG directly in Claude Desktop!
+After restart, Claude Desktop can use the local CodeRAG MCP tools configured by `coderag mcp-install`.
 
 ## ✨ Features
 
-- **Verified citations**: Answers include citations like `[file:start-end]` and expose verification status.
+- **Verified citations**: Answers include citations like `[file:start-end]`, verify them against indexed file snapshots plus retrieved evidence, and fall back to deterministic evidence when a model omits or invents citations.
 - **Hybrid retrieval and context packs**: Combine semantic and lexical retrieval without requiring generation.
 - **Code graph intelligence**: Python and TypeScript/JavaScript symbols, references, and blast-radius evidence are indexed when supported.
 - **Cloud or local LLM**: Use Groq, OpenAI, Anthropic, OpenRouter, Together, or explicitly configured local models.
@@ -315,15 +326,29 @@ SERVER_PORT=8000
 
 Configuration is stored in `~/.config/coderag/config.json` after running `coderag setup`.
 
-## Production readiness
+## Production readiness and evidence
 
-Current release-candidate work is evidence-gated. The supported default is local loopback (`127.0.0.1`) with user-configured model credentials. Binding to public interfaces requires explicit host, trusted CORS origins, authentication, and network controls outside CodeRAG's defaults.
+CodeRAG is complete for the portfolio/local-product scope: a verified codebase context engine with CLI, REST, MCP, and local web UI surfaces. Current evidence covers a real local MarkupSafe indexing/query flow with generated answers, grounded citations, context packs, API, MCP, CLI, UI screenshots, and negative cases.
 
-- Cloud LLM providers send prompt context to the selected provider. Use local/private profiles only when configured and verified for your environment.
+What is claimed:
+
+- Local loopback operation (`127.0.0.1`) with user-configured model credentials.
+- Durable SQLite repository/job state, hybrid retrieval, graph-backed code intelligence where supported, and deterministic citation verification against indexed snapshots.
+- Safe default posture: trusted CORS is required for non-local browser origins, remote model code is disabled unless explicitly configured, and retrieval-only workflows can run without an LLM key.
 - Unsupported graph languages degrade explicitly to text/chunk retrieval; they do not report fake graph confidence.
-- CodeRAG verifies citations against retrieved chunks, but it does not prove repository correctness, execute arbitrary project tests, or make autonomous code changes.
 
-Release-candidate evidence is committed in `docs/superpowers/plans/2026-06-30-m7-release-run-record.md`, `evals/runs/20260630-m7-production-rc.json`, and `evals/reports/20260630-m7-production-rc.md`.
+What is not claimed:
+
+- Hosted SaaS or multi-user production deployment readiness.
+- That CodeRAG proves repository correctness, executes arbitrary project tests, or makes autonomous code changes.
+- Physical headed-browser proof in every harness. The latest local UI E2E captured DOM/screenshot evidence; if a visible browser is required, run the same frozen plan with a headed Playwright-capable driver.
+
+Evidence:
+
+- Portfolio completion plan: `docs/superpowers/plans/2026-07-02-coderag-portfolio-complete.md`
+- Real local E2E plan and run record: `docs/superpowers/plans/2026-07-02-coderag-portfolio-e2e-plan.md`, `docs/superpowers/plans/2026-07-02-coderag-portfolio-e2e-run-record.md`
+- Portfolio readiness review: `docs/superpowers/plans/2026-07-02-coderag-portfolio-readiness-review.md`
+- M7 release-candidate evidence: `docs/superpowers/plans/2026-06-30-m7-release-run-record.md`, `evals/runs/20260630-m7-production-rc.json`, `evals/reports/20260630-m7-production-rc.md`
 
 ## 🏗️ Architecture