Support "embedding" of subitems at any level

[mindsocket]

To express an OST we currently support:

• a set of pages (nodes), each with a type and parent relationship (frontmatter)
• an "OST on a page" with conventions for defining a structure based on markdown content (headings, bullets, inline properties)

In theory these worlds could merge and the concepts for the latter could be supported in the former. That is, a goal page could include headings/lists for sub-goals and/or opportunities inline, just like in an OST structure. This allows for detailed pages where warranted, while not requiring it when there isn't as much detail. A really clear example of this would be to include the mission on a vision page instead of it being separate

Rough idea of how this could work:

• Extract the in-page extraction
• Support that in the readSpace code path - for each node, also look in the markdown for headings/bullets to add to the node list
• The parent property needs a reliable convention for referring to the title extracted from the content of a parent page.

Example:

new_vision.md (vision title is "new_vision" based on the filename)

type: vision

---

Blah blah vision stuff

## [type:: mission] Our mission in 2026

Blah blah mission stuff. 

Note that mission title is "Our mission in 2026" based on the inline property and title content

make_moneys.md (goal title is "make_moneys")

type: goal
parent: [[new_vision#[type mission] Our mission in 2026]]

---

Blah blah goal stuff

This goal's parent wikilink is a (hopefully valid) reference to the heading in the vision page, recognised as a mission node.
Alternatively, or in addition, we could explore supporting anchor markup.

In vision doc: ## [type:: mission] Our mission in 2026 ^mission
In goal doc: parent: [[new_vision#^mission]]

Type is still needed in this case for parsing. That is, unless we decide that a unique named anchor matching the named OSTNode types is allowed as an alternative expression. This would be not just for linking, but parsing OST-on-a-page-like (aka embedded) content too. This wouldn't work for multiples, like multiple embedded goals on a page, unless we extend the convention to allowing numbered anchors (eg ^goal1) or something. This feels like it's well worth trying. While inline [type:: blah] is ok, I don't love it. We can keep that, but also allow this new approach.

[mindsocket]

@claude work on this issue in a new branch. It is appropriate to overhaul the current divided architecture between "on a page" and "space" parsing, and to adapt and extend the tests accordingly, including new tests for this "hybrid" approach.

Note any decisions and assumptions you make in a comment here.

[claude]

Claude finished @mindsocket's task in 24m 12s —— View job • claude/issue-10-20260226-0439 • Create PR ➔

---

Working on Issue #10: Support "embedding" of subitems at any level

• Read existing codebase to understand current architecture
• Design unified parsing approach (see decisions below)
• Create src/parse-embedded.ts — shared extraction logic
• Refactor src/read-ost-page.ts to use parse-embedded + support hybrid files
• Overhaul src/read-space.ts — extract embedded nodes from all typed files
• Update src/validate.ts — fix node index building + handle file#section / file#^anchor wikilinks
• Create new test fixtures (hybrid vision, hybrid standalone, anchor-type)
• Update and extend tests (read-space, read-ost-page, validate)
• Commit and push changes

What was implemented

New src/parse-embedded.ts — all shared body-parsing logic (headings, typed bullets, YAML blocks, anchor extraction, depth inference) lives here, called by both readOstPage and readSpace.

Hybrid pages — any file with a real OST type (e.g. type: vision) can now contain embedded child nodes in its body:

type: vision
---
## [type:: mission] Our Mission ^ourmission
Our mission content.
### [type:: goal] A Goal

Only headings with explicit [type:: x] or an OST-type anchor (^mission, ^goal1) become embedded nodes; other headings are depth-tracking placeholders.

Cross-file parent refs — embedded nodes get compound labels (filename#title) and generated parent refs use [[filename]] or [[filename#title]]:

type: goal
parent: "[[new_vision#Our Mission]]"

Anchor support — ^anchorname stored in data.anchor; indexed for [[File#^anchor]] wikilink resolution; anchors named after OST types imply type.

ost_on_a_page in space context — the file is no longer added as a single node; instead its embedded nodes are extracted with container#title compound labels. The includePageFiles option is removed.

Decisions & Assumptions

• Removed includePageFiles option from readSpace — ost_on_a_page files always contribute embedded nodes now
• In hybrid mode, untyped headings are depth-tracking placeholders (not nodes), so normal content headings don't accidentally become OST nodes
• ost_on_a_page mode retains depth-based type inference (backward compatible)
• anchorToOstType: ^goal1 → type "goal"; exact match (^mission) also works
• The show and diagram CLI commands build parent-child trees using data.title as the lookup key, which won't match compound filename#section parent refs — hybrid embedded nodes will surface as roots rather than children in those views. Can be fixed in a follow-up.

|

[mindsocket]

Following research on #3 (findings in docs/torres-alignment-research.md):

This issue's embedding work is the key enabler for the sub-entity model discussed in #5. Once heading/section embedding is supported at any level, sub-entities (assumptions, metrics, risks, problem statements) can be expressed as annotated headings within a primary entity page without requiring separate files. The schema defines the type in one place; full-page and embedded expressions both validate against it.

This "full page or embedded heading — both valid" flexibility is worth calling out as a deliberate design principle, to be documented in #18.

[mindsocket]

Removed includePageFiles option from readSpace — ost_on_a_page files always contribute embedded nodes now

By definition, historically at least, reading a space should look for files other than ost on a page. This allows a directory to evolve from an "on a page" to set of files without having to keep them separate, and avoiding collisions. It doesn't make sense to combine the approaches, and it doesn't make sense to force them to be in different directories. Restore how it worked before, reading a space collects all non-on-a-page files, and page based strictly reads nodes from only the file given.

Switching topics, it sounds like links and titles have been conflated. Titles are defined at the source from filename, header, or bullet. Links, including anchors ensure the correct referenced item is found but those links should resolve to plain titles in the schema. Perhaps some work is needed to better describe the wikilink formatting vs a title specification.

Specifically...

embedded nodes get compound labels (filename#title) and generated parent refs use [[filename]] or [[filename#title]]:

These compund labels might not be valid wiki links. Embedded nodes should simply get a resolved title ("Our mission"), type and parent. Parent links to that (eg vision#^mission) should resolve to the same unique title in the nodes.

Does that make sense @claude

[claude]

Claude encountered an error —— View job

---

Working on corrections to Issue #10 implementation

• Read current codebase to understand existing implementation
• Restore space/page separation (readSpace only processes non-ost_on_a_page files)
• Fix embedded node titles to use simple resolved titles, not compound filename#title labels
• Update parent wikilink resolution ([[file#section]] / [[file#^anchor]] → plain title lookup)
• Update tests to reflect corrected behavior
• Commit and push changes
  • claude/issue-10-20260226-0709

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[mindsocket]

Pushed corrections to claude/issue-10-20260226-0439.

Changes made

Restored space/page separation (src/read-space.ts):
Reverted to the original logic — readSpace reads non-ost_on_a_page files as single nodes, one per file. Hybrid files (typed pages with embedded content) are included as regular nodes; their body content is ignored in space mode. The includePageFiles option is retained. No more embedded extraction in space mode.

Removed compound labels (src/parse-embedded.ts, src/read-ost-page.ts):
Dropped the labelPrefix option from extractEmbeddedNodes. Embedded nodes now always have plain resolved titles (e.g. "The Mission"), and parent refs within a page use plain wikilinks (e.g. [[The Mission]]). The page itself is referenced by its filename sans extension (e.g. [[hybrid-page-valid]]).

Updated fixture (tests/fixtures/valid-ost/hybrid_solution.md):
Changed parent: "[[hybrid_vision#Embedded Goal]]" to parent: "[[hybrid_vision]]" — since embedded nodes are not extracted in space mode, the solution now correctly references the vision file as a whole.

Updated tests:

• read-space.test.ts: node count 9→7, hybrid section now asserts that no #-labelled nodes appear and that hybrid files are treated as single nodes.
• validate.test.ts: node count 9→7, removed compound-label test cases.

What the wikilink/title distinction now looks like

In page mode (readOstPage on a hybrid file):

• File node: label hybrid-page-valid.md, title hybrid-page-valid
• Embedded mission: label The Mission, parent [[hybrid-page-valid]]
• Embedded goal: label The Goal, parent [[The Mission]]

In space mode (readSpace):

• hybrid_vision.md → one node, title hybrid_vision
• hybrid_solution.md → one node, parent [[hybrid_vision]] (references by filename key)

Cross-file refs to embedded nodes (e.g. [[vision#^mission]]) are out of scope for the current space validation path and can be addressed as a follow-up if needed.