CLI: drop `-e` short alias for `--example` (AI-hallucination trap)

[yamcodes]

Summary

Drop the -e short alias for --example and make --example long-form only. The -e short flag is a semantic trap for AI agents and should be permanently reserved (never reassigned to --example again) in case we later want it for passing an explicit environment.

Problem

Across the broader CLI ecosystem (Docker, Kubernetes, standard Unix utilities), -e almost universally means --env / --environment. For a type-safe environment variable validation library, mapping -e to --example is a particularly sharp trap.

When an AI agent is asked to configure or override a variable, its training makes it instinctively reach for -e — e.g. arkenv init -e NODE_ENV=production. Today that silently binds to the unrelated --example project flag, which consumes the next token as the example name. The agent then observes behavior that doesn't match its intent, assumes a failure, and can get stuck in a retry/hallucination loop.

Current behavior

• --example has a short alias -e (a value-kind flag).
• arkenv init -e NODE_ENV=production is accepted and interpreted as "use example NODE_ENV=production", not as setting an environment variable.
• The alias is advertised in arkenv --help and in the CLI docs flags table.

Desired behavior

• --example works only in long form.
• The -e short alias is removed. Passing -e (standalone or inside a bundle like -ye) falls through to the existing standard Unknown argument: -e error — failing fast with no incorrect action taken.
• -e is treated as reserved: it must not be reassigned to --example (or any other flag) again, so it stays available for a future --env / --environment option.
• Help output and CLI docs no longer list -e.

Acceptance criteria

• arkenv init --example <name> continues to work exactly as before.
• arkenv init -e <name> is rejected with the standard Unknown argument: -e error.
• -e bundled with other short flags (e.g. -ye) is also rejected as an unknown argument.
• arkenv --help no longer lists -e for --example; it shows --example with no short alias.
• The CLI docs flags table no longer shows -e in the alias column for --example.
• Existing tests covering the --example/-e alias are updated; new coverage asserts -e is unknown while --example still works.
• A changeset is added: @arkenv/cli minor, documented as a BREAKING CHANGE (matching the precedent set when the -C/-a aliases were removed).

Out of scope

• Actually introducing a --env / --environment option under -e. This issue only reserves -e; it does not implement a new flag.
• Any change to -y, -q, -j, -H, or -h, which all align with standard Node/POSIX conventions.

Follow-up after merge

This lands on dev (v0) first. After the dev PR is merged, run /forward-port to adapt the change onto the v1 branch (packages/cli/src/** → packages/arkenv/src/**, changeset key @arkenv/cli → arkenv) so v1 keeps parity.

[pullfrog]

This run croaked 😵

The workflow encountered an error before any progress could be reported. Please check the link below for details.

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[yamcodes]

Agent Brief

Category: enhancement
Summary: Remove the -e short alias for --example so --example is long-form only, and permanently reserve -e.

Current behavior:
The CLI recognizes -e as a short alias for the --example value flag. arkenv init -e foo is parsed as "use example foo". The alias is a value-kind flag (it consumes the following token), and it is advertised both in arkenv --help output and in the CLI docs flags table. Because -e almost universally means --env/--environment elsewhere, AI agents frequently reach for arkenv init -e NODE_ENV=production, which silently binds to --example and produces behavior that doesn't match intent.

Desired behavior:
--example should be accepted only in its long form. The -e short alias should be removed entirely so that passing -e — standalone or bundled with other short flags — produces the CLI's standard Unknown argument: -e error, failing fast with no incorrect action. -e must be treated as reserved: do not reassign it to --example or any other flag, keeping it free for a possible future --env/--environment option. Help text and CLI docs must stop listing -e.

Key interfaces:

• The CLI's flag-configuration object (the single source of truth mapping long flags to short aliases and their kind). The --example entry should keep its long form and value kind but drop its short alias. Removing the alias must automatically flow through the derived sets of known flags and valued flags, the bundled-short-flag expansion, and the example accessor — so no code path continues to accept -e.
• The help command's rendered flag list, which mirrors the flag config and must no longer show -e for --example.
• The CLI docs flags table (MDX), which must drop -e from the alias column for --example.

Acceptance criteria:

• arkenv init --example <name> works exactly as before.
• arkenv init -e <name> is rejected with the standard Unknown argument: -e error.
• -e bundled with other short flags (e.g. -ye) is also rejected as an unknown argument.
• arkenv --help shows --example with no short alias.
• The CLI docs flags table no longer lists -e for --example.
• Tests are updated: assertions that -e maps to --example are removed/replaced, and new coverage asserts -e is unknown while --example still works.
• A changeset is added for @arkenv/cli as a minor bump documented as a BREAKING CHANGE, mirroring the -C/-a removal changeset.

Out of scope:

• Implementing a new --env/--environment option under -e; this issue only reserves -e.
• Any change to the -y, -q, -j, -H, or -h aliases.

Follow-up after merge:
This targets dev (v0). Once the dev PR is merged, run /forward-port to bring the change to the v1 branch — re-implement at v1 paths (packages/cli/src/** → packages/arkenv/src/**) and rename the changeset key @arkenv/cli → arkenv.