codenib 0.1.0__tar.gz → 0.2.0__tar.gz

codenib-0.2.0/CHANGELOG.md

@@ -0,0 +1,139 @@
+<!--
+SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Changelog
+
+All notable user-facing changes are recorded here. CodeNib follows
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-05
+
+### Added
+
+- A build-once distribution path that publishes a static Wiki and a verified,
+  commit-addressed context artifact for local or MCP reuse.
+- Capability-aware `search_context` serving through the official
+  `ai.codenib/codenib` MCP package, plus managed package-level SCIP and LSP
+  providers selected from repository languages.
+- Native repository-exploration adapters and quality-constrained token and
+  cost reports for supported agent localization policies.
+
+### Changed
+
+- Hybrid BM25+dense retrieval is the recommended installed default when the
+  semantic extra is present; the base package retains an explicit no-model
+  BM25 path.
+- Repository filtering, graph definition provenance, and TypeScript/TSX import
+  edges use updated builder contracts. Incompatible 0.1 views rebuild once;
+  compatible 0.2 views remain reusable.
+
+### Security
+
+- Downloaded context artifacts are inventory-checked, source-bound, and reject
+  unsafe archive members before any view is loaded.
+
+## [0.2.0a2] - 2026-08-05
+
+### Added
+
+- A capability-aware `search_context` MCP tool and version-matched metadata for
+  publishing the local stdio server as `ai.codenib/codenib` in the official MCP
+  Registry.
+- A repository-aware `codenib toolchain` command that detects graph and LSP
+  providers from the language registry, installs pinned package-managed tools
+  under `~/.codenib/toolchains`, and reports system or project prerequisites
+  without invoking `sudo` or mutating the target checkout.
+
+### Changed
+
+- Local `index` and `wiki` commands now select semantic hybrid retrieval when
+  the semantic extra is installed and explicitly report the no-model BM25
+  fallback otherwise. The reusable Pages workflow selects semantic retrieval
+  by default and caches its pinned local embedding model; `fast` remains an
+  explicit no-model route.
+- CodeNib processes automatically prefer the managed tool directory, removing
+  the shell `PATH` export previously required after source-checkout installs.
+- The public quickstart recommends BM25+dense serving and uses a normal,
+  version-pinned PyPI command instead of exposing a TestPyPI wheel URL.
+
+## [0.2.0a1] - 2026-08-05
+
+### Added
+
+- A reusable GitHub Pages workflow and composite Action that build a no-model
+  static Wiki plus a commit-addressed BM25 context artifact. Semantic builds
+  can use a pinned local CodeRankEmbed model or an explicit OpenAI-compatible
+  embedding endpoint.
+- Portable context artifacts with complete file inventories, source identity,
+  capability metadata, and an artifact-backed MCP path that reuses BM25 and
+  vector views without rebuilding the repository.
+- Secret-free inference route identities for local and remote embeddings,
+  compatibility fingerprints, provider-aware diagnostics, and fail-closed
+  handling of the retired GitHub Models service.
+- A native repository explorer with selective view loading and revision-pinned
+  compatibility layers for SWE-Explore, Agentless, CoSIL, LocAgent, and
+  OrcaLoca SearchAgent contracts.
+- Quality-constrained cost reports that pair localization success with token,
+  USD, and amortized build cost rather than reporting cost without a quality
+  denominator.
+- Graph schema 5 records semantic symbol kinds, explicit definition
+  provenance, and anchored TypeScript/TSX import and re-export edges.
+
+### Changed
+
+- Static Wiki exports now preserve mount paths, source citations, generated
+  pages, and dependency data while keeping query engines in the local or MCP
+  runtime.
+- Pull requests build and inspect distributions once; the complete
+  cross-version and installed-service release matrix runs on `main`, release
+  tags, and explicit TestPyPI dispatches.
+- Static navigation and source adapters no longer treat reference-only symbol
+  provenance as a definition location. Existing schema 4 graph artifacts need
+  a one-time `codenib index <repo> --preset graph --rebuild`.
+
+### Security
+
+- Downloaded context artifacts reject pickle payloads, unsafe archive paths,
+  symbolic and special files, unbounded expansion, inventory mismatches, and
+  source checkouts that do not match the recorded commit and fingerprint.
+- GitHub artifact downloads verify the API digest and never forward the GitHub
+  bearer token to redirects. Pages publication scans outputs for configured
+  credentials and rejects secret-bearing fork execution paths.
+
+## [0.1.0] - 2026-07-26
+
+### Added
+
+- A unified `codenib` CLI with `index`, `wiki`, `mcp`, and `doctor` commands.
+- A two-command local Wiki path with automatic language detection and reusable
+  repository manifests.
+- Fast, semantic, and full indexing presets with explicit optional
+  dependencies.
+- A deterministic static Wiki that requires no LLM credentials.
+- A source-linked MCP server for retrieval, graph, and static navigation tools.
+- Multi-view incremental maintenance and evaluation infrastructure.
+
+### Changed
+
+- Renamed the maintained package, command, state, and protocol namespace to
+  CodeNib.
+- Reduced the default installation to the BM25 and Wiki runtime; model, graph,
+  dataset, MCP, and agent dependencies now use named extras.
+- Made public package imports lazy so CLI startup does not initialize model or
+  graph runtimes.
+
+### Security
+
+- Prepared secretless PyPI publishing through a dedicated GitHub Actions OIDC
+  workflow.
+
+[Unreleased]: https://github.com/sysevol-ai/CodeNib/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/sysevol-ai/CodeNib/compare/v0.1.0...v0.2.0
+[0.2.0a2]: https://github.com/sysevol-ai/CodeNib/compare/620a82d...78e12ac
+[0.2.0a1]: https://github.com/sysevol-ai/CodeNib/tree/620a82d
+[0.1.0]: https://github.com/sysevol-ai/CodeNib/releases/tag/v0.1.0

