Your first local result #

Start without hardware. The first-run example demonstrates the shared core and immutable evidence with verified prebuilt PRG/map/ELF inputs and a deterministic fake target. It does not compile C64 source or emulate its instructions.

Prerequisites by workflow #

Workflow	Required tools	What it proves
Packaged first-run example	Linux host binary, Python 3	Fake orchestration, diagnostics and evidence
Build Ultimate Tool from source	Rust 1.93, Cargo	Host binary build and tests
Rebuild the accepted C64 fixtures	Python 3, Docker and pinned Rust-MOS image	Compiler outputs from the checksummed accepted SDK build inputs and source provenance
Execute in VICE	VICE 3.8 and an executable C64 artifact	Emulator program behavior
Execute on Ultimate	Intended supported device on trusted LAN, fresh identity and authorization	That device's observed program behavior

No environment check or fake command grants device authorization. Display, audio, raster, input and other hardware-dependent claims need suitable real observations, not an emulator pass.

Build the host tool today #

cargo build --locked -p ultimate-tool

Use target/debug/ultimate-tool or install a reviewed release binary when a release is available. The Linux preview distribution and CI are being prepared; this guide does not imply public downloads already exist.

Exercise the first-run example #

From the repository root:

target/debug/ultimate-tool validate --manifest examples/first-run/c64dev.toml
target/debug/ultimate-tool doctor --manifest examples/first-run/c64dev.toml --target fake
target/debug/ultimate-tool test smoke --manifest examples/first-run/c64dev.toml --target fake
target/debug/ultimate-tool test sdk-crash --manifest examples/first-run/c64dev.toml --target fake
target/debug/ultimate-tool runs list --manifest examples/first-run/c64dev.toml

smoke should pass. sdk-crash deliberately fails with exit 4 and preserves crash evidence; the failure is the demonstration, not a broken installation. Use the resulting run ID:

target/debug/ultimate-tool runs crash-report RUN_ID --manifest examples/first-run/c64dev.toml
target/debug/ultimate-tool runs report RUN_ID --manifest examples/first-run/c64dev.toml
target/debug/ultimate-tool runs report-items RUN_ID --section checkpoints --manifest examples/first-run/c64dev.toml
target/debug/ultimate-tool serve --manifest examples/first-run/c64dev.toml

runs report explains that run's recorded outcome and verified evidence without re-running it, and runs report-items pages one detail section; see diagnostic reports for the section list, paging cursor, and what each verdict means. Both are read-only.

Open the announced http://127.0.0.1:PORT URL to inspect history. Transport acceptance, observed test results and evidence are distinct. The server binds loopback only; do not expose it as a public hardware service.

The example's materializer reuses identical verified files safely. Reruns produce new immutable records, not updates to old ones. It fails explicitly on missing or altered snapshot inputs. The packaged source links are local project-relative provenance, not arbitrary host-file access.

See the example for the complete pass/crash/panic/pass sequence and source-rebuild boundary.

Bring your own project #

Start with an existing build command, PRG and bounded boot-screen expectation. No SDK instrumentation is required for screen observation. See existing-project onboarding, then portability tiers for optional symbols, budgets and mailbox instrumentation.

Troubleshooting #

doctor inspects local files/PATH without launching commands or contacting targets. not_checked is not a success claim; version and runtime behavior still need their actual execution gates.
A missing VICE executable does not prevent fake-target use.
A missing/altered first-run snapshot is a materialization error. Do not attach a map or ELF from a different PRG to make resolution appear to work.
Failures retain their layer: build, artifact, preflight, transport, deployment, protocol, assertion, or evidence. Keep the run ID and checksummed evidence.
Testing documents the host/browser/emulator/hardware layers.