Story: Clean up codegen documentation and MASD alignment
Table of Contents
This page documents a story in Sprint 20. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
1. Goal
The codegen documentation tells a coherent story: the MASD document's facet catalogue links to the literate template org files that implement each facet; each template org file links back to the MASD doc and to the relevant modeling facet reference docs; and MASD terminology (projection, facet, facet group) is used consistently throughout.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 20 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-06-10 |
3. Acceptance
- The MASD document's facet catalogue links to the literate template org files for each facet (cpp_domain, cpp_repository, sql_schema, etc.).
- Each template group and facet org file carries a link to MASD and, where a modeling facet reference doc exists, a link to that doc.
- The modeling facet reference docs (type_definition_facet.org, sql_facet.org, etc.) link back to the corresponding template org files.
- "Projection" is used consistently in template prose where MASD terminology applies; loose uses of "meta-model" in template comments are resolved.
4. Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Scaffold story: Clean up codegen documentation and MASD alignment | DONE | 2026-06-07 | 2026-06-07 | Story scaffolding: documents, sprint wiring, and the scaffold PR. |
| Audit and update the MASD document | DONE | 2026-06-07 | 2026-06-07 | Review and update projects/modeling/masd.org: update facet catalogue to link to literate template org files; align transformation model section with the LLM-based approach. |
| Cross-link template org files into the org-roam graph | DONE | 2026-06-10 | 2026-06-10 | Add MASD and modeling facet reference doc links from each template group and facet org file; add reciprocal links in the modeling facet docs. |
| Audit and correct MASD terminology across codegen docs | DONE | 2026-06-07 | 2026-06-08 | Re-scoped after PR #1176: split MASD docs into a pure set (doc/knowledge/masd, no ORE references) and an applied umbrella (projects/modeling/applied_masd.org); fix the "part" definition; augment pure docs with technical content and figures from the Dogen Domain Architecture reference. |
| Improve the Developer Links page with workflow recipes | DONE | 2026-06-08 | 2026-06-08 | Rewrite doc/developer.org from a bare external-URL index into a practical developer guide: add sections linking to the key compass and cmake recipes (build, configure, run tests, setup environment, start services, deploy site/skills/settings, format); group by workflow phase (setup, build, test, develop, release). |
| Write the ORE Studio architectural philosophy page | DONE | 2026-06-10 | 2026-06-10 | Create a narrative architecture doc that explains WHY the system is structured as it is: the motivation behind the four-layer dependency rule, how services interact over NATS (pub/sub, service discovery, event propagation), how Qt, CLI, HTTP, and Wt surfaces share the same domain layer, and how these decisions produce a coherent and extensible system. This is the missing narrative complement to the descriptive system_model.org. |
| Mop up: codegen docs and site navigation | DONE | 2026-06-08 | 2026-06-08 | Seven small cleanups: drop Architecture nav menu; rename MASD menu to Modeling; deduplicate parts/facets note; rename Developer Links to Developer Guide; split inlined archetypes into separate org files; add template-variable reference doc; enrich archetype descriptions. |