codenib 0.2.0__tar.gz → 0.2.2__tar.gz

codenib-0.2.2/CHANGELOG.md

@@ -0,0 +1,202 @@
+<!--
+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.2] - 2026-08-21
+
+### Added
+
+- Persistent, exact repository-relative source exclusions through
+  `--exclude-dir` and `--clear-exclude-dirs`, with one recorded policy reused
+  by CodeGraph, indexing, MCP, Wiki, Web, and public compiler entry points.
+- Manifest 1.2 source-selection identities and builder receipts, while retaining
+  strict read compatibility for manifest 1.1 artifacts.
+- Authenticated optional SCIP occurrence-sidecar receipts bound to the same
+  owned symbol-graph generation as `graph.pkl`.
+
+### Changed
+
+- Authenticated indexing now accepts absolute symbolic links only when their
+  lexical target remains inside the same pinned repository authority. Expo,
+  CocoaPods, and pnpm-style contained link layouts no longer require a broad
+  default-ignore rule.
+- CodeGraph status reports the effective source selection, and Wiki, publish,
+  doctor, and toolchain flows reuse it instead of silently widening the source
+  surface.
+- Manifest-bound C and C++ queries temporarily use the verified persisted
+  symbol graph instead of consuming project-local clangd postings directly.
+
+### Security
+
+- Source paths, graph artifacts, native query routes, and retained manifests
+  are checked against the same authenticated source selection before they can
+  be published or served. Unproven native routes fail closed to the persisted
+  graph.
+- Zoekt builds use a fixed commit-tree contract, private generation
+  publication, and an authenticated shard-tree receipt; custom exclusions are
+  rejected until the backend can prove that narrower surface end to end.
+- Authenticated MCP `search_zoekt` serving uses a retained Linux `/proc`
+  descriptor snapshot. Other platforms fail closed until they have an
+  equivalent immutable runtime handoff.
+
+## [0.2.1] - 2026-08-14
+
+### Added
+
+- A one-command `codenib codegraph init` path that installs repository-aware
+  graph providers, builds BM25 and symbol-graph views, and configures installed
+  Codex and Claude Code clients through their native MCP CLIs.
+- Machine-readable CodeGraph status, idempotent client receipts, safe uninstall,
+  and a no-write dry run.
+- Installed-wheel black-box coverage for `explore_context`,
+  `dependency_subgraph`, both client contracts, repeat initialization, and
+  checkout cleanliness.
+
+### Changed
+
+- The primary agent quickstart now leads with the local, model-free CodeGraph;
+  the Wiki and semantic routes remain available as independent product paths.
+
+### Security
+
+- Client setup refuses unmanaged name collisions and drifted managed
+  registrations. Uninstall removes only receipt-owned entries and preserves
+  repository indexes.
+
+## [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.2...HEAD
+[0.2.2]: https://github.com/sysevol-ai/CodeNib/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/sysevol-ai/CodeNib/compare/v0.2.0...v0.2.1
+[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.2.2/MANIFEST.in

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+graft web
+include native/workspace_owner.c
+include CHANGELOG.md
+include CONTRIBUTING.md
+include server.json
+prune web/.next
+prune web/node_modules
+prune web/playwright-report
+prune web/test-results
+global-exclude *.py[cod]

codenib-0.2.2/PKG-INFO

@@ -0,0 +1,446 @@
+Metadata-Version: 2.4
+Name: codenib
+Version: 0.2.2
+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
+Project-URL: Documentation, https://docs.codenib.ai/
+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 :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: filelock>=3.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rank_bm25>=0.2.2
+Requires-Dist: regex>=2024.11.6
+Requires-Dist: rich>=14.0.0
+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.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
+Requires-Dist: igraph>=0.11.6; extra == "graph"
+Requires-Dist: protobuf>=3.20.0; extra == "graph"
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0.0; extra == "mcp"
+Provides-Extra: semantic
+Requires-Dist: einops>=0.8.0; extra == "semantic"
+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.3.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: serving
+Requires-Dist: numpy>=1.24.0; extra == "serving"
+Requires-Dist: sse-starlette>=2.0.0; extra == "serving"
+Requires-Dist: torch>=2.2.0; extra == "serving"
+Requires-Dist: transformers>=5.15.0; extra == "serving"
+Provides-Extra: vertex
+Requires-Dist: litellm[google]>=1.93.0; extra == "vertex"
+Provides-Extra: zoekt
+Requires-Dist: requests>=2.25.0; extra == "zoekt"
+Provides-Extra: full
+Requires-Dist: datasets>=4.0.0; extra == "full"
+Requires-Dist: einops>=0.8.0; extra == "full"
+Requires-Dist: faiss-cpu>=1.7.0; extra == "full"
+Requires-Dist: igraph>=0.11.6; extra == "full"
+Requires-Dist: litellm[google]>=1.93.0; extra == "full"
+Requires-Dist: mcp<3,>=2.0.0; extra == "full"
+Requires-Dist: numpy>=1.24.0; extra == "full"
+Requires-Dist: openai>=1.0.0; extra == "full"
+Requires-Dist: protobuf>=3.20.0; extra == "full"
+Requires-Dist: requests>=2.25.0; extra == "full"
+Requires-Dist: sentence-transformers>=2.3.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: black>=22.3.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+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: igraph>=0.11.6; 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"
+Requires-Dist: openai>=1.0.0; extra == "test"
+Requires-Dist: protobuf>=3.20.0; extra == "test"
+Requires-Dist: pytest>=6.0.0; extra == "test"
+Requires-Dist: pytest-cov>=3.0.0; extra == "test"
+Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
+Requires-Dist: requests>=2.25.0; extra == "test"
+Requires-Dist: sentence-transformers>=2.3.0; extra == "test"
+Requires-Dist: sse-starlette>=2.0.0; extra == "test"
+Requires-Dist: tomli>=1.1.0; python_version < "3.11" and extra == "test"
+Dynamic: license-file
+
+<!--
+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>Searchable codebase wikis and context for coding agents</h1>
+  <p>
+    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>
+    &nbsp;&middot;&nbsp;
+    <a href="https://codenib.ai">Website</a>
+    &nbsp;&middot;&nbsp;
+    <a href="https://discord.gg/ySer6CGn4">Discord</a>
+    &nbsp;&middot;&nbsp;
+    <a href="https://docs.codenib.ai/">Documentation</a>
+    &nbsp;&middot;&nbsp;
+    <a href="https://docs.codenib.ai/codegraph/">CodeGraph</a>
+    &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-full.yml"><img src="https://github.com/sysevol-ai/CodeNib/actions/workflows/ci-full.yml/badge.svg" alt="CI"></a>
+    <a href="https://pypi.org/project/codenib/"><img src="https://img.shields.io/pypi/v/codenib.svg?cacheSeconds=300" alt="PyPI version"></a>
+    <a href="https://docs.codenib.ai/codegraph/#one-command-setup"><img src="https://img.shields.io/badge/Claude_Code-D97757?logo=claude&amp;logoColor=fff" alt="Claude Code supported"></a>
+    <a href="https://docs.codenib.ai/codegraph/#one-command-setup"><img src="https://img.shields.io/badge/Codex-000?logo=openai&amp;logoColor=fff" alt="Codex supported"></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-0.2.2-2563EB.svg" alt="CodeNib 0.2.2">
+  </p>
+</div>
+
+```bash
+python -m pip install "codenib[graph,mcp]==0.2.2"
+codenib codegraph init /path/to/your/repo
+```
+
+That one command detects the repository languages, installs the pinned
+package-level graph providers it can manage, builds BM25 plus a source-linked
+symbol graph, and registers the resulting MCP server with installed Codex and
+Claude Code clients. It is local, open source, requires no model or cloud, and
+does not write configuration or indexes into the target repository.
+
+## News
+
+- **2026-08-21 — CodeNib 0.2.2 repository source authority.** Authenticated
+  indexing now admits absolute symlinks only when they resolve inside the same
+  pinned checkout, and exact root-relative exclusions persist across indexing,
+  CodeGraph, MCP, Wiki, and Web runtimes.
+  [Release notes](https://docs.codenib.ai/releases/0.2.2/)
+- **2026-08-13 — CodeNib 0.2.1 CodeGraph onboarding.** One command prepares a
+  repository graph and connects it to Codex and Claude Code, with idempotent
+  status, safe uninstall, and installed-wheel MCP graph verification.
+  [CodeGraph guide](https://docs.codenib.ai/codegraph/)
+- **2026-08-08 — RepoNavigator Jump adapter.** The published single-tool
+  [RepoNavigator](https://arxiv.org/abs/2512.20957v6) contract now resolves
+  symbol definitions through a persisted SCIP occurrence or injected LSP
+  signal, with graph-only resolution disclosed as a degraded fallback.
+  [Support boundary](https://docs.codenib.ai/agent_integrations/#reponavigator)
+- **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
+
+| Layer | Responsibility |
+|---|---|
+| View compiler | Chunk source and materialize BM25, dense, graph, and navigation views; reuse current artifacts and atomically rebuild affected views |
+| View manifest | Record repository identity, source fingerprint, builder profile, capabilities, status, and artifact location independently for each view |
+| Context serving | Execute lexical, semantic, hybrid, reranked, and structural query plans while preserving repository-relative source locations |
+| Agent runtime | Expose capability-aware MCP and LSP-shaped tools, assemble bounded evidence, and return citations that agents and humans can inspect |
+
+```text
+repository change
+  -> reuse current views or rebuild affected views
+  -> publish a capability-bearing manifest
+  -> plan repository queries
+  -> deliver bounded, source-linked context
+```
+
+On a later commit, CodeNib reuses views whose source and builder identities are
+still current. A requested view affected by source or policy changes currently
+rebuilds in an isolated generation; file- and symbol-level delta repair remains
+disabled until it can use the same pinned source authority.
+
+## Quickstart
+
+Requires Python 3.10+ and Git. For an agent-ready CodeGraph with no model or API
+key, install the graph and MCP extras and run one command:
+
+```bash
+python -m pip install "codenib[graph,mcp]==0.2.2"
+codenib codegraph init /path/to/repository
+```
+
+`codegraph init` detects Codex and Claude Code, installs only the detected
+languages' package-managed providers, builds reusable `bm25` and
+`symbol_graph` views, and asks each native client CLI to own its configuration.
+Run `codenib codegraph status /path/to/repository` to diagnose the complete
+path or `codenib codegraph uninstall /path/to/repository` to remove only the
+managed client registrations. The index remains reusable.
+
+Repositories can persist exact root-relative subtree exclusions when generated
+or vendored content should not be indexed:
+
+```bash
+codenib codegraph init /path/to/repository \
+  --exclude-dir ios/Pods \
+  --exclude-dir generated/api
+```
+
+Paths use repository-relative POSIX spelling (`/`) and name exact subtrees,
+not globs. Repeat `--exclude-dir` to replace the complete custom exclusion set. Later
+`init` and `index` runs reuse that policy from the manifest; use
+`--clear-exclude-dirs` to return to the default source surface. CodeNib does not
+implicitly treat `.gitignore` as an indexing policy, because tracked and local
+ignored source can still be intentional input.
+
+Zoekt supports the default source policy only when its fixed commit tree
+exactly matches the authenticated checkout and contains no tracked path that
+the default policy excludes. It does not currently support a non-empty custom
+exclusion set. A command that explicitly requests the `zoekt` view, including
+`--preset full`, fails closed when either condition is unmet; use the
+CodeGraph, `fast`, or semantic paths instead.
+In 0.2.2 the authenticated MCP `search_zoekt` runtime requires Linux `/proc`
+so the child process can inherit the exact retained shard generation; other
+platforms fail closed instead of reopening a mutable shard path.
+
+For a browser Wiki with hybrid BM25+dense retrieval, install the semantic extra:
+
+```bash
+python -m pip install "codenib[semantic]==0.2.2"
+codenib wiki /path/to/repository
+```
+
+Both paths keep reusable state under `~/.codenib/repositories` and leave the
+target checkout unchanged. Set `CODENIB_HOME` to relocate state. The
+[0.2.2 release notes](https://docs.codenib.ai/releases/0.2.2/) record the
+upgrade boundary and installed-product evidence.
+
+Preview the CodeGraph operations without installing, indexing, or configuring
+an agent:
+
+```bash
+codenib codegraph init /path/to/repository --dry-run
+```
+
+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.2"
+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 builds or reuses 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.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sysevol-ai/CodeNib/main/assets/codenib_wiki.png" alt="CodeNib Wiki showing the source-linked reverse proxy guide for Caddy" width="100%">
+</p>
+
+## Serve An Agent
+
+The recommended path configures installed Codex and Claude Code clients through
+their native CLIs:
+
+```bash
+python -m pip install "codenib[graph,mcp]==0.2.2"
+codenib codegraph init /path/to/repository
+```
+
+Ask the agent to start with `explore_context` for bounded, source-verified
+repository context and use `dependency_subgraph` for caller impact or callee
+dependencies. The MCP server also exposes ranked BM25, regex, definition,
+reference, route, and bounded source-read tools. See the
+[CodeGraph guide](https://docs.codenib.ai/codegraph/) for client scopes,
+diagnostics, uninstall behavior, and language prerequisites, and the
+[MCP Server](https://docs.codenib.ai/mcp/) for the complete tool contract.
+
+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 |
+|---|---|
+| View compiler | Build independently managed views, reuse current generations, and atomically rebuild changed views under one source identity |
+| 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; 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, plus the published [RepoNavigator](https://arxiv.org/abs/2512.20957v6) `jump` contract over SCIP/LSP definition signals; 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 |
+
+Language support varies by surface. The generated
+[capability matrix](https://docs.codenib.ai/language_capabilities/)
+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/)
+
+Build the documentation site locally with:
+
+```bash
+python -m pip install -e ".[dev]"
+mkdocs serve
+```
+
+## Development
+
+```bash
+git clone https://github.com/sysevol-ai/CodeNib.git
+cd CodeNib
+make dev
+make test
+```
+
+The test suite is split into unit, integration, serial integration, core,
+graph-consumer, and slow tiers. See
+[CI/CD](https://docs.codenib.ai/ci_cd/) before
+running the credential- or toolchain-dependent tiers.
+
+## Status
+
+CodeNib `0.2.2` is a beta release. The CLI and manifest format are usable, but
+public interfaces may still change before a stable release. Historical
+research artifacts retain their published dataset identifiers; the maintained
+package, import namespace, commands, and repository use `CodeNib`. See
+[Naming](https://docs.codenib.ai/branding/).
+
+## Citation
+
+If you use CodeNib in your research, please cite our
+[arXiv paper](https://arxiv.org/abs/2607.25431):
+
+```bibtex
+@misc{yu2026codenibmultiviewdataserving,
+      title={CodeNib: A Multi-View Data System for Serving Repository Context to Coding Agents},
+      author={Zhongming Yu and Hengjia Yu and Boqin Yuan and Shuting Zhao and Yizhao Chen and Aryan Dokania and Mihir Jagtap and Jiayu Chang and Yitong Ma and Yash Jayswal and Wentao Ni and Hejia Zhang and Zhaoling Chen and Gangda Deng and Jishen Zhao},
+      year={2026},
+      eprint={2607.25431},
+      archivePrefix={arXiv},
+      primaryClass={cs.SE},
+      url={https://arxiv.org/abs/2607.25431},
+}
+```
+
+## Project
+
+[Website](https://codenib.ai)
+&nbsp;&middot;&nbsp;
+[Changelog](https://github.com/sysevol-ai/CodeNib/blob/main/CHANGELOG.md)
+&nbsp;&middot;&nbsp;
+[Contributing](https://github.com/sysevol-ai/CodeNib/blob/main/CONTRIBUTING.md)
+
+## License
+
+CodeNib is licensed under the
+[Apache License, Version 2.0](https://github.com/sysevol-ai/CodeNib/blob/main/LICENSE).