Document project principles in docs/principles.md

[mindsocket]

Capture the principles that have emerged from design work, to serve as a reference for future decisions and for contributors.

Draft principles to document

• Composability: schemas are built from shared building blocks; teams compose rather than fork; schemas can be assigned per space
• Flexible page/embedding: entities can be expressed as full pages or as embedded headings/sections within a parent page — both are valid expressions of the same entity type (once Support "embedding" of subitems at any level #10 lands)
• Quality scaffolding: the tool provides scaffolding that helps improve the quality of planning tree content, not just validate structure — through descriptive rules, templates, and agent skill integration
• Reduce toil: automate the mechanical aspects of managing planning content (validation, diagram generation, sync, templates)
• Terminology flexibility: type aliases allow teams to use their own vocabulary while still getting schema validation
• Separation of concerns: structural validation (schema/AJV), qualitative guidance (descriptive rules in schema), and AI-assisted analysis (Create an agent skill that knows how to work with OST content #2) are distinct, composable layers
• Fail loudly: prefer explicit errors over silent fallbacks; the tool should surface problems clearly so they can be fixed

These are draft — the doc should expand and refine them, add rationale and examples, and note where they inform specific design decisions.

When to do this

Best written after the schema reorganization (#13) and strict_ost (#15) work is complete, since those decisions will make the principles more concrete.

[mindsocket]

One to ponder and add - convention over configuration - for this project that probably means: sweat the details on schemas and parsing rules so that content authoring is intuitive and natural once configured - follow common and natural paths (eg natural heading/page/path hierarchies, linking, tagging and metadata structures, content types like tables, lists and databases)