@crypto512/jicon-mcp 1.0.4 → 1.1.0

package/dist/utils/jicon-help.js

@@ -7,159 +7,74 @@
 import { z } from "zod";
 import { formatSuccess, formatError } from "./response-formatter.js";
 // Available topics
-const TOPICS = ["jql", "cql", "storage", "plantuml"];
+const TOPICS = ["jql", "cql", "storage", "plantuml", "buffers"];
 // Default workflow guide (shown when no topic specified)
 const WORKFLOW_GUIDE = `# Jicon Quick Reference
 
-## Topics Available
-\`help(topic="jql|cql|storage|plantuml")\`
+## Decision Tree - Which Topic?
 
----
-
-## Confluence Workflows
-
-### Create Page
-\`\`\`
-help(topic="storage") <- GET SYNTAX FIRST
-  -> confluence_draft_create(spaceKey, title, content)
-     Returns: draftId, bufferId, url
-  -> User publishes via Confluence UI
-\`\`\`
-
-### Create Page with Diagram
-\`\`\`
-help(topic="plantuml") <- GET DIAGRAM SYNTAX FIRST
-help(topic="storage") <- GET PAGE SYNTAX
-  -> confluence_draft_create(...)
-  -> User publishes via Confluence UI
-\`\`\`
-
-### Draft Workflow (iterative editing)
-\`\`\`
-help(topic="storage") <- if syntax needed
-  -> confluence_draft_create(spaceKey, title, content)
-     Returns: draftId, bufferId, url (click to preview)
-  -> buffer_edit_xhtml(...) or buffer_edit(...) [repeat]
-  -> confluence_draft_save(draftId, bufferId) [checkpoint]
-  -> User publishes manually via Confluence UI
-\`\`\`
-
-### Update Page
-\`\`\`
-confluence_get_page(pageId) -> bufferId
-  -> buffer_edit_xhtml(...) or buffer_edit(...)
-  -> confluence_draft_create(spaceKey, title, bufferId=bufferId)
-  -> User publishes via Confluence UI
-\`\`\`
-
-### Search Pages
-\`\`\`
-help(topic="cql") <- GET QUERY SYNTAX FIRST
-  -> confluence_search_content(cql)
-\`\`\`
-
-### Write-Home Restriction
-When enabled, writes restricted to personal space only.
-\`\`\`
-confluence_get_current_user_space() <- GET YOUR SPACE KEY FIRST
-  -> use spaceKey for create/update
-\`\`\`
+| Task | First Step |
+|------|------------|
+| Edit Confluence page | \`help(topic="buffers")\` ← Element ID editing |
+| Create page with diagram | \`help(topic="plantuml")\` |
+| XHTML syntax needed | \`help(topic="storage")\` |
+| Search Confluence | \`help(topic="cql")\` |
+| Search Jira | \`jira_get_issue_types()\` then \`help(topic="jql")\` |
+| Log/get time | \`tempo_get_user_info()\` first |
 
 ---
 
-## Jira Workflows
-
-### Search Issues
-\`\`\`
-jira_get_issue_types() <- DISCOVER TYPE NAMES FIRST
-help(topic="jql") <- GET QUERY SYNTAX
-  -> jira_search_issues(jql)
-\`\`\`
-
-### Create Issue
-\`\`\`
-jira_get_issue_types() <- DISCOVER TYPES FIRST
-  -> jira_create_issue(projectKey, issueType, summary)
-  -> fullurl(issueKey) for clickable link
-\`\`\`
+## Core Workflows
 
-### Worklogs
+### Create/Edit Confluence Page
 \`\`\`
-jira_get_issue_worklogs(issueKey) [single issue]
-jira_get_total_worklogs(epicKey) [epic + children]
-  -> workload_convert/workload_sum for calculations
+1. confluence_draft_create(spaceKey, title, content) OR confluence_get_page(pageId)
+   → Returns: bufferId, structure (element IDs)
+2. buffer_edit(bufferId, after=ID, content="<p>text</p>")
+   → Use IDs from structure to position content
+3. confluence_draft_save(draftId, bufferId)
+   → Returns: url for preview
+4. User publishes via Confluence UI
 \`\`\`
 
----
-
-## Tempo Workflows
-
-### Log Work
+### Insert PlantUML Diagram
 \`\`\`
-tempo_log_work(issueKey, hours, date, description)
+1. plantuml_validate(code="@startuml...") ← Validate FIRST
+2. buffer_edit(bufferId, after=ID, plantuml="@startuml...")
+   → Auto-wraps in Confluence macro
 \`\`\`
+**Multiple diagrams?** See \`help(topic="plantuml")\` for direct macro embedding (fewer tool calls).
 
-### Get Worklogs
+### Search
 \`\`\`
-tempo_get_user_info() <- GET workerKey FIRST
-  -> tempo_get_worklogs(dateFrom, dateTo, workerKey)
-  WARNING: No workerKey = ALL worklogs (slow!)
+Confluence: confluence_search_content(cql="space=KEY AND text~\\"term\\"")
+Jira: jira_search_issues(jql="project=KEY AND type=Bug")
 \`\`\`
 
-### Epic Analysis
+### Tempo Time
 \`\`\`
-tempo_get_epic_worklogs(epicKey) [more efficient than Jira API]
+tempo_get_user_info() → workerKey
+tempo_get_worklogs(dateFrom, dateTo, workerKey=workerKey)
+tempo_log_work(issueKey, hours, date)
 \`\`\`
 
 ---
 
-## Buffer Patterns
-
-### Large Response
-\`\`\`
-[tool] returns bufferId when > 16KB
-  -> buffer_get_chunk(bufferId, offset, limit)
-  -> buffer_grep(bufferId, pattern) [search]
-\`\`\`
-
-### Edit Before Persist
-\`\`\`
-buffer_create(content) OR [tool that returns bufferId]
-  -> buffer_edit(bufferId, old, new)
-  -> buffer_get_chunk(bufferId, limit=50000)
-  -> confluence_draft_create(..., bufferId=bufferId)
-  -> User publishes via Confluence UI
-\`\`\`
-
----
+## Element ID System (Key Concept)
 
-## Utility Tools
+Every XHTML element gets a stable ID. Use IDs for precise positioning:
 
-### fullurl - Clickable Links (display only)
 \`\`\`
-fullurl("PROJ-123")  -> Jira URL
-fullurl("123456")    -> Confluence page URL
-\`\`\`
-WARNING: Never persist fullurl output to Jira/Confluence
+structure: [{id:1, type:"h1"}, {id:2, type:"p"}, {id:3, type:"ul"}]
 
-### workload_convert / workload_sum
-\`\`\`
-workload_convert(28800, "seconds") -> 8h, 1d
-workload_sum([...]) -> total in all units
+buffer_edit(bufferId, after=1, content="<p>New</p>")  → Insert after h1
+buffer_edit(bufferId, replace=2, content="<p>Updated</p>")  → Replace p
+buffer_edit(bufferId, remove=3)  → Delete ul
+buffer_edit(bufferId, append=true, plantuml="@startuml...")  → Add at end
 \`\`\`
 
----
-
-## Decision Tree
-
-| Need | Action |
-|------|--------|
-| Create page with diagram | \`help(topic="plantuml")\` then \`help(topic="storage")\` |
-| Create/update page | \`help(topic="storage")\` |
-| Search Confluence | \`help(topic="cql")\` |
-| Search Jira | \`jira_get_issue_types()\` then \`help(topic="jql")\` |
-| User's worklogs | \`tempo_get_user_info()\` first |
-| Write to Confluence | \`confluence_get_current_user_space()\` if restricted |
+**IDs are STABLE** - never change when content is inserted/deleted.
+See \`help(topic="buffers")\` for full details.
 `;
 // JQL syntax guide
 const JQL_HELP = `# JQL Syntax Guide
@@ -260,31 +175,25 @@ OK: (text~"term1" OR text~"term2") - Each term needs its own text~ operator
 - 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`;
