agentforge-graph 0.3.2__tar.gz

agentforge_graph-0.3.2/.agentforge-state/answers.yml

@@ -0,0 +1,8 @@
+# AgentForge scaffold answers — DO NOT EDIT MANUALLY.
+# Used by `agentforge upgrade` to re-render managed template files.
+_template_name: minimal
+_template_version: 0.2.4
+project_name: Agentforge Graph
+project_slug: agentforge-graph
+llm_provider: anthropic
+description: An AgentForge agent (minimal).

agentforge_graph-0.3.2/.agentforge-state/managed-files.lock

@@ -0,0 +1,170 @@
+.cursorrules:
+  forked: false
+  hash: 8a75b914bdf3cadbde5693497f0c1812a67ee01fde9e2166e97006a299b78962
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+.env.example:
+  forked: false
+  hash: 45e023968759bfc3b10eee810fe2cde2033e8f80c998db5eda156b7ec1eccbe5
+  source_module: template:minimal
+  source_version: 0.2.4
+.github/copilot-instructions.md:
+  forked: false
+  hash: 23c6e939d9d162837a85f0e3859f8e5808327aa77380d2a8e07f5b8c91d423e2
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+.gitignore:
+  forked: false
+  hash: e2e64343502ba0a2753b9b76908c3861fcdcafa1f4052c9da02be123f3d7404a
+  source_module: template:minimal
+  source_version: 0.2.4
+.gitkeep:
+  forked: false
+  hash: 01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+AGENTS.md:
+  forked: false
+  hash: c2f4dad7b549ce1f78d932e03c00159080caa1569a25be4a03f2e33d795fe8e2
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+CLAUDE.md:
+  forked: false
+  hash: 9120f1c4a7740f3147e85b6010ea0c0cd12d09e886b496fd6d0b958e2239b469
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+README.md:
+  forked: false
+  hash: c474ab3012ec420a13389cd5cbfeebc1d69ee35b4f9ad0c6fb84a0404d820303
+  source_module: template:minimal
+  source_version: 0.2.4
+agentforge.yaml:
+  forked: false
+  hash: 3f971e1f7bac5a4d647849d5f6fcdf7b9cb7ad2e399247b38d66c726918e6d98
+  source_module: template:minimal
+  source_version: 0.2.4
+docs/runbooks/01-set-up-new-agent.md:
+  forked: false
+  hash: 9767d5fccc9a78206289504337f26b3ebfd18a62c4ec68c75d5684e64f2ff0d3
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/02-add-a-tool.md:
+  forked: false
+  hash: 54e75ed0aa463dcc143fbee577746b7d853ca19c7b31d4ed91557f2afb1b5f03
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/03-add-a-pipeline-task.md:
+  forked: false
+  hash: e02a38df57668ab1873d35c83c666bc0b3e4f01f9836babe1eb780eb3a3e3d0b
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/04-pick-reasoning-strategy.md:
+  forked: false
+  hash: abe78f8b53fe324f2b86c0a7c69822425c3e267ed232c83021baca0cf6eb804b
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/05-write-prompts.md:
+  forked: false
+  hash: 248e76f52c90220d05d1bb2ad1976643d8e68896e5888e9da4b5ccdbf25ccaae
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/06-test-your-agent.md:
+  forked: false
+  hash: 81af251a9a4ce45d3b80bf07ffd88173926363fa2e27d7c958279c3b760fdd9b
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/07-debug-a-run.md:
+  forked: false
+  hash: 336052b797bc5f39d29ed754fec76e37c50511515a765fbe874cacb1dd06165f
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/08-add-memory.md:
+  forked: false
+  hash: 34357485fbb087775cfd99e55500515795e7ff4207b1257b9b66b77b55e82ea5
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/09-add-mcp.md:
+  forked: false
+  hash: 3e945da99f484716937036b6dd4686a3f84b3784c877e3ef01166ea1b7399cb2
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/10-add-evaluators.md:
+  forked: false
+  hash: acfbdccaaad2ffb9c6fdd7a99de9a42a5fac365585d5cb7fd3e8230ee77bbf26
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/11-add-safety-guardrails.md:
+  forked: false
+  hash: c52053398767e28ec3d6c1e334a7b8fdf9359276ab3248ebdda956d0ec610daf
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/12-add-observability.md:
+  forked: false
+  hash: b9ce79b8f258b393fd9fc5d9aa4f453503399b3415ac893af3cfd158271302ec
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/13-configure-multi-provider.md:
+  forked: false
+  hash: 3587a253001bab61486c59c6f40e29a60b26c0ee0deed2167fa62e6de9cb04f7
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/14-deploy-your-agent.md:
+  forked: false
+  hash: e036df7d4cf3f2d144fb8dd05b747539483b507340fc3ea474c4d1e016424b29
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/15-upgrade-your-agent.md:
+  forked: false
+  hash: 81034a5ee4c294ab12d356461a75f065cb6c2cb42dcc23cc71ce05d0b11098ee
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/16-configuration-reference.md:
+  forked: false
+  hash: e2cf5067d2fb8ef6ba9e3c1f0f7a39f63082b9685ee687385a0bf2d115b014b6
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/17-add-reranker.md:
+  forked: false
+  hash: 2718f76d448ecbe0831c09bcd8431e914b911d487ef50dbb09a4c06bc7bfc36b
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/18-add-hybrid-search.md:
+  forked: false
+  hash: 4f5a8eabfd560ef02552ff24ce9f75288f87a096750cb04e6eb457989e954ba1
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/19-add-graphrag.md:
+  forked: false
+  hash: 39504e95e5eee24c3e533ceaacbb1479406c36d83969d53aca2fe1d06fb69a8f
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/20-apply-schema-migrations.md:
+  forked: false
+  hash: eef758aedb2670f7cbdbb1222b06f8f41e4a786852f344199bf1f5ec63ce2f24
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/21-use-streaming-guardrails.md:
+  forked: false
+  hash: 66b694aabc6e09a4c599d4e347044f8b21ce0c24feaea3157349a667e428d518
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+docs/runbooks/README.md:
+  forked: false
+  hash: baeef86ba55cd2185c5ae2fa3b070771dd90e6e19fa9826472ea5f7772b7b249
+  source_module: template:minimal:_shared
+  source_version: 0.2.4
+pyproject.toml:
+  forked: false
+  hash: 6f314576dc1d2b62ea17fe94d39b0a69d98bda996c89685ee084539312387d95
+  source_module: template:minimal
+  source_version: 0.2.4
+src/agentforge_graph/__init__.py:
+  forked: false
+  hash: b6f9eb202d197dad3ae57d0defe4396b9e14ff0b56a7949cf760492c452a5401
+  source_module: template:minimal
+  source_version: 0.2.4
+src/agentforge_graph/main.py:
+  forked: false
+  hash: c05d490b5a1c7dd8ab3bda75558a7083cf22c8676f872476cb50c087edfbc020
+  source_module: template:minimal
+  source_version: 0.2.4

