@crypto512/jicon-mcp 1.0.4 → 1.1.1

package/TOOL_LIST.md

@@ -5,11 +5,11 @@ This document provides a comprehensive reference of all available tools in the J
 
 ## Summary
 
-**Total Tools**: 63
+**Total Tools**: 64
 - **Jira Tools**: 18 (13 read + 5 write)
 - **Confluence Tools**: 17 (11 read + 6 write)
 - **Tempo Tools**: 12 (9 read + 3 write)
-- **Buffer Tools**: 9
+- **Buffer Tools**: 10
 - **Workload Tools**: 2
 - **URL Tools**: 1
 - **Jicon Help Tools**: 1
@@ -273,7 +273,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 **Response includes**: `pageId`, `version`, `bufferId`, `contentSize`, metadata
 
-**Usage**: Content is always stored in buffer with `contentType: "xhtml"`. Use `buffer_edit_xhtml` to modify (required for XHTML buffers), then `confluence_draft_create` for user review.
+**Usage**: Content is stored in buffer with `contentType: "xhtml"` and returns `structure` with element IDs. Use `buffer_edit` with element IDs to modify, then `confluence_draft_create` for user review.
 
 ---
 
@@ -289,7 +289,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 **Response includes**: `pageId`, `version`, `bufferId`, `contentSize`, metadata
 
-**Usage**: Content is always stored in buffer with `contentType: "xhtml"`. Use `buffer_edit_xhtml` to modify (required for XHTML buffers), then `confluence_draft_create` for user review.
+**Usage**: Content is stored in buffer with `contentType: "xhtml"` and returns `structure` with element IDs. Use `buffer_edit` with element IDs to modify, then `confluence_draft_create` for user review.
 
 ---
 
@@ -428,7 +428,9 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 |-----------|------|----------|-------------|
 | draftId | string | ✓ | Draft page ID |
 
-**Response includes**: `draftId`, `bufferId`, `title`, `spaceKey`, `version`, `url`, `contentPreview`
+**Response includes**: `draftId`, `bufferId`, `structure` (element IDs), `title`, `spaceKey`, `version`, `url`, `contentPreview`
+
+**Usage**: Content is stored in buffer with element IDs. Use `buffer_edit` with element IDs (e.g., `after=2`, `replace=5`) to modify, then `confluence_draft_save` to checkpoint.
 
 ---
 
@@ -444,11 +446,11 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 | parentId | string | ✗ | Parent page ID |
 | labels | string[] | ✗ | Array of labels |
 
-**Response includes**: `draftId`, `bufferId`, `title`, `spaceKey`, `version`, `url` (clickable to preview)
+**Response includes**: `draftId`, `bufferId`, `structure` (element IDs), `title`, `spaceKey`, `version`, `url` (clickable to preview), `contentSummary`
 
-**PlantUML**: Raw @startuml blocks are not supported. Use `buffer_edit_xhtml` with `insert-plantuml` operation.
+**PlantUML**: Raw @startuml blocks are not supported. Use `buffer_edit` with `plantuml` parameter.
 
-**Workflow**: Create draft → Click URL to preview → Use `buffer_edit_xhtml` to modify (required for XHTML buffers) → Use `confluence_draft_save` to checkpoint
+**Workflow**: Create draft → returns `structure` with element IDs → Click URL to preview → Use `buffer_edit` with element IDs (e.g., `after=2`) → Use `confluence_draft_save` to checkpoint
 
 ---
 
@@ -462,11 +464,11 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 | bufferId | string | ✓ | Buffer ID with content to save |
 | title | string | ✗ | Optional new title |
 
-**PlantUML**: Raw @startuml blocks are not supported. Use `buffer_edit_xhtml` with `insert-plantuml` operation.
+**PlantUML**: Raw @startuml blocks are not supported. Use `buffer_edit` with `plantuml` parameter.
 
 **Note**: Due to Confluence API limitations, drafts cannot be updated. This tool deletes the old draft and creates a new one with updated content.
 