-// Confluence storage format (unified)
-const STORAGE_FORMAT_HELP = `# Confluence Storage Format
+// Confluence storage format (XHTML syntax only)
+const STORAGE_FORMAT_HELP = `# Confluence Storage Format (XHTML)
 
-XHTML-based format. All tags must be closed (XML rules).
+All tags must be closed (XML rules). For editing workflow, see \`help(topic="buffers")\`.
 
-## Workflows
+## CRITICAL: CDATA Usage
 
-### Create Page
-\`\`\`
-confluence_draft_create(spaceKey, title, content) -> draftId, bufferId, url
-[user previews via url]
-buffer_edit_xhtml(bufferId, ...) [repeat as needed]
-confluence_draft_save(draftId, bufferId) [checkpoint, returns new draftId and url]
-[user publishes via Confluence UI]
-\`\`\`
+**NEVER wrap content in \`<![CDATA[...]]>\`**
 
-### Update Page
-\`\`\`
-confluence_get_page(pageId) -> bufferId
-buffer_edit_xhtml(bufferId, ...) or buffer_edit(bufferId, old, new)
-confluence_draft_create(spaceKey, title, bufferId=bufferId) -> draftId, url
-[user publishes via Confluence UI]
-\`\`\`
+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>
 
----
+<!-- WRONG: CDATA wrapping content -->
+<![CDATA[<h1>Title</h1>]]>
+\`\`\`
 
 ## Basic Elements
 
@@ -293,18 +202,18 @@ confluence_draft_create(spaceKey, title, bufferId=bufferId) -> draftId, url
 | Paragraph | \`<p>text</p>\` |
 | Headings | \`<h1>\`...\`<h6>\` |
 | Bold/Italic | \`<strong>\`, \`<em>\` |
-| Code | \`<code>text</code>\` |
+| Code inline | \`<code>text</code>\` |
 | Link | \`<a href="url">text</a>\` |
-| List | \`<ul><li>item</li></ul>\` |
+| List | \`<ul><li>item</li></ul>\` or \`<ol>\` |
 
 ## Tables
 \`\`\`xml
 <table><tbody>
-  <tr><th>Header</th></tr>
-  <tr><td>Cell</td></tr>
+  <tr><th>Header1</th><th>Header2</th></tr>
+  <tr><td>Cell1</td><td>Cell2</td></tr>
 </tbody></table>
 \`\`\`
-Merge: \`colspan="2"\`, \`rowspan="2"\`
+Merge cells: \`colspan="2"\`, \`rowspan="2"\`
 
 ## Layouts
 \`\`\`xml
@@ -315,560 +224,320 @@ Merge: \`colspan="2"\`, \`rowspan="2"\`
   </ac:layout-section>
 </ac:layout>
 \`\`\`
-Types: single, two_equal, two_left_sidebar, two_right_sidebar, three_equal
+Types: \`single\`, \`two_equal\`, \`two_left_sidebar\`, \`two_right_sidebar\`, \`three_equal\`
 
 ## Page Links
 \`\`\`xml
-<ac:link><ri:page ri:content-title="Page"/>
-  <ac:plain-text-link-body><![CDATA[text]]></ac:plain-text-link-body>
+<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"\`
+Cross-space: add \`ri:space-key="KEY"\` to ri:page
 
 ## Images
 \`\`\`xml
-<ac:image ac:width="300"><ri:attachment ri:filename="img.png"/></ac:image>
-<ac:image><ri:url ri:value="https://..."/></ac:image>
+<ac:image ac:width="300"><ri:attachment ri:filename="image.png"/></ac:image>
+<ac:image><ri:url ri:value="https://example.com/img.png"/></ac:image>
 \`\`\`
 
 ## Task List
 \`\`\`xml
 <ac:task-list>
-  <ac:task>
-    <ac:task-status>incomplete</ac:task-status>
-    <ac:task-body>Todo</ac:task-body>
-  </ac:task>
+  <ac:task><ac:task-status>incomplete</ac:task-status><ac:task-body>Todo item</ac:task-body></ac:task>
 </ac:task-list>
 \`\`\`
 
----
-
-## Structure Editing (buffer_edit_xhtml)
-
-CSS-like selectors to target elements:
-- Tag: \`p\`, \`table\`, \`h1\`
-- Namespaced: \`ac:structured-macro\`, \`ri:page\`
-- Attribute: \`[ac:name="plantuml"]\`, \`ac:structured-macro[ac:name="code"]\`
-- Pseudo: \`:nth-child(2)\`, \`:first-child\`, \`:last-child\`
-- Descendant: \`table tbody tr\`
-- Direct child: \`ul > li\`
-
-### Operations
-
-| Op | Use | Required params |
-|----|-----|-----------------|
-| insert | Add element | selector, position, content |
-| update | Change content/attrs | selector, content or attributes |
-| remove | Delete element | selector |
-| move | Relocate element | selector, targetSelector, position |
-| wrap | Wrap with parent | selector, content |
-| insert-plantuml | Add diagram | selector, position, plantuml |
-| update-plantuml | Edit diagram | selector, plantuml |
-
-Positions: \`before\`, \`after\`, \`inside-start\`, \`inside-end\`
-
-### Examples
-
-**Add row to table:**
-\`\`\`
-buffer_edit_xhtml(bufferId,
-  operation="insert",
-  selector="table tbody tr:last-child",
-  position="after",
-  content="<tr><td>New</td><td>Row</td></tr>")
-\`\`\`
-
-**Update heading:**
-\`\`\`
-buffer_edit_xhtml(bufferId,
-  operation="update",
-  selector="h1",
-  content="<h1>New Title</h1>")
+## Emoticons
+\`\`\`xml
+<ac:emoticon ac:name="tick"/>  <!-- tick, cross, warning, information -->
+<ac:emoticon ac:name="thumbs-up"/>  <!-- thumbs-up/down, plus, minus -->
 \`\`\`
 
-**Insert PlantUML (auto-validates + wraps in macro):**
-\`\`\`
-buffer_edit_xhtml(bufferId,
-  operation="insert-plantuml",
-  selector="h2:first-child",
-  position="after",
-  plantuml="@startuml\\nA -> B: msg\\n@enduml")
+## Code Block Macro
+\`\`\`xml
+<ac:structured-macro ac:name="code" ac:schema-version="1">
+  <ac:parameter ac:name="language">python</ac:parameter>
+  <ac:plain-text-body><![CDATA[def hello(): pass]]></ac:plain-text-body>
+</ac:structured-macro>
 \`\`\`
 
-**Remove element:**
-\`\`\`
-buffer_edit_xhtml(bufferId,
-  operation="remove",
-  selector="ac:structured-macro[ac:name=\\"toc\\"]")
+## Info/Warning Panels
+\`\`\`xml
+<ac:structured-macro ac:name="info" ac:schema-version="1">
+  <ac:rich-text-body><p>Info message</p></ac:rich-text-body>
+</ac:structured-macro>
 \`\`\`
+Types: \`info\`, \`note\`, \`warning\`, \`tip\`
 
-Options: \`matchIndex=N\` (0-based) or \`matchAll=true\` for multiple matches`;
-// PlantUML syntax guide
-const PLANTUML_HELP = `# PlantUML in Confluence - Syntax Guide
-
-## PlantUML Workflow
-
-PlantUML diagrams must be inserted using \`buffer_edit_xhtml\` with the \`insert-plantuml\` operation.
-Raw @startuml blocks in content are not supported.
-
-### Required Workflow
-\`\`\`
-1. Create XHTML content (WITHOUT PlantUML)
-2. plantuml_validate(code="@startuml...") <- Validate syntax first
-3. buffer_edit_xhtml(bufferId, operation="insert-plantuml", plantuml=code, semanticPosition="...")
-4. confluence_draft_create/save(bufferId)
-5. User publishes via Confluence UI
-\`\`\`
+## Macro Rules
 
-### Example
-\`\`\`
-buffer_edit_xhtml(bufferId,
-  operation="insert-plantuml",
-  semanticPosition="after-title",
-  plantuml="@startuml\\nA -> B\\n@enduml")
-\`\`\`
-Validation happens automatically during insertion.
+| 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 |
 
 ---
 
-## PlantUML Tools (Docker-based)
+For element ID editing workflow, see \`help(topic="buffers")\`.
+For PlantUML diagrams, see \`help(topic="plantuml")\`.`;
+// PlantUML syntax guide (Confluence-specific only - LLMs know PlantUML syntax)
+const PLANTUML_HELP = `# PlantUML in Confluence
 
-### Validation
-\`\`\`
-plantuml_validate(code="@startuml\\nA -> B: msg\\n@enduml")
+## Workflow
 \`\`\`
-Returns: \`valid\`, \`diagramType\`, \`errors\` with line numbers.
-Docker container starts automatically on first use.
-
-**Example Error Response:**
-\`\`\`json
-{
-  "valid": false,
-  "diagramType": "sequence",
-  "errors": [{"line": 3, "message": "Syntax error: unknown arrow type"}]
-}
+1. plantuml_validate(code="@startuml...@enduml")  ← Validate FIRST
+2. buffer_edit(bufferId, after=ID, plantuml="@startuml...@enduml")
+   → Auto-wraps in Confluence macro, auto-validates
+3. confluence_draft_save(draftId, bufferId)
 \`\`\`
 
-### Rendering
-\`\`\`
-plantuml_render(code="...", format="ascii|svg|png|eps")
-\`\`\`
-Returns: rendered content (ASCII/SVG inline, PNG/EPS as base64).
-Large renders return \`bufferId\` for retrieval.
-
-### Status
-\`\`\`
-plantuml_status()
-\`\`\`
-Returns: whether Docker container is running.
-
----
-
-## Insert PlantUML with Semantic Positions
-
-Use \`buffer_edit_xhtml\` with \`semanticPosition\` for easy insertion:
-
-\`\`\`
-buffer_edit_xhtml(bufferId,
-  operation="insert-plantuml",
-  semanticPosition="after-title",  // No selector needed!
-  plantuml="@startuml\\nA -> B\\n@enduml")
-\`\`\`
+## Tools
 
-**Semantic positions:**
-- \`after-title\`: After first h1 or h2
-- \`after-heading\`: After first heading (h1-h6)
-- \`before-content\`: At document start
-- \`end\`: At document end
-- \`after-toc\`: After table of contents macro
-
----
-
-## Confluence Macro Structure
-
-PlantUML diagrams MUST use this exact XML structure:
+| Tool | Use |
+|------|-----|
+| \`plantuml_validate(code)\` | Check syntax before insert |
+| \`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="auto-generated">
+<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
-' Your diagram code here
+' diagram code
 @enduml
 ]]></ac:plain-text-body>
 </ac:structured-macro>
 \`\`\`
 
-**Required attributes:**
-- \`ac:name="plantuml"\` - Macro identifier
-- \`ac:schema-version="1"\` - Must be "1"
-- \`ac:macro-id\` - Any unique ID (use "auto-generated" or UUID)
-
-**Required parameter:**
-- \`atlassian-macro-output-type=INLINE\` - Renders diagram inline
-
-**Required body:**
-- \`ac:plain-text-body\` with \`CDATA\` wrapping
-- Newline before \`@startuml\` marker
+## Critical Rules
 
----
-
-## Choosing the Right Diagram
-
-| Diagram | Use When |
-|---------|----------|
-| Sequence | API calls, request/response flows, message exchanges between systems |
-| Class | Data models, entity relationships, object structures |
-| Activity | Workflows, business processes, decision trees, algorithms |
-| Component | System architecture, module dependencies, deployment structure |
-| State | Lifecycle states, status transitions, finite state machines |
-| Use Case | User requirements, system features, actor interactions |
-| Context (C4) | High-level system overview, external dependencies |
-| Container (C4) | Application architecture, runtime components |
-| Component (C4) | Internal structure of a container/service |
+1. **Always validate first**: \`plantuml_validate(code)\` before inserting
+2. **Use plantuml parameter**: \`buffer_edit(..., plantuml="...")\` not \`content\`
+3. **Include markers**: Always use \`@startuml\` and \`@enduml\`
 
----
+## Stdlib Includes (C4, AWS, Azure)
 
-## Diagram Types
+C4-PlantUML, AWS icons, and Azure diagrams are supported via \`!include\`:
 
-### Sequence Diagram
-**Use for:** API call flows, request/response interactions, message exchanges, authentication flows
 \`\`\`
 @startuml
-participant Alice
-participant Bob
-
-Alice -> Bob: Request
-Bob --> Alice: Response
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+Person(user, "User")
+System(sys, "My System")
+Rel(user, sys, "Uses")
 @enduml
 \`\`\`
 
-### Class Diagram
-**Use for:** Data models, entity relationships, database schemas, object structures
-\`\`\`
-@startuml
-class User {
-  +id: string
-  +name: string
-  +login(): boolean
-}
+**Supported URL prefixes (whitelisted):**
+- \`https://raw.githubusercontent.com/plantuml-stdlib/\` - C4, Azure, Kubernetes, etc.
+- \`https://raw.githubusercontent.com/plantuml/\` - Official PlantUML stdlib
+- \`https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/\` - AWS icons
 
-class Order {
-  +items: Item[]
-  +total(): number
-}
+**Include files are expanded client-side** before validation and Confluence upload.
 
-User "1" --> "*" Order : places
-@enduml
-\`\`\`
+## Quick Examples
 
-### Activity Diagram
-**Use for:** Workflows, business processes, decision trees, algorithms, approval flows
+**Sequence:**
 \`\`\`
 @startuml
-start
-:Initialize;
-if (Valid?) then (yes)
-  :Process;
-else (no)
-  :Reject;
-endif
-stop
+Alice -> Bob: Request
+Bob --> Alice: Response
 @enduml
 \`\`\`
 
-### Component Diagram
-**Use for:** System architecture, module dependencies, package structure, deployment topology
+**Class:**
 \`\`\`
 @startuml
-package "Frontend" {
-  [Web App]
-  [Mobile App]
-}
-
-package "Backend" {
-  [API Server]
-  [Database]
-}
-
-[Web App] --> [API Server]
-[Mobile App] --> [API Server]
-[API Server] --> [Database]
+class User { +name: string }
+class Order
+User --> Order
 @enduml
 \`\`\`
 
-### State Diagram
-**Use for:** Object lifecycle, status transitions, order states, ticket workflows
+**C4 Context Diagram:**
 \`\`\`
 @startuml
-[*] --> Draft
-Draft --> Review : submit
-Review --> Approved : approve
-Review --> Draft : reject
-Approved --> Published : publish
-Published --> [*]
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+Person(user, "Customer", "Uses the system")
+System(sys, "E-Commerce", "Online store")
+System_Ext(pay, "Payment Gateway", "Processes payments")
+Rel(user, sys, "Shops")
+Rel(sys, pay, "Pays via")
 @enduml
 \`\`\`
 
-### Use Case Diagram
-**Use for:** User requirements, feature overview, actor roles, system boundaries
-\`\`\`
-@startuml
-actor User
-actor Admin
-
-rectangle System {
-  usecase "Login" as UC1
-  usecase "View Data" as UC2
-  usecase "Manage Users" as UC3
-}
+## Supported Diagram Types
 
-User --> UC1
-User --> UC2
-Admin --> UC1
-Admin --> UC3
-@enduml
-\`\`\`
+| Type | Marker | Use Case |
+|------|--------|----------|
+| **sequence** | \`@startuml\` | API flows, service interactions, request/response |
+| **class** | \`@startuml\` | OOP design, data models, inheritance |
+| **activity** | \`@startuml\` | Workflows, business processes, flowcharts |
+| **state** | \`@startuml\` | State machines, lifecycle, status transitions |
+| **component** | \`@startuml\` | System architecture, modules, dependencies |
+| **usecase** | \`@startuml\` | User stories, actors, requirements |
+| **object** | \`@startuml\` | Instance diagrams, runtime snapshots |
+| **deployment** | \`@startuml\` | Infrastructure, nodes, servers, containers |
+| **timing** | \`@startuml\` | Time-based signals, hardware timing |
+| **c4** | \`@startuml\` + \`!include C4_*.puml\` | C4 Model (requires stdlib include) |
+| **mindmap** | \`@startmindmap\` | Brainstorming, hierarchical ideas |
+| **gantt** | \`@startgantt\` | Project schedules, timelines |
+| **wbs** | \`@startwbs\` | Work Breakdown Structure, task hierarchy |
+| **json** | \`@startjson\` | JSON data visualization |
+| **yaml** | \`@startyaml\` | YAML data visualization |
 
----
+**Note**: C4 diagrams require \`!include\` to load the C4 library. Use \`C4_Context.puml\`, \`C4_Container.puml\`, \`C4_Component.puml\`, or \`C4_Dynamic.puml\` from plantuml-stdlib.
 
-## C4-Style Architecture Diagrams
+## Troubleshooting
 
-C4-style diagrams for architecture documentation. These use native PlantUML syntax (no external includes required).
+| Error | Fix |
+|-------|-----|
+| "PlantUML syntax error" | Run \`plantuml_validate\` first |
+| "Element not found" | Check \`buffer_get_structure\` for valid IDs |
+| "XHTML invalid" | Create fresh buffer, insert diagram |
 
-### Context Diagram
-**Use for:** High-level system overview, stakeholders, external dependencies, system boundaries
-\`\`\`
-@startuml
-title System Context
-
-skinparam rectangle {
-  BackgroundColor<<person>> #08427B
-  FontColor<<person>> white
-  BackgroundColor<<system>> #1168BD
-  FontColor<<system>> white
-  BackgroundColor<<external>> #999999
-  FontColor<<external>> white
-}
+## Advanced: Direct Macro Embedding
 
-rectangle "User" <<person>> as user
-rectangle "My System" <<system>> as system
-rectangle "External API" <<external>> as external
+For pages with **multiple diagrams**, reduce tool calls by embedding macros directly:
 
-user --> system : Uses
-system --> external : Calls API
-@enduml
 \`\`\`
-
-### Container Diagram
-**Use for:** Application architecture, runtime components, technology choices, data stores
+1. plantuml_validate(code) × N   ← Validate ALL diagrams first (parallel)
+2. buffer_create with embedded macros:
 \`\`\`
-@startuml
-title Container Diagram
-
-skinparam rectangle {
-  BackgroundColor<<container>> #438DD5
-  FontColor<<container>> white
-  BackgroundColor<<database>> #438DD5
-  FontColor<<database>> white
-}
-
-actor "User" as user
 
-rectangle "My System" {
-  rectangle "Web App\\n[React]" <<container>> as web
-  rectangle "API Server\\n[Node.js]" <<container>> as api
-  database "Database\\n[PostgreSQL]" <<database>> as db
-}
-
-user --> web : Uses [HTTPS]
-web --> api : Calls [REST/JSON]
-api --> db : Reads/Writes [SQL]
-@enduml
+\`\`\`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>
 \`\`\`
 
-### Component Diagram
-**Use for:** Internal structure of a container, code organization, module responsibilities
 \`\`\`
-@startuml
-title API Components
-
-skinparam component {
-  BackgroundColor #85BBF0
-  BorderColor #5588BB
-}
-
-package "API Application" {
-  component "Auth Controller" as auth
-  component "User Controller" as userCtrl
-  component "User Service" as service
-  database "User Repository" as repo
-}
-
-auth --> service : Uses
-userCtrl --> service : Uses
-service --> repo : Queries
-@enduml
+3. confluence_draft_create(bufferId=...)
 \`\`\`
 
----
-
-## Common Styling
+**Benefit**: 3 diagrams = 5 calls (vs 8 with buffer_edit per diagram)
 
-### Colors and Themes
-\`\`\`
-@startuml
-skinparam backgroundColor #FEFEFE
-skinparam roundcorner 10
+For element ID editing: \`help(topic="buffers")\``;
+// Buffers help guide (canonical element ID reference)
+const BUFFERS_HELP = `# Buffer & Element ID Editing
 
-skinparam class {
-  BackgroundColor #E8F4FD
-  BorderColor #2196F3
-  ArrowColor #1976D2
-}
+## Element ID System (Key Concept)
 
-class Example
-@enduml
-\`\`\`
+Every XHTML element gets a **stable** ID. IDs never change when content is inserted/deleted.
 
-### Notes
-\`\`\`
-@startuml
-Alice -> Bob: Message
-note right: This is a note
-note over Alice, Bob: Shared note
-@enduml
 \`\`\`
-
-### Grouping
+confluence_get_page(pageId) → structure: [
+  { id: 1, type: "h1", text: "Title" },
+  { id: 2, type: "h2", text: "Section" },
+  { id: 3, type: "p", text: "Paragraph..." },
+  { id: 4, type: "plantuml", text: "Diagram" }
+]
 \`\`\`
-@startuml
-box "Service A" #LightBlue
-  participant A1
-  participant A2
-end box
-
-box "Service B" #LightGreen
-  participant B1
-end box
 
-A1 -> B1: Request
-@enduml
-\`\`\`
+## buffer_edit Operations (XHTML)
 
----
+| Operation | Example | Result |
+|-----------|---------|--------|
+| Insert after | \`after=2, content="<p>New</p>"\` | New element after h2, gets id=5 |
+| Insert before | \`before=3, content="<p>New</p>"\` | New element before paragraph |
+| Replace | \`replace=4, plantuml="@startuml..."\` | Replaces diagram, keeps id=4 |
+| Remove | \`remove=3\` | Deletes paragraph |
+| Append | \`append=true, content="<p>End</p>"\` | Adds at document end |
 
-## Common Pitfalls
+**Content options:** \`content="<xhtml>"\` or \`plantuml="@startuml..."\`
 
-**Avoid:**
-- Missing \`ac:schema-version="1"\`
-- Using \`ac:rich-text-body\` instead of \`ac:plain-text-body\`
-- No CDATA wrapper around diagram code
-- No newline before \`@startuml\`
-- Missing \`@startuml\`/\`@enduml\` markers
+## Batch Operations (Efficient)
 
-**Always:**
-- Use exact macro structure shown above
-- Wrap diagram code in CDATA
-- Include \`atlassian-macro-output-type=INLINE\` parameter
-- Start with \`@startuml\` and end with \`@enduml\`
+For multiple edits, use \`operations\` array - **much faster** than multiple calls:
 
----
-
-## IMPORTANT: External Includes NOT Supported
-
-**Never use external !include statements:**
 \`\`\`
-!include https://raw.githubusercontent.com/...  <-- NOT SUPPORTED
+buffer_edit(bufferId, operations=[
+  { after: 6, plantuml: "@startuml...@enduml" },
+  { after: 8, plantuml: "@startuml...@enduml" },
+  { after: 10, content: "<p>New paragraph</p>" },
+  { remove: 12 }
+])
 \`\`\`
 
-Confluence's PlantUML plugin cannot fetch external URLs.
-Use native PlantUML syntax instead (see C4-Style examples above).
-
----
-
-## Full Example
-
-Complete Confluence storage format for a sequence diagram:
-
-\`\`\`xml
-<ac:structured-macro ac:name="plantuml" ac:schema-version="1" ac:macro-id="diagram-1">
-  <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
-  <ac:plain-text-body><![CDATA[
-@startuml
-skinparam backgroundColor #FEFEFE
+**Benefits:**
+- Parse once, serialize once (vs N times for N calls)
+- Single tool call (reduces latency)
+- All insertedIds returned together
+- Operations execute sequentially; stops on first error
 
-participant "Client" as C
-participant "Server" as S
-database "Database" as DB
+## Complete Workflow
 
-C -> S: POST /api/data
-S -> DB: INSERT
-DB --> S: OK
-S --> C: 201 Created
-@enduml
-]]></ac:plain-text-body>
-</ac:structured-macro>
 \`\`\`
+1. confluence_get_page(pageId) OR confluence_draft_create(...)
+   → bufferId, structure
 
----
-
-## Troubleshooting PlantUML Insertion
+2. buffer_edit(bufferId, after=2, content="<p>Added</p>")
+   → { insertedIds: [5], structure: [...] }
 
-### If insert-plantuml fails:
+3. buffer_edit(bufferId, after=5, plantuml="@startuml...")
+   → { insertedIds: [6], structure: [...] }
 
-1. **Validate diagram first:**
-   \`\`\`
-   plantuml_validate(code="@startuml\\n...\\n@enduml")
-   \`\`\`
-   Fix any errors before retrying insertion.
+4. confluence_draft_save(draftId, bufferId)
+   → url for preview
+\`\`\`
 
-2. **Check buffer content:**
-   \`\`\`
-   buffer_get_chunk(bufferId, limit=5000)
-   buffer_validate_xhtml(bufferId)
-   \`\`\`
+## Other Buffer Tools
 
-3. **Ask user about placement:**
-   If semantic position fails, ASK the user where they want the diagram.
-   Do NOT automatically add diagrams at "end" - wrong placement is worse than no placement.
+| Tool | Use |
+|------|-----|
+| \`buffer_get_structure(bufferId)\` | View current element IDs |
+| \`buffer_get_element(bufferId, elementId)\` | Get raw XHTML of specific element |
+| \`buffer_get_chunk(bufferId, offset, limit)\` | Read content in chunks |
+| \`buffer_grep(bufferId, pattern, "-C"=2)\` | Search with context |
+| \`buffer_validate_xhtml(bufferId)\` | Check XHTML validity |
+| \`buffer_list()\` | See all active buffers |
+| \`buffer_clear(bufferId)\` | Delete buffer |
 
-4. **Insert diagrams one at a time:**
-   Validate after each insertion before adding more.
+## Plain/JSON Editing (non-XHTML)
 
-5. **If XHTML parsing error persists:**
-   - Create a new buffer with simpler content
-   - Insert diagram into the fresh buffer
-   - Build up complexity gradually
+\`\`\`
+buffer_edit(bufferId, old_string="foo", new_string="bar", replace_all=true)
+\`\`\`
 
-### Common Errors and Fixes:
+## Common Errors & Recovery
 
-| Error | Cause | Fix |
-|-------|-------|-----|
-| "PlantUML syntax error" | Invalid diagram code | Use plantuml_validate first |
-| "Could not resolve semantic position" | Document structure issue | Ask user for placement |
-| "Resulting XHTML is invalid" | Corrupted buffer | Create new buffer, restart |
-| "No elements match selector" | Wrong selector | Ask user for correct selector |
+| Error | Fix |
+|-------|-----|
+| "Element not found: N" | Check \`buffer_get_structure\` for valid IDs |
+| "Buffer expired" | Re-fetch content, buffers expire in 10 min |
+| Multiple occurrences | Use \`replace_all=true\` for string edit |
+| XHTML parsing error | Check \`suggestedActions\` in error response |
 
-### Recovery Workflow:
+**XHTML Error Recovery**: When \`confluence_draft_create/save\` fails with an XHTML error:
+1. Error response includes \`errorLocation\` (element ID) and \`suggestedActions\`
+2. Use \`buffer_get_element(bufferId, elementId)\` to inspect problematic element
+3. Use \`buffer_edit(bufferId, replace=elementId, content="...")\` to fix
 
-If you see repeated errors, reset and try this sequence:
-\`\`\`
-1. plantuml_validate(code=diagram) <- Validate diagram syntax FIRST
-2. ASK the user: "The diagram placement failed. Where would you like it inserted?"
-3. buffer_create(content=simpleXhtml) <- Fresh buffer with minimal XHTML
-4. buffer_edit_xhtml(operation="insert-plantuml", selector=userChoice, plantuml=diagram)
-5. buffer_validate_xhtml(bufferId) <- Verify result
-6. confluence_draft_create(spaceKey, title, bufferId=bufferId)
-\`\`\`
+## Tips
 
-IMPORTANT: Never claim diagrams were added if insertion failed. Check contentSummary.plantumlDiagrams in the response.`;
+- 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)
+- XHTML syntax: \`help(topic="storage")\`
+- PlantUML: \`help(topic="plantuml")\``;
 // Topic content map
 const TOPIC_CONTENT = {
     jql: JQL_HELP,
     cql: CQL_HELP,
     storage: STORAGE_FORMAT_HELP,
     plantuml: PLANTUML_HELP,
+    buffers: BUFFERS_HELP,
 };
 export function createJiconHelpTools() {
     return {
@@ -881,18 +550,19 @@ With topic: Returns detailed syntax guide.
 Available topics:
 - jql: JQL (Jira Query Language) syntax
 - cql: CQL (Confluence Query Language) syntax
-- storage: Confluence storage format + structure editing (buffer_edit_xhtml)
+- storage: Confluence storage format + structure editing (element IDs)
 - plantuml: PlantUML diagram syntax for Confluence
+- buffers: Buffer management and large response handling
 
 Examples:
   help() -> Workflow guide
   help(topic="storage") -> Confluence format guide
-  help(topic="plantuml") -> Diagram syntax guide`,
+  help(topic="buffers") -> Buffer management guide`,
             inputSchema: z.object({
                 topic: z
                     .enum(TOPICS)
                     .optional()
-                    .describe('Topic for detailed help: "jql", "cql", "storage", "plantuml"'),
+                    .describe('Topic for detailed help: "jql", "cql", "storage", "plantuml", "buffers"'),
             }),
             handler: async (args) => {
                 const { topic } = args;