agentforge-graph 0.3.3__tar.gz → 0.5.0__tar.gz

{agentforge_graph-0.3.3 → agentforge_graph-0.5.0}/.agentforge-state/managed-files.lock

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

{agentforge_graph-0.3.3 → agentforge_graph-0.5.0}/.claude/CLAUDE.md

@@ -35,10 +35,17 @@
   `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.
+- **One config file: `agentforge.yaml`.** Framework keys at the top
+  level; this agent's engine config (store/ingest/chunking/embed/
+  retrieve/serve/…) under the framework's `app:` passthrough
+  (agentforge-py ≥0.3). The engine reads `app:` with **plain pyyaml,
+  no `agentforge` import** (ADR-0001) — `config.resolve_config()`
+  discovers `agentforge.yaml` (with `app:`) or a standalone `ckg.yaml`,
+  and `_read_block` reads from `app.<key>` or top-level. A standalone
+  `ckg.yaml` is still supported (framework-free use). *(History: we
+  used a separate `ckg.yaml` because 0.2.4's strict validator rejected
+  app keys — fixed upstream in 0.3.x via `app:`; see
+  `docs/framework/upgrade-0.2.4-to-0.3.x.md`.)*
 - **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).

{agentforge_graph-0.3.3 → agentforge_graph-0.5.0}/.env.example

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

agentforge_graph-0.5.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Something the engine, CLI, or MCP server got wrong
+title: "[bug] "
+labels: bug
+---
+
+## What happened
+
+A clear description of the bug, and what you expected instead.
+
+## Reproduce
+
+Steps / the smallest repo or snippet that triggers it:
+
+```bash
+ckg index .
+ckg ...        # the command that misbehaves
+```
+
+If it's an extraction/resolution issue, a **minimal source file** that reproduces
+it helps a lot.
+
+## Environment
+
+- agentforge-graph version: `ckg --version` (or `pip show agentforge-graph`)
+- Python version:
+- OS:
+- Store backend (if not default): `kuzu`/`neo4j`/`pgvector`/`surrealdb`/…
+- Language(s) involved (if extraction): Python / TS / Go / …
+- Provider (if embed/enrich): `bedrock`/`openai`/`anthropic`/`fake`/…
+
+## Logs / output
+
+```
+paste the relevant output, error, or stack trace
+```
+
+## Notes
+
+Anything else — was it incremental vs full index, a specific framework pack, etc.

agentforge_graph-0.5.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/Scaffoldic/agentforge-graph/security/advisories/new
+    about: Please report security issues privately — see SECURITY.md, not a public issue.
+  - name: Question / usage help
+    url: https://github.com/Scaffoldic/agentforge-graph/discussions
+    about: Ask how to use the engine, MCP tools, or a provider/backend.

agentforge_graph-0.5.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature request
+about: Propose a capability, a language/framework pack, or a backend
+title: "[feat] "
+labels: enhancement
+---
+
+## The problem / use case
+
+What are you trying to do that the engine doesn't support today? Who's it for —
+a human, or a coding agent consuming the graph?
+
+## Proposed solution
+
+What you'd like to see. If it's a new **language pack**, **framework pack**,
+**storage backend**, or **model provider**, note the target (e.g. "Rails routes",
+"SurrealDB", "Gemini embeddings") — these ride documented extension points (see
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) §5).
+
+## Alternatives considered
+
+Other approaches, or how you work around it now.
+
+## Scope
+
+- [ ] I'd be willing to help implement this
+- [ ] This needs a design discussion first

agentforge_graph-0.5.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+<!-- Thanks for contributing! Keep PRs to one feature/fix = one branch = one PR. -->
+
+## What & why
+
+What this changes and the motivation. Link the issue / feature spec / ADR if any
+(e.g. `Closes #123`, `feat-0NN`, `ENH-0NN`).
+
+## How
+
+A short note on the approach — and, if it touches an extension point (a language
+/ framework pack, storage backend, model provider, MCP tool, enricher), how it
+rides the existing rails.
+
+## Checklist
+
+- [ ] `uv run ruff format --check . && uv run ruff check . && uv run mypy src` clean
+- [ ] `uv run pytest` green (≥90% coverage)
+- [ ] New behavior has tests (golden + end-to-end where it applies; new backends
+      pass the conformance suite)
+- [ ] Docs updated (README / a `docs/guides/` page / CHANGELOG `[Unreleased]`)
+- [ ] No new `agentforge` import inside the deterministic engine (ADR-0001)
+- [ ] Conventional-commit title (`feat:` / `fix:` / `docs:` / `chore:` / …)

