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

{agentforge_graph-0.4.0 → 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.5.0/.claude/settings.local.json

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

{agentforge_graph-0.4.0 → 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.4.0 → 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.4.0 → 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.4.0 → agentforge_graph-0.5.0}/CHANGELOG.md

@@ -8,6 +8,127 @@ 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

{agentforge_graph-0.4.0 → agentforge_graph-0.5.0}/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- AGENTFORGE-MANAGED: template:minimal@0.2.4 hash:9120f1c4a774 -->
+<!-- AGENTFORGE-MANAGED: template:minimal@0.3.1 hash:9120f1c4a774 -->
 > See [AGENTS.md](./AGENTS.md) for AgentForge conventions. Claude
 > Code reads both files; **AGENTS.md is the canonical source**.
 

{agentforge_graph-0.4.0 → agentforge_graph-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentforge-graph
-Version: 0.4.0
+Version: 0.5.0
 Summary: Code Knowledge Graph (CKG) engine + agent toolset, built on AgentForge.
 Project-URL: Homepage, https://github.com/Scaffoldic/agentforge-graph
 Project-URL: Repository, https://github.com/Scaffoldic/agentforge-graph
@@ -57,7 +57,6 @@ Provides-Extra: voyage
 Requires-Dist: agentforge-voyage; extra == 'voyage'
 Description-Content-Type: text/markdown
 
-<!-- AGENTFORGE-MANAGED: template:minimal@0.2.4 hash:c474ab3012ec -->
 <!-- NOTE: customized for agentforge-graph (forked from the scaffold README). -->
 # agentforge-graph
 
@@ -66,10 +65,12 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://pypi.org/project/agentforge-graph/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](https://github.com/Scaffoldic/agentforge-graph/blob/main/LICENSE)
 
-> **Turn any repo into a knowledge graph your coding agent can actually reason
-> over.** Symbols, calls, imports, **API routes, ORM models, dependency
-> injection, architecture decisions, git history, LLM summaries** — one typed,
-> provenance-tracked graph, served over **MCP** in a single command.
+> **Turn any repo — or your whole org — into a knowledge graph your coding agent
+> can actually reason over.** Symbols, calls, imports, **API routes, ORM models,
+> dependency injection, architecture decisions, git history, LLM summaries** — one
+> typed, provenance-tracked graph, served over **MCP** in a single command. Scale
+> it from one repo to a **federated workspace** with **cross-service tracing**, on
+> a **central** index hosted for the team.
 
 Plain code-graph tools answer *"what is connected."* Agents also need *"what is
 this **for**, what decision governs it, what's the API surface, which tables does
@@ -121,8 +122,15 @@ ckg serve-mcp --repo .              # → 10 read-only tools for your agent
 - 🧠 **LLM enrichment, budgeted & opt-in** — design-pattern tags (*"this class is a
   Repository,"* with confidence + rationale) and bottom-up module summaries, all
   `llm`-provenance. **CI needs no model calls or cloud creds.**
-
-**Status: 0.3.3 — all 12 planned features shipped.** Published on
+- 🏢 **Scales from one repo to a whole org** — host the index **centrally** (shared
+  dir or SurrealDB/Neo4j), built once and consumed **read-only** by many; serve a
+  multi-repo **workspace** from one federated MCP endpoint; and **trace requests
+  across services** — `ckg services-map` / `ckg trace` draw the cross-service call
+  graph (HTTP client → route, matched by path or OpenAPI contract).
+
+**Status: 0.5.0 — all 12 planned features shipped, now org-scale.** 0.5 adds
+central hosting + read-only consumers, a federated multi-repo workspace, and
+cross-service request tracing on top. Published on
 [PyPI](https://pypi.org/project/agentforge-graph/). Each language pack validated on
 a real OSS repo with a creds-enabled embed/retrieval/enrich run; a real agent
 answers questions over the tools unattended. See the [`CHANGELOG`](https://github.com/Scaffoldic/agentforge-graph/blob/main/CHANGELOG.md)
@@ -130,9 +138,38 @@ and [`docs/features/TRACKER.md`](https://github.com/Scaffoldic/agentforge-graph/
 
 ---
 
+## Run it three ways — one repo, a workspace, or a central store
+
+```bash
+# 1) a single repo — a typed graph in seconds
+ckg index . && ckg routes .
+
+# 2) a central store — host the index outside the repo, consume read-only
+#    (set store.central_root in ckg.yaml; built once by CI, read by many)
+ckg status . --read-only
+
+# 3) a workspace — the cross-service call graph across services
+ckg services-map --workspace workspace.yaml      # who calls whom (HTTP → route)
+ckg trace payments --workspace workspace.yaml --direction upstream   # blast radius
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Scaffoldic/agentforge-graph/main/docs/assets/setups.gif"
+       alt="ckg run three ways: a single repo (index + routes), a central store (hosted + read-only), and a workspace (cross-service call graph + trace)"
+       width="820">
+  <br>
+  <em>Single repo → central store → workspace — the cross-service call graph and blast-radius trace, all creds-free.</em>
+</p>
+
+→ pick your path: **[a single repo](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/1-single-repo.md)** ·
+**[a workspace](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/2-workspace.md)** ·
+**[a central store](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/3-central-store.md)**.
+
+---
+
 ## Quick start
 
-> **Prefer a guided walkthrough?** Follow **[01 — Getting started](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/01-getting-started.md)** (install → index → query → serve, ~10 min), or browse all [step-by-step guides](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/README.md).
+> **Prefer a guided walkthrough?** Pick your setup — **[a single repo](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/1-single-repo.md)** (~10 min), **[a workspace](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/2-workspace.md)** (microservices, one federated endpoint), or **[a central store](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/3-central-store.md)** (org-level shared index) — from the **[Getting started hub](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/01-getting-started.md)**. Or browse all [step-by-step guides](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/README.md).
 
 ```bash
 pip install agentforge-graph                # engine included (tree-sitter + kuzu + lancedb)
@@ -372,7 +409,7 @@ This repo is built to be worked on **with** AI agents. Start here:
 | Doc | What it is |
 |---|---|
 | [`docs/ARCHITECTURE.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/ARCHITECTURE.md) | High-level architecture + every pipeline (ASCII) |
-| [**`docs/guides/`**](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/README.md) | **Step-by-step guides** (numbered learning path, each with a TL;DR). Start with **[01 — Getting started](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/01-getting-started.md)** (install → index → query → serve), then: [02 indexing & retrieval](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/02-indexing-and-retrieval.md) · [03 framework extraction](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/03-framework-extraction.md) · [04 cross-file resolution](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/04-cross-file-framework-resolution.md) · [05 architecture decisions](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/05-architecture-decisions.md) · [06 temporal/history](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/06-temporal-history.md) · [07 enrichment](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/07-enrichment.md) · [08 model providers](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/08-model-providers.md) · [09 storage backends](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/09-storage-backends.md) · [10 using over MCP](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/10-using-over-mcp.md) |
+| [**`docs/guides/`**](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/README.md) | **Step-by-step guides** (each with a TL;DR). **Getting started — pick your setup:** [a single repo](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/1-single-repo.md) · [a workspace](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/2-workspace.md) · [a central store](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/3-central-store.md). **Topic guides:** [02 indexing & retrieval](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/02-indexing-and-retrieval.md) · [03 framework extraction](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/03-framework-extraction.md) · [04 cross-file resolution](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/04-cross-file-framework-resolution.md) · [05 architecture decisions](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/05-architecture-decisions.md) · [06 temporal/history](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/06-temporal-history.md) · [07 enrichment](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/07-enrichment.md) · [08 model providers](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/08-model-providers.md) · [09 storage backends](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/09-storage-backends.md) · [10 using over MCP](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/10-using-over-mcp.md) |
 | [`examples/`](https://github.com/Scaffoldic/agentforge-graph/tree/main/examples) | Runnable sample repos (index → routes/models/services/query) |
 | [`docs/adr/`](https://github.com/Scaffoldic/agentforge-graph/tree/main/docs/adr/) | 9 architecture decision records (the *why*) |
 | [`docs/features/`](https://github.com/Scaffoldic/agentforge-graph/tree/main/docs/features/) + [`TRACKER.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/features/TRACKER.md) | 12 feature specs + status board |

{agentforge_graph-0.4.0 → agentforge_graph-0.5.0}/README.md

@@ -1,4 +1,3 @@
-<!-- AGENTFORGE-MANAGED: template:minimal@0.2.4 hash:c474ab3012ec -->
 <!-- NOTE: customized for agentforge-graph (forked from the scaffold README). -->
 # agentforge-graph
 
@@ -7,10 +6,12 @@
 [![Python](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://pypi.org/project/agentforge-graph/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](https://github.com/Scaffoldic/agentforge-graph/blob/main/LICENSE)
 
-> **Turn any repo into a knowledge graph your coding agent can actually reason
-> over.** Symbols, calls, imports, **API routes, ORM models, dependency
-> injection, architecture decisions, git history, LLM summaries** — one typed,
-> provenance-tracked graph, served over **MCP** in a single command.
+> **Turn any repo — or your whole org — into a knowledge graph your coding agent
+> can actually reason over.** Symbols, calls, imports, **API routes, ORM models,
+> dependency injection, architecture decisions, git history, LLM summaries** — one
+> typed, provenance-tracked graph, served over **MCP** in a single command. Scale
+> it from one repo to a **federated workspace** with **cross-service tracing**, on
+> a **central** index hosted for the team.
 
 Plain code-graph tools answer *"what is connected."* Agents also need *"what is
 this **for**, what decision governs it, what's the API surface, which tables does
@@ -62,8 +63,15 @@ ckg serve-mcp --repo .              # → 10 read-only tools for your agent
 - 🧠 **LLM enrichment, budgeted & opt-in** — design-pattern tags (*"this class is a
   Repository,"* with confidence + rationale) and bottom-up module summaries, all
   `llm`-provenance. **CI needs no model calls or cloud creds.**
-
-**Status: 0.3.3 — all 12 planned features shipped.** Published on
+- 🏢 **Scales from one repo to a whole org** — host the index **centrally** (shared
+  dir or SurrealDB/Neo4j), built once and consumed **read-only** by many; serve a
+  multi-repo **workspace** from one federated MCP endpoint; and **trace requests
+  across services** — `ckg services-map` / `ckg trace` draw the cross-service call
+  graph (HTTP client → route, matched by path or OpenAPI contract).
+
+**Status: 0.5.0 — all 12 planned features shipped, now org-scale.** 0.5 adds
+central hosting + read-only consumers, a federated multi-repo workspace, and
+cross-service request tracing on top. Published on
 [PyPI](https://pypi.org/project/agentforge-graph/). Each language pack validated on
 a real OSS repo with a creds-enabled embed/retrieval/enrich run; a real agent
 answers questions over the tools unattended. See the [`CHANGELOG`](https://github.com/Scaffoldic/agentforge-graph/blob/main/CHANGELOG.md)
@@ -71,9 +79,38 @@ and [`docs/features/TRACKER.md`](https://github.com/Scaffoldic/agentforge-graph/
 
 ---
 
+## Run it three ways — one repo, a workspace, or a central store
+
+```bash
+# 1) a single repo — a typed graph in seconds
+ckg index . && ckg routes .
+
+# 2) a central store — host the index outside the repo, consume read-only
+#    (set store.central_root in ckg.yaml; built once by CI, read by many)
+ckg status . --read-only
+
+# 3) a workspace — the cross-service call graph across services
+ckg services-map --workspace workspace.yaml      # who calls whom (HTTP → route)
+ckg trace payments --workspace workspace.yaml --direction upstream   # blast radius
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Scaffoldic/agentforge-graph/main/docs/assets/setups.gif"
+       alt="ckg run three ways: a single repo (index + routes), a central store (hosted + read-only), and a workspace (cross-service call graph + trace)"
+       width="820">
+  <br>
+  <em>Single repo → central store → workspace — the cross-service call graph and blast-radius trace, all creds-free.</em>
+</p>
+
+→ pick your path: **[a single repo](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/1-single-repo.md)** ·
+**[a workspace](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/2-workspace.md)** ·
+**[a central store](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/3-central-store.md)**.
+
+---
+
 ## Quick start
 
-> **Prefer a guided walkthrough?** Follow **[01 — Getting started](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/01-getting-started.md)** (install → index → query → serve, ~10 min), or browse all [step-by-step guides](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/README.md).
+> **Prefer a guided walkthrough?** Pick your setup — **[a single repo](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/1-single-repo.md)** (~10 min), **[a workspace](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/2-workspace.md)** (microservices, one federated endpoint), or **[a central store](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/3-central-store.md)** (org-level shared index) — from the **[Getting started hub](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/01-getting-started.md)**. Or browse all [step-by-step guides](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/README.md).
 
 ```bash
 pip install agentforge-graph                # engine included (tree-sitter + kuzu + lancedb)
@@ -313,7 +350,7 @@ This repo is built to be worked on **with** AI agents. Start here:
 | Doc | What it is |
 |---|---|
 | [`docs/ARCHITECTURE.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/ARCHITECTURE.md) | High-level architecture + every pipeline (ASCII) |
-| [**`docs/guides/`**](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/README.md) | **Step-by-step guides** (numbered learning path, each with a TL;DR). Start with **[01 — Getting started](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/01-getting-started.md)** (install → index → query → serve), then: [02 indexing & retrieval](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/02-indexing-and-retrieval.md) · [03 framework extraction](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/03-framework-extraction.md) · [04 cross-file resolution](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/04-cross-file-framework-resolution.md) · [05 architecture decisions](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/05-architecture-decisions.md) · [06 temporal/history](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/06-temporal-history.md) · [07 enrichment](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/07-enrichment.md) · [08 model providers](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/08-model-providers.md) · [09 storage backends](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/09-storage-backends.md) · [10 using over MCP](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/10-using-over-mcp.md) |
+| [**`docs/guides/`**](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/README.md) | **Step-by-step guides** (each with a TL;DR). **Getting started — pick your setup:** [a single repo](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/1-single-repo.md) · [a workspace](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/2-workspace.md) · [a central store](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/getting-started/3-central-store.md). **Topic guides:** [02 indexing & retrieval](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/02-indexing-and-retrieval.md) · [03 framework extraction](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/03-framework-extraction.md) · [04 cross-file resolution](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/04-cross-file-framework-resolution.md) · [05 architecture decisions](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/05-architecture-decisions.md) · [06 temporal/history](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/06-temporal-history.md) · [07 enrichment](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/07-enrichment.md) · [08 model providers](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/08-model-providers.md) · [09 storage backends](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/09-storage-backends.md) · [10 using over MCP](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/guides/10-using-over-mcp.md) |
 | [`examples/`](https://github.com/Scaffoldic/agentforge-graph/tree/main/examples) | Runnable sample repos (index → routes/models/services/query) |
 | [`docs/adr/`](https://github.com/Scaffoldic/agentforge-graph/tree/main/docs/adr/) | 9 architecture decision records (the *why*) |
 | [`docs/features/`](https://github.com/Scaffoldic/agentforge-graph/tree/main/docs/features/) + [`TRACKER.md`](https://github.com/Scaffoldic/agentforge-graph/blob/main/docs/features/TRACKER.md) | 12 feature specs + status board |

{agentforge_graph-0.4.0 → agentforge_graph-0.5.0}/agentforge.yaml

@@ -1,4 +1,3 @@
-# AGENTFORGE-MANAGED: template:minimal@0.2.4 hash:3f971e1f7bac
 # NOTE: customized for agentforge-graph. One config file: the framework keys
 # below, plus this agent's own engine config under the `app:` passthrough
 # (agentforge-py >=0.3 — the strict validator accepts a free-form `app:` section).