(camel) 01/01: chore: document adoc anchor and generated-catalog-sync guidance in AGENTS.md

[da...@apache.org]

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

davsclaus pushed a commit to branch quick-fix/agents-md-adoc-anchor-guidance
in repository https://gitbox.apache.org/repos/asf/camel.git

commit d4deed562c0e6a343f33e3743a75b8413c8ba347
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Mon Aug 31 10:32:17 2026 +0200

    chore: document adoc anchor and generated-catalog-sync guidance in AGENTS.md
    
    Prompted by a broken structured_error_exchange_properties anchor that
    diverged from AsciiDoc's auto-generated heading id, plus a follow-up
    where regenerating the source doc missed the mirrored copy under
    catalog/camel-catalog/src/generated/resources, breaking CI's
    uncommitted-changes check.
    
    Co-Authored-By: Claude Sonnet 5 <no...@anthropic.com>
    Signed-off-by: Claus Ibsen <cl...@gmail.com>
---
 AGENTS.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index aa8f7d3e73a2..75bdfdca38f2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -353,6 +353,17 @@ When writing or modifying `.adoc` documentation:
   version-aware reference.
 - **When reviewing doc PRs**, check that all `xref:` links and anchors resolve correctly, especially
   cross-component references that may span versions.
+- **Avoid explicit `[[anchor]]` blocks before a heading.** AsciiDoc already auto-generates an id from
+  the heading text (prefixed with `_`, e.g. `=== Structured error exchange properties` becomes
+  `#_structured_error_exchange_properties`). An explicit `[[structured_error_exchange_properties]]`
+  anchor sets the id *without* that prefix, so it silently diverges from the id every other `xref:`
+  in the codebase expects and breaks the website link checker. Only add an explicit anchor when a
+  stable id is needed that must survive a heading rename — never as a matter of habit.
+- **Component doc changes require regenerating the catalog.** Editing a component's
+  `src/main/docs/*.adoc` also requires regenerating and committing the mirrored copy under
+  `catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/`. CI's
+  "uncommitted changes" check fails otherwise — this applies even to small doc-only edits like
+  removing an anchor, not just code-driven metadata changes.
 
 ## Security Model