docs: give each decision in the dense pages its own section #485

Merged

natsukium merged 13 commits from docs/restructure-dense-pages into main 2026-09-26 12:49:27 +09:00

Conversation 0 Commits 13 Files changed 18 +3495 -2304

natsukium commented 2026-09-26 11:11:52 +09:00

Owner

Copy link

Eleven pages were walls of 200–600-word bold-lead bullets or paragraphs under few headings; this gives each decision its own section, leads each with what was chosen and why, splits paragraphs to one point each, and puts rejected alternatives and Revisit if triggers where a reader can find them. Content is preserved (each fixer diffed links, REQ ids and numbers against the original; nothing removed as Trap 1).

Page	Headings	Largest block (words)
explanation/benchmarks.md	1 → 20	618 → 89
explanation/testing.md	9 → 14	212 → 122
explanation/input.md	21 → 33	239 → 146
explanation/architecture/control-surfaces.md	9 → 76	~430 → ~133
explanation/architecture/overview.md	24 → 33	302 → ~141
explanation/security-model.md	13 → 50	331 → 107
explanation/rendering/pipeline.md	18 → 40	286 → 137
explanation/architecture/session-lifecycle.md	26 → 48	319 → 141
explanation/architecture/ipc.md	36 → 77	287 → 157
explanation/rendering/text-shaping.md	10 → 10	344 → 157
reference/ipc.md (reference style: paragraph splits and lists only)	38 → 38	340 → 149

Existing headings keep their text, so inbound anchors resolve (fragment-aware check over docs/, README, CONTRIBUTING, AGENTS, skills: 0 broken). The last commit points links that cited a whole control-surfaces group (REQ-006a, the tags non-goal, retarget landing, pipe and switch asymmetries, extend-ipc) at the specific new section.

Two integration commits retarget links and citations at the new sections: control-surfaces links (REQ-006a, the tags non-goal, retarget landing, pipe/switch asymmetries, extend-ipc), the ResourceReport scope link, and two Rust doc comments (exit_ladder.rs now cites "The exit ladder"; serve.rs's 5 s grace cited "Destruction" but lives under "Post-exit reaping").

Conflicts textually with #477 in explanation/testing.md; whichever merges second takes the other's structure.

Eleven pages were walls of 200–600-word bold-lead bullets or paragraphs under few headings; this gives each decision its own section, leads each with what was chosen and why, splits paragraphs to one point each, and puts rejected alternatives and _Revisit if_ triggers where a reader can find them. Content is preserved (each fixer diffed links, REQ ids and numbers against the original; nothing removed as Trap 1). | Page | Headings | Largest block (words) | |---|---|---| | explanation/benchmarks.md | 1 → 20 | 618 → 89 | | explanation/testing.md | 9 → 14 | 212 → 122 | | explanation/input.md | 21 → 33 | 239 → 146 | | explanation/architecture/control-surfaces.md | 9 → 76 | ~430 → ~133 | | explanation/architecture/overview.md | 24 → 33 | 302 → ~141 | | explanation/security-model.md | 13 → 50 | 331 → 107 | | explanation/rendering/pipeline.md | 18 → 40 | 286 → 137 | | explanation/architecture/session-lifecycle.md | 26 → 48 | 319 → 141 | | explanation/architecture/ipc.md | 36 → 77 | 287 → 157 | | explanation/rendering/text-shaping.md | 10 → 10 | 344 → 157 | | reference/ipc.md (reference style: paragraph splits and lists only) | 38 → 38 | 340 → 149 | Existing headings keep their text, so inbound anchors resolve (fragment-aware check over docs/, README, CONTRIBUTING, AGENTS, skills: 0 broken). The last commit points links that cited a whole control-surfaces group (REQ-006a, the tags non-goal, retarget landing, pipe and switch asymmetries, extend-ipc) at the specific new section. Two integration commits retarget links and citations at the new sections: control-surfaces links (REQ-006a, the tags non-goal, retarget landing, pipe/switch asymmetries, extend-ipc), the ResourceReport scope link, and two Rust doc comments (`exit_ladder.rs` now cites "The exit ladder"; `serve.rs`'s 5 s grace cited "Destruction" but lives under "Post-exit reaping"). Conflicts textually with #477 in `explanation/testing.md`; whichever merges second takes the other's structure.

natsukium added 8 commits 2026-09-26 11:11:52 +09:00

docs: give each benchmark-harness decision its own section ... 5fc6670cdf

The page was one heading over a list of 100-600-word bullets, each packing
a decision, its mechanism, calibration numbers, rejected alternatives and
a Revisit-if trigger into one block, so a reader could neither find a
decision by heading nor see where its argument ended. Each decision now
has a heading that states it, leads with the choice, gives rejected
alternatives and the trigger their own paragraphs, and the decisions are
grouped by the question they answer. The content is unchanged.

Assisted-by: Claude Code

docs: split the testing strategy's gate consequences into sections ... 102aaa3f8a

The support-claim section ran four decisions through one bullet list, the
longest over 200 words, and the shell-overlay rationale was a single
250-word paragraph, so neither could be scanned or linked by decision.
Each consequence now has its own heading that leads with the choice,
rejected alternatives are listed, and each Revisit-if trigger closes its
section. The content is unchanged.

Assisted-by: Claude Code

docs: break the input page's long action and gesture blocks into sections ... ae1547fb5b

Action mapping, mouse momentum, selection and the link preview each ran
several decisions through 200-300-word paragraphs or bullets with their
rejected alternatives and Revisit-if triggers embedded mid-block, so a
reader could not find one decision or see where its argument ended. Each
action and decision now has its own heading that leads with the choice,
rejections are listed, and triggers close their sections. Existing
headings keep their text so inbound anchors and quoted section names
still resolve. The content is unchanged.

Assisted-by: Claude Code

docs: give each control-surface decision its own section ... 34ba01b6d2

The page ran to nearly 12,000 words under nine headings, with "Shared
conventions", "Configuration architecture" and "Deliberate asymmetries"
written as runs of 200-500-word bold-lead bullets that each packed a
decision, its mechanism, the rejected alternatives and a revisit trigger
into one block. A reader could neither find a decision by heading nor see
where its argument ended.

Each decision now has its own heading, grouped under the existing
second-level sections so their anchors keep resolving; rejected
alternatives become short lists and each revisit trigger closes its
section. The content is unchanged.

Assisted-by: Claude Code

docs: split the architecture overview's wire-knowledge bullets into sections ... 67c136f827

"Shared wire knowledge across the satellite clients" held four 200-400-word
bullets, and "Where an auto-spawned daemon lands" buried two revisit
triggers mid-paragraph, so neither could be scanned for the decision it
records. Each adopt/reject decision now has its own heading, rejected
designs are listed, and revisit triggers close their sections. Existing
headings and anchors are unchanged, and no content is dropped.

Assisted-by: Claude Code

docs: give each security-model rule its own section ... cc11883f91

The injection, Kitty graphics, Daemon IPC, text-rendering, OSC 8 and
process-boundary sections were runs of 150-330-word bold-lead bullets,
each packing a rule, its mechanism, rejected alternatives and a revisit
trigger into one block, so a reader could neither find a rule by heading
nor see where its argument ended. Each long rule is now a heading of its
own with the decision first, rejected alternatives and revisit triggers
in separate paragraphs, and Daemon IPC groups its seventeen rules under
four subheadings. The top-level headings, which spec.md and other pages
link to, are unchanged; no fact, citation or REQ reference was dropped.

Assisted-by: Claude Code

docs: split the render pipeline's long sections by decision ... 032246957d

"wgpu surface and resources" and "Demand-driven emission" ran to
thousands of words under one heading each, with paragraphs up to 290
words that mixed a decision, its measurements and its rejected
alternatives, and revisit triggers sat mid-section. Each decision now
has its own subheading that leads with the choice, measurements and
rejections get their own paragraphs, and every revisit trigger closes
its section. Existing headings, which spec.md and other pages link to,
are unchanged; no fact, number or citation was dropped.

Assisted-by: Claude Code

docs, skills: point cross-page links at the new control-surfaces sections ... 80f1425fe5

The control-surfaces restructure turned its "Shared conventions" and
"Deliberate asymmetries" bullet runs into named sections. The links
that cited the whole group for one of its rules (REQ-006a, the tags
non-goal, the retarget-landing policy, the pipe and switch asymmetries,
extend-ipc's --format pointer) now land on that rule.

Assisted-by: Claude Code

natsukium referenced this pull request 2026-09-26 11:18:01 +09:00

ci: push to the niks3 cache at build time through one composite action #477

natsukium added 5 commits 2026-09-26 11:36:29 +09:00

docs: split the text-shaping symbol-fallback block into one point per paragraph ... 719634b4f3

The symbol-group rationale in "Font fallback" was a single 344-word block
that argued the ordering, the first-cover sufficiency, the all-installed
rule, and cluster-level emoji presentation in one breath, so a reader could
not see where one argument ended. Each now has its own paragraph, and the
inline Revisit triggers stand as the last paragraph of their section.

Assisted-by: Claude Code

docs: give each session-lifecycle decision its own section ... 30c946e5a3

The page was a set of long sections whose paragraphs ran to 320 words and
packed a decision, its mechanism, its rejected alternatives and its Revisit
trigger into one block, so a reader could neither find a decision by heading
nor see where its argument ended. Creation, the child environment, the
presentation chain, the exit ladder and the chord pick now split into one
headed section per decision, rejected alternatives are listed where a
section rejects several, and each Revisit trigger closes its section.

Assisted-by: Claude Code

docs: give each IPC design decision its own section ... d352196e7d

The IPC design page carried its decisions as long runs of paragraphs
under a few headings, several over 180 words, with rejected
alternatives and Revisit triggers buried mid-paragraph, so a reader
could neither find a decision by heading nor see where its argument
ended. Each decision now has its own heading, paragraphs split at their
topic shifts, multiple rejected alternatives read as a list, and every
Revisit trigger closes its section. Existing heading text is unchanged,
so every inbound anchor still resolves.

Assisted-by: Claude Code

docs: split the IPC reference's run-on arm bullets and paragraphs ... b76f540b6b

The IPC reference packed whole arms (Attach, Refused, Stop, Scrolled,
Key) and several limit rules into single 150-340-word blocks, so a
reader looking up one refusal reason, one malformed image sequence or
one schema bound had to parse the whole block. Split them at their
topic shifts and turn the enumerations the prose already listed
(Refused reasons, ModeFlags fields, malformed image sequences, the
felis-json published bounds and decode-only checks, the two slot-closing
kinds) into lists. No fact changes and no heading is renamed, so every
inbound anchor still resolves.

Assisted-by: Claude Code

docs, client, daemon: point citations at the sections that now carry them ... bb2bc8975d

The session-lifecycle restructure gave the exit ladder its own section,
so exit_ladder.rs cites "The exit ladder" instead of the section about
telling the window the shell exited. serve.rs cited "Destruction" for
the 5 s post-exit grace, which the page states under "Post-exit
reaping". control-surfaces links the ResourceReport scope rationale to
the IPC page's new section on it rather than the whole typed-unions
rule.

Assisted-by: Claude Code

natsukium changed title from docs: give each decision in the dense explanation pages its own section to docs: give each decision in the dense pages its own section 2026-09-26 11:36:38 +09:00

natsukium scheduled this pull request to auto merge when all checks succeed 2026-09-26 12:19:57 +09:00

natsukium referenced this pull request from a commit 2026-09-26 12:23:57 +09:00

ci: push to the niks3 cache at build time through one composite action (#477)

natsukium force-pushed docs/restructure-dense-pages from bb2bc8975d to 7faad383de 2026-09-26 12:29:30 +09:00 Compare

natsukium merged commit 4865b37fb6 into main 2026-09-26 12:49:27 +09:00

natsukium deleted branch docs/restructure-dense-pages 2026-09-26 12:49:27 +09:00

natsukium referenced this pull request from a commit 2026-09-26 12:49:28 +09:00

docs: give each decision in the dense pages its own section (#485)

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!485

No description provided.