@crypto512/jicon-mcp 1.1.0 → 1.2.0

package/TOOL_LIST.md

@@ -5,13 +5,13 @@ This document provides a comprehensive reference of all available tools in the J
 
 ## Summary
 
-**Total Tools**: 64
+**Total Tools**: 69
 - **Jira Tools**: 18 (13 read + 5 write)
-- **Confluence Tools**: 17 (11 read + 6 write)
+- **Confluence Tools**: 21 (13 read + 8 write)
 - **Tempo Tools**: 12 (9 read + 3 write)
 - **Buffer Tools**: 10
 - **Workload Tools**: 2
-- **URL Tools**: 1
+- **URL Tools**: 2
 - **Jicon Help Tools**: 1
 - **PlantUML Tools**: 3
 
@@ -247,7 +247,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-## Confluence Tools (17)
+## Confluence Tools (21)
 
 ### 1. confluence_search_content
 **Description**: Search Confluence content using CQL. Auto-fetches all results (up to 5000).
@@ -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 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.
+**Usage**: Content is stored in buffer with `contentType: "xhtml"` and returns `structure` with element IDs. Use `buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId)` to add content, then `confluence_draft_create(pageId, bufferId)` for user review.
 
 ---
 
@@ -289,18 +289,60 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 **Response includes**: `pageId`, `version`, `bufferId`, `contentSize`, metadata
 
-**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.
+**Usage**: Content is stored in buffer with `contentType: "xhtml"` and returns `structure` with element IDs. Use `buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId)` to add content, then `confluence_draft_create(pageId, bufferId)` for user review.
+
+---
+
+### 4. confluence_edit (RECOMMENDED)
+**Description**: Smart page/draft loader - auto-resolves URLs, pageIds, draftIds, or SPACE/Title
+**Use Cases**: Edit any Confluence content with a single tool, handle URL input from users
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| input | string | ✓ | URL, pageId, "draft:ID", or "SPACE/Title" |
+
+**Input formats supported**:
+| Input | Behavior |
+|-------|----------|
+| `https://confluence.example.com/pages/viewpage.action?pageId=123` | Parse URL, load page |
+| `https://confluence.example.com/pages/resumedraft.action?draftId=456` | Parse URL, try draft (fallback to page) |
+| `https://confluence.example.com/display/DOCS/Page+Title` | Parse URL, find by space/title |
+| `123456` (numeric) | Load page directly by ID |
+| `draft:123456` | Try draft; if 404 (published), find page by title |
+| `DOCS/API Guide` | Find page by space key and title |
+
+**Response includes**: `bufferId`, `structure`, `pageId` or `draftId`, `spaceKey`, `title`
+
+**Smart behavior**:
+- URLs are parsed automatically to extract pageId or draftId
+- Draft IDs: tries to load draft; if 404 (user published), finds page by title
+- Returns bufferId + structure for editing
+
+**Workflow**:
+```
+1. confluence_edit("URL or SPACE/Title") → bufferId, structure, pageId
+2. buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) → add content
+3. confluence_draft_create(pageId=..., bufferId=...) → draft for review (links to original page)
+4. User publishes via Confluence UI (updates original page)
+5. For more edits: confluence_edit(same input) → auto-resolves
+```
+
+**TIP**: If you created content in a separate buffer, use `fromBufferId` to merge it:
+```
+buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
+```
 
 ---
 
 > **Note**: All page content changes go through the draft workflow.
 > AI creates/edits drafts; user publishes manually via Confluence UI:
-> - New pages: `confluence_draft_create` → user review → user publishes
-> - Existing pages: `confluence_get_page` → edit → `confluence_draft_create` → user review → user publishes
+> - **Edit existing**: `confluence_edit(input)` → `buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId)` → `confluence_draft_create(pageId, bufferId)` → user publishes
+> - **Create new**: `confluence_draft_create(spaceKey, title, content)` → user review → user publishes
+> - **After publish**: Draft ID becomes invalid; use `confluence_edit("SPACE/Title")` to edit again
 
 ---
 
-### 4. confluence_delete_page
+### 5. confluence_delete_page
 **Description**: Delete a Confluence page
 **Use Cases**: Remove outdated content
 
@@ -310,7 +352,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-### 5. confluence_list_spaces
+### 6. confluence_list_spaces
 **Description**: List all accessible Confluence spaces
 **Use Cases**: Discover available spaces, get space keys
 
