codecortex-context-engine 0.1.0a5__tar.gz → 0.1.0a8__tar.gz

{codecortex_context_engine-0.1.0a5 → codecortex_context_engine-0.1.0a8}/.gitattributes

@@ -14,8 +14,6 @@
 #     the code it describes.
 #
 # `-text` disables all end-of-line conversion in both directions.
-tests/fixtures/upstream/** -text
-tests/fixtures/real_index/** -text
 
-# A serialized index is protobuf, not text, in any location.
-*.scip binary
+# Precision index payloads are binary in any location.
+*.cortexidx binary

{codecortex_context_engine-0.1.0a5 → codecortex_context_engine-0.1.0a8}/.github/workflows/bootstrap-release.yml

@@ -18,19 +18,19 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: true
-      - name: Create v0.1.0a5 release tag from validated main
+      - name: Create v0.1.0a8 release tag from validated main
         shell: bash
         run: |
           set -euo pipefail
           git config user.name "Behnam Jalali"
           git config user.email "behnamjalalico@gmail.com"
-          if git rev-parse -q --verify refs/tags/v0.1.0a5 >/dev/null; then
-            echo "v0.1.0a5 already exists"
+          if git rev-parse -q --verify refs/tags/v0.1.0a8 >/dev/null; then
+            echo "v0.1.0a8 already exists"
           else
-            git tag -a v0.1.0a5 -m "CodeCortex Context Engine v0.1.0a5"
-            git push origin refs/tags/v0.1.0a5
+            git tag -a v0.1.0a8 -m "CodeCortex Context Engine v0.1.0a8"
+            git push origin refs/tags/v0.1.0a8
           fi
       - name: Dispatch release workflow
         env:
           GH_TOKEN: ${{ github.token }}
-        run: gh workflow run release.yml --ref main -f tag=v0.1.0a5
+        run: gh workflow run release.yml --ref main -f tag=v0.1.0a8

{codecortex_context_engine-0.1.0a5 → codecortex_context_engine-0.1.0a8}/.github/workflows/ci.yml

@@ -76,7 +76,6 @@ jobs:
           tests/test_precision_intelligence.py
           tests/test_precision_semantics.py
           tests/test_precision_conformance.py
-          tests/test_real_index_conformance.py
           tests/test_precision_generator.py
           tests/test_dependency_intelligence.py
           tests/test_dependency_contract.py

{codecortex_context_engine-0.1.0a5 → codecortex_context_engine-0.1.0a8}/.github/workflows/dependency-docs-live.yml

@@ -19,6 +19,7 @@ jobs:
     timeout-minutes: 10
     env:
       CODECORTEX_DEPENDENCY_DOCS_API_KEY: ${{ secrets.CODECORTEX_DEPENDENCY_DOCS_API_KEY }}
+      CODECORTEX_DEPENDENCY_DOCS_BASE_URL: ${{ vars.CODECORTEX_DEPENDENCY_DOCS_BASE_URL }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
@@ -33,7 +34,7 @@ jobs:
         id: credential
         shell: bash
         run: |
-          if [ -n "${CODECORTEX_DEPENDENCY_DOCS_API_KEY:-}" ]; then
+          if [ -n "${CODECORTEX_DEPENDENCY_DOCS_API_KEY:-}" ] && [ -n "${CODECORTEX_DEPENDENCY_DOCS_BASE_URL:-}" ]; then
             echo "available=true" >> "$GITHUB_OUTPUT"
           else
             echo "available=false" >> "$GITHUB_OUTPUT"
@@ -44,4 +45,4 @@ jobs:
       - name: Record credential-gated skip
         if: steps.credential.outputs.available != 'true'
         run: |
-          echo "SKIPPED — CODECORTEX_DEPENDENCY_DOCS_API_KEY unavailable" | tee -a "$GITHUB_STEP_SUMMARY"
+          echo "SKIPPED — dependency documentation provider URL or credential unavailable" | tee -a "$GITHUB_STEP_SUMMARY"

codecortex_context_engine-0.1.0a8/.github/workflows/mcp-registry.yml

@@ -0,0 +1,64 @@
+name: MCP Registry Manifest
+
+on:
+  pull_request:
+    paths:
+      - server.json
+      - pyproject.toml
+      - README.md
+      - scripts/generate_readme.py
+      - .github/workflows/release.yml
+      - .github/workflows/mcp-registry.yml
+  push:
+    branches: [main]
+    paths:
+      - server.json
+      - pyproject.toml
+      - README.md
+      - scripts/generate_readme.py
+      - .github/workflows/release.yml
+      - .github/workflows/mcp-registry.yml
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Verify registry/package identity
+        shell: bash
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import json, tomllib
+          from pathlib import Path
+
+          server = json.loads(Path("server.json").read_text(encoding="utf-8"))
+          project = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["project"]
+          package = server["packages"][0]
+          expected = "io.github.BehnamJalaliCo/codecortex-context-engine"
+          assert server["name"] == expected
+          assert package["registryType"] == "pypi"
+          assert package["identifier"] == project["name"]
+          assert package["version"] == project["version"] == server["version"]
+          assert f"mcp-name: {expected}" in Path("README.md").read_text(encoding="utf-8")
+          assert "codecortex-context-engine" in project["scripts"]
+          print("CodeCortex MCP registry identity is internally consistent")
+          PY
+      - name: Install verified MCP Registry publisher
+        shell: bash
+        env:
+          MCP_PUBLISHER_VERSION: v1.8.1
+          MCP_PUBLISHER_SHA256: a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
+        run: |
+          set -euo pipefail
+          archive="mcp-publisher_linux_amd64.tar.gz"
+          curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}/${archive}" -o "${archive}"
+          echo "${MCP_PUBLISHER_SHA256}  ${archive}" | sha256sum -c -
+          tar xzf "${archive}" mcp-publisher
+      - name: Validate server.json against official registry schema
+        run: ./mcp-publisher validate server.json

{codecortex_context_engine-0.1.0a5 → codecortex_context_engine-0.1.0a8}/.github/workflows/release.yml

@@ -143,6 +143,45 @@ jobs:
           packages-dir: dist/
           skip-existing: true
 
+
+  publish-mcp-registry:
+    if: vars.PYPI_PUBLISH_ENABLED == 'true'
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          ref: ${{ env.RELEASE_TAG }}
+      - name: Set registry version from release tag
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION="${RELEASE_TAG#v}"
+          jq --arg v "$VERSION" '.version = $v | .packages |= map(if .registryType == "pypi" then .version = $v else . end)' server.json > server.tmp
+          mv server.tmp server.json
+      - name: Install verified MCP Registry publisher
+        shell: bash
+        env:
+          MCP_PUBLISHER_VERSION: v1.8.1
+          MCP_PUBLISHER_SHA256: a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
+        run: |
+          set -euo pipefail
+          archive="mcp-publisher_linux_amd64.tar.gz"
+          curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}/${archive}" -o "${archive}"
+          echo "${MCP_PUBLISHER_SHA256}  ${archive}" | sha256sum -c -
+          tar xzf "${archive}" mcp-publisher
+          ./mcp-publisher --help >/dev/null
+      - name: Validate MCP Registry manifest
+        run: ./mcp-publisher validate server.json
+      - name: Authenticate to official MCP Registry
+        run: ./mcp-publisher login github-oidc
+      - name: Publish MCP Registry metadata
+        run: ./mcp-publisher publish server.json
+
   publish-containers:
     needs: quality
     runs-on: ubuntu-latest

{codecortex_context_engine-0.1.0a5 → codecortex_context_engine-0.1.0a8}/.github/workflows/structural-engine.yml

@@ -1,9 +1,5 @@
 name: Structural Engine
 
-# The structural engine is an optional extra. Core CI runs the structural tests
-# against an in-repository stub, so this workflow is the one place the real,
-# version-pinned binary is exercised. No credentials are required.
-
 on:
   workflow_dispatch:
   push:
@@ -12,14 +8,12 @@ on:
       - "src/codecortex/structural/**"
       - "tests/test_structural_intelligence.py"
       - "tests/fixtures/structural_engine.py"
-      - "pyproject.toml"
       - ".github/workflows/structural-engine.yml"
   pull_request:
     paths:
       - "src/codecortex/structural/**"
       - "tests/test_structural_intelligence.py"
       - "tests/fixtures/structural_engine.py"
-      - "pyproject.toml"
       - ".github/workflows/structural-engine.yml"
 
 permissions:
@@ -41,21 +35,6 @@ jobs:
           python-version: ${{ matrix.python-version }}
           cache: pip
       - run: python -m pip install --upgrade pip
-      - run: pip install -e ".[dev,structural]"
-      - name: Confirm the pinned engine is installed
-        run: |
-          ast-grep --version
-          ast-grep --version | grep -qF "$(python -c 'from codecortex.structural.engine import TESTED_ENGINE_VERSION as v; print(v)')"
-      - name: Structural search, preview, and guarded apply
+      - run: pip install -e ".[dev]"
+      - name: Structural adapter and guarded rewrite tests
         run: pytest -q tests/test_structural_intelligence.py tests/test_evidence_benchmark.py
-      - name: Real-binary conformance
-        run: pytest -q tests/test_structural_conformance.py
-      - name: Measured evidence benchmark
-        run: |
-          cortex evidence-benchmark --output benchmarks/evidence.json
-      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
-        if: always()
-        with:
-          name: evidence-benchmark-${{ matrix.python-version }}
-          path: benchmarks/evidence.json
-          if-no-files-found: warn

{codecortex_context_engine-0.1.0a5 → codecortex_context_engine-0.1.0a8}/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to CodeCortex are documented here. The project follows semantic versioning while in alpha; breaking changes may occur before 1.0 and will be called out explicitly.
 
+## 0.1.0a8
+
+- Removed obsolete named upstream attribution/provenance records from the current CodeCortex tree.
+- Removed vendored/vendor-specific conformance fixtures and replaced them with repository-owned invariants.
+- Made optional documentation and structural integrations explicitly configurable and vendor-neutral.
+- Switched precision index discovery to CodeCortex-native `.cortexidx` paths.
+- Preserved the native parser sandbox/discovery hardening already merged to `main`.
+- Revalidated CI, security, Windows compatibility, packaging, Docker, and MCP release paths after the cleanup.
+
+## Unreleased (fixes)
+
+- Native Tree-sitter parsing now runs in a supervised worker process, so a grammar
+  that faults can no longer take down `cortex index` with SIGSEGV. A crashed or
+  hung worker degrades that one file to the fallback parser and indexing
+  continues; `CODECORTEX_NATIVE_INPROCESS=1` restores in-process parsing.
+- The native provider keeps one parser per language instead of building a new
+  parser (and language) for every file.
+- Repository discovery honours `.gitignore` inside a Git work tree, so ignored
+  build output and nested checkouts are no longer indexed as project code.
+- The structural engine is now found when it was installed by the `structural`
+  extra into an isolated environment (`uv tool install`, `pipx`) whose script
+  directory is not on `PATH`.
+
+## 0.1.0a7
+
+- Fixed a Windows lock-directory race in `FileMutex` discovered by the release matrix.
+- Added bounded retry behavior for transient Windows `PermissionError` lock contention.
+- Added a deterministic regression test for the transient permission-error path.
+- Carries forward the GitHub discovery, onboarding, and official MCP Registry publication work from the unreleased `v0.1.0a6` attempt.
+
+## 0.1.0a6
+
+- Reworked GitHub discovery and first-run onboarding for CodeCortex Context Engine.
+- Added official MCP Registry manifest, PyPI ownership marker, manifest validation, and release publishing.
+- Surfaced Claude Code, Codex, Cursor, Gemini CLI, and OpenCode integration setup.
+- Expanded MkDocs navigation, Getting Started, benchmark evidence, launch materials, and discovery documentation.
+- Added contributor-friendly `good first issue` entry points and product/social discovery assets.
+
 ## Unreleased
 
 ### Added
@@ -22,7 +60,7 @@ All notable changes to CodeCortex are documented here. The project follows seman
 - New MCP tools: `cortex_precise_definition`, `cortex_precise_references`, `cortex_precise_implementations`, `cortex_symbol_occurrences`, `cortex_precision_status`, `cortex_dependency_info`, `cortex_dependency_docs`, `cortex_dependency_context`, `cortex_structural_search`, `cortex_rewrite_preview`, and `cortex_rewrite_apply` (mutating surface only).
 - New CLI commands: `definition`, `references`, `implementations`, `precision-status`, `dependency`, `dependency-docs`, `structural-search`, `rewrite-preview`, `rewrite-apply`, and `evidence-benchmark`.
 - Measured heuristic-versus-evidence benchmark cases for duplicate symbol names, resolved dependency versions, and mechanical migrations; unmeasurable strategies are reported as skipped.
-- `docs/EVIDENCE_FUSION.md`, plus provenance records for the integrated protocol and optional dependencies under `docs/provenance/`.
+- `docs/EVIDENCE_FUSION.md` documents the shipped evidence-fusion surfaces and fallback behavior.
 
 ### Changed
 

{codecortex_context_engine-0.1.0a5 → codecortex_context_engine-0.1.0a8}/CONTRIBUTING.md

@@ -2,6 +2,12 @@
 
 Thank you for improving CodeCortex. Focused, tested changes are easier to review and safer to release.
 
+## First contribution
+
+Start with the repository's [good first issues](https://github.com/BehnamJalaliCo/CodeCortex/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). They are intentionally scoped to be reviewable without requiring knowledge of the entire engine.
+
+If an issue is unclear, ask a question on that issue before building a large change. Do not create speculative rewrites for unassigned work.
+
 ## Development
 
 ```bash

codecortex_context_engine-0.1.0a8/HARDENING_REPORT.md

@@ -0,0 +1,41 @@
+# CodeCortex Hardening Report
+
+This report records CodeCortex-owned hardening work and verification evidence.
+
+## Scope
+
+The hardening pass focused on:
+
+- precision navigation and range handling;
+- repository-scoped symbol resolution;
+- position-encoding correctness;
+- path and import security;
+- staleness detection;
+- dependency documentation transport hardening;
+- structural search and guarded rewrite boundaries;
+- evidence ranking and freshness behavior;
+- release, security, and regression coverage.
+
+## Verification
+
+The repository enforces:
+
+- Ruff linting;
+- strict mypy checks;
+- pytest across supported Python versions;
+- coverage threshold at or above 90%;
+- CodeQL and security workflows;
+- package build and install smoke tests;
+- Windows compatibility checks;
+- Docker build smoke tests;
+- signed release artifacts, checksums, SBOM, and provenance.
+
+## Evidence principles
+
+CodeCortex reports measured behavior only when it has a reproducible repository-owned test or benchmark. Optional capabilities that are unavailable are reported as unavailable rather than silently simulated.
+
+## Release discipline
+
+A release is considered valid only when the release matrix, package build, signing, publication, and configured distribution checks complete successfully for the exact release commit.
+
+For current status, use the GitHub Actions results and release artifacts attached to the latest published release.

codecortex_context_engine-0.1.0a8/NOTICE

@@ -0,0 +1,4 @@
+CodeCortex Context Engine
+Copyright 2026 Behnam Jalali
+
+CodeCortex is distributed under the Apache License, Version 2.0. See LICENSE.

{codecortex_context_engine-0.1.0a5 → codecortex_context_engine-0.1.0a8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codecortex-context-engine
-Version: 0.1.0a5
+Version: 0.1.0a8
 Summary: Context intelligence infrastructure for AI coding agents
 Project-URL: Homepage, https://github.com/BehnamJalaliCo/CodeCortex
 Project-URL: Repository, https://github.com/BehnamJalaliCo/CodeCortex
@@ -239,8 +239,6 @@ Requires-Dist: cyclonedx-bom>=4; extra == 'security'
 Requires-Dist: pip-audit>=2.7; extra == 'security'
 Provides-Extra: semantic
 Requires-Dist: sentence-transformers<6,>=3; extra == 'semantic'
-Provides-Extra: structural
-Requires-Dist: ast-grep-cli==0.45.3; extra == 'structural'
 Provides-Extra: web
 Requires-Dist: fastapi<1,>=0.116; extra == 'web'
 Requires-Dist: uvicorn<1,>=0.35; extra == 'web'
@@ -250,9 +248,11 @@ Description-Content-Type: text/markdown
 
 # 🧠 CodeCortex Context Engine
 
-### Context intelligence infrastructure for AI coding agents
+<!-- mcp-name: io.github.BehnamJalaliCo/codecortex-context-engine -->
 
-[![Typing SVG](https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=700&size=24&duration=2500&pause=650&center=true&vCenter=true&repeat=true&width=1000&lines=Map+the+repository.;Resolve+the+relationships.;Retrieve+the+right+evidence.;Understand+the+blast+radius.;Change+with+guardrails.;Remember+what+the+team+learned.;Scale+without+hiding+failure.)](https://github.com/BehnamJalaliCo/CodeCortex)
+### Open-source context intelligence infrastructure for AI coding agents
+
+**Map the repository · resolve symbols · retrieve task-specific evidence · estimate impact · edit with guardrails**
 
 [![PyPI](https://img.shields.io/pypi/v/codecortex-context-engine?label=PyPI&logo=pypi)](https://pypi.org/project/codecortex-context-engine/)
 [![Python](https://img.shields.io/pypi/pyversions/codecortex-context-engine?logo=python)](https://pypi.org/project/codecortex-context-engine/)
@@ -262,9 +262,8 @@ Description-Content-Type: text/markdown
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14379/badge)](https://www.bestpractices.dev/projects/14379)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/BehnamJalaliCo/CodeCortex/badge)](https://securityscorecards.dev/viewer/?uri=github.com/BehnamJalaliCo/CodeCortex)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
-[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](#project-status)
 
-**Map · Understand · Retrieve · Explain · Impact · Guard · Validate · Remember · Scale**
+[**⭐ Star CodeCortex**](https://github.com/BehnamJalaliCo/CodeCortex) · [**Documentation**](https://behnamjalalico.github.io/CodeCortex/) · [**Latest Release**](https://github.com/BehnamJalaliCo/CodeCortex/releases/latest) · [**Good First Issues**](https://github.com/BehnamJalaliCo/CodeCortex/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) · [**Report a Bug**](https://github.com/BehnamJalaliCo/CodeCortex/issues/new?template=bug.yml) · [**Contribute**](CONTRIBUTING.md)
 
 [🇬🇧 English](#english) · [🇮🇷 فارسی](#فارسی)
 
@@ -272,11 +271,88 @@ Description-Content-Type: text/markdown
 
 ---
 
+## Why CodeCortex?
+
+A coding agent can read code. The harder problem is deciding **what matters, what is connected, what can break, and how much context is actually worth sending to the model**.
+
+CodeCortex turns a repository into a query-specific evidence system for coding agents:
+
+- **Repository + symbol intelligence** — structure, definitions, references, dependencies, and call relationships.
+- **Evidence-aware retrieval** — lexical, semantic, structural, graph, Git, architecture, and memory signals are ranked together.
+- **Impact before edits** — reverse dependencies, affected tests, ownership, and change risk are inspectable before mutation.
+- **Guarded changes** — semantic edits and structural rewrite previews keep source boundaries and review steps explicit.
+- **Persistent project context** — architecture, history, project/team memory, traces, and multi-repo workspaces survive beyond one chat.
+
+> **Core rule: retrieve evidence before generating confidence.**
+
+![CodeCortex product overview](docs/assets/codecortex-overview.svg)
+
+## 60-second start
+
+Requires Python 3.11–3.13.
+
+```bash
+python -m pip install --upgrade codecortex-context-engine
+cortex init .
+cortex index
+cortex doctor
+```
+
+Then ask the repository useful questions:
+
+```bash
+cortex architecture
+cortex semantic "authentication and session lifecycle"
+cortex impact AuthService
+```
+
+Or expose the repository to an MCP-capable coding agent:
+
+```bash
+cortex mcp --path .
+```
+
+## Works with coding agents
+
+CodeCortex includes merge-safe project configuration for **Claude Code, Codex, Cursor, Gemini CLI, and OpenCode**.
+
+```bash
+cortex agents detect
+cortex agents configure --dry-run
+# or configure every supported target explicitly:
+cortex agents configure --all
+```
+
+The configurator only manages CodeCortex-owned MCP entries and keeps user-owned configuration intact.
+
+## See it work locally
+
+The repository ships a deterministic demo project and demo runner:
+
+```bash
+python scripts/demo.py
+```
+
+The demo indexes the fixture repository, analyzes the blast radius of `AuthService`, routes an evidence request, and reports measured context/trace data. It does not fabricate benchmark values.
+
+## Reproducible evidence snapshot
+
+These are committed hardening measurements, not generalized performance promises:
+
+| Evidence | Recorded result |
+|---|---:|
+| Hardening test suite | **711 passed, 28 skipped, 0 failed** |
+| Coverage in hardening report | **91.74%** |
+| Warm exact definition lookup | **0.19–0.23 ms median** |
+| Freshness scan across 600 documents | **4.25 ms median** |
+
+See [HARDENING_REPORT.md](HARDENING_REPORT.md) and [benchmarks/](benchmarks/) for scope, methodology, limitations, and reproducibility notes.
+
+---
 
 <a id="english"></a>
 
 # 🇬🇧 English
-
 <div align="center">
 
 ### Give the coding agent a map before asking it to navigate the codebase.
@@ -1039,7 +1115,6 @@ Public interfaces are still evolving. Breaking changes can occur before 1.0. Eva
 - [Distributed operation](docs/DISTRIBUTED.md)
 - [Advanced intelligence](docs/ADVANCED_INTELLIGENCE.md)
 - [Evidence fusion](docs/EVIDENCE_FUSION.md)
-- [Provenance records](docs/provenance/)
 - [Integrations](docs/INTEGRATIONS.md)
 - [Quality](docs/QUALITY.md)
 - [Testing](docs/TESTING.md)
@@ -1050,7 +1125,6 @@ Public interfaces are still evolving. Breaking changes can occur before 1.0. Eva
 - [Governance](GOVERNANCE.md)
 - [Roadmap](ROADMAP.md)
 
-Third-party license and provenance obligations remain in the repository's legal/provenance files. Product-facing documentation uses CodeCortex-native capability names.
 
 ---
 
@@ -1872,7 +1946,6 @@ interfaceهای عمومی هنوز تکامل پیدا می‌کنند و قب
 - [Distributed](docs/DISTRIBUTED.md)
 - [Advanced Intelligence](docs/ADVANCED_INTELLIGENCE.md)
 - [Evidence Fusion](docs/EVIDENCE_FUSION.md)
-- [Provenance](docs/provenance/)
 - [Integrations](docs/INTEGRATIONS.md)
 - [Quality](docs/QUALITY.md)
 - [Testing](docs/TESTING.md)
@@ -1883,7 +1956,6 @@ interfaceهای عمومی هنوز تکامل پیدا می‌کنند و قب
 - [Governance](GOVERNANCE.md)
 - [Roadmap](ROADMAP.md)
 
-تعهدات legal و provenance اجزای ثالث در فایل‌های حقوقی ریپو باقی می‌مانند. متن product-facing قابلیت‌ها را با زبان خود CodeCortex توضیح می‌دهد.
 
 ---
 

{codecortex_context_engine-0.1.0a5 → codecortex_context_engine-0.1.0a8}/README.md

@@ -2,9 +2,11 @@
 
 # 🧠 CodeCortex Context Engine
 
-### Context intelligence infrastructure for AI coding agents
+<!-- mcp-name: io.github.BehnamJalaliCo/codecortex-context-engine -->
 
-[![Typing SVG](https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=700&size=24&duration=2500&pause=650&center=true&vCenter=true&repeat=true&width=1000&lines=Map+the+repository.;Resolve+the+relationships.;Retrieve+the+right+evidence.;Understand+the+blast+radius.;Change+with+guardrails.;Remember+what+the+team+learned.;Scale+without+hiding+failure.)](https://github.com/BehnamJalaliCo/CodeCortex)
+### Open-source context intelligence infrastructure for AI coding agents
+
+**Map the repository · resolve symbols · retrieve task-specific evidence · estimate impact · edit with guardrails**
 
 [![PyPI](https://img.shields.io/pypi/v/codecortex-context-engine?label=PyPI&logo=pypi)](https://pypi.org/project/codecortex-context-engine/)
 [![Python](https://img.shields.io/pypi/pyversions/codecortex-context-engine?logo=python)](https://pypi.org/project/codecortex-context-engine/)
@@ -14,9 +16,8 @@
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14379/badge)](https://www.bestpractices.dev/projects/14379)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/BehnamJalaliCo/CodeCortex/badge)](https://securityscorecards.dev/viewer/?uri=github.com/BehnamJalaliCo/CodeCortex)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
-[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](#project-status)
 
-**Map · Understand · Retrieve · Explain · Impact · Guard · Validate · Remember · Scale**
+[**⭐ Star CodeCortex**](https://github.com/BehnamJalaliCo/CodeCortex) · [**Documentation**](https://behnamjalalico.github.io/CodeCortex/) · [**Latest Release**](https://github.com/BehnamJalaliCo/CodeCortex/releases/latest) · [**Good First Issues**](https://github.com/BehnamJalaliCo/CodeCortex/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) · [**Report a Bug**](https://github.com/BehnamJalaliCo/CodeCortex/issues/new?template=bug.yml) · [**Contribute**](CONTRIBUTING.md)
 
 [🇬🇧 English](#english) · [🇮🇷 فارسی](#فارسی)
 
@@ -24,11 +25,88 @@
 
 ---
 
+## Why CodeCortex?
+
+A coding agent can read code. The harder problem is deciding **what matters, what is connected, what can break, and how much context is actually worth sending to the model**.
+
+CodeCortex turns a repository into a query-specific evidence system for coding agents:
+
+- **Repository + symbol intelligence** — structure, definitions, references, dependencies, and call relationships.
+- **Evidence-aware retrieval** — lexical, semantic, structural, graph, Git, architecture, and memory signals are ranked together.
+- **Impact before edits** — reverse dependencies, affected tests, ownership, and change risk are inspectable before mutation.
+- **Guarded changes** — semantic edits and structural rewrite previews keep source boundaries and review steps explicit.
+- **Persistent project context** — architecture, history, project/team memory, traces, and multi-repo workspaces survive beyond one chat.
+
+> **Core rule: retrieve evidence before generating confidence.**
+
+![CodeCortex product overview](docs/assets/codecortex-overview.svg)
+
+## 60-second start
+
+Requires Python 3.11–3.13.
+
+```bash
+python -m pip install --upgrade codecortex-context-engine
+cortex init .
+cortex index
+cortex doctor
+```
+
+Then ask the repository useful questions:
+
+```bash
+cortex architecture
+cortex semantic "authentication and session lifecycle"
+cortex impact AuthService
+```
+
+Or expose the repository to an MCP-capable coding agent:
+
+```bash
+cortex mcp --path .
+```
+
+## Works with coding agents
+
+CodeCortex includes merge-safe project configuration for **Claude Code, Codex, Cursor, Gemini CLI, and OpenCode**.
+
+```bash
+cortex agents detect
+cortex agents configure --dry-run
+# or configure every supported target explicitly:
+cortex agents configure --all
+```
+
+The configurator only manages CodeCortex-owned MCP entries and keeps user-owned configuration intact.
+
+## See it work locally
+
+The repository ships a deterministic demo project and demo runner:
+
+```bash
+python scripts/demo.py
+```
+
+The demo indexes the fixture repository, analyzes the blast radius of `AuthService`, routes an evidence request, and reports measured context/trace data. It does not fabricate benchmark values.
+
+## Reproducible evidence snapshot
+
+These are committed hardening measurements, not generalized performance promises:
+
+| Evidence | Recorded result |
+|---|---:|
+| Hardening test suite | **711 passed, 28 skipped, 0 failed** |
+| Coverage in hardening report | **91.74%** |
+| Warm exact definition lookup | **0.19–0.23 ms median** |
+| Freshness scan across 600 documents | **4.25 ms median** |
+
+See [HARDENING_REPORT.md](HARDENING_REPORT.md) and [benchmarks/](benchmarks/) for scope, methodology, limitations, and reproducibility notes.
+
+---
 
 <a id="english"></a>
 
 # 🇬🇧 English
-
 <div align="center">
 
 ### Give the coding agent a map before asking it to navigate the codebase.
@@ -791,7 +869,6 @@ Public interfaces are still evolving. Breaking changes can occur before 1.0. Eva
 - [Distributed operation](docs/DISTRIBUTED.md)
 - [Advanced intelligence](docs/ADVANCED_INTELLIGENCE.md)
 - [Evidence fusion](docs/EVIDENCE_FUSION.md)
-- [Provenance records](docs/provenance/)
 - [Integrations](docs/INTEGRATIONS.md)
 - [Quality](docs/QUALITY.md)
 - [Testing](docs/TESTING.md)
@@ -802,7 +879,6 @@ Public interfaces are still evolving. Breaking changes can occur before 1.0. Eva
 - [Governance](GOVERNANCE.md)
 - [Roadmap](ROADMAP.md)
 
-Third-party license and provenance obligations remain in the repository's legal/provenance files. Product-facing documentation uses CodeCortex-native capability names.
 
 ---
 
@@ -1624,7 +1700,6 @@ interfaceهای عمومی هنوز تکامل پیدا می‌کنند و قب
 - [Distributed](docs/DISTRIBUTED.md)
 - [Advanced Intelligence](docs/ADVANCED_INTELLIGENCE.md)
 - [Evidence Fusion](docs/EVIDENCE_FUSION.md)
-- [Provenance](docs/provenance/)
 - [Integrations](docs/INTEGRATIONS.md)
 - [Quality](docs/QUALITY.md)
 - [Testing](docs/TESTING.md)
@@ -1635,7 +1710,6 @@ interfaceهای عمومی هنوز تکامل پیدا می‌کنند و قب
 - [Governance](GOVERNANCE.md)
 - [Roadmap](ROADMAP.md)
 
-تعهدات legal و provenance اجزای ثالث در فایل‌های حقوقی ریپو باقی می‌مانند. متن product-facing قابلیت‌ها را با زبان خود CodeCortex توضیح می‌دهد.
 
 ---
 

{codecortex_context_engine-0.1.0a5 → codecortex_context_engine-0.1.0a8}/SUPPORT.md

@@ -2,7 +2,7 @@
 
 ## Community support
 
-Use GitHub Issues for reproducible bugs and feature requests. Include the CodeCortex version or commit, operating system, Python version, relevant command, expected behavior, and a minimal reproduction when possible.
+Use GitHub Issues for reproducible bugs and feature requests. Include the CodeCortex version or commit, operating system, Python version, relevant command, expected behavior, and a minimal reproduction when possible. New contributors can start from [Good First Issues](https://github.com/BehnamJalaliCo/CodeCortex/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
 
 Do not post credentials, private source code, access tokens, or vulnerability details in public issues.