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
The following commit(s) were added to refs/heads/main by this push:
new 5a28f0c5 docs: write the Architecture pages for camel.apache.org
5a28f0c5 is described below
commit 5a28f0c545463e4ef43be81adb9b2532ea2afbb2
Author: Luigi De Masi <[email protected]>
AuthorDate: Fri Oct 23 12:15:10 2026 +0200
docs: write the Architecture pages for camel.apache.org
Replace the seven Architecture stubs of the Antora component with the
rewritten content: the architecture overview, the skills system, the MCP
servers (merging the former MCP integration and Camel MCP pages), the
Knowledge MCP server, graph intelligence, environment-in-the-loop and the
Forage configuration catalog. The graph page carries the graph visualization
image under docs/modules/ROOT/images/. The text is rewritten from the
standalone website and the repository documentation into the Camel
documentation register, and every claim was checked against
docs/architecture.md, docs/agent-architectures.md, docs/commands.md, the
shared guides (forage.md, mcp-setup.md, graph-availability.md), the workflow
manifest, the graph and generator sources, distribution.properties, the
camel-kit-knowledge repository at its 0.0.2 tag (tool names, index manifest,
models, bundled catalog) and, for the named-bean overrides, the published
Forage 1.6.1 sources.
docs/antora.yml gains camel-quarkus-version, quarkus-platform-version,
forage-version and citrus-version attributes, kept in step with
distribution.properties, so the pages carry no hardcoded versions.
Two corrections touch pages merged earlier: wildcard literals such as
`*.yaml` or `/camel-*` inside backticks were being paired into bold by the
AsciiDoc quotes substitution and lost their asterisks in the rendered HTML,
so every such span is now a passthrough (`+...+`); and the verification page
now says that Qwen Code and OpenCode keep the runtime verification in their
primary executor, as their traits require.
Built locally with Antora 3.2 and the Camel website UI bundle at log failure
level warn: 27 pages, no warnings, no absolute camel.apache.org links and no
broken code spans in the generated HTML.
---
docs/antora.yml | 4 +
docs/modules/ROOT/images/graph-visualize.png | Bin 0 -> 166512 bytes
docs/modules/ROOT/pages/agents.adoc | 6 +-
docs/modules/ROOT/pages/architecture.adoc | 134 +++++++++++++++-
docs/modules/ROOT/pages/camel-execute.adoc | 2 +-
docs/modules/ROOT/pages/camel-validate.adoc | 2 +-
docs/modules/ROOT/pages/eitl.adoc | 103 +++++++++++-
docs/modules/ROOT/pages/forage.adoc | 175 ++++++++++++++++++++-
docs/modules/ROOT/pages/graph.adoc | 144 ++++++++++++++++-
docs/modules/ROOT/pages/greenfield.adoc | 2 +-
docs/modules/ROOT/pages/index.adoc | 2 +-
docs/modules/ROOT/pages/knowledge.adoc | 144 ++++++++++++++++-
docs/modules/ROOT/pages/mcp.adoc | 163 ++++++++++++++++++-
.../ROOT/pages/migration-camel-upgrade.adoc | 6 +-
docs/modules/ROOT/pages/migration-mulesoft.adoc | 2 +-
docs/modules/ROOT/pages/pipeline.adoc | 2 +-
docs/modules/ROOT/pages/skills.adoc | 150 +++++++++++++++++-
docs/modules/ROOT/pages/verification.adoc | 5 +-
18 files changed, 1025 insertions(+), 21 deletions(-)
diff --git a/docs/antora.yml b/docs/antora.yml
index f1501b29..70b6e3cd 100644
--- a/docs/antora.yml
+++ b/docs/antora.yml
@@ -29,6 +29,10 @@ asciidoc:
camel-kit-snapshot-version: 0.4.2-SNAPSHOT
camel-kit-knowledge-version: 0.0.2
camel-version: 4.22.1
+ camel-quarkus-version: 4.18.3
+ quarkus-platform-version: 3.33.3.2
+ forage-version: 1.6.1
+ citrus-version: 5.0.1
pi-version: 0.84.2
pi-previous-version: 0.83.0
node-version: 22.22.2
diff --git a/docs/modules/ROOT/images/graph-visualize.png
b/docs/modules/ROOT/images/graph-visualize.png
new file mode 100644
index 00000000..1bda152f
Binary files /dev/null and b/docs/modules/ROOT/images/graph-visualize.png differ
diff --git a/docs/modules/ROOT/pages/agents.adoc
b/docs/modules/ROOT/pages/agents.adoc
index 565ac232..694f1485 100644
--- a/docs/modules/ROOT/pages/agents.adoc
+++ b/docs/modules/ROOT/pages/agents.adoc
@@ -51,9 +51,9 @@ skills: `camel-start`, `camel-brainstorm`, `camel-migrate`,
`camel-plan`, `camel
$camel-migrate MuleSoft flows in src/main/mule
----
-Bob Shell's native skill picker uses `$camel-*`; its `/` picker holds built-in
commands and MCP prompts, so a
-`/camel-*` name in this documentation corresponds to a `$camel-*` skill there.
Bob IDE exposes the same skills as
-`/camel-*`. Legacy command stubs stay installed for compatibility. The four
internal helper skills are hidden.
+Bob Shell's native skill picker uses `+$camel-*+`; its `/` picker holds
built-in commands and MCP prompts, so a
+`+/camel-*+` name in this documentation corresponds to a `+$camel-*+` skill
there. Bob IDE exposes the same skills as
+`+/camel-*+`. Legacy command stubs stay installed for compatibility. The four
internal helper skills are hidden.
If a public skill does not appear in the picker, run `camel-kit doctor`: it
reports each affected `SKILL.md` as
`FAIL` with regeneration instructions. Regenerate from the project root with
diff --git a/docs/modules/ROOT/pages/architecture.adoc
b/docs/modules/ROOT/pages/architecture.adoc
index 51bd3a8d..4666242a 100644
--- a/docs/modules/ROOT/pages/architecture.adoc
+++ b/docs/modules/ROOT/pages/architecture.adoc
@@ -1,3 +1,135 @@
= Architecture overview
-This page is written in a following documentation pull request.
+Camel Kit combines two mechanisms to give coding agents accurate and
economical access to the Apache Camel ecosystem.
+*Skills* are Markdown instruction files that carry the process knowledge: how
to design a flow, how to generate YAML,
+how to validate a route. *MCP servers* carry the data knowledge: which
components exist for a Camel version, which
+options they accept, whether an endpoint or a Citrus test action is valid.
Around them sit a generated instruction
+file per agent and an optional code intelligence layer.
+
+The workflow contract lives in
`camel-kit-core/src/main/resources/workflow/camel-kit-workflow.yaml`. It
defines the
+command names and aliases, the generated command stubs, skill visibility,
pipeline stages, artifacts, transitions, MCP
+servers and their allowed tools. The generators read it for command stubs and
tool filters, and tests check the skill
+front matter against it.
+
+[[layers]]
+== Four layers
+
+[cols="1,3,2"]
+|===
+| Layer | What it holds | Where
+
+| 1. Agent instructions
+| The cross-agent equalization layer: a routing table from user intent to the
right command, the six Iron Laws, and
+ the MCP setup
+| `AGENTS.md`, or the agent's own entry file (`CLAUDE.md`, `QWEN.md`,
`.github/copilot-instructions.md`)
+
+| 2. Skills
+| Thirteen skills in four tiers (entry, pipeline, utilities, internal) plus
the shared guides: structured prompts
+ with step-by-step procedures, tool calls, conditions and guide imports,
loaded progressively
+| `camel-kit-core/src/main/resources/skills/`, copied into the agent's skills
directory by `init`
+
+| 3. MCP servers
+| Three local servers queried on demand: the Camel catalog server for
verification and validation, the Knowledge
+ server for documentation search, the Citrus server for test guidance
+| The agent's MCP configuration file, generated by `init`
+
+| 4. Graph CLI (optional)
+| A property graph of the project built by nine parsers and two
post-processors, with fifteen subcommands; every
+ skill works without it
+| `camel-kit graph`, `.camel-kit/project-graph.json`
+|===
+
+See xref:skills.adoc[], xref:mcp.adoc[], xref:knowledge.adoc[],
xref:graph.adoc[] and xref:forage.adoc[] for each
+layer.
+
+[[prompt-is-the-product]]
+== The prompt is the product
+
+In the agent-run workflow the generated instructions own the integration
behaviour. The compiled CLI supplies
+initialization and configuration (`init`), the workspace check (`doctor`),
pipeline document staleness (`doc`),
+pipeline IDs (`nextId`), wave analysis (`plan analyze`) and the graph; it
supports the prompt-owned workflow rather than replacing
+it. This makes the behaviour portable across the eight supported agents,
readable (the instructions an agent follows
+are plain files in the project), customizable by editing Markdown, and
version-configurable through the distribution
+pins and live catalog queries.
+
+The deliberate exception is Ship, a Technology Preview: `/camel-ship` is a
short delegate to the registered
+`camel-kit ship` command, and the workflow controller (stages, run state,
oversight, evidence, guarded publication) is
+compiled code. Eligible hosts relay controller-issued tasks to read-only
native subagents and submit the results; the
+controller keeps the candidate writes, the validation and the publication. See
xref:ship.adoc[].
+
+[[progressive-disclosure]]
+== Progressive disclosure and context isolation
+
+Skills load in three levels: the routing surface of `camel-start` is always
present; a skill's `SKILL.md` is loaded
+when the skill is invoked; its guides are loaded only when the instructions
reference them. Catalog data is never
+loaded wholesale: the agent queries the MCP servers for the artifacts a design
actually uses. Together these keep the
+context small enough for constrained models and keep every component
verifiable.
+
+Where the agent supports subagents, research, implementation and review run in
isolated contexts and only
+structured summaries flow back to the orchestrator: the catalog researcher
verifies a wave's artifacts and returns a
+short summary, and reviewers return reports rather than their traces. Runtime
verification is isolated on the same
+terms where the agent's trait allows it; Qwen Code and OpenCode keep it in
their primary executor by design, so its
+build output stays in that session. Single-conversation agents run every role
inline and record the missing
+isolation.
+
+[[orchestration]]
+== The orchestration model
+
+----
+brainstorm or migrate -> approved design (package)
+ plan -> implementation plan
+ execute -> artifacts, execution report with verification
evidence
+ validate -> validation report
+----
+
+The approved design is the only user gate of a chained run; planning,
execution and validation follow automatically.
+For a migration the same gate covers the complete package, runbook included,
without authorizing any of the runbook's
+operational actions. Execute starts with an environment probe and can enter a
bounded re-plan loop (at most three
+rounds) that modifies only the affected flow sections of the design. Both
entries produce the same design
+specification contract, so plan and execute work identically afterwards; the
plan never consumes the migration
+runbook. See xref:pipeline.adoc[] and xref:eitl.adoc[].
+
+Three concerns are kept apart in the shipped assets: a *skill* is a workflow
with steps and exit criteria, a
+*persona* is a role with a perspective, an output format and composition rules
(integration architect, catalog
+researcher, code quality reviewer, and so on), and a *command* is the
user-facing entry point. Personas never invoke
+other personas; composition is the job of skills or of the user, and the
dispatch depth is one.
+
+[[equalization]]
+== One skill set, eight agents
+
+All targets use the same skills, Iron Laws, constitution rules, MCP tool calls
and output formats. What differs is
+handled by templates and traits: the dispatch mechanism (subagents, modes or
inline execution), the tool restriction
+model, the file reading patterns, the parallelization strategy and the
configuration format. `init` reads the agent's
+descriptor from the capability registry
(`camel-kit-core/src/main/resources/agents/registry/`), copies the skills,
+renders the dispatch block and the MCP configuration, and appends the agent's
traits: instruction fragments under
+`templates/traits/<agent>/` that `TraitApplicator` adds to the generated skill
files between idempotent comment
+sentinels, so re-running `init` never duplicates them. Each persona is
installed as a complete role file in the
+agent's persona directory. See xref:agents.adoc[] for what each target gets.
+
+Skills, generated instruction files, MCP configuration templates and the
active documents are tested as contract
+surfaces: `ResourceConsistencyTest` fails the build on stale command names,
configuration files, graph access patterns,
+Knowledge tool names or Iron Law counts, and `ShippedAssetStructureTest`
checks that every manifest skill, guide
+reference, trait, dispatch template and generated MCP configuration resolves.
+
+[[decisions]]
+== Design decisions worth knowing
+
+DataMapper consistency::
+XSLT generation used to vary between runs because the model re-derived XPaths
from the same schema each time. The
+canonicalize stage now pre-computes the source XPaths and target elements
once, at design time, and the
+implementation uses them verbatim. For model-generated code, an exact template
per case beats one template with
+conditional rules.
+
+Version alignment::
+`distribution.properties` ships the defaults, `init` persists the selected
runtime and versions in
+`.camel-kit/config.properties`, and every catalog call is bound to those
values. Users override with `-p` flags or a
+`-c` file.
+
+Constitution and Iron Laws::
+The constitution's eight rules say what makes a good route; the six Iron Laws
say when and how the pipeline enforces
+quality. Iron Law 2 incorporates the constitution; the two are complementary,
not overlapping. See
+xref:constitution.adoc[] and xref:pipeline.adoc#iron-laws[Iron Laws].
+
+Graph queries in the CLI, not in MCP::
+Graph analysis moved out of an MCP server into `camel-kit graph` because a
local process call is faster than a
+round-trip, and a generated project then needs only the three MCP servers.
diff --git a/docs/modules/ROOT/pages/camel-execute.adoc
b/docs/modules/ROOT/pages/camel-execute.adoc
index 90995f4f..e892f9a9 100644
--- a/docs/modules/ROOT/pages/camel-execute.adoc
+++ b/docs/modules/ROOT/pages/camel-execute.adoc
@@ -115,7 +115,7 @@ module; omit it for a single-module project.
| Artifact | Camel Main | Spring Boot and Quarkus
| Routes, and XSLT files when DataMapper selects XSLT |
`<module>/<name>.camel.yaml`,
- `<module>/kaoto-datamapper-*.xsl` | `<module>/src/main/resources/camel/`
+ `+<module>/kaoto-datamapper-*.xsl+` | `<module>/src/main/resources/camel/`
| Application properties | `<module>/application.properties` |
`<module>/src/main/resources/application.properties`
| Schemas, when requested | `<module>/schemas/` |
`<module>/src/main/resources/schemas/`
| Citrus tests and test support | `<module>/src/test/resources/`:
`<flow>.camel.it.yaml`, `test-data/`,
diff --git a/docs/modules/ROOT/pages/camel-validate.adoc
b/docs/modules/ROOT/pages/camel-validate.adoc
index a9c22d71..ef334001 100644
--- a/docs/modules/ROOT/pages/camel-validate.adoc
+++ b/docs/modules/ROOT/pages/camel-validate.adoc
@@ -27,7 +27,7 @@ current project.
== Checks
The skill first builds the route inventory of every target module for the
project's runtime (module-root
-`*.camel.yaml` and `application.properties` for Camel Main,
`src/main/resources/camel/` and
+`+*.camel.yaml+` and `application.properties` for Camel Main,
`src/main/resources/camel/` and
`src/main/resources/application.properties` for Spring Boot and Quarkus), then
runs:
* Camel YAML DSL schema validation and endpoint configuration;
diff --git a/docs/modules/ROOT/pages/eitl.adoc
b/docs/modules/ROOT/pages/eitl.adoc
index 13383c95..435e65c8 100644
--- a/docs/modules/ROOT/pages/eitl.adoc
+++ b/docs/modules/ROOT/pages/eitl.adoc
@@ -1,3 +1,104 @@
= Environment-in-the-loop
-This page is written in a following documentation pull request.
+Code generation tools usually follow a straight line: analyze the sources,
generate the target code, hope it works.
+When it does not (a dependency that does not resolve, a service that does not
start, a component that does not exist
+for the target runtime), the developer is left alone with the problem. Camel
Kit makes the execution environment a
+participant in the pipeline instead: it checks the environment before any code
is generated, exercises the generated
+application afterwards, and feeds what it learns back into the code and, when
needed, into the design. The approach
+follows the environment-in-the-loop paradigm described by Li and others in
+https://arxiv.org/abs/2602.09944[ReCode 2026]: without automated environment
interaction, the automation of code
+migration is only half complete.
+
+A linear approach has three problems: failures are discovered late, after most
of the code exists; nothing recovers
+automatically when the environment rejects the code; and tests are generated
but never refined against the real
+behaviour. The three mechanisms below address them inside `/camel-execute`.
+
+[[probe]]
+== Before any code: the environment probe
+
+The first step of execution generates a throwaway skeleton in a temporary
directory, with a `pom.xml` holding all
+planned dependencies for Spring Boot and Quarkus (Camel Main records them in
`application.properties` instead), a
+`docker-compose.yaml` only when the design needs external services, and an
empty route with the runtime
+configuration, then runs the applicable checks:
+
+[cols="1,2,1"]
+|===
+| Check | What it validates | Outcome
+
+| Dependency resolution | The Maven artifacts exist and resolve, for Spring
Boot and Quarkus | PASS or FAIL; skipped
+ for Camel Main
+| Docker services | The required databases, brokers and similar services start
| PASS, `PASS (no services
+ required)`, FAIL naming the service, or SKIPPED when services are required
and Docker is unavailable
+| Runtime startup | The framework itself boots with the runtime's start
command | PASS or FAIL
+|===
+
+A failure is classified. A mechanical one (wrong artifact name, port conflict,
missing transitive dependency, wrong
+image tag, incorrect property key) is fixed and only the failed check runs
again. An architectural one (a component that does
+not exist for the runtime or was removed in the target version, an
irreconcilable dependency conflict, a private
+image, an incompatible component combination) triggers the re-plan loop. The
skeleton is deleted afterwards; the
+real implementation generates the project files.
+
+[[verify]]
+== After the code: the verification loop
+
+Once all tasks are implemented, the internal `camel-verify` skill builds or
starts the application, runs the Citrus
+tests with `camel test run`, and reports. The Camel integration is launched
inside each test, Testcontainers start
+the required databases or brokers when a test declares them and Docker is
available, and external APIs are mocked.
+Build and test failures are classified and routed:
+
+[cols="1,2"]
+|===
+| Fix target | When
+
+| Self-repair | A missing dependency, a version conflict, a Docker or service
configuration problem
+| `camel-implement` | A route logic error: the affected flow is regenerated
from the design
+| `camel-validate`, then `camel-implement` | Wrong component options:
diagnosed against the catalog, then corrected
+| `camel-test` | A wrong test: regenerated from the design
+| Re-plan | A persistent architectural failure: the design is modified and the
affected tasks re-implemented
+| Escalate | A build tool error, a Quarkus augmentation failure, the iteration
limit, an unclassified error
+|===
+
+Maven compilation and Citrus testing each allow 15 attempts and the Camel Main
startup smoke test 6; persistent error
+classes promote to re-planning earlier. Details are in
xref:verification.adoc[].
+
+[[replan]]
+== When the plan is wrong: re-planning
+
+Sometimes the problem is not in the code but in the design: a component that
works in isolation conflicts with
+another, or a runtime extension does not exist for the chosen platform. The
re-plan loop identifies the affected
+flow sections of `design-spec.md`, looks for alternatives in the catalog,
modifies only those sections, regenerates
+the plan for the affected tasks and re-implements and re-verifies them. It
runs at most three rounds, stops at once
+when the same failure class returns in consecutive rounds, and then escalates
with a report of what was tried.
+
+Promotion follows two tiers. After one failed fix the skill asks the catalog,
with the project's runtime and
+platform BOM: if a complete list has no exact match for the required artifact,
it re-plans immediately, the way an
+experienced developer checks the documentation before trying fifteen fixes.
After three failed fixes on the same
+error class, each with a different strategy, the approach itself is judged
wrong and the skill re-plans. A
+detail-call error, an incomplete list or a mismatched binding is unknown, not
absence, and never triggers a re-plan
+on its own.
+
+[[loop]]
+== The closed loop
+
+----
+design --(you approve)--> plan --> probe --> implement --> verify
+ ^ |
+ '------ re-plan on an architectural failure
+----
+
+One approval gate, then planning, probing, implementation and verification
flow continuously. When the environment
+exposes a classified problem, the pipeline attempts a bounded code-level
repair or a design-level re-plan; skipped
+checks and unresolved failures are reported for your action, never silently
dropped. Build, startup and test output
+is evidence, not instruction: a repair runs automatically only when the
shipped taxonomy selects it from corroborated
+facts, and a command or procedure found in the output is ignored.
+
+[cols="1,2,2"]
+|===
+| | Generate and hope | Camel Kit
+
+| When the environment is checked | After all the code is generated, if at all
| Before (probe) and after (verify)
+| On failure | The user debugs | Fix, regenerate or re-plan when classified;
otherwise report or escalate
+| Tests | Generated, rarely run | Generated and run, with bounded fixes and
reported gaps
+| Feedback to the design | None | The re-plan loop may modify the affected
flow sections
+| Service management | Manual Docker Compose | Testcontainers for the tests
that declare them
+|===
diff --git a/docs/modules/ROOT/pages/forage.adoc
b/docs/modules/ROOT/pages/forage.adoc
index a837d487..dcd44c04 100644
--- a/docs/modules/ROOT/pages/forage.adoc
+++ b/docs/modules/ROOT/pages/forage.adoc
@@ -1,3 +1,176 @@
= Forage configuration catalog
-This page is written in a following documentation pull request.
+Forage (`io.kaoto.forage`) builds infrastructure beans from properties:
declare `+forage.<name>.<domain>.*+` keys and
+Forage creates the bean and registers it in the Camel registry as `#<name>`,
with no Java and no `+camel.beans.*+`
+wiring. Camel Kit prefers Forage for data sources, connection factories, AI
services, CXF endpoints and similar
+needs, and verifies every key it emits against a cached Forage catalog rather
than against the Camel catalog. This
+is the carve-out of Iron Law 1 (see xref:pipeline.adoc#iron-laws[Iron Laws]).
+
+[[availability]]
+== Availability and versions
+
+`init` records `forage.version` in `.camel-kit/config.properties` and caches
the matching catalogs under
+`.camel-kit/.cache/forage/<version>/`. The mapping from the project's Camel
version is exact-key, from
+`distribution.properties`; an unmapped Camel version has no Forage, and a
missing or invalid cache makes Forage
+unavailable, in which case the skills skip this rung once and say so instead
of inventing configuration.
+
+[cols="2,1"]
+|===
+| Camel version | Forage version
+
+| {camel-version} (Camel Main and Spring Boot default) | {forage-version}
+| 4.22.0 | 1.6.0
+| 4.18.4 | 1.4.1
+| {camel-quarkus-version} (Camel Quarkus) | 1.4.0
+|===
+
+Forage {forage-version} declares Camel {camel-version} in its runtime metadata
and includes the InfluxDB 1 and 2
+client factories for Camel Main and Spring Boot. Camel Kit checks the selected
catalog's factory coverage and runtime
+variant before it uses a factory.
+
+[[ladder]]
+== The configuration ladder
+
+For every infrastructure need and component configuration the skills walk down
the ladder and stop at the first rung
+that works:
+
+. *Forage.* Emit catalog-verified `+forage.*+` keys and reference the bean
from routes and components as `#<name>`.
+. *Component properties.* Use `+camel.component.<scheme>.*+` scalar
properties, each verified through the catalog MCP
+ server for the project's platform BOM.
+. *Custom bean.* When neither rung can construct the required object, declare
a bean in the simplest verified
+ declarative form, with a one-line comment stating why the first two rungs do
not apply. This covers both
+ `+camel.beans.*+` and top-level YAML `beans` definitions.
+
+[[naming]]
+== Naming convention
+
+In `forage.<name>.<domain>.<property>` the `<name>` segment is the registry
name. The cached configuration catalog
+lists keys in their default-bean form, without the name segment
(`forage.jdbc.url`); for a named bean the name is
+inserted after `forage.`, so `forage.myDb.jdbc.url` configures the bean
`#myDb`. Several instances are several
+names. Domains include `jdbc`, `jms`, `rabbitmq`, `cxf` and `agent`.
+
+.PostgreSQL data source
+[source,properties]
+----
+forage.myDb.jdbc.db.kind=postgresql
+forage.myDb.jdbc.url=jdbc:postgresql://{{db.host}}:{{db.port}}/{{db.name}}
+forage.myDb.jdbc.username={{db.username}}
+forage.myDb.jdbc.password={{db.password}}
+----
+
+A route then uses `sql:...?dataSource=#myDb`. Derived beans hang off the same
data source:
+`forage.myDb.jdbc.transaction.enabled=true` registers the transaction policy
beans,
+`forage.myDb.jdbc.idempotent.repository.enabled=true` with
`...repository.table.name=myRepo` registers `#myRepo`,
+and `forage.myDb.jdbc.aggregation.repository.enabled=true` with
`...repository.name=myAgg` registers `#myAgg`.
+
+.Artemis connection factory, the preferred design for Artemis brokers
+[source,properties]
+----
+forage.myBroker.jms.kind=artemis
+forage.myBroker.jms.broker.url=tcp://{{broker.host}}:61616
+forage.myBroker.jms.username={{broker.username}}
+forage.myBroker.jms.password={{broker.password}}
+forage.myBroker.jms.pool.enabled=true
+----
+
+A route then uses `jms:queue:orders?connectionFactory=#myBroker`.
+
+Forage resolves each key from environment variables, then system properties,
then properties files, then defaults.
+Named beans have their own forms: `forage.myDb.jdbc.url` is overridden by the
`FORAGE_MYDB_JDBC_URL` variable or
+the `forage.myDb.jdbc.url` system property, with the environment taking
precedence (verified against Forage
+{forage-version}).
+
+[[custom-beans]]
+== Custom bean construction
+
+On the third rung the skills prefer, in order, constructors and writable
properties, a public static factory
+(`factoryMethod`, plus `factoryBean` when the factory is on another class,
with indexed `constructors` as the factory
+arguments), and a builder supported by the YAML DSL. Before selecting one they
verify the library's constructors,
+method signatures, argument order, type conversions and lifecycle methods for
the project's runtime, platform BOM and
+resolved library version; catalog validation of component options does not
verify third-party Java APIs. Connection
+values and credentials stay externalized and are referenced with placeholders.
+
+.A static factory bean, used only when the mapped Forage catalog lacks the
InfluxDB client
+[source,yaml]
+----
+- beans:
+ # Custom bean: the verified Forage/component configuration cannot
construct this client.
+ - name: influxDbClient
+ type: com.influxdb.client.InfluxDBClient
+ factoryBean: com.influxdb.client.InfluxDBClientFactory
+ factoryMethod: create
+ constructors:
+ 0: "{{influxdb.url}}"
+ 1: "{{influxdb.token}}"
+ 2: "{{influxdb.org}}"
+ 3: "{{influxdb.bucket}}"
+ destroyMethod: close
+----
+
+Camel converts the token to a character array; the factory class needs no
no-argument constructor. With Forage
+{forage-version} on Camel Main or Spring Boot the InfluxDB 2 factory comes
first instead.
+
+A `scriptLanguage` bean is used only when verified declarative mechanisms
cannot express the initialization, for
+example iterating discovered plugins through a registration method with no
bulk setter; the bean carries a one-line
+reason and the language dependency. A failed lookup is an unverified choice,
not proof that a script is necessary:
+the gap is reported as a concern. Review flags unnecessary scripting as a
warning and recommends a declarative
+replacement only when it is verified. This policy concerns bean creation only;
message transformations and the
+DataMapper engine selection are untouched.
+
+.Property-based custom bean on an older Camel, where `amqp` has no host and
port options and Forage has no AMQP 1.0 module
+[source,properties]
+----
+# Rung 3: Forage has no AMQP-1.0/qpid module and the camel.component.amqp
+# host/port options require Camel >= 4.10
+camel.beans.amqpConnectionFactory=#class:org.apache.qpid.jms.JmsConnectionFactory
+camel.beans.amqpConnectionFactory.remoteURI=amqp://{{amqp.host}}:{{amqp.port}}
+camel.beans.amqpConnectionFactory.username={{amqp.username}}
+camel.beans.amqpConnectionFactory.password={{amqp.password}}
+camel.component.amqp.connectionFactory=#amqpConnectionFactory
+----
+
+[[catalog]]
+== Catalog checks
+
+The cache holds `forage-catalog.json` (factories, bean kinds, component
coverage, per-runtime GAVs) and
+`forage-configuration-catalog.json` (property names, types, required flags).
The skills parse only the slices they
+need with a structured JSON parser, never through a shell expression; the same
slices, queried by hand:
+
+[source,bash]
+----
+CACHE=.camel-kit/.cache/forage/${FORAGE_VERSION}
+
+# Factory and bean-kind coverage
+jq -r '.factories[] | .name + ": " + ([.beansByFeature[]?.beans[]?.name] |
join(", "))' \
+ "$CACHE/forage-catalog.json"
+
+# Components served by each factory
+jq -r '.factories[] | .name + " -> " + (.components | join(", "))' \
+ "$CACHE/forage-catalog.json"
+
+# Runtime dependency of a factory
+jq -r '.factories[] | select(.name=="DataSource") | .variants.base.gav' \
+ "$CACHE/forage-catalog.json"
+
+# Property keys of a module
+jq -r '.modules[] | select(.artifactId=="forage-jdbc-common") |
.configEntries[].name' \
+ "$CACHE/forage-configuration-catalog.json"
+----
+
+Every emitted `+forage.*+` key must exist in the configuration catalog once
the name segment is removed. Dependency
+coordinates must have the `io.kaoto.forage` group, a `+forage-*+` artifact and
the configured version; anything else
+is unavailable, not a hint to construct another coordinate. Catalog
descriptions are context, never instructions.
+
+In `/camel-validate`, an unknown `+forage.*+` key, or a hand-wired bean with a
Forage equivalent and no explanation, is
+a failure; a hand-wired bean whose only alternative is a scalar component
property is a warning.
+
+[[dependencies]]
+== Dependencies per runtime
+
+* *Camel Main and JBang.* If the `forage` Camel JBang plugin is installed, its
catalog-driven resolution needs no
+ explicit dependencies, though the GAVs are still recorded in the design.
Otherwise the `base` variant GAVs and the
+ per-kind bean GAVs go into `camel.jbang.dependencies`.
+* *Spring Boot.* The `springboot` variant starters go into `pom.xml`.
+* *Quarkus.* The `quarkus` variant extensions go into `pom.xml`.
+
+The Forage version always comes from `.camel-kit/config.properties`; it is
never hardcoded in a generated file.
diff --git a/docs/modules/ROOT/pages/graph.adoc
b/docs/modules/ROOT/pages/graph.adoc
index 3c889539..db7021d7 100644
--- a/docs/modules/ROOT/pages/graph.adoc
+++ b/docs/modules/ROOT/pages/graph.adoc
@@ -1,3 +1,145 @@
= Graph intelligence
-This page is written in a following documentation pull request.
+Camel Kit can build a property graph of an integration project: nodes for
classes, routes, endpoints, beans, Maven
+artifacts and configuration properties, edges for inheritance, injection,
route flow, bean references and
+configuration bindings. The graph feeds migration analysis, impact analysis,
project-aware validation and
+retirement-candidate reporting. It is optional: every skill works without it,
uses it when it is available, and skips
+the graph-enhanced steps silently when the CLI is unavailable. The graph
enhances the agent; it never gates it.
+
+image::graph-visualize.png["Graph visualization of a MuleSoft project: nodes
are flows, connectors, Maven artifacts and configuration properties"]
+
+[[build]]
+== How the graph is built
+
+`camel-kit graph generate` runs nine content parsers and two post-processors
and persists the result at
+`.camel-kit/project-graph.json` (another path with `--output`; queries take
`--graph-file`). `PomParser` runs first
+and synchronously, because the other parsers need the Maven artifacts for
runtime detection and for the dependency
+allowlist; the eight others then run in parallel on parser-local fragments
that are merged in a fixed order, so the
+result does not depend on completion timing. Parser diagnostics record the
scanned files, warnings, failures,
+timeouts and produced counts.
+
+[cols="1,2,2"]
+|===
+| Parser | Purpose | Files
+
+| `PomParser` | Maven dependencies and properties, runtime detection |
`pom.xml`
+| `JavaGraphParser` | Classes, methods, fields, DI annotations, Java DSL
routes | `+*.java+`
+| `GroovyGraphParser` | Groovy scripts and classes | `+*.groovy+`
+| `XmlRouteParser` | Camel XML routes, recognized by the `route` element in
any namespace | `+*.xml+` except POM, Mule
+ and BizTalk inputs
+| `YamlRouteParser` | Camel YAML DSL routes | `+*.yaml+`, `+*.yml+` except
`+application*+`
+| `ConfigParser` | Every application property, not only the `+camel.*+` keys |
`application.properties`,
+ `+application-*.properties+`
+| `MuleXmlFlowParser` | Mule 3.x and 4.x flows, sub-flows, connectors,
endpoints, transforms, error handlers | `+*.xml+`
+ with the Mule namespace
+| `DataWeaveParser` | DataWeave version, content types, functions, field
access patterns | `+*.dwl+`
+| `BizTalkParser` | Orchestrations, maps, pipelines and bindings, through four
StAX sub-parsers | `.odx`, `.btm`,
+ `.btp`, binding `.xml`
+|===
+
+The post-processors run on the assembled graph: `CrossLinker` links producer
and consumer routes through `direct`
+and `seda` endpoints, maps component usage to Maven artifacts, binds
configuration to endpoints and creates the
+interface shortcuts described below; `PropertyBindingParser` then reads the
property values for Camel's
+`PropertyBindingSupport` syntax. Mule and BizTalk files are detected by their
namespaces and extensions, so no
+configuration is needed; `init --source-platform` only hints the platform for
unusual layouts. `camel-kit graph
+visualize` writes an interactive page to `.camel-kit/project-graph.html`.
+
+[[commands]]
+== Commands
+
+[cols="1,3"]
+|===
+| Command | Purpose
+
+2+| *Analysis*
+| `stats` | `available`, node and edge totals, nodes by type
+| `find` | Nodes by type, with a regular expression on the name or fully
qualified name, falling back to the node ID
+| `neighbors` | Incoming, outgoing or both directions, optionally filtered by
edge type and depth
+| `path` | The shortest path between two nodes
+| `subgraph` | The subgraph around a node, by breadth-first search with a
depth limit
+
+2+| *Camel-specific*
+| `route-flow` | The ordered `FROM`, `PROCESSOR` and `TO` steps of an exact
`CAMEL_ROUTE` node, or of the route
+ consuming a given endpoint with `--from-endpoint`
+| `impact` | Bounded transitive reachability, up to 50 nodes per direction;
`--direction upstream`, `downstream` or
+ `both` (the default)
+| `route-topology` | Route-to-route connections with the target route,
endpoint scheme and URI
+| `dead-code` | Structural retirement candidates: non-framework `+camel-*+`
artifacts with no component usage,
+ `direct` and `seda` consumers no route produces for, `+camel.*+` properties
that configure nothing
+
+2+| *Context*
+| `project-norms` | Route ID naming, error-handling coverage, property
prefixes and route step-count norms, including
+ the observed P75
+| `project-context` | Property conventions, existing beans, dependency
versions and the route directory
+| `route-context` | Upstream, downstream, classified endpoints and the error
flow of a route
+| `migration-context` | Bounded bidirectional context around a route for
migration, see below
+
+2+| *Output*
+| `generate` | Build or rebuild the graph from the sources
+| `visualize` | Render the interactive HTML visualization
+|===
+
+Every result is a candidate within the graph's coverage, not proof: a
`dead-code` entry means the graph found no
+path, not that the code is safe to remove. Regenerate the graph after source
changes so queries reflect the current
+project.
+
+[[di]]
+== Dependency-injection-aware analysis
+
+`JavaGraphParser` understands injection across frameworks. Every field and
constructor parameter of an allowed type
+creates a `USES_TYPE` edge, and `@Inject` or `@Autowired` marks that edge as
an injection; `@Component`, `@Service`, `@Repository`, `@Controller`, `@Named`,
`@Singleton`,
+`@ApplicationScoped` and `@RequestScoped` mark managed beans; `@Value` and
`@ConfigProperty` create `INJECTS_INTO`
+edges from configuration properties to the fields that consume them. A
POM-driven scope guard keeps the graph
+focused: `USES_TYPE` edges are created only for project-local classes, Apache
Camel types and the framework types
+(Spring, Quarkus, Mule) found in the Maven dependencies, never for JDK types.
+
+When class A injects interface I and class C implements I, `CrossLinker` adds
a `DEPENDS_ON_VIA_INTERFACE` shortcut
+from A to C, and the traversal used by `impact` and `migration-context`
crosses it. Without it, an upstream impact
+query on `OrderServiceImpl` returns nothing, because the route class only
knows the `OrderService` interface; with
+it, the query returns the consumer classes, `OrderRoute` among them. `impact`
follows incoming edges only, so the
+route's endpoints are not part of that result: `route-context` or
`migration-context` on the route shows its
+`kafka` source and `direct:payment` target.
+
+`PropertyBindingParser` turns `application.properties` into part of the graph:
`#class:` creates `INSTANTIATES`
+edges, `#bean:`, `#autowired` and `#type:` create `REFERENCES_BEAN` edges,
`#property:` creates
+`REFERENCES_PROPERTY` edges, and placeholders in endpoint URIs create
`CONFIGURES` edges to the matching properties.
+Spring Boot and Quarkus data source conventions become synthetic bean nodes,
and Quarkus build-time properties are
+marked as such. A shared `RuntimeDetector` identifies Spring Boot, Quarkus,
Camel Main or Karaf from the Maven
+dependencies; `init` persists the result in `.camel-kit/config.properties`.
+
+[[migration-context]]
+== Migration context
+
+[source,bash]
+----
+camel-kit graph migration-context <routeId> [--depth N]
+----
+
+The command performs a bidirectional, interface-aware breadth-first search
from one route (the ID without the
+`route:` prefix), with depth 3 by default and at most 50 expanded nodes, and
returns structured JSON: the reached
+`routes` with their source endpoint and file, the deduplicated `components`,
the `services` (bean class and name),
+the Maven `artifacts`, the `properties` with their outgoing edge type and
target, and `warnings` for every reached
+node that was inferred rather than parsed. `runtime` comes from the project
configuration. The result is focused
+local context, not a complete dependency map, and the command makes no MCP
call: documentation, CVE or
+compatibility lookups are separate actions through the Knowledge server, using
the reported components as input.
+See xref:migration.adoc#graph[Graph analysis] for how the migration uses it.
+
+[[background]]
+== Background
+
+The interface-consumer expansion and the bidirectional traversal follow the
deterministic knowledge base approach of
+Chinthareddy, https://arxiv.org/abs/2601.08773[Reliable Graph-RAG for
Codebases: AST-Derived Graphs vs LLM-Extracted
+Knowledge Graphs] (2026), which found deterministic AST-derived graphs both
more correct and far cheaper than
+model-extracted knowledge graphs for multi-hop questions on Java codebases.
Camel Kit departs from the paper where
+Camel projects differ from self-contained applications: it parses with
JavaParser rather than Tree-sitter, tracks
+framework types from the POM instead of project-local types only, models the
Maven dependency layer and the
+component-to-artifact mapping, and treats property-based bean wiring and
configuration-to-code links as part of the
+architecture.
+
+[[usage]]
+== Where the graph is used
+
+* `/camel-migrate` corroborates and accelerates its source analysis with the
graph when one is current.
+* `camel-implement` loads `project-context` and `camel-test` loads
`route-context` when a graph exists.
+* `/camel-validate` consumes `project-norms` and includes the `dead-code`
report.
+* `/camel-start` and `/camel-knowledge` do not use it.
diff --git a/docs/modules/ROOT/pages/greenfield.adoc
b/docs/modules/ROOT/pages/greenfield.adoc
index ed5217b8..75913a62 100644
--- a/docs/modules/ROOT/pages/greenfield.adoc
+++ b/docs/modules/ROOT/pages/greenfield.adoc
@@ -161,7 +161,7 @@ writes `execution-report.md`.
| PASS, SKIPPED or FAILED with the reason
| Test
-| Discovers `*.it.yaml` files recursively and runs `camel test run` when the
Camel test plugin is available. Tests
+| Discovers `+*.it.yaml+` files recursively and runs `camel test run` when the
Camel test plugin is available. Tests
that declare Testcontainers also need Docker; container-free and mock-only
tests run without it
| Passed-test count, or an explicit skip or failure
diff --git a/docs/modules/ROOT/pages/index.adoc
b/docs/modules/ROOT/pages/index.adoc
index 37344c7c..607980f3 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -15,7 +15,7 @@ is Camel Kit {camel-kit-version} with Knowledge MCP
{camel-kit-knowledge-version
* *AI-guided design.* Slash commands run a structured interview and produce a
versionable design specification.
* *Platform migration.* Detects the source platform and converts MuleSoft 3.x
and 4.x, Microsoft BizTalk,
Camel 2.x and 3.x, and JBoss Fuse projects to Camel 4 with YAML DSL routes.
-* *Catalog verification over MCP.* Components, endpoint options and
infrastructure `forage.*` keys are verified
+* *Catalog verification over MCP.* Components, endpoint options and
infrastructure `+forage.*+` keys are verified
against the Camel catalog and the Forage catalog at design and review time.
* *Graph intelligence.* Nine parsers and two post-processors build a
dependency-injection-aware property graph of
the codebase for analysis and migration context.
diff --git a/docs/modules/ROOT/pages/knowledge.adoc
b/docs/modules/ROOT/pages/knowledge.adoc
index a3eff503..db8583b3 100644
--- a/docs/modules/ROOT/pages/knowledge.adoc
+++ b/docs/modules/ROOT/pages/knowledge.adoc
@@ -1,3 +1,145 @@
= Knowledge MCP
-This page is written in a following documentation pull request.
+The Knowledge MCP server gives the agent release-backed access to Apache Camel
documentation, component references,
+migration guides, CVE advisories, release notes and Jira issues, from a
locally cached index rather than a live
+crawl. Knowledge MCP {camel-kit-knowledge-version} accompanies Camel Kit
{camel-kit-version}. Its index, built on
+2026-09-21, holds 20,367 documents covering the supported 4.18 and 4.22 LTS
lines, with release history from 4.18 to
+4.22; `camel_docs_index_info` reports the installed corpus.
+
+The server is developed in the
https://github.com/luigidemasi/camel-kit-knowledge[camel-kit-knowledge]
repository,
+with its own version line. `init` configures it automatically; to run it by
hand:
+
+[source,bash,subs="attributes+"]
+----
+jbang
io.github.luigidemasi:camel-kit-knowledge-mcp:{camel-kit-knowledge-version}:runner
+----
+
+It speaks stdio and opens no HTTP port by default. For HTTP on localhost add
+`-Dquarkus.http.host-enabled=true -Dquarkus.http.host=127.0.0.1
-Dquarkus.http.port=9090` before the coordinate.
+
+[[tools]]
+== Tools
+
+The server exposes seven `+camel_docs_*+` tools. The workflow manifest
allowlists five of them for the generated
+Camel Kit workflow; the other two remain available to direct MCP clients.
+
+[cols="1,2,2"]
+|===
+| Tool | Purpose | Parameters
+
+| `camel_docs_search` | Hybrid search across component references, EIPs, the
user manual, migration guides,
+ getting-started guides and release notes | `query`; optional `version`,
`max_results` (default 5, at most 25)
+| `camel_docs_component_info` | Reference documentation, examples and options
of one component; exact indexed
+ matches are reported separately from fuzzy full-text fallbacks |
`component`; optional `version`, `runtime`
+| `camel_docs_cve_search` | CVE advisories by ID, component, severity or
fixed-in version, with CVSS and CWE details
+ when NVD enrichment was available | optional `cve_id`, `component`,
`severity`, `version`, `max_results`
+| `camel_docs_release_info` | Release notes of a version with features, fixes
and Jira references | `version`;
+ optional `max_results`
+| `camel_docs_jira_lookup` | A Jira issue and the indexed release in which it
was fixed | `jira_id`
+| `camel_docs_validate_endpoint` (direct clients) | Deterministic validation
of one endpoint URI against the catalog
+ bundled in the server, Camel {camel-version} in this release; reports
unknown components or options and missing
+ required options | `uri`
+| `camel_docs_index_info` (direct clients) | Document count, covered Camel
versions, document types, embedding model
+ and search mode of the active index | none
+|===
+
+[[search]]
+== Search pipeline
+
+General searches blend Lucene BM25 keyword scoring (20 percent) with a KNN
vector search over 384-dimensional
+Granite embeddings (80 percent), then rerank the candidates with a local
cross-encoder before applying the result
+limit. Keywords keep exact identifiers such as `kafka`, `CVE-2024-22369` or
`autoOffsetReset` from being displaced by
+semantically similar results; vectors find documents whose wording differs
from the question. Component lookup uses
+exact field matching first and marks any full-text fallback as fuzzy.
+
+If the embedding model is unavailable or does not match the index, the server
disables vector retrieval and continues
+with BM25 and the reranker; if the reranker is unavailable, it returns the
retrieval order. Embedding and reranking
+run locally through ONNX Runtime; queries are not sent to an external model
API.
+
+[cols="1,2"]
+|===
+| Model | Value
+
+| Embedding | granite-embedding-small-english-r2, Q8 ONNX, 384 dimensions,
8,192-token maximum, 2,048 tokens per chunk
+ by default
+| Reranker | ms-marco-MiniLM-L-6-v2, Q8 ONNX
+| Index | Lucene 9.12.1, vectors stored as `KnnFloatVectorField`
+|===
+
+[[contents]]
+== What is indexed
+
+* Component and EIP documentation from Apache Camel, Camel Quarkus and Camel
Spring Boot, plus the structured
+ catalog metadata: URI syntax, options, producer and consumer properties,
examples.
+* The CVE advisories published with the Camel website, each with its affected
and fixed versions and severity, and
+ CVSS, vector and CWE details when the rebuild could enrich them from NVD or,
as a fallback, from the CIRCL
+ vulnerability lookup.
+* Release notes with features, fixes, breaking changes and dependency updates,
enriched with the Jira issue details.
+* Migration guides, user manual chapters and getting-started guides.
+
+[[distribution]]
+== Index distribution and cache
+
+The index is published as `knowledge-index.zip` with an `index.json` manifest
in a GitHub release of the knowledge
+repository; it is not inside the MCP Maven artifact, and normal use needs
neither a clone of that repository nor the
+indexer. The server resolves the index lazily on the first query that needs
it: an explicit `knowledge.index.path`
+is opened directly; otherwise the manifest at `knowledge.index.url` is
fetched, compared with the local cache, and
+the archive is downloaded, checked against its SHA-256 and activated under
`~/.camel-kit/knowledge-index/`; a legacy
+classpath index is the last fallback for older bundled artifacts. The
+first query can therefore take longer, and a successful MCP handshake does not
mean the index is ready: call
+`camel_docs_index_info` to trigger the initialization and check the installed
index.
+
+If a manifest check, download, checksum or activation fails, or times out
(three seconds to connect, five seconds for
+the manifest, five minutes for the archive), the server falls back to the
active cached version when one is readable;
+a first offline query needs a populated cache or a local index path. Cache
updates are serialized across threads and
+processes with file locks, activation uses atomic moves, the current and
previous versions are retained, and a
+corrupted staging directory is cleaned up on the next attempt.
+
+[cols="1,2,1"]
+|===
+| Property | Purpose | Default
+
+| `knowledge.index.path` | Use a local index directly, for development, tests
or air-gapped use | unset
+| `knowledge.index.url` | Release manifest URL, `https://` or `file://` | the
latest GitHub release manifest
+| `knowledge.index.cache-dir` | Downloaded versions and the active-version
marker | `~/.camel-kit/knowledge-index`
+|===
+
+[[rebuild]]
+== Rebuilding the index
+
+Rebuilding is a maintainer task. From a checkout of the knowledge repository:
+
+[source,bash]
+----
+./mvnw -pl index -Prebuild-index -am -B install
+----
+
+The rebuild refreshes the Camel website's release metadata and selects every
supported LTS line, adding the latest
+release line only when it is not an LTS; it then resolves the latest release
tags of those lines, renders their
+documentation, downloads the catalog metadata, parses release notes and
advisories, enriches Jira and NVD data,
+generates or reuses cached embeddings and writes the Lucene files with the
manifest skeleton. CVE enrichment needs
+no API key; requests are rate-limited and cached, and a failed lookup is
retried at a later rebuild. The reviewed
+index is committed, and the manually dispatched release workflow packages and
publishes the archive and the completed
+manifest after a retrieval-quality gate.
+
+[cols="1,3"]
+|===
+| Module | Purpose
+
+| `schema` | Lucene field definitions and the document builder
+| `embedding` | Local ONNX embedding and reranker support
+| `indexer` | Version resolution, crawling, parsing, chunking and indexing
+| `index` | The rebuilt Lucene files and the release manifest inputs
+| `mcp` | The Quarkus MCP server exposing the seven tools and resolving the
released index
+|===
+
+[[skill]]
+== The camel-knowledge skill
+
+`/camel-knowledge` is a prescriptive question-and-answer layer over the five
allowlisted tools. A standalone question
+runs in the primary session: component configuration goes to
`camel_docs_component_info`, troubleshooting and best-practice questions go to
`camel_docs_search`, and the
+answer cites its sources. When a pipeline stage needs documentation context,
the generated instructions isolate the
+lookup in a read-only research role where the agent has one (Bob 2's reviewer
preset, Antigravity's reviewer, Qwen's
+reviewer leaf, OpenCode's researcher task) and run it inline on Pi. The role
returns a concise answer with references
+instead of raw search results, and a failed lookup is reported as missing
evidence rather than replaced with invented
+documentation.
diff --git a/docs/modules/ROOT/pages/mcp.adoc b/docs/modules/ROOT/pages/mcp.adoc
index 7e7dc9f8..05738d26 100644
--- a/docs/modules/ROOT/pages/mcp.adoc
+++ b/docs/modules/ROOT/pages/mcp.adoc
@@ -1,3 +1,164 @@
= MCP servers
-This page is written in a following documentation pull request.
+Camel Kit uses the Model Context Protocol to verify Camel configuration, to
guide Citrus test generation and to
+search documentation without loading whole catalogs into the agent's context.
`init` configures three local servers
+in the agent's MCP configuration file (see xref:agents.adoc[] for the file of
each target); the agent starts each
+one with JBang when a skill first needs it, and JBang resolves the runner and
the catalog artifacts from the
+configured repositories.
+
+[cols="1,3"]
+|===
+| Server | Purpose
+
+| `camel`
+| The Apache Camel catalog: components, EIPs, data formats, languages,
Kamelets and examples; route, YAML and
+ configuration validation; diagnostics, migration and OpenAPI helpers
+
+| `camel-knowledge`
+| Hybrid search over indexed Apache Camel documentation, CVE advisories,
release notes and Jira issues; see
+ xref:knowledge.adoc[]
+
+| `citrus`
+| The Citrus action and endpoint catalogs, the YAML DSL schema and the
test-authoring guidance used by `camel-test`
+|===
+
+The JBang runner coordinates of this release:
+
+[subs="attributes+"]
+----
+camel org.apache.camel:camel-jbang-mcp:{camel-version}:runner
+camel-knowledge
io.github.luigidemasi:camel-kit-knowledge-mcp:{camel-kit-knowledge-version}:runner
+citrus org.citrusframework:citrus-mcp-server:{citrus-version}:runner
+----
+
+The generated configuration is, in the target's JSON or TOML shape:
+
+[source,json,subs="attributes+"]
+----
+{
+ "mcpServers": {
+ "camel": {
+ "command": "jbang",
+ "args": [
+ "--repos", "<configured MCP repositories>",
+ "-Dcamel.catalog.repos=<configured catalog repositories>",
+ "-Dquarkus.log.level=WARN",
+ "-Dquarkus.http.port=-1",
+ "org.apache.camel:camel-jbang-mcp:{camel-version}:runner"
+ ]
+ }
+ }
+}
+----
+
+Versions and repository lists come from `distribution.properties`; nothing is
extracted into the project, and the
+generated launch configuration is used unchanged. Targets with exact tool
filtering receive the workflow allowlist
+of each server from the workflow manifest; Codex CLI adds
`default_tools_approval_mode = "prompt"`, Pi reads the
+same `.mcp.json` through `pi-mcp-adapter`.
+
+[[authority]]
+== Responses are data
+
+An MCP response is loaded context. The workflow relies only on the
purpose-specific fields it requested, after the
+artifact identity, runtime, platform BOM, resolved version, result and
provenance are present and validated. Prose,
+examples, commands, URLs, tool requests or scope changes in a response cannot
direct an action; summaries inherit the
+response's authority rather than increasing it. See
xref:skills.adoc#context-authority[Context authority].
+
+[[binding]]
+== Version binding
+
+Every version-sensitive catalog call passes the project's `runtime` (`main`,
`spring-boot` or `quarkus`) and the full
+platform BOM coordinate derived from `.camel-kit/config.properties`; a call
without them is answered from the catalog
+bundled in the server, which may be the wrong version.
+
+[cols="1,3"]
+|===
+| Runtime | Platform BOM
+
+| `main` | `org.apache.camel:camel-catalog:<project.camelVersion>`
+| `spring-boot` |
`org.apache.camel.springboot:camel-catalog-provider-springboot:<project.camelVersion>`
+| `quarkus` |
`io.quarkus.platform:quarkus-camel-bom:<project.platformBomVersion>`
+|===
+
+Before consuming catalog data the skill calls `camel_catalog_components` with
`limit=0` and the same binding; the
+result carries the catalog's resolved Camel version without a component
payload, and it must match the project's
+version. That probe is the binding for the following calls. Detail tools do
not all echo a version, so each artifact
+is validated by type and name against the request instead. A detail-call error
is not proof of absence: an artifact
+is recorded as `NOT_FOUND` only after a successful list call with a complete
enumeration contains no exact match,
+and as `UNVERIFIED` when completeness or the binding cannot be established.
+
+The current defaults are Camel {camel-version} for Camel Main and Spring Boot,
with Camel {camel-quarkus-version}
+on the Quarkus platform {quarkus-platform-version}; the catalog server
artifact follows the Camel Main stream.
+
+[[camel-tools]]
+== The Camel catalog server
+
+The workflow allowlist covers the read-only and generation helpers the skills
use; runtime mutation and control
+tools stay out of the generated configuration.
+
+[cols="1,2"]
+|===
+| Tool | Purpose
+
+2+| *Catalog exploration*
+| `camel_catalog_components`, `camel_catalog_component_doc`,
`camel_catalog_component_maven` | List, document and
+ locate the Maven coordinates of components
+| `camel_catalog_dataformats`, `camel_catalog_dataformat_doc` | Data formats
and their options
+| `camel_catalog_languages`, `camel_catalog_language_doc` | Expression
languages
+| `camel_catalog_eips`, `camel_catalog_eip_doc` | Enterprise Integration
Patterns and their configuration
+| `camel_catalog_kamelets`, `camel_catalog_kamelet_doc` | Kamelets and their
dependencies
+| `camel_catalog_examples`, `camel_catalog_example_file` | Camel examples and
their files
+
+2+| *Validation, security and tests*
+| `camel_validate_route` | Validate one endpoint URI against the bound catalog
(the skills call it once per
+ statically extracted endpoint)
+| `camel_validate_yaml_dsl` | Validate YAML DSL syntax
+| `camel_transform_route` | Convert routes between YAML and XML
+| `camel_route_context`, `camel_route_harden_context` | Extract components and
EIPs from a route; candidate evidence
+ for route hardening
+| `camel_route_test_scaffold` | A JUnit 5 route test scaffold
+
+2+| *Diagnostics and configuration*
+| `camel_component_properties`, `camel_configuration_validate` | Component
property metadata; validation of
+ configuration properties
+| `camel_dependency_check`, `camel_error_diagnose`,
`camel_properties_translate` | Dependency checks, error
+ diagnosis, property translation between runtimes
+| `camel_version_list` | Camel versions with LTS status and JDK requirements
+
+2+| *Migration and OpenAPI*
+| `camel_migration_analyze`, `camel_migration_compatibility`,
`camel_migration_recipes`,
+ `camel_migration_guide_search`, `camel_migration_wildfly_karaf` | Migration
analysis, compatibility, recipes and
+ guidance
+| `camel_openapi_validate`, `camel_openapi_scaffold`,
`camel_openapi_mock_guidance` | OpenAPI validation,
+ scaffolding and mock guidance
+|===
+
+The design stage verifies every component, EIP, data format and language
before it enters the design, and records
+the evidence (see xref:camel-brainstorm.adoc#catalog[Catalog verification]).
During implementation the route files
+are validated with `camel_validate_route` and `camel_validate_yaml_dsl`, and
`camel_configuration_validate` is a
+mandatory gate after writing application properties: generation is not
complete until it passes or the documented
+manual fallback is recorded. `/camel-validate` uses the same tools for its
endpoint verification, and `camel-test`
+uses the route context and hardening tools for its test strategy.
+
+Without the catalog, a model writes component names from its training data,
which may be renamed, removed or
+different in the target version. With it, a request such as "a message queue"
becomes three verified candidates
+(`jms`, `amqp`, `kafka`) and a question to you, and an unknown name becomes a
clarification instead of a guess.
+
+[[citrus]]
+== The Citrus server
+
+`camel-test` validates the test vocabulary through `citrus_catalog_actions`,
`citrus_catalog_action`,
+`citrus_catalog_action_schema`, `citrus_catalog_endpoints`,
`citrus_catalog_endpoint`,
+`citrus_catalog_endpoint_schema`, `citrus_docs_index` and `citrus_docs_page`,
plus resources such as
+`citrus://schema/dsl/yaml`. The test schema and the generated test
dependencies use `citrus.version` from
+`.camel-kit/config.properties`, and the server coordinate is bound to the
actual runner artifact in the agent's
+configuration. Typed catalog and schema fields are treated as same-version
data only when that runner version equals
+`citrus.version`; otherwise the skill uses the same-version quick reference
cached under `.camel-kit/.cache/citrus/`,
+and marks a generated test as unverified rather than falling back to another
Citrus version silently.
+
+[[fallback]]
+== Fallback
+
+Skills call the tools directly without probing for availability first. If a
call fails (tool not found, network
+error, timeout), the skill falls back to the bundled guides and continues with
a warning; the pipeline degrades
+rather than stopping, and the missing verification is recorded.
diff --git a/docs/modules/ROOT/pages/migration-camel-upgrade.adoc
b/docs/modules/ROOT/pages/migration-camel-upgrade.adoc
index 86224fcc..b564d62f 100644
--- a/docs/modules/ROOT/pages/migration-camel-upgrade.adoc
+++ b/docs/modules/ROOT/pages/migration-camel-upgrade.adoc
@@ -60,7 +60,7 @@ Camel version and runtime, and a component that is not listed
is checked there t
| `swagger-java` | `openapi-java` |
| `ibatis`, `mqtt` | `mybatis`, `paho` |
| `direct-vm`, `vm` | `direct`, `seda` | Cross-context variants removed in 4.0
-| `aws-*` | `aws2-*` | AWS SDK v2; `aws-swf` was removed, use
`aws2-step-functions`
+| `+aws-*+` | `+aws2-*+` | AWS SDK v2; `aws-swf` was removed, use
`aws2-step-functions`
| `dozer` | Removed | Extract the mapping and use DataMapper
| `hdfs2`, `hdfs` | Removed | `camel-hdfs` was removed in Camel 4.4; choose a
replacement and verify it in the catalog
| `boon`, `jibx`, `linkedin`, `ironmq`, `etcd`, `ganglia`, `spark-rest`,
`chronicle-engine`, `rx-netty` |
@@ -175,7 +175,7 @@ forage.myDataSource.jdbc.password={{db.password}}
The data source becomes a Forage-backed named bean with external connection
values. Camel Main uses the
double-brace property placeholder syntax inside `application.properties`;
Spring Boot and Quarkus use the
dollar-brace syntax. Camel Kit verifies Forage availability and the keys in
its cached catalog first; without
-Forage it continues down the configuration ladder to catalog-verified
component properties and uses `camel.beans.*`
+Forage it continues down the configuration ladder to catalog-verified
component properties and uses `+camel.beans.*+`
only as a documented last resort.
=== Deprecated component swap
@@ -233,7 +233,7 @@ them.
== After the migration
. Review the generated YAML routes and configuration.
-. Update retained Java source from `javax.*` to `jakarta.*`: Camel 4 requires
Jakarta EE 10.
+. Update retained Java source from `+javax.*+` to `+jakarta.*+`: Camel 4
requires Jakarta EE 10.
. Run the routes locally with `camel run` or the target runtime's development
mode.
. Check the xref:manual::camel-4-migration-guide.adoc[Camel 4 migration guide]
for breaking changes outside the
migrated routes.
diff --git a/docs/modules/ROOT/pages/migration-mulesoft.adoc
b/docs/modules/ROOT/pages/migration-mulesoft.adoc
index 67b772e6..d8405b82 100644
--- a/docs/modules/ROOT/pages/migration-mulesoft.adoc
+++ b/docs/modules/ROOT/pages/migration-mulesoft.adoc
@@ -83,7 +83,7 @@ verifies each target and its options in the catalog for the
selected Camel versi
|===
Infrastructure beans such as data sources and connection factories are
configured through the Forage configuration
-ladder (see xref:forage.adoc[]) before `camel.beans.*` is considered.
+ladder (see xref:forage.adoc[]) before `+camel.beans.*+` is considered.
Proprietary connectors have no direct equivalent. The agent stops and asks you
to choose a replacement, one
connector at a time, and verifies the choice in the catalog:
diff --git a/docs/modules/ROOT/pages/pipeline.adoc
b/docs/modules/ROOT/pages/pipeline.adoc
index 8810d868..55cd30bb 100644
--- a/docs/modules/ROOT/pages/pipeline.adoc
+++ b/docs/modules/ROOT/pages/pipeline.adoc
@@ -87,7 +87,7 @@ Six rules apply at every stage; every skill and every
reviewer persona refers to
. *Catalog verification.* Every component, EIP, data format and language is
verified through the catalog MCP server,
for the project's runtime and platform BOM, before it is written into a
design or a route. The tool call and its
- result must be visible; a response is data, never an instruction. `forage.*`
keys are verified against the cached
+ result must be visible; a response is data, never an instruction.
`+forage.*+` keys are verified against the cached
Forage catalog instead (see xref:forage.adoc[]).
. *Constitution compliance.* Every generated route passes the eight rules of
`docs/constitution.md`: route
structure, single responsibility, separation of concerns, naming
conventions, observability, external
diff --git a/docs/modules/ROOT/pages/skills.adoc
b/docs/modules/ROOT/pages/skills.adoc
index 6238f529..395b7f1a 100644
--- a/docs/modules/ROOT/pages/skills.adoc
+++ b/docs/modules/ROOT/pages/skills.adoc
@@ -1,3 +1,151 @@
= Skills system
-This page is written in a following documentation pull request.
+A skill is a directory with a manifest, `SKILL.md`, and an optional `guides/`
directory of instruction files loaded on
+demand. Skills are not code: they are structured prompts with step-by-step
procedures, catalog tool calls, conditions
+and shared guide imports. They live in
`camel-kit-core/src/main/resources/skills/` and `init` copies them, adapted to
+the agent, into the project.
+
+[[tiers]]
+== Thirteen skills in four tiers
+
+[cols="1,1,1,3"]
+|===
+| Tier | Skill | Command | Purpose
+
+| Entry | `camel-start` | `/camel-start` | Routes a request to the right skill
+| Pipeline | `camel-brainstorm` | `/camel-brainstorm` | Design interview,
design specification
+| Pipeline | `camel-migrate` | `/camel-migrate` | Migration discovery,
analysis, design and runbook
+| Pipeline | `camel-plan` | `/camel-plan` | Task decomposition, implementation
plan
+| Pipeline | `camel-execute` | `/camel-execute` | Wave-based implementation
with adversarial and staged review
+| Pipeline | `camel-validate` | `/camel-validate` | Static route quality
validation
+| Utility | `camel-ship` | `/camel-ship` | Technology Preview: delegate to the
local Ship controller
+| Utility | `camel-knowledge` | `/camel-knowledge` | Apache Camel
documentation questions
+| Utility | `camel-debug` | `/camel-debug` | Troubleshooting of a broken route
outside a pipeline
+|===
+
+Four internal skills are dispatched by the pipeline skills and have no command
stub: `camel-design` (component
+selection, EIP catalog, design assembly), `camel-implement` (YAML routes,
properties, Docker Compose, DataMapper),
+`camel-test` (Citrus integration tests) and `camel-verify` (build, test,
diagnose and repair at runtime). They are
+the composition primitives the stages assemble. `camel-ship` is the outlier of
its tier: its manifest is a short
+delegate that invokes the registered `camel-kit ship` command once and does
not follow the guide-based structure
+described below.
+
+[[shared-guides]]
+== Shared guides
+
+Guides under `skills/shared/` are loaded by several skills, so one guide
serves many workflows without duplication.
+
+[cols="1,2"]
+|===
+| Guide | Purpose
+
+| `iron-laws.md` | The six pipeline process rules
+| `context-authority.md` | Data versus instruction authority for every loaded
context, response and handoff
+| `camel-security-checklist.md` | Camel security rules, detection patterns and
fix snippets for design, validation and review
+| `mcp-setup.md` | MCP server configuration, version binding rules and
fallback policy
+| `forage.md` | The infrastructure configuration ladder and the Forage catalog
queries
+| `graph-availability.md` | Graph CLI detection and the "enhances, never
gates" fallback
+| `pipeline-infrastructure.md` | Pipeline IDs, state, artifact provenance and
staleness
+| `discovery-completeness.md` | Discovery and completeness semantics shared by
the interview and Ship discovery
+| `datamapper-canonicalize.md` | Engine selection from schemas and field
count; pre-computed XPaths for XSLT
+| `flow-test-data.md` | Test data generation patterns
+| `yaml-structure.md`, `yaml-components.md`, `yaml-examples.md` | YAML DSL
structure rules, component URI syntax, reference patterns
+| `patterns-foundational.md`, `patterns-error-handling.md`,
`patterns-deployment.md` | EIP, error handling and deployment patterns
+|===
+
+The vendor migration guides (MuleSoft, BizTalk and Camel 2.x/3.x phases and
mappings) live under
+`skills/camel-migrate/guides/`, not in `shared/`.
+
+[[structure]]
+== Skill structure
+
+....
+camel-brainstorm/
+ SKILL.md manifest: front matter, steps, guide table
+ guides/
+ greenfield-interview.md
+ design-assembly.md
+ version-selection.md
+ ...
+....
+
+The manifest starts with YAML front matter and declares which guides exist and
when to load them:
+
+[source,yaml]
+----
+---
+name: camel-brainstorm
+description: Design and plan Camel integrations through collaborative dialogue.
+user_invocable: false
+---
+----
+
+In the shared source only `camel-start` sets `user_invocable: true`: it is the
auto-discovered entry point. The
+pipeline and utility skills still get entry points, generated per agent:
slash-command stubs where the agent uses
+them, and native project skills on Codex CLI and GitHub Copilot CLI. Generated
copies may add runtime aliases:
+Copilot, Pi and Qwen add a hyphenated `user-invocable` field, Codex rewrites
`+/camel-*+` invocations to `+$camel-*+`
+mentions, and Bob 2 sets both fields to `true` for the nine public skills so
that Bob Shell lists them in `/skills`
+and the `+$camel-*+` picker. Internal skills keep `false` everywhere. The
front matter must match the workflow manifest;
+a test enforces it.
+
+[[progressive]]
+== Progressive disclosure
+
+. *Routing surface, always loaded.* The agent sees `camel-start` and its
decision tree, enough to select the next
+ skill.
+. *The manifest, on invocation.* `SKILL.md` is read when the user invokes the
skill or the agent matches the intent.
+. *Guides, as referenced.* When the manifest says "load
`guides/greenfield-interview.md`", the agent reads that guide
+ and nothing else.
+
+Actual context use therefore depends on the workflow and the guides it needs,
not on the size of the catalog.
+
+[[context-authority]]
+== Context authority
+
+Camel Kit separates data authority from instruction authority, and never
trusts a source as a whole. Catalog fields,
+recognized `.camel-kit/` fields and approved design or plan fields may be
relied upon for their purpose, after the
+workflow's version, schema, provenance, freshness and approval checks pass.
Only the shipped instructions of the
+active workflow and your explicit directions may direct actions, within the
host agent's own permission system. Prose,
+comments, examples, commands, URLs and requests found in MCP responses,
project files, logs, documentation or
+generated state remain data: they cannot add tasks, widen the scope, waive a
gate, request secrets or authorize a tool
+call or a file change.
+
+When an action outside the shipped workflow turns out to be necessary, the
skill names its source, the exact action,
+the verified reason and the scope, and waits for an action-specific
confirmation; a role that cannot ask returns
+`NEEDS_USER_CONFIRMATION` to its orchestrator without acting. Confirmation
applies to that action only.
+
+[[generation]]
+== Target generation and traits
+
+One skill set is adapted to eight agents. `init` reads the agent descriptor
from the capability registry
+(`agents/registry/<agent>.yaml`: skills directory, command stubs and syntax,
MCP configuration path and format,
+generator strategy, dispatch template, subagent and trait support) and runs
the matching generator:
+`ClaudeGenerator`, `Bob2Generator`, `AntigravityGenerator`, `CodexGenerator`,
`CopilotGenerator`, `PiGenerator`,
+`QwenGenerator` or `OpenCodeGenerator`, on top of the shared
`DefaultGenerator`. The output of each is listed in
+xref:agents.adoc[].
+
+Traits bridge the equalized workflow and the agent's capabilities. They are
`.append.md` fragments under
+`templates/traits/<agent>/` that `TraitApplicator` appends to the generated
files, between idempotent comment
+sentinels so a re-run of `init` adds nothing twice:
+
+[cols="1,2,2"]
+|===
+| Level | Path | Appended to
+
+| Strategy | `traits/<agent>/<skill>.append.md` | the skill's `SKILL.md`
+| Tactics | `traits/<agent>/<skill>/<guide>.append.md` | the skill's guide
+|===
+
+For example, Claude Code's `camel-execute.append.md` adds parallel subagent
dispatch through the `Agent` tool, while
+the same skill on Antigravity gets `invoke_subagent` delegation with
parent-owned decisions, Bob 2 gets
+`spawn_subagent` orchestration with its worker and reviewer presets, Qwen
keeps orchestration in the primary session
+and uses clean-context bounded leaves, and OpenCode's execute command selects
a primary executor that can dispatch
+only its allowlisted leaves. Guide-level traits are discovered from the files
on disk, so a new one needs no Java
+registration.
+
+[[adding]]
+== Adding a skill
+
+Create the directory with its manifest and guides, register the skill in the
workflow manifest, and, for a
+user-invocable skill, in the templates of all eight agents and in the command
reference. Run
+`ShippedAssetStructureTest` after any skill, template or trait change. See
xref:contributing.adoc[].
diff --git a/docs/modules/ROOT/pages/verification.adoc
b/docs/modules/ROOT/pages/verification.adoc
index fe81e34d..9cf5fac9 100644
--- a/docs/modules/ROOT/pages/verification.adoc
+++ b/docs/modules/ROOT/pages/verification.adoc
@@ -2,7 +2,8 @@
`camel-verify` is the internal skill that checks whether the generated
integration actually builds, starts and
behaves as its tests expect. `/camel-execute` dispatches it once, after all
tasks and the cross-cutting review, in an
-isolated subagent where the agent supports one and inline otherwise. It has no
command stub: for a route that breaks
+isolated subagent where the agent's trait allows one (Qwen Code and OpenCode
keep it in their primary executor) and
+inline otherwise. It has no command stub: for a route that breaks
outside a pipeline run use xref:camel-debug.adoc[`/camel-debug`].
The result is a structured report embedded in
`docs/camel-kit/<pipeline-id>/execution-report.md` and summarized
@@ -51,7 +52,7 @@ Build attempt 3: PASS
[[phase2]]
== Phase 2: tests
-The skill discovers every `*.it.yaml` file in the project, validates each one
against the configured Citrus version
+The skill discovers every `+*.it.yaml+` file in the project, validates each
one against the configured Citrus version
and the approved task and design, classifies the files that declare
Testcontainers as Docker-dependent, and runs the
runnable ones with the Camel JBang test plugin:
