feat: add codegraph tool for querying pre-computed codebase dependency graph

- Implemented `tools-codegraph.ts` to provide various queries on the codebase dependency graph, including impact analysis, dead code detection, module boundaries, and more.
- Created a schema for validating query inputs using Zod.
- Developed helper functions for resolving file paths, formatting output, and handling different query types.
- Added tests for the codegraph queries in `codegraph-queries.test.ts` to ensure functionality and correctness.
- Introduced tests for the codegraph scanning and loading functionalities in `codegraph.test.ts`, verifying the detection of source files, imports, exports, circular dependencies, and entry points.

docs/codegraph.md

@@ -0,0 +1,56 @@
+# Codebase Graph
+
+A pre-computed dependency graph built via static analysis (TypeScript compiler API).
+It gives the agent an immediate map of the codebase at session start — no exploration turns needed.
+
+## How it works
+
+When a session starts, shiro-neko scans all `.ts`/`.tsx` files using the TypeScript
+compiler API. It resolves imports, exports, types, classes, and functions, and
+builds a directed dependency graph. The result is cached to `.shiro/codegraph.json`.
+
+On subsequent sessions, if no source files have changed (mtime check), the cached
+graph is reused. This means the system prompt includes the architecture overview
+from the very first turn.
+
+## What it contains
+
+- **Entry points**: files the graph identifies as starting points (few imports, `main()` export, CLI-like)
+- **Module map**: directory → file count → key file names
+- **Key types**: the most frequently defined exported types/interfaces
+- **Circular dependencies**: any cycles detected in the import graph
+- **Total LOC**: total lines across all source files
+
+## System prompt integration
+
+The graph summary appears in the system prompt as a "Codebase Architecture" section,
+right after the Environment block and before Tools. This means the agent knows the
+project structure before making a single tool call.
+
+## Querying the graph
+
+Use the `codegraph` tool for detailed queries:
+
+- `codegraph query: 'summary'` — the same overview in the system prompt
+- `codegraph query: 'list'` — all files with kind and LOC
+- `codegraph query: 'file', path: 'src/session.ts'` — detailed info for one file
+- `codegraph query: 'deps', path: 'session'` — what it imports and what imports it
+- `codegraph query: 'types'` — all exported types across the codebase
+- `codegraph query: 'circular'` — circular dependency chains
+- `codegraph query: 'entry'` — detected entry points
+
+## Commands
+
+`/graph` — force-regenerate the graph and show the summary.
+
+## Architecture decisions
+
+- **TypeScript compiler API** over regex parsing: handles re-exports, type-only imports,
+  and module resolution correctly. Falls back to manual file walk if no tsconfig.json exists.
+- **Mtime-based freshness**: recompute only when a source file has been modified since the
+  graph was generated. The check walks all source files (same as the scan) — for huge
+  codebases, add a `--no-graph` flag to skip.
+- **Lazy computation**: the graph is computed once per session, not per step. The `Session`
+  caches it in a field and the prompt is built from it.
+- **Graceful fallback**: non-TypeScript projects, unreadable directories, or scan failures
+  silently omit the section from the prompt rather than breaking the session.