docs(repo): clarify sql targets the temporal store, not the node/edge graph#173
Merged
Conversation
…ge graph
`codehub sql` and the MCP `sql` tool's `sql` arg run against the DuckDB
temporal store (cochanges + symbol_summaries). The node/edge graph moved
to lbug in ADR 0016 and is reached via the typed tools or Cypher. Docs
across the repo still said "SQL against the graph store", and the
opencodehub-guide skill shipped a whole "Graph schema" + "SQL cheat-sheet"
of `SELECT FROM nodes/relations` queries that ERROR against the current
store (field-report Issue 4).
Reworded every user-facing site: CLAUDE.md, AGENTS.md,
packages/cli/README.md, the `sql` --help in cli/src/index.ts,
cli/src/agent-context.ts, docs reference/cli.md + tool-decision-matrix.mdx,
and both copies of the opencodehub-guide SKILL.md (.claude + plugins). The
SKILL cheat-sheet is rewritten to REAL lbug Cypher: single `:CodeNode`
label with `kind` as a property, snake_case props, per-type relationship
labels, plus a small temporal-SQL cochanges example. Also fixed two MCP
next-step hints (dependencies, list-findings) that told users to run a
relations SELECT — now a Cypher MATCH on the relationship label.
No production query behavior changes — guidance and strings only.
Typecheck and biome clean. A pre-existing, unrelated mcp unit test
("impact surfaces cochanges") fails on clean main from cochange-harness
drift since the #117 DuckDB-graph rip; not in any path this PR touches and
not a required check. Tracked separately.
Merged
theagenticguy
pushed a commit
that referenced
this pull request
May 29, 2026
🤖 Automated release via release-please --- <details><summary>analysis: 0.3.3</summary> ## [0.3.3](analysis-v0.3.2...analysis-v0.3.3) (2026-05-29) ### Features * **cli:** expose 9 read-only graph tools as CLI subcommands ([#174](#174)) ([be15666](be15666)) ### Dependencies * The following workspace dependencies were updated * dependencies * @opencodehub/storage bumped to 0.2.3 * @opencodehub/wiki bumped to 0.2.3 </details> <details><summary>cli: 0.5.6</summary> ## [0.5.6](cli-v0.5.5...cli-v0.5.6) (2026-05-29) ### Features * **cli:** expose 9 read-only graph tools as CLI subcommands ([#174](#174)) ([be15666](be15666)) * **cli:** status surfaces retrieval mode (summaries / vectors / embedder) ([#172](#172)) ([611e818](611e818)) ### Bug Fixes * **cli:** doctor verifies the bandit[sarif] formatter, not just the binary ([#171](#171)) ([0d78c92](0d78c92)) * **scanners:** exclude indexer-ignored dirs from vulture/radon/ty (drop .venv noise) ([#168](#168)) ([848aa34](848aa34)) ### Documentation * **repo:** clarify `sql` targets the temporal store, not the node/edge graph ([#173](#173)) ([814774a](814774a)) ### Dependencies * The following workspace dependencies were updated * dependencies * @opencodehub/analysis bumped to 0.3.3 * @opencodehub/ingestion bumped to 0.4.5 * @opencodehub/mcp bumped to 0.4.5 * @opencodehub/pack bumped to 0.2.4 * @opencodehub/scanners bumped to 0.2.3 * @opencodehub/search bumped to 0.2.3 * @opencodehub/storage bumped to 0.2.3 * @opencodehub/wiki bumped to 0.2.3 </details> <details><summary>cobol-proleap: 0.1.9</summary> ## [0.1.9](cobol-proleap-v0.1.8...cobol-proleap-v0.1.9) (2026-05-29) ### Dependencies * The following workspace dependencies were updated * dependencies * @opencodehub/ingestion bumped to 0.4.5 </details> <details><summary>ingestion: 0.4.5</summary> ## [0.4.5](ingestion-v0.4.4...ingestion-v0.4.5) (2026-05-29) ### Dependencies * The following workspace dependencies were updated * dependencies * @opencodehub/analysis bumped to 0.3.3 * @opencodehub/scip-ingest bumped to 0.2.5 * @opencodehub/storage bumped to 0.2.3 </details> <details><summary>mcp: 0.4.5</summary> ## [0.4.5](mcp-v0.4.4...mcp-v0.4.5) (2026-05-29) ### Features * **cli:** expose 9 read-only graph tools as CLI subcommands ([#174](#174)) ([be15666](be15666)) ### Documentation * **repo:** clarify `sql` targets the temporal store, not the node/edge graph ([#173](#173)) ([814774a](814774a)) ### Dependencies * The following workspace dependencies were updated * dependencies * @opencodehub/analysis bumped to 0.3.3 * @opencodehub/pack bumped to 0.2.4 * @opencodehub/scanners bumped to 0.2.3 * @opencodehub/search bumped to 0.2.3 * @opencodehub/storage bumped to 0.2.3 </details> <details><summary>pack: 0.2.4</summary> ## [0.2.4](pack-v0.2.3...pack-v0.2.4) (2026-05-29) ### Dependencies * The following workspace dependencies were updated * dependencies * @opencodehub/analysis bumped to 0.3.3 * @opencodehub/ingestion bumped to 0.4.5 * @opencodehub/storage bumped to 0.2.3 </details> <details><summary>scanners: 0.2.3</summary> ## [0.2.3](scanners-v0.2.2...scanners-v0.2.3) (2026-05-29) ### Bug Fixes * **scanners:** exclude indexer-ignored dirs from vulture/radon/ty (drop .venv noise) ([#168](#168)) ([848aa34](848aa34)) </details> <details><summary>scip-ingest: 0.2.5</summary> ## [0.2.5](scip-ingest-v0.2.4...scip-ingest-v0.2.5) (2026-05-29) ### Dependencies * The following workspace dependencies were updated * dependencies * @opencodehub/analysis bumped to 0.3.3 </details> <details><summary>search: 0.2.3</summary> ## [0.2.3](search-v0.2.2...search-v0.2.3) (2026-05-29) ### Dependencies * The following workspace dependencies were updated * dependencies * @opencodehub/storage bumped to 0.2.3 </details> <details><summary>storage: 0.2.3</summary> ## [0.2.3](storage-v0.2.2...storage-v0.2.3) (2026-05-29) ### Features * **cli:** status surfaces retrieval mode (summaries / vectors / embedder) ([#172](#172)) ([611e818](611e818)) </details> <details><summary>wiki: 0.2.3</summary> ## [0.2.3](wiki-v0.2.2...wiki-v0.2.3) (2026-05-29) ### Dependencies * The following workspace dependencies were updated * dependencies * @opencodehub/storage bumped to 0.2.3 </details> <details><summary>root: 0.6.7</summary> ## [0.6.7](root-v0.6.6...root-v0.6.7) (2026-05-29) ### Features * **cli:** expose 9 read-only graph tools as CLI subcommands ([#174](#174)) ([be15666](be15666)) * **cli:** status surfaces retrieval mode (summaries / vectors / embedder) ([#172](#172)) ([611e818](611e818)) ### Bug Fixes * **cli:** doctor verifies the bandit[sarif] formatter, not just the binary ([#171](#171)) ([0d78c92](0d78c92)) * **scanners:** exclude indexer-ignored dirs from vulture/radon/ty (drop .venv noise) ([#168](#168)) ([848aa34](848aa34)) ### Documentation * **repo:** clarify `sql` targets the temporal store, not the node/edge graph ([#173](#173)) ([814774a](814774a)) </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
codehub sqland the MCPsqltool'ssqlarg run against the DuckDB temporal store (cochanges+symbol_summaries). The node/edge graph moved to lbug in ADR 0016 and is reachable only via the typed tools or Cypher. Docs across the repo still said "SQL against the graph store" (field-report Issue 4), and theopencodehub-guideskill shipped a whole "Graph schema" + "SQL cheat-sheet" ofSELECT … FROM nodes/relationsqueries that error against the current store.Changes (guidance/strings only — no query behavior change)
CLAUDE.md,AGENTS.md,packages/cli/README.md, thesql--helpincli/src/index.ts,cli/src/agent-context.ts,docs/reference/cli.md,docs/agents/tool-decision-matrix.mdx.opencodehub-guideSKILL.md cheat-sheet (both copies:.claude/skills+plugins/) to real lbug Cypher: single:CodeNodelabel withkindas a property, snake_case props (file_path,start_line,step_count, …), per-type relationship labels ([r:CALLS]), plus a small temporal-SQLcochangesexample. The framing now states the two-store split explicitly.dependencies,list-findings) that told users to runSELECT * FROM relations …→ nowMATCH ()-[r:…]->() RETURN rCypher.Test plan
grepconfirms zeroFROM relations/FROM nodes/ "DuckDB-backed graph" guidance remains in live docs.tsc --noEmit+biomeclean on the touched code files.Heads-up (not caused by this PR)
A pre-existing mcp unit test,
impact surfaces cochanges(tool-handlers.test.js), fails on clean main — the cochange test-harness wiring drifted since #117 (the DuckDB-graph rip). It's not in any path this PR touches and is not a branch-protection-required check (the mcp unit suite is the non-requiredtestjob). Tracked separately for a focused harness fix.