-**Response includes**: `previousDraftId`, `newDraftId`, `bufferId`, `title`, `url` (new clickable URL)
+**Response includes**: `previousDraftId`, `newDraftId`, `bufferId`, `structure` (element IDs), `title`, `url` (new clickable URL)
 
 ---
 
@@ -542,8 +544,8 @@ AND lastModified >= now("-30d")
 
 ### Workflow 3: Documentation Update
 1. `confluence_search_content` - Find existing page
-2. `confluence_get_page` - Read current content (returns bufferId with `contentType: "xhtml"`)
-3. `buffer_edit_xhtml` - Modify content locally (required for XHTML buffers)
+2. `confluence_get_page` - Read current content (returns bufferId with `structure` element IDs)
+3. `buffer_edit` - Modify content using element IDs (e.g., `after=2`, `replace=5`)
 4. `confluence_draft_create` - Create draft for user review
 5. User reviews draft at URL
 6. User publishes via Confluence UI (click "Publish" button)
@@ -559,9 +561,9 @@ AND lastModified >= now("-30d")
 6. `jira_link_issues` - Link related issues
 
 ### Workflow 5: Create Page via Draft
-1. `confluence_draft_create` - Create draft + buffer (with `contentType: "xhtml"`), get preview URL
+1. `confluence_draft_create` - Create draft + buffer with `structure` (element IDs), get preview URL
 2. Click URL to preview draft in browser
-3. `buffer_edit_xhtml` - Modify content locally (required for XHTML buffers)
+3. `buffer_edit` - Modify content using element IDs (e.g., `after=1`, `plantuml="..."`)
 4. `confluence_draft_save` - Checkpoint changes, get new URL
 5. Repeat steps 2-4 as needed
 6. User publishes via Confluence UI (click "Publish" button)
@@ -705,7 +707,7 @@ Large responses are buffered - use `buffer_get_chunk` or `buffer_grep` to access
 ---
 
 ### 11. tempo_get_user_info
-**Description**: Get current user info (workerKey, accountId, displayName)
+**Description**: Get current user info (workerKey, username, accountId, displayName)
 **Use Cases**: Get workerKey for filtering worklogs, verify authentication
 
 | Parameter | Type | Required | Description |
@@ -732,31 +734,51 @@ More efficient than `jira_get_total_worklogs` for Tempo instances. Large respons
 
 ---
 
-## Buffer Tools (9)
+## Buffer Tools (10)
 
 Buffer tools are used for local content management. All buffer operations are in-memory - write enforcement is on Jira/Confluence/Tempo tools.
 
-**XHTML Tools**: `buffer_edit_xhtml` and `buffer_validate_xhtml` provide structure-aware editing and validation for Confluence storage format content. XHTML validation is also automatically applied before any Confluence write operation.
+**XHTML Editing**: `buffer_edit` uses element IDs for precise positioning in XHTML content. Each element gets a unique ID when loaded - use `buffer_get_structure` to see them. `buffer_validate_xhtml` validates Confluence storage format. XHTML validation is also automatically applied before any Confluence write operation.
 
 ### 1. buffer_create
-**Description**: Create a new buffer with initial content
+**Description**: Create a new buffer with initial content. For XHTML, returns element structure with IDs.
 **Use Cases**: Draft new Confluence pages, prepare content before persisting
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | content | string | ✓ | Initial content for the buffer |
+| contentType | enum | ✓ | Content type: `"xhtml"` for Confluence, `"plain"` for text, `"json"` for data |
 | metadata | object | ✗ | Optional metadata to attach to the buffer |
 
