How do I create shell commands for a new entity?

How do I add shell REPL commands for a new entity in ores.shell?

Do not write the unit. Generate it.

1. Annotate the columns. The add verb reads one positional per user-supplied column. The :supplied_by: annotation on a column names its source, and it has four values: user, minted, session_party and unset. Most columns need no annotation, because user is the default, and a uuid primary key already defaults to minted. Write the annotation only where the default is wrong. A column the caller does not supply takes unset; a column that holds the acting party takes session_party.

2. Opt the entity in. Add this entry to the top-level properties drawer of the entity model, beside :ID::

   :ores.cpp.shell-command.enabled: true
   

3. Generate the unit.

   ./compass.sh codegen generate --model projects/ores.<component>/modeling/ores.<component>.<entity>.org --address ores.cpp.shell-command
   

   Three files appear in the entity's adapter part: a header, an implementation and a test. The archetype sets clang-format on the output.

4. Register the unit. Open projects/ores.shell/application/src/app/commands/{component}/{component}_commands.cpp and add two lines, in alphabetical order with the others:

   #include "ores.shell/app/commands/{component}/{entity}_commands.hpp"
   

   {entity}_commands::register_commands(root_menu, session, pagination);
   

   Delete the hand-written unit and its header for the entity in the same change, so the submenu is not registered twice.

5. Refresh the part file lists. The part declares #+component_kind: adapter, so codegen owns its two file lists. The scan is a directory listing, and only this script writes it:

   projects/ores.codegen/venv/bin/python projects/ores.codegen/scripts/regenerate_cmake_component_files.py --component ores.shell.{component}
   

6. Build and test.

   ./compass.sh build ores.shell.exe
   ./compass.sh test run -- -R ores.shell
   

   The generated test file pins the arity check, the malformed token that names its field, and a valid token vector that reaches the transport. Read it before the smoke test, so a failure there is a code failure and not a surprise.

Start ores.shell, connect, and exercise each subcommand interactively against a local database. Every entity's cases carry the {entity}_commands prefix, so ores.shell.{component}.tests --list-tests gives a per-entity handle on a component's suite.

• How do I test the shell? — the three levels that prove the new unit works.
• Shell entity patterns — class layout, the two shapes, file locations.
• compass-codegen-add-surface-entity — skill that drives this workflow.
• Entity lifecycle — layer ordering overview.