{codenib-0.1.0 → codenib-0.2.0}/MANIFEST.in

@@ -5,6 +5,7 @@
 graft web
 include CHANGELOG.md
 include CONTRIBUTING.md
+include server.json
 prune web/.next
 prune web/node_modules
 prune web/playwright-report

{codenib-0.1.0 → codenib-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codenib
-Version: 0.1.0
+Version: 0.2.0
 Summary: A multi-view data system for serving repository context to coding agents
 Author-email: Zhongming Yu <zhy025@ucsd.edu>
 License-Expression: Apache-2.0
@@ -9,7 +9,7 @@ Project-URL: Homepage, https://codenib.ai
 Project-URL: Issues, https://github.com/sysevol-ai/CodeNib/issues
 Project-URL: Repository, https://github.com/sysevol-ai/CodeNib.git
 Keywords: code-search,coding-agents,model-context-protocol,repository-context,static-analysis
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3
@@ -33,7 +33,8 @@ Requires-Dist: tree-sitter>=0.25.2
 Requires-Dist: tree-sitter-language-pack<1.9.0,>=1.8.1
 Requires-Dist: uvicorn>=0.20.0
 Provides-Extra: agent
-Requires-Dist: litellm>=1.40.0; extra == "agent"
+Requires-Dist: litellm>=1.93.0; extra == "agent"
+Requires-Dist: openai>=1.0.0; extra == "agent"
 Provides-Extra: datasets
 Requires-Dist: datasets>=4.0.0; extra == "datasets"
 Provides-Extra: graph
@@ -47,6 +48,10 @@ Requires-Dist: faiss-cpu>=1.7.0; extra == "semantic"
 Requires-Dist: numpy>=1.24.0; extra == "semantic"
 Requires-Dist: openai>=1.0.0; extra == "semantic"
 Requires-Dist: sentence-transformers>=2.2.0; extra == "semantic"
+Provides-Extra: semantic-remote
+Requires-Dist: faiss-cpu>=1.7.0; extra == "semantic-remote"
+Requires-Dist: numpy>=1.24.0; extra == "semantic-remote"
+Requires-Dist: openai>=1.0.0; extra == "semantic-remote"
 Provides-Extra: vertex
 Requires-Dist: litellm[google]>=1.93.0; extra == "vertex"
 Provides-Extra: zoekt
@@ -70,14 +75,17 @@ Requires-Dist: isort>=5.10.1; extra == "dev"
 Requires-Dist: mypy>=0.950; extra == "dev"
 Requires-Dist: flake8>=4.0.1; extra == "dev"
 Requires-Dist: flake8-bugbear>=24.4.0; extra == "dev"
+Requires-Dist: mkdocs<2.0.0; extra == "dev"
 Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
+Requires-Dist: mkdocstrings-python>=2.0.0; extra == "dev"
+Requires-Dist: mkdocs-api-autonav>=0.4.0; extra == "dev"
 Provides-Extra: test
 Requires-Dist: datasets>=4.0.0; extra == "test"
 Requires-Dist: einops>=0.8.0; extra == "test"
 Requires-Dist: faiss-cpu>=1.7.0; extra == "test"
 Requires-Dist: filelock>=3.0.0; extra == "test"
 Requires-Dist: igraph>=0.11.6; extra == "test"
-Requires-Dist: litellm>=1.40.0; extra == "test"
+Requires-Dist: litellm>=1.93.0; extra == "test"
 Requires-Dist: matplotlib>=3.4.0; extra == "test"
 Requires-Dist: mcp<3,>=2.0.0; extra == "test"
 Requires-Dist: numpy>=1.24.0; extra == "test"
@@ -97,12 +105,17 @@ SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
 
 SPDX-License-Identifier: Apache-2.0
 -->
+<!-- mcp-name: ai.codenib/codenib -->
 
 <div align="center">
   <img src="https://raw.githubusercontent.com/sysevol-ai/CodeNib/main/assets/codenib_logo.svg" alt="CodeNib" width="560">
-  <h1>A Multi-View Data System for Serving Repository Context to Coding Agents</h1>
+  <h1>Searchable codebase wikis and context for coding agents</h1>
   <p>
-    Incremental compilation, explicit per-view manifests, and agent-native context serving.
+    Point it at any repo, get a searchable Wiki and an MCP server for your coding agent.
+  </p>
+  <p>
+    <a href="https://arxiv.org/abs/2607.25431"><img src="https://img.shields.io/badge/arXiv-2607.25431-b31b1b.svg?logo=arxiv&amp;logoColor=white" alt="arXiv 2607.25431"></a>
+    <a href="https://huggingface.co/papers/2607.25431"><img src="https://img.shields.io/badge/Hugging_Face-%232_Paper_of_the_Day-FFD21E.svg?logo=huggingface&amp;logoColor=black" alt="Hugging Face: #2 Paper of the Day"></a>
   </p>
   <p>
     <a href="#quickstart">Quickstart</a>
@@ -115,26 +128,50 @@ SPDX-License-Identifier: Apache-2.0
     &nbsp;&middot;&nbsp;
     <a href="https://docs.codenib.ai/mcp/">MCP</a>
     &nbsp;&middot;&nbsp;
+    <a href="https://docs.codenib.ai/agent_integrations/">Agent Integrations</a>
+    &nbsp;&middot;&nbsp;
     <a href="https://docs.codenib.ai/language_capabilities/">Languages</a>
   </p>
   <p>
     <a href="https://github.com/sysevol-ai/CodeNib/actions/workflows/ci.yml"><img src="https://github.com/sysevol-ai/CodeNib/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+    <a href="https://pypi.org/project/codenib/"><img src="https://img.shields.io/pypi/v/codenib.svg" alt="PyPI version"></a>
     <a href="https://github.com/sysevol-ai/CodeNib/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a>
     <a href="https://github.com/sysevol-ai/CodeNib/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB.svg" alt="Python 3.10+"></a>
-    <img src="https://img.shields.io/badge/Release-Developer_Preview-EA580C.svg" alt="Developer Preview">
+    <img src="https://img.shields.io/badge/Release-0.2.0-2563EB.svg" alt="CodeNib 0.2.0">
   </p>
 </div>
 
-CodeNib is a multi-view data system for serving repository context to coding
-agents. Its native runtime compiles a checkout into manifest-linked lexical,
-semantic, structural, and static-navigation views, incrementally maintains
-supported transitions, and serves bounded source evidence through MCP,
-LSP-shaped providers, Python, and HTTP APIs.
+```bash
+python -m pip install "codenib[mcp,semantic]==0.2.0"
+codenib wiki /path/to/your/repo
+```
 
-The Wiki, Ask view, and Dependency Map are inspection clients of that same
-runtime, not the system boundary. The core implementation lives in CodeNib;
-optional model endpoints and language servers are providers rather than a host
-agent or code-Wiki framework.
+Local, open source, and no cloud required. CodeNib combines BM25 and dense code
+search, adds optional SCIP symbol graphs, and incrementally rebuilds repository
+indexes as commits change. The same index powers the Wiki, Dependency Map, Ask,
+and MCP tools instead of making every agent rediscover the codebase.
+
+## News
+
+- **2026-08-05 — CodeNib 0.2.0.** Build a static Wiki and reusable context
+  artifact once, then serve it through Pages or the official MCP package.
+  Hybrid retrieval and managed SCIP/LSP providers ship in the same CLI.
+  [Release notes](https://docs.codenib.ai/releases/0.2.0/)
+- **2026-08-05 — SweRank recipe.** Run
+  [SweRank](https://github.com/SalesforceAIResearch/SweRank) retrieval and
+  reranking over a local checkout. [Example](examples/swerank_retrieve_rerank.py)
+- **2026-08-04 — Native repository explorer.** CodeNib's planner now targets
+  the [SWE-Explore](https://github.com/Qiushao-E/SWE-Explore-Bench)
+  source-region protocol.
+  [Validation](docs/evaluation/swe_explore.md)
+- **2026-08-03 — Native LocAgent policy.**
+  [LocAgent](https://github.com/gersteinlab/LocAgent) runs directly on CodeNib
+  views without LocAgent, LiteLLM, or LlamaIndex dependencies.
+  [Support matrix](https://docs.codenib.ai/agent_integrations/)
+- **2026-08-02 — OrcaLoca SearchAgent.**
+  [OrcaLoca](https://github.com/fishmingyu/OrcaLoca)'s six-tool search loop
+  now reuses CodeNib's symbol graph.
+  [Support matrix](https://docs.codenib.ai/agent_integrations/)
 
 ## System Architecture
 
@@ -160,13 +197,21 @@ publishing a partially updated view.
 
 ## Quickstart
 
-Requires Python 3.10+ and Git.
+Requires Python 3.10+ and Git. The recommended local path includes the pinned
+CodeRankEmbed model and serves hybrid BM25+dense retrieval:
 
 ```bash
-pip install codenib
+python -m pip install "codenib[semantic]==0.2.0"
+codenib doctor --require core --require wiki
 codenib wiki /path/to/repository
 ```
 
+`codenib wiki` selects the semantic route because the installed environment
+contains its dependencies. A smaller `python -m pip install codenib==0.2.0`
+installation selects the deterministic BM25 fallback and downloads no model.
+The [0.2 release notes](https://docs.codenib.ai/releases/0.2.0/) record the
+upgrade boundary and verification evidence.
+
 CodeNib detects the repository languages, builds a reusable index under
 `~/.codenib/repositories`, launches the local Wiki, and opens
 [http://localhost:3000](http://localhost:3000). The wheel includes the
@@ -181,6 +226,39 @@ codenib doctor --require core --require wiki
 codenib index /path/to/repository
 ```
 
+For a structural view, CodeNib detects the repository languages and manages
+only their package-level providers; operating-system and project prerequisites
+remain explicit:
+
+```bash
+python -m pip install "codenib[graph]==0.2.0"
+codenib toolchain install /path/to/repository --scope graph
+codenib doctor /path/to/repository --require graph
+```
+
+Export that indexed commit as a serverless Wiki when a live Ask backend is not
+needed:
+
+```bash
+codenib export /path/to/repository --output /tmp/repository-wiki
+```
+
+The export contains a versioned provenance manifest, precomputed Wiki pages,
+source citations, and available page-level dependency data. It contains no
+provider credential; interactive Ask and runtime graph exploration remain on
+the local or MCP serving path.
+
+For a repository-hosted Wiki, CodeNib also ships a reusable GitHub workflow
+that incrementally builds the same manifest, deploys the static site to Pages,
+and uploads the matching commit-addressed context artifact. Its default
+`semantic` route builds BM25 and vector views with a cached local Hugging Face
+model and needs no API key. An explicit `fast` route avoids the model download;
+a BYO OpenAI-compatible endpoint can replace local embedding. Query-time search
+remains in the local or MCP runtime. See
+[GitHub Pages](https://docs.codenib.ai/github_pages/).
+The published BM25/vector artifact can then be verified against an exact local
+checkout and served through MCP without rebuilding the repository views.
+
 See the
 [Quickstart](https://docs.codenib.ai/quickstart/)
 for ports, advanced indexing, and troubleshooting.
@@ -195,13 +273,15 @@ Install the MCP extra, build once, and serve the same repository manifest over
 stdio:
 
 ```bash
-pip install "codenib[mcp]"
+python -m pip install "codenib[mcp,semantic]==0.2.0"
 codenib index /path/to/repository
 codenib mcp /path/to/repository
 ```
 
-The MCP server advertises its full tool set and uses the compiled manifest to
-decide which calls have a fresh backing view. An agent can therefore reuse
+The MCP server advertises `search_context` as its default ranked entry point,
+then exposes the underlying BM25, vector, graph, and navigation operations for
+explicit control. It uses the compiled manifest to decide which calls have a
+fresh backing view. An agent can therefore reuse
 available repository work instead of rebuilding context through unbounded
 `grep` and `read` loops, while unavailable searches fail explicitly. BM25,
 semantic, regex, Zoekt, dependency, and static-navigation results retain source
@@ -209,15 +289,31 @@ locations for follow-up reads and citations. See
 [MCP Server](https://docs.codenib.ai/mcp/)
 for client configuration and tool contracts.
 
+The same planner is available directly to Python agents:
+
+```python
+from codenib.agent import RepositoryContextExplorer
+
+with RepositoryContextExplorer.from_repository(
+    "/path/to/repository", policy="auto"
+) as explorer:
+    result = explorer.explore("where is request retry behavior implemented?", top_k=10)
+```
+
+Each result includes source-validated evidence plus the selected plan,
+capabilities, loaded views, fusion, graph, and reranking trace.
+
 ## What CodeNib Provides
 
 | Surface | Purpose |
 |---|---|
 | Incremental compiler | Build independently managed views, reuse unchanged content, repair supported transitions, and conservatively rebuild outside those boundaries |
 | Agent context runtime | Plan capability-aware retrieval and navigation, then assemble bounded source-linked evidence |
-| Retrieval | BM25, dense-vector, regex/trigram, Zoekt, fusion, and reranking paths |
+| Retrieval | BM25, dense-vector, regex/trigram, Zoekt, fusion, and reranking paths; see the [validated model matrix](https://docs.codenib.ai/rag_ops/#validated-models) |
 | Structural context | SCIP/LSP-backed symbol graphs with source locations and typed edges |
 | MCP and LSP-shaped tools | Serve one manifest to coding agents without tying the runtime to one agent framework |
+| Agent compatibility | Reuse one manifest across revision-pinned [LocAgent](https://github.com/gersteinlab/LocAgent), [Agentless](https://github.com/OpenAutoCoder/Agentless), [CoSIL](https://github.com/ZhonghaoJiang/CoSIL), and [OrcaLoca](https://github.com/fishmingyu/OrcaLoca) contracts; see the [support matrix](https://docs.codenib.ai/agent_integrations/) |
+| Benchmark compatibility | Evaluate native exploration against pinned external datasets and scorers, including [SWE-Explore](https://github.com/Qiushao-E/SWE-Explore-Bench); see the [dataset and benchmark matrix](https://docs.codenib.ai/evaluation/) |
 | Local inspection | Audit the same context through Wiki pages, Ask answers, citations, and the Dependency Map |
 | Evaluation harness | Measure retrieval, navigation, incremental maintenance, and context policies on the same artifacts |
 
@@ -228,7 +324,11 @@ records chunking, graph, incremental, and C++ decoder support.
 ## Documentation
 
 - [Quickstart](https://docs.codenib.ai/quickstart/)
+- [GitHub Pages](https://docs.codenib.ai/github_pages/)
 - [MCP Server](https://docs.codenib.ai/mcp/)
+- [Agent Integrations](https://docs.codenib.ai/agent_integrations/)
+- [RAG Models and Planner](https://docs.codenib.ai/rag_ops/)
+- [Benchmarks and Evaluation](https://docs.codenib.ai/evaluation/)
 - [Web UI](https://docs.codenib.ai/web_demo/)
 - [Language Capabilities](https://docs.codenib.ai/language_capabilities/)
 - [Concepts and development guides](https://docs.codenib.ai/)
@@ -236,7 +336,7 @@ records chunking, graph, incremental, and C++ decoder support.
 Build the documentation site locally with:
 
 ```bash
-pip install "codenib[dev]"
+python -m pip install -e ".[dev]"
 mkdocs serve
 ```
 

{codenib-0.1.0 → codenib-0.2.0}/README.md

@@ -3,12 +3,17 @@ SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
 
 SPDX-License-Identifier: Apache-2.0
 -->
+<!-- mcp-name: ai.codenib/codenib -->
 
 <div align="center">
   <img src="https://raw.githubusercontent.com/sysevol-ai/CodeNib/main/assets/codenib_logo.svg" alt="CodeNib" width="560">
-  <h1>A Multi-View Data System for Serving Repository Context to Coding Agents</h1>
+  <h1>Searchable codebase wikis and context for coding agents</h1>
   <p>
-    Incremental compilation, explicit per-view manifests, and agent-native context serving.
+    Point it at any repo, get a searchable Wiki and an MCP server for your coding agent.
+  </p>
+  <p>
+    <a href="https://arxiv.org/abs/2607.25431"><img src="https://img.shields.io/badge/arXiv-2607.25431-b31b1b.svg?logo=arxiv&amp;logoColor=white" alt="arXiv 2607.25431"></a>
+    <a href="https://huggingface.co/papers/2607.25431"><img src="https://img.shields.io/badge/Hugging_Face-%232_Paper_of_the_Day-FFD21E.svg?logo=huggingface&amp;logoColor=black" alt="Hugging Face: #2 Paper of the Day"></a>
   </p>
   <p>
     <a href="#quickstart">Quickstart</a>
@@ -21,26 +26,50 @@ SPDX-License-Identifier: Apache-2.0
     &nbsp;&middot;&nbsp;
     <a href="https://docs.codenib.ai/mcp/">MCP</a>
     &nbsp;&middot;&nbsp;
+    <a href="https://docs.codenib.ai/agent_integrations/">Agent Integrations</a>
+    &nbsp;&middot;&nbsp;
     <a href="https://docs.codenib.ai/language_capabilities/">Languages</a>
   </p>
   <p>
     <a href="https://github.com/sysevol-ai/CodeNib/actions/workflows/ci.yml"><img src="https://github.com/sysevol-ai/CodeNib/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+    <a href="https://pypi.org/project/codenib/"><img src="https://img.shields.io/pypi/v/codenib.svg" alt="PyPI version"></a>
     <a href="https://github.com/sysevol-ai/CodeNib/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a>
     <a href="https://github.com/sysevol-ai/CodeNib/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB.svg" alt="Python 3.10+"></a>
-    <img src="https://img.shields.io/badge/Release-Developer_Preview-EA580C.svg" alt="Developer Preview">
+    <img src="https://img.shields.io/badge/Release-0.2.0-2563EB.svg" alt="CodeNib 0.2.0">
   </p>
 </div>
 
-CodeNib is a multi-view data system for serving repository context to coding
-agents. Its native runtime compiles a checkout into manifest-linked lexical,
-semantic, structural, and static-navigation views, incrementally maintains
-supported transitions, and serves bounded source evidence through MCP,
-LSP-shaped providers, Python, and HTTP APIs.
+```bash
+python -m pip install "codenib[mcp,semantic]==0.2.0"
+codenib wiki /path/to/your/repo
+```
 
-The Wiki, Ask view, and Dependency Map are inspection clients of that same
-runtime, not the system boundary. The core implementation lives in CodeNib;
-optional model endpoints and language servers are providers rather than a host
-agent or code-Wiki framework.
+Local, open source, and no cloud required. CodeNib combines BM25 and dense code
+search, adds optional SCIP symbol graphs, and incrementally rebuilds repository
+indexes as commits change. The same index powers the Wiki, Dependency Map, Ask,
+and MCP tools instead of making every agent rediscover the codebase.
+
+## News
+
+- **2026-08-05 — CodeNib 0.2.0.** Build a static Wiki and reusable context
+  artifact once, then serve it through Pages or the official MCP package.
+  Hybrid retrieval and managed SCIP/LSP providers ship in the same CLI.
+  [Release notes](https://docs.codenib.ai/releases/0.2.0/)
+- **2026-08-05 — SweRank recipe.** Run
+  [SweRank](https://github.com/SalesforceAIResearch/SweRank) retrieval and
+  reranking over a local checkout. [Example](examples/swerank_retrieve_rerank.py)
+- **2026-08-04 — Native repository explorer.** CodeNib's planner now targets
+  the [SWE-Explore](https://github.com/Qiushao-E/SWE-Explore-Bench)
+  source-region protocol.
+  [Validation](docs/evaluation/swe_explore.md)
+- **2026-08-03 — Native LocAgent policy.**
+  [LocAgent](https://github.com/gersteinlab/LocAgent) runs directly on CodeNib
+  views without LocAgent, LiteLLM, or LlamaIndex dependencies.
+  [Support matrix](https://docs.codenib.ai/agent_integrations/)
+- **2026-08-02 — OrcaLoca SearchAgent.**
+  [OrcaLoca](https://github.com/fishmingyu/OrcaLoca)'s six-tool search loop
+  now reuses CodeNib's symbol graph.
+  [Support matrix](https://docs.codenib.ai/agent_integrations/)
 
 ## System Architecture
 
@@ -66,13 +95,21 @@ publishing a partially updated view.
 
 ## Quickstart
 
-Requires Python 3.10+ and Git.
+Requires Python 3.10+ and Git. The recommended local path includes the pinned
+CodeRankEmbed model and serves hybrid BM25+dense retrieval:
 
 ```bash
-pip install codenib
+python -m pip install "codenib[semantic]==0.2.0"
+codenib doctor --require core --require wiki
 codenib wiki /path/to/repository
 ```
 
+`codenib wiki` selects the semantic route because the installed environment
+contains its dependencies. A smaller `python -m pip install codenib==0.2.0`
+installation selects the deterministic BM25 fallback and downloads no model.
+The [0.2 release notes](https://docs.codenib.ai/releases/0.2.0/) record the
+upgrade boundary and verification evidence.
+
 CodeNib detects the repository languages, builds a reusable index under
 `~/.codenib/repositories`, launches the local Wiki, and opens
 [http://localhost:3000](http://localhost:3000). The wheel includes the
@@ -87,6 +124,39 @@ codenib doctor --require core --require wiki
 codenib index /path/to/repository
 ```
 
+For a structural view, CodeNib detects the repository languages and manages
+only their package-level providers; operating-system and project prerequisites
+remain explicit:
+
+```bash
+python -m pip install "codenib[graph]==0.2.0"
+codenib toolchain install /path/to/repository --scope graph
+codenib doctor /path/to/repository --require graph
+```
+
+Export that indexed commit as a serverless Wiki when a live Ask backend is not
+needed:
+
+```bash
+codenib export /path/to/repository --output /tmp/repository-wiki
+```
+
+The export contains a versioned provenance manifest, precomputed Wiki pages,
+source citations, and available page-level dependency data. It contains no
+provider credential; interactive Ask and runtime graph exploration remain on
+the local or MCP serving path.
+
+For a repository-hosted Wiki, CodeNib also ships a reusable GitHub workflow
+that incrementally builds the same manifest, deploys the static site to Pages,
+and uploads the matching commit-addressed context artifact. Its default
+`semantic` route builds BM25 and vector views with a cached local Hugging Face
+model and needs no API key. An explicit `fast` route avoids the model download;
+a BYO OpenAI-compatible endpoint can replace local embedding. Query-time search
+remains in the local or MCP runtime. See
+[GitHub Pages](https://docs.codenib.ai/github_pages/).
+The published BM25/vector artifact can then be verified against an exact local
+checkout and served through MCP without rebuilding the repository views.
+
 See the
 [Quickstart](https://docs.codenib.ai/quickstart/)
 for ports, advanced indexing, and troubleshooting.
@@ -101,13 +171,15 @@ Install the MCP extra, build once, and serve the same repository manifest over
 stdio:
 
 ```bash
-pip install "codenib[mcp]"
+python -m pip install "codenib[mcp,semantic]==0.2.0"
 codenib index /path/to/repository
 codenib mcp /path/to/repository
 ```
 
-The MCP server advertises its full tool set and uses the compiled manifest to
-decide which calls have a fresh backing view. An agent can therefore reuse
+The MCP server advertises `search_context` as its default ranked entry point,
+then exposes the underlying BM25, vector, graph, and navigation operations for
+explicit control. It uses the compiled manifest to decide which calls have a
+fresh backing view. An agent can therefore reuse
 available repository work instead of rebuilding context through unbounded
 `grep` and `read` loops, while unavailable searches fail explicitly. BM25,
 semantic, regex, Zoekt, dependency, and static-navigation results retain source
@@ -115,15 +187,31 @@ locations for follow-up reads and citations. See
 [MCP Server](https://docs.codenib.ai/mcp/)
 for client configuration and tool contracts.
 
+The same planner is available directly to Python agents:
+
+```python
+from codenib.agent import RepositoryContextExplorer
+
+with RepositoryContextExplorer.from_repository(
+    "/path/to/repository", policy="auto"
+) as explorer:
+    result = explorer.explore("where is request retry behavior implemented?", top_k=10)
+```
+
+Each result includes source-validated evidence plus the selected plan,
+capabilities, loaded views, fusion, graph, and reranking trace.
+
 ## What CodeNib Provides
 
 | Surface | Purpose |
 |---|---|
 | Incremental compiler | Build independently managed views, reuse unchanged content, repair supported transitions, and conservatively rebuild outside those boundaries |
 | Agent context runtime | Plan capability-aware retrieval and navigation, then assemble bounded source-linked evidence |
-| Retrieval | BM25, dense-vector, regex/trigram, Zoekt, fusion, and reranking paths |
+| Retrieval | BM25, dense-vector, regex/trigram, Zoekt, fusion, and reranking paths; see the [validated model matrix](https://docs.codenib.ai/rag_ops/#validated-models) |
 | Structural context | SCIP/LSP-backed symbol graphs with source locations and typed edges |
 | MCP and LSP-shaped tools | Serve one manifest to coding agents without tying the runtime to one agent framework |
+| Agent compatibility | Reuse one manifest across revision-pinned [LocAgent](https://github.com/gersteinlab/LocAgent), [Agentless](https://github.com/OpenAutoCoder/Agentless), [CoSIL](https://github.com/ZhonghaoJiang/CoSIL), and [OrcaLoca](https://github.com/fishmingyu/OrcaLoca) contracts; see the [support matrix](https://docs.codenib.ai/agent_integrations/) |
+| Benchmark compatibility | Evaluate native exploration against pinned external datasets and scorers, including [SWE-Explore](https://github.com/Qiushao-E/SWE-Explore-Bench); see the [dataset and benchmark matrix](https://docs.codenib.ai/evaluation/) |
 | Local inspection | Audit the same context through Wiki pages, Ask answers, citations, and the Dependency Map |
 | Evaluation harness | Measure retrieval, navigation, incremental maintenance, and context policies on the same artifacts |
 
@@ -134,7 +222,11 @@ records chunking, graph, incremental, and C++ decoder support.
 ## Documentation
 
 - [Quickstart](https://docs.codenib.ai/quickstart/)
+- [GitHub Pages](https://docs.codenib.ai/github_pages/)
 - [MCP Server](https://docs.codenib.ai/mcp/)
+- [Agent Integrations](https://docs.codenib.ai/agent_integrations/)
+- [RAG Models and Planner](https://docs.codenib.ai/rag_ops/)
+- [Benchmarks and Evaluation](https://docs.codenib.ai/evaluation/)
 - [Web UI](https://docs.codenib.ai/web_demo/)
 - [Language Capabilities](https://docs.codenib.ai/language_capabilities/)
 - [Concepts and development guides](https://docs.codenib.ai/)
@@ -142,7 +234,7 @@ records chunking, graph, incremental, and C++ decoder support.
 Build the documentation site locally with:
 
 ```bash
-pip install "codenib[dev]"
+python -m pip install -e ".[dev]"
 mkdocs serve
 ```