-**Response includes**: `bufferId`, `totalSize`, `createdAt`, `expiresAt`, `metadata`, `message`
+**Response for XHTML includes**: `bufferId`, `structure` (element IDs), `nextId`, `contentType`, `totalSize`
+
+**Response for plain/json includes**: `bufferId`, `contentType`, `totalSize`, `createdAt`, `expiresAt`
+
+**CDATA Detection**: For XHTML content, the tool detects if content is incorrectly wrapped in `<![CDATA[...]]>` and returns a clear error. CDATA should only be used inside `<ac:plain-text-body>` elements (for code blocks and PlantUML), never around the entire content.
 
-**Example workflow for new page**:
+**Example workflow for new Confluence page**:
 ```typescript
-// 1. buffer_create({ content: "<h1>Title</h1><p></p>" }) -> returns bufferId
-// 2. buffer_edit({ bufferId, old_string: "<p></p>", new_string: "<p>Content</p>" })
+// 1. buffer_create({ content: "<h1>Title</h1><p>Intro</p>", contentType: "xhtml" })
+//    -> returns bufferId, structure: [{id:1, type:"h1", text:"Title"}, {id:2, type:"p", text:"Intro"}]
+// 2. buffer_edit({ bufferId, after: 1, content: "<p>New paragraph</p>" })
+//    -> inserts after h1, returns structure with new element id:3
 // 3. confluence_draft_create({ spaceKey, title, bufferId }) -> user reviews at URL
 // 4. User publishes via Confluence UI (click "Publish" button)
 ```
 
+**Multi-diagram optimization**: Embed PlantUML macros directly in initial content:
+```typescript
+// 1. plantuml_validate(...) for each diagram (can run in parallel)
+// 2. buffer_create({ contentType: "xhtml", content: `
+//      <h1>Design</h1>
+//      <ac:structured-macro ac:name="plantuml" ac:schema-version="1" ac:macro-id="d1">
+//        <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
+//        <ac:plain-text-body><![CDATA[@startuml...@enduml]]></ac:plain-text-body>
+//      </ac:structured-macro>` })
+// 3. confluence_draft_create({ spaceKey, title, bufferId })
+// Saves tool calls vs placeholder-then-edit pattern. See help(topic="plantuml").
+```
+
 ---
 
 ### 2. buffer_get_chunk
@@ -773,7 +795,38 @@ Buffer tools are used for local content management. All buffer operations are in
 
 ---
 
-### 3. buffer_list
+### 3. buffer_get_element
+**Description**: Get the raw XHTML content of a specific element by ID. Use to inspect problematic elements when fixing XHTML parsing errors.
+**Use Cases**: Debug XHTML validation errors, inspect element content before editing, targeted error recovery
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID containing XHTML content |
+| elementId | number | ✓ | Element ID from buffer structure |
+
+**Response includes**: `bufferId`, `elementId`, `elementType`, `lineCount`, `content`
+
+**Example - Inspect problematic element after XHTML error:**
+```typescript
+// Error message indicates element ID 12 has issues
+buffer_get_element({
+  bufferId: "buf_xxx",
+  elementId: 12
+})
+// Returns: {
+//   bufferId: "buf_xxx",
+//   elementId: 12,
+//   elementType: "code",
+//   lineCount: 8,
+//   content: "<ac:structured-macro ac:name=\"code\">..."
+// }
+```
+
+**Tip**: When `confluence_draft_create` or `confluence_draft_save` fails with an XHTML error, the error response includes `suggestedActions` with a `buffer_get_element` call to inspect the problematic element.
+
+---
+
+### 4. buffer_list
 **Description**: List all active buffers with their metadata
 **Use Cases**: View active buffers, check expiration times
 
@@ -785,7 +838,7 @@ Buffer tools are used for local content management. All buffer operations are in
 
 ---
 
-### 4. buffer_clear
+### 5. buffer_clear
 **Description**: Clear a specific buffer or all buffers
 **Use Cases**: Free up memory, clean up after processing
 
@@ -797,7 +850,7 @@ Buffer tools are used for local content management. All buffer operations are in
 
 ---
 
-### 5. buffer_grep
+### 6. buffer_grep
 **Description**: Search buffered content for patterns (regex supported)
 **Use Cases**: Find specific content in large responses, locate text for editing
 
@@ -816,9 +869,33 @@ Buffer tools are used for local content management. All buffer operations are in
 
 ---
 
-### 6. buffer_edit
-**Description**: Exact string replacement in buffered content
-**Use Cases**: Modify Jira/Tempo content, fix text in non-XHTML buffers
+### 7. buffer_edit
+**Description**: Edit buffer content. For XHTML: use element IDs (single or batch). For plain/json: use string replacement.
+**Use Cases**: Insert/replace/remove elements in Confluence pages, modify Jira/Tempo content
+
+**XHTML Parameters (single operation):**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID to modify |
+| after | number | ✗ | Insert after element with this ID |
+| before | number | ✗ | Insert before element with this ID |
+| replace | number | ✗ | Replace element with this ID |
+| remove | number | ✗ | Remove element with this ID |
+| append | boolean | ✗ | Append at document end |
+| content | string | ✗ | XHTML content to insert/replace |
+| plantuml | string | ✗ | PlantUML code (auto-wrapped in macro, validated) |
+
+**XHTML Batch Operations (multiple edits in one call):**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID to modify |
+| operations | array | ✓ | Array of `{after?, before?, replace?, append?, remove?, content?, plantuml?}` |
+
+**Batch operations** are executed sequentially, stopping on first error. Much more efficient than multiple tool calls (parse once, serialize once).
+
+**Plain/JSON Parameters (string replacement):**
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -827,67 +904,99 @@ Buffer tools are used for local content management. All buffer operations are in
 | new_string | string | ✓ | Replacement text |
 | replace_all | boolean | ✗ | Replace all occurrences (default: false) |
 
-**⚠️ XHTML Buffers Blocked**: This tool is **blocked** for Confluence content (`contentType: "xhtml"`). Use `buffer_edit_xhtml` instead for XHTML buffers.
+**Key Feature - Stable Element IDs**: Element IDs never change when content is inserted or deleted. After inserting between elements 2 and 3, element 3 keeps its ID - only the new element gets a new ID.
 
-**Note**: Fails if old_string is not unique (unless replace_all=true). Changes are in-memory only - call update API to persist.
+**XHTML Response includes**: `success`, `operationsCompleted`, `structure`, `nextId`, `insertedIds`, `diagramTypes`
 
-**Response includes**: `success`, `replacements`, `oldSize`, `newSize`
+**Plain/JSON Response includes**: `success`, `replacements`, `oldSize`, `newSize`
 
----
+**Example - Insert after heading:**
+```typescript
+buffer_edit({
+  bufferId: "buf_xxx",
+  after: 2,  // Insert after element with ID 2
+  content: "<p>New paragraph</p>"
+})
+// Returns: { success: true, insertedIds: [5], structure: [...], nextId: 6 }
+```
 
-### 7. buffer_edit_xhtml
-**Description**: Structure-aware XHTML editing for Confluence storage format
-**Use Cases**: Add table rows, insert PlantUML diagrams, update macros, manipulate page structure
+**Example - Insert PlantUML diagram:**
+```typescript
+buffer_edit({
+  bufferId: "buf_xxx",
+  after: 3,
+  plantuml: "@startuml\nA -> B: message\n@enduml"
+})
+// Automatically validates and wraps in Confluence macro
+```
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| bufferId | string | ✓ | Buffer ID containing XHTML content |
-| operation | string | ✓ | Operation: insert, insert-plantuml, update, update-plantuml, remove, move, wrap |
-| selector | string | ✓ | CSS-like selector for target element(s) |
-| position | string | insert/move | Position: before, after, inside-start, inside-end |
-| content | string | insert/update/wrap | XHTML content for the operation |
-| plantuml | string | plantuml ops | Raw PlantUML code (auto-wrapped and validated) |
-| macroId | string | ✗ | Custom macro ID for PlantUML |
-| attributes | object | update | Attributes to set on element |
-| targetSelector | string | move | Target element for move operation |
-| matchIndex | number | ✗ | Operate on Nth match (0-based) |
-| matchAll | boolean | ✗ | Apply to all matches (default: false) |
-| validate | boolean | ✗ | Validate result (default: true) |
-
-**Selector Syntax**:
-- Tag name: `p`, `table`, `h2`
-- Namespaced: `ac:structured-macro`, `ri:page`
-- Attribute: `[ac:name="plantuml"]`, `ac:structured-macro[ac:name="code"]`
-- Descendant: `table tbody tr`
-- Direct child: `ul > li`
-
-**Example - Add table row**:
+**Example - Batch operations (EFFICIENT for multiple diagrams):**
 ```typescript
