First-Screen Composition Root

Component builds card

This component builds the one card a new reader sees before choosing a deeper route into the public Plectis repository, hosting nothing, calling no provider, and claiming no finished repository. The first-screen composition root builds the one card a new reader sees before they pick a deeper route into the public Plectis repository. It is one Python component, microcosm_core.first_screen_composition, with a small command-line wrapper. It does not host anything, call a model provider, or claim the repository is finished.

Output is card

Its output is one card in three shapes, full JSON, budgeted compact JSON, and terminal text, all built from a standard and checked back against it so drift becomes a failed check. Its output is a single card in three shapes: a full JSON contract, a compact JSON card under a character budget, and a terminal-sized text card. Every shape carries the same shared first command, the same six reader branches, the same evidence accounting, and the same scope limit. The component builds the card from a standard file and then checks the built card back against that same standard, so a renamed field or a dropped branch shows up as a failed check instead of silent drift.

Purpose

The first-screen problem is not depth

The repository already has deep surfaces; the first-screen problem is that depth lands badly when a cold reader first meets a long command list or a raw JSON dump. The repository already has deep surfaces: route maps, component status, standards, result records, and the localhost observatory. The first-screen problem is not missing depth. It is that depth lands badly when the first thing a reader meets is a long command list or a raw JSON dump.

Prose has no contract, so it drifts

A hand-written welcome card drifts because prose has no contract, so the composition root replaces it with a fixed structure answering what must fit on one screen and in what order. A loose, hand-written welcome card fails in a specific way. It drifts. Someone renames a branch, adds a command, or removes the scope limit, and nothing catches it, because prose has no contract. The composition root replaces prose with a fixed structure and answers one question: when a cold reader lands here, what has to fit on one screen, and in what order.

The fixed slots on the card

The fixed slots are a goal-entry line, a shared first command, one behavior proof, six reader branches, an evidence-count legend, a link to the wider system, a deeper-route list, and the scope limit. The fixed slots are the goal-entry line plectis comprehend --first-action "<your goal>", the shared first command plectis hello <project>, one shared behavior proof plectis tour --card <project>, six reader branches, an evidence-count legend read as accounting rather than a score, a link from the local command to the wider source-open system, a short list of the deeper routes the card names instead of copying, and the scope limit.

How it works

The order below is the order first_screen_composition_card runs.

The builder assembles from the standard

first_screen_composition_card loads the standard and assembles one large payload of shared commands, six reader routes, menus, proof fields, legend, counts, and a scope limit, free-handing none of it. first_screen_composition_card(root, project_label) is the builder. It loads standards/std_microcosm_first_screen_composition_root.json through _load_standard, then assembles one large payload: the shared commands, the six reader routes from _reader_routes, the copyable per-reader menu, the behavior-proof fields, the evidence-class legend, the scale counts, and the scope limit copied from the standard. It free-hands none of this. The authority_ceiling, anti_claim, and public_private_boundary are deep-copied straight from the standard.

Internal consistency checks

_validation_checks returns named booleans that are true only when each card surface satisfies its own contract, yielding a false check for any missing or malformed surface and never raising. Once the payload is built the component checks it twice. _validation_checks(payload) returns an ordered dictionary of named booleans. Each boolean is true only when one surface of the card satisfies its own contract: the six reader-route ids match REQUIRED_ROUTE_IDS, the reader menu and the landing packets cover those same ids, the evidence-class legend is complete, the scale counts are honest integers. A missing or malformed surface yields a false check. It never raises.

Scanning the card against its standard

_standard_backed_first_screen_scan confirms the card's routes, copyable commands, and six false denied-authority flags all match the standard, returning pass only when every check is true and never raising. _standard_backed_first_screen_scan(payload, standard, check_ids) then compares the built card against the standard it came from. It confirms the standard reference and validator id match, that every reader route is present across all four route surfaces, that each reader carries the exact copyable commands plectis hello --reader <id> <label> and its text-projection form, and that the six denied-authority flags in DENIED_AUTHORITY_KEYS are false in both the standard and the card. Those six keys are launch, source-file changes, non-public data equivalence, external model access, score-based progress, and whole-system correctness. The scan returns a record whose status is "pass" only when every check is true. On any drift it returns "blocked" with the failing check named. It never raises.

Folding the scan into status

The builder folds the scan status into the check set, sets status to pass only when every check is true, and still returns a blocked card in full so the failing check is visible. The builder folds the scan status into the check set, sets validation.status to "pass" only when every check is true, and copies that to the top-level status. A blocked card is still returned in full, so a reader can see which check failed.

Compact and text projections with budgets

first_screen_compact_card produces a budgeted summary card with an omission list, and first_screen_text_card produces a 33-line terminal card that raises rather than truncating when it would overflow. Two projections render the same card for different media. first_screen_compact_card(payload) produces a summary-first card under COMPACT_JSON_CARD_MAX_CHARS (16000) characters, with an omission list naming the full-contract keys it dropped and the plectis first-screen --full command that restores them. first_screen_text_card(payload, reader_id) produces a terminal card of at most TEXT_CARD_MAX_LINES (33) lines over the same scope limit. Passing reader_id="all" shows every branch; an alias focuses one. It raises ValueError when the reader id is unknown or when the assembled card would exceed the line budget, so an over-long text card is a hard failure, not a truncated screen.

The command-line wrapper

The wrapper scripts/first_screen_composition_card.py exposes the card with --root, --project-label, --format, and --reader, returning exit code 0 only when the card status is pass. The command-line wrapper scripts/first_screen_composition_card.py exposes this without the full console. build_parser defines --root, --project-label, --format (json or text), and --reader. main builds the card, prints the JSON contract or the reader-focused text card, and returns exit code 0 only when the card status is "pass".

flowchart TD A["Standard std_microcosm_first_screen_composition_root.json"] --> B["first_screen_composition_card assemble card packets"] B --> C["_validation_checks internal consistency"] B --> D["_standard_backed_first_screen_scan card vs standard"] C --> E["status: pass or blocked"] D --> E E --> F["first_screen_compact_card / first_screen_text_card JSON or terminal projection"]

Negative cases

What the checks force the card to reject

Mismatched reader ids fail reader_route_parity, a wrong copyable command fails copyable_reader_commands, a non-false denied-authority flag fails denied_authority_flags_false, and an over-33-line text card raises instead of printing. The scan and the checks name what the card must reject. A card whose reader branches do not match the six required ids fails reader_route_parity. A card missing a copyable per-reader command, or carrying a command that does not match the expected plectis hello --reader <id> string, fails copyable_reader_commands. A card where any of the six denied-authority flags is not false fails denied_authority_flags_false. A text card that would run past 33 lines raises instead of printing. Each of these is a blocked result with the failing check named, never a quiet pass.

Prior Art Grounding

Command-line usability and progressive disclosure

The card borrows from command-line usability practice, progressive disclosure, and W3C PROV: a concise shared command, a terminal card, a JSON contract, and evidence counts kept attached to their scope. The card borrows from command-line usability practice rather than inventing an onboarding genre. The Command Line Interface Guidelines argue for concise default help, worked examples, discoverable next commands, and machine-readable output. Those appear here as the one shared command, the terminal-sized card, and the JSON contract. The compression rule follows progressive disclosure: reveal enough to orient a reader without dumping the whole system, the pattern Nielsen Norman Group documents as progressive disclosure. W3C PROV informs the rule that evidence counts stay attached to their source and scope limit rather than becoming standalone scores.

Validation Result record Path

Reader-verifiable emitter commands, run from the microcosm-substrate/ public root:

PYTHONPATH=src ../repo-python scripts/first_screen_composition_card.py --project-label . --format json
PYTHONPATH=src ../repo-python scripts/first_screen_composition_card.py \
  --project-label . \
  --format text \
  --reader safety_evals_engineer

Focused tests, run from the repository root:

PYTHONPATH=src ./repo-pytest \
  tests/test_first_screen_composition_card.py \
  tests/test_cli_hello_first_screen.py \
  tests/test_readme_first_screen_entry.py \
  -q --basetemp /tmp/microcosm-first-screen-composition-tests

What a pass means here

A pass means the built card matched its standard and both projections stayed inside their budgets; the emitter writes no state and certifies no reader success or launch-scope decision. A pass means the built card matched its standard and the two projections stayed inside their budgets. The emitter writes no project state and prints the card to stdout. It does not certify that any reader will succeed or that the repository is ready to launch.