Refactor docs from test-harness tour to system-architecture tour#7
Merged
Merged
Conversation
Reframe the HTML docs around how the index engine is *constructed* rather than around the test suite's file/step layout, using the test suite as ground truth for every claim. - Rename docs/test-harness-tour.html -> docs/architecture.html. - Organize by system architecture: the governing equation (index = projection of Markdown ∪ log), the three storage tiers, the crate/module layout, the substrate bet, the schema, then the data flows (ingest, notes/write discipline, chunks/links/graph, relation vocabulary, embedder seam, hybrid retrieval, suggestion lifecycle, event log/replay, and the Vault/CLI adapter). - Each layer cites the specific tests that pin it as ground truth, plus a single "Grounded in the tests" section that maps every architectural property to its covering test file. - Bring the doc current with the built system: 3 crates (adds b2-embed's real candle-backed LocalEmbedder), 73 passing tests, rustc 1.96.0, and the fail-fast model-mismatch / open()-never- mutates-vectors behavior. - Update the README link to point at the new doc. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01265nrsLFg8VDWMrBXuUoba
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Free Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughReplaces ChangesArchitecture documentation swap
Estimated code review effort: 1 (Trivial) | ~5 minutes Sequence Diagram(s)Not applicable — this PR is a documentation-only change with no functional code flow. Poem
Note 🎁 Summarized by CodeRabbit FreeThe PR author is not assigned a seat. To perform a comprehensive line-by-line review, please assign a seat to the pull request author through the subscription management page by visiting https://app.coderabbit.ai/login. Comment |
samkeen
added a commit
that referenced
this pull request
Jul 13, 2026
… & graph) Four decisions locked ahead of their slices (research §9b #7–#10): - chunk/centroid DDL = one-of nullable FKs on the single chunks table + a sibling resource_centroids table (CASCADE intact; FTS/embeddings keep one rowid space) - similar/doc-ref anchors dispatch by extension (.md/b2id → note, else resource) — the §3 classification doctrine, one rule everywhere - "unlinked" for a resource anchor = the same 1-hop exclusion, direction-agnostic (inbound-only by construction) - façade grows list_resources; list_notes untouched Stage B: specs/resources-inventory-graph.md — the slice-1 build spec (v4 schema: resources table + edges dst_resource_path/embed/caption; generalized walk with (size,mtime)-gated blake3 hashing and pruning; parser forms with caption capture; doc_kind dispatch helper; explain/mv over resources; desktop tree + fallback card + opener; watcher allowlist→denylist inversion). tasks.md points at it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
4 tasks
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
2 participants
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.
Reframe the HTML docs around how the index engine is constructed
rather than around the test suite's file/step layout, using the test
suite as ground truth for every claim.
(index = projection of Markdown ∪ log), the three storage tiers,
the crate/module layout, the substrate bet, the schema, then the
data flows (ingest, notes/write discipline, chunks/links/graph,
relation vocabulary, embedder seam, hybrid retrieval, suggestion
lifecycle, event log/replay, and the Vault/CLI adapter).
plus a single "Grounded in the tests" section that maps every
architectural property to its covering test file.
b2-embed's real candle-backed LocalEmbedder), 73 passing tests,
rustc 1.96.0, and the fail-fast model-mismatch / open()-never-
mutates-vectors behavior.
Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01265nrsLFg8VDWMrBXuUoba
Summary by CodeRabbit