This is an automated email from the ASF dual-hosted git repository.

luigidemasi pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-kit.git

commit db25880da3f82bc3c2f2432eb846329b7d1672a9
Author: Luigi De Masi <[email protected]>
AuthorDate: Tue Nov 17 23:18:04 2026 +0100

    Align Java 21 and harden Aesh CLI compatibility
    
    Fix Windows context fixtures, require nonempty tagged CI suites, and report
    Linux and cross-platform job results independently. Keep malformed option
    errors typed and preserve clean redirected output and interactive rendering.
    
    Share existing help binding, reuse core init directly, simplify imports,
    and enforce a released Aesh host for Kit releases. Align the launchers,
    publishing workflows, Knowledge baseline, and documentation on Java 21.
    
    Co-authored-by: OpenAI Codex <[email protected]>
---
 .github/workflows/build.yml                        | 35 +++++++-------
 .github/workflows/release.yml                      |  4 +-
 .github/workflows/snapshot.yml                     |  4 +-
 .oss-ai-helper-rules/project-standards.md          |  2 +-
 CHANGELOG.md                                       |  7 ++-
 CONTRIBUTING.md                                    |  4 +-
 README.md                                          |  5 +-
 docs/commands.md                                   |  5 +-
 docs/modules/ROOT/pages/contributing.adoc          |  8 ++--
 docs/modules/ROOT/pages/getting-started.adoc       | 12 +++--
 docs/modules/ROOT/pages/ship.adoc                  |  3 +-
 docs/releasing.md                                  |  6 +++
 docs/security-model.md                             |  2 +-
 kit/README.md                                      |  2 +-
 kit/camel-jbang-plugin-kit/README.md               |  7 ++-
 kit/camel-jbang-plugin-kit/pom.xml                 |  2 -
 .../org/apache/camel/kit/jbang/CamelKitPlugin.java |  7 +--
 .../org/apache/camel/kit/jbang/KitCommand.java     | 10 +---
 .../org/apache/camel/kit/jbang/KitInitCommand.java | 20 --------
 .../camel/kit/CamelKitCommandParityTest.java       | 25 +++++++---
 .../camel/kit/HostedCliCompatibilityTest.java      | 36 ++++++++++++--
 .../apache/camel/kit/jbang/CamelKitPluginTest.java | 19 +++++---
 .../java/org/apache/camel/kit/ArgumentFiles.java   |  3 +-
 .../java/org/apache/camel/kit/CamelKitMain.java    | 33 +++++++------
 .../java/org/apache/camel/kit/CommandRunner.java   | 14 ++++--
 .../apache/camel/kit/command/CamelKitCommand.java  |  7 +--
 .../org/apache/camel/kit/command/CliCommand.java   |  5 +-
 .../apache/camel/kit/command/HelpAwareCommand.java | 10 ++++
 .../org/apache/camel/kit/command/HelpCommand.java  |  3 +-
 .../camel/kit/command/InformationOptionParser.java |  2 +-
 .../apache/camel/kit/command/KitOptionParser.java  | 13 +++--
 .../kit/command/graph/GraphGenerateCommand.java    |  3 +-
 .../camel/kit/command/graph/GraphQueryCommand.java |  3 +-
 .../kit/command/graph/GraphVisualizeCommand.java   |  6 ++-
 .../apache/camel/kit/command/ship/ShipCommand.java | 15 +++---
 .../apache/camel/kit/AeshCliCompatibilityTest.java | 56 +++++++++++++++++++---
 .../org/apache/camel/kit/ArgumentFilesTest.java    |  2 +
 .../org/apache/camel/kit/CamelKitMainShipTest.java | 15 ++++--
 .../kit/command/graph/GraphQueryCommandTest.java   |  3 +-
 .../camel/kit/command/ship/ShipCommandTest.java    | 17 ++++---
 .../parser/ParserSourceReadingContractTest.java    |  2 +-
 kit/camel-kit-main/dist/CamelKit.java              |  2 +-
 .../src/main/jbang/main/CamelKit.java              |  2 +-
 knowledge/README.md                                |  2 +-
 pom.xml                                            |  2 +-
 tools/release_target.py                            |  9 ++++
 tools/test_release_target.py                       | 32 +++++++++++++
 47 files changed, 320 insertions(+), 166 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 64fa3095..677def7d 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -23,7 +23,7 @@ jobs:
 
     strategy:
       matrix:
-        java: [17, 21, 25]
+        java: [21, 25]
       fail-fast: false
 
     steps:
@@ -46,16 +46,10 @@ jobs:
         run: ./mvnw -B -Psourcecheck validate
 
       - name: Build and certify Ship payloads
-        run: |
-          if [ "${{ matrix.java }}" = "17" ]; then
-            # Camel 4.24 requires Java 21; certify standalone Kit and 
Knowledge on Java 17.
-            ./mvnw -B -V -Plinux-ship-certification -pl 
'!kit/camel-jbang-plugin-kit' -Dformat.skip=true -Deval.requireVectors=true 
clean install
-          else
-            ./mvnw -B -V -Plinux-ship-certification -Dformat.skip=true 
-Deval.requireVectors=true clean install
-          fi
+        run: ./mvnw -B -V -Plinux-ship-certification -Dformat.skip=true 
-Deval.requireVectors=true clean install
 
       - name: Upload build artifacts
-        if: success() && matrix.java == '17'
+        if: success() && matrix.java == '21'
         uses: actions/[email protected]
         with:
           name: build-artifacts-java${{ matrix.java }}-${{ github.sha }}
@@ -82,7 +76,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [macos-latest, windows-latest]
-        java: [17, 21, 25]
+        java: [21, 25]
     steps:
       - uses: actions/[email protected]
       - uses: actions/[email protected]
@@ -93,11 +87,15 @@ jobs:
       - name: Verify token binding, host discovery, redirected output and 
generated command prefixes
         shell: bash
         run: |
-          if [ "${{ matrix.java }}" = "17" ]; then
-            ./mvnw -B -pl kit/camel-kit-main -am test 
-Dtest=AeshCliCompatibilityTest,ArgumentFilesTest,CamelKitMainShipTest 
-Dsurefire.failIfNoSpecifiedTests=false
-          else
-            ./mvnw -B -pl kit/camel-jbang-plugin-kit -am test 
"-Dtest=AeshCliCompatibilityTest,ArgumentFilesTest,CamelKitMainShipTest,CamelKitPluginTest,CamelKitCommandParityTest#nativeInitAndRegenerationDetectThePrefixInSeparateProcesses+pluginRegistersStandaloneCommandSurface+bob2InitAndRegenerationExposeTheSamePublicSkills+pluginForwardsWithCitrusMcpOption,HostedCliCompatibilityTest"
 -Dsurefire.failIfNoSpecifiedTests=false
-          fi
+          ./mvnw -B -pl kit/camel-jbang-plugin-kit -am install -DskipTests
+          ./mvnw -B -pl kit/camel-kit-core,kit/camel-jbang-plugin-kit test 
-Dgroups=cli-compat -DfailIfNoTests=true
+      - name: Upload CLI compatibility results
+        if: always()
+        uses: actions/[email protected]
+        with:
+          name: cli-results-${{ matrix.os }}-java${{ matrix.java }}-${{ 
github.sha }}
+          path: '**/target/surefire-reports/*.xml'
+          retention-days: 7
 
   comment-pr:
     name: Comment PR Status
@@ -117,12 +115,11 @@ jobs:
             const compatibilityResult = '${{ needs.cli-compatibility.result 
}}';
             const success = buildResult === 'success' && compatibilityResult 
=== 'success';
             const emoji = success ? '✅' : '❌';
-            const status = success ? 'successful' : 'failed';
 
-            const message = `${emoji} Build ${status} for commit 
${context.sha.substring(0, 7)}
+            const message = `${emoji} Build checks for commit 
${context.payload.pull_request.head.sha.substring(0, 7)}
 