{agentforge_graph-0.3.3 → agentforge_graph-0.5.0}/.github/copilot-instructions.md

@@ -1,4 +1,4 @@
-<!-- AGENTFORGE-MANAGED: template:minimal@0.2.4 hash:23c6e939d9d1 -->
+<!-- AGENTFORGE-MANAGED: template:minimal@0.3.1 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

{agentforge_graph-0.3.3 → agentforge_graph-0.5.0}/.github/workflows/ci.yml

@@ -55,7 +55,7 @@ jobs:
   # 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)
+    name: server backends (neo4j + pgvector + surrealdb conformance)
     runs-on: ubuntu-latest
     services:
       neo4j:
@@ -81,14 +81,26 @@ jobs:
         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: Sync dependencies (+ neo4j + pgvector + surrealdb extras)
+        run: uv sync --extra dev --extra engine --extra neo4j --extra pgvector --extra surrealdb
+      # SurrealDB needs its `start` command + args, which a `services:` container
+      # can't express — so run it directly and wait for the /health endpoint.
+      - name: Start SurrealDB
+        run: |
+          docker run -d --name surreal -p 8000:8000 \
+            surrealdb/surrealdb:latest start --user root --pass root memory
+          for i in $(seq 1 30); do
+            curl -sf http://localhost:8000/health && break
+            sleep 1
+          done
       - name: Server-backend conformance
         env:
           CKG_NEO4J_URI: bolt://localhost:7687
           CKG_NEO4J_PASSWORD: ckgckgckg
           CKG_PGVECTOR_DSN: postgresql://postgres:ckg@localhost:5432/ckg
+          CKG_SURREALDB_URL: ws://localhost:8000/rpc
         run: >-
           uv run pytest --no-cov
           tests/store/test_neo4j_conformance.py
           tests/store/test_pgvector_conformance.py
+          tests/store/test_surreal_conformance.py

{agentforge_graph-0.3.3 → agentforge_graph-0.5.0}/AGENTS.md

@@ -1,14 +1,14 @@
-<!-- AGENTFORGE-MANAGED: template:minimal@0.2.4 hash:c2f4dad7b549 -->
+<!-- AGENTFORGE-MANAGED: template:minimal@0.3.1 hash:8156ae690c99 -->
 # AgentForge agent — AI assistant instructions
 
-This project is built on **AgentForge 0.2.4**. Use
+This project is built on **AgentForge 0.3.1**. 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`
+- Framework version: `0.3.1`
 - Template: `minimal`
 - Project slug: `agentforge-graph`
 - LLM provider: `anthropic`
@@ -161,6 +161,4 @@ design-doc-first for features. Gate every change on
 **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 -->
-

{agentforge_graph-0.3.3 → agentforge_graph-0.5.0}/CHANGELOG.md

@@ -8,6 +8,226 @@ on a schema mismatch is **rebuild** (ADR-0006).
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-06-21
+
+The **org-level central knowledge** release — take CKG from "indexes my one repo"
+to "is my org's shared code brain": host the index **centrally** and consume it
+**read-only**, serve a multi-repo **workspace** from one federated MCP endpoint,
+and **trace requests across services** (HTTP client → route, matched by path or
+OpenAPI contract). (Also: the scaffold template was upgraded to AgentForge 0.3.1.)
+
+### Added
+
+- **`ckg services-map` and `ckg trace` CLI commands** (ENH-020). The cross-service
+  call graph and request tracing — previously MCP-only — are now on the command
+  line: `ckg services-map --workspace workspace.yaml` prints `from → to` edges
+  (with handler + `via`), and `ckg trace <service> --workspace …
+  [--direction downstream|upstream] [--depth N]` walks the graph (data flow /
+  blast radius). See the org topology from a terminal, not just an agent.
+- **Microservices demo + end-to-end test** for the org-central features. A
+  bundled `examples/microservices` workspace (web→gateway→orders→payments,
+  spanning JS `fetch`, Python `httpx`/`requests`, and a contract-first OpenAPI
+  service) with a runnable walkthrough, plus an automated e2e test that exercises
+  ENH-018 (central hosting + read-only), ENH-019 (cwd discovery) and ENH-020
+  (federation + `ckg_services_map` + `ckg_trace`) in one flow — the demo is the
+  test fixture, so they can't drift.
+- **OpenAPI contract anchoring for the cross-service map** (ENH-020 C-full). When
+  a member ships an OpenAPI/Swagger spec (`openapi.{json,yaml,yml}` /
+  `swagger.{json,yaml}` at the repo root), `service_map` now matches calls against
+  the **declared contract** too — giving authoritative paths, the `operationId` as
+  the handler, and coverage for **contract-first services with no detected
+  framework**. A framework route and its spec twin are deduped (param-agnostic) so
+  they never make a call ambiguous; each edge reports its `via` (`framework` |
+  `openapi`). Precision + coverage upgrade over URL-string matching alone.
+- **JS/TS cross-service calls (fetch / axios)** (ENH-020 C-full). A new
+  `jshttpclient` pack (spanning `.js` + `.ts`) captures `fetch("…")`,
+  `axios.get("…")` / `axios.post("…")` and `axios("…")` as `ServiceCall` nodes —
+  `fetch`'s method read from a literal `{ method: "POST" }` option, default GET.
+  So a JS/TS frontend or BFF now appears as a caller in the cross-service map /
+  `ckg_services_map` / `ckg_trace`, not just Python services.
+- **HTTP client coverage: instance clients + `base_url`** (ENH-020 C-full). The
+  `httpclient` pack now also captures calls through a client *instance* —
+  `s = requests.Session(); s.get(…)` and `c = httpx.Client(base_url="http://orders");
+  c.get("/v1/x")` — composing `base_url + path` into the matched URL. This is the
+  dominant real-world pattern (previously only module-qualified `requests.get(…)`
+  with a literal URL was seen), so the cross-service map covers far more actual
+  calls. Still conservative: dynamic URLs are counted, not guessed.
+- **`ckg_trace` — walk a request across services** (ENH-020 C-full). From a
+  starting service, trace the cross-service call graph `downstream` (what it
+  calls — data flow) or `upstream` (who calls it — blast radius), to a depth.
+  Returns the reachable hops (with hop numbers) and the services reached; cycles
+  terminate. Turns the `ckg_services_map` edges into the answer to *"what does
+  this service depend on / which services break if I change it"* — impact
+  analysis that spans service boundaries. Federation-only tool.
+- **Cross-service call graph** (ENH-020, C-full increment 2). The federated MCP
+  server now draws **who-calls-whom across services**: it matches each member's
+  outbound `ServiceCall` to a `Route` in *another* member by `(method, path)` —
+  with path-parameter awareness (`{id}` / `:id` / `<id>`) — and exposes the org
+  call graph via a new `ckg_services_map` tool (`from_service → to_service`,
+  method, path, handler, plus `unresolved` calls). Computed live because member
+  graphs are separate stores; unique-match-only (ADR-0004) — an ambiguous call is
+  reported, never guessed. This completes the microservices payoff: an agent can
+  see the whole org's service topology from one endpoint.
+- **Outbound HTTP client calls are captured** (ENH-020, C-full increment 1).
+  A new `httpclient` framework pack records module-qualified `requests.get("…")`
+  / `httpx.post("…")` calls as `ServiceCall` graph nodes (method + URL + path),
+  riding the caller file's subgraph like routes. Surfaced via
+  `CodeGraph.service_calls()` and `ckg service-calls`. Conservative (ADR-0004):
+  literal URLs only; dynamic URLs / client-instance calls are counted, not
+  guessed. This is the **caller side** of a cross-service edge — at federation
+  time these match `Route` nodes in other services (the next increment:
+  `ckg_services_map` / `ckg_trace`).
+- **Federated MCP over a workspace** (ENH-020, C-lite). `ckg serve-mcp
+  --workspace workspace.yaml` serves **many member repos/services from one
+  endpoint**. The **survey tools** (`ckg_search`, `ckg_routes`, `ckg_decisions`,
+  `ckg_status`) fan across every member and tag each result with its `service`
+  (with a per-service staleness envelope); the **pinpoint tools** (`ckg_symbol`,
+  `ckg_impact`, `ckg_neighbors`, `ckg_explain`, `ckg_history`, `ckg_repo_map`)
+  take a `service` to target one member. A single repo is unchanged (no
+  `services` envelope). This is the microservices payoff of the
+  org-central-knowledge theme — one code brain for the whole org. (Cross-service
+  *contract edges* — tracing a request across services — are the next phase,
+  C-full.) Also fixes the MCP `_Engine` to honor `store.central_root` (ENH-018).
+- **Read-only consumers** (ENH-018). `store.read_only: true` (or `--read-only` /
+  `$CKG_READ_ONLY`) makes a store consume-only: the write verbs (`index`,
+  `embed`, `enrich`) refuse with a clear message and a non-zero exit, and opening
+  a *missing* index errors instead of silently creating one. Read verbs
+  (`query`, `map`, `routes`, `serve-mcp`, …) work normally. This is what lets a
+  team host one central index (built by CI) and hand it to many developers and
+  agents without risk of accidental mutation.
+- **Host the index outside the repo with `store.central_root`** (ENH-018).
+  By default the index stays in the gitignored `.ckg/` inside the repo (the
+  laptop story, unchanged). Set `store.central_root: /shared/ckg` and each repo's
+  artifacts move to a stable, **collision-free per-repo subdir** under that root
+  — keyed by git remote (`org/repo`, host-independent) or `<dirname>-<hash>` with
+  no remote — so a team/CI can build once and host many repos centrally. The
+  `.ckg` root is now resolved through one helper (`store.location.resolve_root`),
+  de-duplicating ~10 call sites. `ckg status` shows the resolved location
+  (`(central)` when hosting is on). First rung of the org-central-knowledge theme.
+- **`ckg` now discovers the repo root from the working directory** (ENH-019).
+  When no path is given, every subcommand — including `ckg serve-mcp` — walks up
+  from the cwd to the nearest `.ckg/` / `agentforge.yaml` / `ckg.yaml` / `.git`
+  (nearest wins), like `git`. So a bare `ckg serve-mcp` from anywhere inside a
+  repo serves *that* repo — no `--repo` needed — which is what an MCP client
+  launching the server in a project directory wants. Falls back to `.` when no
+  marker is found (unchanged for a bare directory); an explicit positional /
+  `--path` / `--repo` always wins; when discovery climbs above the cwd the
+  resolved root is announced on stderr. First rung of the org-central-knowledge
+  theme (zero-config consumption).
+
+### Changed
+
+- **Getting-started guides reorganised by setup** into three step-by-step
+  walkthroughs — [single repo](docs/guides/getting-started/1-single-repo.md),
+  [workspace](docs/guides/getting-started/2-workspace.md), and
+  [central store](docs/guides/getting-started/3-central-store.md) — under a hub
+  (`01-getting-started.md`, kept so existing links resolve). The 10 topic guides
+  are unchanged.
+- **README refreshed for the three setups** with a new `docs/assets/setups.gif`
+  (single repo → central store → workspace `services-map` / `trace`), rendered by
+  `scripts/render-setups-gif.sh`.
+- **Scaffold template upgraded to AgentForge 0.3.1** (`agentforge upgrade`); the
+  files we own are forked so future upgrades skip them.
+
+## [0.4.0] — 2026-06-20
+
+### Changed
+
+- **Consolidated engine config into `agentforge.yaml` (`app:` section).**
+  agentforge-py 0.3.x added a sanctioned `app:` passthrough to its strict config
+  file — the fix for the workaround that forced a separate `ckg.yaml`. The engine
+  now reads its config from `app:` (or a top-level standalone `ckg.yaml`, still
+  supported) using **plain pyyaml, no `agentforge` import** (ADR-0001), and
+  **auto-discovers** the file in the repo (previously only `--config` was read).
+  One config file. `config.resolve_config()` + `app:`-aware `_read_block`.
+- **HTTP MCP auth now rides the framework's `from_http(middleware=)` seam**
+  (agentforge-mcp 0.3.x), replacing the `CkgHttpRunner` that reimplemented ~60
+  lines of HTTP-serve internals to add a bearer gate. `BearerAuthMiddleware`
+  unchanged; verified live (401 / pass-through). (ENH-005.)
+- **Upgraded the AgentForge framework pin to `>=0.3,<0.4`** (from the validated
+  0.2.x line). Re-validated: the full gate (666 tests / 95%, ruff + mypy) and an
+  MCP server-construction smoke pass on `agentforge-py` 0.3.1 — the `Tool` /
+  `BudgetPolicy` / `MCPServer` surfaces are unchanged.
+
+### Added
+
+- **Bedrock-native reranker + measurement campaign (ENH-013).** A torch-free
+  `BedrockRerankScorer` (AWS Bedrock Rerank API — Cohere Rerank 3.5 / Amazon
+  Rerank) behind the existing `CrossScorer` seam, selected via
+  `rerank_model: bedrock:cohere.rerank-v3-5:0` — reuses the AWS creds the embedder
+  already uses, no `rerank`/torch extra. A two-corpus campaign (harness
+  `scripts/rerank_eval.py`, [results](docs/validation/rerank/results.md)) found
+  the cross-encoder is an **ordering** win (MRR +10–16% at blend weight 0.3) over
+  an already-recall-saturated base, costing ~540 ms/query — so rerank **stays
+  opt-in**, with the Bedrock config @ `w=0.3` documented as the recommended
+  precision setting. New `retrieve.rerank_region` config. A **rigorous follow-up
+  benchmark** (`scripts/rerank_benchmark.py`, objective docstring→code labels,
+  388 queries / 4 OSS repos) confirms base retrieval MRR 0.95 / recall@1 0.92 and
+  a statistically-significant rerank lift (ΔMRR +0.019, p<0.001) — surfaced in the
+  README's "Retrieval quality (measured)" section.
+
+- **Four new framework packs — Go / C# / PHP / Ruby routes (ENH-012).** Framework
+  awareness now spans **11 packs** across six languages. Each rides a small new
+  `_<lang>_ast` helper and is conservative (ADR-0004); detection uses import
+  markers since these languages' deps live outside the scanned manifests.
+  - **Gin** (Go) — `r.GET("/x", handler)` method calls → `Route` + `HANDLED_BY`
+    to the Go function (mirrors Express).
+  - **ASP.NET** (C#) — `[HttpGet("/x")]` attributes on controllers → `Route` +
+    `HANDLED_BY` to `Class#method`; `[Route]` base path + `[controller]` token
+    (mirrors Spring).
+  - **Laravel** (PHP) — `Route::get('/x', [C::class, 'm'])` / `'C@m'` / invokable.
+  - **Rails** (Ruby) — `routes.rb` explicit `get '/x' => 'c#a'` / `to:` / `root`.
+
+  Laravel and Rails name their handler in another file, so a new **generic
+  cross-file route-handler grounding** pass-2 step (`frameworks/cross_file.py`)
+  resolves the controller reference to the real `Class#method` symbol anywhere in
+  the repo (unique-match), emitting `HANDLED_BY` — globally idempotent, surfaced
+  as `IndexReport.route_handlers_grounded`. ORM models (EF Core / Eloquent /
+  ActiveRecord), the ASP.NET minimal API, and the Rails resourceful DSL are
+  follow-ups.
+
+- **Cross-file framework resolution — route prefixes + DI grounding (ENH-011).**
+  A globally-idempotent pass-2 (`frameworks/cross_file.py`) stitches the
+  compose-points real apps split across files, reading only the persisted graph
+  (`IMPORTS` edges + node attrs), unique-match-only (ADR-0004):
+  - `app.include_router(payments.router, prefix="/api")` composes `/api` onto the
+    included router's routes. The base `path` is preserved; the composed URL is a
+    new `path_pattern` attr (`RouteInfo.path_pattern`, shown by `ckg routes` and
+    returned by the `ckg_routes` MCP tool). New `RouteMount` node kind.
+  - `Depends(get_db)` grounds the provider *name* to the `get_db` function symbol
+    in its module via a new `PROVIDED_BY` edge (+ `Service.provider_symbol`).
+
+  Ships for **FastAPI**; Flask / Express / Django reuse the same framework-
+  agnostic pass-2 (per-pack pass-1 capture pending). New `RouteMount` /
+  `PROVIDED_BY` kinds are additive and migration-free (the stores key edges/nodes
+  by a `kind` string column). `IndexReport.route_prefixes_composed` /
+  `di_providers_grounded`; `incremental == full` preserved. New runbook:
+  `docs/guides/04-cross-file-framework-resolution.md`.
+
+- **`CITATION.cff`** — GitHub "Cite this repository" metadata.
+
+- **Consumer feature guides + a runnable example.** New `docs/guides/` for the
+  headline features — framework extraction (routes/models/services), architecture
+  decisions, temporal/history, enrichment, and an index→query walkthrough — plus
+  `examples/fastapi-shop/`, a tiny FastAPI+SQLAlchemy app you can index in one
+  command to see routes/models/services (output verified against the CLI).
+
+- **Project metadata + community health.** `[project.urls]` (Homepage,
+  Repository, Changelog, Issues, Documentation) so the PyPI page links out;
+  `SECURITY.md`, `CODE_OF_CONDUCT.md`, GitHub issue + PR templates; README doc
+  links made absolute so they resolve on the PyPI project page.
+
+- **SurrealDB storage backend — graph + vectors in one (ENH-010).** A first-party
+  `surrealdb` driver for *both* `store.graph.driver` and `store.vectors.driver`,
+  so one multi-model server is a complete backend (`pip install
+  agentforge-graph[surrealdb]`). It passes the same `GraphStoreConformance` /
+  `VectorStoreConformance` suites as Kuzu/Neo4j/LanceDB/pgvector — verified
+  against a live SurrealDB in the `server-backends` CI job. Nodes/edges are
+  document tables on the shared open schema (hash-keyed records, the symbol id in
+  a `key` field); vector search is brute-force cosine in `[0, 1]`. This makes the
+  "day-one, plug in a different DB" promise provable end-to-end against an
+  independent third backend.
+
 ## [0.3.3] - 2026-06-19
 
 Leaner base install + the refreshed README on PyPI.
@@ -429,10 +649,11 @@ questions over the tools, unattended.
   on a real repo (fixed BUG-008, a default-config `ckg query` break); and parse
   coverage holds at scale (`django`, 2922 files, ~100%, no crash).
 
-[Unreleased]: https://github.com/Scaffoldic/agentforge-grpah/compare/v0.3.3...HEAD
-[0.3.3]: https://github.com/Scaffoldic/agentforge-grpah/compare/v0.3.2...v0.3.3
-[0.3.2]: https://github.com/Scaffoldic/agentforge-grpah/compare/v0.3.1...v0.3.2
-[0.3.1]: https://github.com/Scaffoldic/agentforge-grpah/compare/v0.3.0...v0.3.1
-[0.3.0]: https://github.com/Scaffoldic/agentforge-grpah/compare/v0.2.0...v0.3.0
-[0.2.0]: https://github.com/Scaffoldic/agentforge-grpah/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/Scaffoldic/agentforge-grpah/releases/tag/v0.1.0
+[Unreleased]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.3.3...v0.4.0
+[0.3.3]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/Scaffoldic/agentforge-graph/releases/tag/v0.1.0