Problem
apps/hocuspocus.server/API.md uses the word "section" for two different rules, and both are correct.
API.md:243 is the caller-side rule: "A heading's section is the run of following root siblings, up to the next heading whose level is the same or smaller. Nested subsections fall inside it." It ends: "Compute it from a GET; the server has no section concept."
API.md:774 is the changes-route rule: "A section is one heading plus the top-level nodes up to the next heading of any level. So a section does not contain its subsections, and editing a child never marks its parent modified."
The second is deliberate. segmentSections carries the same reason in its JSDoc: a parent should not be marked modified when only a child changed.
One word, two meanings, one file. Two audit passes read the second as a defect before the code settled it.
What to do
Give each rule a distinct name, and say which surface uses it. Only the documentation changes; no behaviour moves.
Acceptance
Notes
Related to #163, which asks which address a content API caller uses to name a node. That ruling may later promote one shared helper. This issue does not wait on it — naming the two rules apart is worth doing either way, and it makes #163 easier to answer.
A session hook currently rejects edits to apps/hocuspocus.server/API.md. That blocks the work, not the decision.
Problem
apps/hocuspocus.server/API.mduses the word "section" for two different rules, and both are correct.API.md:243is the caller-side rule: "A heading's section is the run of following root siblings, up to the next heading whoselevelis the same or smaller. Nested subsections fall inside it." It ends: "Compute it from aGET; the server has no section concept."API.md:774is the changes-route rule: "A section is one heading plus the top-level nodes up to the next heading of any level. So a section does not contain its subsections, and editing a child never marks its parentmodified."The second is deliberate.
segmentSectionscarries the same reason in its JSDoc: a parent should not be marked modified when only a child changed.One word, two meanings, one file. Two audit passes read the second as a defect before the code settled it.
What to do
Give each rule a distinct name, and say which surface uses it. Only the documentation changes; no behaviour moves.
Acceptance
API.md.CONTEXT.mdcarries whichever name becomes the domain term.Notes
Related to #163, which asks which address a content API caller uses to name a node. That ruling may later promote one shared helper. This issue does not wait on it — naming the two rules apart is worth doing either way, and it makes #163 easier to answer.
A session hook currently rejects edits to
apps/hocuspocus.server/API.md. That blocks the work, not the decision.