Codegen Add Component

When the user asks to create a new ORE Studio component — a new project under projects/. Most domain components are split into .api, .core, and .service parts; decide which parts are needed before starting. See Component architecture for the split rules, facet placement, and CMake dependency chain.

Codegen is mandatory for all boilerplate. Do not hand-write CMakeLists or stub files.

Since PR #1014 the component_overview.org per component is the single source of truth for both humans and codegen — the standalone *_component.json and *_component.org models are retired.

1. Gather requirements: component short name, parts needed (.api, .core, .service, or a subset), one-line brief, longer description.

2. Scaffold the per-part overview via compass. For each part (.api, .core, .service) run:

   ./projects/ores.compass/compass.sh add component \
     --slug component_overview \
     --parent-dir projects/ores.COMPONENT/PART/modeling \
     --title "ores.COMPONENT.PART" \
     --description "<one-liner ≤ 120 chars>" \
     --brief "<short tagline>"
   

   The scaffold includes the codegen-readable keywords (#+name:, #+full_name:, #+brief:) automatically. Fill in the * Summary and other sections per Component Documentation Guide.

3. Run codegen against each overview to scaffold the C++ + CMake project. Each overview's #+component_kind: frontmatter (api, core, service, or the default flat) selects the scaffolding variant. Two addresses are needed: ores.cmake.component writes the CMakeLists.txt files, and ores.cpp writes the C++ presence. The C++ address is the technical space rather than one facet, because the opt-in scaffold below is a sibling of ores.cpp.component.

   ./projects/ores.codegen/codegen.sh generate \
     --model projects/ores.COMPONENT/api/modeling/component_overview.org \
     --address ores.cmake.component
   ./projects/ores.codegen/codegen.sh generate \
     --model projects/ores.COMPONENT/api/modeling/component_overview.org \
     --address ores.cpp
   

   Repeat per part (.api, .core, .service), each against its own overview file.

   The overview scaffold writes :ores.cpp.scaffold.enabled: true into the :PROPERTIES: drawer, because a component with no models yet needs the first-generation scaffold: an umbrella header, a placeholder domain type with its implementation, and a placeholder Catch2 test, so that its targets link and its test runner passes before any real code exists. That scaffold lives in ores.cpp.scaffold, which is #+default: disabled, so that one line is the whole opt-in and nothing else emits the placeholders.

   Remove the line, and the four files, when the component's first real model lands. While the line is present, every regeneration re-emits the placeholders, which is what the line asks for; grep -rn 'ores.cpp.scaffold.enabled: true' projects/*/modeling/ lists the components still carrying scaffolding.

4. (Optional) Add a group-level overview at projects/ores.COMPONENT/modeling/component_overview.org. The group overview is navigation + group-level codegen scalars; the directory layout projects/ores.COMPONENT/{api,core,service}/ is the composite declaration (no :subcomponents: keyword needed).
5. Register each part in projects/CMakeLists.txt in dependency order (.api → .core → .service).
6. Add a PlantUML stub (modeling/ores.COMPONENT.PART.puml) for each part — codegen does not yet produce this. See component-model-creator for the diagram conventions.
7. Build and verify the scaffold tests with cmake-runner, via compass build (not raw cmake --build, so it takes the host-wide build lock — see How do I build the system?): ./compass.sh build ores.COMPONENT.api.tests
8. Fill in the architecture sections of each overview using component-model-creator (Inputs, Outputs, Entry points, Dependencies, See also, and the PlantUML diagram).

The C++ scaffold runs via --address ores.cpp; the overview's #+component_kind: frontmatter picks the variant. The CMake files run via --address ores.cmake.component.

All four kinds consume the same model type component, read from a component_overview.org via load_org_component_overview_model. Full template list is in ORE Studio Codegen§"Profile catalogue".

The codegen-side scaffold flow is exercised by projects/ores.codegen/tests/component_scaffold/verify.py — two fixture components (flat + composite) plus prior-art checks against ores.nats (flat) and ores.controller (composite group + 3 subs).

• Component architecture — split rules, facet placement, CMake dep chain.
• ORE Studio Codegen — model schema, physical-space graph, codegen.sh usage.
• component-model-creator — write the architecture docs once scaffold is working.
• cmake-runner — build and test commands.

• How do I create a component overview? — the overview every new component needs.