@fink-andreas/pi-linear-tools 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## v0.7.0 (2026-05-05)
+
+Issue image fetching and file download release.
+
+### New Features
+- **`linear_issue(action="images")`**: Fetch markdown/HTML embedded images from issue descriptions and comments. Returns images as tool `image` content (base64-encoded). Includes special auth handling for Linear upload URLs (`uploads.linear.app`).
+- **`linear_issue(action="download")`**: Download Linear issue attachments to local filesystem. Supports attachment selection by ID, title, URL, or index. Includes relative path validation, filename sanitization, and `allow_overwrite_files` config guard (default: `false`).
+
+### Performance / API Usage
+- **N+1 issue resolution optimization**: Merged N+1-per-issue lazy loads in milestone details into a single GraphQL batch query (introduced in v0.6.0).
+
+### Documentation
+- **Updated smoke tests**: Added coverage for `images` and `download` actions.
+
+### Bug Fixes
+- **Fixed workspace-wide issue listing (#4)**: `linear_issue list` now falls back to workspace-level listing (using `fetchIssues`) when no project is specified and cwd doesn't match a Linear project. This allows `linear_issue list assignee=me` to work without requiring a project context.
+- Fixed project archive mutation to actually archive instead of delete (INN-301).
+- Fixed `linear_issue comment` to render submitted comment text in result (INN-305).
+- Fixed rate limit display to not show hardcoded total=5000 (INN-304).
+- Fixed `linear_project` and `linear_project_update` to have rate-limit pre-check (INN-303).
+
+## v0.6.0 (2026-04-23)
+
+Rate-limit resilience for milestone operations.
+
+### Bug Fixes
+- **Fixed linear_milestone view rate-limit crash**: `linear_milestone view` no longer crashes when hitting Linear API rate limits. Errors are now properly surfaced as safe tool results instead of propagating as crashes.
+- **Fixed milestone issues rate-limit swallowing**: `fetchMilestoneDetails()` now correctly propagates rate-limit errors from lazy-loaded issue data instead of silently returning partial results.
+
+### Performance / API Usage
+- **Replaced N+1 lazy loading with single GraphQL query**: Milestone details now fetch all issue state/assignee in ONE request instead of N+1 per-issue lazy loads. This dramatically reduces API calls and rate-limit exposure for large milestones.
+- **Added cached rate-limit pre-check**: `linear_milestone` now has the same cached pre-check that `linear_issue` uses to short-circuit before making API calls when the cache already knows about a rate limit.
+- **Exported `isRateLimitError()` helper**: Made available for consistent error handling across tools.
+
+### Documentation
+- **Reorganized README**: Moved Key Concepts section for better onboarding
+- **Added combined Linear+Pi logo**: Light/dark theme support for branding
+
 ## v0.5.1 (2026-04-17)
 
 ### Bug Fixes

package/README.md

@@ -1,20 +1,14 @@
 # pi-linear-tools
 
-`pi-linear-tools` is a Pi extension for the [Pi coding agent](https://github.com/badlogic/pi-mono) that lets you manage [Linear](https://linear.app/about) issues, projects, and milestones via LLM tools and CLI commands.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/images/linear-pi-combined-white.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/images/linear-pi-combined-black.svg">
+    <img src="docs/images/linear-pi-combined-black.svg" alt="Linear + Pi" width="340">
+  </picture>
+</p>
 
-Useful mental model:
-- `issue update` changes issue fields; `issue comment` adds discussion; `issue activity` reads the Activity timeline
-- `project update` changes project fields; `project-update` manages Updates tab entries
-- `project-update` maps to Linear project updates in the Updates tab
-- `sync-doc init` scaffolds `.linear-tools/config.json` in the folder you point at
-- `sync-doc run` and `sync-doc check` default to all configured targets in `.linear-tools/config.json`
-- `sync-doc --target X` narrows the operation to one configured target
-
-Reference conventions:
-- issues use issue key or issue ID
-- projects use project name or project ID
-- project updates use project update ID
-- milestones use milestone ID
+`pi-linear-tools` is a token eficcient Pi extension for the [Pi coding agent](https://github.com/badlogic/pi-mono) that lets you manage [Linear](https://linear.app/about) issues, projects, and milestones via LLM tool calls and CLI commands.
 
 ## Install
 
@@ -47,6 +41,7 @@ Optional non-interactive commands:
 /linear-tools-config --api-key lin_xxx
 /linear-tools-config --default-team ENG
 /linear-tools-config --team ENG --project "My Project"
+/linear-tools-config --allow-overwrite-files true|false
 ```
 
 ## Extension commands
@@ -54,10 +49,30 @@ Optional non-interactive commands:
 - `/linear-tools-config`
 - `/linear-tools-help`
 
+## Key Concepts
+
+Useful mental model:
+- `issue update` changes issue fields; `issue comment` adds discussion; `issue activity` reads the Activity timeline
+- `project update` changes project fields; `project-update` manages Updates tab entries
+- `project-update` maps to Linear project updates in the Updates tab
+- `sync-doc init` scaffolds `.linear-tools/config.json` in the folder you point at
+- `sync-doc run` and `sync-doc check` default to all configured targets in `.linear-tools/config.json`
+- `sync-doc --target X` narrows the operation to one configured target
+
+Reference conventions:
+- issues use issue key or issue ID
+- projects use project name or project ID
+- project updates use project update ID
+- milestones use milestone ID
+
 ## LLM-callable tools
 
 ### `linear_issue`
-Actions: `list`, `view`, `activity`, `create`, `update`, `comment`, `start`, `delete`
+Actions: `list`, `view`, `images`, `download`, `activity`, `create`, `update`, `comment`, `start`, `delete`
+
+`images` fetches image URLs embedded in issue markdown/comments and returns image content inline.
+
+`download` fetches Linear issue attachments only. Destination directories must be relative paths. Existing files are not overwritten unless both `overwrite: true` is provided and the config guard is enabled with `/linear-tools-config --allow-overwrite-files true`.
 
 ### `linear_project`
 Actions: `list`, `view`, `create`, `update`, `delete`, `archive`, `unarchive`
@@ -84,11 +99,12 @@ pi-linear-tools config
 pi-linear-tools config --api-key lin_xxx
 pi-linear-tools config --default-team ENG
 pi-linear-tools config --team ENG --project "My Project"
+pi-linear-tools config --allow-overwrite-files true|false
 ```
 
 ### Issue commands
 
-Use `update` to change the issue itself. Use `comment` to add discussion. Use `activity` to read the Activity timeline shown in Linear.
+Use `update` to change the issue itself. Use `comment` to add discussion. Use `activity` to read the Activity timeline shown in Linear. Use `images` to fetch image attachments embedded in issue markdown/comments.
 
 ```bash
 # List issues
@@ -100,10 +116,18 @@ pi-linear-tools issue list --project "My Project" --assignee me
 pi-linear-tools issue view ENG-123
 pi-linear-tools issue view ENG-123 --no-comments
 
+# Fetch markdown-embedded issue/comment images
+pi-linear-tools issue images ENG-123
+pi-linear-tools issue images ENG-123 --limit 5
+
 # Read Activity timeline
 pi-linear-tools issue activity ENG-123 --limit 20
 pi-linear-tools issue activity https://linear.app/workspace/issue/ENG-123/example --limit 20
 
+# Download a Linear issue attachment
+pi-linear-tools issue download ENG-123 --attachment-index 1 --directory downloads
+pi-linear-tools issue download ENG-123 --attachment-id att_xxx --directory downloads --filename spec.pdf
+
 # Create issue
 pi-linear-tools issue create --title "Fix login bug" --team ENG
 pi-linear-tools issue create --title "New feature" --team ENG --project "My Project" --priority 2 --assignee me
@@ -114,6 +138,10 @@ pi-linear-tools issue update ENG-123 --title "Updated title" --assignee me
 pi-linear-tools issue update ENG-123 --milestone "Sprint 1"
 pi-linear-tools issue update ENG-123 --sub-issue-of ENG-100
 
+# Issue priority uses Linear's native scale: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low.
+# You can also use aliases: none, urgent, high, medium, low.
+pi-linear-tools issue update ENG-123 --priority urgent
+
 # Comment on issue
 pi-linear-tools issue comment ENG-123 --body "This is fixed in PR #456"
 pi-linear-tools issue comment ENG-123 --body "Blocked on API review"

package/extensions/pi-linear-tools.js

@@ -1,5 +1,5 @@
 import { loadSettings, saveSettings } from '../src/settings.js';
-import { createLinearClient, checkAndClearRateLimit, markRateLimited, getClientRequestMetrics } from '../src/linear-client.js';
+import { createLinearClient, checkAndClearRateLimit, markRateLimited, getClientRequestMetrics, getClientRateLimitInfo } from '../src/linear-client.js';
 import { setQuietMode, debug } from '../src/logger.js';
 import {
   resolveProjectRef,
@@ -48,6 +48,8 @@ try {
 import {
   executeIssueList,
   executeIssueView,
+  executeIssueImages,
+  executeIssueDownload,
   executeIssueActivity,
   executeIssueCreate,
   executeIssueUpdate,
@@ -120,12 +122,13 @@ async function createAuthenticatedClient() {
   return createLinearClient(await getLinearAuth());
 }
 
-async function withRequestUsageLogging(client, toolName, action, operation) {
+async function withRequestUsageLogging(client, toolName, action, operation, rateLimitDebug = false) {
   const before = getClientRequestMetrics(client);
 
   try {
     const result = await operation();
     const after = getClientRequestMetrics(client);
+    const rateLimitInfo = rateLimitDebug ? getClientRateLimitInfo(client) : null;
 
     const usageDelta = {
       tool: toolName,
@@ -139,17 +142,63 @@ async function withRequestUsageLogging(client, toolName, action, operation) {
 
     debug('[pi-linear-tools] API usage per command', usageDelta);
 
-    if (!INCLUDE_USAGE_SUMMARY || !result || typeof result !== 'object') {
+    if (rateLimitDebug && rateLimitInfo) {
+      debug('[pi-linear-tools] Rate limit status', {
+        tool: toolName,
+        action,
+        requestsDelta: usageDelta.requestsDelta,
+        rateLimitUsed: rateLimitInfo.used,
+        rateLimitTotal: rateLimitInfo.total,
+        rateLimitRemaining: rateLimitInfo.remaining,
+        rateLimitPercent: rateLimitInfo.usagePercent,
+        rateLimitResetAt: rateLimitInfo.resetTime,
+      });
+    }
+
+    // When rateLimitDebug is true, always include rate limit info in result details
+    // even if INCLUDE_USAGE_SUMMARY is disabled
+    if (!result || typeof result !== 'object') {
       return result;
     }
 
     const details = (result.details && typeof result.details === 'object') ? result.details : {};
+
+    // Add rate limit info to details if debug is enabled
+    if (rateLimitDebug && rateLimitInfo) {
+      details.rateLimit = {
+        ...rateLimitInfo,
+        requestsDelta: usageDelta.requestsDelta,
+      };
+    }
+
+    if (!INCLUDE_USAGE_SUMMARY && !rateLimitDebug) {
+      return {
+        ...result,
+        details,
+      };
+    }
+
     const content = Array.isArray(result.content)
       ? result.content.map((item, idx) => {
         if (idx !== 0 || item?.type !== 'text' || typeof item.text !== 'string') return item;
+        let appendedText = item.text;
+
+        if (INCLUDE_USAGE_SUMMARY) {
+          appendedText += `\n\n_${usageDelta.summary}_`;
+        }
+
+        if (rateLimitDebug && rateLimitInfo) {
+          const percent = rateLimitInfo.usagePercent === null ? 'unknown' : `${rateLimitInfo.usagePercent}%`;
+          const windowUsage = rateLimitInfo.remaining === null
+            ? 'request window: unknown'
+            : `request window: ${rateLimitInfo.used}/${rateLimitInfo.total} used (${percent})`;
+          const reset = rateLimitInfo.resetTime ? ` • Resets at ${rateLimitInfo.resetTime}` : '';
+          appendedText += `\n\n---\n**Rate Limit**: +${usageDelta.requestsDelta} requests this call | ${windowUsage}${reset}`;
+        }
+
         return {
           ...item,
-          text: `${item.text}\n\n_${usageDelta.summary}_`,
+          text: appendedText,
         };
       })
       : result.content;
@@ -159,11 +208,12 @@ async function withRequestUsageLogging(client, toolName, action, operation) {
       content,
       details: {
         ...details,
-        apiUsage: usageDelta,
+        ...(INCLUDE_USAGE_SUMMARY ? { apiUsage: usageDelta } : {}),
       },
     };
   } catch (error) {
     const after = getClientRequestMetrics(client);
+    const rateLimitInfo = rateLimitDebug ? getClientRateLimitInfo(client) : null;
 
     debug('[pi-linear-tools] API usage per command (error)', {
       tool: toolName,
@@ -173,6 +223,13 @@ async function withRequestUsageLogging(client, toolName, action, operation) {
       failedDelta: after.failed - before.failed,
       rateLimitedDelta: after.rateLimited - before.rateLimited,
       error: String(error?.message || error || 'unknown'),
+      ...(rateLimitDebug && rateLimitInfo ? {
+        requestsDelta: after.total - before.total,
+        rateLimitUsed: rateLimitInfo.used,
+        rateLimitTotal: rateLimitInfo.total,
+        rateLimitRemaining: rateLimitInfo.remaining,
+        rateLimitPercent: rateLimitInfo.usagePercent,
+      } : {}),
     });
 
     throw error;
@@ -460,21 +517,35 @@ function toToolTextResult(text, details = {}) {
 }
 
 function buildRateLimitToolResult(error, options = {}) {
-  const { cached = false } = options;
+  const { cached = false, viaCachedPreCheck = false } = options;
   const resetTimestamp = error?.requestsResetAt || Date.now() + 3600000;
   const resetTime = new Date(resetTimestamp).toLocaleTimeString();
 
   markRateLimited(resetTimestamp);
 
   return toToolTextResult(
-    cached
-      ? `Linear API rate limit exceeded (cached).\n\nThe rate limit resets at: ${resetTime}\n\nPlease wait before making more requests.`
-      : `Linear API rate limit exceeded.\n\nThe rate limit resets at: ${resetTime}\n\nPlease wait before making more requests, or reduce the frequency of API calls.`,
+    viaCachedPreCheck
+      ? `Linear API rate limit exceeded (cached — this request was not sent to Linear).
+
+The rate limit resets at: ${resetTime}
+
+Please wait before making more requests.`
+      : cached
+        ? `Linear API rate limit exceeded (cached).
+
+The rate limit resets at: ${resetTime}
+
+Please wait before making more requests.`
+        : `Linear API rate limit exceeded.
+
+The rate limit resets at: ${resetTime}
+
+Please wait before making more requests, or reduce the frequency of API calls.`,
     {
       error: true,
       errorType: 'Ratelimited',
       rateLimited: true,
-      cached,
+      cached: viaCachedPreCheck || cached,
       requestsResetAt: resetTimestamp,
       resetTime,
     }
@@ -487,7 +558,7 @@ function handleToolExecutionError(error, operationLabel, options = {}) {
   const errorMessage = String(transformedError?.message || transformedError || 'Unknown error');
 
   if (errorType === 'Ratelimited' || errorMessage.toLowerCase().includes('rate limit')) {
-    return buildRateLimitToolResult(error);
+    return buildRateLimitToolResult(transformedError, { viaCachedPreCheck: options.viaCachedPreCheck });
   }
 
   if (errorMessage.includes('Linear API error:')) {
@@ -571,18 +642,18 @@ async function registerLinearTools(pi) {
     name: 'linear_issue',
     label: 'Linear Issue',
     description: 'Interact with Linear issues.',
-    promptSnippet: 'Interact with Linear issues (list, view, activity, create, update, comment, start, delete)',
+    promptSnippet: 'Interact with Linear issues (list, view, images, download, activity, create, update, comment, start, delete)',
     parameters: {
       type: 'object',
       properties: {
         action: {
           type: 'string',
-          enum: ['list', 'view', 'activity', 'create', 'update', 'comment', 'start', 'delete'],
+          enum: ['list', 'view', 'images', 'download', 'activity', 'create', 'update', 'comment', 'start', 'delete'],
           description: 'Action to perform on issue(s)',
         },
         issue: {
           type: 'string',
-          description: 'Issue key (ABC-123) or Linear issue ID (for view, activity, update, comment, start, delete)',
+          description: 'Issue key (ABC-123) or Linear issue ID (for view, images, download, activity, update, comment, start, delete)',
         },
         project: {
           type: 'string',
@@ -603,11 +674,46 @@ async function registerLinearTools(pi) {
         },
         limit: {
           type: 'integer',
-          description: 'Maximum number of issues or activity entries to list',
+          description: 'Maximum number of issues, activity entries, or images to fetch',
         },
         includeComments: {
           type: 'boolean',
-          description: 'Include comments when viewing issue (default: true)',
+          description: 'Include comments when viewing an issue or fetching images (default: true)',
+        },
+        attachmentId: {
+          type: 'string',
+          description: 'Attachment ID to download (for download). Use exactly one attachment selector when multiple attachments exist.',
+        },
+        attachmentTitle: {
+          type: 'string',
+          description: 'Attachment title to download (for download). Must uniquely match an issue attachment.',
+        },
+        attachmentUrl: {
+          type: 'string',
+          description: 'Attachment URL to download (for download). Must uniquely match an issue attachment.',
+        },
+        attachmentIndex: {
+          type: 'integer',
+          description: '1-based attachment index from the issue attachment list (for download).',
+          minimum: 1,
+        },
+        directory: {
+          type: 'string',
+          description: 'Relative destination directory for attachment downloads. Missing directories are created.',
+        },
+        filename: {
+          type: 'string',
+          description: 'Optional output filename for attachment downloads. Unsafe characters are sanitized.',
+        },
+        overwrite: {
+          type: 'boolean',
+          description: 'Overwrite existing file during download (default: false). Requires allow_overwrite_files=true in config.',
+        },
+        maxBytes: {
+          type: 'integer',
+          description: 'Maximum bytes to fetch. For images, applies per image with a 10 MiB handler limit. For download, default/max is 52428800.',
+          minimum: 1,
+          maximum: 52428800,
         },
         title: {
           type: 'string',
@@ -618,8 +724,19 @@ async function registerLinearTools(pi) {
           description: 'Issue description in markdown (for create, update)',
         },
         priority: {
-          type: 'integer',
-          description: 'Priority 0..4 (for create, update)',
+          description: 'Issue priority: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low (Linear-native scale), or one of: none, urgent, high, medium, low (for create/update)',
+          oneOf: [
+            {
+              type: 'integer',
+              minimum: 0,
+              maximum: 4,
+              multipleOf: 1,
+            },
+            {
+              type: 'string',
+              enum: ['none', 'urgent', 'high', 'medium', 'low'],
+            },
+          ],
         },
         includeArchived: {
           type: 'boolean',
@@ -668,6 +785,7 @@ async function registerLinearTools(pi) {
         estimate: {
           type: 'integer',
           description: 'Estimate/story points for the issue (non-negative integer, for create/update)',
+          minimum: 0,
         },
         team: {
           type: 'string',
@@ -707,6 +825,8 @@ async function registerLinearTools(pi) {
           return buildRateLimitToolResult({ requestsResetAt: resetAt.getTime(), type: 'Ratelimited' }, { cached: true });
         }
 
+        const settings = await loadSettings();
+        const rateLimitDebug = settings.rateLimitDebug || false;
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_issue', params.action, async () => {
@@ -715,6 +835,10 @@ async function registerLinearTools(pi) {
               return await executeIssueList(client, params);
             case 'view':
               return await executeIssueView(client, params);
+            case 'images':
+              return await executeIssueImages(client, params);
+            case 'download':
+              return await executeIssueDownload(client, params, { settings });
             case 'activity':
               return await executeIssueActivity(client, params);
             case 'create':
@@ -734,7 +858,7 @@ async function registerLinearTools(pi) {
             default:
               throw new Error(`Unknown action: ${params.action}`);
           }
-        });
+        }, rateLimitDebug);
       });
     },
   });
@@ -802,6 +926,14 @@ async function registerLinearTools(pi) {
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
       return executeToolSafely('Linear project operation failed', async () => {
+        // Pre-check: skip API calls if we know we're rate limited
+        const { isRateLimited, resetAt } = checkAndClearRateLimit();
+        if (isRateLimited) {
+          return buildRateLimitToolResult({ requestsResetAt: resetAt.getTime(), type: 'Ratelimited' }, { cached: true });
+        }
+
+        const settings = await loadSettings();
+        const rateLimitDebug = settings.rateLimitDebug || false;
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_project', params.action, async () => {
@@ -823,7 +955,7 @@ async function registerLinearTools(pi) {
             default:
               throw new Error(`Unknown action: ${params.action}`);
           }
-        });
+        }, rateLimitDebug);
       });
     },
   });
@@ -879,6 +1011,14 @@ async function registerLinearTools(pi) {
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
       return executeToolSafely('Linear project update operation failed', async () => {
+        // Pre-check: skip API calls if we know we're rate limited
+        const { isRateLimited, resetAt } = checkAndClearRateLimit();
+        if (isRateLimited) {
+          return buildRateLimitToolResult({ requestsResetAt: resetAt.getTime(), type: 'Ratelimited' }, { cached: true });
+        }
+
+        const settings = await loadSettings();
+        const rateLimitDebug = settings.rateLimitDebug || false;
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_project_update', params.action, async () => {
@@ -898,7 +1038,7 @@ async function registerLinearTools(pi) {
             default:
               throw new Error(`Unknown action: ${params.action}`);
           }
-        });
+        }, rateLimitDebug);
       });
     },
   });
@@ -923,6 +1063,8 @@ async function registerLinearTools(pi) {
     renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
       return executeToolSafely('Linear team operation failed', async () => {
+        const settings = await loadSettings();
+        const rateLimitDebug = settings.rateLimitDebug || false;
         const client = await createAuthenticatedClient();
 
         return await withRequestUsageLogging(client, 'linear_team', params.action, async () => {
@@ -932,7 +1074,7 @@ async function registerLinearTools(pi) {
             default:
               throw new Error(`Unknown action: ${params.action}`);
           }
-        });
+        }, rateLimitDebug);
       });
     },
   });
@@ -978,8 +1120,17 @@ async function registerLinearTools(pi) {
       renderResult: renderMarkdownResult,
       async execute(_toolCallId, params) {
         return executeToolSafely('Linear milestone operation failed', async () => {
+          // Pre-check: skip API calls if we know we're rate limited
+          const { isRateLimited, resetAt } = checkAndClearRateLimit();
+          if (isRateLimited) {
+            return buildRateLimitToolResult({ requestsResetAt: resetAt.getTime(), type: 'Ratelimited' }, { viaCachedPreCheck: true });
+          }
+
+          const settings = await loadSettings();
+          const rateLimitDebug = settings.rateLimitDebug || false;
           const client = await createAuthenticatedClient();
 
+
           return await withRequestUsageLogging(client, 'linear_milestone', params.action, async () => {
             switch (params.action) {
               case 'list':
@@ -995,7 +1146,7 @@ async function registerLinearTools(pi) {
               default:
                 throw new Error(`Unknown action: ${params.action}`);
             }
-          });
+          }, rateLimitDebug);
         }, {
           transformError: withMilestoneScopeHint,
         });
@@ -1008,13 +1159,15 @@ export default async function piLinearToolsExtension(pi) {
   // Safety wrapper: never let extension errors crash pi
   try {
   pi.registerCommand('linear-tools-config', {
-    description: 'Configure pi-linear-tools settings (API key and default team mappings)',
+    description: 'Configure pi-linear-tools settings (API key, default team, rate limit debug, file overwrite guard)',
     handler: async (argsText, ctx) => {
       const args = parseArgs(argsText);
       const apiKey = readFlag(args, '--api-key');
       const defaultTeam = readFlag(args, '--default-team');
       const projectTeam = readFlag(args, '--team');
       const projectName = readFlag(args, '--project');
+      const rateLimitDebug = readFlag(args, '--rate-limit-debug');
+      const allowOverwriteFiles = readFlag(args, '--allow-overwrite-files');
 
       if (apiKey) {
         const settings = await loadSettings();
@@ -1035,6 +1188,28 @@ export default async function piLinearToolsExtension(pi) {
         return;
       }
 
+      if (rateLimitDebug) {
+        const settings = await loadSettings();
+        const enabled = rateLimitDebug === 'true' || rateLimitDebug === '1';
+        settings.rateLimitDebug = enabled;
+        await saveSettings(settings);
+        if (ctx?.hasUI) {
+          ctx.ui.notify(`Rate limit debug ${enabled ? 'enabled' : 'disabled'}`, 'info');
+        }
+        return;
+      }
+
+      if (allowOverwriteFiles) {
+        const settings = await loadSettings();
+        const enabled = allowOverwriteFiles === 'true' || allowOverwriteFiles === '1';
+        settings.allow_overwrite_files = enabled;
+        await saveSettings(settings);
+        if (ctx?.hasUI) {
+          ctx.ui.notify(`File overwrite guard ${enabled ? 'allows overwrites' : 'blocks overwrites'}`, 'info');
+        }
+        return;
+      }
+
       if (defaultTeam) {
         const settings = await loadSettings();
         settings.defaultTeam = defaultTeam;
@@ -1078,18 +1253,24 @@ export default async function piLinearToolsExtension(pi) {
         return;
       }
 
-      if (!apiKey && !defaultTeam && !projectTeam && !projectName && ctx?.hasUI && ctx?.ui) {
+      if (!apiKey && !defaultTeam && !projectTeam && !projectName && !rateLimitDebug && !allowOverwriteFiles && ctx?.hasUI && ctx?.ui) {
         await runInteractiveConfigFlow(ctx, pi);
         return;
       }
 
+      // Show current settings if no valid action was specified
+      if (apiKey || defaultTeam || projectTeam || projectName || rateLimitDebug || allowOverwriteFiles) {
+        // Actions above already handled and returned
+        return;
+      }
+
       const settings = await loadSettings();
       const hasKey = !!(settings.apiKey || settings.linearApiKey || process.env.LINEAR_API_KEY);
       const keySource = process.env.LINEAR_API_KEY ? 'environment' : (settings.apiKey || settings.linearApiKey ? 'settings' : 'not set');
 
       pi.sendMessage({
         customType: 'pi-linear-tools',
-        content: `Configuration:\n  LINEAR_API_KEY: ${hasKey ? 'configured' : 'not set'} (source: ${keySource})\n  Default workspace: ${settings.defaultWorkspace?.name || 'not set'}\n  Default team: ${settings.defaultTeam || 'not set'}\n  Project team mappings: ${Object.keys(settings.projects || {}).length}\n\nCommands:\n  /linear-tools-config --api-key lin_xxx\n  /linear-tools-config --default-team ENG\n  /linear-tools-config --team ENG --project MyProject\n\nNote: environment LINEAR_API_KEY takes precedence over settings file.`,
+        content: `Configuration:\n  LINEAR_API_KEY: ${hasKey ? 'configured' : 'not set'} (source: ${keySource})\n  Default workspace: ${settings.defaultWorkspace?.name || 'not set'}\n  Default team: ${settings.defaultTeam || 'not set'}\n  Rate limit debug: ${settings.rateLimitDebug ? 'enabled' : 'disabled'}\n  Allow overwrite files: ${settings.allow_overwrite_files ? 'enabled' : 'disabled'}\n  Project team mappings: ${Object.keys(settings.projects || {}).length}\n\nCommands:\n  /linear-tools-config --api-key lin_xxx\n  /linear-tools-config --default-team ENG\n  /linear-tools-config --team ENG --project MyProject\n  /linear-tools-config --rate-limit-debug true|false\n  /linear-tools-config --allow-overwrite-files true|false\n\nNote: environment LINEAR_API_KEY takes precedence over settings file.`,
         display: true,
       });
     },
@@ -1115,7 +1296,7 @@ export default async function piLinearToolsExtension(pi) {
       const showMilestoneTool = await shouldExposeMilestoneTool();
       const toolLines = [
         'LLM-callable tools:',
-        '  linear_issue (list/view/activity/create/update/comment/start/delete)',
+        '  linear_issue (list/view/images/download/activity/create/update/comment/start/delete)',
         '  linear_project (list/view/create/update/delete/archive/unarchive)',
         '  linear_project_update (list/view/create/update/archive/unarchive)',
         '  linear_team (list)',
@@ -1134,6 +1315,8 @@ export default async function piLinearToolsExtension(pi) {
           '  /linear-tools-config --api-key <key>',
           '  /linear-tools-config --default-team <team-key>',
           '  /linear-tools-config --team <team-key> --project <project-name-or-id>',
+          '  /linear-tools-config --rate-limit-debug true|false',
+          '  /linear-tools-config --allow-overwrite-files true|false',
           '  /linear-tools-help',
           '  /linear-tools-reload',
           '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fink-andreas/pi-linear-tools",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Pi extension with Linear SDK tools and configuration commands",
   "type": "module",
   "engines": {
@@ -27,7 +27,7 @@
   },
   "scripts": {
     "start": "node index.js",
-    "test": "node tests/test-package-manifest.js && node tests/test-extension-registration.js && node tests/test-settings.js && node tests/test-api-usage-caching.js && node tests/test-assignee-update.js && node tests/test-rate-limit-fallback-update.js && node tests/test-full-assignee-flow.js && node tests/test-branch-param.js && node tests/test-team-filter.js && node tests/test-project-crud.js && node tests/test-project-lifecycle.js && node tests/test-sync-doc.js && node tests/test-issue-activity.js",
+    "test": "node tests/test-package-manifest.js && node tests/test-extension-registration.js && node tests/test-issue-comment-result.js && node tests/test-issue-priority.js && node tests/test-settings.js && node tests/test-issue-download.js && node tests/test-api-usage-caching.js && node tests/test-assignee-update.js && node tests/test-rate-limit-fallback-update.js && node tests/test-full-assignee-flow.js && node tests/test-branch-param.js && node tests/test-team-filter.js && node tests/test-project-crud.js && node tests/test-project-lifecycle.js && node tests/test-sync-doc.js && node tests/test-issue-activity.js",
     "dev:sync-local-extension": "node scripts/dev-sync-local-extension.mjs",
     "release:check": "npm test && npm pack --dry-run"
   },

package/settings.json.example

@@ -1,7 +1,11 @@
 {
-  "schemaVersion": 1,
-  "linearApiKey": "lin_xxx",
+  "schemaVersion": 2,
+  "authMethod": "api-key",
+  "apiKey": "lin_xxx",
   "defaultTeam": "ENG",
+  "defaultWorkspace": null,
+  "rateLimitDebug": false,
+  "allow_overwrite_files": false,
   "projects": {
     "97ec7cae-e252-493d-94d3-6910aa28cacf": {
       "scope": {