docs, skills: realign the pages changed since the last audit with doc-cascade and doc-prose #475

Merged

natsukium merged 1 commit from docs/skill-audit into main 2026-09-26 09:46:39 +09:00

Conversation 0 Commits 1 Files changed 26 +173 -246

natsukium commented 2026-09-26 09:37:55 +09:00

Owner

Copy link

About thirty PRs have edited the docs since the last tree-wide audit (#395), and they let back in the drift that the doc-cascade and doc-prose skills are meant to prevent. This PR re-audits the pages those PRs touched and fixes them.

Pages that contradicted the code

• A full window send queue re-dials; the page said it closes the window.
• The glyph populate walk covers only marked rows, not the full grid.
• Scrollback ships Scrolled, not a ScrollOp message.
• A client on a locked display retries on a backoff timer; the page said it spins.
• Hinting is on everywhere except macOS; the sentence was garbled.
• REQ-915: the session cap is a compiled-in 256, not a configured number.
• REQ-1006: the texture size wording now matches the page it cites (min(8192, adapter_limit)).
• The extend-ipc skill named a STREAMING_OPERATIONS constant that does not exist.
• The bidi-override discard rule in security-model.md now points to grid-and-cells.md, which lists every exemption.

One owner per fact

• Explanation ipc.md repeated facts that reference ipc.md and security-model.md "Daemon IPC" already own: the wrapper naming, the semantic-validation list, the bind rule and the startup lock. Reference ipc.md carried rationale the explanation page already argues. Each fact now lives in one place, and the other page links to it.
• REQ-009d now also cites security-model.md "Daemon IPC".
• AGENTS.md cites workspace.md for the crate graph and cli.md for the verb list instead of keeping copies. Please check this one: revert it if the graph should stay on the page every session loads.

Cleanup

• Removed links to felis issues from the docs and agent skills, including the "Open work is tracked in" line in the support matrix.
• Rewrote past-tense narration ("again", "still", "no longer", "since issue #27") in the present tense.
• Removed three sections that only repeated links: the keyboard how-to's "See also", overview.md's "Reading order", and the trailing "See …" line in security-model.md.

Verification

• just prose-check reports 0 hits.
• The pre-commit hooks pass (treefmt, lychee, skill frontmatter).
• A link check that also verifies #anchors across docs/, the skills, AGENTS.md, README.md and CONTRIBUTING.md found nothing broken.
• Every REQ row in spec.md cites a page and heading that exist.

Not changed in this PR

• Three performance figures have no source: pipeline.md "~150 KB/s, <1% CPU", text-shaping.md "~110× cheaper", and implementation.md "benchmarks show".
• Two passages state planned work: text-shaping.md "A true LRU is future work" and grid-and-cells.md "deferred".
• Reference ipc.md keeps about five one-clause bits of rationale.
• README.md still links the Forgejo issue tracker as a whole, not the GitHub mirror.

About thirty PRs have edited the docs since the last tree-wide audit (#395), and they let back in the drift that the doc-cascade and doc-prose skills are meant to prevent. This PR re-audits the pages those PRs touched and fixes them. ## Pages that contradicted the code - A full window send queue re-dials; the page said it closes the window. - The glyph populate walk covers only marked rows, not the full grid. - Scrollback ships `Scrolled`, not a `ScrollOp` message. - A client on a locked display retries on a backoff timer; the page said it spins. - Hinting is on everywhere except macOS; the sentence was garbled. - REQ-915: the session cap is a compiled-in 256, not a configured number. - REQ-1006: the texture size wording now matches the page it cites (`min(8192, adapter_limit)`). - The extend-ipc skill named a `STREAMING_OPERATIONS` constant that does not exist. - The bidi-override discard rule in security-model.md now points to grid-and-cells.md, which lists every exemption. ## One owner per fact - Explanation ipc.md repeated facts that reference ipc.md and security-model.md "Daemon IPC" already own: the wrapper naming, the semantic-validation list, the bind rule and the startup lock. Reference ipc.md carried rationale the explanation page already argues. Each fact now lives in one place, and the other page links to it. - REQ-009d now also cites security-model.md "Daemon IPC". - AGENTS.md cites workspace.md for the crate graph and cli.md for the verb list instead of keeping copies. **Please check this one**: revert it if the graph should stay on the page every session loads. ## Cleanup - Removed links to felis issues from the docs and agent skills, including the "Open work is tracked in" line in the support matrix. - Rewrote past-tense narration ("again", "still", "no longer", "since issue #27") in the present tense. - Removed three sections that only repeated links: the keyboard how-to's "See also", overview.md's "Reading order", and the trailing "See …" line in security-model.md. ## Verification - `just prose-check` reports 0 hits. - The pre-commit hooks pass (treefmt, lychee, skill frontmatter). - A link check that also verifies `#anchors` across docs/, the skills, AGENTS.md, README.md and CONTRIBUTING.md found nothing broken. - Every REQ row in spec.md cites a page and heading that exist. ## Not changed in this PR - Three performance figures have no source: pipeline.md "~150 KB/s, <1% CPU", text-shaping.md "~110× cheaper", and implementation.md "benchmarks show". - Two passages state planned work: text-shaping.md "A true LRU is future work" and grid-and-cells.md "deferred". - Reference ipc.md keeps about five one-clause bits of rationale. - README.md still links the Forgejo issue tracker as a whole, not the GitHub mirror.

natsukium added 1 commit 2026-09-26 09:37:55 +09:00

docs, skills: realign the pages changed since the last audit with doc-cascade and doc-prose ... bd82423c4e

About thirty PRs have edited the docs since the last tree-wide audit, and they reintroduced the drift the skills exist to
stop.

Some pages contradicted the code:
- a full window send queue re-dials; the page said it closes the window
- the glyph populate walk covers only marked rows, not the full grid
- scrollback ships `Scrolled`, not a `ScrollOp` message
- the locked-display client retries on a backoff timer, not in a spin
- hinting is on everywhere except macOS
- the session cap is a compiled-in 256, not a config knob
- the extend-ipc skill named a `STREAMING_OPERATIONS` constant that does not exist

Explanation ipc.md retold facts that reference ipc.md and security-model.md "Daemon IPC" own: the wrapper naming, the
semantic-validation list, the bind rule and the startup lock. Reference ipc.md carried rationale the explanation page
already argues. Each is now kept in one place, with a link from the other. REQ-009d also cites security-model.md,
which now carries the lock argument alone.

Links to felis issues, including the "open work is tracked in" line, are gone from the docs and agent skills. So is
past-tense narration ("again", "still", "no longer", "since issue #27"). The same applies to trailing See-also sections
and the overview's Reading order section, whose links docs/README.md already carries. AGENTS.md now cites
workspace.md for the crate graph instead of keeping a second copy that drifts.

Assisted-by: Claude Code:Opus 5.5

natsukium scheduled this pull request to auto merge when all checks succeed 2026-09-26 09:45:56 +09:00

natsukium merged commit 38496f310e into main 2026-09-26 09:46:39 +09:00

natsukium deleted branch docs/skill-audit 2026-09-26 09:46:40 +09:00

natsukium referenced this pull request from a commit 2026-09-26 09:46:40 +09:00

docs, skills: realign the pages changed since the last audit with doc-cascade and doc-prose (#475)

Commenting is not possible because the repository is archived.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

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

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

natsukium/felis!475

No description provided.