@thecat69/cache-ctrl 1.0.0 → 1.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 A CLI tool and native opencode plugin that manages the two AI agent caches (`.ai/external-context-gatherer_cache/` and `.ai/local-context-gatherer_cache/`) with a uniform interface.
 
-It handles advisory locking for safe concurrent writes, keyword search across all entries, HTTP freshness checking for external URLs, and file-change detection for local scans.
+It handles advisory locking for safe concurrent writes, keyword search across all entries, and file-change detection for local scans.
 
 ---
 
@@ -46,26 +46,32 @@ src/index.ts              cache_ctrl.ts
      └──────────┬──────────────┘
                │
         Command Layer
-   src/commands/{list, inspect, flush,
-    invalidate, touch, prune,
-    checkFreshness, checkFiles, search,
-    write}.ts
-                │
-          Core Services
-   cacheManager  ← read/write + advisory lock
-   externalCache ← external staleness logic
-   localCache    ← local scan path logic
-   freshnessChecker ← HTTP HEAD requests
-   changeDetector   ← mtime/hash comparison
+   src/commands/{list, inspect, inspectExternal,
+          inspectLocal, flush, invalidate,
+       touch, prune,
+       checkFiles, search, writeLocal,
+      writeExternal, install, update, uninstall,
+      graph, map, watch, version}.ts
+                 │
+           Core Services
+    cacheManager  ← read/write + advisory lock
+    externalCache ← external staleness logic
+    localCache    ← local scan path logic
+    graphCache    ← graph.json read/write path
+    changeDetector   ← mtime/hash comparison
    keywordSearch    ← scoring engine
-                │
+   analysis/symbolExtractor ← import/export AST pass
+   analysis/graphBuilder    ← dependency graph construction
+   analysis/pageRank        ← Personalized PageRank ranking
+                 │
        Cache Directories (on disk)
    .ai/external-context-gatherer_cache/
      ├── <subject>.json
      └── <subject>.json.lock  (advisory)
    .ai/local-context-gatherer_cache/
      ├── context.json
-     └── context.json.lock    (advisory)
+     ├── context.json.lock    (advisory)
+     └── graph.json           (dependency graph; written by watch daemon)
 ```
 
 **Key design decisions:**
@@ -73,6 +79,7 @@ src/index.ts              cache_ctrl.ts
 - The CLI and plugin share the same command functions — no duplicated business logic.
 - All operations return `Result<T, CacheError>` — nothing throws into the caller.
 - `writeCache` defaults to merging updates onto the existing object (preserving unknown agent fields). Local writes use per-path merge — submitted `tracked_files` entries replace existing entries for those paths; entries for other paths are preserved; entries for files no longer present on disk are evicted automatically.
+- `write.ts` and `inspect.ts` are thin routers; all business logic lives in `writeLocal.ts`, `writeExternal.ts`, `inspectLocal.ts`, `inspectExternal.ts`.
 
 ---
 
@@ -129,6 +136,90 @@ Both operations are idempotent — re-running `cache-ctrl install` after `npm up
 
 ---
 
+### `update`
+
+```
+cache-ctrl update [--config-dir <path>]
+```
+
+Updates the globally installed npm package to the latest version, then re-runs the OpenCode integration install to refresh the tool wrapper and skill files.
+
+1. Runs `npm install -g @thecat69/cache-ctrl@latest`.
+2. Re-runs `cache-ctrl install` (idempotent — regenerates the wrapper with the new package path).
+
+If the `npm install` step fails, the error is recorded in `warnings[]` and the integration install still proceeds.
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--config-dir <path>` | Override the detected OpenCode config directory |
+
+```jsonc
+// cache-ctrl update --pretty
+{
+  "ok": true,
+  "value": {
+    "packageUpdated": true,
+    "installedPaths": [
+      "/home/user/.config/opencode/tools/cache_ctrl.ts",
+      "/home/user/.config/opencode/skills/cache-ctrl-caller/SKILL.md",
+      "/home/user/.config/opencode/skills/cache-ctrl-local/SKILL.md",
+      "/home/user/.config/opencode/skills/cache-ctrl-external/SKILL.md"
+    ],
+    "warnings": []
+  }
+}
+```
+
+**Error codes**: `INVALID_ARGS` if `--config-dir` is outside the user home directory. `FILE_WRITE_ERROR` if the integration files cannot be written.
+
+---
+
+### `uninstall`
+
+```
+cache-ctrl uninstall [--config-dir <path>]
+```
+
+Removes the cache-ctrl OpenCode integration and uninstalls the global npm package.
+
+Removes, in order:
+1. `<configDir>/tools/cache_ctrl.ts`
+2. All `<configDir>/skills/cache-ctrl-*` directories (recursive)
+3. `~/.local/bin/cache-ctrl`
+4. Runs `npm uninstall -g @thecat69/cache-ctrl`
+
+Missing files are not treated as errors — they produce a `warnings[]` entry instead. If the `npm uninstall` step fails, the error is recorded in `warnings[]`.
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--config-dir <path>` | Override the detected OpenCode config directory |
+
+```jsonc
+// cache-ctrl uninstall --pretty
+{
+  "ok": true,
+  "value": {
+    "removed": [
+      "/home/user/.config/opencode/tools/cache_ctrl.ts",
+      "/home/user/.config/opencode/skills/cache-ctrl-caller",
+      "/home/user/.config/opencode/skills/cache-ctrl-local",
+      "/home/user/.config/opencode/skills/cache-ctrl-external",
+      "/home/user/.local/bin/cache-ctrl"
+    ],
+    "packageUninstalled": true,
+    "warnings": []
+  }
+}
+```
+
+**Error codes**: `INVALID_ARGS` if `--config-dir` is outside the user home directory. `UNKNOWN` for unexpected filesystem errors.
+
+---
+
 ### `help`
 
 ```
@@ -277,7 +368,7 @@ cache-ctrl prune [--agent external|local|all] [--max-age <duration>] [--delete]
 
 Finds entries older than `--max-age` and invalidates them (default) or deletes them (`--delete`).
 
-**Duration format**: `<number><unit>` — `h` for hours, `d` for days. Examples: `24h`, `7d`, `1d`.
+**Duration format**: `<number><unit>` — `s` for seconds, `m` for minutes, `h` for hours, `d` for days. Examples: `30s`, `15m`, `24h`, `7d`.
 
 **Defaults**: `--agent all`, `--max-age 24h` for external. Local cache **always** matches (no TTL).
 
@@ -292,36 +383,6 @@ cache-ctrl prune --agent external --max-age 1d --delete
 
 ---
 
-### `check-freshness`
-
-```
-cache-ctrl check-freshness <subject-keyword> [--url <url>] [--pretty]
-```
-
-Sends HTTP HEAD requests to each URL in the matched external entry's `sources[]`. Uses conditional headers (`If-None-Match`, `If-Modified-Since`) from stored `header_metadata`. Updates `header_metadata` in-place after checking.
-
-- HTTP 304 → `fresh`
-- HTTP 200 → `stale` (resource changed)
-- Network / 4xx / 5xx → `error` (does not update metadata for that URL)
-
-With `--url`: checks only that specific URL (must exist in `sources[]`).
-
-```jsonc
-// cache-ctrl check-freshness opencode-skills --pretty
-{
-  "ok": true,
-  "value": {
-    "subject": "opencode-skills",
-    "sources": [
-      { "url": "https://example.com/docs", "status": "fresh", "http_status": 304 }
-    ],
-    "overall": "fresh"
-  }
-}
-```
-
----
-
 ### `check-files`
 
 ```
@@ -346,11 +407,15 @@ If `tracked_files` is absent or empty → returns `{ status: "unchanged", ... }`
     "status": "unchanged",
     "changed_files": [],
     "unchanged_files": ["lua/plugins/ui/bufferline.lua"],