-            **Java Version Tests:**
-            All Java versions (17, 21, 25) ${success ? 'passed ✅' : 'had 
failures ❌'}
+            **Java 21 and 25:**
+            Linux build and tests: ${buildResult}
             macOS/Windows CLI compatibility: ${compatibilityResult}
 
             ${success ? 'Build artifacts are available in the workflow run.' : 
`Please check the [workflow 
run](${context.payload.repository.html_url}/actions/runs/${context.runId}) for 
details.`}`;
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 115e82a0..ef145405 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -48,10 +48,10 @@ jobs:
           [[ "$(git rev-parse "refs/tags/${RELEASE_TAG}^{commit}")" == 
"$EXPECTED_SHA" ]]
           python3 tools/release_target.py "$RELEASE_TARGET" --tag 
"$RELEASE_TAG" --check-published-parent
 
-      - name: Set up JDK 17 and Maven Central settings
+      - name: Set up JDK 21 and Maven Central settings
         uses: actions/[email protected]
         with:
-          java-version: '17'
+          java-version: '21'
           distribution: temurin
           cache: maven
           server-id: central
diff --git a/.github/workflows/snapshot.yml b/.github/workflows/snapshot.yml
index 989553e1..ac54f90c 100644
--- a/.github/workflows/snapshot.yml
+++ b/.github/workflows/snapshot.yml
@@ -23,10 +23,10 @@ jobs:
       - name: Checkout code
         uses: actions/[email protected]
 
-      - name: Set up JDK 17
+      - name: Set up JDK 21
         uses: actions/[email protected]
         with:
-          java-version: '17'
+          java-version: '21'
           distribution: temurin
           cache: maven
           server-id: central
diff --git a/.oss-ai-helper-rules/project-standards.md 
b/.oss-ai-helper-rules/project-standards.md
index 0e8422bf..94dde98c 100644
--- a/.oss-ai-helper-rules/project-standards.md
+++ b/.oss-ai-helper-rules/project-standards.md
@@ -12,7 +12,7 @@ This file contains build, test, format, and code-style 
expectations for the came
 
 ## Code Style
 
-- Java 17+ for standalone Kit and Knowledge; Java 21+ for the Camel plugin and 
full-reactor builds
+- Java 21+ for Kit, the Camel plugin, Knowledge, and all builds
 - Max line length: 120 characters
 - Follow standard Java conventions
 - Prefer composition over inheritance
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 22559385..9279e31d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,10 +12,9 @@ and this project adheres to [Semantic 
Versioning](https://semver.org/spec/v2.0.0
 
 - Migrate the standalone CLI and Camel JBang plugin from Picocli to Aesh 
(#171), retaining one-shot execution,
   ordered Ship context, validation before side effects, and machine-readable 
output. The plugin now requires
-  the Aesh-based Camel 4.24.0 line and Java 21+ (currently tested with 
4.24.0-SNAPSHOT); standalone Kit remains
-  compatible with Java 17+, and generated integration version defaults
-  are unchanged. For literal leading `@` values in the plugin, use `@@value` 
or `--text=@value`, following the
-  host's argument-file policy. Standalone Ship continues to accept literal 
`@value`.
+  the Aesh-based Camel 4.24.0 line (currently tested with 4.24.0-SNAPSHOT). 
Kit, its plugin, and Knowledge
+  now require Java 21+. Generated integration version defaults are unchanged. 
For literal leading `@` values in the plugin, use `@@value` or `--text=@value`, 
following the
+  host's argument-file policy; an unescaped missing file fails before the 
plugin runs. Standalone Ship continues to accept literal `@value`.
 
 ### Monorepo migration
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3a022bab..bbcdb7de 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,7 +27,7 @@ This project follows the [Apache Software Foundation Code of 
Conduct](https://ww
 
 ### Prerequisites
 
-- Java 21 or higher for the full reactor (standalone Kit and Knowledge also 
support Java 17)
+- Java 21 or higher for Kit, its plugin, Knowledge, and the full reactor
 - [JBang](https://www.jbang.dev/) (for running the CLI)
 - Maven 3.9+ (included via Maven Wrapper)
 - Git
@@ -84,7 +84,7 @@ CLI commands use Aesh's one-shot argv runtime. Keep error 
output on stderr, retu
 performing side effects, and keep service/controller logic independent of 
parsing. `camel.cli.version` pins
 the Camel JBang plugin host; `camel.main.version` continues to select the 
generated integration runtime.
 The current plugin build targets the Aesh-based Camel 4.24.0 development line 
and requires Java 21 or later.
-Standalone Kit retains Java 17 support; the Java 17 CI lane excludes the host 
plugin. It cannot load in older Picocli hosts.
+Kit and Knowledge also require Java 21 or later. CI covers Java 21 and 25, 
including the plugin. The plugin cannot load in older Picocli hosts.
 
 ## Project Structure
 
diff --git a/README.md b/README.md
index 3a82be30..37f802bf 100644
--- a/README.md
+++ b/README.md
@@ -44,9 +44,8 @@ modules use `org.apache.camel`.
 
 ## Building from source
 
-Use Java 21 or later and the checked-in Maven wrapper for the full reactor.
-Standalone Kit and Knowledge also support Java 17; the Aesh-based Camel plugin 
requires Java 21. Run these commands from
-the repository root:
+Kit, its Camel JBang plugin, and Knowledge require Java 21 or later. Use the 
checked-in Maven wrapper
+and run these commands from the repository root:
 
 ```bash
 git clone https://github.com/apache/camel-kit.git
diff --git a/docs/commands.md b/docs/commands.md
index 1b2c1cd0..2b8db926 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -1205,4 +1205,7 @@ Development builds use Aesh. The plugin targets the Camel 
host selected by `came
 See the [installation guide](modules/ROOT/pages/getting-started.adoc#cli-host).
 Standalone Ship preserves literal `@` values. The new plugin follows Camel's 
argument-file policy: use
 `--text @@literal` or `--text=@literal` to pass `@literal`; shell quotes alone 
do not prevent expansion.
-Use `-h`/`--help` for help and root `-V`/`--version` for the Kit artifact 
version.
+An unescaped missing file produces `Argument file not found` and exit code 2 
before Kit runs.
+Development Kit and Knowledge require Java 21 or later.
+Use `-h`/`--help` on the root, `init`, `doctor` or `ship`, and the `help` 
subcommand for `doc`, `graph` and `plan`.
+Use root `-V`/`--version` for the Kit artifact version.
diff --git a/docs/modules/ROOT/pages/contributing.adoc 
b/docs/modules/ROOT/pages/contributing.adoc
index 0baa354a..3b8ff6fb 100644
--- a/docs/modules/ROOT/pages/contributing.adoc
+++ b/docs/modules/ROOT/pages/contributing.adoc
@@ -10,8 +10,8 @@ https://www.apache.org/foundation/policies/conduct.html[ASF 
code of conduct].
 [[build]]
 == Building
 
-You need Java 21 or later for the full reactor, JBang, and Git; Maven comes 
with the wrapper.
-Standalone Kit and Knowledge retain Java 17 support; omit 
`kit/camel-jbang-plugin-kit` when building on Java 17. Always build with the 
wrapper, from the
+You need Java 21 or later for Kit and Knowledge, JBang, and Git; Maven comes 
with the wrapper.
+Always build with the wrapper, from the
 repository root.
 
 [source,bash]
@@ -98,7 +98,9 @@ tests read, and `docs/user-guide.md`; keep them in step with 
these pages when be
 == Releasing
 
 The shared parent, Kit and Knowledge have independent versions and release 
schedules.
-A product release references a published, released shared parent. Use the 
corresponding
+A product release references a published, released shared parent. All release 
jobs use Java 21.
+Kit release validation also requires a released `camel.cli.version` and a 
synchronized Maven mirror;
+snapshot and prerelease host pins cannot be staged. Verify the released 
Aesh-based host with the CLI compatibility suite. Use the corresponding
 POM (`pom.xml` with `-N`, `kit/pom.xml`, or `knowledge/pom.xml`) when 
preparing or staging a
 release; never deploy the root reactor to release one product.
 
diff --git a/docs/modules/ROOT/pages/getting-started.adoc 
b/docs/modules/ROOT/pages/getting-started.adoc
index 225eadbf..a833466d 100644
--- a/docs/modules/ROOT/pages/getting-started.adoc
+++ b/docs/modules/ROOT/pages/getting-started.adoc
@@ -11,8 +11,8 @@ xref:manual::camel-jbang.adoc[Camel JBang]. Both forms 
provide the same commands
 |===
 | Requirement | Purpose | Install
 
-| Java 17 or later
-| Runtime for Camel Kit, Camel JBang and the generated projects
+| Java 21 or later
+| Runtime for development Kit, Knowledge and the Aesh-based Camel JBang host
 | SDKMAN, Adoptium or your package manager
 
 | https://www.jbang.dev/[JBang]
@@ -32,6 +32,9 @@ xref:manual::camel-jbang.adoc[Camel JBang]. Both forms 
provide the same commands
 | Docker Engine or Docker Desktop
 |===
 
+Released Kit {camel-kit-version} and Knowledge {camel-kit-knowledge-version} 
still support Java 17.
+Generated integrations have their own Java requirements, determined by their 
selected Camel runtime.
+
 Camel JBang and its test plugin are needed for the complete execution and 
verification loops. When Docker is not
 available, the checks that need containers are reported as skipped; design, 
planning and the container-free checks
 still work. `camel-kit init` checks Java, JBang, Camel JBang and the test 
plugin and reports missing tools as
@@ -160,10 +163,11 @@ release coordinates; this page is updated with it.
 
 The development CLI uses Aesh in both entry points. The plugin requires the 
Aesh-based Camel 4.24.0 line;
 the current build is tested against `{camel-cli-version}`. This host requires 
Java 21 or later. Use that development host for source/snapshot testing.
-A released Camel 4.24.0 host must be verified before releasing this Kit 
version. Older Picocli-based hosts cannot
+Kit release validation rejects a snapshot `camel.cli.version`; a released 
Camel 4.24.0 host must be verified before releasing this Kit version. Older 
Picocli-based hosts cannot
 load the new plugin. These requirements do not change the released 
{camel-kit-version} plugin.
 
-The standalone `camel-kit` launcher continues to support Java 17 or later, 
supplies its own parser and does not require a Camel host to parse commands.
+The standalone `camel-kit` launcher and source-built Knowledge also require 
Java 21 or later.
+Standalone Kit supplies its own parser and does not require a Camel host to 
parse commands.
 The existing JLine/TamboUI rendering remains in place. The host pin 
`camel.cli.version` is independent of
 `camel.main.version`, so upgrading the CLI host does not change the defaults 
or supported versions of generated
 integrations. All pins live in `distribution.properties`.
diff --git a/docs/modules/ROOT/pages/ship.adoc 
b/docs/modules/ROOT/pages/ship.adoc
index 531c4afe..8231052b 100644
--- a/docs/modules/ROOT/pages/ship.adoc
+++ b/docs/modules/ROOT/pages/ship.adoc
@@ -63,7 +63,8 @@ With the Aesh-based development plugin, the Camel host 
expands `@file` before Ki
 `camel kit ship --text '@@note'` or `camel kit ship --text=@note` to pass the 
same literal text.
 For a document whose filename starts with `@`, use `--document '@@notes.md'` 
or `[email protected]`.
 To pass two leading `@` characters as a separate plugin value, supply three. 
Quoting preserves shell tokens
-but does not suppress the host's argument-file processing. Other Camel 
commands retain the host's normal policy.
+but does not suppress the host's argument-file processing. An unescaped 
`@missing-file` fails with
+`Argument file not found` and exit code 2 before Kit runs, including when 
supplied as Ship context. Other Camel commands retain the host's normal policy.
 
 [cols="1,1,3"]
 |===
diff --git a/docs/releasing.md b/docs/releasing.md
index 9661352e..0f4047eb 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -17,6 +17,12 @@ Kit's server pin automatically.
 
 ## Prepare a Maven release
 
+Use JDK 21 or later for every release target; the release and snapshot 
workflows use JDK 21.
+Kit release validation rejects snapshot, timestamped snapshot, and prerelease 
Camel CLI host pins.
+Set `camel.cli.version` in `distribution.properties` to a tested released 
Aesh-based Camel host
+(4.24.0 or later), synchronize the Maven mirror, and run the hosted 
compatibility suite before staging.
+Development builds may use the snapshot host. Generated integration pins are 
independent.
+
 1. Start from reviewed source on a release branch. Change only the selected 
product
    POM version and its child parent versions (or only the root version for a 
parent
    release). Set its SCM tag. Keep the other product's version unchanged.
diff --git a/docs/security-model.md b/docs/security-model.md
index bc56a6f1..865c65c8 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -337,7 +337,7 @@ a report against `0.0.2` is triaged on what that release 
documents.
 
 ## 4.5 Assumptions about the environment
 
-- **Host.** Java 17+ and JBang *(documented — README "Prerequisites")*; Camel 
JBang and its test plugin for the
+- **Host.** Java 21+ and JBang *(documented — README "Prerequisites")*; Camel 
JBang and its test plugin for the
   execution and verification loops; Docker only for container-backed checks. 
Ship requires Linux *(documented —
   README, `docs/commands.md`)* and a filesystem that exposes Unix mode and 
link-count attributes and stable file keys
   *(documented — `ShipSecureFilesystem` Javadoc: "Internal bounded read policy 
for Ship trees"; unsupported
diff --git a/kit/README.md b/kit/README.md
index 1a25a91f..a65257bf 100644
--- a/kit/README.md
+++ b/kit/README.md
@@ -57,7 +57,7 @@ Utilities:    /camel-ship          (Technology Preview — 
delegate to the local
 
 | Requirement | Purpose | Install |
 |-------------|---------|---------|
-| Java 17+ | Runtime | [SDKMAN](https://sdkman.io/), 
[Adoptium](https://adoptium.net/), or your package manager |
+| Java 21+ | Runtime | [SDKMAN](https://sdkman.io/), 
[Adoptium](https://adoptium.net/), or your package manager |
 | [JBang](https://www.jbang.dev/) | CLI launcher for camel-kit | See below |
 | [Camel JBang](https://camel.apache.org/manual/camel-jbang.html) | `camel 
run` for route execution and runtime verification | `jbang app install 
camel@apache/camel` |
 | [Camel JBang test plugin](https://camel.apache.org/manual/camel-jbang.html) 
| `camel test run` for Citrus integration tests in the verify loop | `camel 
plugin add test` |
diff --git a/kit/camel-jbang-plugin-kit/README.md 
b/kit/camel-jbang-plugin-kit/README.md
index 71024297..9a6a5db8 100644
--- a/kit/camel-jbang-plugin-kit/README.md
+++ b/kit/camel-jbang-plugin-kit/README.md
@@ -4,8 +4,11 @@ A Camel JBang plugin that exposes Camel-Kit commands under 
`camel kit`.
 
 ## Requirements
 
-- Apache Camel JBang 4.18.0 or higher
-- JDK 17 or higher
+- Development/source builds: Aesh-based Camel JBang 4.24.0 (`4.24.0-SNAPSHOT` 
while under development) and JDK 21 or higher.
+- Released `0.4.1`: Camel JBang 4.18.0 or higher and JDK 17 or higher.
+
+The Aesh plugin cannot load in older Picocli hosts. Kit releases reject a 
snapshot host pin;
+verify the released Camel host before publishing. Standalone Kit and 
source-built Knowledge also require Java 21+.
 
 ## Release Channels
 
diff --git a/kit/camel-jbang-plugin-kit/pom.xml 
b/kit/camel-jbang-plugin-kit/pom.xml
index a3821c4a..fa9a050a 100644
--- a/kit/camel-jbang-plugin-kit/pom.xml
+++ b/kit/camel-jbang-plugin-kit/pom.xml
@@ -13,8 +13,6 @@
     <description>JBang plugin for Camel Kit - Design Apache Camel Integrations 
with AI</description>
 
     <properties>
-        <!-- The Aesh-based Camel host requires Java 21; standalone Kit stays 
on Java 17. -->
-        <maven.compiler.release>21</maven.compiler.release>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 
     </properties>
diff --git 
a/kit/camel-jbang-plugin-kit/src/main/java/org/apache/camel/kit/jbang/CamelKitPlugin.java
 
b/kit/camel-jbang-plugin-kit/src/main/java/org/apache/camel/kit/jbang/CamelKitPlugin.java
index ee64474e..abb524ff 100644
--- 
a/kit/camel-jbang-plugin-kit/src/main/java/org/apache/camel/kit/jbang/CamelKitPlugin.java
+++ 
b/kit/camel-jbang-plugin-kit/src/main/java/org/apache/camel/kit/jbang/CamelKitPlugin.java
@@ -6,11 +6,13 @@ import org.apache.camel.dsl.jbang.core.common.CommandTree;
 import org.apache.camel.dsl.jbang.core.common.Plugin;
 import org.apache.camel.kit.CamelKitMain;
 import org.apache.camel.kit.command.DoctorCommand;
+import org.apache.camel.kit.command.InitCommand;
 import org.apache.camel.kit.command.doc.DocCommand;
 import org.apache.camel.kit.command.graph.GraphCommand;
 import org.apache.camel.kit.command.pipeline.NextIdCommand;
 import org.apache.camel.kit.command.plan.PlanCommand;
 import org.apache.camel.kit.command.ship.ShipCommand;
+import org.apache.camel.kit.output.SystemPrinter;
 
 /**
  * Camel JBang plugin for Camel Kit - Design Apache Camel Integrations with AI
@@ -20,10 +22,9 @@ public class CamelKitPlugin implements Plugin {
 
     @Override
     public void customize(CommandTree commandLine, CamelJBangMain main) {
-        CamelKitMain camelKitMain = new CamelKitMain(new 
org.apache.camel.kit.output.SystemPrinter());
-        camelKitMain.disableTui();
+        CamelKitMain camelKitMain = new CamelKitMain(new SystemPrinter());
         CommandTree kit = new CommandTree(new KitCommand())
-                .addSubcommand("init", new CommandTree(new 
KitInitCommand(main, camelKitMain)))
+                .addSubcommand("init", new CommandTree(new 
InitCommand(camelKitMain)))
                 .addSubcommand("doctor", new CommandTree(new 
DoctorCommand(camelKitMain)))
                 .addSubcommand("doc", new CommandTree(new DocCommand()))
                 .addSubcommand("graph", new CommandTree(new GraphCommand()))
diff --git 
a/kit/camel-jbang-plugin-kit/src/main/java/org/apache/camel/kit/jbang/KitCommand.java
 
b/kit/camel-jbang-plugin-kit/src/main/java/org/apache/camel/kit/jbang/KitCommand.java
index 1b96624b..2e033a49 100644
--- 
a/kit/camel-jbang-plugin-kit/src/main/java/org/apache/camel/kit/jbang/KitCommand.java
+++ 
b/kit/camel-jbang-plugin-kit/src/main/java/org/apache/camel/kit/jbang/KitCommand.java
@@ -1,19 +1,13 @@
 package org.apache.camel.kit.jbang;
 
-import org.apache.camel.kit.command.CliCommand;
-import org.apache.camel.kit.command.InformationOptionParser;
+import org.apache.camel.kit.command.HelpAwareCommand;
 import org.apache.camel.kit.command.KitOptionParser;
 
 import org.aesh.command.CommandDefinition;
 import org.aesh.command.option.Option;
 
 @CommandDefinition(name = "kit", description = "Design Apache Camel 
Integrations with AI", generateHelp = true)
-public class KitCommand extends CliCommand {
-    @org.aesh.command.option.Option(name = "help", shortName = 'h', hasValue = 
false, overrideRequired = true,
-                                    parser = InformationOptionParser.class,
-                                    description = "Display help and exit")
-    protected boolean helpRequested;
-
+public class KitCommand extends HelpAwareCommand {
     @Option(parser = KitOptionParser.class, name = "version", shortName = 'V',
             hasValue = false, description = "Print version information")
     private boolean versionRequested;
diff --git 
a/kit/camel-jbang-plugin-kit/src/main/java/org/apache/camel/kit/jbang/KitInitCommand.java
 
b/kit/camel-jbang-plugin-kit/src/main/java/org/apache/camel/kit/jbang/KitInitCommand.java
deleted file mode 100644
index 7eb5fd52..00000000
--- 
a/kit/camel-jbang-plugin-kit/src/main/java/org/apache/camel/kit/jbang/KitInitCommand.java
+++ /dev/null
@@ -1,20 +0,0 @@
-package org.apache.camel.kit.jbang;
-
-import org.apache.camel.dsl.jbang.core.commands.CamelJBangMain;
-import org.apache.camel.kit.CamelKitMain;
-import org.apache.camel.kit.command.InitCommand;
-
-import org.aesh.command.CommandDefinition;
-
-/** Uses the core option binding and initialization behavior inside the Camel 
host. */
-@CommandDefinition(name = "init", description = "Initialize a new Camel-Kit 
project", generateHelp = true)
-public class KitInitCommand extends InitCommand {
-    public KitInitCommand(CamelJBangMain main) {
-        this(main, new CamelKitMain(new 
org.apache.camel.kit.output.SystemPrinter()));
-    }
-
-    public KitInitCommand(CamelJBangMain main, CamelKitMain camelKitMain) {
-        super(camelKitMain);
-        camelKitMain.disableTui();
-    }
-}
diff --git 
a/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/CamelKitCommandParityTest.java
 
b/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/CamelKitCommandParityTest.java
index c702d443..dfeda3ff 100644
--- 
a/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/CamelKitCommandParityTest.java
+++ 
b/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/CamelKitCommandParityTest.java
@@ -7,11 +7,15 @@ import java.util.List;
 import java.util.Properties;
 import java.util.Set;
 import java.util.concurrent.TimeUnit;
+import java.util.function.ToIntFunction;
+import java.util.stream.Collectors;
 
 import org.apache.camel.dsl.jbang.core.commands.CamelJBangMain;
 import org.apache.camel.dsl.jbang.core.common.CommandTree;
 import org.apache.camel.kit.jbang.CamelKitPlugin;
+import org.apache.camel.kit.output.SystemPrinter;
 
+import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 import org.junit.jupiter.params.ParameterizedTest;
@@ -30,9 +34,10 @@ class CamelKitCommandParityTest {
     @TempDir
     Path tempDir;
 
+    @Tag("cli-compat")
     @Test
     void bob2InitAndRegenerationExposeTheSamePublicSkills() throws Exception {
-        CamelKitMain standaloneMain = new CamelKitMain();
+        CamelKitMain standaloneMain = new CamelKitMain(new SystemPrinter());
         standaloneMain.disableTui();
         CommandRunner standalone = CamelKitMain.commandLine(standaloneMain);
         CamelJBangMain main = new CamelJBangMain();
@@ -55,9 +60,10 @@ class CamelKitCommandParityTest {
         }
     }
 
+    @Tag("cli-compat")
     @Test
     void pluginForwardsWithCitrusMcpOption() throws Exception {
-        CamelKitMain standaloneMain = new CamelKitMain();
+        CamelKitMain standaloneMain = new CamelKitMain(new SystemPrinter());
         standaloneMain.disableTui();
         CommandRunner standalone = CamelKitMain.commandLine(standaloneMain);
         CamelJBangMain main = new CamelJBangMain();
@@ -96,7 +102,7 @@ class CamelKitCommandParityTest {
 
     @Test
     void pluginForwardsTheExistingProjectOptions() throws Exception {
-        CamelKitMain standaloneMain = new CamelKitMain();
+        CamelKitMain standaloneMain = new CamelKitMain(new SystemPrinter());
         standaloneMain.disableTui();
         CommandRunner standalone = CamelKitMain.commandLine(standaloneMain);
         CamelJBangMain main = new CamelJBangMain();
@@ -235,6 +241,7 @@ class CamelKitCommandParityTest {
         return config;
     }
 
+    @Tag("cli-compat")
     @ParameterizedTest
     @CsvSource({"false,bob2", "true,bob2", "false,copilot", "true,copilot", 
"false,claude", "true,claude"})
     void nativeInitAndRegenerationDetectThePrefixInSeparateProcesses(boolean 
plugin, String agent) throws Exception {
@@ -292,7 +299,7 @@ class CamelKitCommandParityTest {
 
     public static class InitProcess {
         public static void main(String[] args) {
-            java.util.function.ToIntFunction<String[]> execute;
+            ToIntFunction<String[]> execute;
             boolean plugin = Boolean.parseBoolean(args[0]);
             var invocation
                     = new ArrayList<>(List.of("init", args[1], "--ai", 
args[2], "--silent", "--no-fetch", "--force"));
@@ -304,7 +311,9 @@ class CamelKitCommandParityTest {
                 invocation.add(0, "kit");
             } else {
                 CamelKitMain main = new CamelKitMain();
-                main.disableTui();
+                if (System.console() == null && (main.getTerminal() != null || 
main.isTuiEnabled())) {
+                    throw new AssertionError("Redirected CLI must not acquire 
an interactive terminal");
+                }
                 var command = CamelKitMain.commandLine(main);
                 execute = command::execute;
             }
@@ -319,14 +328,16 @@ class CamelKitCommandParityTest {
         return command;
     }
 
+    @Tag("cli-compat")
     @Test
     void pluginRegistersStandaloneCommandSurface() {
         CamelJBangMain main = new CamelJBangMain();
         CommandTree pluginRoot = new CommandTree(main);
         new CamelKitPlugin().customize(pluginRoot, main);
 
-        assertEquals(CamelKitMain.commandLine(new 
CamelKitMain()).parser().getAllChildParsers().stream()
-                .map(p -> 
p.getProcessedCommand().name()).collect(java.util.stream.Collectors.toSet()),
+        assertEquals(
+                CamelKitMain.commandLine(new CamelKitMain(new 
SystemPrinter())).parser().getAllChildParsers().stream()
+                        .map(p -> 
p.getProcessedCommand().name()).collect(Collectors.toSet()),
                 
pluginRoot.getSubcommands().get("kit").getSubcommands().keySet());
     }
 }
diff --git 
a/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/HostedCliCompatibilityTest.java
 
b/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/HostedCliCompatibilityTest.java
index f8f0f02d..11fc38ba 100644
--- 
a/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/HostedCliCompatibilityTest.java
+++ 
b/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/HostedCliCompatibilityTest.java
@@ -10,14 +10,17 @@ import java.util.jar.JarOutputStream;
 
 import org.apache.camel.dsl.jbang.core.commands.CamelJBangMain;
 import org.apache.camel.kit.jbang.CamelKitPlugin;
+import org.apache.camel.kit.jbang.KitVersionProvider;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 
 import static org.junit.jupiter.api.Assertions.*;
 
 /** Real Camel startup, including plugin discovery, argument files and 
redirected process output. */
+@Tag("cli-compat")
 class HostedCliCompatibilityTest {
     @TempDir
     Path directory;
@@ -26,7 +29,7 @@ class HostedCliCompatibilityTest {
     void discoversPluginAndKeepsMachineOutputClean() throws Exception {
         Result version = run("kit", "--version");
         assertEquals(0, version.exit, version.err);
-        assertEquals(new 
org.apache.camel.kit.jbang.KitVersionProvider().getVersion()[0], 
version.out.strip());
+        assertEquals(new KitVersionProvider().getVersion()[0], 
version.out.strip());
         Result help = run("kit", "ship", "--help");
         assertEquals(0, help.exit, help.err);
         assertTrue(help.out.contains("Usage: camel kit ship"), help.out);
@@ -64,10 +67,33 @@ class HostedCliCompatibilityTest {
         Result camel = run("@" + camelArguments);
         assertEquals(0, camel.exit, camel.err);
         assertFalse(camel.out.isBlank());
-        assertNotEquals(new 
org.apache.camel.kit.jbang.KitVersionProvider().getVersion()[0], 
camel.out.strip());
+        assertNotEquals(new KitVersionProvider().getVersion()[0], 
camel.out.strip());
+    }
+
+    @Test
+    void redirectedStandaloneBannerIsPlainEvenWithAnImageCapableEnvironment() 
throws Exception {
+        Result banner = run(CamelKitMain.class);
+        assertEquals(0, banner.exit, banner.err);
+        assertTrue(banner.err.isBlank(), banner.err);
+        assertTrue(banner.out.contains("Design Apache Camel Integrations with 
AI"), banner.out);
+        assertTrue(banner.out.contains("Usage: camel-kit"), banner.out);
+        assertFalse(banner.out.contains("\u001b"), "Redirected output contains 
terminal control sequences");
+    }
+
+    @Test
+    void missingUnescapedContextFileFailsBeforeKitExecutes() throws Exception {
+        Result missing = run("kit", "ship", "--text", "@missing-context", 
"--project-dir", directory.toString());
+        assertEquals(2, missing.exit, missing.err);
+        assertTrue(missing.out.isBlank(), missing.out);
+        assertTrue(missing.err.contains("Argument file not found"), 
missing.err);
+        assertFalse(Files.exists(directory.resolve(".camel-kit")));
     }
 
     private Result run(String... arguments) throws Exception {
+        return run(HostProcess.class, arguments);
+    }
+
+    private Result run(Class<?> entryPoint, String... arguments) throws 
Exception {
         String classpath = System.getProperty("surefire.test.class.path", 
System.getProperty("java.class.path"));
         Path classes = 
Path.of(CamelKitPlugin.class.getProtectionDomain().getCodeSource().getLocation().toURI());
         Path jar = directory.resolve("camel-jbang-plugin-kit.jar");
@@ -87,7 +113,7 @@ class HostedCliCompatibilityTest {
         classpath = classpath.replace(classes.toString(), jar.toString());
         Path javaArguments = directory.resolve("java.args");
         Files.writeString(javaArguments, "--class-path\n" + quote(classpath) + 
"\n"
-                                         + quote("-Duser.home=" + directory) + 
"\n" + HostProcess.class.getName()
+                                         + quote("-Duser.home=" + directory) + 
"\n" + entryPoint.getName()
                                          + "\n");
         List<String> command = new ArrayList<>(
                 List.of(Path.of(System.getProperty("java.home"), "bin", 
"java").toString(),
@@ -96,6 +122,10 @@ class HostedCliCompatibilityTest {
         Path out = directory.resolve("stdout"), err = 
directory.resolve("stderr");
         var builder = new ProcessBuilder(command).directory(directory.toFile())
                 .redirectOutput(out.toFile()).redirectError(err.toFile());
+        if (entryPoint == CamelKitMain.class) {
+            builder.environment().put("TERM", "xterm-kitty");
+            builder.environment().put("KITTY_WINDOW_ID", "185");
+        }
         builder.environment().put("CAMEL_CLI_PLUGIN_CONFIG", 
directory.resolve("plugins.json").toString());
         Process process = builder.start();
         process.getOutputStream().close();
diff --git 
a/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/jbang/CamelKitPluginTest.java
 
b/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/jbang/CamelKitPluginTest.java
index 61ef1c16..9ac8fb9d 100644
--- 
a/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/jbang/CamelKitPluginTest.java
+++ 
b/kit/camel-jbang-plugin-kit/src/test/java/org/apache/camel/kit/jbang/CamelKitPluginTest.java
@@ -7,18 +7,23 @@ import java.util.List;
 
 import org.apache.camel.dsl.jbang.core.commands.CamelJBangMain;
 import org.apache.camel.dsl.jbang.core.common.CommandTree;
+import org.apache.camel.kit.CamelKitMain;
 import org.apache.camel.kit.CommandRunner;
+import org.apache.camel.kit.command.InitCommand;
 import org.apache.camel.kit.command.doc.DocCommand;
 import org.apache.camel.kit.command.pipeline.NextIdCommand;
 import org.apache.camel.kit.command.ship.ShipCommand;
+import org.apache.camel.kit.output.SystemPrinter;
 import org.apache.camel.kit.ship.context.ShipContext;
 
 import org.aesh.command.impl.parser.ArgfileExpander;
+import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 
 import static org.junit.jupiter.api.Assertions.*;
 
+@Tag("cli-compat")
 class CamelKitPluginTest {
 
     @TempDir
@@ -26,7 +31,7 @@ class CamelKitPluginTest {
 
     @Test
     void kitInitDefaultsToBob2WhenAgentOptionIsOmitted() throws Exception {
-        KitInitCommand command = new KitInitCommand(new CamelJBangMain());
+        InitCommand command = new InitCommand(new CamelKitMain(new 
SystemPrinter()));
 
         new CommandRunner(command).parse("orders");
 
@@ -35,7 +40,7 @@ class CamelKitPluginTest {
 
     @Test
     void kitInitAcceptsCodexAndShowsItInHelp() throws Exception {
-        KitInitCommand command = new KitInitCommand(new CamelJBangMain());
+        InitCommand command = new InitCommand(new CamelKitMain(new 
SystemPrinter()));
         CommandRunner commandLine = new CommandRunner(command);
 
         commandLine.parse("orders", "--ai", "codex");
@@ -74,13 +79,15 @@ class CamelKitPluginTest {
         assertEquals("camel kit ship", ship.getQualifiedName());
         assertEquals(List.of(new ShipContext.TextInput(literal)),
                 inputs(parseShip(main, "kit", "ship", "--text", "@" + 
literal)));
-        assertEquals(List.of(new ShipContext.DocumentInput(Path.of(literal))),
-                inputs(parseShip(main, "kit", "ship", "--document", "@" + 
literal)));
+        assertEquals(List.of(new 
ShipContext.DocumentInput(Path.of("@notes.md"))),
+                inputs(parseShip(main, "kit", "ship", "--document", 
"@@notes.md")));
         assertEquals(List.of(new ShipContext.TextInput(literal)),
                 inputs(parseShip(main, "kit", "--version=true", "ship", 
"--text", "@" + literal)));
+        assertEquals(List.of(new 
ShipContext.DocumentInput(context.toAbsolutePath())),
+                inputs(parseShip(main, "kit", "ship", "--document", 
context.toAbsolutePath().toString())));
         root.parse(ArgfileExpander.expand(new String[]{"@" + 
arguments.toAbsolutePath()}));
-        KitInitCommand init
-                = (KitInitCommand) 
root.getSubcommands().get("kit").getSubcommands().get("init").getCommand();
+        InitCommand init
+                = (InitCommand) 
root.getSubcommands().get("kit").getSubcommands().get("init").getCommand();
         assertEquals("orders", init.projectName);
         assertEquals("codex", init.ai);
 
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/ArgumentFiles.java 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/ArgumentFiles.java
index 6fc4af83..ef1448d0 100644
--- a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/ArgumentFiles.java
+++ b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/ArgumentFiles.java
@@ -4,6 +4,7 @@ import java.io.File;
 import java.io.FileReader;
 import java.io.IOException;
 import java.io.StreamTokenizer;
+import java.nio.charset.Charset;
 import java.util.ArrayList;
 import java.util.HashSet;
 import java.util.List;
@@ -32,7 +33,7 @@ final class ArgumentFiles {
             if (!file.canRead()) {
                 expanded.add(argument);
             } else if (visited.add(file.getAbsolutePath())) {
-                try (var reader = new FileReader(file, 
java.nio.charset.Charset.defaultCharset())) {
+                try (var reader = new FileReader(file, 
Charset.defaultCharset())) {
                     var tokenizer = new StreamTokenizer(reader);
                     tokenizer.resetSyntax();
                     tokenizer.wordChars(' ', 255);
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/CamelKitMain.java 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/CamelKitMain.java
index e5684196..6c852a0a 100644
--- a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/CamelKitMain.java
+++ b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/CamelKitMain.java
@@ -4,8 +4,8 @@ import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 
-import org.apache.camel.kit.command.CliCommand;
 import org.apache.camel.kit.command.DoctorCommand;
+import org.apache.camel.kit.command.HelpAwareCommand;
 import org.apache.camel.kit.command.InformationOptionParser;
 import org.apache.camel.kit.command.InitCommand;
 import org.apache.camel.kit.command.doc.DocCommand;
@@ -35,12 +35,7 @@ import org.jline.utils.AttributedStyle;
                    name = "camel-kit",
                    generateHelp = true,
                    description = "Design Apache Camel integrations with AI 
coding assistants")
-public class CamelKitMain extends CliCommand {
-    @org.aesh.command.option.Option(name = "help", shortName = 'h', hasValue = 
false, overrideRequired = true,
-                                    parser = InformationOptionParser.class,
-                                    description = "Display help and exit")
-    protected boolean helpRequested;
-
+public class CamelKitMain extends HelpAwareCommand {
     private static DistributionConfig DISTRIBUTION = loadDistribution();
 
     public static String LATEST_CAMEL_LTS_VERSION = 
DISTRIBUTION.camelMainVersion();
@@ -63,6 +58,11 @@ public class CamelKitMain extends CliCommand {
             = org.apache.camel.kit.tui.TaskTracker.noop();
 
     public CamelKitMain() {
+        if (System.console() == null) {
+            this.printer = new SystemPrinter();
+            this.tuiEnabled = false;
+            return;
+        }
         try {
             this.terminal = TerminalBuilder.builder()
                     .system(true)
@@ -206,10 +206,11 @@ public class CamelKitMain extends CliCommand {
     public void printBanner() {
         int terminalWidth = terminal != null ? terminal.getWidth() : 80;
         int terminalHeight = terminal != null ? terminal.getHeight() : 24;
+        boolean interactive = System.console() != null;
 
         printer.println();
 
-        boolean imageRendered = LogoRenderer.tryRender(System.out, 
terminalWidth, terminalHeight);
+        boolean imageRendered = interactive && 
LogoRenderer.tryRender(System.out, terminalWidth, terminalHeight);
 
         if (!imageRendered) {
             // ASCII art fallback
@@ -222,9 +223,9 @@ public class CamelKitMain extends CliCommand {
                 camelLines = new String[]{""};
                 bannerLines = new String[]{""};
             }
-            printCenteredBlock(camelLines, AnsiColors.CAMEL_GRADIENT);
+            printCenteredBlock(camelLines, AnsiColors.CAMEL_GRADIENT, 
interactive);
             printer.println();
-            printCenteredBlock(bannerLines, AnsiColors.CAMEL_GRADIENT);
+            printCenteredBlock(bannerLines, AnsiColors.CAMEL_GRADIENT, 
interactive);
         }
 
         printer.println();
@@ -240,8 +241,12 @@ public class CamelKitMain extends CliCommand {
         // "Camel-Kit — " dimmed, rest in amber
         int splitAt = "Camel-Kit \u2014 ".length();
         printer.print(pad);
-        printer.print(new AttributedString(tagline.substring(0, splitAt), 
dimStyle).toAnsi(terminal));
-        printer.println(new AttributedString(tagline.substring(splitAt), 
mainStyle).toAnsi(terminal));
+        printer.print(!interactive
+                ? tagline.substring(0, splitAt)
+                : new AttributedString(tagline.substring(0, splitAt), 
dimStyle).toAnsi(terminal));
+        printer.println(!interactive
+                ? tagline.substring(splitAt)
+                : new AttributedString(tagline.substring(splitAt), 
mainStyle).toAnsi(terminal));
         printer.println();
     }
 
@@ -249,7 +254,7 @@ public class CamelKitMain extends CliCommand {
      * Prints a block of text centered on the terminal screen. Calculates 
padding once based on the longest line to
      * preserve the block's shape.
      */
-    private void printCenteredBlock(String[] lines, int[] colors) {
+    private void printCenteredBlock(String[] lines, int[] colors, boolean 
interactive) {
         int terminalWidth = (terminal != null && terminal.getWidth() > 0) ? 
terminal.getWidth() : 100;
 
         // Find max width of the block
@@ -265,7 +270,7 @@ public class CamelKitMain extends CliCommand {
             int color = colors[i % colors.length];
             AttributedStyle style = 
AttributedStyle.DEFAULT.foregroundRgb(color);
             printer.print(paddingStr);
-            printer.println(new AttributedString(lines[i], 
style).toAnsi(terminal));
+            printer.println(!interactive ? lines[i] : new 
AttributedString(lines[i], style).toAnsi(terminal));
         }
     }
 }
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/CommandRunner.java 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/CommandRunner.java
index bc0eba0d..7e2403fc 100644
--- a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/CommandRunner.java
+++ b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/CommandRunner.java
@@ -2,11 +2,13 @@ package org.apache.camel.kit;
 
 import java.io.IOException;
 import java.io.PrintWriter;
+import java.nio.charset.Charset;
 import java.util.EnumSet;
 import java.util.LinkedHashMap;
 import java.util.Map;
 
 import org.apache.camel.kit.command.CliCommand;
+import org.apache.camel.kit.command.KitOptionParser;
 
 import org.aesh.command.AeshCommandRuntimeBuilder;
 import org.aesh.command.Command;
@@ -20,6 +22,7 @@ import 
org.aesh.command.impl.registry.AeshCommandRegistryBuilder;
 import org.aesh.command.impl.shell.StdoutShell;
 import org.aesh.command.invocation.CommandInvocation;
 import org.aesh.command.parser.CommandLineParserException;
+import org.aesh.command.parser.OptionParserException;
 import org.aesh.command.parser.RequiredOptionException;
 import org.aesh.command.validator.CommandValidatorException;
 import org.aesh.command.validator.OptionValidatorException;
@@ -28,8 +31,8 @@ import org.aesh.command.validator.OptionValidatorException;
 public final class CommandRunner {
     private final Command<CommandInvocation> command;
     private final Map<String, CommandRunner> children = new LinkedHashMap<>();
-    private PrintWriter out = new PrintWriter(System.out, true, 
java.nio.charset.Charset.defaultCharset());
-    private PrintWriter err = new PrintWriter(System.err, true, 
java.nio.charset.Charset.defaultCharset());
+    private PrintWriter out = new PrintWriter(System.out, true, 
Charset.defaultCharset());
+    private PrintWriter err = new PrintWriter(System.err, true, 
Charset.defaultCharset());
     private boolean argumentFiles;
     private CommandLineParser<CommandInvocation> parser;
     private CommandContainer<CommandInvocation> container;
@@ -186,11 +189,12 @@ public final class CommandRunner {
 
     // Root information flags excuse unknown tokens and omitted required 
arguments, but never malformed options.
     private static boolean onlyInformationalErrors(CommandLineParser<?> 
parser) {
+        // Kit parsers give malformed options a distinct type. Other parsers 
may use the generic type for them.
+        boolean kitOptions = parser.getProcessedCommand().getOptions().stream()
+                .allMatch(option -> option.parser() instanceof 
KitOptionParser);
         for (var error : parser.getProcessedCommand().parserExceptions()) {
             if (!(error instanceof RequiredOptionException)
-                    && !(error.getMessage().startsWith("The option ") && 
error.getMessage().contains(" is unknown."))
-                    && !error.getMessage().startsWith("Unknown argument ")
-                    && !error.getMessage().startsWith("Unexpected argument ")) 
{
+                    && !(kitOptions && error.getClass() == 
OptionParserException.class)) {
                 return false;
             }
         }
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/CamelKitCommand.java
 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/CamelKitCommand.java
index e7871f05..84adc11f 100644
--- 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/CamelKitCommand.java
+++ 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/CamelKitCommand.java
@@ -7,12 +7,7 @@ import org.apache.camel.kit.util.AnsiColors;
 /**
  * Base class for all Camel-Kit commands (following Camel JBang CamelCommand 
pattern).
  */
-public abstract class CamelKitCommand extends CliCommand {
-    @org.aesh.command.option.Option(name = "help", shortName = 'h', hasValue = 
false, overrideRequired = true,
-                                    parser = InformationOptionParser.class,
-                                    description = "Display help and exit")
-    protected boolean helpRequested;
-
+public abstract class CamelKitCommand extends HelpAwareCommand {
     protected final CamelKitMain main;
 
     protected CamelKitCommand(CamelKitMain main) {
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/CliCommand.java 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/CliCommand.java
index a3a0a5ef..1b4d0b0e 100644
--- 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/CliCommand.java
+++ 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/CliCommand.java
@@ -1,6 +1,7 @@
 package org.apache.camel.kit.command;
 
 import java.io.PrintWriter;
+import java.nio.charset.Charset;
 import java.util.concurrent.Callable;
 
 import org.aesh.command.Command;
@@ -11,8 +12,8 @@ import org.aesh.command.option.ParentCommand;
 
 /** Shared execution and output contract for standalone and hosted commands. */
 public abstract class CliCommand implements Command<CommandInvocation>, 
Callable<Integer> {
-    protected PrintWriter out = new PrintWriter(System.out, true, 
java.nio.charset.Charset.defaultCharset());
-    protected PrintWriter err = new PrintWriter(System.err, true, 
java.nio.charset.Charset.defaultCharset());
+    protected PrintWriter out = new PrintWriter(System.out, true, 
Charset.defaultCharset());
+    protected PrintWriter err = new PrintWriter(System.err, true, 
Charset.defaultCharset());
     protected CommandInvocation invocation;
     @ParentCommand
     protected Command<CommandInvocation> parent;
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/HelpAwareCommand.java
 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/HelpAwareCommand.java
new file mode 100644
index 00000000..385e8796
--- /dev/null
+++ 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/HelpAwareCommand.java
@@ -0,0 +1,10 @@
+package org.apache.camel.kit.command;
+
+import org.aesh.command.option.Option;
+
+/** Opt-in help binding for commands with a public --help option. */
+public abstract class HelpAwareCommand extends CliCommand {
+    @Option(name = "help", shortName = 'h', hasValue = false, overrideRequired 
= true,
+            parser = InformationOptionParser.class, description = "Display 
help and exit")
+    protected boolean helpRequested;
+}
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/HelpCommand.java
 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/HelpCommand.java
index 699532e4..f5f9da82 100644
--- 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/HelpCommand.java
+++ 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/HelpCommand.java
@@ -1,5 +1,6 @@
 package org.apache.camel.kit.command;
 
+import java.util.Arrays;
 import java.util.List;
 
 import org.aesh.command.CommandDefinition;
@@ -14,7 +15,7 @@ public final class HelpCommand extends CliCommand {
     public Integer call() {
         String path = qualifiedName(parent) + (commands.isEmpty() ? "" : " " + 
commands.get(0));
         String help = invocation.getHelpInfo(path);
-        if (help == null || (!commands.isEmpty() && java.util.Arrays.stream(
+        if (help == null || (!commands.isEmpty() && Arrays.stream(
                 
parent.getClass().getAnnotation(CommandDefinition.class).groupCommands())
                 .noneMatch(type -> 
type.getAnnotation(CommandDefinition.class).name().equals(commands.get(0))))) {
             throw new UsageException("Unknown command: " + path);
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/InformationOptionParser.java
 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/InformationOptionParser.java
index 1bfb81ca..ab083b5f 100644
--- 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/InformationOptionParser.java
+++ 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/InformationOptionParser.java
@@ -14,7 +14,7 @@ public final class InformationOptionParser extends 
KitOptionParser {
             for (char name : token.substring(1).toCharArray()) {
                 ProcessedOption flag = 
option.parent().findOption(String.valueOf(name));
                 if (flag == null || !flag.getValues().isEmpty()) {
-                    throw new OptionParserException("Invalid or repeated 
option -" + name);
+                    throw new MalformedOptionException("Invalid or repeated 
option -" + name);
                 }
                 flag.addValue("true");
             }
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/KitOptionParser.java
 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/KitOptionParser.java
index 634bc3c3..6dcc820d 100644
--- 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/KitOptionParser.java
+++ 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/KitOptionParser.java
@@ -11,13 +11,13 @@ public class KitOptionParser implements OptionParser {
     public void parse(ParsedLineIterator iterator, ProcessedOption option) 
throws OptionParserException {
         String token = iterator.pollWord();
         if (!option.hasMultipleValues() && !option.getValues().isEmpty()) {
-            throw new OptionParserException("Option --" + option.name() + " 
may only be specified once");
+            throw new MalformedOptionException("Option --" + option.name() + " 
may only be specified once");
         }
         String attached = token.substring(option.isLongNameUsed() ? 
option.name().length() + 2 : 2);
         if (!option.hasValue()) {
             String value = attached.isEmpty() ? "true" : 
attached.startsWith("=") ? attached.substring(1) : attached;
             if (!value.equalsIgnoreCase("true") && 
!value.equalsIgnoreCase("false")) {
-                throw new OptionParserException("Option --" + option.name() + 
" requires true or false");
+                throw new MalformedOptionException("Option --" + option.name() 
+ " requires true or false");
             }
             option.addValue(value);
             return;
@@ -26,7 +26,7 @@ public class KitOptionParser implements OptionParser {
             option.addValue(attached.startsWith("=") ? attached.substring(1) : 
attached);
         } else {
             if (!hasValue(iterator, option)) {
-                throw new OptionParserException("Option --" + option.name() + 
" requires a value");
+                throw new MalformedOptionException("Option --" + option.name() 
+ " requires a value");
             }
             option.addValue(iterator.pollWord());
         }
@@ -41,4 +41,11 @@ public class KitOptionParser implements OptionParser {
         return iterator.hasNextWord() && !"--".equals(iterator.peekWord())
                 && option.parent().searchAllOptions(iterator.peekWord()) == 
null;
     }
+
+    /** Distinguishes malformed known options from Aesh's unknown/excess token 
errors. */
+    public static final class MalformedOptionException extends 
OptionParserException {
+        public MalformedOptionException(String message) {
+            super(message);
+        }
+    }
 }
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphGenerateCommand.java
 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphGenerateCommand.java
index 5909e4df..c85e407b 100644
--- 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphGenerateCommand.java
+++ 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphGenerateCommand.java
@@ -14,6 +14,7 @@ import org.apache.camel.kit.graph.ParserDiagnostic;
 
 import org.aesh.command.CommandDefinition;
 import org.aesh.command.option.Option;
+import org.aesh.command.option.OptionVisibility;
 
 @CommandDefinition(name = "generate", description = "Generate or rebuild the 
project graph from source files")
 public class GraphGenerateCommand extends CliCommand {
@@ -22,7 +23,7 @@ public class GraphGenerateCommand extends CliCommand {
             converter = PathConverter.class)
     Path output;
     @Option(parser = KitOptionParser.class, name = "project-dir", defaultValue 
= ".",
-            visibility = org.aesh.command.option.OptionVisibility.HIDDEN,
+            visibility = OptionVisibility.HIDDEN,
             converter = PathConverter.class)
     Path projectDir;
 
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphQueryCommand.java
 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphQueryCommand.java
index befcd104..5c40b811 100644
--- 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphQueryCommand.java
+++ 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphQueryCommand.java
@@ -11,13 +11,14 @@ import org.apache.camel.kit.graph.GraphSerializer;
 import org.apache.camel.kit.graph.ProjectGraph;
 
 import org.aesh.command.option.Option;
+import org.aesh.command.option.OptionVisibility;
 
 public abstract class GraphQueryCommand extends CliCommand {
 
     @Option(parser = KitOptionParser.class, name = "graph-file",
             description = "Path to project graph JSON",
             defaultValue = ".camel-kit/project-graph.json",
-            visibility = org.aesh.command.option.OptionVisibility.HIDDEN,
+            visibility = OptionVisibility.HIDDEN,
             converter = PathConverter.class)
     protected Path graphFile;
 
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphVisualizeCommand.java
 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphVisualizeCommand.java
index 282979d6..edeec06d 100644
--- 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphVisualizeCommand.java
+++ 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/graph/GraphVisualizeCommand.java
@@ -13,6 +13,8 @@ import org.apache.camel.kit.graph.GraphVisualizer;
 import org.apache.camel.kit.graph.ProjectGraph;
 
 import org.aesh.command.CommandDefinition;
+import org.aesh.command.completer.CompleterInvocation;
+import org.aesh.command.completer.OptionCompleter;
 import org.aesh.command.option.Option;
 
 @CommandDefinition(name = "visualize", description = "Generate interactive 
HTML graph visualization")
@@ -31,8 +33,8 @@ public class GraphVisualizeCommand extends CliCommand {
     String library;
 
     public static class LibCandidates
-            implements 
org.aesh.command.completer.OptionCompleter<org.aesh.command.completer.CompleterInvocation>
 {
-        public void complete(org.aesh.command.completer.CompleterInvocation 
invocation) {
+            implements OptionCompleter<CompleterInvocation> {
+        public void complete(CompleterInvocation invocation) {
             invocation.addAllCompleterValues(List.of("cytoscape", "d3", 
"vis-network", "antv-g6"));
         }
     }
diff --git 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/ship/ShipCommand.java
 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/ship/ShipCommand.java
index ff5c7ac2..82da8519 100644
--- 
a/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/ship/ShipCommand.java
+++ 
b/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/ship/ShipCommand.java
@@ -9,11 +9,12 @@ import java.util.ArrayList;
 import java.util.Comparator;
 import java.util.List;
 import java.util.Locale;
+import java.util.Objects;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.stream.Stream;
 
-import org.apache.camel.kit.command.CliCommand;
+import org.apache.camel.kit.command.HelpAwareCommand;
 import org.apache.camel.kit.command.InformationOptionParser;
 import org.apache.camel.kit.command.KitOptionParser;
 import org.apache.camel.kit.command.PathConverter;
@@ -31,6 +32,7 @@ import org.aesh.command.converter.ConverterInvocation;
 import org.aesh.command.impl.internal.ProcessedOption;
 import org.aesh.command.option.Option;
 import org.aesh.command.option.OptionList;
+import org.aesh.command.option.OptionVisibility;
 import org.aesh.command.parser.OptionParserException;
 import org.aesh.command.validator.OptionValidatorException;
 import org.aesh.parser.ParsedLineIterator;
@@ -44,12 +46,7 @@ import org.aesh.parser.ParsedLineIterator;
                    generateHelp = true,
                    description = "Technology Preview: start, inspect, resume, 
or abort a local Camel Ship run",
                    footer = "Camel Ship is still being stabilized, may change, 
and is not recommended for production use.")
-public final class ShipCommand extends CliCommand {
-    @org.aesh.command.option.Option(name = "help", shortName = 'h', hasValue = 
false, overrideRequired = true,
-                                    parser = InformationOptionParser.class,
-                                    description = "Display help and exit")
-    protected boolean helpRequested;
-
+public final class ShipCommand extends HelpAwareCommand {
     private ShipController controller;
     private WorkflowLauncher launcher;
 
@@ -92,7 +89,7 @@ public final class ShipCommand extends CliCommand {
     Oversight oversight;
 
     @Option(parser = KitOptionParser.class, name = "project-dir", defaultValue 
= ".",
-            visibility = org.aesh.command.option.OptionVisibility.HIDDEN,
+            visibility = OptionVisibility.HIDDEN,
             converter = PathConverter.class)
     Path projectDirectory;
 
@@ -295,7 +292,7 @@ public final class ShipCommand extends CliCommand {
 
     private void validateArguments() {
         long operations
-                = Stream.of(submit, resume, startFrom, status, 
abort).filter(java.util.Objects::nonNull).count();
+                = Stream.of(submit, resume, startFrom, status, 
abort).filter(Objects::nonNull).count();
         if (operations > 1) {
             throw new UsageException("--submit, --resume, --start-from, 
--status and --abort are mutually exclusive");
         }
diff --git 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/AeshCliCompatibilityTest.java
 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/AeshCliCompatibilityTest.java
index 7d160653..46ed995a 100644
--- 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/AeshCliCompatibilityTest.java
+++ 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/AeshCliCompatibilityTest.java
@@ -4,11 +4,15 @@ import java.io.PrintWriter;
 import java.io.StringWriter;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.util.Arrays;
 import java.util.List;
+import java.util.stream.Stream;
 
 import org.apache.camel.kit.command.InitCommand;
 import org.apache.camel.kit.command.ship.ShipCommand;
+import org.apache.camel.kit.output.SystemPrinter;
 
+import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 import org.junit.jupiter.params.ParameterizedTest;
@@ -16,6 +20,7 @@ import org.junit.jupiter.params.provider.ValueSource;
 
 import static org.junit.jupiter.api.Assertions.*;
 
+@Tag("cli-compat")
 class AeshCliCompatibilityTest {
     @TempDir
     Path directory;
@@ -28,18 +33,55 @@ class AeshCliCompatibilityTest {
     void rejectsMalformedShipOptionsBeforeExecution(String arguments) {
         var error = new StringWriter();
         assertEquals(2, new CommandRunner(new ShipCommand()).setErr(new 
PrintWriter(error))
-                .execute(java.util.stream.Stream
-                        .concat(java.util.stream.Stream.of("--project-dir", 
directory.toString()),
-                                java.util.Arrays.stream(arguments.split(" ")))
+                .execute(Stream
+                        .concat(Stream.of("--project-dir", 
directory.toString()),
+                                Arrays.stream(arguments.split(" ")))
                         .toArray(String[]::new)),
                 error.toString());
         assertFalse(Files.exists(directory.resolve(".camel-kit")));
         assertFalse(error.toString().isBlank());
     }
 
+    @Test
+    void informationFlagsKeepMalformedOptionsStrictAcrossTheCommandTree() {
+        var main = new CamelKitMain(new SystemPrinter());
+        var output = new StringWriter();
+        var error = new StringWriter();
+        var runner = CamelKitMain.commandLine(main).setOut(new 
PrintWriter(output)).setErr(new PrintWriter(error));
+        for (String[] arguments : List.of(
+                new String[]{"--help", "init", "--ai"},
+                new String[]{"--version", "init", "--ai", "codex", "--ai", 
"claude"},
+                new String[]{"--help", "ship", "--json=bad"},
+                new String[]{"--help", "ship", "--text"},
+                new String[]{"--help", "--help"},
+                new String[]{"--help", "-hV"},
+                new String[]{"--help", "init", "--silent", "--silent"},
+                new String[]{"--help", "-hX"},
+                new String[]{"--version", "graph", "migration-context", 
"route", "--depth", "invalid"},
+                new String[]{"--help", "init", "--config", "bad\u0000path"})) {
+            assertEquals(2, runner.execute(arguments), 
List.of(arguments).toString());
+        }
+        assertEquals(0, runner.execute("--help", "graph", "neighbors"));
+        assertEquals(0, runner.execute("--version", "init", "--unknown"));
+        assertEquals(0, runner.execute("--help", "init", "one", "two"));
+    }
+
+    @Test
+    void sharesHelpOnlyAcrossCommandsThatAlreadyExposeIt() {
+        var parser = CamelKitMain.commandLine(new CamelKitMain(new 
SystemPrinter())).parser();
+        
assertNotNull(parser.getProcessedCommand().findLongOptionNoActivatorCheck("help"));
+        for (String name : List.of("init", "doctor", "ship")) {
+            
assertNotNull(parser.getChildParser(name).getProcessedCommand().findLongOptionNoActivatorCheck("help"),
+                    name);
+        }
+        for (String name : List.of("graph", "doc", "plan", "nextId")) {
+            
assertNull(parser.getChildParser(name).getProcessedCommand().findLongOptionNoActivatorCheck("help"),
 name);
+        }
+    }
+
     @Test
     void parentHelpAndVersionNeverExecuteChildren() {
-        CamelKitMain main = new CamelKitMain();
+        CamelKitMain main = new CamelKitMain(new SystemPrinter());
         try {
             var output = new StringWriter();
             var error = new StringWriter();
@@ -70,7 +112,7 @@ class AeshCliCompatibilityTest {
 
     @Test
     void preservesTokenizedValuesCollectionArityAndResetsDefaults() throws 
Exception {
-        CamelKitMain main = new CamelKitMain();
+        CamelKitMain main = new CamelKitMain(new SystemPrinter());
         try {
             InitCommand init = new InitCommand(main);
             CommandRunner runner = new CommandRunner(init);
@@ -96,7 +138,7 @@ class AeshCliCompatibilityTest {
 
     @Test
     void rejectsDuplicateOptionsAndInvalidPathsBeforeWriting() {
-        CamelKitMain main = new CamelKitMain();
+        CamelKitMain main = new CamelKitMain(new SystemPrinter());
         try {
             var error = new StringWriter();
             var runner = CamelKitMain.commandLine(main).setErr(new 
PrintWriter(error));
@@ -113,7 +155,7 @@ class AeshCliCompatibilityTest {
 
     @Test
     void nestedHelpAndBothVersionSpellingsStayOnStdout() {
-        CamelKitMain main = new CamelKitMain();
+        CamelKitMain main = new CamelKitMain(new SystemPrinter());
         try {
             var output = new StringWriter();
             var error = new StringWriter();
diff --git 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/ArgumentFilesTest.java 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/ArgumentFilesTest.java
index 85b7f9d3..a00d07a4 100644
--- 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/ArgumentFilesTest.java
+++ 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/ArgumentFilesTest.java
@@ -3,11 +3,13 @@ package org.apache.camel.kit;
 import java.nio.file.Files;
 import java.nio.file.Path;
 
+import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 
 import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 
+@Tag("cli-compat")
 class ArgumentFilesTest {
     @TempDir
     Path directory;
diff --git 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/CamelKitMainShipTest.java
 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/CamelKitMainShipTest.java
index 826b1d2d..95dabb86 100644
--- 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/CamelKitMainShipTest.java
+++ 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/CamelKitMainShipTest.java
@@ -7,8 +7,10 @@ import java.nio.file.Path;
 import java.util.List;
 
 import org.apache.camel.kit.command.ship.ShipCommand;
+import org.apache.camel.kit.output.SystemPrinter;
 import org.apache.camel.kit.ship.context.ShipContext;
 
+import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 
@@ -16,6 +18,7 @@ import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+@Tag("cli-compat")
 class CamelKitMainShipTest {
 
     @TempDir
@@ -23,7 +26,7 @@ class CamelKitMainShipTest {
 
     @Test
     void registersShipWithQualifiedHelp() {
-        CamelKitMain main = new CamelKitMain();
+        CamelKitMain main = new CamelKitMain(new SystemPrinter());
         try {
             CommandRunner root = CamelKitMain.commandLine(main, "ship", 
"--help");
             var ship = root.parser().getChildParser("ship");
@@ -44,14 +47,16 @@ class CamelKitMainShipTest {
     void preservesLiteralAtContextForShip() throws Exception {
         Path arguments = Files.writeString(tempDir.resolve("ship-arguments"), 
"EXPANDED");
         String literal = "@" + arguments.toAbsolutePath();
-        CamelKitMain main = new CamelKitMain();
+        CamelKitMain main = new CamelKitMain(new SystemPrinter());
         try {
             CommandRunner root = CamelKitMain.commandLine(main, "ship", 
"--text", literal);
 
             root.parse("ship", "--text", literal);
             assertEquals(List.of(new ShipContext.TextInput(literal)), 
inputs(root));
-            root.parse("ship", "--document", literal);
-            assertEquals(List.of(new 
ShipContext.DocumentInput(Path.of(literal))), inputs(root));
+            root.parse("ship", "--document", "@notes.md");
+            assertEquals(List.of(new 
ShipContext.DocumentInput(Path.of("@notes.md"))), inputs(root));
+            root.parse("ship", "--document", 
arguments.toAbsolutePath().toString());
+            assertEquals(List.of(new 
ShipContext.DocumentInput(arguments.toAbsolutePath())), inputs(root));
 
         } finally {
             main.closeTerminal();
@@ -61,7 +66,7 @@ class CamelKitMainShipTest {
     @Test
     void retainsArgumentFileExpansionForOtherStandaloneInvocations() throws 
Exception {
         Path arguments = Files.writeString(tempDir.resolve("root-arguments"), 
"--version\n");
-        CamelKitMain main = new CamelKitMain();
+        CamelKitMain main = new CamelKitMain(new SystemPrinter());
         try {
             CommandRunner root = CamelKitMain.commandLine(main, "@" + 
arguments.toAbsolutePath());
 
diff --git 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/command/graph/GraphQueryCommandTest.java
 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/command/graph/GraphQueryCommandTest.java
index 7d93c094..6426d4c8 100644
--- 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/command/graph/GraphQueryCommandTest.java
+++ 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/command/graph/GraphQueryCommandTest.java
@@ -7,6 +7,7 @@ import java.nio.file.Path;
 
 import org.apache.camel.kit.CommandRunner;
 
+import org.aesh.command.CommandDefinition;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 
@@ -17,7 +18,7 @@ class GraphQueryCommandTest {
     @TempDir
     Path tempDir;
 
-    @org.aesh.command.CommandDefinition(name = "test-query", description = 
"Test query")
+    @CommandDefinition(name = "test-query", description = "Test query")
     static class TestQueryCommand extends GraphQueryCommand {
         @Override
         protected String execute(org.apache.camel.kit.graph.ProjectGraph 
graph) {
diff --git 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/command/ship/ShipCommandTest.java
 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/command/ship/ShipCommandTest.java
index bd6de5df..d372039d 100644
--- 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/command/ship/ShipCommandTest.java
+++ 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/command/ship/ShipCommandTest.java
@@ -10,11 +10,13 @@ import java.nio.file.Path;
 import java.nio.file.attribute.PosixFilePermissions;
 import java.time.Duration;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Locale;
 import java.util.Objects;
 
 import org.apache.camel.kit.CommandRunner;
+import org.apache.camel.kit.command.CliCommand;
 import org.apache.camel.kit.config.DistributionConfig;
 import org.apache.camel.kit.ship.ShipDigest;
 import org.apache.camel.kit.ship.context.ShipContext;
@@ -24,6 +26,7 @@ import 
org.apache.camel.kit.ship.controller.ShipControllerTestSupport;
 import org.apache.camel.kit.ship.controller.ShipCoordinator;
 import org.apache.camel.kit.ship.controller.ShipRun;
 
+import org.aesh.command.CommandDefinition;
 import org.junit.jupiter.api.Assumptions;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.condition.EnabledOnOs;
@@ -1329,22 +1332,22 @@ class ShipCommandTest {
         return new RunResult(exitCode, output.toString(), error.toString());
     }
 
-    @org.aesh.command.CommandDefinition(name = "camel", description = "Test 
host")
-    static class CamelRoot extends org.apache.camel.kit.command.CliCommand {
+    @CommandDefinition(name = "camel", description = "Test host")
+    static class CamelRoot extends CliCommand {
         public Integer call() {
             return 0;
         }
     }
 
-    @org.aesh.command.CommandDefinition(name = "kit", description = "Test 
plugin")
-    static class KitRoot extends org.apache.camel.kit.command.CliCommand {
+    @CommandDefinition(name = "kit", description = "Test plugin")
+    static class KitRoot extends CliCommand {
         public Integer call() {
             return 0;
         }
     }
 
-    @org.aesh.command.CommandDefinition(name = "camel-kit", description = 
"Test standalone")
-    static class StandaloneRoot extends 
org.apache.camel.kit.command.CliCommand {
+    @CommandDefinition(name = "camel-kit", description = "Test standalone")
+    static class StandaloneRoot extends CliCommand {
         public Integer call() {
             return 0;
         }
@@ -1407,7 +1410,7 @@ class ShipCommandTest {
             Path stamp,
             Path publication) {
         String stampDigest = 
ShipDigest.sha256("stamp".getBytes(StandardCharsets.UTF_8));
-        List<ShipRun.StageRecord> stages = 
java.util.Arrays.stream(ShipRun.Stage.values())
+        List<ShipRun.StageRecord> stages = 
Arrays.stream(ShipRun.Stage.values())
                 .map(stage -> {
                     boolean validation = stage == ShipRun.Stage.VALIDATE;
                     return new ShipRun.StageRecord(
diff --git 
a/kit/camel-kit-graph/src/test/java/org/apache/camel/kit/graph/parser/ParserSourceReadingContractTest.java
 
b/kit/camel-kit-graph/src/test/java/org/apache/camel/kit/graph/parser/ParserSourceReadingContractTest.java
index 0d8f38f8..82f1248e 100644
--- 
a/kit/camel-kit-graph/src/test/java/org/apache/camel/kit/graph/parser/ParserSourceReadingContractTest.java
+++ 
b/kit/camel-kit-graph/src/test/java/org/apache/camel/kit/graph/parser/ParserSourceReadingContractTest.java
@@ -38,7 +38,7 @@ class ParserSourceReadingContractTest {
 
     @ParameterizedTest
     @EnumSource(ParserCase.class)
-    // Public JFR APIs observe process and class loading on the supported JDKs 
(17, 21, and 25).
+    // Public JFR APIs observe process and class loading on the supported JDKs 
(21 and 25).
     @SuppressForbidden
     void parsingDoesNotRunProjectActionsOrResolveRuntimeValues(ParserCase 
parserCase) throws Exception {
         Path project = Files.createDirectory(tempDir.resolve("project"));
diff --git a/kit/camel-kit-main/dist/CamelKit.java 
b/kit/camel-kit-main/dist/CamelKit.java
index da992ca8..8e369f0a 100755
--- a/kit/camel-kit-main/dist/CamelKit.java
+++ b/kit/camel-kit-main/dist/CamelKit.java
@@ -1,6 +1,6 @@
 ///usr/bin/env jbang "$0" "$@" ; exit $?
 
-//JAVA 17+
+//JAVA 21+
 
 //REPOS 
central=https://repo1.maven.org/maven2/,apache_snap=https://repository.apache.org/snapshots
 //REPOS central_snap=https://central.sonatype.com/repository/maven-snapshots/
diff --git a/kit/camel-kit-main/src/main/jbang/main/CamelKit.java 
b/kit/camel-kit-main/src/main/jbang/main/CamelKit.java
index da992ca8..8e369f0a 100644
--- a/kit/camel-kit-main/src/main/jbang/main/CamelKit.java
+++ b/kit/camel-kit-main/src/main/jbang/main/CamelKit.java
@@ -1,6 +1,6 @@
 ///usr/bin/env jbang "$0" "$@" ; exit $?
 
-//JAVA 17+
+//JAVA 21+
 
 //REPOS 
central=https://repo1.maven.org/maven2/,apache_snap=https://repository.apache.org/snapshots
 //REPOS central_snap=https://central.sonatype.com/repository/maven-snapshots/
diff --git a/knowledge/README.md b/knowledge/README.md
index 201542ac..7c3699e5 100644
--- a/knowledge/README.md
+++ b/knowledge/README.md
@@ -20,7 +20,7 @@ its original download URL and does not support the new 
release-discovery or pinn
 
 ## Prerequisites
 
-- Java 17+
+- Java 21+
 - Use the Maven wrapper at the repository root. All commands below run from 
that root.
 
 No Docker. No Docling. No external tokens.
diff --git a/pom.xml b/pom.xml
index d770ce10..95f378e0 100644
--- a/pom.xml
+++ b/pom.xml
@@ -21,7 +21,7 @@
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
-        <jdk.version>17</jdk.version>
+        <jdk.version>21</jdk.version>
         <maven.compiler.source>${jdk.version}</maven.compiler.source>
         <maven.compiler.target>${jdk.version}</maven.compiler.target>
         <maven.compiler.release>${jdk.version}</maven.compiler.release>
diff --git a/tools/release_target.py b/tools/release_target.py
index fac1cd5f..5d9292ba 100644
--- a/tools/release_target.py
+++ b/tools/release_target.py
@@ -7,6 +7,8 @@ import urllib.request
 from pathlib import Path
 import xml.etree.ElementTree as ET
 
+from sync_distribution_mirrors import load_properties
+
 NS = "{http://maven.apache.org/POM/4.0.0}";
 TARGETS = {
     "parent": ("pom.xml", "camel-kit-parent", ["-N"]),
@@ -44,6 +46,13 @@ def validate(root, target, tag=None, snapshot=False):
                     or child.findtext(f"{NS}parent/{NS}version") != version
                     or child.findtext(NS + "version", version) != version):
                 raise ValueError(f"{child_path}: module and product versions 
must match {version}")
+    if target == "kit" and not snapshot:
+        host = load_properties(root / 
"distribution.properties").get("camel.cli.version", "")
+        if (not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", host)
+                or tuple(map(int, host.split("."))) < (4, 24, 0)):
+            raise ValueError(f"A released Camel CLI host 4.24.0 or newer is 
required, got {host!r}")
+        if pom.findtext(f"{NS}properties/{NS}camel.cli.version") != host:
+            raise ValueError("Synchronize the Camel CLI host version in 
kit/pom.xml before releasing")
     return version, list(arguments)
 
 
diff --git a/tools/test_release_target.py b/tools/test_release_target.py
index 265a5fab..15feef61 100644
--- a/tools/test_release_target.py
+++ b/tools/test_release_target.py
@@ -13,6 +13,7 @@ class ReleaseTargetTest(unittest.TestCase):
         self.tmp = tempfile.TemporaryDirectory()
         self.addCleanup(self.tmp.cleanup)
         self.root = Path(self.tmp.name)
+        (self.root / 
"distribution.properties").write_text("camel.cli.version=4.24.0\n")
         self.pom("pom.xml", "camel-kit-parent", "1.0.0", modules=["kit", 
"knowledge"])
         self.pom("kit/pom.xml", "camel-kit", "0.4.2", "camel-kit-parent", 
"1.0.0", ["core"])
         self.pom("kit/core/pom.xml", "camel-kit-core", None, "camel-kit", 
"0.4.2")
@@ -27,6 +28,8 @@ class ReleaseTargetTest(unittest.TestCase):
         if version:
             content += f"<version>{version}</version>"
             content += f"<scm><tag>{artifact}-{version}</tag></scm>"
+        if artifact == "camel-kit":
+            content += 
"<properties><camel.cli.version>4.24.0</camel.cli.version></properties>"
         content += "<modules>" + "".join(f"<module>{m}</module>" for m in 
modules) + "</modules></project>"
         destination = self.root / path
         destination.parent.mkdir(parents=True, exist_ok=True)
@@ -38,6 +41,34 @@ class ReleaseTargetTest(unittest.TestCase):
     def test_parent_cannot_recurse_into_products(self):
         self.assertEqual(("1.0.0", ["-N"]), validate(self.root, "parent", 
"camel-kit-parent-1.0.0"))
 
+    def test_kit_release_requires_a_released_camel_host(self):
+        for version in ["4.24.0-SNAPSHOT", "4.24.0-20261117.143648-37", 
"4.24.0-RC1", ""]:
+            with self.subTest(version=version):
+                (self.root / 
"distribution.properties").write_text(f"camel.cli.version={version}\n")
+                with self.assertRaisesRegex(ValueError, "released Camel CLI 
host"):
+                    validate(self.root, "kit", "camel-kit-0.4.2")
+
+    def test_host_snapshot_is_allowed_for_development_and_other_products(self):
+        (self.root / 
"distribution.properties").write_text("camel.cli.version=4.24.0-SNAPSHOT\n")
+        self.pom("kit/pom.xml", "camel-kit", "0.4.2-SNAPSHOT", 
"camel-kit-parent", "1.0.0", ["core"])
+        self.pom("kit/core/pom.xml", "camel-kit-core", None, "camel-kit", 
"0.4.2-SNAPSHOT")
+        self.assertEqual("0.4.2-SNAPSHOT", validate(self.root, "kit", 
snapshot=True)[0])
+        self.assertEqual("1.0.0", validate(self.root, "parent")[0])
+        self.assertEqual("0.0.3-SNAPSHOT", validate(self.root, "knowledge", 
snapshot=True)[0])
+
+    def test_kit_release_rejects_an_older_picocli_host(self):
+        (self.root / 
"distribution.properties").write_text("camel.cli.version=4.22.1\n")
+        pom = self.root / "kit/pom.xml"
+        pom.write_text(pom.read_text().replace("4.24.0", "4.22.1"))
+        with self.assertRaisesRegex(ValueError, "released Camel CLI host"):
+            validate(self.root, "kit")
+
+    def test_kit_release_rejects_a_stale_host_mirror(self):
+        pom = self.root / "kit/pom.xml"
+        pom.write_text(pom.read_text().replace("4.24.0", "4.24.0-SNAPSHOT"))
+        with self.assertRaisesRegex(ValueError, "Synchronize the Camel CLI 
host"):
+            validate(self.root, "kit")
+
     def test_knowledge_snapshot_has_its_own_scope(self):
         self.assertEqual(("0.0.3-SNAPSHOT", ["-f", "knowledge/pom.xml"]), 
validate(self.root, "knowledge", snapshot=True))
         with self.assertRaises(ValueError):
@@ -67,6 +98,7 @@ class ReleaseTargetTest(unittest.TestCase):
         repository = Path(__file__).resolve().parent.parent
         (self.root / "tools").mkdir()
         shutil.copy(repository / "tools/release_target.py", self.root / 
"tools/release_target.py")
+        shutil.copy(repository / "tools/sync_distribution_mirrors.py", 
self.root / "tools/sync_distribution_mirrors.py")
         wrapper = self.root / "mvnw"
         wrapper.write_text('#!/usr/bin/env bash\nprintf "%s\\n" "$@"\n')
         wrapper.chmod(0o755)

Reply via email to