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

archetypes/camel-archetype-api-component/src/main/resources-filtered/META-INF/maven/archetype-metadata.xml

@@ -63,11 +63,19 @@
       </includes>
     </fileSet>
 
+    <!-- project root docs -->
+    <fileSet encoding="UTF-8">
+      <directory></directory>
+      <includes>
+        <include>README.md</include>
+        <include>AGENTS.md</include>
+      </includes>
+    </fileSet>
+
     <!-- component directories -->
     <fileSet filtered="true" encoding="UTF-8">
       <directory>__artifactId__-component/</directory>
       <includes>
-        <include>ReadMe.txt</include>
         <include>pom.xml</include>
       </includes>
     </fileSet>

archetypes/camel-archetype-api-component/src/main/resources/archetype-resources/AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS.md
+
+Guidance for AI coding assistants working on this project, which was generated from the
+`camel-archetype-api-component` Maven archetype.
+
+## Start here
+
+- Apache Camel LLM index: https://camel.apache.org/llms.txt
+- Any Apache Camel documentation page is available as LLM-friendly Markdown by replacing `.html` with `.md` in its URL.
+- Prefer the Camel CLI and the Camel MCP server (both linked from the index above) to look up components, their endpoint options and the catalog. Do not invent component URIs or options — verify them against the catalog or the documentation.
+
+## Project layout
+
+This is a multi-module project:
+
+- `*-api` — the Java API that this component proxies.
+- `*-component` — the Camel component generated from that API.
+- `*-component/signatures` — the API signature files consumed by `camel-api-component-maven-plugin`.
+
+## Build and test
+
+- Build: `mvn install` from the project root (the `*-api` module must be built before the `*-component` module).
+- Test: `mvn test`
+
+## Conventions
+
+- The API method proxies and collections are generated at build time by `camel-api-component-maven-plugin` from the API signatures. Do not hand-edit them — change the API or the signature files instead.
+- The endpoint and configuration classes under `*-component/src/main/java` are hand-written: annotate the endpoint with `@UriEndpoint` and its options with `@UriPath`, `@UriParam` and `@Metadata`.
+- Reference: https://camel.apache.org/manual/writing-components.html

archetypes/camel-archetype-api-component/src/main/resources/archetype-resources/README.md

@@ -0,0 +1,22 @@
+# Camel API Component Project
+
+A custom API-based Apache Camel component generated from the `camel-archetype-api-component` Maven archetype.
+
+This is a multi-module project:
+
+- `*-api` — the Java API that the component proxies.
+- `*-component` — the Camel component, generated from that API by `camel-api-component-maven-plugin`
+  using the API signatures under `*-component/signatures`.
+
+## Build
+
+    mvn install
+
+## For AI coding assistants
+
+See `AGENTS.md` in this directory, and start from the Apache Camel LLM index:
+https://camel.apache.org/llms.txt
+
+## More information
+
+Writing custom components: https://camel.apache.org/manual/writing-components.html

archetypes/camel-archetype-component/src/main/resources-filtered/META-INF/maven/archetype-metadata.xml

@@ -79,7 +79,8 @@
     <fileSet encoding="UTF-8">
       <directory></directory>
       <includes>
-        <include>ReadMe.txt</include>
+        <include>README.md</include>
+        <include>AGENTS.md</include>
       </includes>
     </fileSet>
   </fileSets>

archetypes/camel-archetype-component/src/main/resources/archetype-resources/AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md
+
+Guidance for AI coding assistants working on this project, which was generated from the
+`camel-archetype-component` Maven archetype.
+
+## Start here
+
+- Apache Camel LLM index: https://camel.apache.org/llms.txt
+- Any Apache Camel documentation page is available as LLM-friendly Markdown by replacing `.html` with `.md` in its URL.
+- Prefer the Camel CLI and the Camel MCP server (both linked from the index above) to look up components, their endpoint options and the catalog. Do not invent component URIs or options — verify them against the catalog or the documentation.
+
+## Project layout
+
+- `src/main/java` — the `Component`, `Endpoint`, `Producer` and `Consumer` classes of this component.
+- `src/main/resources/META-INF/services/org/apache/camel/component/<scheme>` — registers the component for its URI scheme.
+- `src/test/java` — tests based on `CamelTestSupport`.
+
+## Build and test
+
+- Build: `mvn install`
+- Test: `mvn test`
+
+## Conventions
+
+- Annotate the endpoint with `@UriEndpoint`, and its options with `@UriPath`, `@UriParam` and `@Metadata`; these annotations drive the generated component metadata and documentation.
+- Keep the file name under `META-INF/services/org/apache/camel/component` in sync with the endpoint scheme.
+- Reference: https://camel.apache.org/manual/writing-components.html