-buffer_edit_xhtml({
+buffer_edit({
   bufferId: "buf_xxx",
-  operation: "insert",
-  selector: "table tbody tr",
-  matchIndex: -1,  // Last row
-  position: "after",
-  content: "<tr><td>New Cell</td></tr>"
+  operations: [
+    { after: 6, plantuml: "@startuml\nA -> B\n@enduml" },
+    { after: 8, plantuml: "@startuml\nclass User\n@enduml" },
+    { after: 10, content: "<p>Summary paragraph</p>" },
+    { remove: 12 }
+  ]
 })
+// Returns: { success: true, operationsCompleted: 4, insertedIds: [13, 14, 15], diagramTypes: ["sequence", "class"], structure: [...] }
+// Benefits: parse once, serialize once, single tool call vs 4 separate calls
 ```
 
-**Example - Insert PlantUML diagram**:
+**Example - Replace element:**
 ```typescript
-buffer_edit_xhtml({
+buffer_edit({
   bufferId: "buf_xxx",
-  operation: "insert-plantuml",
-  selector: "h2",
-  matchIndex: 0,
-  position: "after",
-  plantuml: "class User { +name: string }"
+  replace: 4,
+  content: "<p>Updated content</p>"
 })
 ```
 
+**Example - Remove element:**
+```typescript
+buffer_edit({
+  bufferId: "buf_xxx",
+  remove: 5
+})
+```
+
+---
+
+### 8. buffer_get_structure
+**Description**: Get current element structure for an XHTML buffer
+**Use Cases**: View element IDs for editing, understand document structure
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID to get structure for |
+
+**Response includes**: `bufferId`, `structure`, `nextId`
+
+**Structure Format**:
+```typescript
+structure: [
+  { id: 1, type: "h1", text: "Document Title" },
+  { id: 2, type: "h2", text: "Introduction" },
+  { id: 3, type: "p", text: "This section describes..." },
+  { id: 4, type: "plantuml", text: "Sequence diagram" },
+  { id: 5, type: "ul", children: 5 }  // List with 5 items
+]
+nextId: 6
+```
+
+**Element Types**: `h1`-`h6`, `p`, `ul`, `ol`, `table`, `plantuml`, `ac:structured-macro`, etc.
+
+**Example**:
+```typescript
+buffer_get_structure({ bufferId: "buf_xxx" })
+// Returns current element IDs for use with buffer_edit
+```
+
 ---
 
-### 8. buffer_validate_xhtml
+### 9. buffer_validate_xhtml
 **Description**: Validate buffered content as Confluence storage format (XHTML)
 **Use Cases**: Check content validity before writing, debug validation errors
 
@@ -907,7 +1016,7 @@ buffer_edit_xhtml({
 
 ---
 
-### 9. buffer_save_to_file
+### 10. buffer_save_to_file
 **Description**: Save buffer content to a file within the project directory
 **Use Cases**: Export rendered PlantUML diagrams (PNG/EPS), save edited content locally
 
@@ -1015,7 +1124,7 @@ Unified help system for all Jicon workflows and syntax guides. Always available
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| topic | string | ✗ | Topic for detailed help: jql, cql, storage, plantuml |
+| topic | string | ✗ | Topic for detailed help: jql, cql, storage, plantuml, buffers |
 
 **Default (no topic)**: Compact workflow guide with decision trees showing:
 - Confluence workflows (create page, update page, draft workflow, search)
@@ -1031,8 +1140,9 @@ Unified help system for all Jicon workflows and syntax guides. Always available
 |-------|-------------|
 | `jql` | JQL syntax guide - operators, functions, examples |
 | `cql` | CQL syntax guide - search operators, date functions |
-| `storage` | Confluence storage format + structure editing (buffer_edit_xhtml) |
+| `storage` | Confluence storage format + structure editing (element IDs) |
 | `plantuml` | PlantUML syntax for Confluence diagrams |
+| `buffers` | Buffer management and element ID editing guide |
 
 **Examples**:
 ```typescript
@@ -1040,6 +1150,7 @@ help()                       // Get workflow overview and decision tree
 help(topic="jql")            // JQL syntax guide
 help(topic="storage")        // Basic Confluence formatting
 help(topic="plantuml")       // PlantUML diagram syntax
+help(topic="buffers")        // Buffer management guide
 ```
 
 **Tip**: Start with `help()` to understand the overall workflow, then use specific topics for syntax details.
@@ -1050,11 +1161,17 @@ help(topic="plantuml")       // PlantUML diagram syntax
 
 Docker-based PlantUML validation and rendering. Requires Docker to be installed and running.
 
-**⚠️ External Includes NOT Supported:**
+**Docker Lifecycle**:
+- Container starts **at MCP server startup** (not lazily on first use)
+- Does **NOT auto-restart** if container stops - restart MCP server to retry
+- Use `"disableDocker": true` in `.jicon.json` to skip PlantUML entirely
+
+**Stdlib Includes (C4, AWS, Azure):**
 ```
-!include https://raw.githubusercontent.com/...  ← NOT SUPPORTED
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+!include https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/main/dist/AWSCommon.puml
 ```
-Confluence's PlantUML plugin cannot fetch external URLs. Use native PlantUML syntax instead of C4 includes. See `help(topic="plantuml")` for examples.
+Include expansion is enabled by default. Whitelisted URLs: `plantuml-stdlib/*`, `plantuml/*`, `awslabs/aws-icons-for-plantuml/*`. See `help(topic="plantuml")` for examples.
 
 ### 1. plantuml_validate
 **Description**: Validate PlantUML diagram syntax using a real PlantUML server
@@ -1118,12 +1235,13 @@ buffer_save_to_file({
 |-----------|------|----------|-------------|
 | (none) | | | |
 
-**Response includes**: `running`, `port`, `containerId`, `message`
+**Response includes**: `available`, `disabled`, `startupFailed`, `containerDied`, `error`, `containerId`, `port`, `baseUrl`, `message`
 
-**Docker Lifecycle**:
-- Container starts automatically on first `plantuml_validate` or `plantuml_render` call
-- Uses dynamic port allocation (unique per MCP instance)
-- Stops gracefully on MCP server shutdown
+**Status States**:
+- `available: true` - Container running and healthy
+- `disabled: true` - Disabled via `disableDocker: true` config
+- `startupFailed: true` - Docker failed at MCP startup (check logs)
+- `containerDied: true` - Container stopped after startup (restart MCP)
 
 ---
 
@@ -1161,17 +1279,17 @@ Tools that return large content (Confluence pages, Jira issues, Tempo worklogs)
 ### Buffer Workflows
 
 **Creating new Confluence pages (draft workflow):**
-1. `confluence_draft_create` → creates server draft + buffer, returns clickable preview URL
+1. `confluence_draft_create` → creates server draft + buffer with `structure` (element IDs), returns clickable preview URL
 2. User clicks URL to review draft in Confluence UI (can edit there)
-3. If changes needed: `confluence_draft_open` → re-reads user's edits into buffer
-4. `buffer_edit_xhtml` → structure-aware editing (or `buffer_edit` for simple text)
+3. If changes needed: `confluence_draft_open` → re-reads user's edits into buffer with updated structure
+4. `buffer_edit` → edit using element IDs (e.g., `after=2`, `replace=5`, `plantuml="..."`)
 5. `confluence_draft_save` → checkpoint: deletes old draft, creates new with buffer content, returns new URL
 6. Repeat steps 2-5 until user approves
 7. User publishes via Confluence UI (click "Publish" button)
 
 **Editing existing Confluence pages (draft workflow):**
-1. `confluence_get_page` → page content is buffered, returns `bufferId`, `pageId`, and `version`
-2. `buffer_edit_xhtml` → structure-aware editing (tables, macros, layouts)
+1. `confluence_get_page` → page content is buffered, returns `bufferId`, `pageId`, `version`, and `structure`
+2. `buffer_edit` → edit using element IDs (e.g., `after=2`, `replace=5`, `plantuml="..."`)
 3. `confluence_draft_create` → creates draft with modified content for user review
 4. User reviews draft at URL
 5. If changes needed: repeat via `confluence_draft_open` → edit → `confluence_draft_save`
@@ -1184,68 +1302,72 @@ Tools that return large content (Confluence pages, Jira issues, Tempo worklogs)
 
 ### Buffer Content Types
 
-**Buffer types enforce the correct editing tool:**
+**Buffer types determine editing mode:**
 
-| Buffer Source | contentType | Editing Tool |
+| Buffer Source | contentType | Editing Mode |
 |---------------|-------------|--------------|
-| Confluence pages/drafts | `xhtml` | `buffer_edit_xhtml` (required) |
-| Jira issues | `json` | `buffer_edit` |
-| Other content | `plain` | `buffer_edit` |
+| Confluence pages/drafts | `xhtml` | `buffer_edit` with element IDs (`after`, `before`, `replace`, `remove`) |
+| Jira issues | `json` | `buffer_edit` with string replacement (`old_string`, `new_string`) |
+| Other content | `plain` | `buffer_edit` with string replacement (`old_string`, `new_string`) |
 
 **XHTML Buffers (Confluence content):**
 - Confluence tools automatically set `contentType: "xhtml"` on buffers
-- `buffer_edit` is **blocked** for XHTML buffers - use `buffer_edit_xhtml` instead
-- This ensures PlantUML validation and proper structure-aware editing
+- Returns `structure` with element IDs for precise editing
+- Use `buffer_get_structure` to view current element IDs
+- Element IDs are **stable** - they never change when content is inserted/deleted
 
 ### XHTML Structure Editing
 
-Use `buffer_edit_xhtml` for XML tree-aware editing of Confluence storage format content. This tool provides CSS-like selectors for targeting elements and supports PlantUML diagram insertion with automatic syntax validation.
+Use `buffer_edit` with element IDs for precise editing of Confluence storage format content. Each element gets a unique ID when loaded, which remains stable across edits.
 
-**Operations:**
+**Operations (use exactly one):**
 
-| Operation | Description |
+| Parameter | Description |
 |-----------|-------------|
-| `insert` | Add content relative to selected element |
-| `insert-plantuml` | Insert PlantUML diagram with validation and macro wrapping |
-| `update` | Update element content and/or attributes |
-| `update-plantuml` | Update existing PlantUML macro with validation |
-| `remove` | Delete selected element(s) |
-| `move` | Move element to new location |
-| `wrap` | Wrap element with new parent |
+| `after=ID` | Insert content after element with ID |
+| `before=ID` | Insert content before element with ID |
+| `replace=ID` | Replace element with ID |
+| `remove=ID` | Delete element with ID |
+| `append=true` | Append at document end |
 
-**Selector Syntax:**
+**Content Options (use exactly one for insert/replace):**
 
-```
-p                                    # Tag name
-ac:structured-macro                  # Namespaced element
-[ac:name="plantuml"]                 # Attribute selector
-ac:structured-macro[ac:name="code"]  # Combined tag + attribute
-table tbody tr                       # Descendant selector
-ul > li                              # Direct child selector
+| Parameter | Description |
+|-----------|-------------|
+| `content` | XHTML content to insert/replace |
+| `plantuml` | PlantUML code (auto-validated and wrapped in Confluence macro) |
+
+**Element Structure Example:**
+
+```typescript
+// Structure returned by buffer_create or buffer_get_structure:
+structure: [
+  { id: 1, type: "h1", text: "Document Title" },
+  { id: 2, type: "h2", text: "Architecture" },
+  { id: 3, type: "p", text: "This describes..." },
+  { id: 4, type: "plantuml", text: "Sequence diagram" },
+  { id: 5, type: "ul", children: 5 }
+]
+nextId: 6
 ```
 
-**Example - Add Table Row:**
+**Example - Insert paragraph after heading:**
 
 ```typescript
-buffer_edit_xhtml({
+buffer_edit({
   bufferId: "buf_xxx",
-  operation: "insert",
-  selector: "table tbody tr",
-  matchIndex: -1,  // Last row (use 0 for first)
-  position: "after",
-  content: "<tr><td>New Cell 1</td><td>New Cell 2</td></tr>"
+  after: 2,  // Insert after element ID 2 (h2)
+  content: "<p>New paragraph here</p>"
 })
+// Returns: { success: true, insertedIds: [6], structure: [...] }
 ```
 
 **Example - Insert PlantUML Diagram:**
 
 ```typescript
-buffer_edit_xhtml({
+buffer_edit({
   bufferId: "buf_xxx",
-  operation: "insert-plantuml",
-  selector: "h2",
-  matchIndex: 0,
-  position: "after",
+  after: 3,
   plantuml: `
     class User {
       +id: string
@@ -1259,28 +1381,27 @@ buffer_edit_xhtml({
 // and generates complete Confluence PlantUML macro
 ```
 
-**Position Values:**
-- `before` - Insert before the selected element
-- `after` - Insert after the selected element
-- `inside-start` - Insert as first child of selected element
-- `inside-end` - Insert as last child of selected element
+**Example - Replace element:**
 
-**Match Control:**
-- `matchIndex`: Operate on Nth match (0-based, use negative for reverse)
-- `matchAll`: Apply operation to all matches
+```typescript
+buffer_edit({
+  bufferId: "buf_xxx",
+  replace: 4,  // Replace element ID 4 (the plantuml)
+  plantuml: "@startuml\nA -> B: fixed\n@enduml"
+})
+```
 
-**Semantic Positions for PlantUML:**
+**Example - Remove element:**
 
 ```typescript
-buffer_edit_xhtml({
+buffer_edit({
   bufferId: "buf_xxx",
-  operation: "insert-plantuml",
-  semanticPosition: "after-title",  // No selector needed!
-  plantuml: "@startuml\nA -> B: message\n@enduml"
+  remove: 5  // Remove element ID 5 (the list)
 })
 ```
 
-Available: `after-title`, `after-heading`, `before-content`, `end`, `after-toc`
+**Key Feature - Stable IDs:**
+Element IDs never change when content is inserted or deleted. After inserting between IDs 2 and 3, element 3 keeps its ID - only the new element gets a new ID.
 
 ### XHTML Validation
 
@@ -1299,7 +1420,7 @@ buffer_validate_xhtml({
 - Required attributes on Confluence elements (ac:name, ri:space-key, etc.)
 - Valid layout section types
 - Known macro names (warnings for unknown macros)
-- PlantUML syntax (if Docker service is running)
+- PlantUML syntax (requires Docker - returns error if unavailable)
 
 **Automatic Validation:**
 XHTML content is automatically validated before Confluence writes (`confluence_draft_create`, `confluence_draft_save`).