CAMEL-23701: Make generated archetype projects more AI-relevant

[k-krawczyk]

Summary

Applies the same treatment as CAMEL-23702 (#24063), but to the Maven archetypes instead of the JBang export.

• Renames ReadMe.txt to README.md in all six archetypes and rewrites the content in Markdown, with the documentation links refreshed to https and to the current camel.apache.org/manual/writing-components.html location.
• Adds an AGENTS.md to every generated project: the Apache Camel LLM index (https://camel.apache.org/llms.txt), the .html -> .md documentation trick, a pointer to the Camel CLI and the Camel MCP server with an explicit "do not invent component URIs or options" instruction, plus the project layout, the build/run commands and the conventions of that archetype.
• Updates the six archetype-metadata.xml file sets accordingly — the readme is listed explicitly there, so the rename alone would have silently dropped it.
• Adds a camel-archetypes entry to the 4.22 upgrade guide.

Drive-by fix

camel-archetype-api-component declared its readme in the __artifactId__-component/ file set while the file actually lives at the project root, so no readme was generated at all. Reproduced against the released archetype:

mvn archetype:generate -DarchetypeGroupId=org.apache.camel.archetypes \
  -DarchetypeArtifactId=camel-archetype-api-component -DarchetypeVersion=4.21.0 ...

produces a project with pom.xml and the two modules, and no readme. This PR moves the entry to a root file set, so the readme is generated again.

Notes

The .md file sets are deliberately left unfiltered, as ReadMe.txt was. Markdown headings start with #, which is the Velocity directive prefix, so the generated docs are kept free of interpolation rather than risking mangled output. Consequently the content uses no ${artifactId}-style placeholders.

Verification

• ./mvnw install -Dquickly -f archetypes/pom.xml — BUILD SUCCESS.
• mvn archetype:generate run for all six archetypes against the locally installed 4.22.0-SNAPSHOT: README.md and AGENTS.md are generated at the root of every project, with no unresolved ${...} or __x__ tokens.
• The generated content was checked against the actual generated trees (MainApp / MyRouteBuilder, MyApplication / MyBean / MyConfiguration, camel-context.xml, META-INF/services/.../<scheme>, the DataFormat implementation), so it does not describe files that are not there.
• apache-rat-plugin:check on the archetypes module: 0 unapproved (**/*.md is excluded in the root POM).
• All referenced URLs return HTTP 200, including the .md variant of the manual page.

The archetype integration tests under src/test/resources/projects-disabled are disabled, so verification was done by generating projects manually as described above.

Reported by Claude Code on behalf of Karol Krawczyk

[orpiske]

I did a quick manual review and it looks good to me. Thanks @k-krawczyk !

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[davsclaus]

Nice work — this is a clean, well-structured PR that follows the pattern established by #24063 (JBang export). The camel-archetype-api-component bug fix is confirmed valid (the ReadMe.txt was declared in the __artifactId__-component/ fileSet but the file lives at the project root, so no readme was ever generated).

One required change: the upgrade guide entry needs to move to the 4.23 guide since 4.22.0 is being built and released. The camel-4x-upgrade-guide-4_23.adoc file doesn't exist yet, so it will need to be created.

Minor suggestions (non-blocking):

• The camel-archetype-spring AGENTS.md could mention that this archetype is deprecated and suggest Spring Boot instead, so AI agents don't invest effort in a deprecated project unknowingly.
• The camel-archetype-dataformat AGENTS.md reference link points to writing-components.html — inherited from the old readme and probably the closest available page, but slightly off-target for data formats.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

[davsclaus]

This entry should be in camel-4x-upgrade-guide-4_23.adoc instead — 4.22.0 is being released, so this change will ship in 4.23.

[davsclaus]

Just mind that 4.22.0 is released soon so this PR will go into 4.23. But we need to wait until main branch has been prepared for this.

[github-actions]

🧪 CI tested the following changed modules:

• archetypes/camel-archetype-api-component
• archetypes/camel-archetype-component
• archetypes/camel-archetype-dataformat
• archetypes/camel-archetype-java
• archetypes/camel-archetype-main
• archetypes/camel-archetype-spring
• docs

---

🔬 Scalpel shadow comparison — Scalpel: 7 tested, 0 compile-only — current: 6 all tested

Maveniverse Scalpel detected 7 affected modules (current approach: 6).

⚠️ Modules only in Scalpel (1)

• docs

Skip-tests mode would test 7 modules (7 direct + 0 downstream), skip tests for 0 (generated code, meta-modules)

Modules Scalpel would test (7)

• camel-archetype-api-component
• camel-archetype-component
• camel-archetype-dataformat
• camel-archetype-java
• camel-archetype-main
• camel-archetype-spring
• docs

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

All tested modules (7 modules)

• Camel :: Archetypes :: API Component
• Camel :: Archetypes :: Component
• Camel :: Archetypes :: Data Format
• Camel :: Archetypes :: Java Router
• Camel :: Archetypes :: Main
• Camel :: Archetypes :: Spring XML Based Router (deprecated)
• Camel :: Docs

---

⚙️ View full build and test results