@crypto512/jicon-mcp 2.2.1 → 2.3.19

package/dist/utils/jicon-help.js

@@ -11,7 +11,7 @@ const TOPICS = ["jql", "cql", "storage", "plantuml", "buffers", "analysis"];
 // Default workflow guide (shown when no topic specified)
 const WORKFLOW_GUIDE = `# Jicon Quick Reference
 
-TOOLS: jira(26) confluence(21) tempo(13) buffer(11) plantuml(3) url(2) date(1) help(1)
+TOOLS: jira, confluence, tempo, buffer, workload, plantuml, url, date, help, whoami
 
 ## Decision Tree - Which Topic?
 
@@ -30,8 +30,11 @@ TOOLS: jira(26) confluence(21) tempo(13) buffer(11) plantuml(3) url(2) date(1) h
 | Search Confluence | \`help(topic="cql")\` |
 | Search Jira | \`jira_get_issue_types()\` then \`help(topic="jql")\` |
 | Non-English Jira fields | \`jira_get_fields(search="epic")\` → use cf[ID] syntax |
+| **Find user for JQL query** | \`jira_search_users(query="name")\` → get username for assignee/reporter JQL |
+| **Issues worked on in period** | \`tempo_get_worklogs(workerKey, dateFrom, dateTo)\` ← NOT JQL created/updated |
 | Log/get time | \`tempo_get_user_info()\` first |
-| **Create table from Jira data** | \`buffer_pipeline(bufferId, pipeline={output:{type:"xhtml_table"}})\` |
+| **Create table for Confluence** | \`buffer_transform(..., code="return toTable(issues,{columns:[...]})")\` → XHTML |
+| **Create table to show user** | \`buffer_transform(..., code="return toMarkdownTable(issues,{columns:[...]})")\` → Markdown |
 | **Iterate items for AI analysis** | \`buffer_get_items(bufferId, start=0, count=50)\` |
 | **Large dataset + AI columns** | Batch workflow - see \`help(topic="buffers")\` |
 | **LLM analysis tools guide** | \`help(topic="analysis")\` |
@@ -129,7 +132,7 @@ const JQL_HELP = `# JQL Syntax Guide
 
 Before writing JQL with type/status names:
 1. Use \`jira_get_issue_types()\` to discover actual type names (e.g., "Epic" vs "Épopée")
-2. Use \`jira_get_fields()\` to discover field names (e.g., "Epic Link" vs "Lien d'épopée")
+2. Use \`jira_get_fields(search="epic")\` to discover field names (e.g., "Epic Link" vs "Lien d'épopée")
 3. Use \`cf[ID]\` syntax for language-independent field queries
 
 The examples below use English names. Replace with your instance's actual values.
@@ -155,27 +158,32 @@ The examples below use English names. Replace with your instance's actual values
 4. Recently updated issues (last 7 days):
    updated >= startOfDay(-7)
 
-5. Issues by assignee:
+5. Issues by assignee (current user):
    assignee = currentUser()
 
-6. Text search in summary/description:
+6. Issues by a specific person (find their username first):
+   jira_search_users(query="Fabien") → returns username (e.g., "fthuillier")
+   assignee = "fthuillier"
+
+7. Text search in summary/description:
    summary~"login" OR description~"login"
 
-7. Date range:
+8. Date range:
    created >= "2025-01-01" AND created <= "2025-01-31"
 
-8. Multiple projects:
+9. Multiple projects:
    project IN (PROJ1, PROJ2, PROJ3)
 
-9. Exclude resolved:
-   resolution = Unresolved
+10. Exclude resolved (language-independent):
+    statusCategory != Done
 
-10. Issues with specific label:
+11. Issues with specific label:
     labels = "urgent" AND status != Done
 
 ## Tips
 - Use jira_get_issue_types first to discover type names for your instance
 - Use jira_get_fields to discover field names in your language
+- Use jira_search_users to find a person's username for assignee/reporter queries
 - Date functions: startOfDay(), startOfWeek(), startOfMonth(), now()
 - Relative dates: startOfDay(-7) = 7 days ago
 - Always quote field values that contain spaces
@@ -211,7 +219,32 @@ The \`clauseNames\` array shows all valid JQL names for a field.
 ## Date Handling Tips
 - "Last week" in business context = previous Mon-Fri (e.g., Dec 8-12)
 - "Rolling 7 days" = use startOfDay(-7)
-- For exact date ranges, use explicit dates: updated >= "2025-12-08" AND updated <= "2025-12-12"`;
+- For exact date ranges, use explicit dates: updated >= "2025-12-08" AND updated <= "2025-12-12"
+
+## Language-Independent Best Practices
+
+**Always use these approaches for reliable JQL across all Jira instances:**
+- Use \`statusCategory != Done\` instead of \`resolution = Unresolved\`
+- Use \`cf[ID]\` syntax for custom fields instead of localized names
+- Tools like \`jira_list_epic_children\` automatically try multiple patterns
+
+## Troubleshooting Common JQL Errors
+
+### "Le champ 'X' n'existe pas" / "Field 'X' does not exist"
+**Cause**: Field name is localized or doesn't exist on this instance
+**Solution**:
+1. Run \`jira_get_fields(search="part_of_name")\` to find the field
+2. Use the \`clauseNames\` value or \`cf[ID]\` syntax
+
+### Query returns 0 results but issues exist
+**Cause**: Type name mismatch (e.g., searching for "Epic" when locale uses "Épopée")
+**Solution**:
+1. Run \`jira_get_issue_types()\` to see actual type names
+2. Use the exact name from the response
+
+### "resolution = Unresolved" not working in non-English instance
+**Cause**: "Unresolved" may not work consistently across all locales
+**Solution**: Use \`statusCategory != Done\` (works in any language)`;
 // CQL syntax guide
 const CQL_HELP = `# CQL Syntax Guide
 
@@ -232,6 +265,8 @@ CQL is largely language-independent:
 ## Critical Warnings
 WARNING: Do NOT use 'content~' or 'body~' - they're invalid! Use 'text~' instead.
 
+WARNING: Do NOT use 'lastmodifiedby' or 'lastmodifier' - they don't exist! Use 'contributor=' instead.
+
 WARNING: WRONG: text~("term1" OR "term2") - Cannot use OR inside the operator
 OK: (text~"term1" OR text~"term2") - Each term needs its own text~ operator
 
@@ -242,35 +277,51 @@ OK: (text~"term1" OR text~"term2") - Each term needs its own text~ operator
 2. Pages created by a person:
    type=page AND creator="username"
 
-3. Pages with specific label:
+3. Pages I created OR edited:
+   contributor=currentUser() ORDER BY lastmodified DESC
+
+4. Pages with specific label:
    type=page AND label="meeting-notes"
 
-4. Pages in space modified recently:
+5. Pages in space modified recently:
    space=DOCS AND lastmodified >= now("-30d") ORDER BY lastmodified DESC
 
-5. Text search in a space:
+6. Text search in a space:
    text~"API" AND space=DOCS AND type=page
 
-6. Date range:
+7. Date range:
    lastmodified >= "2025-01-01" AND lastmodified <= "2025-01-31"
 
-7. Multiple spaces:
+8. Multiple spaces:
    space IN (DOCS, PROJ, WIKI)
 
-8. Pages by title pattern:
+9. Pages by title pattern:
    type=page AND title~"Sprint Review" ORDER BY created DESC
 
-9. Find by creator name:
-   creator.fullname~"Alex Morgan"
+10. Find by creator name:
+    creator.fullname~"Alex Morgan"
 
-10. Pages created this week:
+11. Pages created this week:
     type=page AND created >= startOfWeek()
 
 ## Tips
 - Use space KEY (e.g., 'DOCS') not space name (e.g., 'Documentation')
 - Date functions: now(), startOfDay(), startOfWeek(), startOfMonth()
 - Relative dates: now("-7d") = 7 days ago
-- Results are always buffered - use buffer_get_items to read, buffer_grep to search`;
+- Results are always buffered - use buffer_get_items to read, buffer_grep to search
+
+## User Fields
+
+| Field | Meaning |
+|-------|---------|
+| creator | Original author only |
+| contributor | Created OR edited |
+
+## Invalid Fields
+
+These do NOT exist in CQL:
+- lastmodifiedby, lastmodifier → use contributor=
+- content~, body~ → use text~`;
 // Confluence storage format (XHTML syntax only)
 const STORAGE_FORMAT_HELP = `# Confluence Storage Format (XHTML)
 
@@ -669,6 +720,7 @@ When editing existing pages, you can create content in a separate buffer and mer
 | \`buffer_get_element(bufferId, elementId)\` | Get raw XHTML of specific element |
 | \`buffer_get_items(bufferId, start, count)\` | Get JSON items by index (arrays) or key (objects) |
 | \`buffer_set_items(bufferId, itemId?, append?, data)\` | Update/append JSON items by ID (arrays) or merge keys (objects) |
+| \`buffer_get_schema(bufferId)\` | Get schema with field types and samples (JSON) |
 | \`buffer_grep(bufferId, pattern, "-C"=2)\` | Search with context |
 | \`buffer_validate_xhtml(bufferId)\` | Check XHTML validity |
 | \`buffer_list()\` | See all active buffers |
@@ -686,109 +738,56 @@ buffer_edit(bufferId, old_string="foo", new_string="bar", replace_all=true)
 buffer_edit(bufferId, append=true, content="text to add at end")
 \`\`\`
 
-## JSON Pipeline (buffer_pipeline) - RECOMMENDED
-
-Transform JSON buffers with a declarative pipeline: filter, group, sort, format, output.
+## JavaScript Sandbox (buffer_transform)
 
-**98% token reduction** for data transformations - no need to iterate through items!
+Transform JSON buffers with JavaScript code in a secure sandbox.
 
 **Basic workflow:**
 \`\`\`
-1. jira_search_issues(jql="...") → { bufferId, structure: { itemCount: 578 } }
-
-2. buffer_pipeline(bufferId, pipeline={
-     filter: [{ field: "status.name", operator: "ne", value: "Done" }],
-     sort: [{ field: "priority.name", direction: "asc" }],
-     output: {
-       type: "xhtml_table",
-       table: {
-         title: "Open Issues",
-         columns: [
-           { field: "key", header: "Issue", link: { type: "jira" } },
-           { field: "summary", header: "Summary" },
-           { field: "priority.name", header: "Priority" }
-         ]
-       }
-     }
-   })
-   → { bufferId: "buf_new", outputItems: 45, preview: "..." }
-
-3. Insert into Confluence page or use directly
-\`\`\`
-
-**Pipeline stages (all optional except output):**
-- \`select\`: Extract and rename fields
-- \`filter\`: Filter items (eq, ne, contains, in, regex, etc.)
-- \`groupBy\`: Group and aggregate (count, sum, avg, list, etc.)
-- \`sort\`: Sort by fields
-- \`limit\`: Limit results
-- \`format\`: Conditional styling (colors, bold, icons)
-- \`output\`: Generate output (xhtml_table, xhtml_list, json, csv, markdown)
-
-**Schema Quick Reference:**
-\`\`\`
-pipeline: {
-  select?: { fields: [{from: "path", as: "name", transform?: "..."}] },
-  filter?: [{ field, operator, value }],
-  groupBy?: { field, aggregations: [{function, field?, as}] },
-  sort?: [{ field, direction: "asc"|"desc" }],  // NOT "sortBy"!
-  limit?: number,
-  format?: [...],
-  output: { type: "xhtml_table"|"json"|"csv"|..., table?: {...} }
-}
+1. jira_search_issues(jql="...") → { bufferId }
+2. buffer_get_schema(bufferId)  # See available fields with samples
+3. buffer_transform(inputs: { issues: bufferId }, code: "return toTable(...)")
+4. confluence_draft_create(bufferId) or display to user
 \`\`\`
 
-**Common Mistakes:**
-| Wrong | Correct |
-|-------|---------|
-| sortBy: [...] | sort: [...] |
-| transform: "map" | transform: "date" (or uppercase, lowercase, number, boolean, string) |
-| No output | output: {...} (REQUIRED) |
-| pipeline: "{...}" | pipeline: {...} (object, not string) |
-
-**After select renames fields, use NEW names in subsequent stages:**
-- select: {from: "issueType", as: "Type"}
-- sort: [{field: "Type"}] ✓ (not "issueType")
-
-**Filter operators:** eq, ne, gt, lt, gte, lte, contains, startsWith, endsWith, in, notIn, exists, notExists, regex, empty, notEmpty
-
-**Aggregations:** count, sum, avg, min, max, first, last, list, unique
-
-**Example - Statistics by assignee:**
-\`\`\`
-buffer_pipeline(bufferId, 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",
+**OUTPUT FORMAT - CHOOSE BY DESTINATION:**
+
+| Destination | Formatters | Result |
+|-------------|-----------|--------|
+| **Confluence page** | toTable(), toList() | XHTML |
+| **Display to user** | toMarkdownTable(), toMarkdownList() | Markdown |
+
+⚠️ **Common mistake**: Using toTable() when you want to display to user. Use toMarkdownTable() instead!
+
+**Built-in helpers:** groupBy, sum, avg, min, max, count, unique, get, pick, omit, parseDate, formatDate, daysBetween, JIRA_URL, CONFLUENCE_URL
+
+**Example - Table for user display:**
+\`\`\`javascript
+buffer_transform(
+  inputs: { issues: bufferId },
+  code: \`
+    const open = issues.filter(i => i.status !== 'Done');
+    return toMarkdownTable(open, {
       columns: [
-        { field: "displayName", header: "Assignee" },
-        { field: "total", header: "Open Issues" },
-        { field: "issues", header: "Issue Keys" }
+        { field: 'key', header: 'Issue', link: { type: 'jira' } },
+        { field: 'summary', header: 'Summary' },
+        { field: 'assignee', header: 'Assignee' }
       ]
-    }
-  }
-})
+    });
+  \`
+)
 \`\`\`
 
-**When to use buffer_pipeline:**
-- Generating tables/lists for Confluence
-- Creating CSV/Markdown exports
-- Aggregating statistics
-- Filtering and sorting large result sets server-side
+**When to use buffer_transform:**
+- Generating tables/lists for Confluence or user display
+- Custom filtering and transformation logic
+- Aggregating statistics across multiple buffers
+
+**When NOT to use buffer_transform:**
+- When you need LLM judgment on each item (use buffer_get_items)
+- When decisions require analyzing content semantically
 
-**When NOT to use buffer_pipeline:**
-- When you need LLM judgment on each item
-- When decisions require analyzing content (use buffer_get_items instead)
+**For formatter details:** See TOOL_LIST.md or tool description for toTable/toList config options.
 
 ## Decision Forks (Choose Your Path)
 
@@ -798,29 +797,30 @@ After jira_search_issues/tempo_get_worklogs returns a bufferId, you have OPTIONS
 |---------------|-------------|--------|
 | READ/ANALYZE items with AI | buffer_get_items(start=0, count=50) | Get items for analysis |
 | SEARCH within results | buffer_grep(pattern) | Find matching items |
-| FORMAT for Confluence | buffer_pipeline → xhtml_table | TERMINAL: publish-ready |
-| TRANSFORM and keep flexible | buffer_pipeline → json | Can process again |
-| EXPORT to file | buffer_pipeline → csv/markdown | TERMINAL: file-ready |
+| FORMAT for Confluence | buffer_transform → toTable/toList | XHTML → confluence_draft_create |
+| FORMAT to show user | buffer_transform → toMarkdownTable/toMarkdownList | Markdown → display directly |
+| TRANSFORM and keep flexible | buffer_transform → return array | JSON → can process again |
 
 **⚠️ OUTPUT TYPE CONSEQUENCES:**
 | Type | Can Iterate Items? | Can Edit? | Next Steps |
 |------|-------------------|-----------|------------|
-| json | ✓ buffer_get_items | ✓ buffer_pipeline | Further processing, re-transform |
-| xhtml_* | ✗ (not iterable) | ✓ buffer_edit | confluence_draft_create |
-| csv/md | ✗ (not iterable) | ✓ buffer_edit | buffer_grep |
+| json | ✓ buffer_get_items | ✓ buffer_transform | Further processing, re-transform |
+| xhtml | ✗ (not iterable) | ✓ buffer_edit | confluence_draft_create |
+| markdown | ✗ (not iterable) | ✓ buffer_edit | Display to user |
 
 **Choose json** if you need to iterate items for AI analysis (buffer_get_items).
-**Choose xhtml_*** when ready to publish - you can still edit elements, but can't iterate.
+**Choose xhtml (toTable/toList)** when publishing to Confluence.
+**Choose markdown (toMarkdownTable/toMarkdownList)** when displaying results to user.
 
 ---
 
 ## Large Dataset Patterns
 
 ### Simple table (no AI analysis)
-Use \`buffer_pipeline\` - generates complete table in **ONE tool call**:
+Use \`buffer_transform\` with \`toTable\` - generates complete table in **ONE tool call**:
 \`\`\`
 jira_search_issues(jql="...") → bufferId (500+ items)
-buffer_pipeline(bufferId, pipeline={output:{type:"xhtml_table",...}}) → complete table!
+buffer_transform(inputs:{issues:bufferId}, code:"return toTable(issues,{columns:[...]})") → complete table!
 \`\`\`
 
 ### Table with AI-enhanced columns (complexity, impact)
@@ -861,7 +861,7 @@ For cases where you need to read and analyze the data (not just transform it):
 
 Use these when:
 - You need to understand the content to make decisions
-- You're writing custom analysis that can't be expressed as a pipeline
+- You're writing custom analysis that requires LLM reasoning on content
 - You're building tables with AI-enhanced columns (batch workflow)
 
 ## Common Errors & Recovery
@@ -893,191 +893,21 @@ const ANALYSIS_HELP = `# LLM-Powered Analysis Tools
 These **intelligent entry points** return pre-processed data **directly to the LLM** (not buffered) for analysis and insight generation. Unlike regular tools that buffer data for transformation, these tools are designed for AI synthesis.
 
 **Key Difference:**
-- **Regular tools** → Buffer data → Use buffer_pipeline for transformation → Token-efficient
+- **Regular tools** → Buffer data → Use buffer_transform for transformation → Token-efficient
 - **Analysis tools** → Return markdown directly to LLM → Enable AI insight and synthesis
 
-## When to Use Analysis Tools
-
-| Task | Tool | Example Query |
-|------|------|---------------|
-| What happened on project X? | \`jira_get_activity_digest\` | "What happened on PROJ this week?" |
-| Any blockers in discussions? | \`jira_get_recent_comments\` | "Are there blockers mentioned in recent comments?" |
-| Track field changes | \`jira_get_changelog\` | "What issues had priority escalations?" |
-| Deep Epic analysis | \`jira_analyze_epic\` | "Analyze Epic PROJ-100 for risks and progress" |
-| Sprint progress & risks | \`jira_analyze_sprint\` | "How is Sprint 42 progressing?" |
-| Quick Epic status | \`jira_epic_summary\` | "Quick status of Epic PROJ-100" |
-| List Epic children | \`jira_list_epic_children\` | "List open Stories in PROJ-100" |
-| Top issues by workload | \`tempo_get_top_worklogs\` | "Which issues had most work last week?" |
-
-## Tool Details
-
-### jira_get_activity_digest
-Fetches comments, status/priority/assignee changes across issues.
-
-\`\`\`
-jira_get_activity_digest(
-  projectKey="ACME",      // or jql="..." or issueKeys=[...]
-  since="7d",             // "1d", "7d", "30d", or ISO date
-  includeComments=true,
-  includeStatusChanges=true,
-  includePriorityChanges=true,
-  includeAssigneeChanges=true
-)
-\`\`\`
-
-**Returns**: Markdown with activities grouped by issue + summary statistics:
-- Issues with activity count
-- Status changes (with "to Done" breakdown)
-- Priority escalations
-- New comments count
-
-### jira_get_recent_comments
-Aggregates comments across multiple issues for discussion analysis.
-
-\`\`\`
-jira_get_recent_comments(
-  projectKey="ACME",
-  since="7d",
-  authorKey="john",       // optional: filter by author
-  maxComments=30
-)
-\`\`\`
-
-**Returns**: Markdown with comments grouped by issue + context (status).
-
-### jira_get_changelog
-Tracks field changes across issues.
-
-\`\`\`
-jira_get_changelog(
-  projectKey="ACME",
-  since="7d",
-  fields=["status", "priority", "assignee", "resolution"],
-  maxChanges=50
-)
-\`\`\`
-
-**Returns**: Markdown with changes grouped by issue + field breakdown.
+## Tool Quick Reference
 
-### jira_analyze_epic
-Comprehensive Epic/Feature analysis for deep insights.
-
-\`\`\`
-jira_analyze_epic(
-  issueKey="PROJ-100",
-  includeComments=true,
-  commentDays=14,
-  maxComments=5
-)
-\`\`\`
-
-**Returns**: Comprehensive markdown analysis including:
-- **Hierarchy**: Epic → Stories → Subtasks with completion %
-- **Time Metrics**: Spent vs estimated, burn rate, overrun warnings
-- **Progress Indicators**: Velocity, in-flight issues
-- **Architecture Context**: Components, labels
-- **Linked Resources**: Confluence pages, related issues
-- **Recent Discussions**: Technical comments for context
-
-**Example output snippet:**
-\`\`\`markdown
-## Issue Hierarchy
-| Type | Total | Done | In Progress | To Do | Completion |
-|------|-------|------|-------------|-------|------------|
-| Story | 5 | 3 | 1 | 1 | 60% |
-| Sub-task | 12 | 8 | 2 | 2 | 67% |
-
-## Time Metrics
-- Time Spent: 2w 3d
-- Original Estimate: 3w
-- Burn Rate: 77% of estimate consumed
-- ⚠️ Overrun: 2d over estimate
-
-## Analysis Summary
-This Epic contains **17 issues** with **65% completion**.
-⚠️ **77% of time used but only 65% complete** - at risk of overrun.
-\`\`\`
-
-### jira_analyze_sprint
-Comprehensive Sprint analysis for progress, risks, and team distribution.
-
-\`\`\`
-jira_analyze_sprint(
-  sprintId=123,           // from jira_get_sprints(boardId)
-  includeComments=true,
-  commentDays=7,
-  includeRisks=true
-)
-\`\`\`
-
-**How to find sprintId**: Call \`jira_get_sprints(boardId)\` first. BoardId can be found in Jira URLs like \`/secure/RapidBoard.jspa?rapidView=123\`.
-
-**Returns**: Comprehensive markdown analysis including:
-- **Sprint Metadata**: Dates, duration, days remaining
-- **Progress**: Completion %, status breakdown (Done/In Progress/To Do)
-- **Issue Breakdown**: By type and status
-- **Time Metrics**: Estimated vs spent vs remaining, burn rate
-- **Team Distribution**: Who's working on what
-- **Risk Indicators**: Stale issues, blocked, high-priority unstarted
-- **Recent Discussions**: Comments from team
-
-**Example output snippet:**
-\`\`\`markdown
-# Sprint Analysis: Sprint 42
-
-**State**: Active
-**Period**: Jan 20 - Feb 3 (14 days)
-**Progress**: Day 10 of 14 (4 days remaining)
-
-## Sprint Progress
-**Completion**: 65% (13 of 20 issues done)
-
-## Risk Indicators
-⚠️ **3 issues at risk:**
-- PROJ-456: In Progress for 5 days without update
-- PROJ-789: High priority, still To Do
-\`\`\`
-
-### jira_epic_summary
-Lightweight Epic status - no time metrics, no comments, no Confluence links.
-
-\`\`\`
-jira_epic_summary(
-  issueKey="PROJ-100",
-  includeLinks=true,      // cross-project dependencies
-  maxDepth=3              // hierarchy depth
-)
-\`\`\`
-
-**Returns**: Quick markdown with hierarchy list, status breakdown, cross-project dependencies.
-
-### jira_list_epic_children
-List Epic children without needing JQL. Auto-detects Epic Link and Parent Link fields.
-
-\`\`\`
-jira_list_epic_children(
-  parentKey="PROJ-100",
-  type="Story",           // optional: filter by type
-  status="open",          // "open", "closed", "all"
-  recursive=false         // true for nested children
-)
-\`\`\`
-
-**Returns**: Buffered results (same format as jira_search_issues).
-
-### tempo_get_top_worklogs
-Top issues or users by workload. Returns directly to LLM.
-
-\`\`\`
-tempo_get_top_worklogs(
-  since="last_week",      // date expression
-  projectKey="PROJ",      // optional filter
-  groupBy="issue",        // "issue" or "user"
-  limit=10
-)
-\`\`\`
-
-**Returns**: Markdown table with ranked results + totals.
+| Tool | Purpose | Best For |
+|------|---------|----------|
+| \`jira_get_activity_digest\` | Recent activity across issues | "What happened on PROJ this week?" |
+| \`jira_get_recent_comments\` | Discussion analysis | "Any blockers in recent discussions?" |
+| \`jira_get_changelog\` | Track field changes | "What issues had priority escalations?" |
+| \`jira_analyze_epic\` | Deep Epic analysis | "Analyze Epic PROJ-100 for risks" |
+| \`jira_analyze_sprint\` | Sprint progress & risks | "How is Sprint 42 progressing?" |
+| \`jira_epic_summary\` | Quick Epic status | "Quick status of Epic PROJ-100" |
+| \`jira_list_epic_children\` | List Epic children | "List open Stories in PROJ-100" |
+| \`tempo_get_top_worklogs\` | Top issues by workload | "Which issues had most work?" |
 
 ## Scoping Parameters
 
@@ -1101,31 +931,53 @@ Use \`date_resolve(expression)\` to preview date ranges:
 date_resolve("this_week") → { dateFrom: "2025-01-27", dateTo: "2025-01-31", businessDays: 5 }
 \`\`\`
 
-## vs Buffer Pipeline
+## Choosing the Right Tool
+
+### Activity & Discussions
+- **What happened?** → \`jira_get_activity_digest(projectKey, since="7d")\`
+- **What are people saying?** → \`jira_get_recent_comments(projectKey, since="7d")\`
+- **What changed?** → \`jira_get_changelog(projectKey, fields=["status","priority"])\`
+
+### Epic Analysis
+- **Full Epic analysis** (time, comments, links) → \`jira_analyze_epic(issueKey)\`
+- **Quick Epic status** (no time metrics) → \`jira_epic_summary(issueKey)\`
+- **List Epic children** (buffered for transform) → \`jira_list_epic_children(parentKey)\`
+
+### Sprint Analysis
+- **Sprint health check** → \`jira_analyze_sprint(sprintId)\`
+  - Find sprintId: \`jira_get_sprints(boardId)\`
+  - Find boardId: \`jira_list_boards()\` or from URL \`/rapidView=123\`
+
+### Time Tracking
+- **Top issues by workload** → \`tempo_get_top_worklogs(since, groupBy="issue")\`
+- **Top contributors** → \`tempo_get_top_worklogs(since, groupBy="user")\`
+
+## vs Buffer Transform
 
 | Need | Use |
 |------|-----|
 | AI analysis and insights | **Analysis tools** (direct to LLM) |
-| Generate Confluence table | \`buffer_pipeline\` (token efficient) |
-| Export to CSV/JSON | \`buffer_pipeline\` (server-side transform) |
-| Filter/sort/aggregate data | \`buffer_pipeline\` (declarative) |
+| Generate Confluence table | \`buffer_transform\` (sandbox transform) |
+| Export to CSV/JSON | \`buffer_transform\` (sandbox transform) |
+| Filter/sort/aggregate data | \`buffer_transform\` (JavaScript code) |
 
 **Analysis tools** are for questions requiring AI judgment:
 - "What are the risks?"
 - "Summarize the discussions"
 - "What needs attention?"
 
-**Buffer pipeline** is for data transformation:
+**Buffer transform** is for data transformation:
 - "Create a table of open issues"
 - "Group by assignee and count"
-- "Export to CSV"
+- "Filter and format data for Confluence"
 
 ## Tips
 
 - Use \`date_resolve\` to understand date ranges before querying
 - Start with smaller \`maxActivities\`/\`maxComments\` for faster responses
 - Combine with \`jira_search_issues\` to narrow scope first if needed
-- Analysis tools return markdown directly - no buffering needed`;
+- Analysis tools return markdown directly - no buffering needed
+- For parameter details, see tool descriptions or TOOL_LIST.md`;
 // Topic content map
 const TOPIC_CONTENT = {
     jql: JQL_HELP,

package/dist/utils/jicon-help.js.map

@@ -1 +1 @@
-{"version":3,"file":"jicon-help.js","sourceRoot":"","sources":["../../src/utils/jicon-help.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAErE,mBAAmB;AACnB,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AAGrF,yDAAyD;AACzD,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8GtB,CAAC;AAEF,mBAAmB;AACnB,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iGA0FgF,CAAC;AAElG,mBAAmB;AACnB,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oFAyDmE,CAAC;AAErF,gDAAgD;AAChD,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kDAsKsB,CAAC;AAEnD,+EAA+E;AAC/E,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kDAqI4B,CAAC;AAEnD,sDAAsD;AACtD,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCAqTkB,CAAC;AAExC,gCAAgC;AAChC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gEA+O0C,CAAC;AAEjE,oBAAoB;AACpB,MAAM,aAAa,GAA0B;IAC3C,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,QAAQ;IACb,OAAO,EAAE,mBAAmB;IAC5B,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE,aAAa;CACxB,CAAC;AAEF,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,IAAI,EAAE;YACJ,WAAW,EAAE;;;;;;;;;;;;;;;;qDAgBkC;YAC/C,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;gBACpB,KAAK,EAAE,CAAC;qBACL,IAAI,CAAC,MAAM,CAAC;qBACZ,QAAQ,EAAE;qBACV,QAAQ,CACP,qFAAqF,CACtF;aACJ,CAAC;YACF,OAAO,EAAE,KAAK,EAAE,IAAuB,EAA2B,EAAE;gBAClE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;gBAEvB,kCAAkC;gBAClC,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,OAAO,aAAa,CAAC;wBACnB,KAAK,EAAE,cAAc;qBACtB,CAAC,CAAC;gBACL,CAAC;gBAED,qCAAqC;gBACrC,IAAI,KAAK,IAAI,aAAa,EAAE,CAAC;oBAC3B,OAAO,aAAa,CAAC;wBACnB,KAAK;wBACL,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC;qBAC5B,CAAC,CAAC;gBACL,CAAC;gBAED,yEAAyE;gBACzE,OAAO,WAAW,CAAC;oBACjB,KAAK,EAAE,IAAI;oBACX,OAAO,EAAE,mBAAmB,KAAK,wBAAwB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;oBAC5E,UAAU,EAAE,GAAG;iBAChB,CAAC,CAAC;YACL,CAAC;SACF;KACF,CAAC;AACJ,CAAC;AAED,0BAA0B;AAC1B,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,CAAU,CAAC;AAElD,uCAAuC;AACvC,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"jicon-help.js","sourceRoot":"","sources":["../../src/utils/jicon-help.ts"],"names":[],"mappings":"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"}