feat: schema reorganization, strict_ost schema, and terminology updates

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "files.associations": {
+    "*.json": "jsonc"
+  }
+}

CLAUDE.md

@@ -1,6 +1,6 @@
 # OST Tools
 
-Opportunity Solution Tree (OST) validation and diagram generation tooling.
+Tools for working with Opportunity Solution Tree structures and other product management and strategy frameworks
 
 ## Development
 
@@ -9,7 +9,7 @@ Space aliases (e.g. `personal`, `politics`) are resolved via `config.json`.
 
 ## Project Context
 
-This project validates OST node markdown files against a JSON schema.
+This project validates data in markdown files against a JSON schema representing product and strategy frameworks, including Opportunity Solution Trees.
 
 Before starting new work, review [docs/concepts.md](docs/concepts.md) for canonical terminology. Use and maintain the definitions there as the source of truth when naming things in code, tests, comments, and documentation.
 

README.md

@@ -1,6 +1,6 @@
 # ost-tools
 
-Opportunity Solution Tree validation and diagram generation tool.
+Tools for working with Opportunity Solution Tree structures and other product management and strategy frameworks
 
 ## Installation
 
@@ -10,7 +10,7 @@ npm install -g ost-tools
 
 ## Concepts
 
-See [docs/concepts.md](docs/concepts.md) for the full terminology reference, including definitions of OST nodes, embedded nodes, spaces, schemas, rules, and more.
+See [docs/concepts.md](docs/concepts.md) for the full terminology reference, including definitions of nodes, embedded nodes, spaces, schemas, rules, and more.
 
 ## Configuration
 
@@ -24,10 +24,10 @@ See `config.example.json` for the full structure. The config maps space aliases
 
 ### Spaces
 
-A space is a named OST directory registered in the config. Spaces let you reference a tree by alias instead of path:
+A space is a named directory or single file registered in the config. Spaces let you reference content by alias instead of path:
 
 ```bash
-ost-tools validate personal
+ost-tools validate ProductX
 ```
 
 ### Schemas
@@ -40,13 +40,13 @@ Schema resolution order: CLI `--schema` > space config `schema` > global config
 
 ## Usage
 
-### Validate OST nodes
+### Validate nodes
 
 ```bash
 ost-tools validate <space-or-dir> [--schema path/to/my-schema.json]
 ```
 
-Validates markdown files against the OST JSON schema:
+Validates markdown files against the JSON schema:
 - Extracts YAML frontmatter from each `.md` file
 - Skips files without frontmatter or without a `type` field
 - Reports validation results with counts and per-file errors
@@ -57,19 +57,19 @@ Validates markdown files against the OST JSON schema:
 ost-tools diagram <space-or-dir> [--output path/to/output.mmd] [--schema path/to/my-schema.json]
 ```
 
-Generates a Mermaid `graph TD` diagram from validated OST nodes:
+Generates a Mermaid `graph TD` diagram from validated space nodes:
 - Uses parent→child relationships from wikilinks
 - Applies type-based styling (different colours per node type and status)
 - Handles orphan nodes (no parent) as a separate cluster
 - Outputs to file or stdout
 
-### Sync OST to Miro
+### Sync space to Miro
 
 ```bash
 ost-tools miro-sync <space> [--new-frame <title>] [--dry-run] [--verbose]
 ```
 
-Syncs OST nodes to a Miro board as cards with connectors. Requires `MIRO_TOKEN` env var and `miroBoardId` set in the space's config entry.
+Syncs space nodes to a Miro board as cards with connectors. Requires `MIRO_TOKEN` env var and `miroBoardId` set in the space's config entry.
 
 - `--new-frame <title>` — create a new frame on the board and sync into it; auto-saves the resulting `miroFrameId` back to the config file
 - `--dry-run` — show what would change without touching Miro

biome.json

@@ -28,6 +28,11 @@
       "quoteStyle": "single"
     }
   },
+  "json": {
+    "parser": {
+      "allowComments": true
+    }
+  },
   "assist": {
     "enabled": true,
     "actions": {

docs/concepts.md

@@ -6,7 +6,7 @@ This document is the canonical reference for concepts and terminology used in th
 
 ## Space
 
-A **space** is a named collection of nodes organised according to a schema. Spaces are the primary unit of organisation — a space has a backing format (a `space directory` or an `OST on a page` file) and may be registered in `config.json` with an alias for convenient access.
+A **space** is a named collection of nodes organised according to a schema. Spaces are the primary unit of organisation — a space has a backing format (a `space directory` or a `space on a page` file) and may be registered in `config.json` with an alias for convenient access.
 
 ```json
 { "alias": "personal", "path": "/path/to/planning directory" }