agentforge_graph-0.3.2/.claude/CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md — agentforge-graph
+
+> Entry point for AI assistants working on **agentforge-graph**, a
+> Code Knowledge Graph (CKG) engine + agent toolset built on the
+> AgentForge framework (agentforge-py 0.2.4). This is an **agent
+> project** (it consumes the framework), not a framework project.
+
+## Read first, in order
+
+1. [`../../../AGENTS.md`](../../../AGENTS.md) — workspace meta rules.
+2. [`../../../.claude/development-pipeline.md`](../../../.claude/development-pipeline.md)
+   — the abstract per-feature workflow every project follows
+   (pick → branch → analyse → design → implement → test → commit → PR
+   → merge), and the `.claude/state/` format.
+3. `.claude/state/current.md` — active feature, branch, what's done,
+   what's pending. **Local-only, git-ignored**; may be absent on a
+   fresh clone — create it when you start tracking work.
+4. [`../docs/features/TRACKER.md`](../docs/features/TRACKER.md) —
+   status board + dependency DAG; tells you what's ready to pick.
+5. [`../docs/features/README.md`](../docs/features/README.md) +
+   the active [`../docs/features/feat-NNN-*.md`](../docs/features/) spec.
+6. [`../docs/design/`](../docs/design/) — **one design doc per feature**
+   (`design-NNN-slug.md` mirrors `feat-NNN`). The *how* (file layout,
+   exact types, resolved decisions, chunk plan); written and approved
+   in the design stage before any code.
+7. [`../docs/adr/`](../docs/adr/) — the 9 architecture decisions.
+7. [`../docs/open-source-ckg-research.md`](../docs/open-source-ckg-research.md)
+   — the research that motivates the design.
+
+## Project-specific notes
+
+- **Tooling is `uv`, not pip.** Install: `uv sync` (base) /
+  `uv sync --extra engine`. Run the framework CLI as
+  `uv run agentforge …`, the agent CLI as `uv run ckg …`.
+  `agentforge add module` does **not** work here (it shells out to
+  `pip`, absent in uv venvs) — declare modules in `pyproject.toml`
+  and `uv sync` instead.
+- **Two config files, on purpose.** `agentforge.yaml` is framework
+  config (strict validator — no unknown keys). `ckg.yaml` is this
+  agent's own engine config (store/ingest/chunking/embed/retrieve/
+  serve), read by the `agentforge_graph` package.
+- **Framework learnings go in `docs/framework/`** — local-only,
+  git-ignored. Log any framework bug/hack/workaround/missing-feature
+  there as you hit it (baseline: agentforge-py 0.2.4).
+- **Reuse framework rails, don't reinvent.** `Tool` ABC + MCP
+  (feat-008), `Agent` + `budget_usd` (feat-010/012 enrichment),
+  reranker (feat-006). Keep the deterministic engine core
+  (`core`/`ingest`/`store`/`retrieve`) free of `agentforge` imports
+  (ADR-0001).
+- **Feature numbering is fixed** by `docs/features/`. Branch
+  `feat/NNN-slug` must match an existing spec filename — never invent
+  numbers. One feature = one branch = one PR.
+- Use `Read`/`Edit`/`Glob`/`Grep`, not Bash `cat`/`find`/`sed`.
+  Never `--no-verify` without explicit authorization.

agentforge_graph-0.3.2/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)"
+    ]
+  }
+}

agentforge_graph-0.3.2/.claude/standards/coding.md

@@ -0,0 +1,19 @@
+# Coding standards — agentforge-graph
+
+- **Python 3.13**, `from __future__ import annotations` in every module.
+- **Type everything.** `mypy --strict` is the gate (`uv run mypy`).
+  No untyped defs, no implicit `Any` in the engine core.
+- **Value types are Pydantic models**, validated at construction —
+  that's where ADR-0004 (provenance) and ADR-0003 (symbol-id) rules are
+  enforced. Frozen where the value is an identity (`Provenance`,
+  `SourceFile`, `ParsedSymbol`).
+- **Layering (ADR-0001):** the deterministic engine core
+  (`core`/`ingest`/`store`/`retrieve`) must not import `agentforge`.
+  Enforced by a unit test. Framework rails are used only at the
+  serving/enrichment edges.
+- **Lint/format:** `ruff` (`uv run ruff check` + `ruff format`),
+  line length 100.
+- **No `print`** in library code; surface results via return values /
+  logging.
+- Public surface of a package is its `__init__.__all__`; internal module
+  moves must not break that surface.

agentforge_graph-0.3.2/.claude/standards/testing.md

@@ -0,0 +1,18 @@
+# Testing standards — agentforge-graph
+
+- **Runner:** `pytest`, async via `pytest-asyncio` (`asyncio_mode =
+  auto` — no per-test marker needed). Run: `uv run pytest`.
+- **Coverage floor: 90%** on `agentforge_graph.core` (and each
+  feature's package as it lands). Enforced by `--cov-fail-under=90`.
+- **Conformance suites** (`core/conformance.py`) are the contract tests:
+  every `GraphStore` adapter (feat-003) and `Extractor` (feat-002/011)
+  subclasses the matching base class and provides its fixture. A new
+  backend is "done" when the shared suite passes against it.
+- **Property/determinism tests** for anything identity-related: symbol
+  IDs round-trip and are order-independent; extraction is deterministic
+  (same content → same subgraph).
+- **No network / no model calls in unit tests.** LLM-touching paths
+  (feat-010/012) use recorded/mocked responses; live tests are
+  env-gated and excluded from the default run.
+- Test fixtures use builders (`make_sample_subgraph`), not copy-pasted
+  literals.

agentforge_graph-0.3.2/.cursorrules

@@ -0,0 +1,12 @@
+See AGENTS.md for project conventions. AGENTS.md is the canonical
+source. This file exists so Cursor's native .cursorrules discovery
+keeps working.
+
+Cursor-specific rules can be added below this marker:
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- Cursor-specific rules go here. This section survives
+     `agentforge upgrade`. -->
+<!-- agentforge:end-custom -->

agentforge_graph-0.3.2/.env.example

@@ -0,0 +1,5 @@
+# Environment variables for My Agent.
+# Copy this file to `.env` and fill in real values.
+
+ANTHROPIC_API_KEY=
+

agentforge_graph-0.3.2/.github/copilot-instructions.md

@@ -0,0 +1,14 @@
+<!-- AGENTFORGE-MANAGED: template:minimal@0.2.4 hash:23c6e939d9d1 -->
+See [AGENTS.md](../AGENTS.md) for project conventions. AGENTS.md
+is the canonical source for AI-assistant instructions. This file
+exists so GitHub Copilot's native
+`.github/copilot-instructions.md` discovery keeps working.
+
+Copilot-specific instructions can be added below this marker:
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- Copilot-specific instructions go here. This section survives
+     `agentforge upgrade`. -->
+<!-- agentforge:end-custom -->

agentforge_graph-0.3.2/.github/workflows/ci.yml

@@ -0,0 +1,94 @@
+name: CI
+
+# Runs the exact local gate on every PR to main: ruff lint + format,
+# mypy --strict, and pytest with a >=90% coverage floor. The coverage threshold
+# is enforced by `--cov-fail-under=90` in pyproject's [tool.pytest.ini_options];
+# CI just runs `pytest`, so local and CI agree. Only on PRs — the PR gate already
+# validated the merge result, so re-running on push to main is redundant.
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+# Opt JS actions into Node 24 now (Node 20 is force-removed from runners
+# 2026-06-16). Drop this once the actions ship Node-24-native majors.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: lint · type · test (>=90% cov)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies (base + dev + engine)
+        # feat-003 is the first feature needing native wheels (kuzu, lancedb)
+        # from the `engine` extra; tree-sitter (feat-002) rides the same extra.
+        run: uv sync --extra dev --extra engine
+
+      - name: Ruff lint
+        run: uv run ruff check
+
+      - name: Ruff format check
+        run: uv run ruff format --check
+
+      - name: Mypy (strict)
+        run: uv run mypy
+
+      - name: Tests + coverage (fails under 90%)
+        run: uv run pytest
+
+  # ENH-004: run the server-backend conformance against real DBs (public images,
+  # no secrets), so Neo4j/pgvector are verified in CI — not just locally. Separate
+  # job so a DB hiccup can't fail the core gate; both must pass to merge.
+  server-backends:
+    name: server backends (neo4j + pgvector conformance)
+    runs-on: ubuntu-latest
+    services:
+      neo4j:
+        image: neo4j:5
+        env:
+          NEO4J_AUTH: neo4j/ckgckgckg
+        ports: ["7687:7687"]
+        options: >-
+          --health-cmd "cypher-shell -u neo4j -p ckgckgckg 'RETURN 1' || exit 1"
+          --health-interval 10s --health-timeout 5s --health-retries 20
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_PASSWORD: ckg
+          POSTGRES_DB: ckg
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U postgres" --health-interval 5s
+          --health-timeout 5s --health-retries 20
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync dependencies (+ neo4j + pgvector extras)
+        run: uv sync --extra dev --extra engine --extra neo4j --extra pgvector
+      - name: Server-backend conformance
+        env:
+          CKG_NEO4J_URI: bolt://localhost:7687
+          CKG_NEO4J_PASSWORD: ckgckgckg
+          CKG_PGVECTOR_DSN: postgresql://postgres:ckg@localhost:5432/ckg
+        run: >-
+          uv run pytest --no-cov
+          tests/store/test_neo4j_conformance.py
+          tests/store/test_pgvector_conformance.py

agentforge_graph-0.3.2/.gitignore

@@ -0,0 +1,27 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# CKG index artifacts (derivable; never committed — ADR-0006)
+.ckg/
+
+# Local-only framework learnings (issues, hacks, upgrade notes)
+docs/framework/
+
+# AI-assistant per-session working state (local-only, not published)
+.claude/state/
+
+# macOS
+.DS_Store
+
+# Keep .agentforge-state checked in — it tracks framework managed
+# files for upgrade.
+
+# build artifacts (uv build / hatchling)
+/dist/

agentforge_graph-0.3.2/.gitkeep

@@ -0,0 +1 @@
+

agentforge_graph-0.3.2/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+# Pre-commit gate for agentforge-graph. Run manually / in CI:
+#   uv run pre-commit run --all-files
+# (Local git-hook install is optional; chunked commits validate via the
+# same tools run directly: uv run ruff check / mypy / pytest.)
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+      - id: mypy
+        name: mypy --strict (src)
+        entry: uv run mypy
+        language: system
+        pass_filenames: false
+        types: [python]
+      - id: pytest
+        name: pytest + coverage
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+        types: [python]

agentforge_graph-0.3.2/AGENTS.md

@@ -0,0 +1,166 @@
+<!-- AGENTFORGE-MANAGED: template:minimal@0.2.4 hash:c2f4dad7b549 -->
+# AgentForge agent — AI assistant instructions
+
+This project is built on **AgentForge 0.2.4**. Use
+these rules when suggesting changes. The file is read by Claude
+Code, Cursor, Aider, and any tool following the
+[AGENTS.md convention](https://agents.md).
+
+## Project shape (you must respect this)
+
+- Framework version: `0.2.4`
+- Template: `minimal`
+- Project slug: `agentforge-graph`
+- LLM provider: `anthropic`
+
+## File ownership rules
+
+- Files starting with `AGENTFORGE-MANAGED:` are owned by the
+  framework. Do not edit. Suggest changes to YAML config or
+  developer-owned files instead.
+- Files starting with `AGENTFORGE-FORKED:` were customised by the
+  developer. Edit normally; do not restore the marker.
+- Files with no marker are developer-owned. Edit normally.
+- Markdown documents may carry a `<!-- agentforge:end-managed -->`
+  marker. Everything above belongs to the framework; everything
+  below is the developer's custom section and survives upgrades.
+
+## Architecture invariants
+
+- **Tools** — use the `@tool` decorator on a typed function, OR
+  subclass `Tool`. Type hints drive the input schema; do not
+  hand-write JSON schemas.
+- **Reasoning loop** — do not edit. Configure via
+  `agentforge.yaml > agent.strategy`.
+- **LLM clients** — do not import vendor SDKs directly. Use
+  `agent.providers["..."]` or pass `model="<provider>:<model_id>"`.
+- **Memory** — do not write SQL directly. Use `agent.memory.put`
+  / `.get` / `.query`.
+- **Costs** — do not bypass `BudgetPolicy`. Every LLM call is
+  checked. Bypassing it is a P3 (cost-safety) violation.
+- **Run id** — do not invent your own correlation id. Use
+  `current_run().run_id` from `agentforge_core.production.run_context`.
+- **Guardrails** — input / output / tool-gate validators live in
+  `agentforge.guardrails`. Custom validators implement the locked
+  ABCs in `agentforge_core.contracts.guardrails`.
+
+## How to add common things
+
+Open the runbook for the full step-by-step. Each runbook lives at
+`docs/runbooks/NN-<topic>.md` and is upgrade-safe (the framework
+maintains the managed section).
+
+| Task | Runbook |
+|---|---|
+| Set up a fresh agent | `docs/runbooks/01-set-up-new-agent.md` |
+| Add a tool | `docs/runbooks/02-add-a-tool.md` |
+| Add a pipeline task | `docs/runbooks/03-add-a-pipeline-task.md` |
+| Pick a reasoning strategy | `docs/runbooks/04-pick-reasoning-strategy.md` |
+| Write prompts | `docs/runbooks/05-write-prompts.md` |
+| Test your agent | `docs/runbooks/06-test-your-agent.md` |
+| Debug a run | `docs/runbooks/07-debug-a-run.md` |
+| Add memory / persistence | `docs/runbooks/08-add-memory.md` |
+| Add MCP servers | `docs/runbooks/09-add-mcp.md` |
+| Add evaluators | `docs/runbooks/10-add-evaluators.md` |
+| Add safety guardrails | `docs/runbooks/11-add-safety-guardrails.md` |
+| Add observability | `docs/runbooks/12-add-observability.md` |
+| Configure multi-provider | `docs/runbooks/13-configure-multi-provider.md` |
+| Deploy your agent | `docs/runbooks/14-deploy-your-agent.md` |
+| Upgrade your agent | `docs/runbooks/15-upgrade-your-agent.md` |
+| Configuration reference | `docs/runbooks/16-configuration-reference.md` |
+| Add a reranker | `docs/runbooks/17-add-reranker.md` |
+| Add hybrid search (BM25 + vector) | `docs/runbooks/18-add-hybrid-search.md` |
+| Add GraphRAG (graph-augmented retrieval) | `docs/runbooks/19-add-graphrag.md` |
+| Apply schema migrations | `docs/runbooks/20-apply-schema-migrations.md` |
+| Use streaming guardrails (sentence-window) | `docs/runbooks/21-use-streaming-guardrails.md` |
+
+## Anti-patterns (do not suggest these)
+
+- **Other-framework idioms** (chain/runnable/pipe abstractions from a
+  different agent framework) — wrong framework. Use AgentForge's
+  `Agent` + `@tool` + strategy
+  composition instead.
+- **Hand-rolling JSON schemas for tools** — use type hints on a
+  `@tool`-decorated function and the schema is derived.
+- **Storing API keys in `agentforge.yaml` literals** — use
+  `${ENV_VAR}` interpolation; secrets live in `.env` (gitignored).
+- **Catching exceptions inside tool code to "make the agent more
+  robust"** — let them surface; the framework records them as
+  observations and the LLM recovers naturally.
+- **Adding a wrapper around `Agent.run()` to add logging** — the
+  framework already logs; install a custom hook (runbook 12).
+- **Writing SQL directly against the memory backend** — use
+  `agent.memory.put / .get / .query`; SQL bypasses the contract
+  and breaks driver swaps.
+- **Running expensive code outside `BudgetPolicy`** — every
+  external call (LLM, tool, retriever) should respect the run's
+  budget.
+
+## Pre-commit checks (run these before suggesting a commit)
+
+```bash
+agentforge config validate
+agentforge status              # no managed file should be drifted
+pytest -q
+ruff check
+```
+
+## Where to find the framework's truth
+
+- Locked ABCs: `agentforge_core/contracts/*.py`
+- Default config schema: `agentforge_core/config/schema.py`
+- Built-in evaluators / guardrails / tools: `agentforge/*/`
+- Spec for any feature: `docs/features/feat-NNN-*.md` in the
+  framework repo
+
+When in doubt, prefer the framework's locked types over inventing
+new shapes. Suggesting an `Agent` subclass or a new ABC is almost
+always wrong — the framework is composed from named modules.
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+
+## agentforge-graph — project-specific AI guidance
+
+This project is a **Code Knowledge Graph engine** (not a typical agent). Before
+changing a subsystem, read [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) (the
+map), [`CONTRIBUTING.md`](CONTRIBUTING.md) (playbooks), and the relevant
+[`docs/design/`](docs/design/) doc.
+
+**Invariants you must respect:**
+
+- **Layering (ADR-0001):** the deterministic engine — `core`, `config`,
+  `ingest`, `store`, `chunking`, `embed`, `retrieve`, `repomap`, `frameworks`,
+  `knowledge` — **must not import `agentforge`**. There's a layering test that
+  enforces it. Only `serve` and `enrich` may import the framework.
+- **Provenance (ADR-0004):** every `Node`/`Edge` carries `Provenance`
+  (`parsed | resolved | llm | manual`, + extractor, commit, confidence). LLM
+  facts use `Provenance.llm(...)` with a confidence and are opt-out-able. Never
+  emit an unattributed fact.
+- **Stable ids (ADR-0003):** node ids are `SymbolID` strings derived from
+  `(lang, repo, path, descriptor)` — deterministic, no counters. Use
+  `SymbolID.for_symbol` / `.parse`, never invent ids.
+- **Locked kinds (ADR-0005):** `NodeKind`/`EdgeKind` are fixed in
+  `core/kinds.py`. Don't add kinds casually; producers for reserved kinds ship
+  in later features.
+- **Conservative resolution:** create a cross-file edge only on an unambiguous
+  match; count the rest, never guess.
+- **Injectable models:** never hard-call a model. Implement/inject `Embedder`,
+  `PatternJudge`, or `Summarizer`. CI uses the deterministic fakes — keep tests
+  model-free; live tests are env-gated (`CKG_LIVE_BEDROCK` / `CKG_LIVE_AGENT`).
+- **Budget rails:** LLM enrichment runs under `BudgetPolicy`; account cost
+  per-batch and persist partial progress on a trip. Don't bypass it.
+
+**Tooling & workflow:** use `uv` (`uv run ckg …`), not pip. Use `Read`/`Edit`/
+`Grep`, not Bash `cat`/`find`/`sed`. One feature/bug/enh = one branch = one PR;
+design-doc-first for features. Gate every change on
+`pytest + mypy --strict + ruff`. Log AgentForge/Kuzu surprises in
+`docs/framework/` (local-only).
+
+**Dogfood:** `ckg index . && ckg serve-mcp --repo .` exposes this repo's own
+graph (decisions, routes, impact, summaries) — useful grounded context for an
+assistant working here.
+
+<!-- agentforge:end-custom -->
+