Claus Ibsen created CAMEL-25714:
-----------------------------------
Summary: camel-jbang-mcp - camel_catalog_doc: a summary for each
doc section, so an agent can tell which section to read
Key: CAMEL-25714
URL: https://issues.apache.org/jira/browse/CAMEL-25714
Project: Camel
Issue Type: Improvement
Components: camel-jbang-mcp
Reporter: Claus Ibsen
Fix For: 4.24.0
CAMEL-25541 gave the component answer of {{camel_catalog_doc}} the titles of
the page sections ({{sections}}), and {{docPage=<section title>}} returns one
section. An agent has to pick a section from its title alone, and many titles
say little about what the section holds: the doc pages under {{components/}}
(590) have about 5,000 {{==}} to {{====}} headings, and the most common titles
are *Usage* (311 pages) and *Examples* (244). Usage is often the catch-all that
holds what decides correctness, such as the mail {{useHeader*}} options.
h3. Proposal
* Let an AI go over every section of the doc pages and write a one-line summary
of what the section holds, stored in the .adoc as a named attribute on the line
above the heading:
{code}
[summary="TLS for imaps, pop3s and smtps: sslContextParameters, or JavaMail
properties for STARTTLS"]
=== SSL support
{code}
** Asciidoctor keeps an unknown named attribute on the section and renders
nothing, so the website does not change.
** It sets no id, so the generated id ({{_ssl_support}}) and the xrefs to it
keep working, unlike an explicit anchor before the heading.
** It moves with the heading when a section is renamed or moved, and it reaches
the catalog copy of the page that {{camel_catalog_doc}} reads.
** One line, in double quotes (summaries have commas); a quote inside is
written as backslash and quote.
* {{camel_catalog_doc}} returns the summary with each section title. When a
section has no summary, the first sentence of its text is the fallback.
* Keep the summaries true: store a short hash of the section text with the
summary (for example {{summary-hash=...}}), and let a build check report the
sections whose text changed since, so only those are summarized again. The
check reports and does not fail, so a doc fix does not break the build.
h3. Also
* Return the parent of each section (the list is flat today: _Using the JSSE
Configuration Utility_ does not say it is part of _SSL support_) and its size,
so an agent knows what a {{docPage}} call will cost.
* Fit the 16,000 character cap of the answer: 40 sections with a 100 character
summary are 4,000 characters, so the summaries may go only with the sections
that rank first, or come from a table of contents call.
* Rank the sections by the agent's question, not only by a substring of
{{optionsFilter}}.
* Small fixes: 28 headings use the closing form ({{=== Legacy ===}}) and the
title keeps the trailing equal signs; 13 titles keep the doctitle attribute
unresolved ("doctitle components").
* Measure the effect with the agent benchmark: does the agent pick the section
with the xslt header parameters, the mail {{useHeader*}} options, or
{{camel.server.*}} for platform-http.
Start with the component pages; the EIP, language, data format and user manual
pages can follow.
_Claude Code on behalf of davsclaus_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
