@guiho/runx 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -15,6 +15,29 @@ owner: runx
 
 # Changelog
 
+## 0.2.4 - 2026-07-14
+
+### Added
+
+- Added Citty as the runtime CLI builder for typed commands, nested routing,
+  aliases, and generated usage.
+- Added end-to-end command-contract coverage for help, version, catalog,
+  agents, self-management, selector shorthand, and native/package behavior.
+
+### Changed
+
+- Replaced RunX's handwritten argument parser and top-level router with the
+  complete Citty command tree while preserving `runx r` and `runx <selector>`.
+- Updated public documentation, architecture, AGENTS instructions, and the
+  bundled RunX skill for the Citty-owned interface.
+
+### Fixed
+
+- Fixed `runx -v` and `runx -h` so they work outside configured projects
+  without attempting to discover `runx.yaml`.
+- Unknown options and missing required selectors now report relevant command
+  usage instead of unrelated manifest errors.
+
 ## 0.2.2 - 2026-07-14
 
 ### Changed

package/DOCS.md

@@ -26,6 +26,8 @@ lists its commands, and runs exactly one selected command.
 | Command | Purpose |
 | --- | --- |
 | `runx` | Show the home page and usage without loading a manifest. |
+| `runx -h`, `runx --help` | Show Citty-generated usage without loading a manifest. Append help to a command for command-specific usage. |
+| `runx -v`, `runx --version` | Show the installed version without loading a manifest. |
 | `runx list` | List all manifest commands. Add `--format json` for structured output. |
 | `runx describe <selector>` | Show one command's description and operational metadata. |
 | `runx check` | Validate discovery and the manifest without execution. |
@@ -34,11 +36,21 @@ lists its commands, and runs exactly one selected command.
 | `runx <selector>` | Human shorthand for `runx run <selector>` when no built-in name conflicts. |
 | `runx agents install <local|global>` | Install `guiho-s-runx`; add `--tool agents|claude|all` when needed. |
 | `runx agents instructions` | Add or refresh the managed RunX section in `AGENTS.md`. |
-| `runx upgrade [check|list]` | Check releases, list releases, or replace a native installed executable. |
+| `runx upgrade` | Replace a native installed executable when a newer release is available. |
+| `runx upgrade check` | Check whether a newer release is available. |
+| `runx upgrade list` | List recent release versions. |
 | `runx uninstall [--dry-run]` | Remove a native installed executable. |
 
 Global flags: `--cwd <path>`, `--file <path>`, `--format <text|json>`,
-`--verbose`, `--version`, `--help`, `--help-tree`, and `--help-docs`.
+`--verbose`, `-v`/`--version`, `-h`/`--help`, `--help-tree`, and
+`--help-docs`. Applicable command flags include `--dry-run`, `--yes`, and
+`--tool <agents|claude|all>`. Options may appear before or after their command.
+Unknown options and missing required arguments produce command usage instead
+of falling through to manifest discovery.
+
+Citty is the CLI parser, command router, alias registry, and ordinary usage
+renderer. RunX keeps its home page, extended command tree, and manifest guide
+as the explicit `runx`, `--help-tree`, and `--help-docs` surfaces.
 
 ## Manifest
 
@@ -114,6 +126,8 @@ macOS/Linux assets from GitHub Releases into the user's local bin directory.
 on Windows replacement is scheduled after RunX exits. `runx uninstall` removes
 the same native executable and supports `--dry-run`.
 
+When the latest GitHub Release matches the installed version, `runx upgrade` prints `Already up to date.` and exits successfully without downloading or scheduling executable replacement. JSON output reports `upToDate: true`.
+
 CI validates code and compiles the local executable plus the native release
 matrix. Protected `@guiho/runx@*` tags run the `production` publish workflow,
 which uploads twelve native assets to GitHub Releases and publishes the public

package/README.md

@@ -61,15 +61,21 @@ Then use RunX:
 
 ```text
 runx                         Show the home page and usage.
+runx -h                      Show Citty-generated command help.
+runx -v                      Show the installed version without loading a manifest.
 runx list                    List commands in the nearest manifest.
 runx describe app-dev        Explain one command without execution.
 runx run app-dev --dry-run   Inspect the execution plan.
 runx run app-dev             Execute the command.
 runx r app-dev               Use the short run alias.
+runx app-dev                 Use the human selector shorthand.
 ```
 
 Use `confirm: always` for commands that should require an explicit `--yes`.
 Use `runx list --format json` and stable UIDs for agent automation.
+RunX uses Citty for argument parsing, aliases, command routing, and ordinary
+usage text, so conventional `-h`/`--help` and `-v`/`--version` work outside a
+configured project.
 
 ## Documentation
 

package/docs/architecture/architecture.xdocs.md

@@ -1,10 +1,10 @@
 ---
 subject: runx-architecture
-description: Technical architecture for the RunX manifest, CLI, agent skill, and native distribution.
+description: Technical architecture for the RunX manifest, Citty command tree, agent skill, and native distribution.
 parent: runx-docs
 children: []
 files:
-  cli-architecture.md: Documents RunX component boundaries and execution flow.
+  cli-architecture.md: Documents Citty routing, RunX domain boundaries, safety invariants, and native distribution.
 documents:
   cli-architecture.md: Technical architecture for the first RunX CLI release.
 tags:
@@ -13,6 +13,7 @@ keywords:
   - runx
   - bun
   - cli
+  - citty
 flags: []
 status: stable
 ---

package/docs/architecture/cli-architecture.md

@@ -1,7 +1,7 @@
 ---
 name: RunX CLI Architecture
 purpose: Describe the component boundaries and data flow of the RunX alpha CLI.
-description: Explains manifest discovery, TypeBox validation, selector resolution, execution, agent installation, and native distribution.
+description: Explains Citty routing, manifest discovery, TypeBox validation, selector resolution, execution, agent installation, and native distribution.
 created: 2026-07-12
 flags:
   - approved
@@ -10,6 +10,7 @@ tags:
   - cli
 keywords:
   - runx
+  - citty
   - typebox
   - bun
 owner: runx-architecture
@@ -19,14 +20,20 @@ owner: runx-architecture
 
 ## Flow
 
-`cli.ts` parses a command and global flags. Manifest commands use `manifest.ts`
-to discover the nearest `runx.yaml`, parse YAML, validate a strict TypeBox
-schema, and resolve a selector. `render.ts` presents text or JSON. `executor.ts`
-spawns exactly one configured shell command only for a real run.
+`cli.ts` defines a Citty command tree. Citty parses options and positionals,
+resolves nested commands and aliases, and renders ordinary usage. A bounded
+command-map adapter preserves the legacy `runx <selector>` shorthand while
+known Citty commands retain precedence. Manifest commands use `manifest.ts` to
+discover the nearest `runx.yaml`, parse YAML, validate a strict TypeBox schema,
+and resolve a selector. `render.ts` presents text or JSON. `executor.ts` spawns
+exactly one configured shell command only for a real run.
 
 ## Boundaries
 
 - Inspection paths never call the executor.
+- Help, version, and CLI usage failures do not discover a manifest.
+- `source/flags.ts` no longer exists; RunX has no second token parser or manual
+  execution router behind Citty.
 - `agents.ts` copies the embedded or packaged skill into the requested standard
   or Claude-compatible skill location.
 - `self-management.ts` queries GitHub Releases and only replaces/removes a
@@ -35,5 +42,6 @@ spawns exactly one configured shell command only for a real run.
 
 ## Distribution
 
-Bun compiles standalone binaries. Direct installers select a GitHub Release
-asset; CI validates source and a native build but does not publish artifacts.
+Bun bundles Citty and compiles standalone binaries without a Node.js runtime.
+Direct installers select a GitHub Release asset; CI validates source and the
+native release matrix, while protected tags publish release artifacts.

package/docs/decisions/citty-cli-migration.md

