[codex] Make the CodeGraphy CLI self-explanatory for agents

[joesobo]

Why

The CLI and extension share one model: configure graph contributors, index the complete workspace graph into SQLite, shape results through Filters and Graph Scope, then query the cache. The agent-facing CLI needs the same model with a compact database and a self-sufficient command contract.

What changed

• Replaces the old cache layout with five small relational tables:
  • File(id, path, mtime, size, contentHash)
  • Node(id, key, type, label, fileId, parentId, pluginId, language)
  • NodeView(nodeKey, color, x, y, favorite, shape, imageUrl, isCollapsed)
  • Symbol(nodeId, name, kind, pluginId, language)
  • Edge(id, key, sourceNodeId, targetNodeId, type)
• Uses generated integer row IDs and real foreign keys. Stable graph keys remain separate from database identity.
• Removes generic JSON columns plus duplicate paths, analysis IDs, source/provenance fields, renderer physics, Unity metadata, ranges, signatures, relation variants, and edge owner fields.
• Keeps symbol-only data in Symbol; non-symbol nodes do not carry symbol fields.
• Uses mtime to skip unchanged file reads and hashes. Uses contentHash when timestamps are ambiguous.
• Indexes complete Nodes, Symbols, and Edges once. Filters and Graph Scope only change the returned or displayed projection.
• Makes the extension persist the complete unscoped graph while still returning the scoped graph to the UI.
• Adds transient --filter, --node-type, and --edge-type options to every query command. Values may be repeated or comma-separated and never modify settings.json.
• Makes Node Type projections follow Graph Scope hierarchy and symbol meaning. Parent, descendant, and overlapping types match semantically while returned Nodes keep their specific stored nodeType.
• Makes root and command help self-sufficient. Successful data commands return { ok: true, command, data }; failures return the exclusive { ok: false, command, error } shape.
• Extends read-only doctor output with separate schema compatibility, SQLite integrity, foreign-key health, cache state, and File, Node, Symbol, and Edge counts. Unhealthy checks are returned in error.details.
• Splits the large cache, indexing, scope, and workspace command test files into focused files under 300 lines.
• Reduces the CodeGraphy Agent Skill to a short Plugin -> index -> filter/scope -> query guide and syncs the global skill.

Deliberate deferrals

• No CLI watcher, stale notification daemon, or background reindexing.
• No --dry-run or resolve command without a concrete shared contract.
• No embedded query language, prompts, pagers, or formatting DSL.

Validation

• Two independent code reviews found no remaining P1 or P2 issues after corrections.
• git diff --check, stale-import search, test-file size check, and protected-worktree checks passed.
• Local heavy test, mutation, CRAP, and Playwright runs were intentionally stopped for this review-fix commit. PR CI is the test authority.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4f2a081

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@codegraphy-dev/core	Minor
@codegraphy-dev/extension	Patch
@codegraphy-dev/plugin-markdown	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR