@crypto512/jicon-mcp 1.1.1 → 1.3.0

package/TOOL_LIST.md

@@ -5,24 +5,24 @@ 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
 
-**Note**: Tools that return large content use in-memory buffering with pagination support. See the Buffer Tools section for content retrieval.
+**Note**: All data-heavy tools (search, list, get) **always** return buffered responses with metadata for origin tracking. Use `buffer_get_chunk` to read and `buffer_grep` to search. See the Buffer Tools section for details.
 
 ---
 
 ## Jira Tools (18)
 
 ### 1. jira_search_issues
-**Description**: Search for Jira issues using JQL. Auto-fetches all results (up to 5000).
+**Description**: Search for Jira issues using JQL. Auto-fetches all results.
 **Use Cases**: Find bugs, filter by status, search by assignee, complex queries
 
 | Parameter | Type | Required | Description |
@@ -30,7 +30,7 @@ This document provides a comprehensive reference of all available tools in the J
 | jql | string | ✓ | JQL query string |
 | fields | string[] | ✗ | Specific fields to return |
 
-Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_search", title: "JQL: ..."}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
@@ -44,7 +44,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 | fields | string[] | ✗ | Specific fields to return |
 | expand | string[] | ✗ | Additional data (e.g., "changelog", "renderedFields") |
 
-Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_issue", title: "PROJ-123: Summary", issueId, projectKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
@@ -112,7 +112,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 | issueKey | string | ✓ | Issue key |
 | orderBy | string | ✗ | Sort order ("created" or "-created") |
 
-Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_comments", title: "PROJ-123 comments", issueKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
@@ -125,6 +125,8 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 | recent | boolean | ✗ | Only recent projects |
 | expand | string[] | ✗ | Additional data to expand |
 
+**Returns**: `bufferId` with metadata `{resourceType: "jira_projects", title: "All Projects"}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+
 ---
 
 ### 9. jira_get_project
@@ -136,6 +138,8 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 | projectKey | string | ✓ | Project key |
 | expand | string[] | ✗ | Additional data to expand |
 
+**Returns**: `bufferId` with metadata `{resourceType: "jira_project", title: "Project Name", projectKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+
 ---
 
 ### 10. jira_get_issue_types
@@ -181,6 +185,8 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 |-----------|------|----------|-------------|
 | boardId | number | ✓ | Board ID |
 
+**Returns**: `bufferId` with metadata `{resourceType: "jira_board", title: "Board Name", boardId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+
 ---
 
 ### 14. jira_get_sprints
@@ -192,7 +198,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 | boardId | number | ✓ | Board ID |
 | state | string | ✗ | Sprint state ("active", "future", "closed") |
 
-Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_sprints", title: "Board #123 sprints", boardId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
@@ -204,7 +210,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 |-----------|------|----------|-------------|
 | sprintId | number | ✓ | Sprint ID |
 
-Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_sprint_issues", title: "Sprint #456 issues", sprintId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
@@ -226,9 +232,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 |-----------|------|----------|-------------|
 | issueKey | string | ✓ | Issue key (e.g., PROJ-123) |
 
-**Response includes**: `worklogCount`, `totalTimeSpentSeconds`, `totalTimeSpent`, `worklogs`
-
-Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_worklogs", title: "PROJ-123 worklogs", issueKey}`. Includes `worklogCount`, `totalTimeSpentSeconds`, `totalTimeSpent`, `worklogs`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
@@ -240,17 +244,14 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 |-----------|------|----------|-------------|
 | issueKey | string | ✓ | Issue key (e.g., PROJ-123) |
 
-**Response includes**: Breakdown by issue and grand total including:
-- The specified issue
-- All sub-tasks
-- All issues in the Epic (if the issue is an Epic)
+**Returns**: `bufferId` with metadata `{resourceType: "jira_worklogs_total", title: "PROJ-123 total worklogs (recursive)", issueKey}`. Includes breakdown by issue and grand total for the issue, sub-tasks, and Epic children.
 
 ---
 
-## Confluence Tools (17)
+## Confluence Tools (21)
 
 ### 1. confluence_search_content
-**Description**: Search Confluence content using CQL. Auto-fetches all results (up to 5000).
+**Description**: Search Confluence content using CQL. Auto-fetches all results.
 **Use Cases**: Find pages, search by keyword, filter by space
 
 | Parameter | Type | Required | Description |
@@ -258,7 +259,7 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 | cql | string | ✓ | CQL query string |
 | expand | string[] | ✗ | Additional data to expand |
 
-Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_search", title: "CQL: ..."}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
@@ -273,7 +274,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 +290,61 @@ 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, ...)` → `buffer_validate_xhtml(bufferId)` → `confluence_draft_create(pageId, bufferId)` → user publishes
+> - **Create new**: `buffer_create(content, contentType="xhtml")` → `buffer_validate_xhtml(bufferId)` → `confluence_draft_create(spaceKey, title, bufferId)` → user publishes
+> - **After publish**: Draft ID becomes invalid; use `confluence_edit("SPACE/Title")` to edit again
+> - **XHTML syntax**: Call `help(topic="storage")` for HTML vs XHTML differences
 
 ---
 
-### 4. confluence_delete_page
+### 5. confluence_delete_page
 **Description**: Delete a Confluence page
 **Use Cases**: Remove outdated content
 
@@ -310,7 +354,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
 
@@ -318,11 +362,11 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 |-----------|------|----------|-------------|
 | type | string | ✗ | Space type filter ("global" or "personal") |
 
-Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_spaces", title: "All Spaces"}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
-### 6. confluence_get_space
+### 7. confluence_get_space
 **Description**: Get detailed information about a space
 **Use Cases**: View space details, get homepage
 
@@ -331,9 +375,11 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 | spaceKey | string | ✓ | Space key |
 | expand | string[] | ✗ | Additional data to expand |
 
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_space", title: "Space Name", spaceKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+
 ---
 
-### 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
 
@@ -342,11 +388,11 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 | pageId | string | ✓ | Parent page ID (accepts string or number) |
 | expand | string[] | ✗ | Additional data to expand |
 
-Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_page_children", title: "Page 123 children", pageId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
-### 8. confluence_add_comment
+### 9. confluence_add_comment
 **Description**: Add a comment to a Confluence page
 **Use Cases**: Provide feedback, ask questions
 
@@ -357,7 +403,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
 
@@ -365,11 +411,11 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 |-----------|------|----------|-------------|
 | pageId | string | ✓ | Page ID (accepts string or number) |
 
-Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_comments", title: "Page 123 comments", pageId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
-### 10. confluence_upload_attachment
+### 11. confluence_upload_attachment
 **Description**: Upload an attachment to a Confluence page
 **Use Cases**: Attach documents, upload images
 
@@ -381,7 +427,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
 
@@ -389,11 +435,11 @@ Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_g
 |-----------|------|----------|-------------|
 | pageId | string | ✓ | Page ID (accepts string or number) |
 
-Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_attachments", title: "Page 123 attachments", pageId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
-### 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,20 +453,19 @@ 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
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | spaceKey | string | ✗ | Filter by space key |
-| limit | number | ✗ | Maximum results (default: 25) |
 
-**Response includes**: `drafts` array with `draftId`, `title`, `spaceKey`, `spaceName`, `created`, `url`
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_drafts", title: "All Drafts"}`. Includes `drafts` array with `draftId`, `title`, `spaceKey`, `spaceName`, `created`, `url`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
-### 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 +475,71 @@ 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 |
+**REQUIRES `bufferId`** - content must be in a buffer for validation and error recovery.
+
+**Two Modes:**
+
+1. **NEW PAGE**: Create a standalone draft
+   | Parameter | Type | Required | Description |
+   |-----------|------|----------|-------------|
+   | spaceKey | string | ✓ | Space key |
+   | title | string | ✓ | Draft title |
+   | bufferId | string | ✓ | Buffer ID from `buffer_create(contentType="xhtml")` |
+   | 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)
 
