New dev feedback: the get-started programmatic path fails end-to-end

# Miden Foundry: new developer feedback

I went through the Foundry stack as a first-time user, following the official Get Started docs (docs.miden.xyz) from install through the CLI, the Rust SDK examples, and building a first smart contract. Binaries installed via `midenup`, run natively. Environment: midenup 0.15.0, node/protocol 0.15.3, macOS.

Short version: the CLI happy path is fine. Install, create a wallet, mint tokens, check balance, all works. The programmatic path is where it falls apart. Every card that touches the SDK or the compiler fails, and almost all of it traces back to the docs and the `miden new` template having drifted out of sync with the current 0.15 toolchain.

Every issue is rated blocker (couldn't continue), annoyance (lost time), or nit (minor).

## Blockers a newcomer hits

1. You can't build a contract by following the docs. The Create card tells you to run `miden build`, which doesn't exist (it forwards to `midenc` and errors "expected input file"). The real command is `cargo miden build`; the toolchain ships `cargo-miden` but doesn't put it on PATH as a `cargo miden` subcommand, so it fails with "no such command: miden" on a default install. (F10)
2. The SDK transaction examples don't run. `mint.rs` on the Notes & Transactions page doesn't compile as pasted (missing `miden-protocol` dependency), and once you fix that it dies at runtime on a transaction kernel assertion reported as a raw opaque code. (F6, F7)
3. Read Storage fails at runtime. `read-count.rs` hardcodes a counter account ID that no longer parses ("`0` is not a known account ID version"). (F8)
4. The first Get Started link 404s. The "Installation" card on the get-started page resolves to a missing page on a cold load. (F1)

## Issue summary

| # | Phase | Problem | Severity |
|---|---|---|---|
| F1 | install | "Installation" card on the get-started page 404s | blocker |
| F2 | cli-basics | `miden_core::mast` ERROR spam (from miden-vm) on every CLI command (up to 24 lines), commands still succeed | annoyance |
| F3 | cli-basics | `miden mint` prints "Note not found, retrying..." before succeeding | nit |
| F4 | cli-basics | `miden client init` fails ("config already exists") and the error help contradicts itself | annoyance |
| F5 | sdk accounts | First `cargo run` of an SDK example downloads a nightly toolchain and builds ~400 crates (~4 min) with no heads-up | nit |
| F6 | sdk notes | `mint.rs` / `consume.rs` / `send.rs` import `miden_protocol`, which the template omits, so they won't compile | blocker |
| F7 | sdk notes | After fixing F6, `mint.rs` compiles but fails at runtime on a transaction kernel assertion, reported as a raw opaque code | blocker |
| F8 | sdk read-storage | `read-count.rs` compiles but fails at runtime on a stale hardcoded account ID | blocker |
| F9 | smart-contract/create | Docs manifests don't match what `miden new` generates (missing section, wrong note namespace) | annoyance |
| F10 | smart-contract/create | No working build command: docs' `miden build` doesn't exist, and `cargo-miden` isn't on PATH as `cargo miden` by default | blocker |
| F11 | smart-contract/create | `increment-note` fails componentization (`fpi-get-count`) from version skew: contract SDK `miden` 0.13 vs 0.15 toolchain | blocker |

Doc pages: [get-started](https://docs.miden.xyz/builder/get-started), [cli-basics](https://docs.miden.xyz/builder/get-started/setup/cli-basics), [accounts](https://docs.miden.xyz/builder/get-started/accounts), [notes](https://docs.miden.xyz/builder/get-started/notes), [read-storage](https://docs.miden.xyz/builder/get-started/read-storage), [create](https://docs.miden.xyz/builder/get-started/your-first-smart-contract/create).

## Installation and first steps

### F1: first Get Started link 404s (blocker)

On the get-started page, the "Installation" (1. Set up) card links to `./setup/installation`. Because the page URL has no trailing slash, that resolves to `/builder/setup/installation` (the `get-started` segment drops out), which 404s. The link should point directly at [`/builder/get-started/setup/installation`](https://docs.miden.xyz/builder/get-started/setup/installation). It's intermittent: it reproduces on a cold load, in incognito, or after a hard reload, but once the Docusaurus client router has warmed up from browsing the site the same click resolves fine. The page itself exists; the link just resolves to the wrong path. No recent docs commits either, so this reads like a routing and caching problem.

## CLI basics

### F2: ERROR-level MAST spam on every CLI command (annoyance)

Every `miden client` command prints pairs of `miden_core::mast::serialization` ERROR lines ("UntrustedMastForest expected HASHLESS/STRIPPED input ..."). The volume scales with the command: `miden client account` printed about 12 pairs, so 24 ERROR lines, before the actual table. The commands all succeed (wallet created, mint worked, balance 1000), but a first-timer sees a wall of red ERROR before anything else and assumes something crashed.

The ERROR lines themselves are emitted by miden-vm (`miden_core::mast::serialization`), triggered by how the `miden client` CLI wrapper loads its artifacts: the programmatic SDK path emits none of these (running `cargo run --bin account`, with miden-client used directly as a library, produced zero MAST errors). Root cause looks like a MAST artifact format mismatch: loaded component code carries node hashes and DebugInfo the deserializer didn't expect, logged at ERROR when it should be handled quietly or downgraded.

### #F4: `miden client init` fails and its own help contradicts it (annoyance)

The config file gets auto-created on the first `new-wallet` ("Config file successfully created at .../miden-client.toml"). So when you reach the docs' explicit `miden client init --network devnet` step, it fails: "config error: The file miden-client.toml already exists in the global .miden directory ... Please remove it first." The error's `help:` text then says "If it does not exist, run `miden client init` command to create it", which is the exact command that just failed. A newcomer is stuck: remove the file? rerun init? skip the step? Fix: either don't auto-create on first use, or make `init` idempotent (a no-op with an "already initialized" message), and fix the contradictory help text.

### F3: confusing wording during mint (nit)

`miden mint` prints "Note not found, retrying in 5 seconds... (1/3)" before consuming the note on the next attempt. It works, but "not found" reads like a failure. Something like "waiting for note to be committed" would read better.

## Rust SDK examples (Accounts / Notes / Read Storage)

### F5: first build of an SDK example hangs with no heads-up (nit)

The first `cargo run --bin account --release` (running the `accounts.rs` SDK example, not the CLI `account` command) pulls a pinned nightly toolchain and compiles around 400 crates, roughly 4 minutes, before it runs. Normal for Rust, but the docs don't warn you, so someone who just copy-pasted the snippet watches the terminal sit there for minutes and assumes it hung. One line in the docs ("the first build downloads the toolchain and can take several minutes") would fix it. The example itself compiled and ran correctly (account ID printed, empty vault).

### F6: Notes and Transactions snippets don't compile (blocker)

`mint.rs`, `consume.rs`, and `send.rs` all do `use miden_protocol::asset::{AssetAmount, FungibleAsset, TokenSymbol};`, but the project `miden new` scaffolds doesn't list `miden-protocol` in `integration/Cargo.toml` (it has miden-client, miden-client-sqlite-store, miden-standards, miden-testing, miden-mast-package). So all three fail with `E0433: cannot find module or crate miden_protocol`. The Accounts card (`accounts.rs`) compiled because it only imports from `miden_client`.

Fix: add `miden-protocol` to the `miden new` template, or re-export those asset types from `miden_client` and update the docs to import from there. Workaround to keep going: `cargo add miden-protocol@0.15` (matches the transitively built 0.15.3).

### F7: `mint.rs` fails at runtime, with an unreadable error (blocker)

After the F6 workaround, `mint.rs` compiles, prints Alice's account ID and the faucet account ID, then dies:

```
Error: transaction execution failed
Caused by: failed to execute transaction kernel program:
× assertion failed with error code: 16269270600290497661
```

The example connects to testnet, creates a fresh local fungible faucet (`create_fungible_faucet` with a new seed), and mints from it. The mint transaction fails the kernel assertion. Following the docs verbatim, you can't finish the Notes and Transactions page. Either the example is stale against the 0.15.3 transaction kernel, or the freshly created faucet isn't in a valid state to mint. That needs a maintainer to confirm, it isn't something fresh eyes can debug. The CLI `miden mint` worked earlier against the real testnet faucet, so minting itself is fine. This SDK example is the thing that's broken.

On top of the failure itself, the error is unreadable: it surfaces as a raw u64 assertion code (16269270600290497661) with only generic help ("assertions validate program invariants..."), never saying which kernel check failed or how to fix it. The assertion codes should be mapped to human-readable messages.

### F8: Read Storage uses a stale address (blocker)

`read-count.rs` compiles cleanly (it only imports miden_client and miden_client_sqlite_store, so no F6 issue) but fails at runtime with `Error: `0` is not a known account ID version`. It hardcodes a counter-contract address, `AccountId::from_hex("0x224a96d294e10d006aef3d4f1b0876")`, that no longer parses under the current Account ID version encoding. Without a valid live counter account ID there's nothing the reader can do to make the card work.

One thing to flag above the individual bugs: two of the three programmatic Get Started cards (Notes and Transactions, Read Storage) fail at runtime because the examples are out of date. The mint example hits a kernel assertion, the read example uses a stale hardcoded ID. Only the Accounts card ran clean. The programmatic quick-start isn't being kept in sync with the current SDK and protocol.

## First smart contract (create / build)

### F9: docs manifests don't match the generated template (annoyance)

On the Create card, the `miden-project.toml` files shown in the docs differ from what `miden new counter-project` actually generates:

- counter-account: the docs manifest stops at `[dependencies]`. The generated file also has `[package.metadata.miden]` with `supported-types = ["RegularAccountImmutableCode"]`, which the docs omit.
- increment-note namespace differs. Docs: `miden:increment-note/increment-note@0.1.0`. Generated: `miden:increment-note/miden-increment-note@0.1.0`. The generated file even carries a comment explaining why: notes export a package-derived interface (`miden-`) to match the `#[note]` macro. So the docs version without the `miden-` prefix is stale, and hand-copying it would break the interface the `#[note]` macro expects.

Harmless if you use the generated files as-is. Copy the docs by hand and the build breaks. Same docs-vs-template drift as F6.

### F10: no working build command (blocker)

The Create card's build step doesn't work. In `contracts/counter-account`:

```
$ miden build
error: expected input file
Usage: midenc [OPTIONS] [FILE]
```

So `miden build` just proxies to `midenc`, the low-level compiler, with no input and errors out. It isn't a project build command. The actual project build tool also fails:

```
$ cargo miden build
error: no such command: `miden`
```

`cargo-miden` isn't on PATH as a `cargo miden` subcommand. The toolchain does ship it — it's at `$MIDENUP_HOME/toolchains/0.15.0/bin/cargo-miden` — but midenup only symlinks the `miden` porcelain onto PATH, not `cargo-miden`, so `cargo miden build` fails on a default install. Combined with the docs giving a non-existent command, a newcomer can't build either contract, and can't produce the `.masp` package the deploy step needs.

Confirmed by poking at the help:

- `miden --help` (the "Miden toolchain porcelain") lists only help commands. There's no `build` at all, so the docs' `miden build` isn't a real command and falls through to `midenc`.
- `miden build --help` prints midenc's help, whose `--release` flag is documented as "Build in release mode (used by `cargo miden build`)". So the intended command is `cargo miden build`.
- `cargo miden build` fails with "no such command: miden" because the toolchain's `cargo-miden` isn't on PATH (only `miden` is).

Fix: docs should say `cargo miden build`, and midenup should expose its `cargo-miden` on PATH as a `cargo miden` subcommand out of the box. Workaround I used: `cargo install cargo-miden`, then `cargo miden build`.

### F11: contract build fails on the note (blocker)

`cargo miden build` in `counter-account` succeeded and produced `counter-account.masp`, but `increment-note` failed to link:

```
error: linking with `wasm-component-ld` failed
error: failed to parse core wasm for componentization
... failed to merge interface `counter-contract`
expected function `fpi-get-count` to be present
```

The note calls the account over FPI (foreign procedure invocation), and its generated bindings expect `fpi-get-count`, which the counter-account's generated WIT doesn't provide. The cause is a version skew: the contract SDK crate `miden` resolves to 0.13.0 (the latest on crates.io) while the toolchain and protocol are 0.15.x (miden-protocol 0.15.3, sysroot 0.15.0). The 0.13 `#[account(...)]` / `#[note]` macros generate FPI bindings that don't match what counter-account 0.1.0 emits under 0.15. This reproduces with the toolchain's own `cargo-miden` (not just a manual install), so it's not a workaround artifact.

Net effect: the contract can't be fully built, so the Test and Deploy cards are blocked as well.

## Created issues

- **docs** — [0xMiden/docs#343](https://github.com/0xMiden/docs/issues/343) — Rust SDK examples (F6, F7, F8), the `cargo miden build` command (F10, docs side), the manifest drift (F9), the 404 (F1), and the first-build heads-up (F5).
- **project-template** — [0xMiden/project-template#54](https://github.com/0xMiden/project-template/issues/54) — the missing `miden-protocol` dependency (F6).
- **miden-vm** — [0xMiden/miden-vm#3425](https://github.com/0xMiden/miden-vm/issues/3425) — the ERROR-level MAST spam (F2). Confirmed still present in the latest miden-core (0.25.7): `log_untrusted_overspecification` still logs the HASHLESS case via `log::error!`.