@crypto512/jicon-mcp 1.2.0 → 2.0.0

package/dist/utils/jicon-help.js

@@ -6,23 +6,27 @@
  */
 import { z } from "zod";
 import { formatSuccess, formatError } from "./response-formatter.js";
-import { ALLOWED_INCLUDE_URLS } from "./plantuml/index.js";
 // Available topics
 const TOPICS = ["jql", "cql", "storage", "plantuml", "buffers"];
 // Default workflow guide (shown when no topic specified)
 const WORKFLOW_GUIDE = `# Jicon Quick Reference
 
+TOOLS: jira(16) confluence(18) tempo(11) buffer(14) plantuml(3) url(2) help(1)
+
 ## Decision Tree - Which Topic?
 
 | Task | First Step |
 |------|------------|
 | Edit Confluence page | \`confluence_edit(input)\` ← accepts URL, pageId, or SPACE/Title |
-| Create NEW page | \`confluence_draft_create(spaceKey, title, content)\` |
+| Create NEW page | \`buffer_create(content, contentType="xhtml")\` then \`confluence_draft_create\` |
 | Create page with diagram | \`help(topic="plantuml")\` |
-| XHTML syntax needed | \`help(topic="storage")\` |
+| XHTML syntax needed | \`help(topic="storage")\` ← **READ THIS for HTML vs XHTML** |
 | Search Confluence | \`help(topic="cql")\` |
 | Search Jira | \`jira_get_issue_types()\` then \`help(topic="jql")\` |
 | Log/get time | \`tempo_get_user_info()\` first |
+| **Create table from Jira data** | \`buffer_pipeline(bufferId, pipeline={output:{type:"xhtml_table"}})\` |
+| **Iterate items for AI analysis** | \`buffer_get_items(bufferId, start=0, count=50)\` |
+| **Large dataset + AI columns** | Batch workflow - see \`help(topic="buffers")\` |
 
 ---
 
@@ -34,16 +38,16 @@ const WORKFLOW_GUIDE = `# Jicon Quick Reference
    - Accepts: URL, pageId, "draft:ID", or "SPACE/Title"
    → Returns: bufferId, structure (element IDs), pageId
 2. buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId)
-   → Use content="<p>text</p>" for XHTML
+   → Use content="<p>text</p>" for XHTML (use <br/> not <br>!)
    → Use plantuml="@startuml..." for diagrams
    → Use fromBufferId="buf_xxx" to merge another buffer
-3. confluence_draft_create(pageId=..., bufferId=...)
+3. buffer_validate_xhtml(bufferId) → check for errors before saving
+4. confluence_draft_create(pageId=..., bufferId=...)
    → Creates "[jicon-mcp REVIEW] Title" draft linked to original
    → Returns: reviewDraftId, draft URL for user review
-4. User reviews in Confluence UI (can share draft with team)
-5. confluence_review_publish(reviewDraftId) → applies changes to original
+5. User reviews in Confluence UI (can share draft with team)
+6. confluence_review_publish(reviewDraftId) → applies changes to original
    OR confluence_review_discard(reviewDraftId) → cancels without changes
-6. For more edits: confluence_edit(same URL or "SPACE/Title")
 \`\`\`
 
 **Review Workflow Tools:**
@@ -51,14 +55,24 @@ const WORKFLOW_GUIDE = `# Jicon Quick Reference
 - \`confluence_review_discard(reviewDraftId)\` - Discard without changes
 - \`confluence_review_list()\` - Find all review drafts for cleanup
 
-### Create NEW Confluence Page
+**Draft Management Tools:**
+- \`confluence_draft_list()\` - List all drafts in your personal space
+- \`confluence_draft_open(draftId)\` - Reopen a draft for editing
+- \`confluence_draft_delete(draftId)\` - Delete a draft
+
+### Create NEW Confluence Page (Buffer-First)
 \`\`\`
-1. confluence_draft_create(spaceKey, title, content)
-   → Returns: draftId, bufferId, draft URL
-2. User reviews and publishes via Confluence UI
-3. For edits after publish: confluence_edit("SPACE/Title")
+1. buffer_create(content="<h1>Title</h1><p>Content</p>", contentType="xhtml")
+   → Returns: bufferId, structure (element IDs)
+2. buffer_validate_xhtml(bufferId)
+   → If errors: use buffer_edit(bufferId, replace=elementId, ...) to fix
+3. confluence_draft_create(spaceKey, title, bufferId)
+   → Returns: draftId, draft URL for user review
+4. User reviews and publishes via Confluence UI
 \`\`\`
 
+**Why buffer-first?** Enables validation and surgical error fixing with element IDs.
+
 ### Insert PlantUML Diagram
 \`\`\`
 1. plantuml_validate(code="@startuml...") ← Validate FIRST
@@ -143,7 +157,18 @@ const JQL_HELP = `# JQL Syntax Guide
 - Date functions: startOfDay(), startOfWeek(), startOfMonth(), now()
 - Relative dates: startOfDay(-7) = 7 days ago
 - Always quote field values that contain spaces
