@crypto512/jicon-mcp 1.3.0 → 2.0.0

package/TOOL_LIST.md

@@ -5,24 +5,143 @@ This document provides a comprehensive reference of all available tools in the J
 
 ## Summary
 
-**Total Tools**: 69
+**Total Tools**: 70
 - **Jira Tools**: 18 (13 read + 5 write)
 - **Confluence Tools**: 21 (13 read + 8 write)
 - **Tempo Tools**: 12 (9 read + 3 write)
-- **Buffer Tools**: 10
+- **Buffer Tools**: 11
 - **Workload Tools**: 2
 - **URL Tools**: 2
 - **Jicon Help Tools**: 1
 - **PlantUML Tools**: 3
 
-**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.
+**Note**: All data-heavy tools (search, list, get) **always** return buffered responses with metadata for origin tracking:
+- **JSON arrays**: Use `buffer_get_items` for complete items, `buffer_pipeline` for reports
+- **XHTML**: Use `buffer_get_element` for element-based access
+- **Search**: Use `buffer_grep` to search within any buffer
+
+**Important**: `buffer_get_chunk` is blocked for JSON arrays and XHTML. Use the appropriate tool above.
+
+---
+
+## Agentic Workflow Patterns
+
+### Tool Description Pattern
+
+All tools follow a consistent description pattern for easy discovery:
+
+```
+<Primary purpose - one line>
+
+REQUIRES: <Prerequisites or dependencies>
+RETURNS: <Key return values and buffer content>
+NEXT: <Typical next tools in workflow>
+
+TIP: <Usage hints>
+WARNING: <Important caveats>
+```
+
+### Suggested Next Tools
+
+JSON responses include `suggestedNextTools` based on context:
+
+```json
+{
+  "bufferId": "buf_xxx",
+  "structure": { "type": "array", "itemCount": 500 },
+  "suggestedNextTools": [
+    { "tool": "buffer_pipeline", "description": "Transform to table/report (98% token reduction)", "condition": "for Confluence reports" },
+    { "tool": "buffer_get_items", "description": "Get complete items for AI analysis", "condition": "for detailed analysis" },
+    { "tool": "buffer_grep", "description": "Search within results" }
+  ]
+}
+```
+
+### Error Recovery Patterns
+
+#### 409 Conflict Handling (Optimistic Locking)
+
+Write operations may fail with HTTP 409 when the resource was modified since it was last read. Use `autoRetry=true` for automatic recovery:
+
+```typescript
+// Manual retry pattern
+jira_update_issue({ issueKey: "PROJ-123", fields: {...} })
+// If 409 error → re-fetch issue → retry update
+
+// Auto-retry pattern (RECOMMENDED for agents)
+jira_update_issue({ issueKey: "PROJ-123", fields: {...}, autoRetry: true })
+// Automatically: re-fetches → retries once → returns success or final error
+```
+
+**Tools supporting autoRetry:**
+- `jira_update_issue` - Auto-retries on 409 (refetches issue)
+- `confluence_review_publish` - Auto-retries on 409 (refetches page version)
+- `tempo_update_worklog` - Auto-retries on 409 (refetches worklog)
+
+**Response on successful retry:**
+```json
+{
+  "success": true,
+  "issueKey": "PROJ-123",
+  "retriedAfterConflict": true
+}
+```
+
+#### XHTML Validation Errors
+
+When XHTML validation fails, the response includes element ID and suggested actions:
+
+```json
+{
+  "error": true,
+  "message": "XHTML parsing error at line 45",
+  "errorContext": {
+    "elementId": 12,
+    "bufferId": "buf_xxx"
+  },
+  "suggestedActions": {
+    "inspect": "buffer_get_element(bufferId=\"buf_xxx\", elementId=12)",
+    "fix": "buffer_edit(bufferId=\"buf_xxx\", replace=12, content=\"<corrected>\")",
+    "validate": "buffer_validate_xhtml(bufferId=\"buf_xxx\")"
+  }
+}
+```
+
+### Common Agentic Workflows
+
+#### Jira Search → Confluence Report
+```
+1. jira_search_issues(jql) → bufferId, suggestedNextTools
+2. buffer_pipeline(bufferId, pipeline) → tableBufferId (98% token reduction)
+3. confluence_edit(pageId) → pageBufferId, structure
+4. buffer_edit(pageBufferId, after=ID, fromBufferId=tableBufferId)
+5. confluence_draft_create(pageId, pageBufferId, autoRetry=true) → draft URL
+```
+
+#### Tempo Time Report
+```
+1. tempo_get_user_info() → workerKey
+2. tempo_get_worklogs(dateFrom, dateTo, workerKey) → bufferId, suggestedNextTools
+3. buffer_pipeline(bufferId, groupBy=project, sum=hours) → summaryBufferId
+4. Use in report or display directly
+```
+
+#### Edit Existing Page with Error Recovery
+```
+1. confluence_edit(input) → bufferId, pageId, structure
+2. buffer_edit(bufferId, after=ID, content) → updated structure
+3. buffer_validate_xhtml(bufferId) → check before publish
+   - If errors: buffer_get_element(elementId) → inspect → buffer_edit(replace=ID) → retry
+4. confluence_draft_create(pageId, bufferId) → draft for review
+5. confluence_review_publish(reviewDraftId, autoRetry=true) → published
+```
 
 ---
 
 ## Jira Tools (18)
 
 ### 1. jira_search_issues
-**Description**: Search for Jira issues using JQL. Auto-fetches all results.
+**Description**: Search for Jira issues using JQL. Auto-fetches all results (up to 5000).
 **Use Cases**: Find bugs, filter by status, search by assignee, complex queries
 
 | Parameter | Type | Required | Description |
@@ -30,7 +149,26 @@ This document provides a comprehensive reference of all available tools in the J
 | jql | string | ✓ | JQL query string |
 | fields | string[] | ✗ | Specific fields to return |
 
-**Returns**: `bufferId` with metadata `{resourceType: "jira_search", title: "JQL: ..."}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Response Fields (Important!):**
+| Field | Description |
+|-------|-------------|
+| `returnedItems` | Items available in buffer - **USE THIS** for actual count |
+| `jiraTotalMatching` | Total matching in Jira (may exceed returnedItems) |
+| `apiLimit` | Maximum items per search (5000 cap) |
+| `note` | Explanation when results are truncated |
+
+**Example Response** (when JQL matches 9998 issues):
+```json
+{
+  "bufferId": "buf_xxx",
+  "returnedItems": 5000,
+  "jiraTotalMatching": 9998,
+  "apiLimit": 5000,
+  "note": "9998 issues match query, 5000 returned (API limit)"
+}
+```
+
+**Returns**: `bufferId` with issues. Use `buffer_pipeline` for tables, `buffer_get_items` for AI analysis.
 
 ---
 
@@ -75,6 +213,9 @@ This document provides a comprehensive reference of all available tools in the J
 | issueKey | string | ✓ | Issue key |
 | fields | object | ✓ | Fields to update |
 | notifyUsers | boolean | ✗ | Send notifications (default: true) |
+| autoRetry | boolean | ✗ | Auto-retry once on 409 conflict (refetches current state) |
+
+**Error Recovery**: Use `autoRetry: true` for automatic 409 conflict handling. Response includes `retriedAfterConflict: true` if retry was needed.
 
 ---
 
@@ -499,12 +640,14 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 2. **EDIT EXISTING PAGE**: Create a draft to edit an existing page
    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
-   | pageId | string | ✓ | Existing page ID to edit |
+   | pageId | string | ✓ | Existing PAGE ID (NOT a draft ID) |
    | 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.
 
+**WARNING**: `pageId` must be a real page ID, NOT a draft ID. If you pass a draft ID, you'll get an error suggesting `confluence_draft_open` instead.
+
 **Response includes**: `draftId`, `bufferId`, `structure` (element IDs), `title`, `spaceKey`, `version`, `url` (clickable to preview), `contentSummary`, `editingExistingPage` (when editing)
 
 **On validation error**: Returns `bufferId`, `errorElementId`, and `errorContext` for surgical fix with `buffer_edit`.
@@ -590,6 +733,9 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | reviewDraftId | string | ✓ | ID of the [jicon-mcp REVIEW] draft to publish |
+| autoRetry | boolean | ✗ | Auto-retry once on 409 conflict (refetches page version) |
+
+**Error Recovery**: Use `autoRetry: true` for automatic 409 conflict handling when the original page was modified. Response includes `retriedAfterConflict: true` if retry was needed.
 
 **Workflow**:
 1. Validates the draft is a "[jicon-mcp REVIEW]" draft with proper label
@@ -626,7 +772,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 project = PROJ AND type = Bug AND status = Open AND assignee = currentUser()
 
 # Issues updated in the last 7 days
-updatedDate >= -7d
+updated >= startOfDay(-7)
 
 # High priority issues in multiple projects
 project in (PROJ1, PROJ2) AND priority = High
@@ -776,6 +922,9 @@ AND lastModified >= now("-30d")
 | hours | number | ✗ | New hours (decimal) |
 | description | string | ✗ | New description |
 | date | string | ✗ | New date (YYYY-MM-DD) |
+| autoRetry | boolean | ✗ | Auto-retry once on 409 conflict (refetches current state) |
+
+**Error Recovery**: Use `autoRetry: true` for automatic 409 conflict handling. Response includes `retriedAfterConflict: true` if retry was needed.
 
 ---
 
@@ -877,25 +1026,44 @@ AND lastModified >= now("-30d")
 
 ---
 
-## Buffer Tools (10)
+## Buffer Tools (11)
 
 Buffer tools are used for local content management. All buffer operations are in-memory - write enforcement is on Jira/Confluence/Tempo tools.
 
 **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.
 
+**Data Pipelines**: `buffer_pipeline` transforms JSON buffers (from Jira/Tempo searches) with server-side filtering, grouping, sorting, and output generation - minimizing token usage.
+
 ### 1. buffer_create
-**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
+**Description**: Create a new buffer with initial content. Returns bufferId and structure.
+
+**TIP**: Call `help(topic="storage")` for XHTML syntax. Call `help(topic="plantuml")` for diagram syntax.
+
+**Content types**:
+- **xhtml**: Confluence storage format. Returns element IDs for `buffer_edit`.
+- **json**: JSON data (array or object). Use `buffer_pipeline` to filter, aggregate, and transform.
+- **plain**: Raw text content.
+
+**Use Cases**: Draft new Confluence pages, prepare content before persisting, create JSON arrays for aggregation
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| content | string | ✓ | Initial content for the buffer |
+| content | string \| object \| array | ✓ | Content: string for all types, or object/array for json (auto-stringified) |
 | contentType | enum | ✓ | Content type: `"xhtml"` for Confluence, `"plain"` for text, `"json"` for data |
 | metadata | object | ✗ | Optional metadata to attach to the buffer |
 
-**Response for XHTML includes**: `bufferId`, `structure` (element IDs), `nextId`, `contentType`, `totalSize`
+**Auto-stringify for JSON**: When `contentType: "json"`, you can pass native objects/arrays directly instead of JSON strings:
+```typescript
+// Both work:
+buffer_create({ content: '[{"key":"PROJ-1"}]', contentType: "json" })  // String
+buffer_create({ content: [{"key":"PROJ-1"}], contentType: "json" })    // Native array (auto-stringified)
+```
+
+**Response for XHTML includes**: `bufferId`, `structure` (element IDs), `nextId`, `contentType`, `bufferSizeBytes`
 
-**Response for plain/json includes**: `bufferId`, `contentType`, `totalSize`, `createdAt`, `expiresAt`
+**Response for JSON includes**: `bufferId`, `contentType`, `bufferSizeBytes`, `structure` (type, itemCount/keys, preview), `hint` (suggested next tool)
+
+**Response for plain includes**: `bufferId`, `contentType`, `bufferSizeBytes`, `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.
 
@@ -924,8 +1092,12 @@ Buffer tools are used for local content management. All buffer operations are in
 ---
 
 ### 2. buffer_get_chunk
-**Description**: Retrieve a chunk of buffered content by buffer ID
-**Use Cases**: Get remaining content from large responses, retrieve edited content
+**Description**: Retrieve raw character chunks from a buffer. Returns raw content by character offset.
+**Use Cases**: Plain text buffers only, raw character access
+
+**BLOCKED FOR**: JSON arrays and XHTML content. Use instead:
+- JSON arrays: `buffer_get_items` - returns complete items
+- XHTML: `buffer_get_element` - returns element content
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -935,9 +1107,58 @@ Buffer tools are used for local content management. All buffer operations are in
 
 **Response includes**: `bufferId`, `content`, `offset`, `limit`, `totalSize`, `hasMore`, `metadata`
 
+**Error on JSON/XHTML**: Returns error with guidance to use correct tool
+
+---
+
+### 3. buffer_get_items
+**Description**: Retrieve complete JSON array items from a buffer. Unlike `buffer_get_chunk` which may truncate mid-item, this returns whole items.
+**Use Cases**: Iterate through search results, process items in batches, inspect specific items
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID containing JSON array |
+| start | number | ✗ | Starting index (0-based, default: 0) |
+| count | number | ✗ | Number of items to return (default: 10, max: 100) |
+
+**Type Requirement**: Buffer must have `contentType: "json"`. Returns error if buffer is XHTML or plain text.
+
+**Response includes**: `bufferId`, `items` (array of parsed objects), `start`, `count`, `totalItems`, `hasMore`, `itemSchema` (field names in items)
+
+**Example - Get first 10 items:**
+```typescript
+buffer_get_items({
+  bufferId: "buf_xxx",
+  start: 0,
+  count: 10
+})
+// Returns: {
+//   items: [{key: "PROJ-1", ...}, {key: "PROJ-2", ...}, ...],
+//   start: 0,
+//   count: 10,
+//   totalItems: 578,
+//   hasMore: true,
+//   itemSchema: ["key", "summary", "status", "priority", ...]
+// }
+```
+
+**Example - Page through results:**
+```typescript
+// Page 1
+buffer_get_items({ bufferId: "buf_xxx", start: 0, count: 50 })
+// Page 2
+buffer_get_items({ bufferId: "buf_xxx", start: 50, count: 50 })
+// Page 3
+buffer_get_items({ bufferId: "buf_xxx", start: 100, count: 50 })
+```
+
+**When to use `buffer_get_items` vs `buffer_get_chunk`:**
+- Use `buffer_get_items` for JSON array buffers when you need complete items
+- Use `buffer_get_chunk` for XHTML/plain text or when you need raw character access
+
 ---
 
-### 3. buffer_get_element
+### 4. 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
 
@@ -946,6 +1167,8 @@ Buffer tools are used for local content management. All buffer operations are in
 | bufferId | string | ✓ | Buffer ID containing XHTML content |
 | elementId | number | ✓ | Element ID from buffer structure |
 
+**Type Requirement**: Buffer must have `contentType: "xhtml"`. Returns error if buffer is JSON or plain text.
+
 **Response includes**: `bufferId`, `elementId`, `elementType`, `lineCount`, `content`
 
 **Example - Inspect problematic element after XHTML error:**
@@ -968,7 +1191,7 @@ buffer_get_element({
 
 ---
 
-### 4. buffer_list
+### 5. buffer_list
 **Description**: List all active buffers with their metadata
 **Use Cases**: View active buffers, check expiration times
 
@@ -980,7 +1203,7 @@ buffer_get_element({
 
 ---
 
-### 5. buffer_clear
+### 6. buffer_clear
 **Description**: Clear a specific buffer or all buffers
 **Use Cases**: Free up memory, clean up after processing
 
@@ -992,8 +1215,8 @@ buffer_get_element({
 
 ---
 
-### 6. buffer_grep
-**Description**: Search buffered content for patterns (regex supported)
+### 7. buffer_grep
+**Description**: Search buffered content for patterns. Supports regex, context lines (-A/-B/-C), and case-insensitive (-i). Large results are buffered.
 **Use Cases**: Find specific content in large responses, locate text for editing
 
 | Parameter | Type | Required | Description |
@@ -1002,17 +1225,288 @@ buffer_get_element({
 | pattern | string | ✓ | Regex pattern to search for |
 | -A | number | ✗ | Lines to show after each match |
 | -B | number | ✗ | Lines to show before each match |
-| -C | number | ✗ | Lines to show before AND after |
+| -C | number | ✗ | Lines to show before AND after (overrides -A/-B) |
 | -i | boolean | ✗ | Case insensitive search |
 | -n | boolean | ✗ | Show line numbers (default: true) |
-| output_mode | string | ✗ | "content" or "count" |
+| output_mode | string | ✗ | "content" shows matching lines, "count" shows match count |
+| multiline | boolean | ✗ | Enable multiline mode where `.` matches newlines |
+| head_limit | number | ✗ | Limit to first N matches |
+| offset | number | ✗ | Skip first N matches |
 
 **Response includes**: `totalMatches`, `matches` with line numbers and context
 
 ---
 
-### 7. buffer_edit
-**Description**: Edit buffer content. For XHTML: use element IDs (single or batch). For plain/json: use string replacement.
+### 8. buffer_pipeline
+**Description**: Transform JSON buffer data with a declarative pipeline: select fields, filter, group/aggregate, sort, format, and output to various formats.
+**Use Cases**: Server-side data transformation to minimize token usage, generate XHTML tables for Confluence, export to CSV/Markdown, aggregate statistics
+
+**Token Efficiency**: A pipeline that filters, sorts, and outputs a table executes in **1 tool call** instead of iterating through items. For pure data transforms, this achieves **98% token reduction**.
+
+**Schema Quick Reference:**
+```json
+{
+  "sourceBufferId": "buf_xxx",
+  "pipeline": {
+    "select": { "fields": [...] },
+    "filter": [...],
+    "groupBy": { "field": "...", "aggregations": [...] },
+    "sort": [...],
+    "limit": 10,
+    "format": [...],
+    "output": { "type": "xhtml_table", "table": {...} }
+  }
+}
+```
+
+**Common Mistakes:**
+
+| Wrong | Correct | Why |
+|-------|---------|-----|
+| `sortBy: [...]` | `sort: [...]` | Key name is "sort" not "sortBy" |
+| `transform: "map"` | `transform: "date"` | Valid: uppercase, lowercase, date, number, boolean, string |
+| No `output` | `output: {...}` | Required field - pipeline must have output |
+| `pipeline: "{...}"` | `pipeline: {...}` | Must be object, not JSON string |
+| After select: `sort: [{field: "issueType"}]` | `sort: [{field: "Type"}]` | After `select` renames "issueType" to "Type", use NEW name |
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Source buffer ID containing JSON array |
+| pipeline | object | ✓ | Pipeline definition (see below) |
+
+**Type Requirement**: Buffer must have `contentType: "json"`. Returns error if buffer is XHTML or plain text.
+
+**Pipeline Definition:**
+
+```typescript
+{
+  // Stage 1: Select specific fields (optional)
+  select?: {
+    fields: [
+      { from: "key" },                           // Keep field as-is
+      { from: "priority.name", as: "Priority" }, // Rename field
+      { from: "created", transform: "date" }     // Transform value
+    ]
+  },
+
+  // Stage 2: Filter items (optional, AND logic between conditions)
+  filter?: [
+    { field: "status.name", operator: "ne", value: "Done" },
+    { field: "priority.name", operator: "in", value: ["High", "Critical"] }
+  ],
+
+  // Stage 3: Group and aggregate (optional)
+  groupBy?: {
+    field: "assignee.displayName",
+    aggregations: [
+      { function: "count", as: "totalIssues" },
+      { function: "sum", field: "timeSpent", as: "totalTime" },
+      { function: "list", field: "key", as: "issueKeys" }
+    ]
+  },
+
+  // Stage 4: Sort results (optional)
+  sort?: [
+    { field: "priority.name", direction: "asc" },
+    { field: "key", direction: "desc" }
+  ],
+
+  // Stage 5: Limit results (optional)
+  limit?: 50,
+
+  // Stage 6: Conditional formatting (optional)
+  format?: [
+    {
+      condition: { field: "priority.name", operator: "eq", value: "High" },
+      style: { color: "#dc3545", bold: true }
+    },
+    {
+      condition: { field: "status.name", operator: "eq", value: "Done" },
+      style: { color: "#28a745", icon: "✓" }
+    }
+  ],
+
+  // Stage 7: Output configuration (REQUIRED)
+  output: {
+    type: "xhtml_table",  // or "xhtml_list", "json", "csv", "markdown"
+    table: {
+      title: "Open Issues",
+      columns: [
+        { field: "key", header: "Issue", link: { type: "jira" } },
+        { field: "summary", header: "Summary" },
+        { field: "priority.name", header: "Priority" }
+      ]
+    }
+  }
+}
+```
+
+**Filter Operators:**
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `eq` | Equals | `{ field: "status.name", operator: "eq", value: "Open" }` |
+| `ne` | Not equals | `{ field: "status.name", operator: "ne", value: "Done" }` |
+| `gt`, `lt`, `gte`, `lte` | Numeric comparison | `{ field: "priority.id", operator: "gt", value: 2 }` |
+| `contains` | Substring match (case-insensitive) | `{ field: "summary", operator: "contains", value: "bug" }` |
+| `startsWith`, `endsWith` | String prefix/suffix | `{ field: "key", operator: "startsWith", value: "PROJ-" }` |
+| `in`, `notIn` | Value in array | `{ field: "priority.name", operator: "in", value: ["High", "Critical"] }` |
+| `exists`, `notExists` | Field presence | `{ field: "assignee", operator: "exists" }` |
+| `empty`, `notEmpty` | Empty string/array/null | `{ field: "labels", operator: "notEmpty" }` |
+| `regex` | Regular expression | `{ field: "summary", operator: "regex", value: "^\\[BUG\\]" }` |
+
+**Aggregation Functions:**
+
+| Function | Description | Requires `field` |
+|----------|-------------|------------------|
+| `count` | Count items in group | No |
+| `sum` | Sum numeric values | Yes |
+| `avg` | Average numeric values | Yes |
+| `min`, `max` | Min/max numeric values | Yes |
+| `first`, `last` | First/last value | Yes |
+| `list` | Collect all values | Yes |
+| `unique` | Unique values | Yes |
+
+**Output Types:**
+
+| Type | Description | Config |
+|------|-------------|--------|
+| `xhtml_table` | Confluence-compatible table | `table: { title?, columns: [...], showRowNumbers? }` |
+| `xhtml_list` | Confluence-compatible list | `list: { title?, template: "{{key}}: {{summary}}", style?: "bullet"|"numbered"|"none" }` |
+| `json` | Clean JSON array | `includeMetadata?: boolean` |
+| `csv` | CSV with headers | `table: { columns: [...] }` |
+| `markdown` | Markdown table | `table: { columns: [...] }` |
+
+**Column Configuration:**
+
+```typescript
+{
+  field: "key",                    // Field path (dot notation)
+  header: "Issue",                 // Column header text
+  link?: { type: "jira" },         // Auto-link (jira, confluence, url)
+  width?: "100px",                 // Column width
+  align?: "left" | "center" | "right"
+}
+```
+
+**Response includes**: `bufferId` (new output buffer), `inputItems`, `outputItems`, `pipelineStages`, `outputType`, `preview`, `bufferSizeBytes`, `structure` (for XHTML), `hint`
+
+**Example - Filter and output table:**
+```typescript
+// Search returns bufferId with 500 issues
+jira_search_issues({ jql: "project = PROJ" })
+// -> { bufferId: "buf_issues", structure: { itemCount: 500 } }
+
+// Transform in ONE call (instead of iterating 500 items)
+buffer_pipeline({
+  bufferId: "buf_issues",
+  pipeline: {
+    filter: [
+      { field: "issuetype.name", operator: "eq", value: "Bug" },
+      { field: "status.name", operator: "ne", value: "Done" }
+    ],
+    sort: [{ field: "priority.name", direction: "asc" }],
+    limit: 20,
+    format: [
+      { condition: { field: "priority.name", operator: "eq", value: "High" },
+        style: { color: "#dc3545", bold: true } }
+    ],
+    output: {
+      type: "xhtml_table",
+      table: {
+        title: "Top 20 Open Bugs",
+        columns: [
+          { field: "key", header: "Issue", link: { type: "jira" } },
+          { field: "summary", header: "Summary" },
+          { field: "priority.name", header: "Priority" },
+          { field: "assignee.displayName", header: "Assignee" }
+        ]
+      }
+    }
+  }
+})
+// -> { bufferId: "buf_result", outputItems: 15, preview: "<table>...", structure: [...] }
+```
+
+**Example - Group by assignee with aggregations:**
+```typescript
+buffer_pipeline({
+  bufferId: "buf_issues",
+  pipeline: {
+    filter: [{ field: "status.name", operator: "ne", value: "Done" }],
+    groupBy: {
+      field: "assignee.displayName",
+      aggregations: [
+        { function: "count", as: "issueCount" },
+        { function: "list", field: "key", as: "issues" }
+      ]
+    },
+    sort: [{ field: "issueCount", direction: "desc" }],
+    output: {
+      type: "xhtml_table",
+      table: {
+        title: "Issues by Assignee",
+        columns: [
+          { field: "displayName", header: "Assignee" },
+          { field: "issueCount", header: "Count" },
+          { field: "issues", header: "Issues" }
+        ]
+      }
+    }
+  }
+})
+```
+
+**Example - Export to CSV:**
+```typescript
+buffer_pipeline({
+  bufferId: "buf_issues",
+  pipeline: {
+    select: {
+      fields: [
+        { from: "key" },
+        { from: "summary" },
+        { from: "status.name", as: "Status" },
+        { from: "created", transform: "date" }
+      ]
+    },
+    output: {
+      type: "csv",
+      table: {
+        columns: [
+          { field: "key", header: "Issue" },
+          { field: "summary", header: "Summary" },
+          { field: "Status", header: "Status" },
+          { field: "created", header: "Created" }
+        ]
+      }
+    }
+  }
+})
+// -> { bufferId: "buf_csv", output: "Issue,Summary,Status,Created\nPROJ-1,..." }
+```
+
+**Common Jira Fields:**
+- `key`, `summary`, `description`
+- `status.name`, `priority.name`, `issuetype.name`
+- `assignee.displayName`, `reporter.displayName`
+- `created`, `updated`, `resolutiondate`
+- `labels` (array), `components[].name`
+- `timeoriginalestimate`, `timeestimate`, `timespent`
+
+**Workflow - Jira to Confluence table:**
+```
+1. jira_search_issues(jql) → bufferId with JSON
+2. buffer_pipeline(bufferId, pipeline) → bufferId with XHTML table
+3. confluence_edit(pageId) → page bufferId
+4. buffer_edit(pageBufferId, after=ID, fromBufferId=tableBufferId)
+5. confluence_draft_create(pageId, pageBufferId) → draft for review
+```
+
+---
+
+### 9. buffer_edit
+**Description**: Edit buffer content. For XHTML: use element IDs (single or batch). For plain/json: use string replacement or append.
 **Use Cases**: Insert/replace/remove elements in Confluence pages, modify Jira/Tempo content, compose content from multiple buffers
 
 **XHTML Parameters (single operation):**
@@ -1049,6 +1543,14 @@ buffer_get_element({
 | new_string | string | ✓ | Replacement text |
 | replace_all | boolean | ✗ | Replace all occurrences (default: false) |
 
+**Plain/JSON Parameters (append):**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID to modify |
+| append | boolean | ✓ | Must be `true` |
+| content | string | ✓ | Text to append at end of buffer |
+
 **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.
 
 **XHTML Response includes**: `success`, `operationsCompleted`, `structure`, `nextId`, `insertedIds`, `diagramTypes`
@@ -1135,7 +1637,7 @@ confluence_draft_create({ pageId: "123", bufferId: "buf_A" })
 
 ---
 
-### 8. buffer_get_structure
+### 10. buffer_get_structure
 **Description**: Get current element structure for an XHTML buffer
 **Use Cases**: View element IDs for editing, understand document structure
 
@@ -1143,6 +1645,8 @@ confluence_draft_create({ pageId: "123", bufferId: "buf_A" })
 |-----------|------|----------|-------------|
 | bufferId | string | ✓ | Buffer ID to get structure for |
 
+**Type Requirement**: Buffer must have `contentType: "xhtml"`. Returns error if buffer is JSON or plain text.
+
 **Response includes**: `bufferId`, `structure`, `nextId`
 
 **Structure Format**:
@@ -1167,19 +1671,27 @@ buffer_get_structure({ bufferId: "buf_xxx" })
 
 ---
 
-### 9. buffer_validate_xhtml
+### 11. buffer_validate_xhtml
 **Description**: Validate buffered content as Confluence storage format (XHTML)
 **Use Cases**: Check content validity before writing, debug validation errors
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | bufferId | string | ✓ | Buffer ID containing XHTML content |
+| validatePlantUml | boolean | ✗ | Validate PlantUML syntax via Docker service (default: true) |
+
+**Type Requirement**: Buffer must have `contentType: "xhtml"`. Returns error if buffer is JSON or plain text.
 
 **Validation Checks**:
 - XML well-formedness (balanced tags, proper nesting)
 - Required attributes on Confluence elements (ac:name, ri:space-key, etc.)
 - Valid layout section types (single, two_equal, etc.)
 - Known macro names (warns for unknown macros)
+- PlantUML syntax (via Docker service, if running)
+
+**PlantUML validation**:
+- If Docker service is running, validates all PlantUML macros
+- If not running, adds warning (use `plantuml_validate` to start the service)
 
 **Response includes**: `valid`, `errorCount`, `warningCount`, `errors`, `warnings`
 
@@ -1187,40 +1699,6 @@ buffer_get_structure({ bufferId: "buf_xxx" })
 
 ---
 
-### 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
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| bufferId | string | ✓ | Buffer ID containing content to save |
-| outputPath | string | ✓ | Output file path (must be within project directory) |
-| decodeBase64 | boolean | ✗ | Decode base64 content before saving (auto-detected for PNG/EPS) |
-
-**Security**: Files can only be saved within the project directory (must contain `.jicon.json`).
-
-**Binary Content**: Base64-encoded content (e.g., from `plantuml_render` with PNG/EPS format) is automatically decoded when `decodeBase64` is true or when the output path ends with `.png` or `.eps`.
-
-**Response includes**: `success`, `path`, `size`, `message`
-
-**Example - Save PlantUML render**:
-```typescript
-// 1. Render diagram to PNG
-const result = plantuml_render({
-  code: "@startuml\nA -> B\n@enduml",
-  format: "png"
-})
-// Returns: { bufferId: "buf_xxx", ... }
-
-// 2. Save to file
-buffer_save_to_file({
-  bufferId: "buf_xxx",
-  outputPath: "./diagrams/sequence.png"
-})
-```
-
----
-
 ## Workload Tools (2)
 
 Utility tools for time calculations. Always available with any Jira, Confluence, or Tempo action.
@@ -1302,11 +1780,13 @@ fullurl("/display/DOCS/Home") // → https://confluence.example.com/display/DOCS
 | `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`)
+**Response includes**: `url`, `type`, extracted fields (`issueKey`, `pageId`, `draftId`, `spaceKey`, `title`), and `warning` if domain mismatch
+
+**Domain Validation**: If the URL domain doesn't match the configured JIRA_URL or CONFLUENCE_URL, a warning is included suggesting the correct domain.
 
 **Workflow**:
 ```
-1. parseurl(url) → extract identifier
+1. parseurl(url) → extract identifier (check for warning)
 2. Use extracted ID with appropriate tool (jira_get_issue, confluence_get_page, confluence_edit, etc.)
 ```
 
@@ -1401,7 +1881,7 @@ Include expansion is enabled by default. Whitelisted URLs: `plantuml-stdlib/*`,
 
 **Response includes**: `bufferId` (for large outputs), `content` (for small outputs), `format`, `size`
 
-**Binary Formats**: PNG and EPS outputs are base64-encoded. Use `buffer_save_to_file` to decode and save to disk.
+**Binary Formats**: PNG and EPS outputs are base64-encoded in the buffer.
 
 **Example - ASCII preview**:
 ```typescript
@@ -1413,18 +1893,6 @@ plantuml_render({
 // Returns ASCII art directly in response
 ```
 
-**Example - Save PNG**:
-```typescript
-const result = plantuml_render({
-  code: "@startuml\nA -> B\n@enduml",
-  format: "png"
-})
-buffer_save_to_file({
-  bufferId: result.bufferId,
-  outputPath: "./diagram.png"
-})
-```
-
 ---
 
 ### 3. plantuml_status
@@ -1453,27 +1921,38 @@ When using Jicon with AI assistants (Claude, GPT, etc.), follow these patterns f
 
 All data-heavy tools (search, list, get) **always** return buffered responses with metadata for origin tracking.
 
-**Response Format:**
+**Response Format (JSON arrays from Jira/Tempo):**
 ```json
 {
   "bufferId": "buf_abc123",
+  "contentType": "json",
+  "structure": { "type": "array", "itemCount": 578 },
   "metadata": {
     "resourceType": "jira_search",
-    "title": "JQL: project = PROJ AND status = 'In Progress'"
+    "title": "JQL: project = PROJ"
   },
-  "totalSize": 125000,
-  "hint": "Use buffer_get_chunk(bufferId) to read, buffer_grep(bufferId, pattern) to search"
+  "accessors": {
+    "pipeline": { "tool": "buffer_pipeline", "description": "Transform to table/CSV/list" },
+    "get_items": { "tool": "buffer_get_items", "description": "Get complete items for analysis" },
+    "search": { "tool": "buffer_grep", "description": "Search within buffer" }
+  }
 }
 ```
 
 **Metadata Fields:**
 - `resourceType`: Type of resource (e.g., `jira_issue`, `confluence_page`, `tempo_worklogs`)
 - `title`: Human-readable description of the buffered content origin
+- `contentType`: Buffer type (`json`, `xhtml`, `plain`)
 
-**Working with Buffers:**
-- `buffer_get_chunk(bufferId, offset, limit)` - Read data in chunks
+**Working with JSON Buffers (Jira/Tempo):**
+- `buffer_pipeline(bufferId, pipeline)` - Transform to table/CSV/list (98% token reduction)
+- `buffer_get_items(bufferId, start, count)` - Get complete items for AI analysis
+- `buffer_grep(bufferId, pattern)` - Search within buffered data
+
+**Working with XHTML Buffers (Confluence):**
+- `buffer_get_structure(bufferId)` - View element IDs for editing
+- `buffer_edit(bufferId, after=ID, content)` - Edit using element IDs
 - `buffer_grep(bufferId, pattern)` - Search within buffered data
-- `buffer_list()` - List all active buffers with their metadata
 
 **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`
@@ -1511,11 +1990,6 @@ If you created content in a separate buffer and need to insert it into a page:
 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`)
-- Binary content (PNG/EPS from `plantuml_render`) is auto-decoded from base64
-
 ### Buffer Content Types
 
 **Buffer types determine editing mode:**
@@ -1532,6 +2006,56 @@ If you created content in a separate buffer and need to insert it into a page:
 - Use `buffer_get_structure` to view current element IDs
 - Element IDs are **stable** - they never change when content is inserted/deleted
 
+### Buffer Type Requirements
+
+Tools enforce type-safe buffer access - each tool only accepts buffers of the type it understands. This prevents errors and provides clear guidance.
+
+| Buffer Type | Tools That REQUIRE This Type |
+|-------------|------------------------------|
+| **json** | `buffer_pipeline`, `buffer_get_items` |
+| **xhtml** | `buffer_get_structure`, `buffer_get_element`, `buffer_validate_xhtml`, `confluence_draft_create` (with bufferId), `confluence_draft_save` |
+| **any** | `buffer_grep`, `buffer_get_chunk`, `buffer_list`, `buffer_clear`, `buffer_edit` (string mode) |
+
+**Error Messages**: When you use a tool with the wrong buffer type, you get a helpful error:
+```
+buffer_pipeline requires json buffer, but got: xhtml.
+For XHTML content, use buffer_edit or buffer_get_structure instead.
+```
+
+**Key Principle**: If you have a JSON buffer (from Jira/Tempo search), use JSON-aware tools (`buffer_pipeline`, `buffer_get_items`). If you have an XHTML buffer (from Confluence), use XHTML-aware tools (`buffer_get_structure`, `buffer_edit` with element IDs).
+
+### Large Dataset Patterns
+
+**Simple table (no AI analysis):**
+Use `buffer_pipeline` - generates complete table in ONE tool call:
+```typescript
+jira_search_issues({ jql: "project=PROJ" })  // → bufferId (500+ items)
+buffer_pipeline({ bufferId, pipeline: { output: { type: "xhtml_table", ... } } })  // → complete table!
+```
+
+**Table with AI-enhanced columns (complexity, impact):**
+Use batch accumulation workflow - analyze items in batches, compose results:
+```typescript
+// 1. Search Jira
+jira_search_issues({ jql: "..." })  // → sourceBufferId (N items)
+
+// 2. Create accumulator table
+buffer_create({
+  content: "<table><thead>...</thead><tbody></tbody></table>",
+  contentType: "xhtml"
+})  // → accumulatorBufferId, structure (note tbody element ID)
+
+// 3. For each batch of items:
+buffer_get_items({ bufferId: sourceBufferId, start: X, count: 50 })  // → items[]
+// AI analyzes items, builds XHTML rows with AI columns
+buffer_create({ content: rowsXHTML, contentType: "xhtml" })  // → batchBufferId
+buffer_edit({ bufferId: accumulatorBufferId, after: lastRowId, fromBufferId: batchBufferId })
+
+// 4. Insert into page and create draft
+buffer_edit({ bufferId: pageBufferId, after: ID, fromBufferId: accumulatorBufferId })
+confluence_draft_create({ pageId, bufferId: pageBufferId })  // → draft for review
+```
+
 ### XHTML Structure Editing
 
 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.
@@ -1643,6 +2167,99 @@ buffer_validate_xhtml({
 **Automatic Validation:**
 XHTML content is automatically validated before Confluence writes (`confluence_draft_create`, `confluence_draft_save`).
 
+### JSON Pipeline Workflows
+
+Use `buffer_pipeline` for efficient server-side data transformation. This eliminates the need to iterate through items in the LLM context.
+
+**Workflow - Search to Table (98% token reduction):**
+```
+1. jira_search_issues(jql) → bufferId with JSON array
+2. buffer_pipeline(bufferId, pipeline) → bufferId with XHTML/CSV/Markdown
+3. Use result directly or insert into Confluence page
+```
+
+**Workflow - Jira Report to Confluence:**
+```typescript
+// 1. Search Jira
+jira_search_issues({ jql: "project = PROJ AND type = Bug" })
+// → { bufferId: "buf_issues", structure: { itemCount: 150 } }
+
+// 2. Transform to table with one call (NOT iterating 150 items!)
+buffer_pipeline({
+  bufferId: "buf_issues",
+  pipeline: {
+    filter: [{ field: "status.name", operator: "ne", value: "Done" }],
+    sort: [{ field: "priority.name", direction: "asc" }],
+    format: [
+      { condition: { field: "priority.name", operator: "eq", value: "High" },
+        style: { color: "#dc3545", bold: true } }
+    ],
+    output: {
+      type: "xhtml_table",
+      table: {
+        title: "Open Bugs",
+        columns: [
+          { field: "key", header: "Issue", link: { type: "jira" } },
+          { field: "summary", header: "Summary" },
+          { field: "priority.name", header: "Priority" }
+        ]
+      }
+    }
+  }
+})
+// → { bufferId: "buf_table", outputItems: 45, preview: "<table>..." }
+
+// 3. Insert into Confluence page
+confluence_edit("DOCS/Bug Report")
+// → { bufferId: "buf_page", pageId: "123", structure: [...] }
+
+buffer_edit({ bufferId: "buf_page", after: 5, fromBufferId: "buf_table" })
+confluence_draft_create({ pageId: "123", bufferId: "buf_page" })
+// → Draft for user review
+```
+
+**Workflow - Statistics Dashboard:**
+```typescript
+// Group issues by assignee with counts
+buffer_pipeline({
+  bufferId: "buf_issues",
+  pipeline: {
+    filter: [{ field: "status.name", operator: "ne", value: "Done" }],
+    groupBy: {
+      field: "assignee.displayName",
+      aggregations: [
+        { function: "count", as: "total" },
+        { function: "list", field: "key", as: "issues" }
+      ]
+    },
+    sort: [{ field: "total", direction: "desc" }],
+    output: {
+      type: "xhtml_table",
+      table: {
+        title: "Work Distribution",
+        columns: [
+          { field: "displayName", header: "Assignee" },
+          { field: "total", header: "Open Issues" },
+          { field: "issues", header: "Issue Keys" }
+        ]
+      }
+    }
+  }
+})
+```
+
+**When to Use `buffer_pipeline`:**
+- Generating tables/lists for Confluence from Jira/Tempo data
+- Creating CSV/Markdown exports
+- Aggregating statistics (count by status, sum time by project, etc.)
+- Filtering and sorting large result sets server-side
+- Any data transformation that doesn't require LLM reasoning
+
+**When NOT to Use `buffer_pipeline`:**
+- When you need to read and understand each item's content
+- When decisions require LLM judgment (e.g., categorizing by sentiment)
+- When output format depends on item content analysis
+
 ### Buffer Lifecycle & Staleness Prevention
 
 **Automatic Invalidation**: When write operations succeed (`confluence_draft_save`, `jira_update_issue`, `tempo_update_worklog`, etc.), any cached buffers for that resource are automatically invalidated.