Entry & orientation

cold_reader_route_map makes Microcosm's first ten minutes executable. It validates a public route map whose rows bind the first-run sequence to runnable commands, docs refs, result record refs, and scope limits.

Purpose

A cold technical reader should not have to infer the product path from a long README or raw result record tree. The route map answers one question: what should I run first, and what evidence proves that path is wired?

The unusual part is how the validator checks that proof. It does not merely confirm that each route row carries the right fields. It replays every route against real source: each row's command, its docs refs, its result record refs, and the human-readable signals it claims to show are matched against the actual text of copied source modules and public docs. A command whose material tokens do not appear anywhere in that source corpus is blocked, as is a docs ref that does not resolve to a real heading and a result record ref that does not open a pass-status result record. So a route cannot promise a command the system does not actually run, which is the failure mode a hand-written quick-start guide drifts into the moment the commands change underneath it.

The evidence contract is source-open by default: public route cards, route result record bindings, route policy, exported bundle refs, and generated result records carry the system, while secret_exclusion_scan excludes only private source bodies, model-output data, account or browser material, secrets, and account secret-equivalent live-access data. Result record bodies are not inlined; they are represented by body_in_receipt: false plus public runtime refs.

Shape

flowchart LR subgraph Entry["First-screen entry"] Project["Public project path repo -> .microcosm"] First["First-screen card claim frame, first command, evidence legend, exit rule"] end subgraph Accounting["Route-map accounting"] Route["Ordered route rows command, result record ref, evidence class"] Ceiling["Scope boundary and scope limit attached to each row"] end subgraph ReaderBranch["Reader branch"] Branch["Reader branch choose one first action"] Safety["Safety/evals status, authority, workingness"] Hiring["Hiring reviewer first-screen card, legibility scorecard"] Developer["Peer developer tour, observe, explain or compile"] end subgraph Boundary["Proof boundary"] Drilldown["Drilldowns tour, status, explain, observe, compile, serve"] Result record["Result records and route refs public refs only; body_in_receipt false"] end Project --> First First --> Route Route --> Ceiling Route --> Branch Branch --> Safety Branch --> Hiring Branch --> Developer Safety --> Drilldown Hiring --> Drilldown Developer --> Drilldown Ceiling --> Result record Drilldown --> Result record

Reader Evidence Routing

Start with core/paper_module_capsules.json::paper_modules[13:paper_module.cold_reader_route_map], then read the generated JSON projection for the resolved relationships. A diagram view is generated for this module and an atlas card entry is available. The route-map fixture, exported bundle, source-module manifests, and temporary result records are evidence for replay shape. This Markdown gives cold readers the interpretation order, source-linked only.

Prior Art Grounding

This component is grounded in documentation systems that treat reader state and task shape as first-class. Diataxis separates tutorials, how-to guides, reference, and explanation so readers are not forced through one undifferentiated documentation pile. Knuth's literate programming is an older anchor for the idea that executable systems should be written for human comprehension as well as machine execution.

Microcosm borrows the reader-route pattern: first command, result record ref, evidence class, scope boundary, scope limit, and next drilldown are ordered for a cold reader. It does not make the route map source authority or substitute documentation sequence for validator evidence.

Reader-Specific Evidence Routing

The route map should make the evidence-count frame visible before the reader chooses a drilldown. Honest counters are not progress badges:

• A safety/evals engineer follows microcosm status --card, microcosm authority --card, and microcosm workingness --card first. The useful question is whether each claim names its evidence class, validator, failure mode, and scope limit.
• A hiring reviewer follows the first-screen card and legibility scorecard first. The useful question is whether small verified counts are framed as honest proof boundaries instead of hidden or inflated.
• A peer developer follows microcosm tour --card, microcosm observe --card, and then full microcosm observe, microcosm compile, or microcosm explain as drilldowns. The useful question is whether a fresh clone can reproduce the route/work/event/evidence chain locally without opening full event rows first.

The route map must therefore preserve both the command order and the evidence interpretation order: command, result record ref, evidence class, scope boundary, scope limit, then deeper route. Reader-specific branches may hide other branches, but they may not hide the accounting frame that prevents "1 verified import" from being read as either failure or marketing.

One-Screen Handoff Contract

The route map consumes the first-screen card as the handoff, not as another route row. A cold reader should see this sequence:

1. First-screen card: claim frame, microcosm hello <project>, shared proof, evidence legend, structural join, reader rail, and exit rule.
2. Route map: the accepted command order, with result record refs and scope limits attached to each command.
3. Reader branch: one audience-specific first action, one proof surface, one success criterion, and one next drilldown.

The handoff fails when the first screen turns into a complete route inventory, or when the route map assumes the reader already understands evidence classes. The first screen should compress; the route map should sequence; the reveal should demonstrate the path against public result records.

Comparison-Backed Route Rows

Each route row should make the unusual discipline visible by naming the normal failure mode it is avoiding. The route map is not just a command list; it is a sequence of claim-boundary checks:

Rows that omit the comparison cue are still technically navigable, but they make the rigor invisible to a cold reader. The validator should prefer a shorter row with command, result record, class, scope boundary, and failure mode over a longer row that lists more components without explaining what each boundary prevents.

Observable Drilldown Order

Browser-first readers follow the same route map as terminal-first readers. The route order is compressed, not replaced:

1. First-screen card or compact browser board.
2. microcosm tour --card <project> as the shared behavior proof.
3. Selected route plus work/event/evidence refs.
4. Compact observatory view for the same route.
5. Full route map, result records, standards, and raw JSON drilldowns.

The compact observatory row must carry the same command ref, result record ref, evidence class, scope boundary, and scope limit as the terminal route row. If the browser board cannot show those fields, it is a preview only and cannot serve as the cold-reader route handoff.

readme_onboarding_route is the selected route only for projects with a README; folders without one still get a route/work/event/evidence path through the selected route emitted by tour and compile.

Each route card must include a command and public docs refs. Each route id must also resolve to at least one result record ref. The sequence must be ordinal sorted so the public entry does not drift into a bag of impressive but unordered components.

Validation

The fixture observes negative cases for missing command refs, missing result record refs, route sequence gaps, launch/provider overclaims, and private source body fields. The exported bundle omits negative cases and validates the real runtime shape used by microcosm run, with synthetic result record stand-ins explicitly disallowed as product evidence. If focused validation reports an exact-copy source-module body mismatch, route that repair through microcosm_exact_copy_refresh; do not treat this Markdown projection as the authority for copied source bodies.

Validation Result record Path

From microcosm-substrate/, reproduce this page's proof boundary with temporary result records:

The focused pytest file is the proof consumer for this Markdown section. It asserts the fixture status, ten-route command and result record-ref counts, front-door route order, expected negative cases, route-source replay support, exported bundle shape, copied source-module digest and anchor matches, source-open fixture-manifest counts, no source bodies in public result records, streamed line-count and digest handling, and fresh exported-bundle card reuse. The corpus check verifies that this page remains in the 98-module paper-module set and that the JSON bundle, generated Mermaid, Atlas card, and Markdown projection stay mutually consistent.

These result records validate the route-map fixture, exported bundle result records, copied cold-entry evidence, and paper-module corpus membership only; they do not grant route registry control, external model service, source-file changes, launch-scope decision, private-data equivalence, financial decisions, publishing-scope decision, hosted readiness, or whole-system correctness.

public_reveal_walkthrough is the accepted component that makes Microcosm's public reveal executable instead of descriptive.

It validates a ten-minute cold-reader path:

1. Compile a project into .microcosm/.
2. Inspect catalog, patterns, and routes.
3. Explain one route through patterns, standard pressure, work, events, and evidence.
4. Open the observatory causal chain before raw JSON drilldown.
5. Run microcosm intake to see the source projection intake cells connected to spine, reveal, and runtime evidence.
6. Read the result records and scope limit.

The component reads public fixtures from fixtures/first_wave/public_reveal_walkthrough/input/ and exported runtime input from examples/public_reveal_walkthrough/exported_public_reveal_bundle/.

It emits:

• receipts/first_wave/public_reveal_walkthrough/public_reveal_walkthrough_result.json
• receipts/first_wave/public_reveal_walkthrough/ten_minute_reveal_board.json
• receipts/first_wave/public_reveal_walkthrough/public_reveal_validation_receipt.json
• result records/sign-off/first_wave/public_reveal_walkthrough_fixture_acceptance.json

The reveal path treats microcosm intake as a runtime bridge rather than a private planning note. The command exposes runtime_reveal_import_bridge, keeps formal_math_readiness_extensions visible as a public replacement when its extension board exists, and points back to the source projection intake board without copying private source bodies.

Purpose

A cold reader meeting Microcosm for the first time needs one thing the README cannot give them on its own: proof that the first ten minutes are real and not a tour of screenshots. This component answers a single question. Can a reader who has never seen the system run a short, fixed path from a command to local state, to a route, to the result record and source boundary behind it, with nothing on that path that the system does not actually run?

The validator enforces that path as an accounting floor rather than a narrative. A reveal only passes if it carries at least five steps, four distinct runnable commands, and four evidence refs, and if four overclaim fixtures stay rejected: a launch or hosting claim, a private-data equivalence claim, a step with no evidence ref, and marketing copy with no command behind it. The floor exists because a walkthrough drifts towards a hero pitch the moment it is allowed to. Removing the commands and the result record refs is the easiest way to make a reveal look more impressive and prove less.

The part worth noting is the real-lane witness. The fixture run does not pass on its own paperwork. It is gated on the exported reveal bundle actually running, with its copied source bodies present and digest-verified. If that backing run is missing or blocked, the fixture is marked blocked too, with real_runtime_receipt set to false. So the reveal cannot describe a runnable path while the runnable path is broken underneath it, which is the quiet failure mode of every quick-start guide that says more than it can execute.

Shape

Public Reveal Walkthrough is the source-backed entry membrane for a cold technical reader. It turns the local Microcosm first-run path into a runnable accounting exercise: commands produce local state, routes point at work and events, evidence refs point at result records, and scope limits keep the visual or browser layer from becoming a product or public-sharing claims.

flowchart TD Bundle["JSON bundle paper_module.public_reveal_walkthrough"] Fixture["First-wave public reveal fixture 10-minute route + negative cases"] Bundle["Exported public reveal bundle 5 copied source bodies"] Runtime["Runtime component public_reveal_walkthrough.py"] Shell["Runtime shell bridge microcosm intake + public reveal view"] Result records["metadata-only result records result, board, validation, sign-off"] Reader["Cold reader route command -> route -> evidence refs -> ceiling"] Ceiling["Scope limit no launch, hosting, provider, or private-system claims"] Bundle --> Runtime Fixture --> Runtime Bundle --> Runtime Runtime --> Result records Runtime --> Shell Shell --> Reader Result records --> Reader Reader --> Ceiling

The runtime shape has five bounded inputs:

• the public reveal fixture under fixtures/first_wave/public_reveal_walkthrough/input;
• the exported reveal bundle under examples/public_reveal_walkthrough/exported_public_reveal_bundle;
• the source-module manifest for copied source bodies;
• the component source and focused tests that enforce command, evidence, and negative-case behavior;
• the standard and JSON bundle that bind the paper module to the mechanism, source locus, and scope limit.

The proof shape is route-first rather than dashboard-first. A valid reveal shows a command, a selected route, the route explanation through work/events/ evidence, result record refs, evidence-class counts, and the scope boundary beside any impressive total. Generated cards, observatory views, and browser/video boards are presentation layers over that accounting path.

The negative-case shape is part of the floor. launch or hosting overclaims, private-data equivalence, missing evidence refs, and marketing-only reveal material must remain rejected. If those refusals stop appearing, the reveal is no longer bounded enough for a cold reader.

The source-open shape is also bounded. The exported bundle carries five copied public bodies, and the manifest verifies exact-copy relation, digests, material classes, and metadata-only result records.

Evidence/accounting:

• Bundle authority: core/paper_module_capsules.json::paper_modules[paper_module.public_reveal_walkthrough] sets source_authority: json_capsule, binds the component, binds mechanism.public_reveal_walkthrough.validates_public_reveal_walkthrough, and resolves src/microcosm_core/organs/public_reveal_walkthrough.py.
• Generated instance: paper_modules/public_reveal_walkthrough.json reports source_authority: json_capsule, Mermaid available_from_capsule_edges, Atlas linked_from_capsule_edges_after_atlas_binding, 20 relationship edges, and a resolved paper_module.depends_on.paper_module edge to paper_module.first_screen_composition_root because the reveal path spends the first-screen composition contract before deeper route/evidence drilldown.
• Runtime and shell consumers: src/microcosm_core/organs/public_reveal_walkthrough.py exposes run, run_reveal_bundle, _source_module_manifest_result, _source_open_body_import_summary, EXPECTED_NEGATIVE_CASES, AUTHORITY_CEILING, and PUBLIC_SAFE_SOURCE_BODY_CLASSES. src/microcosm_core/runtime_shell.py routes the exported reveal bundle through public_reveal_walkthrough.run_reveal_bundle and publishes the public_reveal_view runtime lens.
• Result record and test floor: receipts/first_wave/public_reveal_walkthrough/public_reveal_walkthrough_result.json, ten_minute_reveal_board.json, public_reveal_validation_receipt.json, and result records/sign-off/first_wave/public_reveal_walkthrough_fixture_acceptance.json are metadata-only evidence. tests/test_public_reveal_walkthrough.py checks the fixture path, exported-bundle path, source-module digest validation, negative cases, and public-relative result record posture.
• Claim boundary: standards/std_microcosm_public_reveal_walkthrough.json, the generated structured source record, and this page limit the module to public reveal walkability, route/evidence accounting, exact-copy public source-body import evidence, negative-case rejection, and metadata-only result records. They do not include launch operations, hosted deployment, public sharing, recipient work, external model access, secret export, private-system equivalence, source-file changes, Lean/Lake execution, or whole-system correctness.

Source-Backed Mechanism

The source mechanism is mechanism.public_reveal_walkthrough.validates_public_reveal_walkthrough in core/mechanism_sources.json.

The runtime locus is src/microcosm_core/organs/public_reveal_walkthrough.py. The source symbols that matter for cold-agent drilldown are:

• run
• run_reveal_bundle
• _source_module_manifest_result
• _source_open_body_import_summary
• EXPECTED_NEGATIVE_CASES
• AUTHORITY_CEILING
• PUBLIC_SAFE_SOURCE_BODY_CLASSES

The governing standard is standards/std_microcosm_public_reveal_walkthrough.json. Its paper_module_contract binds this Markdown module to core/paper_module_capsules.json#paper_module.public_reveal_walkthrough and to the mechanism row above.

The atlas source row is intentionally not claimed as complete in this pass: core/organ_atlas.json is the source surface that must later receive paper_module_ref, mechanism_refs, and code_loci for this component. The re-entry capture is cap_quick_public_reveal_atlas_edge_population_wait_147e39c7a896.

Source-Open Body Imports

The exported reveal bundle carries five copied source bodies under examples/public_reveal_walkthrough/exported_public_reveal_bundle/source_modules/. The authority manifest is examples/public_reveal_walkthrough/exported_public_reveal_bundle/source_module_manifest.json.

The copied materials are:

All five rows are exact-copy imports, body_in_receipt=false, and digest checks must pass before the exported reveal bundle can count as source-backed. Result records may name refs, hashes, counts, and verdicts; they do not embed copied body text.

First Commands

From microcosm-substrate/, the first fixture command is:

The exported bundle command is:

PYTHONPATH=src python3 -m microcosm_core.organs.public_reveal_walkthrough run-reveal-bundle --input examples/public_reveal_walkthrough/exported_public_reveal_bundle --out receipts/runtime_shell/demo_project/organs/public_reveal_walkthrough --card

Focused regression:

PYTHONPATH=src ../repo-pytest tests/test_public_reveal_walkthrough.py -q --basetemp=/tmp/microcosm-public-reveal-pytest --ignore-host-pressure

Evidence Counts In The Reveal

The reveal board should not ask a cold reader to decode evidence-class numbers from context. When the walkthrough shows source-open body material counts, verified import counts, subprocess witnesses, algorithmic projection counts, or rows with source imports, it should pair each number with the evidence class and the scope boundary:

• Counts prove that the public route exposes an inspectable accounting surface.
• Counts do not prove launch-scope decision, whole-system correctness, or equal evidence depth across every component.
• A small high-authority count is stronger than a large low-authority count for the claim it actually covers.
• Generated or projected rows are reveal handles; source files, validators, result records, and scope limits remain the proof surfaces.

This keeps the public reveal from becoming a dashboard of impressive totals. The first reveal task is to show how a reader can move from number to result record to source boundary without crossing into private bodies, model-output data, account or browser state, or launch claims.

Reveal First View

The reveal board should open with the same compression grammar as the first-screen card, then widen only after the reader has a route to inspect:

1. Restate the bounded claim frame.
2. Show the command that produced the local state.
3. Show one route explanation with result record refs.
4. Show the evidence-count legend beside the result record refs.
5. Show the scope limit before any totals, drilldowns, or observatory links.

This gives video-first or browser-first readers a visible artifact without turning the reveal into a marketing hero. Motion, screenshots, and observatory views are allowed presentation layers only when the same evidence legend, scope boundary, and result record refs remain on the first view.

Discipline In The Reveal

The reveal should make discipline legible as prevented failure, not as a wall of policy labels. Before showing totals or motion, the board should pair each impressive-looking artifact with the boundary that keeps it honest:

If the reveal cannot show those boundaries on the first view, it should defer the visual flourish and keep the compact result record-backed route visible instead.

Prior Art Grounding

The public reveal path is grounded in first-run CLI and progressive-disclosure practice. The Command Line Interface Guidelines motivate a single runnable command, examples, discoverable next steps, and machine-readable output. Nielsen Norman Group's progressive disclosure pattern motivates showing the bounded first route before expanding into full observatory or JSON drilldowns.

The reveal's evidence walk also borrows from provenance and tracing patterns: W3C PROV for moving from artifact to source and result record, and OpenTelemetry traces for representing causal chains as inspectable linked work. Microcosm applies those patterns to a local walkthrough so the visual board remains evidence accounting, not a launch or maturity claim.

Browser/Video Reveal Board

The reveal board is the public visual candidate for a 60-second walkthrough. It must therefore be more than raw JSON, but it must still be less than a product claim. The first browser/video frame should show:

1. The command that produced the local state.
2. The selected route and one-line route reason.
3. The route explanation through work, events, evidence, and result record refs.
4. The evidence legend, including evidence class and scope boundary.
5. The compact observatory or first-screen endpoint used for the board.
6. The scope limit before totals, motion, or full-model drilldown.

Motion is allowed to make the causal order easier to inspect: command to local state, local state to selected route, selected route to work/event/evidence, and evidence to result record or validator. Motion is not allowed to displace the command, result record/evidence ref, scope boundary, or scope limit from the first view.

The board should end by offering exactly three next steps: reader-specific branch, result record drilldown, and full observatory JSON. That keeps the visual surface from expanding into a second README while still making the public reveal inspectable by readers who will not start in the terminal.

The validated claim is narrow:

> Microcosm turns a repo into a local operating system: patterns, routes, > work transactions, events, evidence, and explanations.

Negative fixtures reject launch or hosting overclaim, private-data equivalence, missing evidence refs, and marketing-only reveal material without runtime commands.

Reader Evidence Routing

• Start with the first commands and the JSON Bundle Binding to identify the fixture, exported bundle, source record, mechanism row, standard, and result record surfaces.
• For behavior questions, read src/microcosm_core/organs/public_reveal_walkthrough.py and tests/test_public_reveal_walkthrough.py before trusting this prose.
• For source-open body questions, read the exported bundle's source_module_manifest.json; it is the evidence for exact-copy relation, digest match, material class, and metadata-only result record posture.
• For visual or browser walkthrough questions, read the evidence legend, result record refs, scope boundary, and scope limit before reading totals, observatory links, or motion as meaningful.
• Treat generated atlas docs, generated coverage projections, generated result records, copied-body presence, and browser/video boards as navigation or validation projections. They do not become source authority for launch, hosting, provider, private-system-equivalence, or whole-system claims.

Validation Result record Path

PYTHONPATH=src ./repo-pytest tests/test_public_reveal_walkthrough.py -q --basetemp=/tmp/microcosm_public_reveal_walkthrough_pytest --ignore-host-pressure
./repo-python scripts/build_doctrine_projection.py --check-paper-module-corpus