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:

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

   Repeat with --profile component-core and --profile component-service as needed.

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 stub tests with cmake-runner: cmake --build --preset linux-clang-debug-ninja --target 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).

Scaffold profiles (each generates 9 files for .api=/.core=; 18 for .service):

All four profiles 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, profiles, run_generator.sh usage.
• component-model-creator — write the architecture docs once scaffold is working.
• cmake-runner — build and test commands.