Skip to content

docs: align repository guidance with the code it describes - #170

Merged
Azganoth merged 7 commits into
mainfrom
docs/align-guidance-with-repo
Aug 3, 2026
Merged

docs: align repository guidance with the code it describes#170
Azganoth merged 7 commits into
mainfrom
docs/align-guidance-with-repo

Conversation

@Azganoth

@Azganoth Azganoth commented Aug 3, 2026

Copy link
Copy Markdown
Owner

Summary

AGENTS.md, CONTRIBUTING.md, and docs/ had drifted from the code they
describe, and two conventions the code follows uniformly were written down
nowhere.

Documentation that no longer matched the code

  • patterns.md taught the hand-written SETTINGS_PERSISTED_KEYS array as the
    persisted-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 pointing
    at a pattern with no remaining instance in src/, and at the defect the
    decision record exists to prevent: satisfies PersistedTauriStoreKey<State>[]
    checked that each listed key was valid, never that every field was listed.
  • architecture.md listed four leaf features; oxlint.config.ts enforces five.
    diagnostics was missing from the paragraph that asks for the two to be kept
    in step, and plugins/ from the subdirectory list.
  • src/AGENTS.md advertised types/ as a standard feature subdirectory, which
    no feature has and which the next rule restricts to an exception, while
    omitting services/ (five features) and plugins/ (fifteen modules).
  • patterns.md named three of the five directories under src/test/, and
    called factories/ fixtures while a separate fixtures/ directory holds the
    literal sample data.

Guidance moved to where it is read

  • Rust import grouping moves from the contribution guide's command reference to
    src-tauri/AGENTS.md. Nothing enforces it, since the rustfmt options are
    nightly-only, so it is applied by hand on every Rust edit.
  • src-tauri/AGENTS.md gains a route into patterns.md, whose Tauri Boundaries
    section carries backend-side rules and had none. src/AGENTS.md gains routes
    into 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.
  • The documentation no longer routes readers to the AGENTS.md files, which
    agents load directly.

Conventions nothing stated or enforced

  • Command payload structs carry #[serde(rename_all = "camelCase")] and
    boundary errors carry #[serde(tag = "kind", ...)], across 23 and 11
    declarations 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.
  • All 50 reactive store reads select one field and all 223 non-reactive reads go
    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_blocking rules are
reworded to match what the code does.

Related Issue

Not applicable.

Verification

pnpm exec oxfmt --check passes on all six files. Documentation-only with no
executable configuration touched, so no application suite, per the
documentation-only rule in CONTRIBUTING.md and AGENTS.md.

  • All six patterns.md anchors referenced from the two AGENTS.md files
    resolve to real headings, as do both new decisions.md links.
  • The leaf feature list matches oxlint.config.ts exactly.
  • No *_PERSISTED_KEYS constant remains in src/. The surviving
    PersistedTauriStoreKey<State>[] mention is deliberate, describing the removed
    pattern to explain the defect.

No changelog entry. Nothing here changes user-facing behavior.

Notes

Shared Foundations is a new section holding the path and error-handling
pointers. It and Resource Lifecycles are arguably one category under two
headings, and merging them is a reasonable review outcome.

Deliberate omissions:

  • The nested deep-merge constraint stays a consequence in decisions.md rather
    than becoming a pattern. No nested setting exists, and documenting it in
    patterns.md would repeat the types/ mistake fixed here.
  • File naming, backend logging, and mutex poisoning stay undocumented. Naming is
    uniform across ~150 files and recoverable from any sibling; the other two have
    nine call sites and one.

oxlint.config.ts still restricts @/components/dialogs, a directory removed in
449cf405. architecture.md was corrected for this in e3bb86ab and the config
was not, so it carries a dead boundary root, the mirror image of the
diagnostics drift fixed here and a breach of the same invariant. Left out as it
is not a documentation change.

src/AGENTS.md line 20, the Radix exception in Focus Visibility, and the Radix
mention in Keyboard Traversal are three coupled lines that go stale together if
the Base UI spike in #167 lands.

…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
Azganoth enabled auto-merge (squash) August 3, 2026 07:20
@Azganoth Azganoth self-assigned this Aug 3, 2026
@Azganoth Azganoth added the Maintenance Chore, refactor, dependency, or test work without user-facing change label Aug 3, 2026
@Azganoth
Azganoth merged commit 8243130 into main Aug 3, 2026
2 checks passed
@Azganoth
Azganoth deleted the docs/align-guidance-with-repo branch August 3, 2026 07:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Maintenance Chore, refactor, dependency, or test work without user-facing change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant