@fink-andreas/pi-linear-tools 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## v0.7.1 (2026-06-09)
+
+Patch release for issue creation milestone assignment and configuration text cleanup.
+
+### Bug Fixes
+- **Fixed issue create milestone assignment**: `linear_issue create` now assigns project milestones when `milestone` or `projectMilestoneId` is provided.
+- **Fixed configuration text typo**: Corrected config command/help text in the pi extension.
+
+### Release Maintenance
+- Updated package metadata to `0.7.1`.
+
+## v0.7.0 (2026-06-09)
+
+Issue image fetching and file download release.
+
+### New Features
+- **Issue image fetching**: Added `linear_issue(action="images")` to fetch embedded markdown/HTML images from issue descriptions and comments as tool image content.
+- **Issue attachment downloads**: Added `linear_issue(action="download")` to download Linear issue attachments to validated local paths with filename sanitization and overwrite controls.
+- **Workspace-wide issue listing**: `linear_issue list` can now list across the workspace without requiring a project context.
+- **Overwrite configuration**: Added `allow_overwrite_files` config support via `/linear-tools-config` and `pi-linear-tools config`.
+
+### Bug Fixes
+- Fixed project archive mutation so `archiveProject` archives instead of deleting projects.
+- Fixed comment rendering so submitted comment text appears in `linear_issue comment` results.
+- Fixed rate-limit display to reflect actual complexity-based limits instead of a hardcoded total.
+- Added project and project-update rate-limit pre-checks.
+
+### Documentation
+- Added smoke test coverage for image and attachment workflows.
+- Added dedicated release notes in `docs/RELEASE_NOTES_v0.7.0.md`.
+
 ## v0.6.0 (2026-04-23)
 
 Rate-limit resilience for milestone operations.

package/README.md

@@ -41,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
@@ -67,7 +68,11 @@ Reference conventions:
 ## 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`
@@ -94,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
@@ -110,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
@@ -124,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