-- Issue type names may be localized (e.g., "Epopee" instead of "Epic")`;
+- Issue type names may be localized (e.g., "Epopee" instead of "Epic")
+
+## Response Fields (jira_search_issues)
+- returnedItems: Items available in buffer (max 5000) - USE THIS
+- jiraTotalMatching: Total Jira found (may exceed returnedItems)
+- apiLimit: Maximum per search (5000)
+- If jiraTotalMatching > returnedItems, refine JQL to narrow results
+
+## Date Handling Tips
+- "Last week" in business context = previous Mon-Fri (e.g., Dec 8-12)
+- "Rolling 7 days" = use startOfDay(-7)
+- For exact date ranges, use explicit dates: updated >= "2025-12-08" AND updated <= "2025-12-12"`;
 // CQL syntax guide
 const CQL_HELP = `# CQL Syntax Guide
 
@@ -196,25 +221,48 @@ OK: (text~"term1" OR text~"term2") - Each term needs its own text~ operator
 - Use space KEY (e.g., 'DOCS') not space name (e.g., 'Documentation')
 - Date functions: now(), startOfDay(), startOfWeek(), startOfMonth()
 - Relative dates: now("-7d") = 7 days ago
-- Results are auto-fetched (up to 5000) and buffered for large responses`;
+- Results are always buffered - use buffer_get_chunk to read, buffer_grep to search`;
 // Confluence storage format (XHTML syntax only)
 const STORAGE_FORMAT_HELP = `# Confluence Storage Format (XHTML)
 
-All tags must be closed (XML rules). For editing workflow, see \`help(topic="buffers")\`.
+Confluence uses **XHTML** (strict XML), NOT loose HTML5. This matters!
 
-## CRITICAL: CDATA Usage
+## CRITICAL: HTML vs XHTML Differences
 
-**NEVER wrap content in \`<![CDATA[...]]>\`**
+| HTML (loose) | XHTML (strict) | Why |
+|--------------|----------------|-----|
+| \`<br>\` | \`<br/>\` | Self-closing required |
+| \`<hr>\` | \`<hr/>\` | Self-closing required |
+| \`<img src="x">\` | \`<img src="x"/>\` | Self-closing required |
+| \`<p>text\` | \`<p>text</p>\` | All tags must close |
+| \`<li>item\` | \`<li>item</li>\` | All tags must close |
+| \`&\` in URLs | \`&amp;\` | Must escape special chars |
+| \`<LI>\` | \`<li>\` | Tags are lowercase |
 
-CDATA is ONLY used inside \`<ac:plain-text-body>\` elements (code blocks, PlantUML):
-\`\`\`xml
-<!-- CORRECT: CDATA inside ac:plain-text-body -->
-<ac:structured-macro ac:name="code">
-  <ac:plain-text-body><![CDATA[code here]]></ac:plain-text-body>
-</ac:structured-macro>
+## Common Mistakes to AVOID
+
+| ❌ Wrong | ✅ Correct | Error |
+|----------|-----------|-------|
+| \`<br>\` | \`<br/>\` | Parser expects \`</br>\` |
+| \`li>item</li>\` | \`<li>item</li>\` | Missing \`<\` before tag |
+| \`h2. Title\` | \`<h2>Title</h2>\` | Wiki syntax not allowed |
+| \`**bold**\` | \`<strong>bold</strong>\` | Markdown not allowed |
+| \`<![CDATA[<p>...</p>]]>\` | \`<p>...</p>\` | CDATA only in macros |
+
+## Workflow: Buffer-First Approach
 
-<!-- WRONG: CDATA wrapping content -->
-<![CDATA[<h1>Title</h1>]]>
+\`\`\`
+1. buffer_create(content="<h1>Title</h1><p>Text</p>", contentType="xhtml")
+   → bufferId, structure (element IDs)
+
+2. buffer_validate_xhtml(bufferId)
+   → If errors: shows elementId to fix
+
+3. buffer_edit(bufferId, replace=elementId, content="<p>Fixed</p>")
+   → Surgical fix using element ID
+
+4. confluence_draft_create(spaceKey, title, bufferId)
+   → Creates draft for user review
 \`\`\`
 
 ## Basic Elements
@@ -222,11 +270,41 @@ CDATA is ONLY used inside \`<ac:plain-text-body>\` elements (code blocks, PlantU
 | Element | Syntax |
 |---------|--------|
 | Paragraph | \`<p>text</p>\` |
-| Headings | \`<h1>\`...\`<h6>\` |
-| Bold/Italic | \`<strong>\`, \`<em>\` |
+| Headings | \`<h1>...</h1>\` to \`<h6>...</h6>\` |
+| Bold/Italic | \`<strong>text</strong>\`, \`<em>text</em>\` |
+| Line break | \`<br/>\` (self-closing!) |
+| Horizontal rule | \`<hr/>\` (self-closing!) |
 | Code inline | \`<code>text</code>\` |
-| Link | \`<a href="url">text</a>\` |
-| List | \`<ul><li>item</li></ul>\` or \`<ol>\` |
+| List | \`<ul><li>item</li></ul>\` or \`<ol><li>...</li></ol>\` |
+
+## Links (IMPORTANT: Two Types!)
+
+### External Links (Jira, Web URLs)
+For links to external sites including Jira issues, use standard HTML anchor tags:
+\`\`\`xml
+<a href="https://jira.example.com/browse/PROJ-123">PROJ-123</a>
+<a href="https://example.com">Example Site</a>
+\`\`\`
+
+**Example: Jira links in a table:**
+\`\`\`xml
+<table><tbody>
+  <tr><th>Issue</th><th>Summary</th></tr>
+  <tr>
+    <td><a href="https://jira.example.com/browse/FR-1301">FR-1301</a></td>
+    <td>Fix login bug</td>
+  </tr>
+</tbody></table>
+\`\`\`
+
+### Confluence Page Links (Internal)
+For links to other Confluence pages, use the ac:link macro:
+\`\`\`xml
+<ac:link><ri:page ri:content-title="Page Title"/>
+  <ac:plain-text-link-body><![CDATA[Link Text]]></ac:plain-text-link-body>
+</ac:link>
+\`\`\`
+Cross-space: add \`ri:space-key="KEY"\` to ri:page
 
 ## Tables
 \`\`\`xml
@@ -248,14 +326,6 @@ Merge cells: \`colspan="2"\`, \`rowspan="2"\`
 \`\`\`
 Types: \`single\`, \`two_equal\`, \`two_left_sidebar\`, \`two_right_sidebar\`, \`three_equal\`
 
-## Page Links
-\`\`\`xml
-<ac:link><ri:page ri:content-title="Page Title"/>
-  <ac:plain-text-link-body><![CDATA[Link Text]]></ac:plain-text-link-body>
-</ac:link>
-\`\`\`
-Cross-space: add \`ri:space-key="KEY"\` to ri:page
-
 ## Images
 \`\`\`xml
 <ac:image ac:width="300"><ri:attachment ri:filename="image.png"/></ac:image>
@@ -269,10 +339,14 @@ Cross-space: add \`ri:space-key="KEY"\` to ri:page
 </ac:task-list>
 \`\`\`
 
-## Emoticons
+## Status Indicators (use emoticons)
 \`\`\`xml
-<ac:emoticon ac:name="tick"/>  <!-- tick, cross, warning, information -->
-<ac:emoticon ac:name="thumbs-up"/>  <!-- thumbs-up/down, plus, minus -->
+<ac:emoticon ac:name="tick"/>      <!-- ✓ green checkmark -->
+<ac:emoticon ac:name="cross"/>     <!-- ✗ red X -->
+<ac:emoticon ac:name="warning"/>   <!-- ⚠ yellow warning -->
+<ac:emoticon ac:name="information"/>  <!-- ℹ blue info -->
+<ac:emoticon ac:name="plus"/>      <!-- + green plus -->
+<ac:emoticon ac:name="minus"/>     <!-- - red minus -->
 \`\`\`
 
 ## Code Block Macro
@@ -291,18 +365,31 @@ Cross-space: add \`ri:space-key="KEY"\` to ri:page
 \`\`\`
 Types: \`info\`, \`note\`, \`warning\`, \`tip\`
 
-## Macro Rules
+## CDATA Rules
+
+**CDATA is ONLY used inside \`<ac:plain-text-body>\`** (code blocks, PlantUML):
+\`\`\`xml
+<!-- CORRECT: CDATA inside ac:plain-text-body -->
+<ac:structured-macro ac:name="code">
+  <ac:plain-text-body><![CDATA[code here]]></ac:plain-text-body>
+</ac:structured-macro>
+
+<!-- WRONG: CDATA wrapping regular content -->
+<![CDATA[<h1>Title</h1>]]>
+\`\`\`
+
+## Macro Content Rules
 
 | Element | Content Allowed |
 |---------|-----------------|
 | \`ac:parameter\` | Plain text only (no child elements) |
-| \`ac:plain-text-body\` | Raw text, wrap in \`<![CDATA[...]]>\` |
-| \`ac:rich-text-body\` | XHTML for info/warning panels |
+| \`ac:plain-text-body\` | Raw text wrapped in \`<![CDATA[...]]>\` |
+| \`ac:rich-text-body\` | XHTML (for info/warning panels) |
 
 ---
 
-For element ID editing workflow, see \`help(topic="buffers")\`.
-For PlantUML diagrams, see \`help(topic="plantuml")\`.`;
+For element ID editing: \`help(topic="buffers")\`
+For PlantUML diagrams: \`help(topic="plantuml")\``;
 // PlantUML syntax guide (Confluence-specific only - LLMs know PlantUML syntax)
 const PLANTUML_HELP = `# PlantUML in Confluence
 
@@ -322,18 +409,6 @@ const PLANTUML_HELP = `# PlantUML in Confluence
 | \`plantuml_render(code, format)\` | Preview: ascii, svg, png, eps |
 | \`plantuml_status()\` | Check Docker container status |
 
-## Confluence Macro Structure (auto-generated by buffer_edit)
-\`\`\`xml
-<ac:structured-macro ac:name="plantuml" ac:schema-version="1" ac:macro-id="uuid">
-  <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
-  <ac:plain-text-body><![CDATA[
-@startuml
-' diagram code
-@enduml
-]]></ac:plain-text-body>
-</ac:structured-macro>
-\`\`\`
-
 ## Critical Rules (MANDATORY)
 
 1. **Always use \`plantuml\` parameter**: \`buffer_edit(..., plantuml="...")\` is REQUIRED
@@ -351,27 +426,28 @@ const PLANTUML_HELP = `# PlantUML in Confluence
 
 ## Stdlib Includes (C4, AWS, Azure)
 
-C4-PlantUML, AWS icons, and Azure diagrams are supported via \`!include\`:
+C4-PlantUML, AWS icons, Azure, and Kubernetes diagrams use PlantUML's built-in standard library.
+GitHub URLs are automatically converted to stdlib syntax:
+
+| GitHub URL | Converted to |
+|------------|--------------|
+| \`https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/.../C4_Context.puml\` | \`!include <C4/C4_Context>\` |
+| \`https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/.../dist/AWSCommon.puml\` | \`!include <awslib/AWSCommon>\` |
+| \`https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/.../AzureCommon.puml\` | \`!include <azure/AzureCommon>\` |
+| \`https://raw.githubusercontent.com/plantuml-stdlib/plantuml-kubernetes-sprites/...\` | \`!include <kubernetes/...>\` |
 
+**Example (either syntax works):**
 \`\`\`
 @startuml
-!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+!include <C4/C4_Context>
 Person(user, "User")
 System(sys, "My System")
 Rel(user, sys, "Uses")
 @enduml
 \`\`\`
 
-**Requires \`plantumlInclude: true\`** (enabled by default in .jicon.json)
-
-When enabled, \`!include\` from whitelisted URLs are authorized and expanded client-side
-before validation and Confluence upload. Expanded includes are automatically collapsed
-back to \`!include\` directives when reading pages.
-
-**Whitelisted URL prefixes:**
-${ALLOWED_INCLUDE_URLS.map((url) => `- \`${url}\``).join("\n")}
-
-Non-whitelisted URLs are left unchanged (PlantUML server may reject them due to SSRF restrictions).
+GitHub URLs in diagrams are converted to stdlib syntax before validation and rendering.
+Non-convertible URLs are left unchanged and may fail if the PlantUML server can't fetch them.
 
 ## Quick Examples
 
@@ -395,7 +471,7 @@ User --> Order
 **C4 Context Diagram:**
 \`\`\`
 @startuml
-!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+!include <C4/C4_Context>
 Person(user, "Customer", "Uses the system")
 System(sys, "E-Commerce", "Online store")
 System_Ext(pay, "Payment Gateway", "Processes payments")
@@ -434,34 +510,19 @@ Rel(sys, pay, "Pays via")
 | "Element not found" | Check \`buffer_get_structure\` for valid IDs |
 | "XHTML invalid" | Create fresh buffer, insert diagram |
 
-## Advanced: Direct Macro Embedding
-
-For pages with **multiple diagrams**, reduce tool calls by embedding macros directly:
-
-\`\`\`
-1. plantuml_validate(code) × N   ← Validate ALL diagrams first (parallel)
-2. buffer_create with embedded macros:
-\`\`\`
+## Multiple Diagrams
 
-\`\`\`xml
-<h2>Architecture</h2>
-<ac:structured-macro ac:name="plantuml" ac:schema-version="1" ac:macro-id="diag-1">
-  <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
-  <ac:plain-text-body><![CDATA[@startuml
-...validated code...
-@enduml]]></ac:plain-text-body>
-</ac:structured-macro>
-<h2>Sequence Flow</h2>
-<ac:structured-macro ac:name="plantuml" ac:schema-version="1" ac:macro-id="diag-2">
-  ...second diagram...
-</ac:structured-macro>
-\`\`\`
+For pages with multiple diagrams, call \`buffer_edit\` multiple times:
 
 \`\`\`
-3. confluence_draft_create(bufferId=...)
+1. plantuml_validate(code1)  ← Validate first diagram
+2. plantuml_validate(code2)  ← Validate second diagram (parallel)
+3. buffer_edit(bufferId, after=5, plantuml=code1)
+4. buffer_edit(bufferId, after=6, plantuml=code2)
+5. confluence_draft_create(bufferId=...)
 \`\`\`
 
-**Benefit**: 3 diagrams = 5 calls (vs 8 with buffer_edit per diagram)
+Each \`plantuml\` parameter = one diagram. The macro wrapping is automatic.
 
 For element ID editing: \`help(topic="buffers")\``;
 // Buffers help guide (canonical element ID reference)
@@ -555,9 +616,10 @@ When editing existing pages, you can create content in a separate buffer and mer
 
 | Tool | Use |
 |------|-----|
