docs: give every fact one owning page and cut what restates it #289
No reviewers
Labels
No labels
priority/P0
priority/P1
priority/P2
release/v0.1.0
status/blocked
status/planned
type/bug
type/design
type/test-gap
type/tracker
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
natsukium/felis!289
Loading…
Reference in a new issue
No description provided.
Delete branch "docs/role-cleanup"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Tree-wide pass on
docs/for role and redundancy: each fact now has one owning page (reference owns facts, explanation owns decisions with their rejected alternatives and revisit triggers), and text that restated another page, narrated history, opened on its audience, or trailed off into link lists is gone. Closes #242.What changed
explanation/protocols/landscape.mdis now "Protocol admission decisions" (263 → 80 lines). The support-matrix legend is the one status vocabulary (⚠️ = consumed without effect, 🚫 = reaches no implementation), with rows added for every verdict the landscape tables alone carried (?12,OSC 6, XTSETTCAP, legacyDCS = 1 s, 8-bit C1, SS2/SS3, PM/SOS, HVP, IND/NEL, VT500 page memory, NRCS, DECDLD, an APC table, mintty/mosh images). The OSC 66 key table moved to its reference page.reference/cli.md; the registry caps have a row in "Semantic limits"; the RegionReplybullet now states the trim the daemon applies (the refusal it described was never implemented).overview.md; the pipe/run action design lives ininput.md; the session-spawn environment design moved from the security model intosession-lifecycle.md"Creation"; the transient unit's properties and theKillUserProcesseslogout condition are stated inreference/cli.md"Auto-spawning".design.mdowns the boundary argument once;vision.md,comparison.md,feature-baseline.mdandnon-goals.mdstop re-deriving it;input.mdandsecurity-model.mdeach own one half of the link-preview decision.cli.mdfor verb facts; README points at the pages instead of replaying them.implementation.mdkeeps its decisions and drops the sourced catalog; the publication gate has one owner; mutation testing is documented; AGENTS.md and CONTRIBUTING.md citeCargo.tomlfor MSRV/edition/lint values instead of restating them.docs/too" (with the AGENTS.md guardrail and README summary exceptions) and the page-mechanics rules this pass established (subject opener, nodescription:, no pointer-only tails); section-number citations became heading citations;add-escape-sequenceandimplement-featuresend the verdict lookup to the support matrix.#anchorand every by-namepage "Section"citation indocs/andcrates/comments was checked against the target headings; 80 stale by-name citations (76 pre-dating this branch) and 3 pre-existing broken links are fixed.Verification
just checkgreen;just prose-check origin/main...HEAD0 hits;just skill-check;cargo nextest run -p felis-workspace-tests(doc index + internal links) green; a fragment-aware anchor checker reports 0 broken links; five independent review rounds (pi sol ×5, luna ×2; the last verdict PASS) with every blocker resolved from the Rust source, plus a systematic pass over the 175 requirement rows that cite a changed page (27 citations retargeted, 9 clauses restored). Two daemon/bridge timing tests flaked once each under a saturated host while the CI runner compiled another job; both pass 3/3 in isolation and the crate diff is comments only.Not in this PR
CHANGELOG.md's released[0.1.0]section says apipechord over an oversized scrollback "fails with a message naming the size"; the daemon has trimmed instead since 2026-09-04. Editing a released section is a maintainer call.explanation/architecture/ipc.md"Open extensibility considerations" has no issue yet; a ready body is in the session notes.0pixel stub 7e586f02c2?2048ordering promise lives in d5b0b8ec47A reference page's first sentence was an audience roll-call ("a reference for contributors, client implementers and tool authors specifying …") that told a reader looking up a wire fact nothing they did not already know from arriving on the page. Reference is declarative lookup material, so each page now starts with the thing it specifies. Assisted-by: Claude Code Assisted-by: Claude Code:Fable 5.1Seven sites described a rejected shape as the one felis used to have ("the choice this replaces", "the shape this replaces", "the one the code held until it was challenged", "the string it supersedes"), which dates the page and tells a reader nothing about why the alternative fails. Each now states the alternative and its cost in the present tense. The Windows config and doctor suites could not isolate a temp profile before --config existed; that is the flag's motivation, not a fact about the test suites, so the page states the standing constraint instead. Assisted-by: Claude Code Assisted-by: Claude Code:Fable 5.1Five headings on the IPC design page stated the section's verdict ("A claim is not a length", "Absence is the only thing a sentinel may mean", "Switch targets are typed, not implied"), so the table of contents spoiled every argument before the reader met it, and two read as aphorisms whose referent is clear only afterwards. Each now names the object it covers. The wire reference's links to the renamed anchors move with them. Assisted-by: Claude Code Assisted-by: Claude Code:Fable 5.1The codec spec argued a decoder policy inline ("rejecting it would turn another implementation's failure to coalesce into an interop break"), which is a rejected alternative and belongs with the codec's other rationale. The two reference pages also justified the soft-wrap bit's placement differently; the codec page owns the layout, so it owns the reason and the wire page states only where the bit rides. Assisted-by: Claude Code Assisted-by: Claude Code:Fable 5.1The enumeration covers the matrix's supported rows only, and a tolerated row cannot satisfy its assertion: the input is consumed and dropped, which is what the ⚠️ status means. Assisted-by: Claude Code:Fable 5.1The Region family's `Reply` bullet promised a `Conn::Error { InvalidRequest }` refusal for an over-budget region, while the semantic-limits row, REQ-105a and scrollback.md state the trim the daemon performs (`trim_region_reply` cuts to the youngest resumable boundary and returns no position). A reader looking up the wire behavior found the contract the code does not implement, and the pager-anchor pages promised an anchor that a trimmed reply cannot carry. Assisted-by: Claude Code:Fable 5.1