archetypes/camel-archetype-component/src/main/resources/archetype-resources/README.md

@@ -0,0 +1,19 @@
+# Camel Component Project
+
+A custom Apache Camel component generated from the `camel-archetype-component` Maven archetype.
+
+The component, endpoint, producer and consumer classes are in `src/main/java`, and the component is
+registered for its URI scheme by the file in `src/main/resources/META-INF/services/org/apache/camel/component`.
+
+## Build
+
+    mvn install
+
+## For AI coding assistants
+
+See `AGENTS.md` in this directory, and start from the Apache Camel LLM index:
+https://camel.apache.org/llms.txt
+
+## More information
+
+Writing custom components: https://camel.apache.org/manual/writing-components.html

archetypes/camel-archetype-dataformat/src/main/resources-filtered/META-INF/maven/archetype-metadata.xml

@@ -73,7 +73,8 @@
    <fileSet encoding="UTF-8">
       <directory></directory>
       <includes>
-        <include>ReadMe.txt</include>
+        <include>README.md</include>
+        <include>AGENTS.md</include>
       </includes>
     </fileSet>
   </fileSets>

archetypes/camel-archetype-dataformat/src/main/resources/archetype-resources/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md
+
+Guidance for AI coding assistants working on this project, which was generated from the
+`camel-archetype-dataformat` Maven archetype.
+
+## Start here
+
+- Apache Camel LLM index: https://camel.apache.org/llms.txt
+- Any Apache Camel documentation page is available as LLM-friendly Markdown by replacing `.html` with `.md` in its URL.
+- Prefer the Camel CLI and the Camel MCP server (both linked from the index above) to look up components, their endpoint options and the catalog. Do not invent component URIs or options — verify them against the catalog or the documentation.
+
+## Project layout
+
+- `src/main/java` — the `org.apache.camel.spi.DataFormat` implementation.
+- `src/test/java` — tests based on `CamelTestSupport`.
+
+## Build and test
+
+- Build: `mvn install`
+- Test: `mvn test`
+
+## Conventions
+
+- Implement both `marshal` and `unmarshal`, and stream from the given `InputStream`/`OutputStream` instead of buffering whole messages where possible.
+- Use the Camel type converters (`exchange.getContext().getTypeConverter()`) rather than casting the body directly.
+- The data format is registered by the `@org.apache.camel.spi.annotations.Dataformat("<scheme>")` annotation on the class; there is no `META-INF/services` file to add. Keep the annotation value and `getDataFormatName()` in sync.
+- Data formats in Camel: https://camel.apache.org/manual/data-format.html
+- Writing the implementation: https://camel.apache.org/manual/writing-components.html

archetypes/camel-archetype-dataformat/src/main/resources/archetype-resources/README.md

@@ -0,0 +1,21 @@
+# Camel Data Format Project
+
+A custom Apache Camel data format generated from the `camel-archetype-dataformat` Maven archetype.
+
+The data format implementation is in `src/main/java` and implements `org.apache.camel.spi.DataFormat`
+(`marshal` and `unmarshal`).
+
+## Build
+
+    mvn install
+
+## For AI coding assistants
+
+See `AGENTS.md` in this directory, and start from the Apache Camel LLM index:
+https://camel.apache.org/llms.txt
+
+## More information
+
+Data formats in Camel: https://camel.apache.org/manual/data-format.html
+
+Writing the implementation: https://camel.apache.org/manual/writing-components.html

archetypes/camel-archetype-java/src/main/resources-filtered/META-INF/maven/archetype-metadata.xml

@@ -70,7 +70,8 @@
     <fileSet encoding="UTF-8">
       <directory></directory>
       <includes>
-        <include>ReadMe.txt</include>
+        <include>README.md</include>
+        <include>AGENTS.md</include>
       </includes>
     </fileSet>
   </fileSets>

