feat(app): add app --instance flag, deprecate app-instance command

[Ducksss]

Summary

Collapses the two co-equal Codex Desktop launch commands into one verb with an opt-in flag:

• codex-profile app <profile> — unchanged default: quit + relaunch the stock, notarized Codex.app (one window).
• codex-profile app <profile> --instance [--rebuild] — the parallel clone path (experimental, macOS).
• --rebuild errors unless combined with --instance.
• codex-profile app-instance … — kept as a hidden, deprecated back-compat alias that forwards to app --instance (same code path). Existing scripts/muscle memory keep working.

Why a flag, not two commands

"Launch alongside" is a modifier on "launch Codex for a profile," not a different operation — matching how GUI apps expose parallel/multi-profile launch (Firefox -no-remote, Chrome/VS Code --user-data-dir). Keeping the name --instance stays consistent with the existing logs --instance and CODEX_PROFILE_APP_INSTANCE_ROOT, and demoting parallel to opt-in keeps the safe/cheap/notarized path as the default.

Changes

• bin/codex-profile: parser split into run_app_switch / run_app_instance; alias; help text; macOS-only messaging; bash/zsh/fish completions (drop app-instance from advertised lists, add --instance/--rebuild, keep alias completable).
• Docs lead with app, present --instance as opt-in, demote app-instance: README.md, SECURITY.md, AGENTS.md, docs/llms.txt, docs/index.html, docs/geo-measurement.md.
• CHANGELOG.md: 0.5.0 entry (Changed + Deprecated).
• Version bump to 0.5.0 across package.json, bin/codex-profile, and docs/index.html (drift guard enforces all three match).

Tests

• make lint clean; shell suite 54/54; geo-site + npm-package smoke tests pass.
• New: app --instance launch, app-instance alias still works, --rebuild without --instance errors.

Release (manual, after merge)

Tag v0.5.0 to trigger the npm publish workflow; check the Homebrew tap picks up 0.5.0.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR consolidates Codex Desktop launching into a single app command with an opt-in --instance mode, while keeping app-instance as a deprecated compatibility alias. It updates the CLI parser, docs, and tests, and bumps the release to 0.5.0.

Changes:

• Add codex-profile app <profile> --instance [--rebuild] [workspace] and route app-instance through the same code path as a deprecated alias.
• Update documentation and site content to lead with app --instance and demote app-instance.
• Add test coverage for --instance, the app-instance alias, and --rebuild requiring --instance, plus bump version to 0.5.0 across release surfaces.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
bin/codex-profile	Implements app --instance flag parsing, routes deprecated app-instance alias, updates help text and shell completions.
test/codex-profile-test.sh	Adds tests for app --instance, app-instance alias behavior, and --rebuild validation; updates completion expectations.
README.md	Updates primary usage examples and command reference to app --instance and documents the deprecated alias.
SECURITY.md	Updates isolation/security wording to reference app --instance instead of app-instance.
CHANGELOG.md	Adds 0.5.0 entry documenting the change and deprecation.
package.json	Bumps package version to 0.5.0.
docs/index.html	Bumps softwareVersion and updates site copy/examples to app --instance.
docs/llms.txt	Updates AI-facing quickstart example to app --instance.
docs/geo-measurement.md	Updates GEO Q/A answer to reference app --instance.
AGENTS.md	Updates agent guidance examples to use app --instance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.