docs: _llm/ + AGENTS.md + doc audit (closes #193)#197
Merged
forkwright merged 3 commits intomainfrom Apr 19, 2026
Merged
Conversation
added 3 commits
April 18, 2026 20:54
Per kanon AGENT-DOCS.md, the 19-crate workspace needs on-demand AI context files separate from the always-loaded CLAUDE.md. _llm/ (3 files): - README.md: loading order + format rules - architecture.toml: 19 crates grouped by layer, dependency direction - decisions.toml: technology choices compressed from docs/ and Cargo.toml AGENTS.md (root, cross-tool): build/test/lint commands, non-obvious rules with WHY, where-to-add table, boundaries. 64 lines, within the 100-line target for the AGENTS.md standard. Per-crate CLAUDE.md files for all 19 crates deferred to a follow-up (too large for one pass). AGENTS.md flags this. kanon lint _llm AGENTS.md --summary: clean. Refs #193
Apply the 4-criterion inclusion filter and kanon's "no derivable metrics in docs" rule. Deleted: - docs/policy/git-history.md (22 lines): duplicated in CLAUDE.md and AGENTS.md; fails "not discoverable" and "broadly applicable". - docs/serving/quic-streaming.md (11 lines): stub pointing at a research file that does not exist in the repo. Phase 4 content will land with the implementation. Updated stale counts/references: - docs/PROJECT.md: drop hardcoded "15 workspace crates, 543 tests"; point to cargo metadata and _llm/architecture.toml instead. Also replace Tauri references with Dioxus (legacy Kotlin/Tauri sources were removed in a417c13). - docs/architecture/cargo.md: same treatment for the "All 17 crates" line and the stale mouseion/ tree entry (mouseion/ is gone from the repo tree). - docs/policy/versioning.md: fully rewrite; referenced legacy mouseion/akouo-web/akouo-android components that no longer exist. Now describes release-please + single workspace version. - docs/desktop/architecture.md: rewrite; described a Tauri/React frontend, actual implementation is Dioxus (theatron-desktop). - docs/lexicon.md, docs/architecture/binary-modes.md: Tauri -> Dioxus. - docs/README.md: remove dead links (gnomon.md, CLAUDE_CODE.md, roadmap/*, serving/opds.md, and five other serving/* placeholders that referenced files that do not exist). Add _llm/ pointer at the top so agents load the compressed view first. kanon lint on touched files: clean except one pre-existing WRITING/definitional-opening in architecture/binary-modes.md line 54 that predates this PR. Refs #193
Per kanon AGENT-DOCS.md: - Remove the embedded crates/ tree: file trees are discoverable via `ls crates/`, and the tree was also factually drifting (prostheke was listed as "mDNS service discovery" but actually does subtitle management; mDNS lives in paroche). - Remove the derivable-from-Cargo.toml inline crate descriptions (duplicated more accurately in _llm/architecture.toml). - Drop "No filler words" literal list: it triggered the WRITING/ai-trope lint on CLAUDE.md itself. Point at the lint rule instead. - Add cross-references to AGENTS.md and _llm/ so new agents load the right file for their task. - Keep under 100 lines (now 60). Preserve the 4-criterion-passing conventions (snafu, IDs, Aggelia, lint suppressions, cross-crate types) that are not discoverable from code or help commands. kanon lint CLAUDE.md --summary: clean. Refs #193
Contributor
|
Consider splitting into smaller PRs for easier review. Not a blocker, just a signal. |
6 tasks
forkwright
pushed a commit
that referenced
this pull request
Apr 19, 2026
Recovers 7 lint-cleanup commits that were pushed to the kanon forge but never propagated to GitHub main. Work from harmonia kanon lint cleanup arc (task #144), safely preserved on forge origin until now. Conflicts with #197's docs/architecture/cargo.md changes resolved to keep both sides' edits. # Conflicts: # docs/architecture/cargo.md
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
_llm/with README,architecture.toml(19 crates + layers),decisions.toml(tech choices compressed from docs/ and Cargo.toml). Follows kanonstandards/AGENT-DOCS.md.AGENTS.mdat repo root: build/test/lint commands, non-obvious rules with WHY, where-to-add table, boundaries. 64 lines, within the standard's 100-line max.CLAUDE.mdfrom 83 to 60 lines: drop duplicative crates/ tree (now in_llm/architecture.toml) and literal AI-trope word list (was tripping theWRITING/ai-tropelint on CLAUDE.md itself).docs/policy/git-history.md(22 lines, duplicated in CLAUDE.md/AGENTS.md).docs/serving/quic-streaming.md(11-line stub pointing at a research file that doesn't exist).docs/policy/versioning.md(referenced legacy mouseion/akouo-web/akouo-android components that were removed in a417c13).docs/desktop/architecture.md(described a Tauri/React frontend; actual is Dioxustheatron-desktop).docs/PROJECT.mddropped hardcoded15 workspace crates, 543 tests;docs/architecture/cargo.mddropped17 cratesand stalemouseion/tree entry.docs/PROJECT.md,docs/lexicon.md,docs/architecture/binary-modes.md.docs/README.mdto remove eight dead links (gnomon.md, CLAUDE_CODE.md, roadmap/, 6 planned serving/); add_llm/pointer at top.Deferred
CLAUDE.mdfiles for the 19 crates. Too large for one pass; tracked as issue docs: add _llm/ directory, AGENTS.md, and audit docs per kanon doc standards #193 follow-up.AGENTS.mdflags this._llm/(Aletheia-style). Deferred until per-crate CLAUDE.md exists to source from.WRITING/*lint violations in docs I didn't touch (30 total across download/, media/, serving/*, architecture/binary-modes.md:54). These predate this PR.Verification
kanon lint _llm --summary: clean.kanon lint AGENTS.md --summary: clean.kanon lint CLAUDE.md --summary: clean.kanon lint docs/PROJECT.md docs/README.md docs/desktop/architecture.md docs/policy/versioning.md docs/architecture/cargo.md docs/lexicon.md --summary: clean.cargo build/cargo testsurface unchanged.Branch is based on
mainat f8aa71e (latest tip at PR creation time).Closes #193