Starter Pack migration guide uses a macOS-only edit and skips explicit dry-run/apply

[benagentai93-dot]

Baseline

5a306f8956cb1eeae69f9709de0e4d61b44e11e7 (v1.3.1)

Reproduction

1. Check out the baseline commit.
2. Open docs/src/reference/from-agent-starter-pack.md.
3. Follow the "Migrating an Existing Project" steps on Linux, or inspect which commands are read-only versus mutating.

Actual behavior

The guide makes sed -i '' the primary edit command. That syntax is specific to BSD/macOS sed and fails on common GNU/Linux environments. It then runs agents-cli info and describes migration as if it will happen implicitly, without an explicit preview and apply sequence.

Expected behavior

The primary flow should be portable and make mutation explicit:

1. agents-cli info reads the current state.
2. agents-cli scaffold upgrade --dry-run previews the migration.
3. agents-cli scaffold upgrade applies it.

Minimal fix

Tell users to rename the two TOML section headers in their editor, document the three commands above in order, and add a lightweight contract test that verifies the commands/flag exist and prevents the macOS-only sed command from returning.

Tested fix:

• Fork branch: https://github.com/benagentai93-dot/agents-cli/tree/codex/batch-5-doc-skill-consistency
• Root-cause commit: benagentai93-dot@4ea60bf

Verification

• Documentation contract tests: 7 passed
• Full test suite: 99 passed
• ruff check src tests: passed
• ty check src: passed
• uv build: passed
• Built wheel installed normally; agents-cli --version returned 1.3.1 on Python 3.11 and 3.13

I am not opening a PR because the upstream repository currently does not accept PRs.