archetypes/camel-archetype-java/src/main/resources/archetype-resources/AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md
+
+Guidance for AI coding assistants working on this project, which was generated from the
+`camel-archetype-java` Maven archetype.
+
+## Start here
+
+- Apache Camel LLM index: https://camel.apache.org/llms.txt
+- Any Apache Camel documentation page is available as LLM-friendly Markdown by replacing `.html` with `.md` in its URL.
+- Prefer the Camel CLI and the Camel MCP server (both linked from the index above) to look up components, their endpoint options and the catalog. Do not invent component URIs or options — verify them against the catalog or the documentation.
+
+## Project layout
+
+- `src/main/java/<package>/MyRouteBuilder.java` — the Camel routes.
+- `src/main/java/<package>/MainApp.java` — starts the application via `org.apache.camel.main.Main`.
+- `src/main/resources/log4j2.properties` — logging.
+- `src/data` — sample messages consumed by the generated route.
+
+## Build and run
+
+- Build: `mvn install`
+- Run: `mvn camel:run`
+
+## Conventions
+
+- Add routes as `RouteBuilder` classes and register them on `Main` the same way as `MyRouteBuilder`, with `main.configure().addRoutesBuilder(...)`. This archetype does not scan for routes.
+- Keep endpoint configuration in `pom.xml` dependencies plus route URIs; add a component dependency before using its scheme.

archetypes/camel-archetype-java/src/main/resources/archetype-resources/README.md

@@ -0,0 +1,22 @@
+# Camel Java Router Project
+
+A standalone Apache Camel application generated from the `camel-archetype-java` Maven archetype.
+Routes live in `src/main/java/<package>/MyRouteBuilder.java` and are started by
+`src/main/java/<package>/MainApp.java`.
+
+## Build
+
+    mvn install
+
+## Run
+
+    mvn camel:run
+
+## For AI coding assistants
+
+See `AGENTS.md` in this directory, and start from the Apache Camel LLM index:
+https://camel.apache.org/llms.txt
+
+## More information
+
+Apache Camel documentation: https://camel.apache.org/

archetypes/camel-archetype-main/src/main/resources-filtered/META-INF/maven/archetype-metadata.xml

@@ -73,7 +73,8 @@
     <fileSet encoding="UTF-8">
       <directory></directory>
       <includes>
-        <include>ReadMe.txt</include>
+        <include>README.md</include>
+        <include>AGENTS.md</include>
       </includes>
     </fileSet>
   </fileSets>

archetypes/camel-archetype-main/src/main/resources/archetype-resources/AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS.md
+
+Guidance for AI coding assistants working on this project, which was generated from the
+`camel-archetype-main` Maven archetype.
+
+## Start here
+
+- Apache Camel LLM index: https://camel.apache.org/llms.txt
+- Any Apache Camel documentation page is available as LLM-friendly Markdown by replacing `.html` with `.md` in its URL.
+- Prefer the Camel CLI and the Camel MCP server (both linked from the index above) to look up components, their endpoint options and the catalog. Do not invent component URIs or options — verify them against the catalog or the documentation.
+
+## Project layout
+
+- `src/main/java/<package>/MyRouteBuilder.java` — the Camel routes.
+- `src/main/java/<package>/MyApplication.java` — starts the application via `org.apache.camel.main.Main`.
+- `src/main/java/<package>/MyBean.java`, `src/main/java/<package>/MyConfiguration.java` — beans wired by Camel's built-in dependency injection.
+- `src/main/resources/application.properties` — Camel Main configuration.
+- `src/test/java/<package>/MyApplicationTest.java` — test using `CamelMainTestSupport`.
+
+## Build and run
+
+- Build: `mvn install`
+- Run: `mvn camel:run`
+- Test: `mvn test`
+
+## Conventions
+
+- Configure Camel through `application.properties` (`camel.main.*`, `camel.component.*`) rather than in code where possible.
+- Register beans with `@BindToRegistry`, and inject with `@BeanInject` and `@PropertyInject`.

archetypes/camel-archetype-main/src/main/resources/archetype-resources/README.md

@@ -0,0 +1,24 @@
+# Camel Main
+
+A standalone Apache Camel application generated from the `camel-archetype-main` Maven archetype,
+running via the built-in `Main` class.
+
+It also shows how to configure the application with Camel's built-in dependency injection
+(`@BindToRegistry`, `@BeanInject` and `@PropertyInject`), and via `src/main/resources/application.properties`.
+
+## Build
+
+    mvn install
+
+## Run
+
+    mvn camel:run
+
+## For AI coding assistants
+
+See `AGENTS.md` in this directory, and start from the Apache Camel LLM index:
+https://camel.apache.org/llms.txt
+
+## More information
+
+Apache Camel documentation: https://camel.apache.org/