-    "missing_files": []
+    "missing_files": [],
+    "new_files": [],
+    "deleted_git_files": []
   }
 }
 ```
 
+`new_files` lists non-ignored files absent from cache (includes git-tracked and untracked non-ignored files). `deleted_git_files` lists git-tracked files removed from the working tree.
+
 ---
 
 ### `search`
@@ -378,11 +443,11 @@ cache-ctrl search neovim --pretty
 
 ---
 
-### `write`
+### `write-local` / `write-external`
 
 ```
-cache-ctrl write external <subject> --data '<json>' [--pretty]
-cache-ctrl write local --data '<json>' [--pretty]
+cache-ctrl write-external <subject> --data '<json>' [--pretty]
+cache-ctrl write-local --data '<json>' [--pretty]
 ```
 
 Writes a validated cache entry to disk. The `--data` argument must be a valid JSON string matching the ExternalCacheFile or LocalCacheFile schema. Schema validation runs first — all required fields must be present in `--data` or the write is rejected with `VALIDATION_ERROR`.
@@ -395,18 +460,148 @@ Writes a validated cache entry to disk. The `--data` argument must be a valid JS
 
 > The `subject` parameter (external agent) must match `/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/` and be at most 128 characters. Returns `INVALID_ARGS` if it fails validation.
 
-**Always use this command (or `cache_ctrl_write`) instead of writing cache files directly.** Direct writes skip schema validation and risk corrupting the cache.
+**Always use these commands (or `cache_ctrl_write_local` / `cache_ctrl_write_external`) instead of writing cache files directly.** Direct writes skip schema validation and risk corrupting the cache.
 
 ```json
-// cache-ctrl write external mysubject --data '{"subject":"mysubject","description":"...","fetched_at":"2026-04-05T10:00:00Z","sources":[],"header_metadata":{}}' --pretty
+// cache-ctrl write-external mysubject --data '{"subject":"mysubject","description":"...","fetched_at":"2026-04-05T10:00:00Z","sources":[]}' --pretty
 { "ok": true, "value": { "file": "/path/to/.ai/external-context-gatherer_cache/mysubject.json" } }
 ```
 
 ---
 
+### `graph`
+
+```
+cache-ctrl graph [--max-tokens <number>] [--seed <path>[,<path>...]] [--pretty]
+```
+
+Returns a PageRank-ranked dependency graph within a token budget. Reads from `graph.json` computed by the `watch` daemon. Files are ranked by their centrality in the import graph; use `--seed` to personalize the ranking toward specific files (e.g. recently changed files).
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--max-tokens <number>` | Token budget for `ranked_files` output (default: 1024, clamped 64–128000) |
+| `--seed <path>[,<path>...]` | Personalize PageRank toward these file paths (repeat `--seed` for multiple values) |
+
+Returns `FILE_NOT_FOUND` if `graph.json` does not exist — run `cache-ctrl watch` to generate it.
+
+```jsonc
+// cache-ctrl graph --max-tokens 512 --pretty
+{
+  "ok": true,
+  "value": {
+    "ranked_files": [
+      {
+        "path": "src/cache/cacheManager.ts",
+        "rank": 0.142,
+        "deps": ["src/utils/validate.ts"],
+        "defs": ["readCache", "writeCache", "findRepoRoot"],
+        "ref_count": 12
+      }
+    ],
+    "total_files": 36,
+    "computed_at": "2026-04-11T10:00:00Z",
+    "token_estimate": 487
+  }
+}
+```
+
+---
+
+### `map`
+
+```
+cache-ctrl map [--depth overview|modules|full] [--folder <path-prefix>] [--pretty]
+```
+
+Returns a semantic map of the local `context.json` using the structured `FileFacts` metadata. Files are sorted by `importance` (ascending) then path. Use `--folder` to scope the output to a subtree.
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--depth overview\|modules\|full` | Output depth (default: `overview`) |
+| `--folder <path-prefix>` | Restrict output to files whose path equals or starts with this prefix |
+
+**Depth values:**
+- `overview` — includes `summary`, `role`, `importance` per file (no individual facts)
+- `modules` — same as `overview` plus the `modules` grouping from `context.json`
+- `full` — includes all per-file `facts[]` strings
+
+Returns `FILE_NOT_FOUND` if `context.json` does not exist.
+
+```jsonc
+// cache-ctrl map --depth overview --folder src/commands --pretty
+{
+  "ok": true,
+  "value": {
+    "depth": "overview",
+    "global_facts": ["TypeScript CLI, Bun runtime"],
+    "files": [
+      {
+        "path": "src/commands/graph.ts",
+        "summary": "Reads graph.json and returns PageRank-ranked file list",
+        "role": "implementation",
+        "importance": 2
+      }
+    ],
+    "total_files": 1,
+    "folder_filter": "src/commands"
+  }
+}
+```
+
+---
+
+### `watch`
+
+```
+cache-ctrl watch [--verbose]
+```
+
+Long-running daemon that watches the repo for source file changes (`.ts`, `.tsx`, `.js`, `.jsx`) and incrementally rebuilds `graph.json`. On startup it performs an initial full graph build. Subsequent file changes trigger a debounced rebuild (200 ms). Rebuilds are serialized — concurrent changes are queued.
+
+Writes to `.ai/local-context-gatherer_cache/graph.json`. The graph is then available to `cache-ctrl graph` and `cache_ctrl_graph`.
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--verbose` | Log watcher lifecycle events and rebuild completion to stdout |
+
+The process runs until `SIGINT` or `SIGTERM`, which trigger a clean shutdown. Exit code `1` on startup failure (e.g., `Bun.watch` unavailable or graph write error).
+
+```sh
+# Start the daemon in the background
+cache-ctrl watch &
+
+# Or run it in a dedicated terminal with verbose output
+cache-ctrl watch --verbose
+```
+
+---
+
+### `version`
+
+```
+cache-ctrl version
+```
+
+Prints the current package version as JSON and exits.
+
+No flags or arguments.
+
+```jsonc
+// cache-ctrl version
+{ "ok": true, "value": { "version": "1.1.1" } }
+```
+
+---
+
 ## opencode Plugin Tools
 
-The plugin (`cache_ctrl.ts`) is auto-discovered via `~/.config/opencode/tools/cache_ctrl.ts` and registers 7 tools that call the same command functions as the CLI:
+The plugin (`cache_ctrl.ts`) is auto-discovered via `~/.config/opencode/tools/cache_ctrl.ts` and registers 9 tools that call the same command functions as the CLI:
 
 | Tool | Description |
 |---|---|
@@ -414,13 +609,15 @@ The plugin (`cache_ctrl.ts`) is auto-discovered via `~/.config/opencode/tools/ca
 | `cache_ctrl_list` | List entries with age and staleness flags |
 | `cache_ctrl_inspect` | Return full content of a specific entry |
 | `cache_ctrl_invalidate` | Zero out a cache entry's timestamp |
-| `cache_ctrl_check_freshness` | HTTP HEAD check for external source URLs |
 | `cache_ctrl_check_files` | Compare tracked files against stored mtime/hash |
-| `cache_ctrl_write` | Write a validated cache entry; validates against ExternalCacheFile or LocalCacheFile schema |
+| `cache_ctrl_write_local` | Write a validated local cache entry |
+| `cache_ctrl_write_external` | Write a validated external cache entry |
+| `cache_ctrl_graph` | Return a PageRank-ranked dependency graph within a token budget (reads `graph.json`) |
+| `cache_ctrl_map` | Return a semantic map of `context.json` with per-file FileFacts metadata |
 
 No bash permission is required for agents that use the plugin tools directly.
 
-All 7 plugin tool responses include a `server_time` field at the outer JSON level:
+All 9 plugin tool responses include a `server_time` field at the outer JSON level:
 
 ```json
 { "ok": true, "value": { ... }, "server_time": "2026-04-05T12:34:56.789Z" }
@@ -439,10 +636,6 @@ Use `server_time` to assess how stale stored timestamps are without requiring ba
 cache-ctrl list --agent external --pretty
 # If is_stale: false → skip fetch
 
-# For a precise HTTP freshness check on a borderline entry
-cache-ctrl check-freshness <subject>
-# If overall: "fresh" → skip re-fetch
-
 # After writing new cache content — mark entry fresh
 cache-ctrl touch external <subject>
 
@@ -476,14 +669,6 @@ cache-ctrl invalidate local
   "sources": [
     { "type": "github_api", "url": "https://..." }
   ],
-  "header_metadata": {
-    "https://...": {
-      "etag": "\"abc123\"",
-      "last_modified": "Fri, 04 Apr 2026 10:00:00 GMT",
-      "checked_at": "2026-04-04T12:00:00Z",
-      "status": "fresh"
-    }
-  }
   // Any additional agent fields are preserved unchanged
 }
 ```
@@ -495,25 +680,53 @@ cache-ctrl invalidate local
 ```jsonc
 {
   "timestamp": "2026-04-04T12:00:00Z",   // auto-set on write; "" when invalidated
-  "topic": "neovim plugin configuration",
-  "description": "Scan of nvim lua plugins",
+  "topic": "cache-ctrl source",
+  "description": "Scan of cache-ctrl TypeScript source",
   "cache_miss_reason": "files changed",  // optional: why the previous cache was discarded
   "tracked_files": [
-    { "path": "lua/plugins/ui/bufferline.lua", "mtime": 1743768000000, "hash": "sha256hex..." }
+    { "path": "src/commands/graph.ts", "mtime": 1743768000000, "hash": "sha256hex..." }
     // mtime is auto-populated by the write command; agents only need to supply path (and optionally hash)
   ],
   "global_facts": [                       // optional: repo-level facts; last-write-wins; max 20 entries, each ≤ 300 chars
-    "Kubuntu dotfiles repo",
-    "StyLua for Lua (140 col, 2-space indent)"
+    "TypeScript CLI tool executed by Bun",
+    "All errors use Result<T,E> — no thrown exceptions across command boundaries"
   ],
-  "facts": {                              // optional: per-file facts; per-path merge; max 30 entries per file, each ≤ 800 chars
-    "lua/plugins/ui/bufferline.lua": ["lazy-loaded via ft = lua", "uses catppuccin mocha theme"]
-    // Facts for files deleted from disk are evicted automatically on the next write
+  "facts": {                              // optional: per-file structured FileFacts; per-path merge
+    "src/commands/graph.ts": {
+      "summary": "Reads graph.json and returns PageRank-ranked file list within a token budget",
+      "role": "implementation",           // one of: entry-point | interface | implementation | test | config
+      "importance": 2,                    // 1 = critical, 2 = important, 3 = peripheral
+      "facts": [                          // max 10 entries, each ≤ 300 chars
+        "Uses computePageRank with optional seed files for personalized ranking",
+        "Token budget clamped to 64–128000; defaults to 1024"
+      ]
+    }
+    // FileFacts entries for files deleted from disk are evicted automatically on the next write
+  },
+  "modules": {                            // optional: logical groupings of file paths
+    "commands": ["src/commands/graph.ts", "src/commands/map.ts"]
   }
   // Any additional agent fields are preserved unchanged
 }
 ```
 
+### Graph: `.ai/local-context-gatherer_cache/graph.json`
+
+Written and maintained by the `watch` daemon. Read by `cache-ctrl graph` and `cache_ctrl_graph`. Agents do not write this file directly.
+
+```jsonc
+{
+  "computed_at": "2026-04-11T10:00:00Z",
+  "files": {
+    "src/cache/cacheManager.ts": {
+      "rank": 0.0,          // stored as 0.0; PageRank is recomputed on every graph command call
+      "deps": ["src/utils/validate.ts", "src/types/result.ts"],
+      "defs": ["readCache", "writeCache", "findRepoRoot"]
+    }
+  }
+}
+```
+
 ---
 
 ## Error Codes
@@ -531,9 +744,7 @@ cache-ctrl invalidate local
 | `VALIDATION_ERROR` | Schema validation failed (e.g., missing required field or type mismatch in `write`) |
 | `NO_MATCH` | No cache file matched the keyword |
 | `AMBIGUOUS_MATCH` | Multiple files with identical top score |
-| `HTTP_REQUEST_FAILED` | Network error during HEAD request |
-| `URL_NOT_FOUND` | `--url` value not found in `sources[]` |
-| `UNKNOWN` | Unexpected internal error |
+| `UNKNOWN` | Unexpected internal/runtime error (including unexpected HTTP client failures) |
 
 ---
 

package/cache_ctrl.ts

@@ -2,11 +2,14 @@ import { tool } from "@opencode-ai/plugin";
 import { listCommand } from "./src/commands/list.js";
 import { inspectCommand } from "./src/commands/inspect.js";
 import { invalidateCommand } from "./src/commands/invalidate.js";
-import { checkFreshnessCommand } from "./src/commands/checkFreshness.js";
 import { checkFilesCommand } from "./src/commands/checkFiles.js";
 import { searchCommand } from "./src/commands/search.js";
-import { writeCommand } from "./src/commands/write.js";
-import { ErrorCode } from "./src/types/result.js";
+import { writeLocalCommand } from "./src/commands/writeLocal.js";
+import { writeExternalCommand } from "./src/commands/writeExternal.js";
+import { graphCommand } from "./src/commands/graph.js";
+import { mapCommand } from "./src/commands/map.js";
+import { toUnknownResult } from "./src/utils/errors.js";
+import { rejectTraversalKeys } from "./src/utils/traversal.js";
 
 const z = tool.schema;
 
@@ -18,8 +21,7 @@ function withServerTime(result: unknown): string {
 }
 
 function handleUnknownError(err: unknown): string {
-  const message = err instanceof Error ? err.message : String(err);
-  return withServerTime({ ok: false, error: message, code: ErrorCode.UNKNOWN });
+  return withServerTime(toUnknownResult(err));
 }
 
 export const search = tool({
@@ -97,17 +99,87 @@ export const invalidate = tool({
   },
 });
 
-export const check_freshness = tool({
-  description: "For external cache: send HTTP HEAD requests to all source URLs and return freshness status per URL.",
+export const check_files = tool({
+  description:
+    "For local cache: compare tracked files against stored mtime/hash values and return which files changed. Also reports new_files (files not excluded by .gitignore that are absent from cache — includes both git-tracked and untracked-non-ignored files) and deleted_git_files (git-tracked files deleted from working tree).",
+  args: {},
+  async execute(_args) {
+    try {
+      const result = await checkFilesCommand();
+      return withServerTime(result);
+    } catch (err) {
+      return handleUnknownError(err);
+    }
+  },
+});
+
+export const write_local = tool({
+  description:
+    "Write a validated local cache entry. timestamp is auto-set to current UTC time — do not include it in content. tracked_files entries need only { path }; mtime/hash are computed by the command. Uses per-path merge and evicts entries for files deleted from disk.",
   args: {
-    subject: z.string().min(1),
-    url: z.string().url().optional(),
+    topic: z.string(),
+    description: z.string(),
+    tracked_files: z.array(z.object({ path: z.string() })),
+    global_facts: z.array(z.string().max(300)).max(20).optional(),
+    facts: z
+      .record(
+        z.string(),
+        z.object({
+          summary: z.string().optional(),
+          role: z.string().optional(),
+          importance: z.union([z.literal(1), z.literal(2), z.literal(3)]).optional(),
+          facts: z.array(z.string()).optional(),
+        }),
+      )
+      .superRefine(rejectTraversalKeys)
+      .optional(),
+    cache_miss_reason: z.string().optional(),
+  },
+  async execute(args) {
+    try {
+      const result = await writeLocalCommand({
+        agent: "local",
+        content: {
+          topic: args.topic,
+          description: args.description,
+          tracked_files: args.tracked_files,
+          ...(args.global_facts !== undefined ? { global_facts: args.global_facts } : {}),
+          ...(args.facts !== undefined ? { facts: args.facts } : {}),
+          ...(args.cache_miss_reason !== undefined ? { cache_miss_reason: args.cache_miss_reason } : {}),
+        },
+      });
+      return withServerTime(result);
+    } catch (err) {
+      return handleUnknownError(err);
+    }
+  },
+});
+
+export const write_external = tool({
+  description:
+    "Write a validated external cache entry to disk. Uses atomic write-with-merge so unknown fields are preserved.",
+  args: {
+    subject: z.string(),
+    description: z.string(),
+    fetched_at: z.string().datetime(),
+    sources: z.array(
+      z.object({
+        type: z.string(),
+        url: z.string(),
+        version: z.string().optional(),
+      }),
+    ),
   },
   async execute(args) {
     try {
-      const result = await checkFreshnessCommand({
+      const result = await writeExternalCommand({
+        agent: "external",
         subject: args.subject,
-        ...(args.url !== undefined ? { url: args.url } : {}),
+        content: {
+          description: args.description,
+          fetched_at: args.fetched_at,
+          sources: args.sources,
+        },
       });
       return withServerTime(result);
     } catch (err) {
@@ -116,13 +188,22 @@ export const check_freshness = tool({
   },
 });
 
-export const check_files = tool({
+export const graph = tool({
   description:
-    "For local cache: compare tracked files against stored mtime/hash values and return which files changed. Also reports new_files (files not excluded by .gitignore that are absent from cache — includes both git-tracked and untracked-non-ignored files) and deleted_git_files (git-tracked files deleted from working tree).",
-  args: {},
-  async execute(_args) {
+    "Return a PageRank-ranked file dependency graph within a token budget. Use this to understand which files are most central to recent changes. Reads from the pre-computed graph.json updated by 'cache-ctrl watch'.",
+  args: {
+    maxTokens: z.number().optional().describe("Token budget for the response (default: 1024)"),
+    seed: z
+      .array(z.string())
+      .optional()
+      .describe("File paths to personalize PageRank toward (e.g. recently changed files)"),
+  },
+  async execute(args) {
     try {
-      const result = await checkFilesCommand();
+      const result = await graphCommand({
+        ...(args.maxTokens !== undefined ? { maxTokens: args.maxTokens } : {}),
+        ...(args.seed !== undefined ? { seed: args.seed } : {}),
+      });
       return withServerTime(result);
     } catch (err) {
       return handleUnknownError(err);
@@ -130,20 +211,21 @@ export const check_files = tool({
   },
 });
 
-export const write = tool({
+export const map = tool({
   description:
-    "Write a validated cache entry to disk. Validates the content object against the ExternalCacheFile or LocalCacheFile schema before writing. Returns VALIDATION_ERROR if required fields are missing or have wrong types. For 'external': subject arg is required and must match content.subject (or will be injected if absent). For 'local': omit subject; timestamp is auto-set to current UTC time — do not include it in content. In tracked_files, each entry needs only { path } — mtime and hash are auto-computed by the tool; any caller-provided mtime or hash values are stripped. For local: uses per-path merge — tracked_files entries are merged by path (submitted paths replace existing entries for those paths; other paths are preserved). Entries for files no longer present on disk are evicted automatically. On cold start (no existing cache), submit all relevant files. On subsequent writes, submit only new and changed files. For 'external': uses atomic write-with-merge — existing unknown fields in the file are preserved. Call cache_ctrl_schema or read the skill to see required fields before calling this.",
+    "Return a semantic mental map of the codebase from the local context cache. Use 'overview' (default) for a ~300-token summary of what each file does. Use 'modules' to see logical groupings. Use 'full' to include all per-file facts.",
   args: {
-    agent: AgentRequiredSchema,
-    subject: z.string().min(1).optional(),
-    content: z.record(z.string(), z.unknown()),
+    depth: z
+      .enum(["overview", "modules", "full"])
+      .optional()
+      .describe("Map depth (default: 'overview')"),
+    folder: z.string().optional().describe("Restrict map to files under this path prefix"),
   },
   async execute(args) {
     try {
-      const result = await writeCommand({
-        agent: args.agent,
-        ...(args.subject !== undefined ? { subject: args.subject } : {}),
-        content: args.content,
+      const result = await mapCommand({
+        ...(args.depth !== undefined ? { depth: args.depth } : {}),
+        ...(args.folder !== undefined ? { folder: args.folder } : {}),
       });
       return withServerTime(result);
     } catch (err) {