@@ -18,77 +18,73 @@ A space carries optional configuration alongside its alias: schema path, templat
 
 ### Space directory
 
-A **space directory** is a directory of markdown files that backs a `space`. Each file may represent an `OST node`, embed child nodes in its body, or be an unrelated file that the tooling ignores.
+A **space directory** is a directory of markdown files that backs a `space`. Each file may represent a `space node`, embed child nodes in its body, or be an unrelated file that the tooling ignores.
 
 Parsing behaviour for a space directory:
-- Files declaring an `OST node` type via frontmatter are included as nodes.
+- Files declaring a `space node` type via frontmatter are included as nodes.
 - Such files may also contain `embedded nodes` in their body, which are extracted and included.
-- Files declaring a `tooling type` (e.g. `ost_on_a_page`, `dashboard`) are excluded from the node set.
+- Files declaring a `tooling type` (e.g. `space_on_a_page`, `dashboard`) are excluded from the node set.
 - Files without frontmatter, or without a `type` field, are excluded from the node set.
 - Non-markdown files are not scanned.
 
-### OST on a page
+### Space on a page
 
-**OST on a page** is a single-file backing format for a `space`. An entire planning tree is represented in one markdown document, using heading hierarchy, bullet point annotations, and `anchor` syntax. No separate per-node files are used. This format is most useful for the early development stages of a space, keeping information together in one file with less "boilerplate".
+**Space on a page** is a single-file backing format for a `space`. An entire planning tree is represented in one markdown document, using heading hierarchy, bullet point annotations, and `anchor` syntax. No separate per-node files are used. This format is most useful for the early development stages of a space, keeping information together in one file with less "boilerplate".
 
-A file in this format carries `type: ost_on_a_page` in its frontmatter. It is not itself an `OST node` — it is a container.
+A file in this format carries `type: space_on_a_page` in its frontmatter. It is not itself a `space node` — it is a container.
 
 Key properties:
-- Heading hierarchy determines node depth and infers `OST node` type (depth-based type inference).
+- Heading hierarchy determines node depth and infers `space node` type (depth-based type inference).
 - Heading levels must not skip — each level must be exactly one deeper than its parent.
 - A horizontal rule (`---`) terminates parsing; headings below it are ignored.
 
 > The name "OST on a page" may be revised as the tooling moves toward space-centric terminology — see [GitHub issue #22](https://github.com/mindsocket/ost-tools/issues/22).
 
 #### Preamble
 
-**Preamble** is content in an `OST on a page` document that appears before the first heading. It is parsed but discarded — not associated with any node.
+**Preamble** is content in a `space on a page` document that appears before the first heading. It is parsed but discarded — not associated with any node.
 
 ---
 
-## OST node
+## Space node
 
-An **OST node** is a single entity in a `space` — a named, typed item defined in the schema. `OST nodes` are the primary content of a space.
+A **space node** (or **node** for short) is a single entity in a `space` — a named, typed item defined in the schema. Nodes are the primary content of a space.
 
 Node types are defined by the schema in use and may vary across schemas. Examples from the default schema: `vision`, `mission`, `goal`, `opportunity`, `solution`. The tooling is not prescriptive about which types exist — schemas are designed to be extended and replaced.
 
-> `ost_on_a_page` and `dashboard` are not `OST node` types — they are `tooling types`.
-
-> The "OST" prefix reflects the project's origins. As the tooling evolves toward broader planning support, this term may be revised — see [GitHub issue #22](https://github.com/mindsocket/ost-tools/issues/22).
+> `space_on_a_page` and `dashboard` are not `space node` types — they are `tooling types`.
 
 ### Embedded node
 
-An **embedded node** is an `OST node` defined *within* a containing document rather than as its own file. Embedded nodes are declared using markdown heading syntax with inline field annotations (e.g. `[type:: goal]`) or `anchor-implied types`, and are extracted at parse time.
+An **embedded node** is a `space node` defined *within* a containing document rather than as its own file. Embedded nodes are declared using markdown heading syntax with inline field annotations (e.g. `[type:: goal]`) or `anchor-implied types`, and are extracted at parse time.
 
 A `typed page` may contain embedded nodes in its body. Those nodes become full members of the parsed node set, with `parent references` wired to their containing page or enclosing heading.
 
 ### Type alias
 
-A **type alias** is an alternative name accepted in the `type` field for a given `OST node` type. Aliases allow teams to use their own vocabulary while still receiving schema validation. For example, a schema might accept `outcome` as an alias for `goal`.
-
-*(Type alias support is planned — see [GitHub issue #14](https://github.com/mindsocket/ost-tools/issues/14).)*
+A **type alias** is an alternative name accepted in the `type` field for a given `space node` type. Aliases allow teams to use their own vocabulary while still receiving schema validation. For example, a schema might accept `outcome` as an alias for `goal`.
 
 ---
 
 ## Typed page
 
-A **typed page** is a markdown file whose frontmatter declares an `OST node` type (e.g. `type: goal`). The file itself represents one node, and its body may additionally contain `embedded nodes`.
+A **typed page** is a markdown file whose frontmatter declares a `space node` type (e.g. `type: goal`). The file itself represents one node, and its body may additionally contain `embedded nodes`.
 
-Typed pages are distinct from `OST on a page` files: a typed page *is* an `OST node`; an `ost_on_a_page` file is merely a container.
+Typed pages are distinct from `space on a page` files: a typed page *is* a `space node`; a `space_on_a_page` file is merely a container.
 
 ---
 
 ## Schema
 
-A **schema** defines the valid structure for `OST nodes` in a `space`: the fields, types, constraints, and descriptive `rules` for each entity type. A space uses the default schema unless a custom one is declared in its config.
+A **schema** defines the valid structure for nodes in a `space`: the fields, types, constraints, and descriptive `rules` for each entity type. A space uses the default schema unless a custom one is declared in its config.
 
 The schema handles structural validation. It does not encode qualitative or cross-node checks — those are handled by `rules`, which may be embedded within the schema or applied separately.
 
-Schemas are designed to be composable: shared building blocks (common field sets, scoring models, constraint overlays) can be referenced across schema files, letting teams tailor a schema without forking its foundations. *(Schema composability is under active development — see [GitHub issues #13](https://github.com/mindsocket/ost-tools/issues/13), [#17](https://github.com/mindsocket/ost-tools/issues/17).)*
+Schemas are designed to be composable: shared building blocks (common field sets, scoring models, constraint overlays) can be referenced across schema files, letting teams tailor a schema without forking their foundations. *(Schema composability is under active development — see [GitHub issues #13](https://github.com/mindsocket/ost-tools/issues/13), [#17](https://github.com/mindsocket/ost-tools/issues/17).)*
 
 ### Rules
 
-**Rules** are descriptive, and potentially executable, checks applied to `OST nodes` beyond what structural schema validation can express. Rules encode qualitative guidance and best practices alongside the schema, making them available to both tooling and agent skills.
+**Rules** are descriptive, and potentially executable, checks applied to nodes beyond what structural schema validation can express. Rules encode qualitative guidance and best practices alongside the schema, making them available to both tooling and agent skills.
 
 Rules may be:
 - **Descriptive** — human-readable guidance, useful as documentation and as structured input to agent skills
@@ -108,28 +104,28 @@ Rules are distinct from schema validation: the schema checks structure; rules ch
 
 ## Tooling types
 
-**Tooling types** are `type` values recognised by the schema and tooling but not treated as `OST nodes`. They serve organisational or display purposes:
+**Tooling types** are `type` values recognised by the schema and tooling but not treated as `space nodes`. They serve organisational or display purposes:
 
-- **`ost_on_a_page`** — a container file for an `OST on a page`. Not itself a node.
-- **`dashboard`** — a summary view for a `space directory`. Conceptually similar to `OST on a page` in that it presents a high-level, single-document view of a space — but rather than defining the space, it reflects it, querying and assembling information from the space's node files. Useful after a space has "graduated" from a single `OST on a page` file to a `space directory`, as a way to preserve that top-level overview. The dashboard concept may evolve to surface more operational information over time, but there is no concrete design for that yet.
+- **`space_on_a_page`** — a container file for a `space on a page`. Not itself a node.
+- **`dashboard`** — a summary view for a `space directory`. Conceptually similar to `space on a page` in that it presents a high-level, single-document view of a space — but rather than defining the space, it reflects it, querying and assembling information from the space's node files. Useful after a space has "graduated" from a single `space on a page` file to a `space directory`, as a way to preserve that top-level overview. The dashboard concept may evolve to surface more operational information over time, but there is no concrete design for that yet.
 
 ---
 
 ## Parent reference
 
-A **parent reference** is the `parent` field on an `OST node` — a `wikilink` pointing to the node's direct parent in the tree. Root-level node types (such as `vision` in the default schema) carry no parent. Other node types carry one optionally, allowing for orphaned nodes — useful while drafting a tree or when explicitly capturing ideas like "solutions looking for a problem".
+A **parent reference** is the `parent` field on a `space node` — a `wikilink` pointing to the node's direct parent in the tree. Root-level node types (such as `vision` in the default schema) carry no parent. Other node types carry one optionally, allowing for orphaned nodes — useful while drafting a tree or when explicitly capturing ideas like "solutions looking for a problem".
 
 Parent references are validated during ref-checking: each `parent` wikilink must resolve to a known node title in the parsed node set.
 
 ### Wikilink
 
-A **wikilink** is the `[[Title]]` linking syntax (compatible with Obsidian) used to express `parent references` between `OST nodes`. The `parent` field of a node holds a wikilink to its parent.
+A **wikilink** is the `[[Title]]` linking syntax (compatible with Obsidian) used to express `parent references` between `space nodes`. The `parent` field of a node holds a wikilink to its parent.
 
 Two forms are supported:
 
 | Form | Example | Resolves to |
 |---|---|---|
-| Plain title | `[[My Goal]]` | The `OST node` whose title equals `My Goal` |
+| Plain title | `[[My Goal]]` | The `space node` whose title equals `My Goal` |
 | Anchor ref | `[[vision_page#^goal1]]` | The `embedded node` with `anchor` `goal1` inside `vision_page.md` |
 
 ### Anchor
@@ -143,8 +139,8 @@ An **anchor** is a block anchor (e.g. `^goal1`) appended to a heading in a `type
 
 ## Status
 
-**Status** is a lifecycle field on `OST nodes` indicating a node's current stage. The valid values and their semantics are defined by the schema in use. Examples from the default schema (in rough progression):
+**Status** is a lifecycle field on nodes indicating a node's current stage. The valid values and their semantics are defined by the schema in use. Examples from the default schema (in rough progression):
 
 `identified` → `wondering` → `exploring` → `active` → `paused` → `completed` → `archived`
 
-Status is required on all `OST node` types at _validation_ time. Note however that currently the `On A Page` parser chooses to apply a default.
+Status is required on all node types at _validation_ time. Note however that currently the `space on a page` parser chooses to apply a default.