@guiho/runx 0.2.6 → 0.2.7

package/CHANGELOG.md

@@ -15,6 +15,23 @@ owner: runx
 
 # Changelog
 
+## 0.2.7 - 2026-07-15
+
+### Added
+
+- Added an interactive `runx init` command that collects the project name and
+  scripts directory, previews the generated catalog, and confirms before writing.
+- Added safe cancellation and explicit overwrite confirmation so initialization
+  never leaves a partial manifest or replaces an existing catalog silently.
+
+### Changed
+
+- Initialized catalogs now use the SemVer-compatible manifest version `1.0.0`,
+  configure `scripts.directory`, include the required `public` group, and begin
+  with an empty command list.
+- `runx init` creates only `runx.yaml`; the configured `scripts` directory is
+  created later with the first real script.
+
 ## 0.2.6 - 2026-07-14
 
 ### Added

package/DOCS.md

@@ -28,6 +28,7 @@ lists its commands, and runs exactly one selected command.
 | `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 init [--cwd <path>]` | Interactively create an empty `runx.yaml` catalog in the selected directory. |
 | `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. |
@@ -48,6 +49,13 @@ Global flags: `--cwd <path>`, `--file <path>`, `--format <text|json>`,
 Unknown options and missing required arguments produce command usage instead
 of falling through to manifest discovery.
 
+`runx init` is intentionally an interactive text workflow: it accepts `--cwd`
+to select the target project, but rejects `--file` (the target is always
+`runx.yaml`) and `--format json`. It previews the exact file, requires a final
+confirmation, asks before replacing an existing file, and leaves no partial
+file when cancelled. It creates the manifest only; the configured scripts
+directory is created later when the first script is added.
+
 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.
@@ -58,10 +66,14 @@ RunX searches upward from the current directory for `runx.yaml`. Use `--file`
 to select an explicit manifest. RunX does not merge files.
 
 ```yaml
-version: 1
+version: "1.0.0"
 project:
   name: example
+scripts:
+  directory: scripts
 groups:
+  public:
+    summary: Default public project commands.
   development:
     summary: Local development work.
   release:
@@ -85,14 +97,22 @@ commands:
     confirm: always
 ```
 
-Required fields are `uid`, `id`, `group`, `summary`, `description`, and
-`command`. `uid` and `id` begin with a lowercase letter and use lowercase
+`version` is a Semantic Versioning string. RunX currently supports major
+version `1`, including valid prerelease and build metadata forms. Every manifest
+also requires `scripts.directory`, which must be a relative subdirectory inside
+the manifest directory, and a `public` group with a non-empty summary. A
+catalog may start with `commands: []`; every command added later must explicitly
+name an existing group (normally `public`).
+
+Required command fields are `uid`, `id`, `group`, `summary`, `description`,
+and `command`. `uid` and `id` begin with a lowercase letter and use lowercase
 letters, digits, and hyphens. `uid` is globally unique; the group and ID pair
 is also unique.
 
-Optional fields are `cwd`, `shell`, `tags`, and `confirm`. `cwd` is relative to
-the manifest and cannot escape its directory. Shell values are `auto`, `bash`,
-`sh`, `powershell`, and `cmd`. Confirmation values are `never` and `always`.
+Optional command fields are `cwd`, `shell`, `tags`, and `confirm`. `cwd` is
+relative to the manifest and cannot escape its directory. Shell values are
+`auto`, `bash`, `sh`, `powershell`, and `cmd`. Confirmation values are `never`
+and `always`.
 
 ## Selectors and Safety
 

package/README.md

@@ -39,11 +39,29 @@ curl -fsSL https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.sh
 
 ## Quick Start
 
-Create `runx.yaml` in a project root:
+Start with the interactive initializer:
+
+```text
+runx init
+```
+
+It writes only `runx.yaml`—not an empty `scripts/` directory. The resulting
+catalog starts with a SemVer `1.x` manifest version, a configurable scripts
+directory, the required `public` group, and no commands. Add commands directly
+or ask an agent to add a script under the configured directory and its command
+entry together.
+
+For example, a catalog with a development command can look like this:
 
 ```yaml
-version: 1
+version: "1.0.0"
+project:
+  name: example
+scripts:
+  directory: scripts
 groups:
+  public:
+    summary: Default public project commands.
   development:
     summary: Local development commands.
 commands:
@@ -52,7 +70,7 @@ commands:
     group: development
     summary: Start the application locally.
     description: Starts the application in local development mode until interrupted.
-    command: bun run dev
+    command: bash scripts/dev.sh
     shell: bash
     tags: [local, watch]
 ```
@@ -63,6 +81,7 @@ Then use RunX:
 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 init                    Interactively create an empty runx.yaml catalog.
 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.

package/docs/decisions/decisions.xdocs.md

@@ -6,12 +6,14 @@ 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.
+  interactive-init-manifest.md: Defines interactive initialization, Semantic Versioning, the public group, and the scripts directory contract.
   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.
   windows-self-upgrade.md: Defines synchronous Windows executable replacement, verification, rollback, and cleanup.
 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.
+  interactive-init-manifest.md: Accepted manifest and interactive initialization decision for runx init.
   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.
   windows-self-upgrade.md: Accepted design for synchronous and recoverable Windows native self-upgrade.
@@ -20,6 +22,8 @@ tags:
 keywords:
   - runx
   - decisions
+  - runx init
+  - scripts directory
   - mirror push
   - windows self-upgrade
 flags: []

package/docs/decisions/interactive-init-manifest.md

@@ -0,0 +1,187 @@
+---
+name: RunX Interactive Init Manifest
+purpose: Preserve the accepted manifest structure and initialization behavior for runx init.
+description: Defines the Semantic Versioning manifest field, mandatory public group, configurable scripts directory, and empty interactive initialization contract.
+created: 2026-07-14
+flags:
+  - accepted
+  - decision
+tags:
+  - decisions
+  - cli
+  - manifest
+keywords:
+  - runx init
+  - runx.yaml
+  - semantic versioning
+  - public group
+  - scripts directory
+owner: runx-decisions
+---
+
+# RunX Interactive Init Manifest
+
+## Status
+
+Accepted by the project owner on 2026-07-14.
+
+## Context
+
+RunX needs an interactive `runx init` command so a project can establish its
+single `runx.yaml` command catalog before any commands exist. The repository
+already defines groups and documented commands as the core catalog model. The
+initializer must preserve that model without inventing framework-specific
+commands, creating a second configuration file, or forcing a placeholder
+command into the catalog.
+
+Projects may later store executable Bash, PowerShell, or other script files in
+a manifest-owned scripts directory. The manifest must identify that directory
+so agents and developers use one predictable location when adding scripts.
+
+## Decision
+
+### Initialized manifest
+
+`runx init` creates this shape, using the current directory name as the default
+project name:
+
+```yaml
+version: "1.0.0"
+
+project:
+  name: my-project
+
+scripts:
+  directory: scripts
+
+groups:
+  public:
+    summary: Default public project commands.
+
+commands: []
+```
+
+The initializer creates only `runx.yaml`. It does not create an empty `scripts`
+directory because the directory is created when the first script is written.
+
+### Manifest version
+
+- `version` is a valid Semantic Versioning 2.0.0 string with a
+  `MAJOR.MINOR.PATCH` core and optional prerelease or build metadata.
+- The first supported manifest contract is `"1.0.0"`.
+- RunX accepts manifest versions whose major version is `1` and rejects
+  unsupported major versions.
+- Numeric `version: 1` manifests are invalid. RunX is still under development
+  and has no deployed numeric-version compatibility requirement.
+- Future backward-incompatible manifest changes require a major version change.
+
+### Scripts directory
+
+- Every manifest contains `scripts.directory`; it configures the project script
+  location.
+- The initializer's default value is `scripts` relative to the directory
+  containing `runx.yaml`.
+- The path must remain inside the manifest directory and cannot escape through
+  an absolute path or parent traversal.
+- Existing and future command strings may invoke any suitable script type from
+  this directory; RunX remains language-agnostic.
+- The manifest command entry is the script descriptor. No sidecar RunX config
+  or per-script descriptor file is introduced.
+
+### Groups and commands
+
+- `groups` is a first-class catalog concept.
+- Every manifest contains a `public` group, analogous to PostgreSQL's default
+  `public` schema.
+- Additional groups may organize commands by domain or responsibility.
+- Every command explicitly names an existing group. Missing and unknown group
+  references are invalid.
+- Authoring workflows place a new command in `public` unless the user requests
+  or selects another group, but the stored command still contains
+  `group: public` explicitly.
+- An initialized catalog may contain no commands. Once present, every command
+  retains the required `uid`, `id`, `group`, `summary`, `description`, and
+  executable `command` fields.
+
+### Interactive behavior
+
+- `runx init` is a first-class Citty command that never requires an existing
+  manifest.
+- The interactive flow collects or confirms the project name and scripts
+  directory, renders a YAML preview, and requests confirmation before writing.
+- The interface should use a polished terminal presentation with clear
+  progress, validation, cancellation, and success states.
+- No framework-specific templates or automatic package-script imports are
+  offered.
+- An existing `runx.yaml` is never overwritten without explicit confirmation.
+- Cancellation leaves no partial file, and non-interactive invocation fails
+  clearly instead of hanging.
+
+## Alternatives Considered
+
+### Require a first command during initialization
+
+Rejected. Initialization establishes the catalog so commands can be added later
+from explicit developer requests. A fabricated starter command would make the
+manifest less truthful.
+
+### Offer framework-specific templates or scan package scripts
+
+Rejected. RunX is language-agnostic, and the project owner explicitly excluded
+framework-specific starter templates from the initializer.
+
+### Keep numeric `version: 1` compatibility
+
+Rejected. RunX has not been used outside development, so there is no legacy
+manifest population to migrate. Supporting two version shapes would add
+unnecessary schema and documentation complexity.
+
+### Store the scripts directory in a separate config file
+
+Rejected. `runx.yaml` remains the single source of truth for the command
+catalog and its script location.
+
+### Create the scripts directory eagerly
+
+Rejected for initialization. An empty directory is not useful to the catalog
+and is not preserved by Git. The directory should be created with the first
+real script.
+
+## Consequences
+
+- The manifest TypeBox schema must accept only supported Semantic Versioning
+  strings, require `scripts.directory`, and allow an empty command array.
+- Semantic validation must require the `public` group and continue requiring
+  every command to reference a declared group.
+- Script-directory validation must enforce a relative path within the manifest
+  root.
+- Existing fixtures and documentation using numeric `version: 1` must move to
+  `version: "1.0.0"` and include `public`.
+- Listing and checking an empty initialized manifest must succeed without
+  attempting command execution.
+- The initializer needs an isolated prompt boundary so interactive behavior can
+  be tested without depending on a real terminal.
+- The bundled agent skill update is intentionally deferred to the process that
+  delivers the complete agent-integration request.
+
+## Reversal Or Revisit Conditions
+
+Revisit this decision only if real-world manifest migration requires a
+compatibility policy, the command catalog needs multiple script roots, or a
+future major manifest version replaces the group model. Such a change must be
+recorded as a new decision and reflected in the manifest's major version.
+
+## Follow-up Work
+
+- Implement the manifest schema and semantic validation changes.
+- Implement and test the interactive `runx init` command.
+- Update canonical CLI and manifest documentation.
+- Update XDocs descriptors for every changed module or companion document.
+- Leave agent-skill content changes for the complete agent-integration work.
+
+## References
+
+- [Alpha boundaries](./alpha-boundaries.md)
+- [Alpha command-catalog requirements](../requirements/alpha-command-catalog.md)
+- [CLI architecture](../architecture/cli-architecture.md)
+- [GitHub issue #10](https://github.com/CGuiho/runx/issues/10)

package/docs/plans/interactive-init-manifest.md

@@ -0,0 +1,177 @@
+---
+name: RunX Interactive Init Manifest Plan
+purpose: Sequence implementation of the accepted runx init workflow and manifest contract.
+description: Defines the schema, interactive terminal UI, validation, documentation, and pull-request work for RunX initialization.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - plans
+  - cli
+  - manifest
+keywords:
+  - runx init
+  - runx.yaml
+  - semantic versioning
+  - public group
+  - scripts directory
+owner: runx-plans
+---
+
+# RunX Interactive Init Manifest Plan
+
+## Sources
+
+- [Interactive Init Manifest Decision](../decisions/interactive-init-manifest.md)
+- [Alpha Command Catalog Requirements](../requirements/alpha-command-catalog.md)
+- [CLI Architecture](../architecture/cli-architecture.md)
+- GitHub issue [#10](https://github.com/CGuiho/runx/issues/10)
+
+## Unit 1: Establish the Manifest Contract
+
+- Goal: Make the current manifest validator enforce the accepted `1.x.x`
+  Semantic Versioning, scripts directory, public group, and empty catalog
+  contract.
+- Owner: `C:\GUIHO\runx`.
+- Dependencies: Accepted interactive-init decision.
+- Files:
+  - `source/manifest.ts`
+  - `source/types.ts` when TypeScript inference exposes the new manifest shape
+  - `source/guiho-runx.spec.ts`
+  - `source/cli.spec.ts` fixtures that construct manifests
+- Behavior:
+  - Replace numeric `version: 1` with a Semantic Versioning string and accept
+    only supported major version `1`.
+  - Require `scripts.directory` as a non-empty relative path inside the
+    manifest root.
+  - Require the `public` group with a non-empty summary.
+  - Permit an empty `commands` array while keeping every populated command
+    explicit about its existing group.
+  - Preserve strict unknown-property rejection and existing selector and
+    execution safety behavior.
+- Data, auth, permissions, and cache: Local YAML contract only. No remote data,
+  authentication, authorization, cache, or secret changes.
+- Tests:
+  - Accept `"1.0.0"` and prerelease/build SemVer forms with major `1`.
+  - Reject numeric versions, malformed SemVer, unsupported major versions,
+    missing scripts configuration, escaping script paths, missing public, and
+    commands that name unknown groups.
+  - Prove empty initialized catalogs check and list without execution.
+- Acceptance: `readManifest()` returns a strict manifest with `scripts` and
+  `public`, and invalid configurations fail with actionable `RunXError`
+  messages.
+- Stop conditions: Stop if SemVer support would require a migration policy,
+  scripts need more than one root, or the change weakens command safety.
+
+## Unit 2: Implement the Interactive Initializer
+
+- Goal: Add a beautiful, cancellable `runx init` Citty command that creates a
+  valid empty `runx.yaml` without ever executing a configured command.
+- Dependencies: Unit 1.
+- Files:
+  - `package.json`
+  - `bun.lock`
+  - `source/init.ts`
+  - `source/init.spec.ts`
+  - `source/cli.ts`
+  - `source/cli.spec.ts`
+  - `source/help.ts`
+- Behavior:
+  - Use a dependency-free Bun terminal prompt adapter with clear visual states,
+    so the initializer remains portable across native and Windows builds.
+  - Isolate prompt interactions behind an injected interface so prompt flow and
+    filesystem behavior can be tested without a real terminal.
+  - In an interactive terminal, welcome the user, collect a project name
+    defaulting to the selected directory name, collect a scripts directory
+    defaulting to `scripts`, preview the exact YAML, and request confirmation.
+  - Write only `runx.yaml`; create `scripts/` later when the first real script
+    is added.
+  - Detect an existing `runx.yaml` in the selected directory and require a
+    second explicit overwrite confirmation.
+  - Use an atomic temporary-file write and leave no partial manifest on
+    cancellation or failure.
+  - Fail clearly outside an interactive terminal; do not hang and do not emit
+    interactive ANSI frames into JSON output.
+  - Accept `--cwd` as the target directory, reject `--file` because the
+    initializer always creates `runx.yaml`, and reject `--format json` because
+    initialization is an interactive terminal workflow.
+  - Register `init` as a first-class Citty command, include it in help/home and
+    command-tree output, and reserve the word from selector shorthand.
+- Tests:
+  - Successful creation exactly matches the accepted YAML shape.
+  - Cancellation leaves no file.
+  - Existing-file rejection and confirmed overwrite are safe.
+  - Default and custom project/scripts values validate.
+  - CLI help works outside a manifest and non-interactive invocation exits with
+    a clear error.
+  - `--file` and `--format json` report clear unsupported-option errors without
+    creating files.
+  - The generated file passes `runx check` and `runx list`.
+- Acceptance: `runx init` produces a polished, deterministic creation flow and
+  never executes a manifest command.
+- Stop conditions: Stop if the terminal prompt adapter fails Bun tests or native
+  compile, if Citty cannot route `init` without conflicting with selector shorthand, or
+  if atomic replacement is not portable on Windows.
+
+## Unit 3: Align Canonical Documentation and XDocs
+
+- Goal: Make public and structured documentation accurately describe the new
+  manifest and initializer without modifying the bundled agent skill.
+- Dependencies: Units 1 and 2.
+- Files:
+  - `README.md`
+  - `DOCS.md`
+  - `source/source.xdocs.md`
+  - `runx.xdocs.md` when its package description needs updating
+  - `docs/plans/plans.xdocs.md`
+- Behavior:
+  - Document `runx init`, Semantic Versioning, `scripts.directory`, mandatory
+    `public`, empty catalog initialization, and command-to-script examples.
+  - Keep the bundled `skills/guiho-s-runx/SKILL.md` unchanged; its update belongs
+    to the separate agent-integration delivery requested by the project owner.
+  - Update the source descriptor for the initializer module and changed CLI /
+    manifest responsibilities.
+- Checks:
+  - `xdocs meta docs\plans --documents --strict --format json`
+  - `xdocs meta source --strict --format json`
+  - `xdocs tree`
+- Acceptance: User-facing docs, XDocs metadata, and implementation agree.
+- Stop conditions: Stop if XDocs requires unrelated coverage cleanup; validate
+  only the affected subtrees and report wider pre-existing findings.
+
+## Unit 4: Validate, Review, Commit, Push, and Open a Pull Request
+
+- Goal: Produce evidence that the implementation satisfies the accepted
+  decision, then deliver it as a draft pull request from `codex/runx-init`.
+- Dependencies: Units 1 through 3.
+- Checks:
+  - `bun run typecheck`
+  - `bun test`
+  - `bun run build`
+  - `bun run binary`
+  - `xdocs meta docs\plans --documents --strict --format json`
+  - `xdocs meta source --strict --format json`
+  - `xdocs tree`
+  - `git diff --check`
+- Delivery:
+  - Write an implementation review and validation report with XDocs metadata.
+  - Commit coherent code, tests, documentation, and validation artifacts.
+  - Push only the feature branch and create a draft pull request that links
+    issue #10 and states that agent-skill automation is intentionally tracked
+    separately in issue #11.
+- Acceptance: All applicable checks pass, the worktree is clean, the branch is
+  pushed, and the draft pull request is reviewable without a release, tag, or
+  package publication.
+- Stop conditions: Stop before push/PR if validation fails, unrelated changes
+  appear, GitHub rejects authentication, or the branch diverges unexpectedly.
+
+## TODO Alignment
+
+This is one approved, focused package implementation and does not need a new
+long-running TODO entry. The decision, plan, review, and validation records are
+the durable delivery trail.
+
+## First Executable Unit
+
+Unit 1: update `source/manifest.ts` and its fixtures/tests to enforce the
+accepted manifest contract.

package/docs/plans/plans.xdocs.md

@@ -6,12 +6,14 @@ 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.
+  interactive-init-manifest.md: Sequences the SemVer manifest, public group, scripts directory, and interactive initializer delivery.
   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.
   windows-self-upgrade.md: Sequences synchronous Windows replacement, rollback coverage, validation, issue closure, and patch delivery.
 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.
+  interactive-init-manifest.md: Approved implementation plan for the RunX interactive init manifest feature.
   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.
   windows-self-upgrade.md: Approved executable plan for fixing Windows native self-upgrade and delivering its patch.
@@ -21,6 +23,8 @@ keywords:
   - runx
   - implementation
   - citty
+  - runx init
+  - scripts directory
   - mirror push
   - windows self-upgrade
 flags: []

package/docs/reviews/implementation/implementation.xdocs.md

@@ -5,9 +5,11 @@ parent: runx-reviews
 children: []
 files:
   citty-cli-migration-review.md: Reviews the implemented Citty command tree, compatibility adapter, tests, documentation, packaging, and release readiness.
+  interactive-init-manifest-review.md: Reviews the implemented RunX initializer, strict manifest contract, tests, documentation, and delivery readiness.
   windows-self-upgrade-review.md: Reviews synchronous Windows replacement, rollback, cleanup, tests, CI coverage, and release readiness.
 documents:
   citty-cli-migration-review.md: Accepted implementation review for the full Citty CLI migration.
+  interactive-init-manifest-review.md: Accepted implementation review for the RunX interactive init manifest feature.
   windows-self-upgrade-review.md: Accepted implementation review for the Windows native self-upgrade fix.
 tags:
   - reviews
@@ -15,6 +17,8 @@ tags:
 keywords:
   - runx
   - citty
+  - runx init
+  - scripts directory
   - implementation review
   - windows self-upgrade
 flags: []

package/docs/reviews/implementation/interactive-init-manifest-review.md

@@ -0,0 +1,69 @@
+---
+name: RunX Interactive Init Manifest Implementation Review
+purpose: Assess the delivered RunX initializer and manifest contract against the accepted decision and plan.
+description: Reviews Citty routing, strict SemVer and group validation, terminal safety, tests, documentation, and delivery boundaries.
+created: 2026-07-14
+flags:
+  - accepted
+tags:
+  - reviews
+  - implementation
+  - cli
+keywords:
+  - runx init
+  - runx.yaml
+  - semantic versioning
+  - public group
+  - scripts directory
+owner: runx-implementation-reviews
+---
+
+# RunX Interactive Init Manifest Implementation Review
+
+## Verdict
+
+Accepted. No blocking, high, medium, or low findings remain.
+
+## Acceptance Criteria Check
+
+- `runx init` is a first-class Citty command, appears in the home/help tree,
+  and is reserved from selector shorthand.
+- The manifest accepts Semantic Versioning `1.x` strings, requires an in-root
+  `scripts.directory` and `public` group, and permits `commands: []` while
+  retaining strict command-group validation.
+- The initializer uses a guided terminal adapter with project and scripts
+  prompts, an exact YAML preview, confirmation, overwrite confirmation, and
+  cancellation behavior. It writes only `runx.yaml`, not `scripts/`.
+- Writes use a same-directory temporary file, validate the temporary manifest,
+  then rename it into place. No configured command is read for execution or
+  spawned by this path.
+- `--file` and `--format json` fail explicitly for `init`; `--cwd` selects the
+  target directory.
+- The README, canonical documentation, source XDocs metadata, and package
+  metadata align with the implementation. The bundled agent skill is unchanged
+  by design; the separate agent-integration follow-up remains issue #11.
+
+## Verification Evidence
+
+- `bun run typecheck` passed.
+- `bun test` passed: 22 tests and 180 assertions, including initialization,
+  cancellation, overwrite, empty-catalog list/check, and non-interactive CLI
+  coverage.
+- `bun run build` and `bun run binary` passed.
+- The compiled `bin/runx.exe --help-tree` includes `init`.
+- XDocs strict metadata checks for `source`, plans, and plan reviews passed;
+  the XDocs tree is intact.
+
+## Residual Risk
+
+The automated environment has no interactive TTY, so the live terminal frame
+was exercised through the injected prompt contract rather than a human session.
+The native binary build and its command-tree smoke check confirm that the
+initializer is included in the compiled executable.
+
+## References
+
+- [Decision](../../decisions/interactive-init-manifest.md)
+- [Plan](../../plans/interactive-init-manifest.md)
+- [Plan Review](../plans/interactive-init-manifest-review.md)
+- GitHub issues [#10](https://github.com/CGuiho/runx/issues/10) and [#11](https://github.com/CGuiho/runx/issues/11)

package/docs/reviews/plans/interactive-init-manifest-review.md

@@ -0,0 +1,82 @@
+---
+name: RunX Interactive Init Manifest Plan Review
+purpose: Verify that the interactive-init implementation plan is executable, safe, and traceable.
+description: Reviews manifest constraints, terminal workflow boundaries, test coverage, XDocs work, and pull-request delivery for runx init.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - reviews
+  - plans
+  - cli
+keywords:
+  - runx init
+  - runx.yaml
+  - semantic versioning
+  - public group
+  - scripts directory
+owner: runx-plan-reviews
+---
+
+# RunX Interactive Init Manifest Plan Review
+
+## Verdict
+
+Ready for execution.
+
+## Findings
+
+No blocker, high, medium, or low findings remain.
+
+The plan is traceable to the accepted interactive-init decision, the existing
+command-catalog requirement, and the Citty CLI architecture. The only review
+finding was resolved in the plan: `runx init` is an interactive terminal
+workflow, so `--format json` and `--file` must fail clearly rather than create
+ambiguous output or target files.
+
+## Sequencing and Safety
+
+- Manifest schema changes precede the initializer, so generated YAML is
+  validated by the same strict contract that later commands use.
+- The initializer is isolated from the executor and is explicitly prohibited
+  from spawning configured manifest commands.
+- The prompt boundary is injectable for tests; an interactive terminal is
+  required for the real user interface.
+- Existing-file confirmation, cancellation, and atomic writes prevent silent
+  replacement and partial manifests.
+- The `scripts` directory is configured but not created until a real script is
+  added, matching the accepted file-only initialization boundary.
+- Manifest evolution is constrained to supported SemVer major `1`; no legacy
+  numeric compatibility or migration policy is hidden in the implementation.
+
+## Coverage Review
+
+- Tests cover SemVer, public-group, scripts-directory, empty-catalog, command
+  group-reference, creation, cancellation, overwrite, non-interactive, and
+  unsupported-option behavior.
+- The full Bun typecheck, test, library build, local native compilation, XDocs
+  subtree validation, and diff hygiene are named.
+- Native compilation of the terminal prompt dependency is an explicit stop
+  condition.
+- No API, database, authentication, authorization, cache, cloud, secret,
+  deployment, release, tag, or package-publication work is in scope.
+
+## Documentation and TODO Alignment
+
+The plan updates public CLI documentation and the affected XDocs descriptors.
+The bundled RunX agent skill is deliberately deferred to the separate
+agent-integration feature tracked in issue #11, as directed by the project
+owner. The work is one focused package session, so no additional long-running
+TODO entry is required.
+
+## First Executable Unit
+
+Update `source/manifest.ts` and its tests/fixtures to establish the SemVer,
+scripts-directory, mandatory-public-group, and empty-catalog contract.
+
+## References
+
+- [Plan](../../plans/interactive-init-manifest.md)
+- [Decision](../../decisions/interactive-init-manifest.md)
+- [Requirements](../../requirements/alpha-command-catalog.md)
+- [CLI Architecture](../../architecture/cli-architecture.md)

package/docs/reviews/plans/plans.xdocs.md

@@ -5,11 +5,13 @@ parent: runx-reviews
 children: []
 files:
   citty-cli-migration-review.md: Reviews completeness, compatibility, safety invariants, native packaging, and release sequencing for the Citty migration.
+  interactive-init-manifest-review.md: Reviews the RunX init manifest schema, terminal workflow, tests, XDocs, and pull-request delivery.
   mirror-automatic-push-review.md: Reviews synchronized-main safeguards, read-only validation, protected delivery, and release side effects.
   npm-trusted-publishing-release-review.md: Reviews sequencing, acceptance criteria, safety gates, and validation for the RunX 0.2.1 trusted-publishing plan.
   windows-self-upgrade-review.md: Reviews synchronous replacement, rollback, regression coverage, issue closure, and patch delivery.
 documents:
   citty-cli-migration-review.md: Ready-for-execution review of the full Citty CLI migration plan.
+  interactive-init-manifest-review.md: Ready-for-execution review of the RunX interactive init manifest plan.
   mirror-automatic-push-review.md: Ready-for-execution review of the Mirror automatic-push configuration plan.
   npm-trusted-publishing-release-review.md: Ready-for-execution review of the npm trusted-publishing release plan.
   windows-self-upgrade-review.md: Ready-for-execution review of the Windows native self-upgrade fix plan.
@@ -20,6 +22,8 @@ keywords:
   - runx
   - plan review
   - citty
+  - runx init
+  - scripts directory
   - mirror push
   - trusted publishing
   - windows self-upgrade

package/docs/validation/interactive-init-manifest.md

@@ -0,0 +1,79 @@
+---
+name: RunX Interactive Init Manifest Validation
+purpose: Record executable verification evidence for the RunX initializer and strict manifest contract.
+description: Captures typecheck, tests, library and native builds, compiled CLI smoke checks, and XDocs validation for runx init.
+created: 2026-07-14
+flags:
+  - passed
+tags:
+  - validation
+  - cli
+  - manifest
+keywords:
+  - runx init
+  - runx.yaml
+  - bun test
+  - native binary
+  - xdocs
+owner: runx-validation
+---
+
+# RunX Interactive Init Manifest Validation
+
+## Summary
+
+The interactive initializer and strict manifest contract passed all applicable
+local validation gates. No release, version, tag, package publication, cloud,
+or secret operation was performed.
+
+## Scope
+
+- Citty registration and help surfaces for `runx init`.
+- SemVer `1.x`, scripts-directory, `public` group, and empty-command manifest
+  validation.
+- Prompt cancellation, overwrite confirmation, exact generated YAML, atomic
+  write validation, and non-interactive error behavior.
+- User documentation and XDocs metadata.
+
+## Commands Run
+
+| Command | Result | Evidence |
+| --- | --- | --- |
+| `bun run typecheck` | Passed | Strict TypeScript compilation completed without diagnostics. |
+| `bun test` | Passed | 22 tests and 180 assertions passed across CLI, manifest, initializer, and self-management suites. |
+| `bun run build` | Passed | Library output compiled successfully. |
+| `bun run binary` | Passed | Native Windows executable compiled to `bin/runx.exe`. |
+| `bin/runx.exe --help-tree` | Passed | The compiled command tree includes `init`. |
+| `xdocs meta source --strict --format json` | Passed | The new initializer and test files are fully described. |
+| `xdocs meta docs\\plans --documents --strict --format json` | Passed | The plan and companion metadata validate. |
+| `xdocs meta docs\\reviews\\plans --documents --strict --format json` | Passed | The plan review and companion metadata validate. |
+| `xdocs tree` | Passed | The RunX documentation hierarchy is intact. |
+| `git diff --check` | Passed | No whitespace errors were reported before delivery records were added. |
+
+## Manual Checks
+
+- The generated empty manifest has the required version, project, scripts,
+  `public` group, and `commands: []` shape.
+- No empty `scripts/` directory is created by initialization.
+- `runx init --file ...` and `runx init --format json` return explicit errors
+  without creating a manifest.
+
+## Skipped Checks
+
+A person-driven interactive terminal session could not be run in this automated
+non-TTY environment. The initializer’s prompt sequence is covered through its
+injected prompt adapter; the compiled executable was smoke-tested for command
+registration.
+
+## Readiness
+
+Ready for code review and a draft pull request. The bundled agent-skill
+automation remains intentionally outside this change and is tracked by issue
+#11.
+
+## References
+
+- [Decision](../decisions/interactive-init-manifest.md)
+- [Plan](../plans/interactive-init-manifest.md)
+- [Implementation Review](../reviews/implementation/interactive-init-manifest-review.md)
+- GitHub issue [#10](https://github.com/CGuiho/runx/issues/10)

package/docs/validation/validation.xdocs.md

@@ -6,10 +6,12 @@ children: []
 files:
   alpha-implementation-summary.md: Records the completed alpha implementation, checks, and release boundaries.
   citty-cli-migration.md: Records the complete local validation gate for the Citty command-tree migration.
+  interactive-init-manifest.md: Records validation evidence for the interactive initializer and strict manifest contract.
   windows-self-upgrade.md: Records Windows replacement, rollback, cleanup, native build, CI, and XDocs validation evidence.
 documents:
   alpha-implementation-summary.md: Validation summary for the first RunX implementation.
   citty-cli-migration.md: Validation evidence for TypeScript, tests, native assets, npm packaging, CLI behavior, and XDocs.
+  interactive-init-manifest.md: Validation evidence for the RunX interactive init manifest feature.
   npm-trusted-publishing-0.2.2.md: Validation evidence for the blocked 0.2.2 npm trusted-publishing retry.
   windows-self-upgrade.md: Validation evidence for GitHub issues #9 and #1 and the Windows self-upgrade patch.
 tags:
@@ -17,6 +19,8 @@ tags:
 keywords:
   - runx
   - citty
+  - runx init
+  - scripts directory
   - tests
   - summary
   - windows self-upgrade

package/library/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,OAAO,KAAK,EAAkB,UAAU,EAAkB,MAAM,OAAO,CAAA;AAGvE,OAAO,EACL,MAAM,EACN,uBAAuB,EACvB,WAAW,GACZ,CAAA;AAqPD,QAAA,MAAiB,WAAW,iBAAwB,CAAA;AAEpD,iBAAe,MAAM,CAAC,OAAO,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAY9E;AAED,iBAAe,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBxE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAaH,OAAO,KAAK,EAAkB,UAAU,EAAkB,MAAM,OAAO,CAAA;AAGvE,OAAO,EACL,MAAM,EACN,uBAAuB,EACvB,WAAW,GACZ,CAAA;AA8PD,QAAA,MAAiB,WAAW,iBAAwB,CAAA;AAEpD,iBAAe,MAAM,CAAC,OAAO,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAY9E;AAED,iBAAe,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBxE"}

package/library/cli.js

@@ -7,6 +7,7 @@ import { installAgentInstructions, installAgentSkill } from './agents.js';
 import { RunXError } from './errors.js';
 import { runCommand } from './executor.js';
 import { readVersion, showHelpDocs, showHelpTree, showHome } from './help.js';
+import { initializeRunXManifest } from './init.js';
 import { readManifest, resolveCommand } from './manifest.js';
 import { renderDescription, renderExecutionPlan, renderJson, renderList } from './render.js';
 import { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf } from './self-management.js';
@@ -95,6 +96,12 @@ const createCommandTree = () => {
         setup: withCommandHelp(state),
         run: async () => checkManifest(resolveOptions(state.globalArgs)),
     });
+    const initCommand = defineCommand({
+        meta: { name: 'runx init', description: 'Interactively create an empty RunX manifest.' },
+        args: commonArgs,
+        setup: withCommandHelp(state),
+        run: async () => initializeProject(state.globalArgs),
+    });
     const agentsInstallCommand = defineCommand({
         meta: { name: 'runx agents install', description: 'Install the bundled RunX skill.' },
         args: {
@@ -166,6 +173,7 @@ const createCommandTree = () => {
         describe: describeCommandDefinition,
         run: runCommandDefinition,
         check: checkCommand,
+        init: initCommand,
         agents: agentsCommand,
         upgrade: upgradeCommand,
         uninstall: uninstallCommand,
@@ -176,6 +184,7 @@ const createCommandTree = () => {
         ['run', runCommandDefinition],
         ['r', runCommandDefinition],
         ['check', checkCommand],
+        ['init', initCommand],
         ['agents', agentsCommand],
         ['agents install', agentsInstallCommand],
         ['agents instructions', agentsInstructionsCommand],
@@ -334,6 +343,15 @@ async function checkManifest(options) {
     const result = { valid: true, manifestPath: path, commandCount: manifest.commands.length, groups: Object.keys(manifest.groups) };
     write(options.format === 'json' ? renderJson(result) : `valid: true\nmanifest: ${path}\ncommands: ${result.commandCount}\n`);
 }
+async function initializeProject(args) {
+    if (args.file) {
+        throw new RunXError('runx init does not support --file. It always creates runx.yaml in --cwd or the current directory.');
+    }
+    if (args.format === 'json') {
+        throw new RunXError('runx init does not support --format json because initialization is an interactive terminal workflow.');
+    }
+    await initializeRunXManifest({ cwd: resolve(args.cwd ?? process.cwd()) });
+}
 async function runSelectedCommand(selector, options, args) {
     const { manifest, path } = await readManifest(options.cwd, options.file);
     const command = resolveCommand(manifest, path, selector);

package/library/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../source/help.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,QAAO,MAAiF,CAAA;AAEhH,eAAO,MAAM,QAAQ,QAAO,MAe3B,CAAA;AAED,eAAO,MAAM,YAAY,QAAO,MAapB,CAAA;AAEZ,eAAO,MAAM,YAAY,QAAO,MAU/B,CAAA"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../source/help.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,QAAO,MAAiF,CAAA;AAEhH,eAAO,MAAM,QAAQ,QAAO,MAiB3B,CAAA;AAED,eAAO,MAAM,YAAY,QAAO,MAcpB,CAAA;AAEZ,eAAO,MAAM,YAAY,QAAO,MAW/B,CAAA"}

package/library/help.js

@@ -5,6 +5,7 @@ export const showHome = () => `RunX ${readVersion()}
 A documented, local command catalog for runx.yaml manifests.
 
 Usage:
+  runx init [--cwd <path>]
   runx list [--file <path>] [--format <text|json>]
   runx describe <selector>
   runx run <selector> [--dry-run] [--yes]
@@ -12,6 +13,7 @@ Usage:
   runx <selector>
 
 Start here:
+  runx init                 Interactively create an empty runx.yaml catalog.
   runx list                 List every command in the nearest manifest.
   runx --help-tree          Show the complete command tree.
   runx --help-docs          Show manifest and agent documentation guidance.
@@ -23,6 +25,7 @@ export const showHelpTree = () => [
     '|- run <selector>',
     '|  `- alias: r',
     '|- check',
+    '|- init',
     '|- agents',
     '|  |- install <local|global>',
     '|  `- instructions',
@@ -33,6 +36,7 @@ export const showHelpTree = () => [
 export const showHelpDocs = () => `RunX documentation
 
 Manifest: runx.yaml, discovered from the current directory upward or selected with --file.
+Create an empty catalog with runx init. Its manifest uses SemVer 1.x, configures a scripts directory, and always includes the public group.
 Required command fields: uid, id, group, summary, description, command.
 Optional command fields: cwd, shell, tags, confirm.
 

package/library/init.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { RunXManifest } from './types.js';
+export type RunXInitPrompter = {
+    intro(title: string): void;
+    text(options: {
+        message: string;
+        initialValue: string;
+        validate: (value: string | undefined) => string | undefined;
+    }): Promise<string | undefined>;
+    confirm(options: {
+        message: string;
+        initialValue: boolean;
+    }): Promise<boolean | undefined>;
+    preview(manifest: string): void;
+    cancel(message: string): void;
+    outro(message: string): void;
+    close?(): void;
+};
+export type RunXInitResult = {
+    status: 'cancelled';
+} | {
+    status: 'created';
+    path: string;
+    manifest: RunXManifest;
+};
+type RunXInitOptions = {
+    cwd: string;
+    isInteractive?: boolean;
+    prompter?: RunXInitPrompter;
+};
+export declare const initializeRunXManifest: ({ cwd, isInteractive, prompter }: RunXInitOptions) => Promise<RunXInitResult>;
+export declare const createInitialManifest: (projectName: string, scriptsDirectory: string) => RunXManifest;
+export declare const renderInitialManifest: (manifest: RunXManifest) => string;
+export {};
+//# sourceMappingURL=init.d.ts.map

package/library/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../source/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,IAAI,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IAClJ,OAAO,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAA;IAC1F,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,KAAK,CAAC,IAAI,IAAI,CAAA;CACf,CAAA;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,CAAA;AAE/D,KAAK,eAAe,GAAG;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAC5B,CAAA;AAID,eAAO,MAAM,sBAAsB,qCAA4G,eAAe,KAAG,OAAO,CAAC,cAAc,CAmDtL,CAAA;AAED,eAAO,MAAM,qBAAqB,gBAAiB,MAAM,oBAAoB,MAAM,KAAG,YAQpF,CAAA;AAEF,eAAO,MAAM,qBAAqB,aAAc,YAAY,KAAG,MAenD,CAAA"}

package/library/init.js

@@ -0,0 +1,165 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { randomUUID } from 'node:crypto';
+import { rename, rm, writeFile } from 'node:fs/promises';
+import { basename, isAbsolute, relative, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { RunXError } from './errors.js';
+import { readManifest } from './manifest.js';
+const manifestVersion = '1.0.0';
+export const initializeRunXManifest = async ({ cwd, isInteractive = process.stdin.isTTY === true && process.stdout.isTTY === true, prompter }) => {
+    if (!isInteractive) {
+        throw new RunXError('runx init requires an interactive terminal. Run it directly in a terminal with stdin and stdout attached.');
+    }
+    const activePrompter = prompter ?? createTerminalPrompter();
+    try {
+        const root = resolve(cwd);
+        const path = resolve(root, 'runx.yaml');
+        const defaultProjectName = basename(root) || 'my-project';
+        activePrompter.intro('RunX project setup');
+        if (await Bun.file(path).exists()) {
+            const overwrite = await activePrompter.confirm({
+                message: 'runx.yaml already exists. Replace it?',
+                initialValue: false,
+            });
+            if (overwrite !== true)
+                return cancelInitialization(activePrompter);
+        }
+        const projectName = await activePrompter.text({
+            message: 'Project name',
+            initialValue: defaultProjectName,
+            validate: (value) => value?.trim() ? undefined : 'Enter a project name.',
+        });
+        if (projectName === undefined)
+            return cancelInitialization(activePrompter);
+        const scriptsDirectory = await activePrompter.text({
+            message: 'Scripts directory',
+            initialValue: 'scripts',
+            validate: (value) => validateScriptsDirectory(value, root),
+        });
+        if (scriptsDirectory === undefined)
+            return cancelInitialization(activePrompter);
+        const manifest = createInitialManifest(projectName.trim(), scriptsDirectory.trim());
+        const yaml = renderInitialManifest(manifest);
+        activePrompter.preview(yaml);
+        const confirmed = await activePrompter.confirm({
+            message: 'Create this runx.yaml?',
+            initialValue: true,
+        });
+        if (confirmed !== true)
+            return cancelInitialization(activePrompter);
+        await writeValidatedManifest(root, path, yaml);
+        activePrompter.outro(`Created ${path}`);
+        return { status: 'created', path, manifest };
+    }
+    finally {
+        activePrompter.close?.();
+    }
+};
+export const createInitialManifest = (projectName, scriptsDirectory) => ({
+    version: manifestVersion,
+    project: { name: projectName },
+    scripts: { directory: scriptsDirectory },
+    groups: {
+        public: { summary: 'Default public project commands.' },
+    },
+    commands: [],
+});
+export const renderInitialManifest = (manifest) => [
+    `version: ${JSON.stringify(manifest.version)}`,
+    '',
+    'project:',
+    `  name: ${JSON.stringify(manifest.project?.name ?? '')}`,
+    '',
+    'scripts:',
+    `  directory: ${JSON.stringify(manifest.scripts.directory)}`,
+    '',
+    'groups:',
+    '  public:',
+    `    summary: ${JSON.stringify(manifest.groups.public.summary)}`,
+    '',
+    'commands: []',
+    '',
+].join('\n');
+const createTerminalPrompter = () => {
+    const terminal = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    const accent = (value) => process.env['NO_COLOR'] ? value : `\u001b[36m${value}\u001b[0m`;
+    const success = (value) => process.env['NO_COLOR'] ? value : `\u001b[32m${value}\u001b[0m`;
+    const muted = (value) => process.env['NO_COLOR'] ? value : `\u001b[2m${value}\u001b[0m`;
+    const error = (value) => process.env['NO_COLOR'] ? value : `\u001b[31m${value}\u001b[0m`;
+    const write = (value) => {
+        process.stdout.write(value);
+    };
+    const ask = async (label) => {
+        try {
+            return await terminal.question(label);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return {
+        intro: (title) => write(`\n${accent('◆')} ${title}\n${muted('  A documented command catalog for this project.')}\n\n`),
+        text: async (options) => {
+            while (true) {
+                const value = await ask(`${accent('◆')} ${options.message} ${muted(`[${options.initialValue}]`)}\n  `);
+                if (value === undefined)
+                    return undefined;
+                const selected = value.trim() || options.initialValue;
+                const validation = options.validate(selected);
+                if (!validation)
+                    return selected;
+                write(`${error('▲')} ${validation}\n`);
+            }
+        },
+        confirm: async (options) => {
+            while (true) {
+                const defaultLabel = options.initialValue ? 'Y/n' : 'y/N';
+                const value = await ask(`${accent('◆')} ${options.message} ${muted(`[${defaultLabel}]`)}\n  `);
+                if (value === undefined)
+                    return undefined;
+                const answer = value.trim().toLowerCase();
+                if (!answer)
+                    return options.initialValue;
+                if (answer === 'y' || answer === 'yes')
+                    return true;
+                if (answer === 'n' || answer === 'no')
+                    return false;
+                write(`${error('▲')} Enter yes or no.\n`);
+            }
+        },
+        preview: (manifest) => write(`\n${accent('┌─ runx.yaml preview ─────────────────────────────────')}\n${manifest.trimEnd().split('\n').map((line) => `${accent('│')} ${line}`).join('\n')}\n${accent('└────────────────────────────────────────────────────')}\n\n`),
+        cancel: (message) => write(`${error('■')} ${message}\n`),
+        outro: (message) => {
+            write(`${success('◆')} ${message}\n`);
+        },
+        close: () => terminal.close(),
+    };
+};
+const cancelInitialization = (prompter) => {
+    prompter.cancel('Initialization cancelled. No files were changed.');
+    return { status: 'cancelled' };
+};
+const validateScriptsDirectory = (value, root) => {
+    const directory = value?.trim();
+    if (!directory)
+        return 'Enter a scripts directory.';
+    const resolvedDirectory = resolve(root, directory);
+    const relativeDirectory = relative(root, resolvedDirectory);
+    if (relativeDirectory === '' || relativeDirectory === '.' || isAbsolute(relativeDirectory) || relativeDirectory.startsWith('..')) {
+        return 'Use a relative subdirectory inside this project.';
+    }
+    return undefined;
+};
+const writeValidatedManifest = async (root, path, yaml) => {
+    const temporaryPath = resolve(root, `.runx-${randomUUID()}.yaml.tmp`);
+    try {
+        await writeFile(temporaryPath, yaml, { encoding: 'utf8', flag: 'wx' });
+        await readManifest(root, temporaryPath);
+        await rename(temporaryPath, path);
+    }
+    finally {
+        await rm(temporaryPath, { force: true });
+    }
+};

package/library/manifest.d.ts

@@ -12,10 +12,13 @@ export declare const CommandSchema: import("@sinclair/typebox").TObject<{
     confirm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"never">, import("@sinclair/typebox").TLiteral<"always">]>>;
 }>;
 export declare const ManifestSchema: import("@sinclair/typebox").TObject<{
-    version: import("@sinclair/typebox").TLiteral<1>;
+    version: import("@sinclair/typebox").TString;
     project: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         name: import("@sinclair/typebox").TString;
     }>>;
+    scripts: import("@sinclair/typebox").TObject<{
+        directory: import("@sinclair/typebox").TString;
+    }>;
     groups: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
         summary: import("@sinclair/typebox").TString;
     }>>;

package/library/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../source/manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAe,YAAY,EAAE,MAAM,YAAY,CAAA;AAI5E,eAAO,MAAM,aAAa;;;;;;;;;;;EAiBS,CAAA;AAEnC,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;EAKQ,CAAA;AAInC,eAAO,MAAM,YAAY,QAAe,MAAM,iBAAiB,MAAM,KAAG,OAAO,CAAC,MAAM,CAiBrF,CAAA;AAED,eAAO,MAAM,YAAY,QAAe,MAAM,iBAAiB,MAAM,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmBvH,CAAA;AAED,eAAO,MAAM,cAAc,aAAc,YAAY,gBAAgB,MAAM,YAAY,MAAM,KAAG,eAkC/F,CAAA"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../source/manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAe,YAAY,EAAE,MAAM,YAAY,CAAA;AAK5E,eAAO,MAAM,aAAa;;;;;;;;;;;EAiBS,CAAA;AAEnC,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;EAMQ,CAAA;AAInC,eAAO,MAAM,YAAY,QAAe,MAAM,iBAAiB,MAAM,KAAG,OAAO,CAAC,MAAM,CAiBrF,CAAA;AAED,eAAO,MAAM,YAAY,QAAe,MAAM,iBAAiB,MAAM,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmBvH,CAAA;AAED,eAAO,MAAM,cAAc,aAAc,YAAY,gBAAgB,MAAM,YAAY,MAAM,KAAG,eAkC/F,CAAA"}

package/library/manifest.js

@@ -3,6 +3,7 @@ import { Type } from '@sinclair/typebox';
 import { TypeCompiler } from '@sinclair/typebox/compiler';
 import { RunXError, invariant } from './errors.js';
 const identifier = '^[a-z][a-z0-9-]*$';
+const semver = '^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$';
 export const CommandSchema = Type.Object({
     uid: Type.String({ pattern: identifier }),
     id: Type.String({ pattern: identifier }),
@@ -22,10 +23,11 @@ export const CommandSchema = Type.Object({
     confirm: Type.Optional(Type.Union([Type.Literal('never'), Type.Literal('always')])),
 }, { additionalProperties: false });
 export const ManifestSchema = Type.Object({
-    version: Type.Literal(1),
+    version: Type.String({ pattern: semver }),
     project: Type.Optional(Type.Object({ name: Type.String({ minLength: 1 }) }, { additionalProperties: false })),
+    scripts: Type.Object({ directory: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
     groups: Type.Record(Type.String({ pattern: identifier }), Type.Object({ summary: Type.String({ minLength: 1 }) }, { additionalProperties: false })),
-    commands: Type.Array(CommandSchema, { minItems: 1 }),
+    commands: Type.Array(CommandSchema),
 }, { additionalProperties: false });
 const manifestCheck = TypeCompiler.Compile(ManifestSchema);
 export const findManifest = async (cwd, explicitFile) => {
@@ -96,6 +98,17 @@ export const resolveCommand = (manifest, manifestPath, selector) => {
     };
 };
 const validateManifestSemantics = (manifest, path) => {
+    const versionMajor = manifest.version.split('.', 1)[0];
+    if (versionMajor !== '1') {
+        throw new RunXError(`Unsupported RunX manifest version "${manifest.version}" in ${path}. Supported major version: 1.`);
+    }
+    const manifestDirectory = dirname(path);
+    const scriptsDirectory = resolve(manifestDirectory, manifest.scripts.directory);
+    const relativeScriptsDirectory = relative(manifestDirectory, scriptsDirectory);
+    invariant(relativeScriptsDirectory !== '' && relativeScriptsDirectory !== '.' && !isAbsolute(relativeScriptsDirectory) && !relativeScriptsDirectory.startsWith('..'), `Scripts directory "${manifest.scripts.directory}" must be a relative subdirectory inside the manifest directory in ${path}.`);
+    if (!manifest.groups.public) {
+        throw new RunXError(`RunX manifest ${path} must define the default "public" group.`);
+    }
     const uids = new Set();
     const selectors = new Set();
     for (const command of manifest.commands) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/runx",
   "description": "A language-agnostic, documented command catalog and local CLI executor.",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "type": "module",
   "main": "./library/guiho-runx.js",
   "types": "./library/guiho-runx.d.ts",