Problem
An agent must understand a document before it writes to one. docs.plus has no route that returns a containing outline, and the caller cannot derive one from the route that looks closest.
apps/hocuspocus.server/API.md:243 states the rule a caller needs: "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." The same line ends: "Compute it from a GET; the server has no section concept."
The changes route reports a different tree, and on purpose. apps/hocuspocus.server/API.md:774 states it: "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 segmentSections JSDoc gives the same reason.
So the two rules are correct for two different jobs, and neither is the caller's outline. GET /api/documents/:documentId/changes?scope=headings also returns sections: [] whenever no comparison ran, so it is empty for a document nobody has edited since a baseline.
A caller that mistakes the changes tree for an outline gets parents that do not contain their children. Nothing reports an error, so every later step works on a wrong picture.
What to do
Write getOutline as a pure function over GET /api/documents/:documentId/content?format=json, using the containing rule at API.md:243.
Do not change the changes module. Its non-containing tree is deliberate and documented.
Acceptance
Notes
Size is the second reason to derive an outline. The largest measured document is 284,028 bytes of JSON, while its outline is about 6,579 bytes.
Related: #163 asks which address a content API caller uses to name a node. That ruling may later promote one shared section helper. This issue does not wait on it, because the caller-side rule is already written down.
Ordered after #223, but not blocked by it. It can start in parallel.
Problem
An agent must understand a document before it writes to one. docs.plus has no route that returns a containing outline, and the caller cannot derive one from the route that looks closest.
apps/hocuspocus.server/API.md:243states the rule a caller needs: "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." The same line ends: "Compute it from aGET; the server has no section concept."The changes route reports a different tree, and on purpose.
apps/hocuspocus.server/API.md:774states it: "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." ThesegmentSectionsJSDoc gives the same reason.So the two rules are correct for two different jobs, and neither is the caller's outline.
GET /api/documents/:documentId/changes?scope=headingsalso returnssections: []whenever no comparison ran, so it is empty for a document nobody has edited since a baseline.A caller that mistakes the changes tree for an outline gets parents that do not contain their children. Nothing reports an error, so every later step works on a wrong picture.
What to do
Write
getOutlineas a pure function overGET /api/documents/:documentId/content?format=json, using the containing rule atAPI.md:243.Do not change the changes module. Its non-containing tree is deliberate and documented.
Acceptance
getOutlinereturns the heading tree of a known document, and every parent node contains its own children.Notes
Size is the second reason to derive an outline. The largest measured document is 284,028 bytes of JSON, while its outline is about 6,579 bytes.
Related: #163 asks which address a content API caller uses to name a node. That ruling may later promote one shared section helper. This issue does not wait on it, because the caller-side rule is already written down.
Ordered after #223, but not blocked by it. It can start in parallel.