Repository navigation
Simplify the docs to the current approach and the key decisions - #263
Merged
Merged
Conversation
The docs had grown to about 40k words across 31 files, with the same rules restated in the invariants, the ADRs, both specs, the architecture map and the plain-language tour. They now run to about 12k words in 10 files, and each fact has one home. - invariants.md keeps every id (S1 to K1) and states each rule in a few lines. - decisions.md replaces ADRs/: nine decisions that are expensive to reverse, with the reason for each. ADR numbers stay as stable ids. The other thirteen records restated an invariant and are retired. - architecture.md absorbs index-engine.md and the mechanics from search-and-similarity.md: crates, the index, and the flows. - data-model.md is the on-disk contract only: notes, links, verbs, resources. - evals.md keeps the instruments, the gate, the rulings and the process rules (same numbers). - quickstart.md keeps the walkthrough, every command (adds `b2 why`) and every environment variable, and now explains the strength dots. - CLAUDE.md and the desktop CLAUDE.md are tightened, and gain the rules that keep the docs short: one home per fact, no history in docs, no section numbers in citations. Removed: ADRs/, docs/README.md, docs/index-engine.md, docs/search-and-similarity.md. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PgG847TLizZXGt5hVNqiKm
Comment-only, plus two label-file descriptions. No behaviour changes. - Citations of a retired decision record now name the invariant that carries it: ADR-0006 to M4, ADR-0007 to M2, ADR-0021 to C1, ADR-0016 to E5, ADR-0017 to K1, ADR-0009 to G1. ADR-0013 becomes evals.md, ADR-0020 folds into ADR-0005, and ADR-0008 and ADR-0022 become architecture.md. - index-engine.md becomes architecture.md. - Section numbers are dropped from doc citations. Several already pointed at the wrong section. - queries.json and similar.json: the description text loses its pointers to the removed doc. Labels and queries are untouched. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PgG847TLizZXGt5hVNqiKm
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
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.
The docs had grown to about 40k words across 31 files, with the same rules
restated in the invariants, the ADRs, both specs, the architecture map and
the plain-language tour. They now run to about 12k words in 10 files, and
each fact has one home.
lines.
with the reason for each. ADR numbers stay as stable ids. The other
thirteen records restated an invariant and are retired.
search-and-similarity.md: crates, the index, and the flows.
resources.
rules (same numbers).
b2 why) andevery environment variable, and now explains the strength dots.
keep the docs short: one home per fact, no history in docs, no section
numbers in citations.
Removed: ADRs/, docs/README.md, docs/index-engine.md,
docs/search-and-similarity.md.
Co-Authored-By: Claude noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01PgG847TLizZXGt5hVNqiKm