@@ -0,0 +1,139 @@
+---
+name: RunX Citty CLI Migration
+purpose: Define the accepted replacement of RunX's handwritten argument parser and router with Citty.
+description: Records the full Citty command-tree migration, compatibility requirements, error behavior, validation scope, and patch-release boundary.
+created: 2026-07-14
+flags:
+  - accepted
+  - implemented
+tags:
+  - decisions
+  - cli
+  - typescript
+keywords:
+  - runx
+  - citty
+  - argument parsing
+  - command routing
+  - short flags
+owner: runx-decisions
+---
+
+# RunX Citty CLI Migration
+
+## Context
+
+RunX currently parses arguments and routes commands with repository-owned loops
+and conditionals. The parser recognizes only long options beginning with `--`,
+so conventional aliases such as `runx -v` and `runx -h` are treated as command
+selectors. That incorrect fallback causes global CLI operations to search for a
+`runx.yaml` manifest.
+
+Mirror and XDocs provide useful command semantics and help conventions, but
+both also maintain handwritten parsers. RunX will instead use Citty as the
+single parser, command router, alias registry, and usage generator.
+
+## Decision
+
+- Add `citty` as a runtime dependency and bundle it into native RunX builds.
+- Replace the handwritten parser in `source/flags.ts` and the manual routing in
+  `source/cli.ts` with a complete Citty command tree.
+- Do not introduce Commander, yargs, oclif, Clipanion, or a second parsing
+  abstraction around Citty.
+- Keep Bun as the development, test, build, and native-compilation toolchain.
+- Do not add a Node.js runtime dependency or an npm `postinstall` hook.
+- Release the completed migration as the next Mirror-managed patch after all
+  validation passes.
+
+## Command Tree
+
+The Citty tree must preserve the current public commands:
+
+```text
+runx
+|- list
+|- describe <selector>
+|- run <selector>
+|- r <selector>
+|- check
+|- agents
+|  |- install <local|global>
+|  `- instructions
+|- upgrade
+|  |- check
+|  `- list
+`- uninstall
+```
+
+`r` remains an alias of `run`. The human shorthand `runx <selector>` remains
+supported through the root command's positional selector compatibility path.
+Known Citty subcommands always take precedence over selector fallback.
+
+## Arguments and Help
+
+- Citty owns `-h`/`--help` and `-v`/`--version`.
+- Version and help must return without reading or discovering `runx.yaml`.
+- Preserve `--cwd`, `--file`, `--format`, `--verbose`, `--dry-run`, `--yes`,
+  `--help-tree`, and `--help-docs` where they apply.
+- Preserve `--tool agents|claude|all` for agent-skill installation.
+- Preserve JSON output contracts for successful commands and self-management
+  results.
+- Use Citty metadata and argument definitions as the source of ordinary command
+  usage text. Keep RunX's extended help tree and documentation guidance as
+  explicit custom outputs rather than duplicating Citty's ordinary help.
+
+## Implementation Boundaries
+
+- `source/cli.ts` owns the root Citty command and CLI entry function.
+- Command definitions may be grouped into focused modules for catalog,
+  agent, and self-management commands when that keeps `source/cli.ts` small.
+- Existing manifest parsing, selector resolution, execution, agent
+  installation, upgrade, and uninstall functions remain the business-logic
+  implementations. The migration changes their CLI adapters, not their domain
+  behavior.
+- Remove `source/flags.ts` after all consumers migrate to Citty.
+- Keep entrypoints thin: they register embedded native resources when needed
+  and invoke the Citty-backed CLI.
+
+## Error Behavior
+
+- Unknown options fail as CLI usage errors and never trigger manifest discovery.
+- Unknown explicit subcommands show relevant Citty usage.
+- A root positional that is not a known command is treated as the intentional
+  selector shorthand and may discover a manifest.
+- Missing command arguments show the specific command's usage.
+- Domain failures continue to use `RunXError` messages and non-zero exit codes.
+- Verbose mode may expose additional diagnostics, but normal errors remain
+  concise and actionable.
+
+## Testing
+
+Automated coverage must include:
+
+- `runx -v` and `runx --version` outside a configured project.
+- `runx -h` and `runx --help` outside a configured project.
+- Help and missing-argument behavior for each command group.
+- `runx run <selector>`, `runx r <selector>`, and `runx <selector>` compatibility.
+- Unknown flags and unknown explicit commands.
+- Existing global flags, JSON output, confirmation gates, and dry runs.
+- Agent install/instructions routing.
+- Upgrade check/list/apply and uninstall routing.
+- Typecheck, unit tests, library build, local native build, and the twelve-target
+  native binary matrix.
+
+## Documentation and Release
+
+Update public command documentation, the bundled `guiho-s-runx` skill, source
+descriptors, and release notes to match the Citty command tree. Validate the
+affected XDocs scopes before delivery. Use Mirror to plan and apply the next
+patch; never hand-edit the package version or create the release tag manually.
+
+## Acceptance Criteria
+
+- No RunX-owned argument-token loop or manual top-level command router remains.
+- `-v`, `--version`, `-h`, and `--help` work without a manifest.
+- Current commands and selector shorthand remain compatible.
+- Invalid CLI input produces usage errors rather than unrelated manifest errors.
+- The npm package and native executables expose the same Citty-backed behavior.
+- The implementation adds no `postinstall` hook and no Node.js runtime
+  requirement.

package/docs/decisions/decisions.xdocs.md

@@ -5,15 +5,20 @@ parent: runx-docs
 children: []
 files:
   alpha-boundaries.md: Captures accepted alpha scope, safety, distribution, and compatibility decisions.
+  citty-cli-migration.md: Defines the accepted full migration from handwritten parsing and routing to Citty.
+  mirror-automatic-push.md: Defines automatic Mirror release pushes with a synchronized protected-main gate.
   npm-trusted-publishing.md: Defines the accepted npm OIDC publishing workflow and protected-branch patch-release trial.
 documents:
   alpha-boundaries.md: Decision record for RunX alpha boundaries.
+  citty-cli-migration.md: Decision record for the complete Citty CLI parser and router migration.
+  mirror-automatic-push.md: Accepted release-policy decision for Mirror push=true and protected delivery ordering.
   npm-trusted-publishing.md: Decision record for GitHub Actions npm trusted publishing and the first automated patch release.
 tags:
   - decisions
 keywords:
   - runx
   - decisions
+  - mirror push
 flags: []
 status: stable
 ---

package/docs/decisions/mirror-automatic-push.md

@@ -0,0 +1,84 @@
+---
+name: RunX Mirror Automatic Release Push
+purpose: Record the accepted policy that Mirror pushes RunX release commits and tags automatically.
+description: Defines push=true, the synchronized-main precondition, protected GitHub delivery, failure behavior, and rollback boundary.
+created: 2026-07-14
+flags:
+  - accepted
+tags:
+  - decisions
+  - release
+  - mirror
+keywords:
+  - runx
+  - mirror push
+  - protected main
+  - release tags
+owner: runx-decisions
+---
+
+# RunX Mirror Automatic Release Push
+
+## Status
+
+Accepted by the repository owner on 2026-07-14.
+
+## Context
+
+RunX previously configured Mirror with `push = false`. Each release applied the
+version commit and tag locally, then required separate branch delivery and tag
+push commands. The owner wants RunX to match the automatic Mirror release flow
+used by the related GUIHO repositories.
+
+RunX also protects `main` and `@guiho/runx@*` tags. Automatic pushing must not
+allow a release tag to reference a commit that has not reached protected
+`main`.
+
+## Decision
+
+- Set `[git].push = true` in `mirror.config.toml`.
+- Run future `mirror version apply` operations only from a clean, synchronized
+  local `main` whose HEAD equals `origin/main`.
+- Complete implementation changes through protected pull requests before
+  applying Mirror.
+- Treat `mirror version apply` as the single release mutation that writes the
+  version, commits, tags, and pushes the configured refs.
+- Keep package publication behind the GitHub `production` environment approval
+  and npm OIDC trusted publishing.
+
+## Alternatives Considered
+
+- Keep `push = false`: rejected because it preserves the manual release step the
+  owner explicitly asked to remove.
+- Pass `--push` per release: rejected because it makes release behavior depend
+  on operator memory instead of repository configuration.
+- Apply Mirror on a release branch and merge later: rejected because the tag
+  could publish a commit before that commit is part of protected `main`.
+
+## Consequences
+
+- Successful Mirror applies will immediately push release refs and can trigger
+  the public Publish workflow.
+- Operators must treat `mirror version apply` as an externally visible release,
+  not a local preparation step.
+- The synchronized-main gate becomes mandatory; failures stop before apply.
+- Existing GitHub rulesets, environment review, and OIDC remain the enforcement
+  layers for branch, tag, and package publication.
+
+## Reversal Or Revisit Conditions
+
+Return to `push = false` if Mirror cannot push through repository protections
+reliably, if releases need a separate staging phase, or if automatic tag
+publication creates unacceptable operational risk.
+
+## Follow-up Work
+
+- Update repository instructions and XDocs metadata.
+- Validate resolved Mirror configuration and a read-only patch plan.
+- Deliver the configuration through protected `main` without applying another
+  release.
+
+## References
+
+- [Citty CLI Migration Plan](../plans/citty-cli-migration.md)
+- [npm Trusted Publishing Decision](npm-trusted-publishing.md)

package/docs/plans/citty-cli-migration.md

@@ -0,0 +1,169 @@
+---
+name: RunX Citty CLI Migration Plan
+purpose: Execute the accepted full migration from RunX handwritten argument parsing and routing to Citty.
+description: Sequences dependency verification, command-tree migration, compatibility tests, documentation, protected delivery, and the next Mirror-managed patch release.
+created: 2026-07-14
+flags:
+  - approved
+  - in-progress
+tags:
+  - plans
+  - cli
+  - citty
+keywords:
+  - runx
+  - citty
+  - argument parsing
+  - command routing
+  - patch release
+owner: runx-plans
+---
+
+# RunX Citty CLI Migration Plan
+
+## Source Decision
+
+- [Full Citty CLI Migration](../decisions/citty-cli-migration.md)
+
+## Unit 1: Add and Verify Citty
+
+- Goal: Add Citty as the only CLI parser/router dependency and verify its Bun,
+  TypeScript, and native-executable interfaces before replacing production
+  routing.
+- Dependencies: Accepted Citty migration decision.
+- Files:
+  - `package.json`
+  - `bun.lock`
+- Data, auth, and cache: No persisted data, authentication, or cache behavior
+  changes.
+- Checks:
+  - Install `citty` with Bun as a runtime dependency.
+  - Inspect its locally installed types for command definitions, aliases,
+    positional arguments, raw argument execution, help, and version handling.
+  - Run a bounded native compile after integration begins to confirm Citty is
+    bundled without a Node.js runtime dependency.
+- Acceptance: Citty is declared once as a production dependency and exposes
+  the interfaces needed for a testable RunX command tree.
+- Stop conditions: Stop if Citty requires Node.js at runtime, cannot be bundled
+  by Bun, or cannot express the accepted command and alias contract.
+
+## Unit 2: Replace Parsing and Routing
+
+- Goal: Make Citty own all CLI parsing, help, version handling, subcommands,
+  aliases, and dispatch while retaining RunX domain behavior.
+- Dependencies: Unit 1 complete.
+- Files:
+  - `source/cli.ts`
+  - `source/flags.ts` (remove)
+  - supporting source modules only when separation materially improves the
+    command definitions
+- Command tree:
+  - `runx`
+  - `runx list`
+  - `runx describe <selector>`
+  - `runx run <selector>` and alias `runx r <selector>`
+  - `runx check`
+  - `runx agents install <local|global>`
+  - `runx agents instructions`
+  - `runx upgrade`, `runx upgrade check`, and `runx upgrade list`
+  - `runx uninstall`
+- Compatibility:
+  - Preserve root `runx <selector>` as a compatibility shorthand after known
+    Citty subcommands take precedence.
+  - Preserve `--cwd`, `--file`, `--format`, `--verbose`, `--dry-run`, `--yes`,
+    `--help-tree`, `--help-docs`, and `--tool` on their applicable paths.
+  - Citty owns `-h`/`--help` and `-v`/`--version`; neither may discover a
+    manifest.
+  - Unknown options are usage failures; manifest and execution failures remain
+    `RunXError` domain failures.
+- Data, auth, and cache: Manifest parsing, selectors, subprocess behavior,
+  installer destinations, upgrade metadata, and output payloads remain
+  unchanged.
+- Acceptance: No handwritten token parser or top-level manual command router
+  remains, and all accepted command paths dispatch through Citty.
+- Stop conditions: Stop if listing, describing, checking, help, version, or dry
+  runs spawn a configured command, or if JSON output contracts drift.
+
+## Unit 3: Prove and Document the Public Contract
+
+- Goal: Lock the migrated command tree with tests and align every public
+  reference with the Citty-owned interface.
+- Dependencies: Unit 2 complete.
+- Files:
+  - CLI tests under `source/`
+  - `README.md`
+  - `DOCS.md`
+  - `skills/guiho-s-runx/SKILL.md`
+  - affected named `*.xdocs.md` descriptors
+  - `AGENTS.md` only if its durable command contract needs correction
+- Tests:
+  - Root help, `-h`, `--help`, `-v`, and `--version` outside a RunX project.
+  - Every command, nested command, alias, positional selector, applicable flag,
+    and root-selector shorthand.
+  - Unknown option, missing argument, manifest/domain error, JSON, dry-run, and
+    no-spawn safety behavior.
+  - Upgrade and agent paths retain their existing business behavior.
+- Documentation: Explain the Citty command tree and generated help without
+  exposing an obsolete parser implementation.
+- Acceptance: Tests cover all public paths and aliases; the bundled skill and
+  XDocs metadata describe the same contract as the executable.
+- Stop conditions: Stop on contradictory docs, missing command coverage, or a
+  safety regression.
+
+## Unit 4: Validate and Deliver Through Protected Main
+
+- Goal: Demonstrate package and native-executable correctness, then merge the
+  implementation without bypassing repository protections.
+- Dependencies: Unit 3 complete.
+- Checks:
+  - `bun run typecheck`
+  - `bun test`
+  - `bun run build`
+  - `bun run binary`
+  - `bun run binaries`
+  - package dry-run and packed-launcher `-v`/help checks outside a manifest
+  - native executable `-v`/help checks outside a manifest
+  - targeted strict XDocs metadata and doctor checks
+  - `git diff --check`
+- Delivery:
+  - Commit only understood migration changes on the current `codex/` branch.
+  - Push, open a pull request, wait for required CI, and merge through protected
+    `main`.
+  - Synchronize local `main` after the merge.
+- Acceptance: CI passes and remote `main` contains the complete migration.
+- Stop conditions: Stop on validation failure, unexpected worktree changes,
+  unresolved review, or branch-protection failure.
+
+## Unit 5: Publish the Next Mirror-Managed Patch
+
+- Goal: Release the merged migration as patch `0.2.4` and verify both npm and
+  native GitHub distribution.
+- Dependencies: Unit 4 merged; user authorization in this task to complete the
+  patch release.
+- Sequence:
+  - Load the Mirror workflow and inspect `mirror.config.toml`.
+  - Confirm a clean, synchronized base and run the full release validation.
+  - Run `mirror version plan patch` and require `0.2.4`.
+  - Prepare the allowed changelog/XDocs updates and commit them.
+  - Apply the patch with Mirror; do not hand-edit managed versions.
+  - Deliver the release commit through protected `main`, then push the protected
+    tag only after the tagged commit is in `main` history.
+  - Monitor the `production` workflow while the user performs its manual
+    environment approval.
+  - Verify the GitHub Release assets and npm version/provenance.
+- Acceptance: `package.json`, the Mirror release commit, protected tag,
+  successful Publish run, GitHub Release, and npm registry all agree on
+  `0.2.4`.
+- Stop conditions: Stop before tagging if Mirror plans another version or
+  validation fails. If publication fails after tagging, preserve the tag and
+  capture the exact failure before deciding any follow-up release.
+
+## TODO Alignment
+
+This is a single authorized execution session with a durable decision, plan,
+and review. It does not require a separate long-running TODO entry.
+
+## First Executable Unit
+
+Unit 1: add Citty with Bun and verify the installed API against the accepted
+RunX command contract.

package/docs/plans/mirror-automatic-push.md

@@ -0,0 +1,77 @@
+---
+name: RunX Mirror Automatic Push Plan
+purpose: Execute the accepted push=true release policy through protected main without creating another release.
+description: Sequences configuration, safety instructions, XDocs validation, protected delivery, and post-merge verification.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - plans
+  - release
+  - mirror
+keywords:
+  - runx
+  - mirror push
+  - protected main
+  - configuration
+owner: runx-plans
+---
+
+# RunX Mirror Automatic Push Plan
+
+## Source Decision
+
+- [RunX Mirror Automatic Release Push](../decisions/mirror-automatic-push.md)
+
+## Unit 1: Configure And Document Automatic Push
+
+- Goal: Make automatic release pushing a repository-owned Mirror policy.
+- Owner: RunX repository.
+- Dependencies: Accepted automatic-push decision; `0.2.4` already applied and
+  pushed, so this change must not apply another version.
+- Files:
+  - `mirror.config.toml`
+  - `AGENTS.md`
+  - `runx.xdocs.md`
+- Data, auth, and cache: No application data, authentication, authorization, or
+  cache impact. GitHub credentials and rulesets remain external.
+- Changes:
+  - Set `[git].push = true`.
+  - Require clean synchronized `main` before `mirror version apply`.
+  - Document that apply is an externally visible release mutation.
+- Checks:
+  - `mirror config check`
+  - `mirror config show`
+  - `mirror version plan patch --format json`
+  - Verify the plan reports `pushEnabled: true` and next patch `0.2.5` without
+    applying it.
+  - Strict root XDocs metadata and doctor checks.
+- Acceptance: The resolved config enables push; safety guidance prevents apply
+  from a feature branch or stale main; no version, commit, or tag is created by
+  validation.
+- Stop conditions: Stop if Mirror cannot load the config, the read-only plan
+  mutates state, or the worktree contains unrelated changes.
+
+## Unit 2: Deliver Through Protected Main
+
+- Goal: Merge the configuration policy without bypassing required CI.
+- Dependencies: Unit 1 complete and committed.
+- Delivery:
+  - Push `codex/mirror-auto-push`.
+  - Open a ready pull request to `main`.
+  - Wait for required CI and merge through the repository ruleset.
+  - Synchronize local `main` and confirm `mirror config show` reports
+    `push: true`.
+- Acceptance: `origin/main` owns the configuration and instructions; no new
+  release tag was created.
+- Stop conditions: Stop on CI failure, unresolved protection failure, or an
+  unexpected version/tag mutation.
+
+## TODO Alignment
+
+This is a bounded owner-approved configuration change completed in one session;
+it does not require a separate TODO entry.
+
+## First Executable Unit
+
+Unit 1: set and document the resolved Mirror automatic-push policy.

package/docs/plans/plans.xdocs.md

@@ -5,15 +5,21 @@ parent: runx-docs
 children: []
 files:
   alpha-implementation.md: Breaks the accepted alpha into implementation and validation units.
+  citty-cli-migration.md: Executes the full Citty command-tree migration, compatibility validation, protected delivery, and patch release.
+  mirror-automatic-push.md: Enables automatic Mirror release pushes with a synchronized protected-main safety gate.
   npm-trusted-publishing-release.md: Sequences workflow implementation, protected delivery, Mirror patching, and public trusted-publishing verification.
 documents:
   alpha-implementation.md: Plan used for the initial RunX implementation.
+  citty-cli-migration.md: Active plan for replacing handwritten CLI parsing and routing with Citty and delivering its patch release.
+  mirror-automatic-push.md: Approved plan for configuring, validating, and merging Mirror push=true without applying another release.
   npm-trusted-publishing-release.md: Approved executable plan for the RunX 0.2.1 trusted-publishing release trial.
 tags:
   - plans
 keywords:
   - runx
   - implementation
+  - citty
+  - mirror push
 flags: []
 status: stable
 ---