@wwjd/pi-graphify 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0](https://github.com/WianVDM/pi-graphify/compare/pi-graphify-v0.2.0...pi-graphify-v0.3.0) (2026-07-12)
+
+
+### Features
+
+* **tools:** add build, query, path, explain, affected, and version tools ([5b8cb07](https://github.com/WianVDM/pi-graphify/commit/5b8cb0730f7c766dd00f40149e7abb6b1fce64fa))
+* **tools:** add shared tool types and formatting helpers ([0efd421](https://github.com/WianVDM/pi-graphify/commit/0efd4214e6b4397c126abecb864ad947be896fa6))
+
+
+### Bug Fixes
+
+* replace /graphify-build references with graphify CLI command ([63f4fb2](https://github.com/WianVDM/pi-graphify/commit/63f4fb25889719448f13c4dffb485164f7774c55))
+
 ## [0.2.0](https://github.com/WianVDM/pi-graphify/compare/pi-graphify-v0.1.0...pi-graphify-v0.2.0) (2026-07-12)
 
 

package/README.md

@@ -1,93 +1,86 @@
 # pi-graphify
 
-A production-quality [pi](https://pi.dev) extension for [Graphify](https://github.com/Graphify-Labs/graphify).
+A [Pi](https://pi.dev) extension that brings [Graphify](https://github.com/Graphify-Labs/graphify) knowledge graph capabilities into your agent sessions.
 
-This extension brings Graphify knowledge graph capabilities into your Pi sessions, making it easy to query, explore, and update codebase graphs without leaving the agent.
+## Install
 
-> ⚠️ **Work in progress** — this package is in early development. The public API, tools, and commands will evolve as the extension matures toward a stable 1.0 release.
+```bash
+pi install @wwjd/pi-graphify
+```
 
-## Quick Start
+Or run locally during development:
 
 ```bash
-# Install from a local path (during development)
 pi install .
-
-# Or run ephemerally without installing
-pi -e .
-
-# Type check
-npm run typecheck
-
-# Lint
-npm run lint
 ```
 
-## What's Included
+## What it does
 
-```
-pi-graphify/
-├── extensions/
-│   └── index.ts          # Extension entry point (tools, commands, events)
-├── src/                   # Core implementation
-├── package.json           # Pi manifest + npm config
-├── tsconfig.json          # TypeScript config (type checking only)
-├── biome.json             # Linter/formatter config
-├── .gitignore
-├── LICENSE
-├── CHANGELOG.md
-├── RELEASE.md             # Versioning and release standards
-├── AGENTS.md              # Agent context / development conventions
-└── README.md
-```
+`pi-graphify` detects the Graphify CLI and a project's `graphify-out/graph.json` graph, then exposes Graphify operations as Pi tools and slash commands. It routes requests through a backend abstraction so the agent can use Graphify without worrying about whether it's talking to the CLI or (in the future) an MCP server.
+
+When a graph is present, the extension also injects a lightweight hint into the system prompt so the agent knows it can ask structural codebase questions via the graph.
 
-## Package Structure
+## Requirements
 
-### Extensions (`extensions/`)
+- [Graphify](https://github.com/Graphify-Labs/graphify) must be installed and on your `PATH`.
+- The project must have a generated graph at `graphify-out/graph.json`.
 
-TypeScript modules that extend pi's behavior with custom tools, slash commands, and event handlers.
+## Current commands
 
-### Source (`src/`)
+| Command | Description |
+|---|---|
+| `/graphify-status` | Check whether a graph exists and whether the Graphify CLI is compatible. |
 
-Pi-agnostic implementation logic. The `extensions/` layer imports from here and registers everything with Pi.
+## Current tools
 
-## Development
+| Tool | Description |
+|---|---|
+| `graphify_status` | Check graph presence, path, and Graphify CLI compatibility. |
+| `graphify_build` | Build or incrementally update the Graphify knowledge graph. |
+| `graphify_query` | Ask a natural-language question against the graph. |
+| `graphify_path` | Find the shortest path between two graph nodes. |
+| `graphify_explain` | Explain a node and its connections in the graph. |
+| `graphify_affected` | Show the blast radius of changes to one or more files. |
+| `graphify_version` | Report the installed Graphify version and compatibility status. |
 
-### Requirements
+## What's coming
 
-- Node.js 22+
-- npm 10+
-- pi CLI
+Slash commands for the tools above are planned in the next phase:
 
-### Scripts
+- `/graphify-build`
+- `/graphify-query`
+- `/graphify-path`
+- `/graphify-explain`
+- `/graphify-affected`
+- `/graphify-version`
 
-| Command | Description |
-|---------|-------------|
-| `npm run typecheck` | TypeScript type checking (`tsc --noEmit`) |
-| `npm run lint` | Check lint + formatting (`biome check`) |
-| `npm run lint:fix` | Auto-fix lint + formatting issues |
-| `npm run format` | Format code only |
+Later phases will add background file watching, MCP backend support, ecosystem integrations, and release readiness work. See [plan/PLAN.md](plan/PLAN.md) for the full roadmap.
 
-### Testing the package
+## How it works
 
-```bash
-# Run ephemerally with no other extensions loaded
-pi -ne -e . --no-session
+1. On session start, the extension detects the installed Graphify version and looks for `graphify-out/graph.json`.
+2. If a graph is found, a hint is added to the agent context.
+3. Tools and commands route through a coordinator that selects the best available backend.
 
-# Test a specific tool in print mode
-pi -ne -e . --no-session -p "List the available tools."
-```
+## Status
 
-## Publishing
+This extension is in early development. The public API, tools, and commands will evolve as the extension matures toward a stable 1.0 release.
 
-This package is intended for publication to npm so it can be listed on [pi.dev/packages](https://pi.dev/packages). CI/CD workflows for release automation are included under `.github/workflows/`.
+## Documentation
 
-See `RELEASE.md` for versioning and release standards.
+- [Design](docs/DESIGN.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Ecosystem](docs/ECOSYSTEM.md)
+- [Versioning](docs/VERSIONING.md)
+- [Release standards](RELEASE.md)
+- [Agent context](AGENTS.md)
 
-Before publishing, update:
+## Development
 
-- `package.json` author and repository fields
-- `README.md` with final usage instructions
-- `CHANGELOG.md` with release notes
+```bash
+npm run typecheck
+npm run lint
+```
 
 ## License
 

package/docs/TESTING.md

@@ -0,0 +1,149 @@
+# Local Development and Testing Guide
+
+This guide covers how to install and test the local `pi-graphify` extension, plus how to install and uninstall the Graphify CLI for end-to-end verification.
+
+## Prerequisites
+
+- [Pi](https://pi.dev) installed and on your PATH.
+- Node.js 20+ and npm.
+- Python 3.10+ (only needed when testing with the Graphify CLI).
+- [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/) (recommended for Graphify).
+
+## Install the local pi-graphify extension
+
+From the project root directory, run:
+
+```bash
+pi install .
+```
+
+This installs the local package into Pi so the extension is loaded on the next Pi session.
+
+To verify the install, start Pi in any project and check that `/graphify-status` autocompletes.
+
+## Automated checks
+
+Before running manual tests, run the static and automated checks:
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm audit --audit-level=moderate
+```
+
+All should pass.
+
+## Install the Graphify CLI
+
+The official PyPI package is **`graphifyy`** (double-y). The CLI command is still `graphify`.
+
+### Recommended: uv
+
+```bash
+uv tool install graphifyy
+graphify --version
+```
+
+### Alternative: pipx
+
+```bash
+pipx install graphifyy
+graphify --version
+```
+
+### Alternative: pip
+
+```bash
+pip install graphifyy
+graphify --version
+```
+
+After installing, `graphify` should be available on your PATH. If it is not, add the tool's bin directory to your PATH (for example, `~/.local/bin` for `uv tool` or `pipx`).
+
+## Build a graph for testing
+
+Phase 3 only adds the tools. The `/graphify-build` command is added in Phase 4, so for now build the graph directly with the Graphify CLI.
+
+The recommended approach for testing `pi-graphify` is a code-only graph. It skips semantic extraction, so it does not require an API key or extra Python dependencies:
+
+```bash
+graphify . --code-only
+```
+
+This creates a `graphify-out/` directory with `graph.json`, `graph.html`, and `GRAPH_REPORT.md`. It has been verified to work with the default `uv tool install graphifyy` setup.
+
+If you want semantic extraction (docs, images, etc.), you need the `kimi` backend dependencies. Install them with:
+
+```bash
+uv tool install "graphifyy[kimi]" --force
+```
+
+Then run the full build:
+
+```bash
+graphify .
+```
+
+Once Phase 4 is complete, `/graphify-build` will be available as an alternative.
+
+## Verify the extension with Graphify installed
+
+1. Start Pi in a project with a built graph.
+2. You should see a notification: `Graphify graph ready: ...`.
+3. The supported tools should be available to the LLM. You can verify by asking: "What graphify tools are available?" or by checking the system prompt tool list.
+4. Test a tool by asking: "Use the graphify graph to explain how auth works in this codebase."
+
+## Verify the extension without Graphify
+
+1. Uninstall Graphify (see below).
+2. Start Pi in a project.
+3. You should see a warning: `Graphify CLI was not detected on PATH...`.
+4. No `graphify_*` tools should be available to the LLM.
+5. `/graphify-status` should still work and report that no graph was found.
+
+## Uninstall the Graphify CLI
+
+### uv
+
+```bash
+uv tool uninstall graphifyy
+```
+
+### pipx
+
+```bash
+pipx uninstall graphifyy
+```
+
+### pip
+
+```bash
+pip uninstall graphifyy
+```
+
+After uninstalling, run `graphify --version` to confirm it is no longer on PATH.
+
+## Uninstall the local pi-graphify extension
+
+```bash
+pi uninstall npm:@wwjd/pi-graphify
+```
+
+Or remove the package manually from Pi's package directory if you installed it locally.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `graphify` command not found after install | Ensure the tool bin directory is on your PATH. For `uv tool`, try `uv tool update-shell`. |
+| Pi does not load the extension | Run `pi --version` and confirm the package is listed in `pi packages`. Try `/reload`. |
+| Extension shows old version after changes | Run `pi install .` again, then start a fresh Pi session. |
+| `graphify_status` returns "No Graphify graph found" | Build the graph first with `graphify . --code-only`. |
+| Semantic extraction fails with `openai` package error | Run `graphify . --code-only` for a code-only graph, or install the `kimi` backend with `uv tool install "graphifyy[kimi]" --force`. |
+
+## References
+
+- [Graphify repository](https://github.com/Graphify-Labs/graphify)
+- [graphifyy on PyPI](https://pypi.org/project/graphifyy/)
+- [Pi extensions documentation](https://pi.dev/docs/extensions)

package/extensions/index.ts

@@ -4,7 +4,7 @@
  * Brings Graphify knowledge graph capabilities into Pi sessions:
  *   - Detects existing graphify-out/graph.json in the project
  *   - Registers LLM-callable tools (graphify_status, graphify_query, ...)
- *   - Registers slash commands (/graphify-build, /graphify-status, ...)
+ *   - Registers slash commands (/graphify-status, ...)
  *   - Optionally watches source files for incremental rebuilds
  */
 
@@ -17,10 +17,9 @@ export default function (pi: ExtensionAPI) {
   // Coordinator is created per session and shared by tools and commands.
   let coordinator: GraphifyCoordinator | null = null;
   const getCoordinator = () => coordinator;
+  const registeredToolNames = new Set<string>();
 
-  // ── 1. Register tools and commands synchronously ──────────────────
-  registerGraphifyTools(pi, getCoordinator);
-
+  // ── 1. Register slash commands synchronously ─────────────────────
   pi.registerCommand("graphify-status", {
     description: "Show Graphify graph status for the current project",
     handler: async (_args, ctx) => {
@@ -34,16 +33,21 @@ export default function (pi: ExtensionAPI) {
       if (status.hasGraph && status.graphPath) {
         ctx.ui.notify(`Graphify graph ready: ${status.graphPath}`, "info");
       } else {
-        ctx.ui.notify("No Graphify graph found. Run /graphify-build to create one.", "warning");
+        ctx.ui.notify("No Graphify graph found. Build one with `graphify .`.", "warning");
       }
     },
   });
 
-  // ── 2. Initialize coordinator per session ─────────────────────────
+  // ── 2. Initialize coordinator and register tools per session ───────
+  // Tools are registered inside session_start so we can gate them by the
+  // coordinator's detected capabilities. Registering at load time would mean
+  // the LLM sees tools that may not be supported by the installed Graphify version.
   pi.on("session_start", async (_event, ctx) => {
     coordinator = new GraphifyCoordinator({ cwd: ctx.cwd });
     await coordinator.initialize();
 
+    registerGraphifyTools(pi, getCoordinator, { registeredToolNames });
+
     const status = await coordinator.status({ cwd: ctx.cwd });
     if (status.hasGraph && status.graphPath) {
       ctx.ui.notify(`Graphify graph ready: ${status.graphPath}`, "info");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwjd/pi-graphify",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Graphify knowledge graph integration for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "scripts": {
-    "test": "echo \"No tests yet\" && exit 0",
+    "test": "node --test --import tsx src/tools/tools.test.ts src/extensions/extension-load.test.ts",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
@@ -57,6 +57,7 @@
     "@earendil-works/pi-ai": "^0.74.0",
     "@earendil-works/pi-coding-agent": "^0.80.6",
     "@types/node": "^20.0.0",
+    "tsx": "^4.23.0",
     "typebox": "^1.1.24",
     "typescript": "^5.0.0"
   },

package/src/backends/mock.ts

@@ -0,0 +1,47 @@
+import type { GraphifyBackend, GraphifyCapabilities, GraphifyResult } from "./types.js";
+
+export const allCapabilitiesEnabled = (): GraphifyCapabilities => ({
+  build: true,
+  query: true,
+  path: true,
+  explain: true,
+  affected: true,
+  add: true,
+  watch: true,
+  reflect: true,
+  mcp: true,
+  status: true,
+  version: true,
+  directedGraph: true,
+  incrementalUpdate: true,
+  semanticExtraction: true,
+});
+
+export interface MockBackendOptions {
+  version?: string;
+  capabilities?: GraphifyCapabilities;
+  run?: (operation: string, options: unknown) => Promise<GraphifyResult>;
+}
+
+export function createMockBackend(options: MockBackendOptions = {}): GraphifyBackend {
+  const {
+    version = "2.100.0",
+    capabilities = allCapabilitiesEnabled(),
+    run = async (operation) => ({
+      stdout: `ok: ${operation}`,
+      stderr: "",
+      exitCode: 0,
+      durationMs: 1,
+      backend: "cli",
+      feature: operation,
+    }),
+  } = options;
+
+  return {
+    type: "cli",
+    version,
+    capabilities,
+    run,
+    close: async () => {},
+  };
+}

package/src/coordinator.ts

@@ -37,6 +37,8 @@ export interface GraphifyStatusResult {
 export interface CoordinatorOptions {
   cwd: string;
   config?: GraphifyConfig;
+  /** Optional backend, primarily for tests. */
+  backend?: GraphifyBackend;
 }
 
 export class GraphifyCoordinator {
@@ -49,6 +51,7 @@ export class GraphifyCoordinator {
   constructor(options: CoordinatorOptions) {
     this.cwd = options.cwd;
     this.config = options.config ?? loadConfig();
+    this.backend = options.backend ?? null;
   }
 
   async initialize(): Promise<void> {
@@ -57,11 +60,13 @@ export class GraphifyCoordinator {
     }
 
     try {
-      // Phase 2 only supports CLI backend. MCP is a Phase 6 addition.
-      this.backend = await createCliBackend({
-        cwd: this.cwd,
-        timeoutMs: this.config.queryTimeoutMs,
-      });
+      if (!this.backend) {
+        // Phase 2 only supports CLI backend. MCP is a Phase 6 addition.
+        this.backend = await createCliBackend({
+          cwd: this.cwd,
+          timeoutMs: this.config.queryTimeoutMs,
+        });
+      }
     } catch (error) {
       this.backend = null;
       this._warnings.push(

package/src/extensions/extension-load.test.ts

@@ -0,0 +1,15 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+
+/**
+ * Smoke test that verifies the extension entry point module loads and exports a
+ * valid factory function. This catches syntax errors, import issues, or jiti
+ * problems without requiring the full Pi runtime.
+ */
+describe("extension entry point", () => {
+  it("exports a default factory function", async () => {
+    const module = await import("../../extensions/index.js");
+    assert.equal(typeof module.default, "function");
+    assert.equal(module.default.length, 1);
+  });
+});

package/src/graphify.ts

@@ -33,6 +33,8 @@ export function buildGraphifyHint(graphPath: string): string {
     "<graphify-context>",
     `A Graphify knowledge graph is available at ${graphPath}.`,
     "When answering questions about this codebase, prefer querying the graph via the graphify_status, graphify_query, graphify_path, and graphify_explain tools instead of grepping or reading raw files.",
+    "Use graphify_explain to explain a specific function, file, tool, or concept that is a node in the graph.",
+    "Use graphify_path to trace how two functions, files, tools, or concepts are connected in the graph.",
     "Only fall back to raw file reads when the graph lacks the needed detail or when modifying/debugging specific lines.",
     "</graphify-context>",
   ].join("\n");

package/src/tools/affected.ts

@@ -0,0 +1,37 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { GraphifyError } from "../errors.js";
+import { formatGraphifyError, formatGraphifyResult } from "./format.js";
+import type { CoordinatorProvider } from "./index.js";
+
+export function registerAffectedTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_affected",
+    label: "Graphify Affected",
+    description: "Show the blast radius of changes to the given files or nodes.",
+    promptSnippet: "Show what files, nodes, or concepts depend on the given files or nodes",
+    promptGuidelines: [
+      "Use graphify_affected when the user asks what would break if they change a file or node.",
+      "Use graphify_affected to find downstream dependents of a file or concept before refactoring.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.String({ description: "Working directory of the project to analyze." }),
+      files: Type.Array(Type.String({ minLength: 1 }), {
+        minItems: 1,
+        description: "The files or nodes whose downstream dependents should be reported.",
+      }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const coordinator = getCoordinator();
+      if (!coordinator) {
+        return formatGraphifyError(new GraphifyError("MISSING", "Graphify is not initialized."));
+      }
+      try {
+        const result = await coordinator.affected({ ...params, cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}

package/src/tools/build.ts

@@ -0,0 +1,43 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { GraphifyError } from "../errors.js";
+import { formatGraphifyError, formatGraphifyResult } from "./format.js";
+import type { CoordinatorProvider } from "./index.js";
+
+export function registerBuildTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_build",
+    label: "Graphify Build",
+    description:
+      "Build or incrementally update the Graphify knowledge graph for the current project.",
+    promptSnippet: "Build or update the project's Graphify knowledge graph",
+    promptGuidelines: [
+      "Use graphify_build when the user wants to create or update the knowledge graph.",
+      "Use graphify_build when graphify_status reports that no graph exists.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.String({ description: "Working directory of the project to build the graph for." }),
+      codeOnly: Type.Optional(
+        Type.Boolean({ description: "Only index code files; skip semantic extraction." }),
+      ),
+      update: Type.Optional(
+        Type.Boolean({ description: "Perform an incremental update instead of a full rebuild." }),
+      ),
+      directed: Type.Optional(
+        Type.Boolean({ description: "Build a directed graph instead of an undirected one." }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const coordinator = getCoordinator();
+      if (!coordinator) {
+        return formatGraphifyError(new GraphifyError("MISSING", "Graphify is not initialized."));
+      }
+      try {
+        const result = await coordinator.build({ ...params, cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}

package/src/tools/explain.ts

@@ -0,0 +1,38 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { GraphifyError } from "../errors.js";
+import { formatGraphifyError, formatGraphifyResult } from "./format.js";
+import type { CoordinatorProvider } from "./index.js";
+
+export function registerExplainTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_explain",
+    label: "Graphify Explain",
+    description:
+      "Explain how a specific node (function, file, tool, or concept) is connected in the Graphify knowledge graph.",
+    promptSnippet: "Explain a function, file, tool, or concept from the project's knowledge graph",
+    promptGuidelines: [
+      "Use graphify_explain when the user asks what a specific function, file, tool, or concept does.",
+      "Use graphify_explain instead of reading source code when the subject is a node in the knowledge graph.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.String({ description: "Working directory of the project to explain." }),
+      node: Type.String({
+        minLength: 1,
+        description: "The node or concept to explain in the graph.",
+      }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const coordinator = getCoordinator();
+      if (!coordinator) {
+        return formatGraphifyError(new GraphifyError("MISSING", "Graphify is not initialized."));
+      }
+      try {
+        const result = await coordinator.explain({ ...params, cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}

package/src/tools/format.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared result formatting helpers for graphify tools.
+ */
+
+import type { GraphifyResult } from "../backends/types.js";
+import { GraphifyError } from "../errors.js";
+import { errorResult, successResult, type ToolResult } from "./types.js";
+
+/** Format a successful Graphify result into tool content. */
+export function formatGraphifyResult(result: GraphifyResult): ToolResult {
+  return successResult(result);
+}
+
+/** Format a Graphify or unexpected error into friendly tool content. */
+export function formatGraphifyError(error: unknown): ToolResult {
+  if (error instanceof GraphifyError) {
+    return errorResult(error.userMessage, { code: error.code, details: error.details });
+  }
+
+  if (error instanceof Error) {
+    return errorResult(error.message);
+  }
+
+  return errorResult(String(error));
+}

package/src/tools/index.ts

@@ -1,12 +1,89 @@
-/**
- * Tool registration barrel
- */
-
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { GraphifyCapabilities } from "../backends/types.js";
+import type { GraphifyCoordinator } from "../coordinator.js";
+import { registerAffectedTool } from "./affected.js";
+import { registerBuildTool } from "./build.js";
+import { registerExplainTool } from "./explain.js";
+import { registerPathTool } from "./path.js";
+import { registerQueryTool } from "./query.js";
 import { registerStatusTool } from "./status.js";
+import { registerVersionTool } from "./version.js";
+
+export type CoordinatorProvider = () => GraphifyCoordinator | null;
+
+export interface RegisterToolsOptions {
+  /** Tracks tool names that have already been registered to prevent duplicates. */
+  registeredToolNames: Set<string>;
+}
+
+export function registerGraphifyTools(
+  pi: ExtensionAPI,
+  getCoordinator: CoordinatorProvider,
+  options: RegisterToolsOptions,
+): void {
+  const { registeredToolNames } = options;
+  const coordinator = getCoordinator();
+  if (!coordinator) {
+    return;
+  }
 
-export type CoordinatorProvider = () => import("../coordinator.js").GraphifyCoordinator | null;
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_status", () =>
+    registerStatusTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_build", () =>
+    registerBuildTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_query", () =>
+    registerQueryTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_path", () =>
+    registerPathTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_explain", () =>
+    registerExplainTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_affected", () =>
+    registerAffectedTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_version", () =>
+    registerVersionTool(pi, getCoordinator),
+  );
+}
+
+function registerToolIfSupported(
+  coordinator: GraphifyCoordinator,
+  registeredToolNames: Set<string>,
+  name: string,
+  register: () => void,
+): void {
+  if (registeredToolNames.has(name)) {
+    return;
+  }
+
+  const feature = nameToFeature(name);
+  if (feature && !coordinator.supports(feature)) {
+    return;
+  }
+
+  registeredToolNames.add(name);
+  register();
+}
 
-export function registerGraphifyTools(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
-  registerStatusTool(pi, getCoordinator);
+function nameToFeature(name: string): keyof GraphifyCapabilities | null {
+  switch (name) {
+    case "graphify_build":
+      return "build";
+    case "graphify_query":
+      return "query";
+    case "graphify_path":
+      return "path";
+    case "graphify_explain":
+      return "explain";
+    case "graphify_affected":
+      return "affected";
+    case "graphify_version":
+      return "version";
+    default:
+      return null;
+  }
 }

package/src/tools/path.ts

@@ -0,0 +1,43 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { GraphifyError } from "../errors.js";
+import { formatGraphifyError, formatGraphifyResult } from "./format.js";
+import type { CoordinatorProvider } from "./index.js";
+
+export function registerPathTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_path",
+    label: "Graphify Path",
+    description:
+      "Trace the shortest path between two nodes (functions, files, tools, or concepts) in the Graphify knowledge graph.",
+    promptSnippet:
+      "Trace how two functions, files, tools, or concepts are connected in the knowledge graph",
+    promptGuidelines: [
+      "Use graphify_path when the user asks how two concepts, functions, files, tools, or symbols are related.",
+      "Use graphify_path instead of manually tracing code when both source and target are known nodes in the graph.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.String({ description: "Working directory of the project to search." }),
+      source: Type.String({
+        minLength: 1,
+        description: "The source node or concept to start from.",
+      }),
+      target: Type.String({
+        minLength: 1,
+        description: "The target node or concept to find a path to.",
+      }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const coordinator = getCoordinator();
+      if (!coordinator) {
+        return formatGraphifyError(new GraphifyError("MISSING", "Graphify is not initialized."));
+      }
+      try {
+        const result = await coordinator.path({ ...params, cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}

package/src/tools/query.ts

@@ -0,0 +1,37 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { GraphifyError } from "../errors.js";
+import { formatGraphifyError, formatGraphifyResult } from "./format.js";
+import type { CoordinatorProvider } from "./index.js";
+
+export function registerQueryTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_query",
+    label: "Graphify Query",
+    description: "Ask a natural-language question against the Graphify knowledge graph.",
+    promptSnippet: "Ask a natural-language question about the project's knowledge graph",
+    promptGuidelines: [
+      "Use graphify_query when the user asks a broad question about the codebase.",
+      "Use graphify_query instead of grepping or reading files when a graph is available.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.String({ description: "Working directory of the project to query." }),
+      question: Type.String({
+        minLength: 1,
+        description: "The natural-language question to run against the graph.",
+      }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const coordinator = getCoordinator();
+      if (!coordinator) {
+        return formatGraphifyError(new GraphifyError("MISSING", "Graphify is not initialized."));
+      }
+      try {
+        const result = await coordinator.query({ ...params, cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}

package/src/tools/status.ts

@@ -11,6 +11,11 @@ export function registerStatusTool(pi: ExtensionAPI, getCoordinator: Coordinator
     name: "graphify_status",
     label: "Graphify Status",
     description: "Check whether a Graphify knowledge graph exists for the current project.",
+    promptSnippet: "Check whether a Graphify knowledge graph exists for the current project",
+    promptGuidelines: [
+      "Use graphify_status when the user asks if a Graphify graph is available.",
+      "Use graphify_status before calling other graphify tools to confirm the graph exists.",
+    ],
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const coordinator = getCoordinator();
@@ -38,7 +43,7 @@ export function registerStatusTool(pi: ExtensionAPI, getCoordinator: Coordinator
           content: [
             {
               type: "text",
-              text: `No Graphify graph found. Run /graphify-build to build one.${cliNote}`,
+              text: `No Graphify graph found. Build one with \`graphify .\`.${cliNote}`,
             },
           ],
           details,

package/src/tools/tools.test.ts

@@ -0,0 +1,282 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { allCapabilitiesEnabled, createMockBackend } from "../backends/mock.js";
+import { GraphifyCoordinator } from "../coordinator.js";
+import { GraphifyError } from "../errors.js";
+import { type RegisterToolsOptions, registerGraphifyTools } from "./index.js";
+
+interface ToolRecord {
+  name: string;
+  label: string;
+  description: string;
+  parameters: unknown;
+  execute: (
+    toolCallId: string,
+    params: unknown,
+    signal: unknown,
+    onUpdate: (content: unknown) => void,
+    ctx: { cwd: string },
+  ) => Promise<{ content: { type: string; text: string }[]; details: Record<string, unknown> }>;
+}
+
+interface MockPi {
+  tools: Record<string, ToolRecord>;
+  registerTool: (tool: ToolRecord) => void;
+}
+
+function createMockPi(): MockPi {
+  const tools: Record<string, ToolRecord> = {};
+  return {
+    tools,
+    registerTool: (tool: ToolRecord) => {
+      tools[tool.name] = tool;
+    },
+  };
+}
+
+function createTestCoordinator(backend = createMockBackend()): GraphifyCoordinator {
+  return new GraphifyCoordinator({ cwd: process.cwd(), backend });
+}
+
+function createRegisterOptions(): RegisterToolsOptions {
+  return { registeredToolNames: new Set<string>() };
+}
+
+const noopOnUpdate = (): void => {};
+
+const expectedTools = [
+  "graphify_status",
+  "graphify_build",
+  "graphify_query",
+  "graphify_path",
+  "graphify_explain",
+  "graphify_affected",
+  "graphify_version",
+];
+
+describe("registerGraphifyTools", () => {
+  it("registers all expected tools when all capabilities are enabled", () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    const options = createRegisterOptions();
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => coordinator, options);
+
+    for (const name of expectedTools) {
+      assert.ok(name in pi.tools, `expected tool ${name} to be registered`);
+    }
+  });
+
+  it("does not register tools when coordinator is null", () => {
+    const pi = createMockPi();
+    const options = createRegisterOptions();
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => null, options);
+
+    assert.equal(Object.keys(pi.tools).length, 0);
+  });
+
+  it("skips tools whose capabilities are disabled", () => {
+    const pi = createMockPi();
+    const capabilities = { ...allCapabilitiesEnabled(), build: false, query: false };
+    const backend = createMockBackend({ capabilities });
+    const coordinator = createTestCoordinator(backend);
+    const options = createRegisterOptions();
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => coordinator, options);
+
+    assert.ok(
+      !("graphify_build" in pi.tools),
+      "graphify_build should not be registered when build is unsupported",
+    );
+    assert.ok(
+      !("graphify_query" in pi.tools),
+      "graphify_query should not be registered when query is unsupported",
+    );
+    assert.ok(
+      "graphify_path" in pi.tools,
+      "graphify_path should be registered when path is supported",
+    );
+  });
+
+  it("prevents duplicate registration when called again with the same set", () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    const options = createRegisterOptions();
+
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => coordinator, options);
+    const firstCount = Object.keys(pi.tools).length;
+
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => coordinator, options);
+    const secondCount = Object.keys(pi.tools).length;
+
+    assert.equal(firstCount, expectedTools.length);
+    assert.equal(secondCount, expectedTools.length);
+  });
+});
+
+async function runTool(
+  pi: MockPi,
+  name: string,
+  params: Record<string, unknown>,
+  cwd: string,
+): Promise<{ content: { type: string; text: string }[]; details: Record<string, unknown> }> {
+  return pi.tools[name].execute("call-1", params, null, noopOnUpdate, { cwd });
+}
+
+describe("graphify_build", () => {
+  it("returns formatted result on success", async () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(pi, "graphify_build", {}, process.cwd());
+
+    assert.equal(result.content[0].text, "ok: build");
+    assert.equal(result.details.exitCode, 0);
+    assert.equal(result.details.feature, "build");
+  });
+});
+
+describe("graphify_query", () => {
+  it("passes question and cwd to the coordinator", async () => {
+    const pi = createMockPi();
+    let captured: unknown = null;
+    const backend = createMockBackend({
+      run: async (_operation, options) => {
+        captured = options;
+        return {
+          stdout: "answer",
+          stderr: "",
+          exitCode: 0,
+          durationMs: 1,
+          backend: "cli",
+          feature: "query",
+        };
+      },
+    });
+    const coordinator = createTestCoordinator(backend);
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(
+      pi,
+      "graphify_query",
+      { question: "how does auth work?" },
+      process.cwd(),
+    );
+
+    assert.equal(result.content[0].text, "answer");
+    assert.deepEqual(captured, { cwd: process.cwd(), question: "how does auth work?" });
+  });
+
+  it("is not registered when the coordinator is missing", () => {
+    const pi = createMockPi();
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => null, createRegisterOptions());
+    assert.equal("graphify_query" in pi.tools, false);
+  });
+
+  it("returns an error when the coordinator becomes null after registration", async () => {
+    const pi = createMockPi();
+    let coordinator: GraphifyCoordinator | null = createTestCoordinator();
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+
+    coordinator = null;
+    const result = await runTool(pi, "graphify_query", { question: "x" }, process.cwd());
+
+    assert.ok(result.content[0].text.includes("Graphify is not initialized"));
+  });
+});
+
+describe("graphify_path", () => {
+  it("returns formatted result on success", async () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(pi, "graphify_path", { source: "a", target: "b" }, process.cwd());
+
+    assert.equal(result.content[0].text, "ok: path");
+  });
+});
+
+describe("graphify_explain", () => {
+  it("returns formatted result on success", async () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(pi, "graphify_explain", { node: "auth" }, process.cwd());
+
+    assert.equal(result.content[0].text, "ok: explain");
+  });
+});
+
+describe("graphify_affected", () => {
+  it("returns formatted result on success", async () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(
+      pi,
+      "graphify_affected",
+      { files: ["src/auth.ts"] },
+      process.cwd(),
+    );
+
+    assert.equal(result.content[0].text, "ok: affected");
+  });
+});
+
+describe("graphify_version", () => {
+  it("returns formatted version on success", async () => {
+    const pi = createMockPi();
+    const backend = createMockBackend({ version: "2.100.0" });
+    const coordinator = createTestCoordinator(backend);
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(pi, "graphify_version", {}, process.cwd());
+
+    assert.equal(result.content[0].text, "2.100.0");
+  });
+});
+
+describe("tool error handling", () => {
+  it("returns friendly error when the backend throws GraphifyError", async () => {
+    const pi = createMockPi();
+    const backend = createMockBackend({
+      run: async () => {
+        throw new GraphifyError("QUERY", "graphify query failed");
+      },
+    });
+    const coordinator = createTestCoordinator(backend);
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(pi, "graphify_query", { question: "x" }, process.cwd());
+
+    assert.ok(result.content[0].text.includes("graphify query failed"));
+  });
+});

package/src/tools/types.ts

@@ -0,0 +1,31 @@
+import type { GraphifyResult } from "../backends/types.js";
+
+export interface ToolContext {
+  cwd: string;
+}
+
+export interface TextContentItem {
+  type: "text";
+  text: string;
+}
+
+export interface ToolResult {
+  content: TextContentItem[];
+  details: Record<string, unknown>;
+}
+
+export function successResult(result: GraphifyResult): ToolResult {
+  return {
+    content: [{ type: "text", text: result.stdout || "Operation completed successfully." }],
+    details: {
+      exitCode: result.exitCode,
+      durationMs: result.durationMs,
+      backend: result.backend,
+      feature: result.feature,
+    },
+  };
+}
+
+export function errorResult(text: string, details: Record<string, unknown> = {}): ToolResult {
+  return { content: [{ type: "text", text: `Error: ${text}` }], details };
+}

package/src/tools/version.ts

@@ -0,0 +1,35 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { GraphifyError } from "../errors.js";
+import { formatGraphifyError, formatGraphifyResult } from "./format.js";
+import type { CoordinatorProvider } from "./index.js";
+
+export function registerVersionTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_version",
+    label: "Graphify Version",
+    description: "Report the installed Graphify version and compatibility status.",
+    promptSnippet: "Report the installed Graphify CLI version and compatibility status",
+    promptGuidelines: [
+      "Use graphify_version when the user asks what version of Graphify is installed.",
+      "Use graphify_version to check whether the installed Graphify version is supported.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.Optional(
+        Type.String({ description: "Optional working directory to check Graphify in." }),
+      ),
+    }),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const coordinator = getCoordinator();
+      if (!coordinator) {
+        return formatGraphifyError(new GraphifyError("MISSING", "Graphify is not initialized."));
+      }
+      try {
+        const result = await coordinator.getVersion({ cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}