@thecat69/cache-ctrl 1.0.0 → 1.1.1

package/README.md

@@ -46,26 +46,33 @@ src/index.ts              cache_ctrl.ts
      └──────────┬──────────────┘
                │
         Command Layer
-   src/commands/{list, inspect, flush,
-    invalidate, touch, prune,
-    checkFreshness, checkFiles, search,
-    write}.ts
-                │
-          Core Services
+   src/commands/{list, inspect, inspectExternal,
+     inspectLocal, flush, invalidate,
+     touch, prune, checkFreshness,
+     checkFiles, search, writeLocal,
+     writeExternal, install, 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
    freshnessChecker ← HTTP HEAD requests
    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 +80,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`.
 
 ---
 
@@ -277,7 +285,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).
 
@@ -306,6 +314,8 @@ Sends HTTP HEAD requests to each URL in the matched external entry's `sources[]`
 
 With `--url`: checks only that specific URL (must exist in `sources[]`).
 
+Security: before any request, the URL is validated. Non-HTTP(S) schemes and local-network targets (RFC1918/private, loopback, link-local, and IPv4-mapped IPv6 addresses) are blocked and reported with `blocked` status.
+
 ```jsonc
 // cache-ctrl check-freshness opencode-skills --pretty
 {
@@ -346,11 +356,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 +392,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 +409,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":[],"header_metadata":{}}' --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 10 tools that call the same command functions as the CLI:
 
 | Tool | Description |
 |---|---|
@@ -416,11 +560,14 @@ The plugin (`cache_ctrl.ts`) is auto-discovered via `~/.config/opencode/tools/ca
 | `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 10 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" }
@@ -495,25 +642,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 +706,8 @@ 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

@@ -5,8 +5,12 @@ 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 +22,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({
@@ -130,20 +133,129 @@ export const check_files = tool({
   },
 });
 
-export const write = tool({
+export const write_local = 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.",
+    "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: {
-    agent: AgentRequiredSchema,
-    subject: z.string().min(1).optional(),
-    content: z.record(z.string(), z.unknown()),
+    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 writeCommand({
-        agent: args.agent,
-        ...(args.subject !== undefined ? { subject: args.subject } : {}),
-        content: args.content,
+      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(),
+      }),
+    ),
+    header_metadata: z.record(
+      z.string(),
+      z.object({
+        etag: z.string().optional(),
+        last_modified: z.string().optional(),
+        checked_at: z.string(),
+        status: z.enum(["fresh", "stale", "unchecked"]),
+      }),
+    ),
+  },
+  async execute(args) {
+    try {
+      const result = await writeExternalCommand({
+        agent: "external",
+        subject: args.subject,
+        content: {
+          description: args.description,
+          fetched_at: args.fetched_at,
+          sources: args.sources,
+          header_metadata: args.header_metadata,
+        },
+      });
+      return withServerTime(result);
+    } catch (err) {
+      return handleUnknownError(err);
+    }
+  },
+});
+
+export const graph = tool({
+  description:
+    "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 graphCommand({
+        ...(args.maxTokens !== undefined ? { maxTokens: args.maxTokens } : {}),
+        ...(args.seed !== undefined ? { seed: args.seed } : {}),
+      });
+      return withServerTime(result);
+    } catch (err) {
+      return handleUnknownError(err);
+    }
+  },
+});
+
+export const map = tool({
+  description:
+    "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: {
+    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 mapCommand({
+        ...(args.depth !== undefined ? { depth: args.depth } : {}),
+        ...(args.folder !== undefined ? { folder: args.folder } : {}),
       });
       return withServerTime(result);
     } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thecat69/cache-ctrl",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "type": "module",
   "bin": {
     "cache-ctrl": "src/index.ts"
@@ -26,6 +26,7 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "latest",
+    "@typescript-eslint/typescript-estree": "8.58.1",
     "zod": "4.3.6"
   },
   "devDependencies": {

package/skills/cache-ctrl-caller/SKILL.md

@@ -10,8 +10,6 @@ For any agent that calls **local-context-gatherer** and **external-context-gathe
 The cache avoids expensive subagent calls when their data is already fresh.
 Use `cache_ctrl_*` tools directly for all status checks — **never spawn a subagent just to check cache state**.
 
----
-
 ## Availability Detection (run once at startup)
 
 1. Call `cache_ctrl_list` (built-in tool).
@@ -19,9 +17,7 @@ Use `cache_ctrl_*` tools directly for all status checks — **never spawn a suba
    - Failure (tool not found / permission denied) → try step 2.
 2. Run `bash: "which cache-ctrl"`.
    - Exit 0 → **use Tier 2** for all operations.
-   - Not found → **use Tier 3** for all operations.
-
----
+   - Not found → **neither Tier is available**. Stop and request environment access to `cache_ctrl_*` tools or the `cache-ctrl` CLI before proceeding.
 
 ## Before Calling local-context-gatherer
 
@@ -59,10 +55,6 @@ After `local-context-gatherer` returns, verify it actually wrote to cache:
 4. Re-invoke the gatherer **once** with the explicit instruction appended: *"IMPORTANT: You MUST call `cache_ctrl_write` before returning. Your previous invocation did not update the cache (timestamp was not advanced)."*
 5. Do not retry more than once.
 
-> **Why `timestamp`, not `check-files`?** A `check-files` result of `"changed"` after a successful write is expected — it does not indicate a missing write. Only the `timestamp` advancing is a reliable signal that the write occurred.
-
----
-
 ## Before Calling external-context-gatherer
 
 Check whether external docs for a given subject are already cached and fresh.
@@ -71,7 +63,6 @@ Check whether external docs for a given subject are already cached and fresh.
 
 **Tier 1:** Call `cache_ctrl_list` with `agent: "external"`.
 **Tier 2:** `cache-ctrl list --agent external`
-**Tier 3:** `glob` `.ai/external-context-gatherer_cache/*.json` → for each file, `read` and check `fetched_at` (stale if empty or older than 24 hours).
 
 ### Step 2 — Search for a matching subject
 
@@ -79,7 +70,6 @@ If entries exist, check whether one already covers the topic:
 
 **Tier 1:** Call `cache_ctrl_search` with relevant keywords.
 **Tier 2:** `cache-ctrl search <keyword> [<keyword>...]`
-**Tier 3:** Scan `subject` and `description` fields in the listed files.
 
 ### Step 3 — Decide
 
@@ -97,7 +87,38 @@ To **force a re-fetch** for a specific subject:
 **Tier 1:** Call `cache_ctrl_invalidate` with `agent: "external"` and the subject keyword.
 **Tier 2:** `cache-ctrl invalidate external <subject>`
 
----
+## Exploring Local Context: map and graph
+
+### `cache_ctrl_map`
+
+- **Purpose:** Build a semantic mental map of the codebase (what each file does, plus role/importance metadata).
+- **Params:**
+  - `depth` (optional):
+    - `overview` (default): ~300-token orientation (summaries + roles)
+    - `modules`: adds module/grouping information
+    - `full`: includes per-file `facts[]` arrays
+  - `folder` (optional): restrict output to a path prefix
+- **When to use:** first call when entering a new task, before deeper inspection.
+
+### `cache_ctrl_graph`
+
+- **Purpose:** Return a structural dependency graph with PageRank-ranked files by centrality.
+- **Params:**
+  - `maxTokens` (optional, default `1024`)
+  - `seed` (optional `string[]`): personalize ranking toward specific files (for example changed files)
+- **Requirements:** `cache-ctrl watch` must be running (or must have run recently) to populate `graph.json`.
+- **When to use:** after `cache_ctrl_map`, to identify the most connected/high-leverage files.
+
+## Progressive Disclosure protocol (4-step)
+
+Use this 4-step sequence to control token usage while preserving accuracy:
+
+1. `cache_ctrl_map(depth: "overview")` — orient quickly (~300 tokens)
+2. `cache_ctrl_graph(maxTokens: 1024, seed: [changedFiles])` — structural dependency view
+3. `cache_ctrl_inspect(filter: [...])` — deep facts for specific files
+4. Read only the relevant source files (typically 2–5 files)
+
+> See **Reading a Full Cache Entry** below for the three filter targeting options and when to use each.
 
 ## Reading a Full Cache Entry
 
@@ -105,7 +126,6 @@ Use when you want to pass a cached summary to a subagent or include it inline in
 
 **Tier 1:** Call `cache_ctrl_inspect` with `agent` and `subject`.
 **Tier 2:** `cache-ctrl inspect external <subject>` or `cache-ctrl inspect local context --filter <kw>[,<kw>...]`
-**Tier 3:** `read` the file directly from `.ai/<agent>_cache/<subject>.json`.
 
 > **For `agent: "local"`: always use at least one filter on large codebases.** Three targeting options are available — use the most specific one that fits your task:
 >
@@ -114,25 +134,21 @@ Use when you want to pass a cached summary to a subagent or include it inline in
 > | `filter` | File path contains keyword | When you know which files by name/path segment |
 > | `folder` | File path starts with folder prefix (recursive) | When you need all files in a directory subtree |
 > | `search_facts` | Any fact string contains keyword | When you need files related to a concept, pattern, or API |
->
-> Unfiltered local inspect returns the **entire facts map**. This is only appropriate for codebases with ≤ ~20 tracked files. On larger codebases, always use at least one of the above.
-
----
 
 ## Quick Reference
 
-| Operation | Tier 1 | Tier 2 | Tier 3 |
-|---|---|---|---|
-| Check local freshness | `cache_ctrl_check_files` | `cache-ctrl check-files` | read context.json, check timestamp |
-| List external entries | `cache_ctrl_list` (agent: "external") | `cache-ctrl list --agent external` | glob + read each JSON |
-| Search entries | `cache_ctrl_search` | `cache-ctrl search <kw>...` | scan subject/description fields |
-| Read facts (local) | `cache_ctrl_inspect` + `filter` | `cache-ctrl inspect local context --filter <kw>` | read file, extract facts |
-| Read entry (external) | `cache_ctrl_inspect` | `cache-ctrl inspect external <subject>` | read file directly |
-| Invalidate local | `cache_ctrl_invalidate` (agent: "local") | `cache-ctrl invalidate local` | delete or overwrite file |
-| Invalidate external | `cache_ctrl_invalidate` (agent: "external", subject) | `cache-ctrl invalidate external <subject>` | set `fetched_at` to `""` via edit |
-| HTTP freshness check | `cache_ctrl_check_freshness` | `cache-ctrl check-freshness <subject>` | compare `fetched_at` with now |
-
----
+| Operation | Tier 1 | Tier 2 |
+|---|---|---|
+| Check local freshness | `cache_ctrl_check_files` | `cache-ctrl check-files` |
+| List external entries | `cache_ctrl_list` (agent: "external") | `cache-ctrl list --agent external` |
+| Search entries | `cache_ctrl_search` | `cache-ctrl search <kw>...` |
+| Read facts (local) | `cache_ctrl_inspect` + `filter` | `cache-ctrl inspect local context --filter <kw>` |
+| Read entry (external) | `cache_ctrl_inspect` | `cache-ctrl inspect external <subject>` |
+| Invalidate local | `cache_ctrl_invalidate` (agent: "local") | `cache-ctrl invalidate local` |
+| Invalidate external | `cache_ctrl_invalidate` (agent: "external", subject) | `cache-ctrl invalidate external <subject>` |
+| HTTP freshness check | `cache_ctrl_check_freshness` | `cache-ctrl check-freshness <subject>` |
+| Codebase map | `cache_ctrl_map` | `cache-ctrl map [--depth <overview|modules|full>] [--folder <path>]` |
+| Dependency graph | `cache_ctrl_graph` | `cache-ctrl graph [--max-tokens <n>] [--seed <file1,file2,...>]` |
 
 ## Anti-Bloat Rules
 
@@ -141,8 +157,6 @@ Use when you want to pass a cached summary to a subagent or include it inline in
 - Use `cache_ctrl_inspect` to read only the entries you actually need.
 - Cache entries are the source of truth. Prefer them over re-fetching.
 
----
-
 ## server_time in Responses
 
 Every `cache_ctrl_*` tool call returns a `server_time` field at the outer JSON level: