docs: align repository guidance with the code it describes - #170
Merged
Conversation
…action The interface and arrow-function conventions stay stated outright rather than deferring to established local practice. The codebase measures 217 interface declarations against no type-alias props, and 950 arrow consts against 17 non-component function declarations, so a reader can be told the convention instead of sampling for it.
`types/` was listed as a standard feature subdirectory while no feature has one, and the rule that follows already restricts it to shared domain contracts without a clearer owner. `services/` and `plugins/` were absent despite five features and fifteen modules using them. The leaf feature list omitted `diagnostics`, which `oxlint.config.ts` enforces as one, in the paragraph that asks for the two to be kept in step.
The section still taught the hand-written `SETTINGS_PERSISTED_KEYS` array that was removed when persisted state moved onto derived contracts, so it pointed at a pattern with no remaining instance in the codebase and with the defect the decision record exists to prevent.
It sat under the contribution guide's command reference, which is not open at the moment an import is added. Nothing enforces the grouping, so it has to be applied by hand on every Rust edit.
Agents load the AGENTS.md files directly, so the documentation no longer routes readers to them. The test helper list named three of the five directories under `src/test/`, and called factories fixtures while a separate fixtures directory holds the literal sample data.
Every payload struct and every boundary error already carries these serde attributes, across 23 and 11 declarations with no exception, but clippy does not inspect them. A new command that omits one compiles, passes the backend checks, and ships snake_case keys the frontend never reads.
All 50 reactive store reads already select one field, and the 223 non-reactive reads all go through getState, but a no-selector call type-checks and passes the lint set while subscribing to every field. Path identity and error handling were the two patterns with no entry point from these instructions. Path comparison shipped a defect once, when canonicalized Windows paths broke folder-context identity.
Azganoth
enabled auto-merge (squash)
August 3, 2026 07:20
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.
Summary
AGENTS.md,CONTRIBUTING.md, anddocs/had drifted from the code theydescribe, and two conventions the code follows uniformly were written down
nowhere.
Documentation that no longer matched the code
patterns.mdtaught the hand-writtenSETTINGS_PERSISTED_KEYSarray as thepersisted-state pattern. chore: derive persisted state sanitizers from value contracts #157 replaced it with contracts derived from one
shape and updated
decisions.md, leaving the implementation guidance pointingat a pattern with no remaining instance in
src/, and at the defect thedecision record exists to prevent:
satisfies PersistedTauriStoreKey<State>[]checked that each listed key was valid, never that every field was listed.
architecture.mdlisted four leaf features;oxlint.config.tsenforces five.diagnosticswas missing from the paragraph that asks for the two to be keptin step, and
plugins/from the subdirectory list.src/AGENTS.mdadvertisedtypes/as a standard feature subdirectory, whichno feature has and which the next rule restricts to an exception, while
omitting
services/(five features) andplugins/(fifteen modules).patterns.mdnamed three of the five directories undersrc/test/, andcalled
factories/fixtures while a separatefixtures/directory holds theliteral sample data.
Guidance moved to where it is read
src-tauri/AGENTS.md. Nothing enforces it, since the rustfmt options arenightly-only, so it is applied by hand on every Rust edit.
src-tauri/AGENTS.mdgains a route intopatterns.md, whose Tauri Boundariessection carries backend-side rules and had none.
src/AGENTS.mdgains routesinto Path Identity and Error Handling, the two remaining patterns with no
entry point; path comparison shipped a defect in Canonicalized Windows paths break folder-context identity comparisons #146.
AGENTS.mdfiles, whichagents load directly.
Conventions nothing stated or enforced
#[serde(rename_all = "camelCase")]andboundary errors carry
#[serde(tag = "kind", ...)], across 23 and 11declarations with no exception. Clippy does not inspect serde attributes, so
an omission compiles, passes the backend checks, and ships snake_case keys the
frontend never reads.
through
getState, but a no-selector call type-checks, passes the lint set,and subscribes the component to every field.
Standing rules land alongside: not weakening the verification oracle to obtain
passing checks, backend filesystem side effects, and interaction and
accessibility, the last paired with a new Keyboard Traversal section so the rule
and its reasoning arrive together. The constants and
spawn_blockingrules arereworded to match what the code does.
Related Issue
Not applicable.
Verification
pnpm exec oxfmt --checkpasses on all six files. Documentation-only with noexecutable configuration touched, so no application suite, per the
documentation-only rule in
CONTRIBUTING.mdandAGENTS.md.patterns.mdanchors referenced from the twoAGENTS.mdfilesresolve to real headings, as do both new
decisions.mdlinks.oxlint.config.tsexactly.*_PERSISTED_KEYSconstant remains insrc/. The survivingPersistedTauriStoreKey<State>[]mention is deliberate, describing the removedpattern to explain the defect.
No changelog entry. Nothing here changes user-facing behavior.
Notes
Shared Foundationsis a new section holding the path and error-handlingpointers. It and
Resource Lifecyclesare arguably one category under twoheadings, and merging them is a reasonable review outcome.
Deliberate omissions:
decisions.mdratherthan becoming a pattern. No nested setting exists, and documenting it in
patterns.mdwould repeat thetypes/mistake fixed here.uniform across ~150 files and recoverable from any sibling; the other two have
nine call sites and one.
oxlint.config.tsstill restricts@/components/dialogs, a directory removed in449cf405.architecture.mdwas corrected for this ine3bb86aband the configwas not, so it carries a dead boundary root, the mirror image of the
diagnosticsdrift fixed here and a breach of the same invariant. Left out as itis not a documentation change.
src/AGENTS.mdline 20, the Radix exception in Focus Visibility, and the Radixmention in Keyboard Traversal are three coupled lines that go stale together if
the Base UI spike in #167 lands.