docs: pre-release sweep — surface Phase 7 completion + MCP discoverability#74
Merged
Conversation
…ility
Audit pass over docs/ + README + examples + SDK READMEs ahead of the
v0.1.25 release that ships sqlrite-mcp (Phase 7h) for the first time.
Phase 7 is now feature-complete except for the deferred FTS scope, so
a lot of "in progress" / "pending" / "shipping in 7g.X-7g.Y" wording
turned stale and needed flipping.
The biggest single gap was MCP discoverability — `sqlrite-mcp` was
only mentioned in its own README + a few cross-refs in the docs we
just shipped. Anyone landing on the root README, an SDK README, or
the Embedding doc would have no idea it existed. Added a one-liner
"sibling product" cross-ref everywhere.
## Changes
- **README.md** — flipped the Phase 7 "(in progress)" marker; added a
full "MCP server" section near the desktop install with
`cargo install sqlrite-mcp` + a Claude Code config snippet; rewrote
the "Per-product wrappers ship in 7g.3-7g.8" claim into past tense
with the MCP tool included; flipped the stale Phase 4 marker;
flipped "examples for every language" checkbox to done; dropped the
stale `0.1.0` REPL banner literal; rewrote the Phase 2 onboarding
hint about persistence ("`.open` coming in Phase 2" → present-day
"use `.open <path>`").
- **docs/_index.md** — refreshed the "Project state" with Phase 7
achievements (vector + HNSW, JSON, ask family, MCP); added MCP to
the published-artifacts list; flipped active frontier from "Phase 7"
to "Phase 8 (FTS)"; bumped May 2026.
- **docs/roadmap.md** — added an "Active frontier" callout at the
top; dropped "(in progress)" from Phase 3 and Phase 4 headings.
- **docs/phase-7-plan.md** — flipped status from "approved 2026-04-26
— implementation pending" to "complete except 7f, deferred to
Phase 8"; rewrote "Next steps" as a retrospective with pointers to
the two scope-correction retros (7d's HNSW split into three sub-
phases, 7g.2's dep-direction flip).
- **docs/embedding.md** — rewrote the Phase-5 status block (was
future tense across 5b-5g) into a retrospective; added 7g + 7h
bullets with the framing "use SDKs when YOUR code drives the DB,
use MCP when an LLM AGENT drives it"; rewrote the
"Per-product wrappers ship in 7g.3-7g.8" line.
- **docs/architecture.md** — added a Workspace layout table covering
every workspace member (sqlrite-engine root, sqlrite-ffi, sqlrite-
ask, sqlrite-mcp, the four SDKs, desktop) with what each does;
refreshed the engine module map to include connection.rs, ask/,
hnsw.rs, json.rs (all Phase 7 additions); rewrote the stale "What's
deliberately missing" section (transactions/locks/concurrency now
shipped — flipped to the actually-still-missing list: optimizer
beyond eq-probe, joins, aggregates, network layer, streaming
cursor).
- **docs/supported-sql.md** — added an HNSW indexes subsection under
CREATE INDEX with the `USING hnsw` syntax + the recall@10 ≥ 0.95
default + a note that brute-force still works without the index.
- **docs/smoke-test.md** — dropped the stale "123 tests pass" pin;
added a one-line smoke step for `cargo run --bin sqlrite-mcp -- --help`
to catch regressions in the stdio_redirect dance; updated the
"unsupported format version" note (3 → 4, since 7a bumped it);
dropped the `0.1.0` REPL banner literal.
- **docs/getting-started.md** — refreshed the repo-tree map to
include sqlrite-ffi/, sqlrite-ask/, sqlrite-mcp/, sdk/{python,
nodejs,go,wasm}/, examples/, scripts/, plus the new engine
modules (connection.rs, ask/, hnsw.rs, json.rs); dropped the
`0.1.0` REPL banner literal.
- **docs/usage.md** — flipped the future-tense "SDKs land in Phases
5b – 5g" to past tense; added MCP cross-ref.
- **docs/desktop.md** — rewrote the "see Roadmap Phase 5" cursor-
API line to point specifically at the deferred 5a.2.
- **sdk/{python,nodejs,go,wasm}/README.md** — added a "Sibling
products" subsection to each pointing at sqlrite-mcp with the
"your code vs LLM agent" framing.
- **sqlrite-ask/README.md** — NEW. The crate had no README, which
means the crates.io page would render only the Cargo.toml
description. Now: install snippet, "most users want the engine's
ask feature instead", configuration env-var table, features table,
architecture notes, sibling-products list. Cargo.toml gets the
matching `readme = "README.md"` field plus keywords + categories
for crates.io discoverability.
- **examples/README.md** — added an MCP row to the "Languages"
table pointing at docs/mcp.md (no examples/mcp/ subdir — the
doc covers the wiring directly, lower friction than maintaining
parallel quickstart files).
No code changes; no new tests. Existing test suite still passes
(workspace builds clean, `cargo test --workspace` minus the SDKs
that need their own runners shows ~340 tests passing across the
engine + sqlrite-mcp + sqlrite-ask + sqlrite-ffi).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.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
Pre-release documentation audit ahead of v0.1.25 (which ships
sqlrite-mcpto crates.io for the first time). Two themes:sqlrite-mcpwas only mentioned in its own README + the newdocs/mcp.md. Anyone landing on the root README, an SDK README, ordocs/embedding.mdhad no idea it existed. Added a one-line "Sibling products" cross-ref everywhere with the framing "use SDKs when YOUR code drives the DB; use MCP when an LLM AGENT drives it."What changed
README.md— flipped Phase 4 / Phase 7 status markers; added a full "MCP server" install section withcargo install sqlrite-mcp+ a Claude Code config snippet; rewrote the "Per-product wrappers ship in 7g.3-7g.8" claim into past tense including the MCPasktool; flipped the "examples for every language" checkbox; dropped the stale0.1.0REPL banner literal.docs/_index.md— refreshed Project state with Phase 7 achievements; flipped active frontier to Phase 8; bumped May 2026.docs/roadmap.md— added an "Active frontier (May 2026)" callout up top; dropped "(in progress)" from Phase 3 and Phase 4 headings.docs/phase-7-plan.md— flipped status to "complete except 7f"; rewrote "Next steps" as a retrospective.docs/embedding.md— Phase 5b-5g rewritten in past tense; added 7g + 7h bullets.docs/architecture.md— added a Workspace layout table covering every crate (engine, ffi, ask, mcp, four SDKs, desktop); refreshed the engine module map (connection.rs,ask/,hnsw.rs,json.rs); rewrote the stale "What's deliberately missing" section.docs/supported-sql.md— added an HNSW indexes subsection under CREATE INDEX with theUSING hnswsyntax + recall@10 default.docs/smoke-test.md— dropped stale "123 tests pass" pin; added acargo run --bin sqlrite-mcp -- --helpsmoke step (catches stdio_redirect regressions); updated format-version note (3 → 4).docs/getting-started.md— refreshed repo-tree map to include all current workspace dirs + new engine modules; dropped0.1.0literal.docs/usage.md+docs/desktop.md— small tense fixes; MCP cross-ref.sdk/{python,nodejs,go,wasm}/README.md— added "Sibling products" cross-refs tosqlrite-mcp.sqlrite-ask/README.md— NEW. The crate had no README; crates.io would render only the Cargo.toml description. Now has install snippet, "most users want the engine'saskfeature instead", env-var config table, features, architecture notes, sibling products.Cargo.tomlgetsreadme+keywords+categoriesfields for crates.io discoverability.examples/README.md— added an MCP row pointing atdocs/mcp.md.No code changes. No new tests.
Test plan
cargo build --workspacecleancargo test --workspace --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-desktop— all green (~340 tests across engine + sqlrite-mcp + sqlrite-ask + sqlrite-ffi)sqlrite-ask/README.mdwill render as expected once published to crates.io (no broken inline links)Out of scope (intentional)
The audit also flagged some deeper rewrites that I left for follow-up PRs because they're architectural rather than just stale-text:
docs/storage-model.md— the upper sections still describe the pre-Phase-3e per-ColumnIndexshape. Needs a real rewrite, not a touch-up.docs/pager.md— the "Staging writes" code sample uses the pre-3c bincode-blob path. Same.docs/sql-engine.md— dispatcher table doesn't include transaction statements; no mention of CreateIndex, JSON funcs, or vec funcs.docs/design-decisions.md— stops at Phase 6; doesn't capture the Phase 7 architectural choices (sqlrite-ask split + dep-direction flip; MCP stdio fd-redirect trick).These would be a separate "internals doc refresh" PR — not blocking the release.
🤖 Generated with Claude Code