grag-mcp 0.2.0__tar.gz

grag_mcp-0.2.0/.dockerignore

@@ -0,0 +1,19 @@
+.venv
+.git
+.github
+.pytest_cache
+.ruff_cache
+.mypy_cache
+__pycache__
+*.pyc
+.env
+models
+tests
+examples
+scripts
+# ...except the model-fetch script, which the builder stage runs to vendor the
+# embedding model into the image.
+!scripts/fetch_model.py
+training-docs
+docs
+.claude

grag_mcp-0.2.0/.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+
+[*.py]
+indent_size = 4
+max_line_length = 100
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

grag_mcp-0.2.0/.env.example

@@ -0,0 +1,26 @@
+# Copy to .env and adjust for local dev. Never commit the real .env.
+
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=changeme-local-dev
+NEO4J_URI=bolt://localhost:7687
+
+# MCP server
+MCP_HOST=127.0.0.1
+MCP_PORT=8765
+MCP_AUTH_TOKEN=
+
+# Base images for `docker compose`. Override in restricted environments that
+# only allow approved hardened images. Defaults match what CI builds/scans.
+# See docs/operations.md "Restricted / hardened-registry environments".
+#
+# Docker Hardened Images (needs `docker login dhi.io`; Select/Enterprise
+# subscribers swap `dhi.io/` for `<your-org>/`). DHI's Neo4j is Community
+# edition on the same CalVer stream as the official image, but has no
+# wget/curl or awk — set NEO4J_PLUGINS= and preload the apoc/gds jars into
+# the neo4j_plugins volume. BUILDER is a throwaway stage (-dev = has a
+# shell); RUNTIME's own Python is unused. See docs/operations.md.
+# NEO4J_IMAGE=dhi.io/neo4j:2026
+# NEO4J_PLUGINS=
+# BUILDER_IMAGE=dhi.io/python:3-dev
+# RUNTIME_IMAGE=dhi.io/python:3
+# UV_IMAGE=<registry>/uv:0.12.5

grag_mcp-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,56 @@
+name: Bug report
+description: Something isn't working as documented
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. Please search existing issues first.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you expected vs. what actually occurred.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Exact commands / MCP calls / inputs. A minimal repro helps a lot.
+      placeholder: |
+        1. make up && make apply-schema
+        2. uv run grag-mcp ingest ...
+        3. ...
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / traceback
+      render: shell
+  - type: input
+    id: version
+    attributes:
+      label: Version / commit
+      description: Output of `git rev-parse --short HEAD` or the release tag.
+    validations:
+      required: true
+  - type: dropdown
+    id: run-mode
+    attributes:
+      label: How are you running it?
+      options:
+        - CLI (uv run grag-mcp ...)
+        - MCP server (make mcp-serve)
+        - docker compose
+        - Other / not sure
+    validations:
+      required: true
+  - type: input
+    id: env
+    attributes:
+      label: OS, Python, Neo4j image
+      placeholder: "macOS 15 / Python 3.12.4 / neo4j:2026.07.1"
+    validations:
+      required: true

grag_mcp-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question / discussion
+    url: https://github.com/tmustafiz/graph-rag/discussions
+    about: Ask usage questions or propose ideas before opening an issue.
+  - name: Security vulnerability
+    url: https://github.com/tmustafiz/graph-rag/security/advisories/new
+    about: Report privately. Do not open a public issue for security problems.

grag_mcp-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,44 @@
+name: Feature request
+description: Suggest a new capability or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What are you trying to do that's hard or impossible today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What should happen? Sketch the CLI flag / MCP tool / config if you can.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Ingestion / parsers
+        - Retrieval / ranking
+        - Graph schema / enrichment
+        - MCP tools
+        - Agent memory
+        - Embeddings backend
+        - Ops / deployment
+        - Docs
+        - Other
+    validations:
+      required: true
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Contribution
+      options:
+        - label: I'm willing to open a PR for this

grag_mcp-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,30 @@
+<!-- Thanks for contributing! Keep PRs focused; open an issue first for anything non-trivial. -->
+
+## Summary
+
+<!-- What does this change and why? -->
+
+## Related issue
+
+Closes #
+
+## Changes
+
+-
+
+## Verification
+
+```
+# paste the commands you ran and their results
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest -q
+```
+
+## Checklist
+
+- [ ] Lint, format, and tests pass locally
+- [ ] Tests added/updated for the change
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] Follows the one-class-per-file convention (see `CONTRIBUTING.md`)
+- [ ] Docs updated (README / `docs/`) if behavior or interfaces changed

grag_mcp-0.2.0/.github/copilot-instructions.md

@@ -0,0 +1,105 @@
+# GitHub Copilot instructions — graph-rag
+
+These rules are prepended to every Copilot request in this repo. The full
+reference is [`AGENTS.md`](../AGENTS.md); this file is the short version.
+
+## What this project is
+
+A local-first **Graph RAG knowledge base for coding agents**. It ingests
+PDF / Markdown / Python / YAML(Checkov) into a **Neo4j** knowledge graph and
+serves hybrid retrieval + the agent's own working memory over an **MCP** server
+(Streamable HTTP, default `http://127.0.0.1:8765/mcp`). Runs entirely locally;
+the embedding model is local.
+
+## Names — do not mix these up
+
+| Thing | Value |
+| --- | --- |
+| PyPI distribution + CLI command | `grag-mcp` |
+| Python import package + `src/` dir | `graph_rag` |
+| GitHub repo | `graph-rag` |
+| MCP server identity (`MCPServer(name=…)`, `graph-rag://sources`) | `graph-rag` — never rename |
+
+CLI is invoked as `uv run grag-mcp <verb>` (or `grag-mcp <verb>` once installed).
+Verbs: `status`, `apply-schema`, `ingest`, `serve-mcp` (`--stdio` for stdio
+transport), `compute-centrality`, `prune-memory`, `eval-retrieval`.
+
+## How to work
+
+- **Think first.** State assumptions. If the request has multiple reasonable
+  readings, present them — don't silently pick one.
+- **Simplest thing that works.** No speculative abstractions, no unrequested
+  features. If 200 lines could be 50, write 50.
+- **Surgical diffs.** Touch only what the task needs. Don't reformat or refactor
+  adjacent code. Remove only dead code your change created.
+- **No false completion.** Complete, runnable code — never stubs or `TODO`.
+  Never say "done" without running the verification below. If blocked, say so
+  and give the exact command to check.
+
+## Python standards
+
+- Python 3.12+, full type hints, Pydantic v2 for data crossing a boundary.
+- `ruff` for lint + format (`line-length = 100`, rules `E,F,I,UP,B`).
+- `pathlib.Path`, not `os.path`. Specific exception types, not bare `except`.
+- Dependency injection over module-level globals/singletons.
+- Avoid single-letter names.
+
+## One class per file (strict)
+
+- Every primary class in its own `lower_snake_case.py`; filename is the class
+  name in snake_case (`ParserRegistry` → `parser_registry.py`). Small helper
+  dataclasses/enums used only by that class may sit alongside it.
+- Every package has an `__init__.py` that re-exports its public classes
+  (`from .parser_registry import ParserRegistry`) and defines `__all__`.
+- Consumers import from the package (`from graph_rag.ingest import ParserRegistry`),
+  never the submodule. Within a package use relative imports (`from .x import X`).
+- A new file type = a new self-contained parser class registered in the registry.
+  Never a rewrite of the pipeline.
+
+## Verification — run before handing back
+
+```bash
+make lint                    # uv run ruff check .
+uv run ruff format --check .
+make test                    # uv run pytest
+make eval                    # ONLY if you touched chunking / embedding / ranking (needs Neo4j)
+```
+
+CI (`.github/workflows/ci.yml`) runs the first three on every PR, plus the
+retrieval eval and a Trivy scan of the Docker image.
+
+## Planning & PRs
+
+Planning lives on **GitHub**, not in the repo — Project board, milestones,
+issues. Branch from `main`, open a PR that says `Closes #<n>`, and let the repo
+owner merge and delete the branch. For a non-trivial task, post a `[CHECKPOINT]`
+comment on the issue/PR before starting (objective / done & verified / critical
+context / discarded paths / next step).
+
+## Don't break these
+
+- **Never commit `.env`** (gitignored). Only `.env.example` is tracked; its
+  placeholder password is `changeme-local-dev`.
+- The MCP server binds `127.0.0.1` only; origin / DNS-rebinding checks are
+  always on; `MCP_AUTH_TOKEN` (optional) adds a bearer check. Don't loosen these.
+- `NEO4J_IMAGE`, `BUILDER_IMAGE`, `RUNTIME_IMAGE`, `UV_IMAGE` are overridable for
+  hardened-registry environments — keep the public defaults, keep them
+  overridable. See [`docs/operations.md`](../docs/operations.md).
+- Neo4j needs the **APOC + GDS** plugins. The stock `neo4j` image auto-installs
+  them from `NEO4J_PLUGINS` in `docker-compose.yml`; hardened images need them
+  preloaded (see operations.md).
+- The repo ships **no document corpus**. `examples/` holds a tiny Checkov sample
+  set — that's it.
+
+## Report back in this format
+
+```
+**What changed**
+- <file>: <what and why>
+
+**Verification run**
+- <command> → <result>
+
+**Remaining issues / risks**
+- <list or "None">
+```

grag_mcp-0.2.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-minor-patch:
+        update-types: ["minor", "patch"]
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"

grag_mcp-0.2.0/.github/prompts/add-a-parser.prompt.md

@@ -0,0 +1,31 @@
+---
+mode: agent
+description: Add ingestion support for a new file type (a new parser class).
+---
+Add a parser for a new file type: ${input:fileType:e.g. reStructuredText / .rst}.
+
+This must be a small, isolated change — a new parser class registered in the
+registry. Do **not** modify the chunker, pipeline, graph writer, or existing
+parsers unless the new type genuinely requires it (say why if so).
+
+1. Read an existing parser to match the pattern — e.g.
+   `src/graph_rag/ingest/parsers/markdown_parser.py` (prose) or
+   `python_parser.py` (code). Note the return type (`ParsedDocument` / sections /
+   code entities) and how it's registered.
+2. Create `src/graph_rag/ingest/parsers/<snake_case>_parser.py` with one class,
+   `<PascalCase>Parser`, filename = class name in snake_case. One class per file.
+3. Register it: add it to the parser registry keyed by file extension, and
+   re-export it from the package `__init__.py` (`from .x_parser import XParser`,
+   add to `__all__`).
+4. Heavy or optionally-licensed third-party imports go **lazily inside the parse
+   method** with an actionable error if missing (see `pdf_parser.py`'s handling
+   of `pymupdf`) — never at module top. If it needs a new dependency, add it as
+   an optional extra in `pyproject.toml`, not a base dependency.
+5. Tests in `tests/test_<snake_case>_parser.py`: a normal parse, an empty file,
+   and the missing-dependency error path if step 4 applies.
+6. Verify: `make lint`, `uv run ruff format --check .`, `make test`. Run
+   `make eval` only if you touched chunking/embedding/ranking.
+7. Update `CHANGELOG.md` (`[Unreleased]`) and the file-type list in `README.md`
+   and `docs/ARCHITECTURE.md`.
+
+Report in the What changed / Verification run / Remaining issues format.

grag_mcp-0.2.0/.github/prompts/configure-dev-environment.prompt.md

@@ -0,0 +1,21 @@
+---
+mode: agent
+description: Set up a local graph-rag dev environment from a fresh clone.
+---
+Get this repo running locally from a fresh clone.
+
+Steps:
+1. `cp .env.example .env`. Leave `NEO4J_PASSWORD=changeme-local-dev` unless the
+   user asked to change it. Never commit `.env`.
+2. `make install` (`uv sync --all-extras`).
+3. `make fetch-model` — downloads `sentence-transformers/all-MiniLM-L6-v2` into
+   `models/all-MiniLM-L6-v2/` (~87 MB). Needs network once; after that
+   ingestion/tests can run with `HF_HUB_OFFLINE=1`.
+4. `make up` — starts Neo4j in Docker. The stock `neo4j` image auto-installs the
+   APOC + GDS plugins from `NEO4J_PLUGINS` in `docker-compose.yml`; nothing to
+   do. Wait until `make status` prints `Neo4j is reachable.`
+5. `make apply-schema` — constraints, full-text indexes, vector indexes.
+6. Verify: `make lint`, `make test`.
+
+Report which steps ran and their output. If `make fetch-model` can't reach
+`huggingface.co`, say so — ingestion will fail without the model.

grag_mcp-0.2.0/.github/prompts/cut-a-release.prompt.md

@@ -0,0 +1,31 @@
+---
+mode: agent
+description: Prepare a grag-mcp release (version bump, changelog, tag).
+---
+Prepare the ${input:version:e.g. 0.2.0} release of `grag-mcp`.
+
+Publishing is automated: pushing a `vX.Y.Z` tag triggers
+`.github/workflows/release.yml`, which builds and publishes to PyPI via Trusted
+Publishing (no stored token). Your job is to prepare the commit and tag.
+
+1. Bump `version` in `pyproject.toml` to `${input:version}`.
+2. `CHANGELOG.md`: turn the `[Unreleased]` section into
+   `[${input:version}] - <today's date, YYYY-MM-DD>`, add a fresh empty
+   `[Unreleased]`, and update the link definitions at the bottom.
+3. Sanity-check the build:
+   ```bash
+   uv build
+   uvx twine check dist/*
+   test "$(uv version --short)" = "${input:version}"
+   ```
+4. Commit on a branch (`release/v${input:version}`), open a PR that says
+   `Closes #<n>` if there's a release issue. Do **not** merge or push the tag —
+   the repo owner does that after merge:
+   ```
+   git tag v${input:version} && git push origin v${input:version}
+   ```
+5. Note in the PR that the PyPI Trusted Publisher for project `grag-mcp` and the
+   `pypi` GitHub Environment must already exist (one-time setup, owner's task).
+
+Do not rename the distribution, the import package, or the MCP server identity —
+see `AGENTS.md` → "Names".

grag_mcp-0.2.0/.github/prompts/deploy-with-compose.prompt.md

@@ -0,0 +1,28 @@
+---
+mode: agent
+description: Build and deploy the full stack (Neo4j + MCP server) with Docker Compose.
+---
+Deploy the whole stack with Docker Compose.
+
+1. `docker compose build` — multi-stage: the app venv is built against a
+   standalone CPython (via `uv`) and copied into a distroless runtime image
+   (no shell, non-root uid 65532). Entry point is `/app/.venv/bin/grag-mcp`.
+2. `docker compose up -d` — starts `graph-rag-neo4j` then `graph-rag-mcp`
+   (the latter waits on the Neo4j healthcheck). Ports are published on
+   `127.0.0.1` only: `7474`/`7687` (Neo4j), `8765` (MCP).
+3. Verify:
+   - `docker compose ps` — both up, `graph-rag-neo4j` healthy.
+   - `docker compose exec -T mcp-server grag-mcp status` → `Neo4j is reachable.`
+   - `curl` the MCP `initialize` (see `run-locally.prompt.md`) → 200,
+     `"serverInfo":{"name":"graph-rag"}`.
+   - `docker compose logs mcp-server` → `MCP server listening on …:8765/mcp`.
+
+Hardened / restricted registries: every base image is overridable via `.env`
+(`NEO4J_IMAGE`, `BUILDER_IMAGE`, `RUNTIME_IMAGE`, `UV_IMAGE`). For Docker
+Hardened Images the working set is `NEO4J_IMAGE=dhi.io/neo4j:2026` +
+`NEO4J_PLUGINS=` (that image has no wget/awk, so preload APOC/GDS jars into the
+`neo4j_plugins` volume), `BUILDER_IMAGE=dhi.io/python:3-dev`,
+`RUNTIME_IMAGE=dhi.io/python:3`. Full recipe and constraints:
+[`docs/operations.md`](../../docs/operations.md) → "Restricted / hardened-registry
+environments". Keep the tracked defaults public and overridable — don't hardcode
+a `dhi.io/...` image as the default.

grag_mcp-0.2.0/.github/prompts/run-locally.prompt.md

@@ -0,0 +1,33 @@
+---
+mode: agent
+description: Run the MCP server locally and ingest content into the graph.
+---
+Run graph-rag locally and load some content.
+
+Assumes the dev environment is configured (see
+`configure-dev-environment.prompt.md`) and Neo4j is up (`make up`,
+`make status` → `Neo4j is reachable.`).
+
+1. Ingest content:
+   - `make ingest INGEST_PATH=examples/checkov-policies` for the bundled sample,
+     or `uv run grag-mcp ingest <path>` for a file or directory the user names.
+   - Re-running is cheap: unchanged files (by content hash) are skipped.
+   - `--dry-run` previews without writing; `--watch` re-ingests on change.
+2. (Optional) `uv run grag-mcp compute-centrality` — GDS PageRank over the
+   `CodeEntity` CALLS/IMPORTS graph; needed for `get_central_code_entities`.
+   Requires Python source to have been ingested first.
+3. Serve:
+   - HTTP (default): `make mcp-serve` → `http://127.0.0.1:8765/mcp`.
+   - stdio (for clients that spawn the server): `uv run grag-mcp serve-mcp --stdio`.
+4. Smoke-test the HTTP server:
+   ```bash
+   curl -s -X POST http://127.0.0.1:8765/mcp \
+     -H 'Content-Type: application/json' \
+     -H 'Accept: application/json, text/event-stream' \
+     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}'
+   ```
+   Expect HTTP 200 with `"serverInfo":{"name":"graph-rag"}`.
+
+Do not change `MCP_HOST` to `0.0.0.0` on the host, and do not disable the
+origin / DNS-rebinding checks. Set `MCP_AUTH_TOKEN` in `.env` if the user wants
+a bearer-token gate.

grag_mcp-0.2.0/.github/release.yml

@@ -0,0 +1,31 @@
+# Configures GitHub's "Generate release notes" button and the notes attached to
+# published releases. Categories are matched by PR label, top to bottom.
+changelog:
+  exclude:
+    labels:
+      - duplicate
+      - invalid
+      - wontfix
+    authors:
+      - dependabot
+  categories:
+    - title: Features
+      labels:
+        - enhancement
+    - title: Fixes
+      labels:
+        - bug
+    - title: Build, CI & Ops
+      labels:
+        - "type: chore"
+        - "area: ops"
+    - title: Documentation
+      labels:
+        - documentation
+        - "area: docs"
+    - title: Dependencies
+      labels:
+        - dependencies
+    - title: Other changes
+      labels:
+        - "*"

grag_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,138 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    # Weekly, so a CVE disclosed against an otherwise-unchanged image still trips
+    # the `image` job (Mondays 07:00 UTC).
+    - cron: "0 7 * * 1"
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint & format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+      - name: ruff check
+        run: uv run ruff check .
+      - name: ruff format --check
+        run: uv run ruff format --check .
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+      - name: Cache embedding model
+        id: model-cache
+        uses: actions/cache@v6
+        with:
+          path: models/all-MiniLM-L6-v2
+          key: minilm-l6-v2-v1
+      - name: Fetch embedding model
+        if: steps.model-cache.outputs.cache-hit != 'true'
+        run: make fetch-model
+      - name: Run pytest
+        # Model is on disk (fetched or restored from cache) — no network needed.
+        env:
+          HF_HUB_OFFLINE: "1"
+        run: uv run pytest -q
+
+  eval:
+    name: Retrieval eval
+    runs-on: ubuntu-latest
+    services:
+      neo4j:
+        image: neo4j:2026.07.1
+        env:
+          NEO4J_AUTH: neo4j/testpassword
+        ports:
+          - 7687:7687
+          - 7474:7474
+        options: >-
+          --health-cmd "wget -qO- http://localhost:7474 || exit 1"
+          --health-interval 10s --health-timeout 5s --health-retries 20
+    env:
+      NEO4J_URI: bolt://localhost:7687
+      NEO4J_USER: neo4j
+      NEO4J_PASSWORD: testpassword
+      HF_HUB_OFFLINE: "1"
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+      - name: Cache embedding model
+        id: model-cache
+        uses: actions/cache@v6
+        with:
+          path: models/all-MiniLM-L6-v2
+          key: minilm-l6-v2-v1
+      - name: Fetch embedding model
+        if: steps.model-cache.outputs.cache-hit != 'true'
+        run: make fetch-model
+      - name: Apply schema and run retrieval eval
+        run: |
+          uv run grag-mcp apply-schema
+          uv run grag-mcp eval-retrieval
+
+  image:
+    name: Image build & CVE scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Build runtime image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          load: true
+          tags: graph-rag:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Trivy scan (fail on fixable HIGH/CRITICAL)
+        uses: aquasecurity/trivy-action@v0.36.0
+        # Pull the vuln DB from ECR, not GHCR, to dodge anonymous-pull rate limits.
+        env:
+          TRIVY_DB_REPOSITORY: public.ecr.aws/aquasecurity/trivy-db
+          TRIVY_JAVA_DB_REPOSITORY: public.ecr.aws/aquasecurity/trivy-java-db
+        with:
+          image-ref: graph-rag:ci
+          format: table
+          severity: HIGH,CRITICAL
+          # Only block on CVEs that actually have a fix — an unfixable base CVE
+          # shouldn't wedge every PR. Flip to false to tighten.
+          ignore-unfixed: true
+          exit-code: "1"