-**Response includes**: `draftId`, `bufferId`, `structure` (element IDs), `title`, `spaceKey`, `version`, `url` (clickable to preview), `contentSummary`
+**On validation error**: Returns `bufferId`, `errorElementId`, and `errorContext` for surgical fix with `buffer_edit`.
 
 **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 new page (buffer-first)**:
+```
+1. buffer_create(content="<h1>Title</h1><p>Content</p>", contentType="xhtml")
+   → bufferId, structure (element IDs)
+2. buffer_validate_xhtml(bufferId)
+   → If errors: buffer_edit(bufferId, replace=errorElementId, content="<fixed>")
+3. confluence_draft_create(spaceKey, title, bufferId)
+   → draftId, url for preview
+4. User reviews and publishes via Confluence UI
+```
+
+**Workflow for editing existing page**:
+```
+1. confluence_get_page(pageId) or confluence_edit(input)
+   → bufferId, structure
+2. buffer_edit(bufferId, after=ID, content/plantuml)
+   → modify content
+3. buffer_validate_xhtml(bufferId)
+   → check for errors
+4. confluence_draft_create(pageId=..., bufferId=...)
+   → draft for review
+5. User reviews and publishes in Confluence UI (updates original page)
+```
+
+**Why buffer-first?** Enables validation with element IDs for surgical error fixing. Call `help(topic="storage")` for XHTML syntax (HTML vs XHTML differences).
 
 ---
 
-### 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 +557,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 +569,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
@@ -600,7 +733,9 @@ AND lastModified >= now("-30d")
 | issueKey | string | ✗ | Filter by issue key (e.g., PROJ-123) |
 | workerKey | string | ✗ | Filter by worker username (get from tempo_get_user_info). Leave empty for ALL worklogs. |
 
-**WARNING**: No workerKey = returns ALL worklogs. Large responses are buffered.
+**WARNING**: No workerKey = returns ALL worklogs.
+
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_worklogs", title: "Worklogs 2024-01-01 to 2024-01-31"}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
@@ -612,6 +747,8 @@ AND lastModified >= now("-30d")
 |-----------|------|----------|-------------|
 | worklogId | number | ✓ | Tempo worklog ID |
 
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_worklog", title: "PROJ-123 worklog #456", resourceId, issueKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+
 ---
 
 ### 3. tempo_log_work
@@ -660,6 +797,8 @@ AND lastModified >= now("-30d")
 |-----------|------|----------|-------------|
 | (none) | | | |
 
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_accounts", title: "All Tempo Accounts"}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+
 ---
 
 ### 7. tempo_get_account
@@ -670,6 +809,8 @@ AND lastModified >= now("-30d")
 |-----------|------|----------|-------------|
 | accountKey | string | ✓ | Account key |
 
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_account", title: "Account Name", accountKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+
 ---
 
 ### 8. tempo_get_teams
@@ -680,6 +821,8 @@ AND lastModified >= now("-30d")
 |-----------|------|----------|-------------|
 | (none) | | | |
 
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_teams", title: "All Tempo Teams"}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+
 ---
 
 ### 9. tempo_get_team
@@ -690,6 +833,8 @@ AND lastModified >= now("-30d")
 |-----------|------|----------|-------------|
 | teamId | number | ✓ | Team ID |
 
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_team", title: "Team Name", teamId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+
 ---
 
 ### 10. tempo_get_team_worklogs
@@ -702,7 +847,7 @@ AND lastModified >= now("-30d")
 | dateFrom | string | ✓ | Start date (YYYY-MM-DD) |
 | dateTo | string | ✓ | End date (YYYY-MM-DD) |
 
-Large responses are buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_team_worklogs", title: "Team #123 worklogs 2024-01-01 to 2024-01-31", teamId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
 
 ---
 
@@ -728,9 +873,7 @@ Large responses are buffered - use `buffer_get_chunk` or `buffer_grep` to access
 | dateFrom | string | ✗ | Start date filter (YYYY-MM-DD) |
 | dateTo | string | ✗ | End date filter (YYYY-MM-DD) |
 
-**Response includes**: `totalTimeSpent`, `totalWorklogCount`, `issueCount`, breakdown by issue, and full worklog list.
-
-More efficient than `jira_get_total_worklogs` for Tempo instances. Large responses are buffered.
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_epic_worklogs", title: "PROJ-100 epic worklogs", epicKey}`. Includes `totalTimeSpent`, `totalWorklogCount`, `issueCount`, breakdown by issue, and full worklog list. Use `buffer_get_chunk` to read, `buffer_grep` to search. More efficient than `jira_get_total_worklogs` for Tempo instances.
 
 ---
 
@@ -766,17 +909,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 +1013,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 +1025,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 +1065,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 +1108,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 +1252,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 +1285,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.
@@ -1251,28 +1451,37 @@ When using Jicon with AI assistants (Claude, GPT, etc.), follow these patterns f
 
 ### Content Buffering
 
-Tools that return large content (Confluence pages, Jira issues, Tempo worklogs) use an in-memory buffering system for efficient content pagination.
+All data-heavy tools (search, list, get) **always** return buffered responses with metadata for origin tracking.
+
+**Response Format:**
+```json
+{
+  "bufferId": "buf_abc123",
+  "metadata": {
+    "resourceType": "jira_search",
+    "title": "JQL: project = PROJ AND status = 'In Progress'"
+  },
+  "totalSize": 125000,
+  "hint": "Use buffer_get_chunk(bufferId) to read, buffer_grep(bufferId, pattern) to search"
+}
+```
 
-**How It Works:**
-1. **Initial Call**: When you call a tool like `confluence_get_page`, it fetches the full content and stores it in a buffer
-2. **Chunked Response**: The response includes a `bufferId`, the first chunk of content (default 5000 chars), and pagination info
-3. **Retrieve More**: Use `buffer_get_chunk` with the `bufferId` to get subsequent chunks
+**Metadata Fields:**
+- `resourceType`: Type of resource (e.g., `jira_issue`, `confluence_page`, `tempo_worklogs`)
+- `title`: Human-readable description of the buffered content origin
 
-**Buffered Response Format:**
-- `bufferId`: Unique identifier for retrieving more content
-- `content`: The current chunk of content
-- `offset`: Starting position of this chunk
-- `limit`: Maximum characters returned
-- `totalSize`: Total size of buffered content
-- `hasMore`: Whether more content is available
+**Working with Buffers:**
+- `buffer_get_chunk(bufferId, offset, limit)` - Read data in chunks
+- `buffer_grep(bufferId, pattern)` - Search within buffered data
+- `buffer_list()` - List all active buffers with their metadata
 
-**Auto-Buffered Tools:**
-- `confluence_get_page`, `confluence_get_page_by_title`
-- `jira_get_issue`, `jira_search_issues`
-- `tempo_get_worklogs`, `tempo_get_team_worklogs`
+**Always-Buffered Tools:**
+- **Jira**: `jira_search_issues`, `jira_get_issue`, `jira_list_projects`, `jira_get_project`, `jira_get_board`, `jira_get_sprints`, `jira_get_sprint_issues`, `jira_get_issue_comments`, `jira_get_issue_worklogs`, `jira_get_total_worklogs`
+- **Confluence**: `confluence_search_content`, `confluence_list_spaces`, `confluence_get_space`, `confluence_get_page_children`, `confluence_get_comments`, `confluence_list_attachments`, `confluence_draft_list`
+- **Tempo**: `tempo_get_worklogs`, `tempo_get_worklog`, `tempo_get_accounts`, `tempo_get_account`, `tempo_get_teams`, `tempo_get_team`, `tempo_get_team_worklogs`, `tempo_get_epic_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 +1491,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 +1550,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:**