cadrumo.application.operator_surface.help module

Backend-owned help and discovery documents for accepted CLI roots.

The builders return typed HelpDocument and RootLandingReport records for the contract-backed root, config, and app help surfaces declared by application.operator_surface. CLI adapters render these records through the shared output boundary; they do not own the command inventory.

This module is manifest-discovery only: it builds in-memory documents from locale keys and caller-supplied profile state. It does not inspect storage, read environment variables, construct repositories, or decide whether the bare root should render the landing report or the overview status report.

build_help_document(surface)

Return the curated help document for surface.

Accepts a HelpSurface member or its string token and returns a HelpDocument with workflow-ordered HelpSection and HelpEntry records for the requested surface. The returned document is consumed by render_help_text() and by the root/app envelope paths.

Return type:

HelpDocument

Parameters:

surface (HelpSurface | str)

build_root_landing_report(active_profile, *, profile_selected=None, registered_profile_count=0)

Return the RootLandingReport for caller-supplied profile state.

The caller owns active-profile discovery and passes the projected display label here, separately from whether the profile-selection pointer exists. A present label points operators at aeat app overview status; a selected profile whose label cannot be resolved points at profile repair; a genuinely absent selection points at profile creation. The CLI root callback decides whether this landing report or the full overview status is emitted under root.status.

Return type:

RootLandingReport

Parameters:

• active_profile (str | None)

• profile_selected (bool | None)

• registered_profile_count (int)

render_help_text(document)

Render a curated HelpDocument as terminal-safe plain text.

The renderer preserves the backend-owned ordering of HelpSection and HelpEntry records, aligns command columns, and returns text for CLI adapters to pass through their normal output boundary. It does not inspect the live CLI tree; conformance tests own the check that rendered command rows still map to mounted command families.

Return type:

str

Parameters:

document (HelpDocument)