docs: document --flutter-version=fvm and =system

[eseidel]

Description

Adds a "Match the Flutter version you already use" section to getting-started/flutter-version.mdx, covering the two --flutter-version aliases added in shorebirdtech/shorebird#3932:

• --flutter-version=fvm — uses the version fvm resolves for the project (from its .fvmrc).
• --flutter-version=system — uses the version reported by the flutter on your PATH.

The section makes the key point explicit, since it's the thing users are most likely to get wrong: Shorebird resolves the alias to a version number and then builds with Shorebird's fork at that version. It does not build with your fvm or system Flutter install, so the version still has to be one Shorebird supports.

The :::note covers what each alias needs to work:

• fvm on PATH. Shorebird asks fvm api project for the project's pin first, which answers without running Flutter. A channel (stable) or fork-ref pin falls back to fvm flutter --version, which may install that Flutter first and take several minutes.
• flutter on PATH for =system, which a Shorebird-only user won't have, since Shorebird's private copy at ~/.shorebird/bin/cache/flutter is explicitly not meant to be on PATH.

Gated on Shorebird 1.6.123, the first release containing shorebirdtech/shorebird#3932 (dea22a5), published 2026-09-21.

Context: shorebirdtech/shorebird#1385 asked for fvm support "and/or at least docs on how they're supposed to work together" — this is the docs half.

[AbhishekDoshi26]

Reviewed against what actually shipped in shorebirdtech/shorebird#3932. The core explanation on this page is correct and is the thing users most need, but the HOLD still applies, and one claim about how fvm resolution works does not match the merged implementation.

I've pushed two commits to this branch: main merged in (it was 24 commits behind), and the cspell fix described below. CI should be green now.

The HOLD is still active: merged is not released

The description gates this on shorebirdtech/shorebird#3932 landing and being in a released CLI. Only the first half is true today:

shorebird#3932 merged	2026-09-17 17:23 UTC, as dea22a5
Latest CLI release	v1.6.122, published 2026-09-16 15:59 UTC
compare/v1.6.122...dea22a5	status: ahead, ahead_by: 1

So the release tag does not contain the commit. The feature is on main but in nobody's hands.

If this merges before v1.6.123 ships, a reader who copies the command gets the alias passed straight through to resolveFlutterRevision, which fails with:

Version fvm not found. Please open an issue to request a new version.
Use `shorebird flutter versions list` to list available versions.

That's a rough landing for someone who just read the docs telling them to type it. Happy to watch for the release and ping this PR when the tag actually contains dea22a5.

What I verified as correct

The paragraph at lines 123-126 is the most load-bearing part of the section, and it holds up against the merged code:

• system really does read the flutter on PATH. getSystemVersion() runs with useVendedFlutter: false. Worth noting this was exactly the bug in the earlier #3238 attempt, where _resolveExecutable rewrote flutter to Shorebird's own binary and made the flag a no-op. This PR's wording describes the fixed behavior.
• "It does not build with your fvm or system Flutter install" is right. The reported version goes through the normal version-to-revision lookup, so the build uses Shorebird's fork at that version.
• "the version has to be one Shorebird supports" is right, and #3932 went a little beyond its original scope to make it true: assertArgsAreValid now resolves the alias, so the minimumFlutterVersion check applies to fvm/system instead of silently skipping.
• --flutter-version is still release-only. patch_command.dart has no such option, so the existing note above this section stays accurate.

Spell-check (fixed on this branch)

fvmrc was flagged at flutter-version.mdx:116:60, and it was the only red check. I added it to the alphabetical words: list in .cspell.yaml:

  - frontmatter
  - fvmrc
  - gallego

fvm on its own already passes via the shared allowed dictionary, so only fvmrc needed adding. This mirrors what #3932 did to cspell.config.yaml in the shorebird repo. Verified locally: cspell, Vale, prettier, the component-label linter, and a full astro build with link validation all pass.

Still needs your attention

The :::note at lines 130-131 describes the fallback path as though it were the normal one, and omits the part users will actually feel. Details in the inline comment.

One optional addition: on success the CLI prints Using Flutter 3.32.4, as reported by `flutter --version`. A sentence pointing at that line would let users confirm the alias resolved to what they expected, which is handy when an .fvmrc isn't where they thought it was.

[AbhishekDoshi26]

Checked the prose against the merged implementation in shorebirdtech/shorebird#3932 (ShorebirdFlutter.getFvmVersion/getSystemVersion and ReleaseCommand.resolveFlutterVersionArg). The framing is right: resolving the alias to a version number and then building with Shorebird's fork at that version matches the code, and the supported-version constraint is real since assertArgsAreValid resolves the alias before the minimumFlutterVersion check.

Three things to correct, all in the new section. I've pushed a commit applying them.

Also confirmed the .cspell.yaml addition is needed: stripping fvmrc and re-running cspell flags it at line 116, so that hunk stays.

[AbhishekDoshi26]

The HOLD is cleared: Shorebird 1.6.123 shipped 2026-09-21 and its tag contains dea22a5, with origin/stable pointing at that release commit, so shorebird upgrade delivers the aliases today.

Everything from my earlier review is applied: the fvm :::note now describes fvm api project as the normal path and warns that a channel or fork-ref pin falls back to fvm flutter --version and may install Flutter first, the duplicated patches sentence is trimmed, and the section is gated on 1.6.123. Also added the =system PATH prerequisite, since a Shorebird-only reader won't have a flutter on PATH, and the resolved-version confirmation line.

Verified against origin/stable of shorebirdtech/shorebird. All four checks green.