@@ -48,6 +48,8 @@ try {
 import {
   executeIssueList,
   executeIssueView,
+  executeIssueImages,
+  executeIssueDownload,
   executeIssueActivity,
   executeIssueCreate,
   executeIssueUpdate,
@@ -144,7 +146,9 @@ async function withRequestUsageLogging(client, toolName, action, operation, rate
       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,
@@ -161,7 +165,10 @@ async function withRequestUsageLogging(client, toolName, action, operation, rate
 
     // Add rate limit info to details if debug is enabled
     if (rateLimitDebug && rateLimitInfo) {
-      details.rateLimit = rateLimitInfo;
+      details.rateLimit = {
+        ...rateLimitInfo,
+        requestsDelta: usageDelta.requestsDelta,
+      };
     }
 
     if (!INCLUDE_USAGE_SUMMARY && !rateLimitDebug) {
@@ -181,8 +188,12 @@ async function withRequestUsageLogging(client, toolName, action, operation, rate
         }
 
         if (rateLimitDebug && rateLimitInfo) {
-          const percent = rateLimitInfo.usagePercent;
-          appendedText += `\n\n---\n**Rate Limit**: ${rateLimitInfo.used}/${rateLimitInfo.total} used (${percent}%) • Resets at ${rateLimitInfo.resetTime}`;
+          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 {
@@ -213,7 +224,9 @@ async function withRequestUsageLogging(client, toolName, action, operation, rate
       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,
       } : {}),
@@ -345,7 +358,7 @@ async function runInteractiveConfigFlow(ctx, pi) {
   }
 
   if (!client) {
-    const selectedAuthMethod = await ctx.ui.select('Select authentication method', ['API Key (recommended for full functionlaity)', 'OAuth']);
+    const selectedAuthMethod = await ctx.ui.select('Select authentication method', ['API Key (recommended for full functionality)', 'OAuth']);
 
     if (!selectedAuthMethod) {
       ctx.ui.notify('Configuration cancelled', 'warning');
@@ -629,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',
@@ -661,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',
@@ -676,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',
@@ -689,11 +748,11 @@ async function registerLinearTools(pi) {
         },
         milestone: {
           type: 'string',
-          description: 'For update: milestone name/ID, or "none" to clear milestone assignment.',
+          description: 'For create/update: milestone name/ID. For create, also provide project so names can be resolved. Use "none" to clear on update.',
         },
         projectMilestoneId: {
           type: 'string',
-          description: 'Optional explicit milestone ID alias for update.',
+          description: 'Optional explicit milestone ID alias for create/update.',
         },
         subIssueOf: {
           type: 'string',
@@ -726,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',
@@ -775,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':
@@ -862,6 +926,12 @@ 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();
@@ -941,6 +1011,12 @@ 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();
@@ -1083,7 +1159,7 @@ 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, default team, rate limit debug)',
+    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');
@@ -1091,6 +1167,7 @@ export default async function piLinearToolsExtension(pi) {
       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();
@@ -1122,6 +1199,17 @@ export default async function piLinearToolsExtension(pi) {
         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;
@@ -1165,13 +1253,13 @@ export default async function piLinearToolsExtension(pi) {
         return;
       }
 
-      if (!apiKey && !defaultTeam && !projectTeam && !projectName && !rateLimitDebug && 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) {
+      if (apiKey || defaultTeam || projectTeam || projectName || rateLimitDebug || allowOverwriteFiles) {
         // Actions above already handled and returned
         return;
       }
@@ -1182,7 +1270,7 @@ export default async function piLinearToolsExtension(pi) {
 
       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  Rate limit debug: ${settings.rateLimitDebug ? '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\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,
       });
     },
@@ -1208,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)',
@@ -1228,6 +1316,7 @@ export default async function piLinearToolsExtension(pi) {
           '  /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.6.0",
+  "version": "0.7.1",
   "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-issue-create-milestone.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": {

package/src/cli.js

@@ -18,6 +18,8 @@ import {
 import {
   executeIssueList,
   executeIssueView,
+  executeIssueImages,
+  executeIssueDownload,
   executeIssueActivity,
   executeIssueCreate,
   executeIssueUpdate,
@@ -164,6 +166,8 @@ Other commands:
   config                        Show current configuration
   config --api-key <key>        Set Linear API key (legacy)
   config --default-team <key>   Set default team
+  config --allow-overwrite-files true|false
+                                Allow issue download overwrites when requested
 
 Auth Actions:
   login    Authenticate with Linear via OAuth 2.0
@@ -173,9 +177,12 @@ Auth Actions:
 Issue Actions:
   list [--project X] [--states X,Y] [--assignee me|all] [--team X] [--limit N]
   view <issue> [--no-comments]
+  images <issue> [--no-comments] [--limit N] [--max-bytes N]
+  download <issue> --directory DIR [--attachment-id ID|--attachment-title TITLE|--attachment-url URL|--attachment-index N]
+         [--filename NAME] [--overwrite true|false] [--max-bytes N]
   activity <issue> [--limit N] [--include-archived true|false]
-  create --title X [--team X] [--project X] [--description X] [--priority 0-4] [--assignee me|ID]
-  update <issue> [--title X] [--description X] [--state X] [--priority 0-4]
+  create --title X [--team X] [--project X] [--description X] [--priority 0-4|name] [--assignee me|ID]
+  update <issue> [--title X] [--description X] [--state X] [--priority 0-4|name]
          [--assignee me|ID] [--milestone X] [--sub-issue-of X]
   comment <issue> --body X
   start <issue> [--from-ref X] [--on-branch-exists switch|suffix]
@@ -242,7 +249,7 @@ Common Flags:
   --project     Project name or ID
   --team        Team key (e.g., ENG)
   --assignee    "me" or assignee ID
-  --priority    Priority 0-4 (0=None, 1=Urgent, 2=High, 3=Medium, 4=Low)
+  --priority    Issue priority: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low; or none, urgent, high, medium, low
   --state       State name or ID
   --limit       Max results (default: 50)
 
@@ -286,11 +293,14 @@ Guidance:
   Use "update" to change the issue itself: title, description, state, assignee, milestone, or parent.
   Use "comment" to add a discussion entry.
   Use "activity" to read the Activity timeline shown in Linear.
+  Use "images" to fetch image attachments embedded in issue markdown/comments.
 
 Actions:
   list      List issues in a project
   view      View issue details
+  images    Fetch image attachments embedded in issue markdown/comments
   activity  View issue activity/history
+  download  Download a Linear issue attachment
   create    Create a new issue
   update    Update an existing issue
   comment   Add a comment to an issue
@@ -308,6 +318,23 @@ View Options:
   <issue>          Issue key (e.g., ENG-123), ID, or issue URL
   --no-comments    Exclude comments from output
 
+Images Options:
+  <issue>          Issue key (e.g., ENG-123), ID, or issue URL
+  --no-comments    Exclude images from comments
+  --limit N        Max images to fetch (default: 10)
+  --max-bytes N    Max bytes per image (default/max: 10485760)
+
+Download Options:
+  <issue>              Issue key, ID, or issue URL
+  --directory DIR      Relative destination directory (required)
+  --attachment-id ID   Attachment ID selector
+  --attachment-title X Attachment title selector (must be unique)
+  --attachment-url URL Attachment URL selector
+  --attachment-index N 1-based attachment index selector
+  --filename NAME      Optional output filename
+  --overwrite X        true or false (default: false; requires config guard)
+  --max-bytes N        Max download bytes (default/max: 52428800)
+
 Activity Options:
   <issue>          Issue key, ID, or issue URL
   --limit N        Max activity entries to fetch (default: 20)
@@ -318,7 +345,7 @@ Create Options:
   --team X         Team key, e.g., ENG (required if no default team)
   --project X      Project name or ID
   --description X  Issue description (markdown)
-  --priority N     Priority 0-4
+  --priority N     Issue priority: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low; or none, urgent, high, medium, low
   --assignee X     "me" or assignee ID
   --parent-id X    Parent issue ID for sub-issues
 
@@ -327,7 +354,7 @@ Update Options:
   --title X        New title
   --description X  New description
   --state X        New state name or ID
-  --priority N     New priority 0-4
+  --priority N     New issue priority: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low; or none, urgent, high, medium, low
   --assignee X     "me" or assignee ID
   --milestone X    Milestone name/ID, or "none" to clear
   --sub-issue-of X Parent issue key/ID, or "none" to clear
@@ -351,6 +378,7 @@ Examples:
   pi-linear-tools issue comment ENG-123 --body "Ready for review"
   pi-linear-tools issue activity ENG-123 --limit 20
   pi-linear-tools issue activity https://linear.app/workspace/issue/ENG-123/example --limit 20
+  pi-linear-tools issue download ENG-123 --attachment-index 1 --directory downloads
 `);
 }
 
@@ -729,6 +757,7 @@ async function handleConfig(args) {
   const defaultTeam = readFlag(args, '--default-team');
   const projectTeam = readFlag(args, '--team');
   const projectName = readFlag(args, '--project');
+  const allowOverwriteFiles = readFlag(args, '--allow-overwrite-files');
 
   if (apiKey) {
     const settings = await loadSettings();
@@ -748,6 +777,19 @@ async function handleConfig(args) {
     return;
   }
 
+  if (allowOverwriteFiles !== undefined) {
+    const enabled = parseBoolean(allowOverwriteFiles);
+    if (enabled === undefined) {
+      throw new Error('Invalid value for --allow-overwrite-files. Use true or false.');
+    }
+
+    const settings = await loadSettings();
+    settings.allow_overwrite_files = enabled;
+    await saveSettings(settings);
+    console.log(`File overwrite guard ${enabled ? 'allows overwrites' : 'blocks overwrites'}`);
+    return;
+  }
+
   if (projectTeam) {
     if (!projectName) {
       throw new Error('Missing required flag: --project when using --team');
@@ -777,12 +819,14 @@ async function handleConfig(args) {
   console.log(`Configuration:
   LINEAR_API_KEY: ${hasKey ? 'configured' : 'not set'} (source: ${keySource})
   Default team: ${settings.defaultTeam || 'not set'}
+  Allow overwrite files: ${settings.allow_overwrite_files ? 'enabled' : 'disabled'}
   Project team mappings: ${Object.keys(settings.projects || {}).length}
 
 Commands:
   pi-linear-tools config --api-key lin_xxx
   pi-linear-tools config --default-team ENG
-  pi-linear-tools config --team ENG --project MyProject`);
+  pi-linear-tools config --team ENG --project MyProject
+  pi-linear-tools config --allow-overwrite-files true|false`);
 }
 
 // ===== ISSUE HANDLERS =====
@@ -819,6 +863,25 @@ async function handleIssueView(args) {
   console.log(result.content[0].text);
 }
 
+async function handleIssueImages(args) {
+  const client = await createAuthenticatedClient();
+
+  const positional = args.filter((a) => !a.startsWith('-'));
+  if (positional.length === 0) {
+    throw new Error('Missing required argument: issue key or ID');
+  }
+
+  const params = {
+    issue: positional[0],
+    includeComments: !hasFlag(args, '--no-comments'),
+    limit: parseNumber(readFlag(args, '--limit')),
+    maxBytes: parseNumber(readFlag(args, '--max-bytes')),
+  };
+
+  const result = await executeIssueImages(client, params);
+  console.log(result.content[0].text);
+}
+
 async function handleIssueActivity(args) {
   const client = await createAuthenticatedClient();
 
@@ -837,6 +900,32 @@ async function handleIssueActivity(args) {
   console.log(result.content[0].text);
 }
 
+async function handleIssueDownload(args) {
+  const client = await createAuthenticatedClient();
+  const settings = await loadSettings();
+
+  const positional = args.filter((a) => !a.startsWith('-'));
+  if (positional.length === 0) {
+    throw new Error('Missing required argument: issue key or ID');
+  }
+
+  const overwrite = parseBoolean(readFlag(args, '--overwrite'));
+  const params = {
+    issue: positional[0],
+    attachmentId: readFlag(args, '--attachment-id'),
+    attachmentTitle: readFlag(args, '--attachment-title'),
+    attachmentUrl: readFlag(args, '--attachment-url'),
+    attachmentIndex: parseNumber(readFlag(args, '--attachment-index')),
+    directory: readFlag(args, '--directory'),
+    filename: readFlag(args, '--filename'),
+    overwrite: overwrite === undefined ? undefined : overwrite,
+    maxBytes: parseNumber(readFlag(args, '--max-bytes')),
+  };
+
+  const result = await executeIssueDownload(client, params, { settings });
+  console.log(result.content[0].text);
+}
+
 async function handleIssueCreate(args) {
   const client = await createAuthenticatedClient();
 
@@ -845,7 +934,7 @@ async function handleIssueCreate(args) {
     team: readFlag(args, '--team'),
     project: readFlag(args, '--project'),
     description: readFlag(args, '--description'),
-    priority: parseNumber(readFlag(args, '--priority')),
+    priority: readFlag(args, '--priority'),
     assignee: readFlag(args, '--assignee'),
     parentId: readFlag(args, '--parent-id'),
     state: readFlag(args, '--state'),
@@ -872,7 +961,7 @@ async function handleIssueUpdate(args) {
     title: readFlag(args, '--title'),
     description: readFlag(args, '--description'),
     state: readFlag(args, '--state'),
-    priority: parseNumber(readFlag(args, '--priority')),
+    priority: readFlag(args, '--priority'),
     assignee: readFlag(args, '--assignee'),
     milestone: readFlag(args, '--milestone'),
     subIssueOf: readFlag(args, '--sub-issue-of'),
@@ -950,6 +1039,10 @@ async function handleIssue(args) {
       return handleIssueList(rest);
     case 'view':
       return handleIssueView(rest);
+    case 'images':
+      return handleIssueImages(rest);
+    case 'download':
+      return handleIssueDownload(rest);
     case 'activity':
       return handleIssueActivity(rest);
     case 'create':