-| \`buffer_get_structure(bufferId)\` | View current element IDs |
+| \`buffer_get_structure(bufferId)\` | View current element IDs (XHTML) |
 | \`buffer_get_element(bufferId, elementId)\` | Get raw XHTML of specific element |
-| \`buffer_get_chunk(bufferId, offset, limit)\` | Read content in chunks |
+| \`buffer_get_items(bufferId, start, count)\` | Get complete JSON items (not truncated) |
+| \`buffer_get_chunk(bufferId, offset, limit)\` | Read raw content in character chunks |
 | \`buffer_grep(bufferId, pattern, "-C"=2)\` | Search with context |
 | \`buffer_validate_xhtml(bufferId)\` | Check XHTML validity |
 | \`buffer_list()\` | See all active buffers |
@@ -565,16 +627,200 @@ When editing existing pages, you can create content in a separate buffer and mer
 
 ## Plain/JSON Editing (non-XHTML)
 
+**String replacement:**
 \`\`\`
 buffer_edit(bufferId, old_string="foo", new_string="bar", replace_all=true)
 \`\`\`
 
+**Append content:**
+\`\`\`
+buffer_edit(bufferId, append=true, content="text to add at end")
+\`\`\`
+
+## JSON Pipeline (buffer_pipeline) - RECOMMENDED
+
+Transform JSON buffers with a declarative pipeline: filter, group, sort, format, output.
+
+**98% token reduction** for data transformations - no need to iterate through items!
+
+**Basic workflow:**
+\`\`\`
+1. jira_search_issues(jql="...") → { bufferId, structure: { itemCount: 578 } }
+
+2. buffer_pipeline(bufferId, pipeline={
+     filter: [{ field: "status.name", operator: "ne", value: "Done" }],
+     sort: [{ field: "priority.name", direction: "asc" }],
+     output: {
+       type: "xhtml_table",
+       table: {
+         title: "Open Issues",
+         columns: [
+           { field: "key", header: "Issue", link: { type: "jira" } },
+           { field: "summary", header: "Summary" },
+           { field: "priority.name", header: "Priority" }
+         ]
+       }
+     }
+   })
+   → { bufferId: "buf_new", outputItems: 45, preview: "..." }
+
+3. Insert into Confluence page or use directly
+\`\`\`
+
+**Pipeline stages (all optional except output):**
+- \`select\`: Extract and rename fields
+- \`filter\`: Filter items (eq, ne, contains, in, regex, etc.)
+- \`groupBy\`: Group and aggregate (count, sum, avg, list, etc.)
+- \`sort\`: Sort by fields
+- \`limit\`: Limit results
+- \`format\`: Conditional styling (colors, bold, icons)
+- \`output\`: Generate output (xhtml_table, xhtml_list, json, csv, markdown)
+
+**Schema Quick Reference:**
+\`\`\`
+pipeline: {
+  select?: { fields: [{from: "path", as: "name", transform?: "..."}] },
+  filter?: [{ field, operator, value }],
+  groupBy?: { field, aggregations: [{function, field?, as}] },
+  sort?: [{ field, direction: "asc"|"desc" }],  // NOT "sortBy"!
+  limit?: number,
+  format?: [...],
+  output: { type: "xhtml_table"|"json"|"csv"|..., table?: {...} }
+}
+\`\`\`
+
+**Common Mistakes:**
+| Wrong | Correct |
+|-------|---------|
+| sortBy: [...] | sort: [...] |
+| transform: "map" | transform: "date" (or uppercase, lowercase, number, boolean, string) |
+| No output | output: {...} (REQUIRED) |
+| pipeline: "{...}" | pipeline: {...} (object, not string) |
+
+**After select renames fields, use NEW names in subsequent stages:**
+- select: {from: "issueType", as: "Type"}
+- sort: [{field: "Type"}] ✓ (not "issueType")
+
+**Filter operators:** eq, ne, gt, lt, gte, lte, contains, startsWith, endsWith, in, notIn, exists, notExists, regex, empty, notEmpty
+
+**Aggregations:** count, sum, avg, min, max, first, last, list, unique
+
+**Example - Statistics by assignee:**
+\`\`\`
+buffer_pipeline(bufferId, pipeline={
+  filter: [{ field: "status.name", operator: "ne", value: "Done" }],
+  groupBy: {
+    field: "assignee.displayName",
+    aggregations: [
+      { function: "count", as: "total" },
+      { function: "list", field: "key", as: "issues" }
+    ]
+  },
+  sort: [{ field: "total", direction: "desc" }],
+  output: {
+    type: "xhtml_table",
+    table: {
+      title: "Work Distribution",
+      columns: [
+        { field: "displayName", header: "Assignee" },
+        { field: "total", header: "Open Issues" },
+        { field: "issues", header: "Issue Keys" }
+      ]
+    }
+  }
+})
+\`\`\`
+
+**When to use buffer_pipeline:**
+- Generating tables/lists for Confluence
+- Creating CSV/Markdown exports
+- Aggregating statistics
+- Filtering and sorting large result sets server-side
+
+**When NOT to use buffer_pipeline:**
+- When you need LLM judgment on each item
+- When decisions require analyzing content (use buffer_get_items instead)
+
+## Decision Forks (Choose Your Path)
+
+After jira_search_issues/tempo_get_worklogs returns a bufferId, you have OPTIONS:
+
+| What You Need | Tool to Use | Result |
+|---------------|-------------|--------|
+| READ/ANALYZE items with AI | buffer_get_items(start=0, count=50) | Get items for analysis |
+| SEARCH within results | buffer_grep(pattern) | Find matching items |
+| FORMAT for Confluence | buffer_pipeline → xhtml_table | TERMINAL: publish-ready |
+| TRANSFORM and keep flexible | buffer_pipeline → json | Can process again |
+| EXPORT to file | buffer_pipeline → csv/markdown | TERMINAL: file-ready |
+
+**⚠️ OUTPUT TYPE CONSEQUENCES:**
+| Type | Can Iterate Items? | Can Edit? | Next Steps |
+|------|-------------------|-----------|------------|
+| json | ✓ buffer_get_items | ✓ buffer_pipeline | Further processing, re-transform |
+| xhtml_* | ✗ (not iterable) | ✓ buffer_edit | confluence_draft_create |
+| csv/md | ✗ (not iterable) | ✓ buffer_edit | buffer_get_chunk |
+
+**Choose json** if you need to iterate items for AI analysis (buffer_get_items).
+**Choose xhtml_*** when ready to publish - you can still edit elements, but can't iterate.
+
+---
+
+## Large Dataset Patterns
+
+### Simple table (no AI analysis)
+Use \`buffer_pipeline\` - generates complete table in **ONE tool call**:
+\`\`\`
+jira_search_issues(jql="...") → bufferId (500+ items)
+buffer_pipeline(bufferId, pipeline={output:{type:"xhtml_table",...}}) → complete table!
+\`\`\`
+
+### Table with AI-enhanced columns (complexity, impact)
+Use **batch accumulation workflow** - analyze items in batches, compose results:
+
+\`\`\`
+1. jira_search_issues(jql="...") → sourceBufferId (578 items)
+
+2. buffer_create(content="<table><thead>...</thead><tbody></tbody></table>", contentType="xhtml")
+   → accumulatorBufferId, structure (note tbody element ID)
+
+3. For each batch of 50 items:
+   buffer_get_items(sourceBufferId, start=X, count=50) → items[]
+   // AI analyzes items, builds XHTML rows with AI columns
+   buffer_create(content=rowsXHTML, contentType="xhtml") → batchBufferId
+   buffer_edit(accumulatorBufferId, after=lastRowId, fromBufferId=batchBufferId)
+
+4. buffer_edit(pageBufferId, after=ID, fromBufferId=accumulatorBufferId)
+   confluence_draft_create(pageId, pageBufferId) → draft for review
+\`\`\`
+
+---
+
+## Reading JSON Data (buffer_get_items, buffer_grep)
+
+For cases where you need to read and analyze the data (not just transform it):
+
+\`\`\`
+1. jira_search_issues(jql="...")
+   → { bufferId, structure: { itemCount: 519 } }
+
+2. buffer_get_items(bufferId, start=0, count=50)
+   → Get 50 complete items for analysis (not truncated)
+
+3. buffer_grep(bufferId, pattern="urgent")
+   → Search within buffer
+\`\`\`
+
+Use these when:
+- You need to understand the content to make decisions
+- You're writing custom analysis that can't be expressed as a pipeline
+- You're building tables with AI-enhanced columns (batch workflow)
+
 ## Common Errors & Recovery
 
 | Error | Fix |
 |-------|-----|
 | "Element not found: N" | Check \`buffer_get_structure\` for valid IDs |
-| "Buffer expired" | Re-fetch content, buffers expire in 10 min |
+| "Buffer expired" | Re-fetch content, buffers expire in 1 hour |
 | Multiple occurrences | Use \`replace_all=true\` for string edit |
 | XHTML parsing error | Check \`suggestedActions\` in error response |
 
@@ -587,7 +833,7 @@ buffer_edit(bufferId, old_string="foo", new_string="bar", replace_all=true)
 
 - IDs are **stable**: insert between 2 and 3 → new element gets id=5, element 3 unchanged
 - Use \`buffer_get_structure\` after edits to see updated structure
-- Buffers expire in 10 min (24h if modified)
+- Buffers expire in 1 hour (24h if modified)
 - XHTML syntax: \`help(topic="storage")\`
 - PlantUML: \`help(topic="plantuml")\``;
 // Topic content map
@@ -611,7 +857,7 @@ Available topics:
 - cql: CQL (Confluence Query Language) syntax
 - storage: Confluence storage format + structure editing (element IDs)
 - plantuml: PlantUML diagram syntax for Confluence
-- buffers: Buffer management and large response handling
+- buffers: Buffer management and element ID editing
 
 Examples:
   help() -> Workflow guide

package/dist/utils/jicon-help.js.map

@@ -1 +1 @@
-{"version":3,"file":"jicon-help.js","sourceRoot":"","sources":["../../src/utils/jicon-help.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"jicon-help.js","sourceRoot":"","sources":["../../src/utils/jicon-help.ts"],"names":[],"mappings":"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"}