git:20260825.c9bee9b to git:20260829.c96b3b0

# AGENT DIRECTIVES

## General

- Never use `any` or `as unknown as`

- Never use nested ternary expressions. Use `if`/`else`, a helper function, or named intermediate values instead.

- Never use `=== true`, `=== false`, etc. in boolean conditions; keep them as terse and simple as possible like `!condition`. Extract conditions to variables when the variable name adds clarity/insight into the reason for the condition.

- In boolean condition contexts, use the shortest syntactically equivalent expression. Prefer `items.length` over `items.length > 0`, `!items.length` over `items.length === 0`, and `items?.length` over `items && items.length > 0`.

- Always consider the impact of a change on tests or when more test cases are needed. Never make tests pass for the sake of passing; always exercise real behavior.

- Always keep documentation updated and accurate while being minimal and concise.

- Keep paragraphs to no more than 4 concise sentences. Prefer bullets for dense details.

- Keep `README.md` as the landing page and docs index. Do not turn it back into the only canonical reference for every example and workflow.

- When public-facing install, runtime, CLI, library API, MCP, agent workflow, or release guidance changes, update the relevant canonical docs in the same change: `README.md`, `docs/installation.md`, `docs/cli.md`, `docs/library-api.md`, `docs/mcp.md`, `docs/agent-workflows.md`, `docs/how-it-works.md`, and `PUBLISHING.md` as applicable.

- For repo-understanding flows, start with `node ./dist/cli.js doctor` and `node ./dist/cli.js orient --root . --budget small --json` when `dist` is built; build first if validating the working tree from a fresh checkout.

- For source-checkout validation and contributor examples, prefer `node ./dist/cli.js ...`; reserve bare `codegraph ...` for published/global install guidance.

- When package metadata, install scripts, optional native dependencies, or the resolved npm graph changes, update `package-lock.json` in the same change and verify with `npm ci --ignore-scripts --dry-run` unless lifecycle scripts are part of the behavior under test.

- Treat `--root` as the project boundary for config lookup, path confinement, and output normalization. Cache/manifests may use the resolved cache anchor (`--cache-dir`/`CODEGRAPH_CACHE_DIR`, repository metadata, or project root); cached contents remain project-relative.

- Keep discovery glob guidance accurate: `codegraph.config.json` globs are project-root-relative, while CLI `--include-glob`/`--ignore-glob` values are one-off filters relative to each active scan root.

- Within any claimed cross-language capability, behavior should stay consistent across all supported languages for that capability. Avoid language-subset branches; if a limitation is intentional, document it in the parity docs and cover it with explicit tests in the same change.

- When language support changes, update `docs/language-parity.md` and `docs/scenario-catalog.md` in the same change so support claims, limitations, and fixture coverage stay aligned.

- When adding or changing a cross-file language scenario, add or update the nearest language test in `tests/languages/*.test.ts` and the shared semantic coverage in `tests/goto.test.ts`, `tests/references.test.ts`, and `tests/native-semantic-parity.test.ts` when the language uses the native runtime.

- Always keep the README.md table of contents updated whenever README sections are added, removed, or renamed.

- Human-readable CLI output is a public contract. User-facing `writeCliOutput(...)` callsites must provide a command-specific formatter unless the output is intentionally scalar or JSON-first, and the same change should add or update a pretty-output test.

- When CLI commands, flags, or output contracts change, update both `docs/cli.md` and `codegraph-skill/codegraph/SKILL.md` in the same change.

- Always keep `codegraph-skill/codegraph/SKILL.md` updated when CLI commands, flags, or capabilities change. This file is the skill definition used by agents and must reflect the current tool surface.

- Distinguish library/session-only features from CLI/config features explicitly. If a capability exists only in exported library APIs, docs and types must say so, and CLI/config surfaces must not imply support they do not implement.

- When changing MCP notification, transport, or progress behavior, verify both the protocol seam and the serving seam users actually hit (HTTP/stdio); do not assume protocol-level behavior survives a transport wrapper unchanged.

- Before major commits or concluding work, run `npm run check` to verify formatting, lint, build, and tests together. During iteration, use the narrowest meaningful test command: targeted Vitest suites for localized changes, `npm run test:fast` for broader TypeScript changes, `npm run test:integration` for CLI/report/output contracts, and `npm run test:native` when touching `packages/codegraph-native`.

- Installation guidance must use `@lzehrung/codegraph` and the `@lzehrung` GitHub Packages registry. Keep detailed install docs in `docs/installation.md`.

- Any persistent storage schema change (e.g. SQLite tables/columns/indexes) MUST include a migration path for existing on-disk data. If using `CREATE TABLE IF NOT EXISTS`, you must also `ALTER TABLE` / backfill as needed (or introduce explicit schema versioning) and add a regression test that starts from an older schema to prove upgrades work.

- DO NOT use curly quote variants or other non-standard characters humans would not type with a standard QWERTY keyboard.