Document Go CLI migration state and usage

[mrjf]

Summary

Add a README or README section that explains the current Python-to-Go CLI migration state and gives maintainers/users clear instructions for trying the Go CLI today.

Current state to document

• The Crane Python-to-Go migration PR was merged in [Crane: crane-migration-python-to-go-full-apm-cli-rewrite] #91.
• The migration issue Crane Migration: Python to Go -- Full APM CLI Rewrite #78 is marked crane-completed.
• The restored migration workflow now verifies Python-vs-Go parity with APM_PYTHON_BIN set.
• The latest verified parity evidence shows migration_score=1, progress=1, and 706/706 parity tests passing.
• The migration benchmark workflow now uploads migration-benchmark-evidence with Python-vs-Go CLI timing results.
• The smoke benchmark currently shows the Go CLI roughly 327x-370x faster than the Python CLI for startup/help/init style commands.

README should explain

• What implementation is authoritative today: Python remains present as the reference/oracle while the Go CLI exists under cmd/apm.

• How to build the Go CLI locally:

  go build -o ./dist/apm-go ./cmd/apm

• How to run the Go CLI locally:

  ./dist/apm-go --help
  ./dist/apm-go init --yes

• How to run the definitive parity check locally when the Python CLI is installed:

  uv sync --extra dev
  export APM_PYTHON_BIN="$PWD/.venv/bin/apm"
  go test ./...
  go test -json ./... | go run .crane/scripts/score.go

• How to run the Actions check manually:

  gh workflow run migration-ci.yml --repo githubnext/apm --ref main

• Where to find benchmark evidence in Actions: the Migration Benchmarks job summary and the migration-benchmark-evidence artifact.

Implementation notes

• Prefer a short top-level README section if the repository already has a README; otherwise create a dedicated migration README and link it from the top-level README.
• Keep the wording explicit about what is verified versus what is still not a green gate. Python unit tests and Go parity tests pass; full historical Python integration/live/benchmark coverage is not the same thing as the migration parity gate.
• Include commands that can be copy-pasted.
• Link to Crane Migration: Python to Go -- Full APM CLI Rewrite #78, [Crane: crane-migration-python-to-go-full-apm-cli-rewrite] #91, and ci: ensure migration benchmark runs #93 for provenance.

Acceptance criteria

• A maintainer can read the README and understand the merged migration status without reading issue comments.
• A contributor can build and run the Go CLI locally.
• A contributor can run the parity check locally or dispatch it in Actions.
• The README points to the benchmark artifact location and explains the Go/Python ratio column.