@@ -322,7 +364,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-### 6. confluence_get_space
+### 7. confluence_get_space
 **Description**: Get detailed information about a space
 **Use Cases**: View space details, get homepage
 
@@ -333,7 +375,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-### 7. confluence_get_page_children
+### 8. confluence_get_page_children
 **Description**: Get all child pages of a page
 **Use Cases**: Navigate page hierarchy, list subpages
 
@@ -346,7 +388,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-### 8. confluence_add_comment
+### 9. confluence_add_comment
 **Description**: Add a comment to a Confluence page
 **Use Cases**: Provide feedback, ask questions
 
@@ -357,7 +399,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-### 9. confluence_get_comments
+### 10. confluence_get_comments
 **Description**: Get all comments on a Confluence page
 **Use Cases**: Read feedback, review discussions
 
@@ -369,7 +411,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-### 10. confluence_upload_attachment
+### 11. confluence_upload_attachment
 **Description**: Upload an attachment to a Confluence page
 **Use Cases**: Attach documents, upload images
 
@@ -381,7 +423,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-### 11. confluence_list_attachments
+### 12. confluence_list_attachments
 **Description**: List all attachments on a Confluence page
 **Use Cases**: View uploaded files, check attachments
 
@@ -393,7 +435,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-### 12. confluence_get_current_user_space
+### 13. confluence_get_current_user_space
 **Description**: Get the current user's personal Confluence space
 **Use Cases**: Verify personal space before write operations, check space key for write-home restriction
 
@@ -407,7 +449,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-### 13. confluence_draft_list
+### 14. confluence_draft_list
 **Description**: List user's draft pages
 **Use Cases**: View pending drafts, find drafts to continue editing
 
@@ -420,7 +462,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-### 14. confluence_draft_open
+### 15. confluence_draft_open
 **Description**: Load existing draft into buffer for editing
 **Use Cases**: Continue editing a draft, prepare draft for publishing
 
@@ -430,31 +472,58 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 **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.
+**Usage**: Content is stored in buffer with element IDs. Use `buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId)` to modify, then `confluence_draft_save` to checkpoint.
 
 ---
 
-### 15. confluence_draft_create
-**Description**: Create a new server-side draft with local buffer
-**Use Cases**: Start new page as draft, iterative content development
+### 16. confluence_draft_create
+**Description**: Create a draft for user review - either a new page or as an edit to an existing page
+**Use Cases**: Start new page as draft, edit existing page through draft workflow
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| spaceKey | string | ✓ | Space key |
-| title | string | ✓ | Draft title |
-| content | string | ✓ | Initial content (storage format) |
-| parentId | string | ✗ | Parent page ID |
-| labels | string[] | ✗ | Array of labels |
+**Two Modes:**
 
-**Response includes**: `draftId`, `bufferId`, `structure` (element IDs), `title`, `spaceKey`, `version`, `url` (clickable to preview), `contentSummary`
+1. **NEW PAGE**: Create a standalone draft
+   | Parameter | Type | Required | Description |
+   |-----------|------|----------|-------------|
+   | spaceKey | string | ✓ | Space key |
+   | title | string | ✓ | Draft title |
+   | content/bufferId | string | ✓ | Content (storage format) or buffer ID |
+   | parentId | string | ✗ | Parent page ID |
+   | labels | string[] | ✗ | Array of labels |
+
+2. **EDIT EXISTING PAGE**: Create a draft to edit an existing page
+   | Parameter | Type | Required | Description |
+   |-----------|------|----------|-------------|
+   | pageId | string | ✓ | Existing page ID to edit |
+   | bufferId | string | ✓ | Buffer ID from `confluence_get_page(pageId)` or `confluence_edit(pageId)` |
+   | title | string | ✗ | Optional new title (defaults to original) |
+
+   **Important**: When `pageId` is provided, `bufferId` must originate from that page (validated). Space, title, and parent are auto-populated from the original page.
+
+**Response includes**: `draftId`, `bufferId`, `structure` (element IDs), `title`, `spaceKey`, `version`, `url` (clickable to preview), `contentSummary`, `editingExistingPage` (when editing)
 
 **PlantUML**: Raw @startuml blocks are not supported. Use `buffer_edit` with `plantuml` parameter.
 
-**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
+**Workflow for editing existing page**:
+```
+1. confluence_get_page(pageId) → bufferId, structure
+2. buffer_edit(bufferId, ...) → modify content
+3. confluence_draft_create(pageId=..., bufferId=...) → draft for review
+4. User reviews and publishes in Confluence UI (updates original page)
+```
+
+**Workflow for new page**:
+```
+1. confluence_draft_create(spaceKey, title, content) → draftId, bufferId, url
+2. User clicks URL to preview
+3. buffer_edit(bufferId, ...) → modify if needed
+4. confluence_draft_save(draftId, bufferId) → checkpoint
+5. User publishes via Confluence UI
+```
 
 ---
 
-### 16. confluence_draft_save
+### 17. confluence_draft_save
 **Description**: Save buffer content to draft (delete + recreate pattern)
 **Use Cases**: Checkpoint work, persist edits before publishing
 
@@ -472,7 +541,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
-### 17. confluence_draft_delete
+### 18. confluence_draft_delete
 **Description**: Permanently delete a draft
 **Use Cases**: Clean up abandoned drafts, remove unwanted content
 
@@ -484,6 +553,54 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 
 ---
 
+### 19. confluence_review_list
+**Description**: List all "[jicon-mcp REVIEW]" drafts for cleanup or management
+**Use Cases**: Find abandoned review drafts, manage multiple review workflows, clean up after publishing
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| spaceKey | string | ✗ | Filter by space key |
+
+**Response includes**: `reviewDrafts` array with `reviewDraftId`, `title`, `originalTitle`, `originalPageId`, `spaceKey`, `spaceName`, `createdDate`, `editUrl`; `total`, `message`
+
+**Note**: Review drafts are created when using `confluence_draft_create` with a `pageId` parameter to edit an existing page. They are linked to the original page via a label.
+
+---
+
+### 20. confluence_review_publish
+**Description**: Publish a review draft to apply changes to the original page
+**Use Cases**: Apply reviewed changes to the original page, complete the review workflow
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| reviewDraftId | string | ✓ | ID of the [jicon-mcp REVIEW] draft to publish |
+
+**Workflow**:
+1. Validates the draft is a "[jicon-mcp REVIEW]" draft with proper label
+2. Copies the draft content to the original page (creates new version)
+3. Deletes the review draft
+
+**Response includes**: `success`, `originalPageId`, `originalTitle`, `newVersion`, `reviewDraftDeleted`, `viewUrl`, `message`
+
+---
+
+### 21. confluence_review_discard
+**Description**: Discard a review draft without applying changes to the original page
+**Use Cases**: Cancel a review, abandon changes, clean up unwanted review drafts
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| reviewDraftId | string | ✓ | ID of the [jicon-mcp REVIEW] draft to discard |
+
+**Workflow**:
+1. Validates the draft is a "[jicon-mcp REVIEW]" draft
+2. Deletes the review draft permanently
+3. Original page remains unchanged
+
+**Response includes**: `success`, `discarded`, `reviewDraftId`, `originalTitle`, `message`
+
+---
+
 ## Query Language Reference
 
 ### JQL (Jira Query Language) Examples
@@ -766,17 +883,16 @@ Buffer tools are used for local content management. All buffer operations are in
 // 4. User publishes via Confluence UI (click "Publish" button)
 ```
 
-**Multi-diagram optimization**: Embed PlantUML macros directly in initial content:
+**Multi-diagram workflow**: Use batch operations with plantuml parameter:
 ```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>` })
+// 1. buffer_create({ contentType: "xhtml", content: "<h1>Design</h1><p>Introduction</p>" })
+// 2. buffer_edit({ bufferId, operations: [
+//      { after: 1, plantuml: "@startuml\nA -> B\n@enduml" },
+//      { after: 2, plantuml: "@startuml\nclass User\n@enduml" }
+//    ]})
+//    -> All PlantUML validated in batch before any changes, rolled back on error
 // 3. confluence_draft_create({ spaceKey, title, bufferId })
-// Saves tool calls vs placeholder-then-edit pattern. See help(topic="plantuml").
+// NOTE: Embedding PlantUML macros directly in content is NOT allowed - use plantuml parameter.
 ```
 
 ---
@@ -871,7 +987,7 @@ buffer_get_element({
 
 ### 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
+**Use Cases**: Insert/replace/remove elements in Confluence pages, modify Jira/Tempo content, compose content from multiple buffers
 
 **XHTML Parameters (single operation):**
 
@@ -883,15 +999,18 @@ buffer_get_element({
 | 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) |
+| content | string | ✗ | XHTML content to insert/replace (**NO PlantUML macros allowed**) |
+| plantuml | string | ✗ | PlantUML code (**REQUIRED** for diagrams - auto-validated and wrapped) |
+| fromBufferId | string | ✗ | Insert content from another buffer (useful for composing content) |
+
+**IMPORTANT**: The `content` parameter **rejects** PlantUML macros. All PlantUML must use the `plantuml` parameter for mandatory validation.
 
 **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?}` |
+| operations | array | ✓ | Array of `{after?, before?, replace?, append?, remove?, content?, plantuml?, fromBufferId?}` |
 
 **Batch operations** are executed sequentially, stopping on first error. Much more efficient than multiple tool calls (parse once, serialize once).
 
@@ -920,14 +1039,15 @@ buffer_edit({
 // Returns: { success: true, insertedIds: [5], structure: [...], nextId: 6 }
 ```
 
-**Example - Insert PlantUML diagram:**
+**Example - Insert PlantUML diagram (REQUIRED method):**
 ```typescript
 buffer_edit({
   bufferId: "buf_xxx",
   after: 3,
   plantuml: "@startuml\nA -> B: message\n@enduml"
 })
-// Automatically validates and wraps in Confluence macro
+// Automatically validates syntax, rejects invalid code, and wraps in Confluence macro
+// NOTE: Using content parameter with PlantUML macros will be REJECTED
 ```
 
 **Example - Batch operations (EFFICIENT for multiple diagrams):**
@@ -962,6 +1082,31 @@ buffer_edit({
 })
 ```
 
+**Example - Insert content from another buffer (buffer composition):**
+```typescript
+// EDITING EXISTING PAGES: When you have created content in a separate buffer
+// and want to insert it into the page's buffer:
+
+// 1. Load existing page
+confluence_edit("https://confluence.example.com/pages/viewpage.action?pageId=123")
+// -> returns bufferId_A (page content), pageId
+
+// 2. Create new content in a separate buffer
+buffer_create({ content: "<p>New content to add</p>", contentType: "xhtml" })
+// -> returns bufferId_B
+
+// 3. Insert bufferId_B's content into bufferId_A
+buffer_edit({
+  bufferId: "buf_A",
+  after: 5,  // Insert after element 5 in the page
+  fromBufferId: "buf_B"  // Takes content from this buffer
+})
+
+// 4. Create draft linked to original page
+confluence_draft_create({ pageId: "123", bufferId: "buf_A" })
+// -> Works! bufferId_A originated from pageId 123
+```
+
 ---
 
 ### 8. buffer_get_structure
@@ -1081,9 +1226,9 @@ Utility tools for time calculations. Always available with any Jira, Confluence,
 
 ---
 
-## URL Tools (1)
+## URL Tools (2)
 
-Utility tools for URL construction. Always available with any Jira, Confluence, or Tempo action.
+Utility tools for URL construction and parsing. Always available with any Jira, Confluence, or Tempo action.
 
 ### 1. fullurl
 **Description**: Convert Jira issue keys, Confluence page IDs, or relative paths into full URLs
@@ -1114,6 +1259,35 @@ fullurl("/display/DOCS/Home") // → https://confluence.example.com/display/DOCS
 
 ---
 
+### 2. parseurl
+**Description**: Parse a Jira or Confluence URL to extract identifiers (pageId, issueKey, draftId, etc.)
+**Use Cases**: Extract IDs from URLs users share, prepare input for other tools
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| url | string | ✓ | Full URL to parse (Jira or Confluence) |
+
+**Supported URL formats**:
+| URL Pattern | Extracted Fields |
+|-------------|------------------|
+| `https://jira.example.com/browse/PROJ-123` | `{type: "jira_issue", issueKey: "PROJ-123"}` |
+| `https://confluence.example.com/pages/viewpage.action?pageId=123` | `{type: "confluence_page", pageId: "123"}` |
+| `https://confluence.example.com/pages/resumedraft.action?draftId=456` | `{type: "confluence_draft", draftId: "456"}` |
+| `https://confluence.example.com/display/SPACE/Page+Title` | `{type: "confluence_space_path", spaceKey: "SPACE", title: "Page Title"}` |
+| `https://confluence.example.com/spaces/SPACE/pages/123/Title` | `{type: "confluence_page", pageId: "123", spaceKey: "SPACE", title: "Title"}` |
+
+**Response includes**: `url`, `type`, and extracted fields (`issueKey`, `pageId`, `draftId`, `spaceKey`, `title`)
+
+**Workflow**:
+```
+1. parseurl(url) → extract identifier
+2. Use extracted ID with appropriate tool (jira_get_issue, confluence_get_page, confluence_edit, etc.)
+```
+
+**Tip**: `confluence_edit` can accept URLs directly and parses them internally, so you can often skip `parseurl` for Confluence workflows.
+
+---
+
 ## Jicon Help Tools (1)
 
 Unified help system for all Jicon workflows and syntax guides. Always available with any Jira, Confluence, or Tempo action.
@@ -1272,7 +1446,7 @@ Tools that return large content (Confluence pages, Jira issues, Tempo worklogs)
 - `tempo_get_worklogs`, `tempo_get_team_worklogs`
 
 **Buffer Management:**
-- **TTL**: Buffers expire after 10 minutes by default; edited buffers reset to 1 day TTL
+- **TTL**: Buffers expire after 1 hour by default; edited buffers reset to 1 day TTL
 - **List Buffers**: Use `buffer_list` to see active buffers
 - **Clear Buffers**: Use `buffer_clear` to free memory
 
@@ -1282,19 +1456,26 @@ Tools that return large content (Confluence pages, Jira issues, Tempo worklogs)
 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 with updated structure
-4. `buffer_edit` → edit using element IDs (e.g., `after=2`, `replace=5`, `plantuml="..."`)
+4. `buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId)` → edit using element IDs
 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`, `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
+1. `confluence_edit(URL or pageId)` → page content is buffered, returns `bufferId`, `pageId`, `version`, and `structure`
+2. `buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId)` → edit using element IDs
+3. `confluence_draft_create(pageId, bufferId)` → creates draft linked to original page for user review
 4. User reviews draft at URL
 5. If changes needed: repeat via `confluence_draft_open` → edit → `confluence_draft_save`
 6. User publishes via Confluence UI (click "Publish" button)
 
+**Buffer composition (when content created separately):**
+If you created content in a separate buffer and need to insert it into a page:
+1. `confluence_edit(pageId)` → `bufferId_A` (page buffer with structure)
+2. `buffer_create(content, contentType="xhtml")` → `bufferId_B` (new content)
+3. `buffer_edit(bufferId=bufferId_A, after=5, fromBufferId=bufferId_B)` → merges B into A
+4. `confluence_draft_create(pageId, bufferId=bufferId_A)` → works because bufferId_A originated from pageId
+
 **Saving buffer content to files:**
 - `buffer_save_to_file(bufferId, outputPath)` - Save buffer content to a local file
 - Security: Files can only be saved within project directory (must contain `.jicon.json`)
@@ -1334,8 +1515,10 @@ Use `buffer_edit` with element IDs for precise editing of Confluence storage for
 
 | Parameter | Description |
 |-----------|-------------|
-| `content` | XHTML content to insert/replace |
-| `plantuml` | PlantUML code (auto-validated and wrapped in Confluence macro) |
+| `content` | XHTML content to insert/replace (**REJECTS PlantUML macros**) |
+| `plantuml` | PlantUML code (**REQUIRED for diagrams** - auto-validated and wrapped in Confluence macro) |
+
+**MANDATORY**: All PlantUML diagrams MUST use the `plantuml` parameter. The `content` parameter will reject any PlantUML macros to ensure validation.
 
 **Element Structure Example:**
 

package/dist/confluence/client.d.ts

@@ -43,7 +43,7 @@ export declare class ConfluenceClient {
     /**
      * Delete a draft page permanently
      * Drafts are not sent to trash - they are permanently deleted
-     * Requires draft=true query parameter
+     * Data Center REST API v1 requires status=draft query parameter
      */
     deleteDraft(draftId: string): Promise<void>;
     /**
@@ -60,6 +60,11 @@ export declare class ConfluenceClient {
      * This returns drafts for the authenticated user (drafts are private to their creator).
      */
     listUserDrafts(spaceKey?: string, limit?: number): Promise<ConfluenceSearchResult>;
+    /**
+     * Find a draft by label
+     * Used to find existing review drafts linked to original pages
+     */
+    findDraftByLabel(label: string): Promise<ConfluencePage | null>;
     listSpaces(type?: "global" | "personal"): Promise<{
         results: ConfluenceSpace[];
         total: number;
@@ -79,7 +84,7 @@ export declare class ConfluenceClient {
         results: ConfluenceAttachment[];
         total: number;
     }>;
-    private addLabels;
+    addLabels(pageId: string, labels: string[], isDraft?: boolean): Promise<void>;
     getCurrentUser(): Promise<{
         userKey: string;
         username: string;

package/dist/confluence/client.d.ts.map

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

package/dist/confluence/client.js

@@ -149,9 +149,9 @@ export class ConfluenceClient {
             body.ancestors = [{ id: pageData.parentId }];
         }
         const page = await this.http.post("/rest/api/content?status=draft", body);
-        // Add labels if provided
+        // Add labels if provided (must use isDraft=true for draft status parameter)
         if (pageData.labels && pageData.labels.length > 0) {
-            await this.addLabels(page.id, pageData.labels);
+            await this.addLabels(page.id, pageData.labels, true);
         }
         return page;
     }
@@ -170,10 +170,10 @@ export class ConfluenceClient {
     /**
      * Delete a draft page permanently
      * Drafts are not sent to trash - they are permanently deleted
-     * Requires draft=true query parameter
+     * Data Center REST API v1 requires status=draft query parameter
      */
     async deleteDraft(draftId) {
-        await this.http.delete(`/rest/api/content/${draftId}?draft=true`);
+        await this.http.delete(`/rest/api/content/${draftId}?status=draft`);
     }
     /**
      * List user's draft pages
@@ -193,7 +193,7 @@ export class ConfluenceClient {
         params.append("status", "draft");
         params.append("type", "page");
         params.append("limit", String(limit));
-        params.append("expand", DEFAULT_SEARCH_EXPAND.join(","));
+        params.append("expand", [...DEFAULT_SEARCH_EXPAND, "metadata.labels"].join(","));
         if (spaceKey) {
             params.append("spaceKey", spaceKey);
         }
@@ -201,6 +201,20 @@ export class ConfluenceClient {
         // The response format is compatible with ConfluenceSearchResult
         return this.http.get(`/rest/api/content?${params.toString()}`);
     }
+    /**
+     * Find a draft by label
+     * Used to find existing review drafts linked to original pages
+     */
+    async findDraftByLabel(label) {
+        // List all user's drafts with labels expanded
+        const drafts = await this.listUserDrafts(undefined, 500);
+        // Find draft with matching label
+        const matchingDraft = drafts.results.find((draft) => {
+            const labels = draft.metadata?.labels?.results || [];
+            return labels.some((l) => l.name === label);
+        });
+        return matchingDraft || null;
+    }
     // Space operations
     async listSpaces(type) {
         // Fetch all spaces (auto-paginate internally)
@@ -322,9 +336,13 @@ export class ConfluenceClient {
         return { results: allAttachments, total: allAttachments.length };
     }
     // Labels
-    async addLabels(pageId, labels) {
+    async addLabels(pageId, labels, isDraft = false) {
         const labelObjects = labels.map((name) => ({ prefix: "global", name }));
-        await this.http.post(`/rest/api/content/${pageId}/label`, labelObjects);
+        // Data Center REST API v1 requires status=draft query parameter for draft operations
+        const endpoint = isDraft
+            ? `/rest/api/content/${pageId}/label?status=draft`
+            : `/rest/api/content/${pageId}/label`;
+        await this.http.post(endpoint, labelObjects);
     }
     // User operations
     async getCurrentUser() {
@@ -338,7 +356,7 @@ export class ConfluenceClient {
     }
     async getCurrentUserSpace() {
         const user = await this.getCurrentUser();
-        // Personal space key convention: ~username (e.g., ~jdoe or ~john.doe)
+        // Personal space key convention: ~username (e.g., ~amorgan or ~alex.morgan)
         const personalSpaceKey = `~${user.username}`;
         try {
             return await this.getSpace(personalSpaceKey);
@@ -358,10 +376,10 @@ export class ConfluenceClient {
                 // Case-insensitive match
                 if (keyLower === `~${usernameLower}`)
                     return true;
-                // Personal space key contains username (e.g., ~fabien.thomas contains fabien)
+                // Personal space key contains username (e.g., ~alex.morgan contains alex)
                 if (keyLower.startsWith("~") && keyLower.includes(usernameLower))
                     return true;
-                // Space name contains display name (e.g., "Fabien THOMAS" space)
+                // Space name contains display name (e.g., "Alex Morgan" space)
                 if (nameLower.includes(displayNameLower))
                     return true;
                 return false;