[maui-labs docs] Document `maui go upgrade` command implementation

## Source PR

**PR**: https://github.com/dotnet/maui-labs/pull/233
**Title**: feat(go): implement `maui go upgrade` command
**Author**: David Ortinau (@davidortinau)
**Merged**: 2026-05-12

---

## Summary of Changes

The `maui go upgrade` CLI command was previously a stub that printed "Not implemented yet." PR #233 fully implements it.

`maui go upgrade` **graduates a Comet Go single-file program to a full .NET MAUI project**. It detects the Go source file (identified by `#:package Comet` directives), scaffolds a complete MAUI project structure alongside it, strips the `#:` directives from the original `.cs` file, and (optionally) verifies the result with `dotnet build`.

### New flags added

| Flag | Default | Description |
|---|---|---|
| `--force` | `false` | Overwrite known-generated files that already exist |
| `--dry-run` | `false` | Print the planned actions without writing any files |
| `--build` | `false` | Run `dotnet build` after scaffolding to verify the upgrade succeeded |
| `--keep-backup` | `true` | Back up the original `.cs` (and any overwritten files) under `.maui-go-backup/(timestamp)/` before modifying them |

### Upgrade behavior

1. Detects a single Comet Go `.cs` file in the current directory (fails if multiple `View` subclasses are present — v1 supports single-file programs only)
2. Pre-flight checks for file conflicts; refuses to overwrite unless `--force` is passed
3. Scaffolds: `Platforms/`, `MauiProgram.cs`, `App.cs`, `.csproj`, and resource files copied from the Comet project template
4. Strips `#:package`, `#:property`, and `#:sdk` directives from the original source file
5. Optionally backs up originals under `.maui-go-backup/(timestamp)/`
6. Optionally runs `dotnet build -f (host-tfm)` to verify compilation

The command prints a "Next:" hint after a successful upgrade, e.g.:
```
Upgrade complete.
Next:
dotnet build -t:Run -f net11.0-ios
```

---

## Documentation Pages Affected

- **CLI `maui go` reference** (if it exists): `docs/developer-tools/cli/go.md` or similar
- **Comet Go landing / quickstart**: wherever `maui go` commands are listed and described
- **`docs/TOC.yml`**: no new page needed if folded into an existing `maui go` page; otherwise add an entry

---

## Suggested Changes

### On the `maui go` commands reference page

Locate the section that lists `maui go` subcommands and update (or add) the `upgrade` row/description from the placeholder text to the actual behavior.

**Suggested command reference entry:**

````markdown
### `maui go upgrade`

Graduates a Comet Go single-file program to a full .NET MAUI project.

```shell
maui go upgrade [options]
```

#### Options

| Option | Default | Description |
|---|---|---|
| `--force` | `false` | Overwrite known-generated files if they already exist. |
| `--dry-run` | `false` | Preview the files that would be written without making any changes. |
| `--build` | `false` | Run `dotnet build` after scaffolding to verify the upgraded project compiles. |
| `--keep-backup` | `true` | Save a copy of the original `.cs` file (and any overwritten files) to `.maui-go-backup/(timestamp)/` before modifying them. |

#### What the upgrade does

1. Detects a single Comet Go `.cs` file in the current directory.
2. Verifies no file conflicts exist (use `--force` to overwrite).
3. Scaffolds a full MAUI project structure: `Platforms/`, `App.cs`, `MauiProgram.cs`, and `.csproj`.
4. Strips `#:` directives (e.g., `#:package Comet`) from the original source file — your `View` subclasses remain unchanged.
5. Optionally backs up originals and runs `dotnet build` to validate the result.

> **Note:** v1 supports single-file programs with exactly one `View` subclass. If your file defines multiple views, split them into separate files before upgrading.

#### Example

```shell
# Preview what will be written (no files changed)
maui go upgrade --dry-run

# Upgrade and verify it builds
maui go upgrade --build

# Re-run upgrade on a directory that was already partially upgraded
maui go upgrade --force
```
````

### If there is a "Comet Go" or "maui go" concept page

Add a section or callout explaining the graduation path: start with a single `.cs` file using `maui go serve`, then use `maui go upgrade` when ready to move to full MAUI.

> Generated by [PR Documentation Check](https://github.com/dotnet/maui-labs/actions/runs/25725259133) for issue #233 · [◷](https://github.com/search?q=repo%3Adotnet%2Fdocs-maui+is%3Aissue+%22gh-aw-workflow-call-id%3A+dotnet%2Fmaui-labs%2Fpr-docs-check%22&type=issues)

Start by locating the existing `maui go` reference, likely under `docs/developer-tools/cli/go.md`, and check related Comet Go quickstart content. Update the command reference with the implemented `upgrade` behavior, options, limitations, and examples; check `docs/TOC.yml` only if a new page is needed. Done means the documentation accurately reflects the merged command and its single-file limitation.

Written by the indexing model from the issue text.