From 40b6886b25ea8c83de5155f5813666751f9d5a49 Mon Sep 17 00:00:00 2001 From: Laith Al-Saadoon Date: Sun, 10 May 2026 19:18:56 +0000 Subject: [PATCH 1/4] docs(docs): drop migrating-from-duckdb guide and its cross-references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The site reads as if v1 is the only reality — there is no installed base on a prior layout to migrate from. Delete the migration guide and its inbound links from configuration.md, indexing-a-repo.md, and storage-backend.md. Update the llms-txt customSet description so it no longer advertises a migration guide. --- packages/docs/astro.config.mjs | 2 +- .../docs/architecture/storage-backend.md | 10 +- .../content/docs/guides/indexing-a-repo.md | 5 +- .../docs/guides/migrating-from-duckdb.md | 140 ------------------ .../content/docs/reference/configuration.md | 4 +- 5 files changed, 7 insertions(+), 154 deletions(-) delete mode 100644 packages/docs/src/content/docs/guides/migrating-from-duckdb.md diff --git a/packages/docs/astro.config.mjs b/packages/docs/astro.config.mjs index eee99eb4..97ad68c3 100644 --- a/packages/docs/astro.config.mjs +++ b/packages/docs/astro.config.mjs @@ -74,7 +74,7 @@ export default defineConfig({ label: "user-guide", paths: ["start-here/**", "guides/**"], description: - "User-facing pages only: install, quick-start, editor integration guides, group + migration guides.", + "User-facing pages only: install, quick-start, editor integration guides, group and indexing guides.", }, { label: "agents", diff --git a/packages/docs/src/content/docs/architecture/storage-backend.md b/packages/docs/src/content/docs/architecture/storage-backend.md index f0dd82c1..02df6fd0 100644 --- a/packages/docs/src/content/docs/architecture/storage-backend.md +++ b/packages/docs/src/content/docs/architecture/storage-backend.md @@ -112,15 +112,11 @@ commit produce the same hash. The CI parity gate that landed with M7 asserts this on every PR that touches `packages/storage`. The implication: a developer can switch backends on a working repo -without re-indexing, as long as both artifact files exist. See -[Migrating from DuckDB](/opencodehub/guides/migrating-from-duckdb/) -for the recipe. +without re-indexing, as long as both artifact files exist. ## See also -- [ADR 0011 — LadybugDB (phase-1)](https://github.com/theagenticguy/opencodehub/blob/main/docs/adr/0011-graph-db-backend.md) -- [ADR 0013 (M7) — Default-flip + interface segregation](https://github.com/theagenticguy/opencodehub/blob/main/docs/adr/0013-m7-default-flip-and-abstraction.md) +- [ADR 0011 — LadybugDB graph backend](https://github.com/theagenticguy/opencodehub/blob/main/docs/adr/0011-graph-db-backend.md) +- [ADR 0013 — Storage default + interface segregation](https://github.com/theagenticguy/opencodehub/blob/main/docs/adr/0013-m7-default-flip-and-abstraction.md) - [Configuration](/opencodehub/reference/configuration/) — env vars and on-disk layout. -- [Migrating from DuckDB](/opencodehub/guides/migrating-from-duckdb/) - — how to move an existing index. diff --git a/packages/docs/src/content/docs/guides/indexing-a-repo.md b/packages/docs/src/content/docs/guides/indexing-a-repo.md index df090c7a..de9a34e0 100644 --- a/packages/docs/src/content/docs/guides/indexing-a-repo.md +++ b/packages/docs/src/content/docs/guides/indexing-a-repo.md @@ -14,9 +14,8 @@ root. The default backend is **LadybugDB** for the graph half + **DuckDB** for the temporal sibling. Set `CODEHUB_STORE=duck` to -force the legacy single-file DuckDB layout. See -[Storage backend](/opencodehub/architecture/storage-backend/) and -[Migrating from DuckDB](/opencodehub/guides/migrating-from-duckdb/). +force the single-file DuckDB layout. See +[Storage backend](/opencodehub/architecture/storage-backend/). ## Basic indexing diff --git a/packages/docs/src/content/docs/guides/migrating-from-duckdb.md b/packages/docs/src/content/docs/guides/migrating-from-duckdb.md deleted file mode 100644 index 30748708..00000000 --- a/packages/docs/src/content/docs/guides/migrating-from-duckdb.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Migrating from DuckDB to LadybugDB -description: Move an existing OpenCodeHub index from the legacy DuckDB single-file layout to the default LadybugDB + DuckDB temporal layout. -sidebar: - order: 75 ---- - -If you indexed a repo before the M7 default-flip, your `.codehub/` -holds a single `graph.duckdb` file. The default backend is now -**LadybugDB + DuckDB temporal** (two artifacts: -`graph.lbug` + `temporal.duckdb`). This guide covers the migration -options. - -## Option A — re-index from scratch - -The simplest path. Throws the legacy artifact away, runs the full -pipeline against HEAD, writes the new layout. - -```bash title="re-index a repo into the default backend" -codehub clean -codehub analyze -``` - -`codehub analyze` defaults to `CODEHUB_STORE=auto`, which probes -`@ladybugdb/core` and uses LadybugDB when the binding is importable. -The graph hash will match what the legacy DuckDB layout would have -produced at the same commit (the M7 parity gate enforces this), so -downstream tooling does not see drift. - -Trade-off: full re-index time. On a 100k-LOC repo that is single-digit -minutes; on a 500k-LOC repo it can be 10–20 minutes depending on the -machine. - -## Option B — keep both artifacts, let the resolver pick - -`codehub analyze` will not delete a sibling artifact. If you run -`codehub analyze` while `.codehub/graph.duckdb` exists, the new run -writes `graph.lbug` + `temporal.duckdb` alongside it. From that -moment, **the newer-mtime file wins** when both exist. - -To force the legacy backend explicitly during a migration window: - -```bash -CODEHUB_STORE=duck codehub analyze -``` - -This is useful if you need to keep an older script reading -`graph.duckdb` directly — but the moment you move to OCH-driven tools -(`codehub query`, MCP tools, `verdict`), `CODEHUB_STORE=duck` is the -only way to keep them on the legacy file. - -To force LadybugDB explicitly (and refuse the fallback): - -```bash -CODEHUB_STORE=lbug codehub analyze -``` - -This **throws** if `@ladybugdb/core` is not importable, instead of -silently dropping back to DuckDB. Useful in CI to guarantee a -specific layout. - -## Option C — run on the legacy DuckDB layout indefinitely - -The legacy single-file DuckDB layout is supported. Set -`CODEHUB_STORE=duck` in your environment and every `codehub -analyze` / `codehub query` / MCP tool / scanner emission stays on -the legacy path: - -```bash title="opt out of the M7 flip permanently" -export CODEHUB_STORE=duck -``` - -This is the right choice if your deployment cannot install -`@ladybugdb/core` (locked-down npm registry, air-gapped CI image, -unsupported platform). The graph hash, the MCP surface, the SARIF -output, and the determinism contract all hold on the legacy layout. - -Trade-off: the M3+ workload performance improvements that motivated -the M7 flip are not available — recursive-CTE traversals on the -polymorphic `relations` table do not get faster than they were in -v1.0. - -## Verifying the migration - -```bash title="confirm the active backend" -codehub status -``` - -`status` reports the artifact path (`graph.lbug` or `graph.duckdb`) -and the graph hash. If the same commit produced different hashes on -the two backends, the M7 parity invariant is broken — file an issue -with the `meta.json` from each `.codehub/`. - -## Edge cases - -### Both `graph.lbug` and `graph.duckdb` exist - -The newer-mtime file wins. If you need to force one: - -```bash -# Force the graph-database backend regardless of mtime. -CODEHUB_STORE=lbug codehub status - -# Force the legacy file regardless of mtime. -CODEHUB_STORE=duck codehub status -``` - -To delete the unused sibling once the migration is complete: - -```bash -rm .codehub/graph.duckdb # if you migrated to the graph-database backend -# or -rm .codehub/graph.lbug .codehub/temporal.duckdb # if you stayed on legacy -``` - -### Embedder model mismatch - -If you re-index with a different embedder than the original (e.g. -switching from local ONNX to a SageMaker endpoint), the embeddings -table inherits the modelId of whichever embedder ran last. The query -path refuses with `EMBEDDER_MISMATCH` rather than silently misranking; -ADR 0014 covers the contract. Pass the documented force flag if you -intend to mix embedders. - -### CI parity - -If you run a CI matrix that exercises both backends, set -`CODEHUB_STORE=lbug` on one job and `CODEHUB_STORE=duck` on the -other. The M7 parity gate compares the hashes at the same commit and -fails the build on drift. - -## See also - -- [Storage backend](/opencodehub/architecture/storage-backend/) — the - resolver, the dual-artifact precedence rule, the community-adapter - escape hatch. -- [ADR 0013 (M7)](https://github.com/theagenticguy/opencodehub/blob/main/docs/adr/0013-m7-default-flip-and-abstraction.md) - — the decision and the parity gate. -- [Configuration](/opencodehub/reference/configuration/#storage-backend) - — the env var inventory. diff --git a/packages/docs/src/content/docs/reference/configuration.md b/packages/docs/src/content/docs/reference/configuration.md index 7ff31770..97200fb1 100644 --- a/packages/docs/src/content/docs/reference/configuration.md +++ b/packages/docs/src/content/docs/reference/configuration.md @@ -82,9 +82,7 @@ exact files depend on the backend selected at index time. | `scan.sarif` | SARIF output from `codehub scan`. | When both `graph.lbug` and `graph.duckdb` exist as siblings, the -newer-`mtime` file wins. See [Migrating from -DuckDB](/opencodehub/guides/migrating-from-duckdb/) for the migration -recipe. +newer-`mtime` file wins. Safe to delete and rebuild at any time via `codehub clean` + `codehub analyze`. From e05cd50a8d440594fa873e3aca3d0e565f3b9ffd Mon Sep 17 00:00:00 2001 From: Laith Al-Saadoon Date: Sun, 10 May 2026 19:21:24 +0000 Subject: [PATCH 2/4] docs(docs): describe storage as default+fallback, not as a milestone flip LadybugDB is the default; the single-file DuckDB layout is the opt-in fallback for environments where the @ladybugdb/core binding cannot load. Drop "M7 default-flip", "legacy default", and "what's new" prose across storage-backend, overview, determinism, monorepo-map, install, quick-start, what-is-opencodehub, configuration, indexing-a-repo, and troubleshooting. ADR 0013 is now described as recording a decision, not as a flip event. --- .../content/docs/architecture/determinism.md | 4 +-- .../content/docs/architecture/monorepo-map.md | 4 +-- .../src/content/docs/architecture/overview.md | 9 ++++--- .../docs/architecture/storage-backend.md | 25 ++++++++++--------- .../content/docs/guides/indexing-a-repo.md | 2 +- .../content/docs/guides/troubleshooting.md | 4 +-- .../content/docs/reference/configuration.md | 11 ++++---- .../src/content/docs/start-here/install.md | 2 +- .../content/docs/start-here/quick-start.md | 8 +++--- .../docs/start-here/what-is-opencodehub.md | 19 +++++++------- 10 files changed, 46 insertions(+), 42 deletions(-) diff --git a/packages/docs/src/content/docs/architecture/determinism.md b/packages/docs/src/content/docs/architecture/determinism.md index 1924c5d6..8aa6ae9c 100644 --- a/packages/docs/src/content/docs/architecture/determinism.md +++ b/packages/docs/src/content/docs/architecture/determinism.md @@ -47,8 +47,8 @@ are pure: inputs in, relations out, no ambient state. The `graphHash` invariant is **backend-independent**. A repo indexed into LadybugDB (`graph.lbug`) and the same repo indexed into the -legacy DuckDB layout (`graph.duckdb`) at the same commit produce the -same hash. The M7 parity gate in CI compares the two hashes on every +single-file DuckDB layout (`graph.duckdb`) at the same commit produce +the same hash. A parity gate in CI compares the two hashes on every PR that touches the storage layer. ## How we test it diff --git a/packages/docs/src/content/docs/architecture/monorepo-map.md b/packages/docs/src/content/docs/architecture/monorepo-map.md index fe6a24ab..838bfa53 100644 --- a/packages/docs/src/content/docs/architecture/monorepo-map.md +++ b/packages/docs/src/content/docs/architecture/monorepo-map.md @@ -52,7 +52,7 @@ Think of it as two layers: Orchestrators import leaves; leaves do not import orchestrators. The TypeScript project-references graph enforces this via `tsc --noEmit`. -## Storage — the M7 segregation +## Storage — interface segregation `@opencodehub/storage` exposes two narrow interfaces — `IGraphStore` (graph workload: nodes, edges, embeddings, multi-hop traversal) and @@ -63,7 +63,7 @@ adapters implement them: artifacts on disk (`graph.lbug` + `temporal.duckdb`), backed by a Cypher-emitting dialect for the graph half and DuckDB SQL for the temporal half. -- **Single DuckDB file** — the legacy fallback. One artifact +- **Single DuckDB file** — the opt-in fallback. One artifact (`graph.duckdb`) backs both interfaces. See [Storage backend](/opencodehub/architecture/storage-backend/) for diff --git a/packages/docs/src/content/docs/architecture/overview.md b/packages/docs/src/content/docs/architecture/overview.md index a9760454..ec65afc7 100644 --- a/packages/docs/src/content/docs/architecture/overview.md +++ b/packages/docs/src/content/docs/architecture/overview.md @@ -34,8 +34,9 @@ agent queries. ## Where the data lives The default backend is **LadybugDB**, with **DuckDB** as the temporal -sibling. The legacy single-file DuckDB layout is still supported via -`CODEHUB_STORE=duck`. See [Storage backend](/opencodehub/architecture/storage-backend/). +sibling. A single-file DuckDB layout is the opt-in fallback when the +`@ladybugdb/core` binding cannot load (or when forced via +`CODEHUB_STORE=duck`). See [Storage backend](/opencodehub/architecture/storage-backend/). ```mermaid flowchart LR @@ -173,7 +174,7 @@ cheapest configuration that hits all three: | 0007–0010 | Artifact factory, document pattern, output conventions, dogfood findings. | | 0011 | LadybugDB (phase-1) — graph-native backend behind the `IGraphStore` seam. | | 0012 | Repo as a first-class graph node — `repo_uri`, group registry, `AMBIGUOUS_REPO` envelope. | -| 0013 (M7) | Default-flip + interface segregation — LadybugDB by default, DuckDB temporal sibling. | +| 0013 (storage) | Storage default + interface segregation — LadybugDB by default, DuckDB temporal sibling. | | 0013 (parse) | WASM-default parse runtime on Node 22 and Node 24. | | 0014 | SCIP REFERENCES + TYPE_OF emission, embedder modelId stamping. | @@ -184,7 +185,7 @@ See [ADRs](/opencodehub/architecture/adrs/) for the full list. - [Monorepo map](/opencodehub/architecture/monorepo-map/) — every workspace package and what it owns. - [Storage backend](/opencodehub/architecture/storage-backend/) — the - M7 default-flip + interface segregation. + graph + temporal interface segregation and the resolver. - [Cross-repo federation](/opencodehub/architecture/cross-repo-federation/) — `repo_uri`, the group registry, and the `AMBIGUOUS_REPO` envelope. - [Determinism](/opencodehub/architecture/determinism/) — the diff --git a/packages/docs/src/content/docs/architecture/storage-backend.md b/packages/docs/src/content/docs/architecture/storage-backend.md index 02df6fd0..a8667e85 100644 --- a/packages/docs/src/content/docs/architecture/storage-backend.md +++ b/packages/docs/src/content/docs/architecture/storage-backend.md @@ -5,10 +5,11 @@ sidebar: order: 25 --- -OpenCodeHub's M7 storage layer is two narrow interfaces, two adapters, +OpenCodeHub's storage layer is two narrow interfaces, two adapters, and a probe. The default is LadybugDB for the graph half and DuckDB -for the temporal half. The legacy single-file DuckDB layout is still -available as a fallback. +for the temporal half. A single-file DuckDB layout is available as an +opt-in fallback for environments where the LadybugDB binding cannot +load. ## The interfaces @@ -24,10 +25,10 @@ available as a fallback. Splitting the interfaces lets community adapters implement only the half they have an engine for. A graph-only Neo4j adapter does not have to handle cochange queries; a DuckDB-only deployment does not have to -implement Cypher. ADR 0013 (M7) describes the call-site refactor that -made this work — 108 raw-SQL call sites across `analysis/`, `mcp/`, -`pack/`, `wiki/`, and `cli/` now route through the typed finders on -the interfaces. +implement Cypher. ADR 0013 records the call-site refactor that made +this work — 108 raw-SQL call sites across `analysis/`, `mcp/`, +`pack/`, `wiki/`, and `cli/` route through the typed finders on the +interfaces. ## The two adapters that ship @@ -41,10 +42,10 @@ Two artifacts on disk: | `/.codehub/temporal.duckdb` | Cochanges, symbol-summary cache — everything `ITemporalStore` owns. | The graph half speaks Cypher natively and stores each edge kind in -its own physical layout, which is the part of the M7 motivation that -DuckDB's polymorphic `relations` table could not match. +its own physical layout — the part of the motivation that DuckDB's +polymorphic `relations` table could not match. -### Single DuckDB file (legacy / fallback) +### Single DuckDB file (opt-in fallback) | File | Holds | |---|---| @@ -108,8 +109,8 @@ ADR 0013 names the four explicitly. The `graphHash` invariant holds across both adapters. A repo indexed into LadybugDB and the same repo indexed into DuckDB at the same -commit produce the same hash. The CI parity gate that landed with M7 -asserts this on every PR that touches `packages/storage`. +commit produce the same hash. A CI parity gate asserts this on every +PR that touches `packages/storage`. The implication: a developer can switch backends on a working repo without re-indexing, as long as both artifact files exist. diff --git a/packages/docs/src/content/docs/guides/indexing-a-repo.md b/packages/docs/src/content/docs/guides/indexing-a-repo.md index de9a34e0..25582df0 100644 --- a/packages/docs/src/content/docs/guides/indexing-a-repo.md +++ b/packages/docs/src/content/docs/guides/indexing-a-repo.md @@ -93,7 +93,7 @@ On the default LadybugDB layout: | `scan.sarif` | SARIF scan output when `codehub scan` has run. | | `sbom.cyclonedx.json` / `sbom.spdx.json` | SBOMs when `codehub analyze --sbom` has run. | -On the legacy DuckDB layout, `graph.duckdb` replaces both +On the single-file DuckDB fallback, `graph.duckdb` replaces both `graph.lbug` and `temporal.duckdb`. ## Other useful flags diff --git a/packages/docs/src/content/docs/guides/troubleshooting.md b/packages/docs/src/content/docs/guides/troubleshooting.md index 9124621b..bb72c104 100644 --- a/packages/docs/src/content/docs/guides/troubleshooting.md +++ b/packages/docs/src/content/docs/guides/troubleshooting.md @@ -25,8 +25,8 @@ prints. The default parse runtime is `web-tree-sitter` (WASM) on both Node 22 and Node 24, so a missing C/C++ toolchain does not break analyze itself — only the optional native opt-in via `OCH_NATIVE_PARSER=1` is -affected. `@duckdb/node-api` still has a native binding requirement -on the legacy DuckDB layout; if it cannot load, set `CODEHUB_STORE=lbug` +affected. `@duckdb/node-api` has a native binding requirement on the +single-file DuckDB fallback; if it cannot load, set `CODEHUB_STORE=lbug` to use LadybugDB instead, which has its own platform packages. ## Stale index diff --git a/packages/docs/src/content/docs/reference/configuration.md b/packages/docs/src/content/docs/reference/configuration.md index 97200fb1..23a232d4 100644 --- a/packages/docs/src/content/docs/reference/configuration.md +++ b/packages/docs/src/content/docs/reference/configuration.md @@ -16,12 +16,13 @@ mutate global state. | Variable | Purpose | |---|---| -| `CODEHUB_STORE` | `lbug` forces LadybugDB; `duck` forces the legacy DuckDB single-file layout. Unset (the default) means probe `@ladybugdb/core` and use LadybugDB when the binding is importable, otherwise DuckDB. | +| `CODEHUB_STORE` | `lbug` forces LadybugDB; `duck` forces the single-file DuckDB layout. Unset (the default) means probe `@ladybugdb/core` and use LadybugDB when the binding is importable, otherwise fall back to DuckDB. | | `CODEHUB_HOME` | Override `~/.codehub/` (where the registry, embedder weights, and global state live). | | `OCH_VERBOSE` | Set to `1` to surface the storage-backend probe advisory in non-TTY environments. | -ADR 0013 (`docs/adr/0013-m7-default-flip-and-abstraction.md`) explains -the M7 flip from DuckDB-default to LadybugDB-default. +ADR 0013 (`docs/adr/0013-m7-default-flip-and-abstraction.md`) records +the LadybugDB-default decision and the `IGraphStore` / `ITemporalStore` +interface segregation. ### Parse runtime @@ -30,7 +31,7 @@ the M7 flip from DuckDB-default to LadybugDB-default. | `OCH_NATIVE_PARSER` | Set to `1` on Node 22 to opt into the native `tree-sitter` N-API addon. The default runtime on Node 22 and Node 24 is `web-tree-sitter` (WASM). | The `--native-parser` CLI flag is equivalent. ADR -0013-parse-runtime-wasm-default explains the v1 flip. +0013-parse-runtime-wasm-default records the WASM-default decision. ### Embedding backends @@ -73,7 +74,7 @@ exact files depend on the backend selected at index time. | `scan.sarif` | SARIF output from `codehub scan`. | | `sbom.cyclonedx.json` / `sbom.spdx.json` | SBOMs when `codehub analyze --sbom` has run. | -### DuckDB (legacy / fallback) +### DuckDB (opt-in fallback) | Path | Purpose | |---|---| diff --git a/packages/docs/src/content/docs/start-here/install.md b/packages/docs/src/content/docs/start-here/install.md index 4ac0aef9..6a25d1e2 100644 --- a/packages/docs/src/content/docs/start-here/install.md +++ b/packages/docs/src/content/docs/start-here/install.md @@ -110,7 +110,7 @@ node packages/cli/dist/index.js doctor | Variable | Default | Effect | |---|---|---| | `OCH_NATIVE_PARSER` | unset | Set to `1` on Node 22 to opt into the native tree-sitter N-API addon. Leave unset to use the WASM default. | -| `CODEHUB_STORE` | unset | `lbug` (force LadybugDB), `duck` (force the legacy DuckDB single-file layout), or unset (auto-probe — LadybugDB when `@ladybugdb/core` is importable, otherwise DuckDB). | +| `CODEHUB_STORE` | unset | `lbug` (force LadybugDB), `duck` (force the single-file DuckDB layout), or unset (auto-probe — LadybugDB when `@ladybugdb/core` is importable, otherwise DuckDB). | | `OCH_VERBOSE` | unset | Set to `1` to surface the storage-backend probe advisory in non-TTY environments. | See [Configuration](/opencodehub/reference/configuration/) for the full diff --git a/packages/docs/src/content/docs/start-here/quick-start.md b/packages/docs/src/content/docs/start-here/quick-start.md index f5f294f8..5d9e4872 100644 --- a/packages/docs/src/content/docs/start-here/quick-start.md +++ b/packages/docs/src/content/docs/start-here/quick-start.md @@ -65,7 +65,7 @@ git, every teammate who clones the repo gets the plugin automatically. No per-machine install step. If you prefer the manual path — just the MCP config, no project-scope -plugin — use the legacy `setup` flow: +plugin — use `codehub setup`: ```bash title="manual: MCP config only" codehub setup --editors claude-code @@ -80,9 +80,9 @@ codehub analyze `analyze` writes the graph to `.codehub/` under the repo root and registers the repo in `~/.codehub/registry.json`. By default the graph lands in `.codehub/graph.lbug` (LadybugDB) with `.codehub/temporal.duckdb` -alongside it; if `@ladybugdb/core` is unavailable the analyze falls -back to the single-file `.codehub/graph.duckdb` layout. Add -`--embeddings` to compute semantic vectors for hybrid search, or +alongside it; if `@ladybugdb/core` cannot load on the current platform, +analyze falls back to the single-file `.codehub/graph.duckdb` layout. +Add `--embeddings` to compute semantic vectors for hybrid search, or `--offline` to guarantee zero network sockets. ## 5. Ask the agent diff --git a/packages/docs/src/content/docs/start-here/what-is-opencodehub.md b/packages/docs/src/content/docs/start-here/what-is-opencodehub.md index a6eb4628..678286c4 100644 --- a/packages/docs/src/content/docs/start-here/what-is-opencodehub.md +++ b/packages/docs/src/content/docs/start-here/what-is-opencodehub.md @@ -28,12 +28,13 @@ where does this data flow. OpenCodeHub parses your repository with tree-sitter (15 GA languages, plus SCIP indexers for TypeScript, Python, Go, Rust, and Java), resolves imports and inheritance, and materialises a **typed symbol -graph**. That graph is stored in LadybugDB, a graph-native database -(with DuckDB as the temporal sibling, and as the legacy fallback when -the `@ladybugdb/core` binding is unavailable). BM25 lexical search and -filter-aware HNSW vector search sit on the same store. A local MCP -server exposes the graph to any agent that speaks Model Context -Protocol. +graph**. That graph is stored in LadybugDB, a graph-native database, +with DuckDB carrying the temporal sibling (cochanges and the +symbol-summary cache). DuckDB also serves as a single-file fallback +for environments where the `@ladybugdb/core` binding cannot load. +BM25 lexical search and filter-aware HNSW vector search sit on the +same store. A local MCP server exposes the graph to any agent that +speaks Model Context Protocol. ```mermaid flowchart LR @@ -50,11 +51,11 @@ Clustering, execution-flow tracing, and blast-radius analysis all happen once at index time. Agents get complete relational context in one tool call, not ten round-trips. -## What's new since the v1.0 cut +## What you get in v1 - **Graph-native storage by default.** LadybugDB is the default backend; - a dedicated DuckDB sibling serves the temporal store. The legacy - single-file DuckDB layout is still selectable via `CODEHUB_STORE=duck`. + a dedicated DuckDB sibling serves the temporal store. A single-file + DuckDB layout is the opt-in fallback via `CODEHUB_STORE=duck`. - **Cross-repo federation.** Group several indexed repos with `codehub group` and query them through the `group_*` MCP tools. The repo is a first-class graph node and `repo_uri` carries through every From 63a6c0b5ceb2f7f8072c48f0d09617b5cc320121 Mon Sep 17 00:00:00 2001 From: Laith Al-Saadoon Date: Sun, 10 May 2026 19:23:38 +0000 Subject: [PATCH 3/4] =?UTF-8?q?docs(docs):=20drop=20M3-M7=20milestone=20fr?= =?UTF-8?q?aming=20=E2=80=94=20describe=20OCH=20as=20it=20is,=20not=20how?= =?UTF-8?q?=20it=20evolved?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Site prose now describes the current shape of the system without pinning behavior to milestones. ADR cross-references are reframed as "records this decision" rather than "this milestone delivered X". Trims the canned-prompts page so it explains why playbooks live as skills instead of narrating a removal event. --- .../src/content/docs/architecture/adrs.md | 27 +++++++------- .../architecture/cross-repo-federation.md | 2 +- .../src/content/docs/architecture/lessons.md | 3 +- .../docs/src/content/docs/mcp/overview.md | 13 ++++--- packages/docs/src/content/docs/mcp/prompts.md | 35 +++++++++---------- 5 files changed, 38 insertions(+), 42 deletions(-) diff --git a/packages/docs/src/content/docs/architecture/adrs.md b/packages/docs/src/content/docs/architecture/adrs.md index a6302156..aae2b4f3 100644 --- a/packages/docs/src/content/docs/architecture/adrs.md +++ b/packages/docs/src/content/docs/architecture/adrs.md @@ -18,8 +18,8 @@ DuckDB via `@duckdb/node-api` plus the `hnsw_acorn` community extension for filter-aware vector search and the official `fts` extension for BM25. SQLite + `sqlite-vec` was rejected because FTS5 has no filtered-HNSW story. Superseded as the default by ADR 0011 + -ADR 0013 (M7), but DuckDB is still the temporal-store backend and the -legacy single-file fallback. +ADR 0013, but DuckDB is still the temporal-store backend and the +single-file opt-in fallback. [Read ADR 0001](https://github.com/theagenticguy/opencodehub/blob/main/docs/adr/0001-storage-backend.md) @@ -92,32 +92,31 @@ column, Phase 0 schema preflight. ### ADR 0011 — LadybugDB (phase-1) -Add `@ladybugdb/core` as the opt-in LadybugDB graph backend behind the -existing `IGraphStore` seam. Default stays on DuckDB through M3 – M6. -Motivation: recursive-CTE traversals on the polymorphic `relations` -table do not get faster, and the predicate cannot be pushed into the -graph walk. +Adds `@ladybugdb/core` as the LadybugDB graph backend behind the +`IGraphStore` seam. Motivation: recursive-CTE traversals on the +polymorphic `relations` table do not get faster, and the predicate +cannot be pushed into the graph walk. [Read ADR 0011](https://github.com/theagenticguy/opencodehub/blob/main/docs/adr/0011-graph-db-backend.md) ### ADR 0012 — Repo as a first-class graph node Promote `repo_uri`, `default_branch`, and `group` to typed graph -attributes on a `Repo` node. Backs the M6 federation surface +attributes on a `Repo` node. Backs the cross-repo federation surface (`group_query`, `group_status`, `group_contracts`, `group_list`, `group_cross_repo_links`) and the structured `AMBIGUOUS_REPO` envelope returned by per-repo tools. [Read ADR 0012](https://github.com/theagenticguy/opencodehub/blob/main/docs/adr/0012-repo-as-first-class-node.md) -### ADR 0013 — M7 default-flip + storage abstraction +### ADR 0013 — Storage default + interface segregation -Flip the default to LadybugDB and segregate `IGraphStore` from -`ITemporalStore`. The temporal half (cochanges, summary cache) stays -on DuckDB. Adds the community-adapter escape hatch (AGE / Memgraph / -Neo4j / Neptune) so OCH does not lock users into LadybugDB. +LadybugDB is the default backend and `IGraphStore` is segregated from +`ITemporalStore`. The temporal half (cochanges, summary cache) lives +on DuckDB. The community-adapter escape hatch (AGE / Memgraph / +Neo4j / Neptune) keeps OCH from locking users into LadybugDB. -[Read ADR 0013 (M7)](https://github.com/theagenticguy/opencodehub/blob/main/docs/adr/0013-m7-default-flip-and-abstraction.md) +[Read ADR 0013](https://github.com/theagenticguy/opencodehub/blob/main/docs/adr/0013-m7-default-flip-and-abstraction.md) ### ADR 0013 — Parse runtime: WASM default, native opt-in diff --git a/packages/docs/src/content/docs/architecture/cross-repo-federation.md b/packages/docs/src/content/docs/architecture/cross-repo-federation.md index 852e2c3d..20f09d43 100644 --- a/packages/docs/src/content/docs/architecture/cross-repo-federation.md +++ b/packages/docs/src/content/docs/architecture/cross-repo-federation.md @@ -1,6 +1,6 @@ --- title: Cross-repo federation -description: Repo as a first-class graph node, the group registry, the AMBIGUOUS_REPO envelope, and the M5 / M6 design. +description: Repo as a first-class graph node, the group registry, the AMBIGUOUS_REPO envelope, and the cross-repo group_* MCP surface. sidebar: order: 27 --- diff --git a/packages/docs/src/content/docs/architecture/lessons.md b/packages/docs/src/content/docs/architecture/lessons.md index da4a2a81..769dae66 100644 --- a/packages/docs/src/content/docs/architecture/lessons.md +++ b/packages/docs/src/content/docs/architecture/lessons.md @@ -49,7 +49,8 @@ The lessons that shape this codebase the most include: - `architecture-patterns/scip-monorepo-dist-src-alias.md` — the TypeScript monorepo `dist/` ↔ `src/` alias pattern. - `architecture-patterns/igraphstore-itemporalstore-segregation.md` - — why M7 split the storage interface in two. + — why the storage interface is split into `IGraphStore` and + `ITemporalStore`. - `architecture-patterns/typed-finders-replace-raw-sql-in-consumers.md` — the call-site refactor that lets the graph backend swap underneath consumer packages. diff --git a/packages/docs/src/content/docs/mcp/overview.md b/packages/docs/src/content/docs/mcp/overview.md index 6ae90e45..7f2aac40 100644 --- a/packages/docs/src/content/docs/mcp/overview.md +++ b/packages/docs/src/content/docs/mcp/overview.md @@ -14,8 +14,8 @@ can connect to over stdio. - **Transport:** stdio (JSON-RPC over stdin/stdout) - **Launch command:** `codehub mcp` - **Capabilities:** `tools` and `resources`. The server does not - advertise `prompts` — the canned-prompts surface was removed in v1 - in favour of the Claude Code plugin's skills. + advertise `prompts` — the canned-prompts surface lives as Claude + Code skills shipped by `plugins/opencodehub/` instead. - **Tool count:** 29 (registered in `packages/mcp/src/server.ts`) Clients spawn the `codehub mcp` process and exchange JSON-RPC frames @@ -93,8 +93,7 @@ Error responses instead carry `isError: true`, and metadata. See [tools](/opencodehub/mcp/tools/). - **7 resources** — structured views over repos, clusters, and processes. See [resources](/opencodehub/mcp/resources/). -- **0 prompts** — the v1 surface is intentionally empty. The - pre-baked playbooks formerly served from `prompts/` now live as - Claude Code [skills](/opencodehub/skills/) shipped by - `plugins/opencodehub/`. See [prompts](/opencodehub/mcp/prompts/) for - the rationale. +- **0 prompts** — the v1 surface is intentionally empty. Pre-baked + playbooks live as Claude Code [skills](/opencodehub/skills/) shipped + by `plugins/opencodehub/`. See [prompts](/opencodehub/mcp/prompts/) + for the rationale. diff --git a/packages/docs/src/content/docs/mcp/prompts.md b/packages/docs/src/content/docs/mcp/prompts.md index 25c3508b..2d33492b 100644 --- a/packages/docs/src/content/docs/mcp/prompts.md +++ b/packages/docs/src/content/docs/mcp/prompts.md @@ -1,21 +1,18 @@ --- title: MCP prompts -description: The MCP prompts surface is intentionally empty in v1 — the canned-prompt playbooks moved to skills. +description: The MCP prompts surface is intentionally empty — playbooks live as Claude Code skills instead. sidebar: order: 40 --- -The `opencodehub` MCP server v1 advertises **0 prompts**. The server +The `opencodehub` MCP server advertises **0 prompts**. The server capability block declares `tools` and `resources` only — `prompts` is not registered, and clients that probe for it get an empty list. ## Why -Earlier prereleases of OpenCodeHub shipped five canned prompts -(`detect-impact`, `review-pr`, `explore-area`, `audit-dependencies`, -`generate-map`). Each was a multi-step playbook the agent could invoke -to drive a structured task. Two problems shaped the v1 decision to -remove them: +Two reasons playbook material lives as Claude Code skills rather than +as MCP prompts: - **Prompts are static.** A canned prompt template can name a sequence of tool calls but cannot adapt to repo state, group @@ -27,21 +24,21 @@ remove them: the plugin reaches every supported editor that loads the plugin — not just the few clients with a working prompts UI. -## What replaced them +## Where the playbooks live -The prompts surface from prereleases is now the -[skills](/opencodehub/skills/) family in `plugins/opencodehub/`: +The [skills](/opencodehub/skills/) family in `plugins/opencodehub/` +covers the playbook surface: -| Old prompt | Now lives at | +| Playbook | Lives at | |---|---| -| `detect-impact` | `opencodehub-impact-analysis` skill + `verdict` MCP tool | -| `review-pr` | `opencodehub-pr-review` skill + `codehub-pr-description` skill | -| `explore-area` | `opencodehub-exploring` skill + `codehub-onboarding` skill | -| `audit-dependencies` | `audit-deps` slash command + `license_audit` MCP tool | -| `generate-map` | `codehub-document` skill + `route_map` / `tool_map` MCP tools | - -All five replacements are richer than the originals because they -inspect graph state and dispatch tools dynamically. +| Impact / blast-radius analysis | `opencodehub-impact-analysis` skill + `verdict` MCP tool | +| PR review | `opencodehub-pr-review` skill + `codehub-pr-description` skill | +| Codebase exploration | `opencodehub-exploring` skill + `codehub-onboarding` skill | +| Dependency audit | `audit-deps` slash command + `license_audit` MCP tool | +| Route / tool map generation | `codehub-document` skill + `route_map` / `tool_map` MCP tools | + +Each skill is richer than a static template because it inspects graph +state and dispatches tools dynamically. If you are on a non-Claude-Code editor and want similar guidance, follow the [MCP tools](/opencodehub/mcp/tools/) catalog — every skill From cd388bb96c465bbad69d767cc5662b5d889cdd4e Mon Sep 17 00:00:00 2001 From: Laith Al-Saadoon Date: Sun, 10 May 2026 19:24:53 +0000 Subject: [PATCH 4/4] docs(docs): drop 0.x BREAKING-change caveats from contributing pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Conventional Commits is a reference; the rule list does not need a "while we're on 0.x" preamble. feat! and BREAKING CHANGE: footer both bump the major version — that is the rule, stated forward-looking. --- .../content/docs/contributing/commit-conventions.md | 9 +++------ .../content/docs/contributing/release-process.md | 13 ++++--------- 2 files changed, 7 insertions(+), 15 deletions(-) diff --git a/packages/docs/src/content/docs/contributing/commit-conventions.md b/packages/docs/src/content/docs/contributing/commit-conventions.md index 136c5e05..05cbab63 100644 --- a/packages/docs/src/content/docs/contributing/commit-conventions.md +++ b/packages/docs/src/content/docs/contributing/commit-conventions.md @@ -93,13 +93,10 @@ Meta-scopes cover cross-cutting changes: | `repo` | Root-level repo files (`.gitignore`, `mise.toml`, etc.) | | `release` | Release-please-authored PRs only | -## Breaking changes on 0.x +## Breaking changes -OpenCodeHub is pre-1.0. The breaking-change rule is version-dependent: - -- **On 0.x:** `feat!` and a `BREAKING CHANGE:` footer both bump the - **minor** version (0.4.2 → 0.5.0). -- **After 1.0.0:** the same signals bump the **major** version. +A `feat!` and a `BREAKING CHANGE:` footer both bump the **major** +version. The `!` form is the short one: diff --git a/packages/docs/src/content/docs/contributing/release-process.md b/packages/docs/src/content/docs/contributing/release-process.md index e0ae9936..c0e20065 100644 --- a/packages/docs/src/content/docs/contributing/release-process.md +++ b/packages/docs/src/content/docs/contributing/release-process.md @@ -77,16 +77,11 @@ Hidden sections still land in git history and still trigger a patch bump format: `-v` (e.g. `@opencodehub/cli-v0.4.2`) plus a root tag `root-v0.4.2`. -## Breaking changes on 0.x +## Breaking changes -While OpenCodeHub sits on `0.x.y`, a `feat!` or `BREAKING CHANGE:` -footer bumps the **minor** version, not the major. That is intentional: -the 0.x prefix signals "not yet stable" and we want the freedom to break -things without forcing a 1.0 → 2.0 stampede. - -After the first 1.0.0 release, the same signals bump the major version. -See the breaking-change section in -[Commit conventions](/opencodehub/contributing/commit-conventions/#breaking-changes-on-0x). +A `feat!` or `BREAKING CHANGE:` footer bumps the major version. See +the breaking-change section in +[Commit conventions](/opencodehub/contributing/commit-conventions/#breaking-changes). ## What you do when your PR lands