# 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

```sh
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:

```sh
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:

```sh
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](DIAGNOSTICS.md) 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](../examples/first-run/README.md) 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](EXISTING_PROJECT.md), then
[portability tiers](PORTABILITY.md) 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](TESTING.md) documents the host/browser/emulator/hardware layers.