Codegen Add Surface Entity

Exposing an existing entity through one of the user-facing surfaces: the CLI, the HTTP API, or the shell REPL. The procedure is the same for all three, so it is one skill and a table; only the file locations, the build target and the phase contents differ.

Prerequisites, in order: the domain type exists (compass-code-add-domain-type), and its repository and table I/O are implemented. See Entity lifecycle for the full layer ordering.

1. Pick the surface and read its row below. The row names the build target, the patterns document holding its file locations and class shapes, and the walkthrough recipe.
2. Gather requirements: the entity name, the surface's own name for it (a plural hyphenated command, a menu name, a route), the operations needed, the key field, and the required and optional parameters.
3. Work the three phases, one PR each. The phases differ per surface and the row names them. Each phase ends in a building, reviewable state.
4. Build after every step through compass, so the host-wide build lock is taken and a concurrent build in another worktree cannot corrupt this one (see How do I build the system?).
5. Raise each phase's PR with compass-pr-raise, branching between phases with compass-code-start-branch.

The CLI and the HTTP API have no codegen profile, so the code in them is written by hand. That is a gap to close rather than a standing arrangement: generated structure is the target state for every surface (Generated artefacts).

When one of those three surfaces is reached during entity work, raise a sprint story for its profile, link it to the entity task, and reference Entity lifecycle§"Codegen gaps" for what the profile must cover. Once the profile lands, regenerate the surface and discard the hand-written code.

The shell left that list on 2026-09-16. The ores.cpp.shell-command facet generates one command unit per entity into the ores.shell.<domain> adapter part, so an entity's shell verbs become a codegen run. The trading units are mid-migration: Generate shell command units per component retires the hand-written units one component at a time, and until it finishes the two flows coexist.

• How do I create HTTP endpoints for a new entity?
• How do I create shell commands for a new entity?

• Entity lifecycle — layer ordering across every surface.
• compass-codegen-add-entity — the orchestrator that reaches this layer.
• Skill architecture — why a uniform verb is one skill plus a type table.