shortcutxl 0.3.48 → 0.3.50

package/CHANGELOG.md

@@ -1,14 +1,26 @@
-# Changelog
-
-## [0.3.48]
-
-- **Background subagents** - Subagents can now work in the background, be steered during conversations, be revived for additional tasks once they are done, and have their statuses surfaced in the UI.
-- **Skill proposals** - ShortcutXL now automatically browses through past sessions and suggests new skills and skill modifications.
-
-## [0.3.47]
-
-- **GPT-5.5** — Upgraded the OpenAI reasoning model from GPT-5.4 to GPT-5.5 (400K context window, stronger reasoning). 
-- **Out-of-credits message** — When your credit balance runs out, ShortcutXL now shows a clear message instead of silently failing.
+# Changelog
+
+## [0.3.50]
+
+- **MCP-enabled task agents** - General task agents can now use connected MCP servers, giving delegated work access to the same external tools and resources as the main CLI.
+- **Safer skill uploads** - Uploading skills no longer treats missing local skills as cloud deletions, so remote-only skills stay untouched unless explicitly replaced.
+- **Misc bug fixes** - Shift+A for agent panel, wording, clarity.
+
+## [0.3.49]
+
+- **Transcript scrolling & rendering** - Long conversations now scroll more cleanly with mouse wheel, PageUp/PageDown, and Ctrl+Home/Ctrl+End support while the editor and footer stay pinned.
+- **Longer-running task agents** - Background task agents now get a 30-minute default timeout, reducing early timeouts on bigger jobs.
+- **Clearer path-based skills** - Skills loaded from custom folders are grouped by their real root paths so the agent can find and use them more reliably.
+
+## [0.3.48]
+
+- **Background subagents** - Subagents can now work in the background, be steered during conversations, be revived for additional tasks once they are done, and have their statuses surfaced in the UI.
+- **Skill proposals** - ShortcutXL now automatically browses through past sessions and suggests new skills and skill modifications.
+
+## [0.3.47]
+
+- **GPT-5.5** — Upgraded the OpenAI reasoning model from GPT-5.4 to GPT-5.5 (400K context window, stronger reasoning). 
+- **Out-of-credits message** — When your credit balance runs out, ShortcutXL now shows a clear message instead of silently failing.
 
 ## [0.3.46]
 

package/agent-docs/docs/tui.md

@@ -28,6 +28,8 @@ interface Component {
 
 The TUI appends a full SGR reset and OSC 8 reset at the end of each rendered line. Styles do not carry across lines. If you emit multi-line text with styling, reapply styles per line or use `wrapTextWithAnsi()` so styles are preserved for each wrapped line.
 
+Shortcut's interactive shell configures `ProcessTerminal` to use the terminal alternate screen buffer. The main transcript is an app-owned scroll viewport, not native terminal scrollback. In that shell, PageUp/PageDown, Ctrl+Home/Ctrl+End, and mouse wheel input scroll the transcript while the editor/footer remain pinned. Fullscreen custom views should clear/redraw inside the existing alternate buffer instead of entering or leaving alternate-buffer mode themselves.
+
 ## Focusable Interface (IME Support)
 
 Components that display a text cursor and need IME (Input Method Editor) support should implement the `Focusable` interface:
@@ -445,12 +447,34 @@ interface MyTheme {
 
 ## Debug logging
 
+`ProcessTerminal` only enters the alternate screen buffer (`CSI ? 1049 h`) when `useAlternateBuffer: true` is passed. Shortcut's interactive shell enables that mode; full-screen subviews should clear and redraw inside the existing TUI buffer instead of entering or leaving alternate buffer themselves.
+
+Set `SHORTCUT_TUI_RENDER_TRACE=1` to capture a structured JSONL trace of TUI rendering decisions, input events, overlay/focus state, cursor movement, changed line hashes/previews, and ANSI write summaries. By default this writes to `~/.shortcut/agent/tui-render-traces/<timestamp>-<pid>.jsonl`. Set it to a file path to choose the destination. Add `SHORTCUT_TUI_RENDER_TRACE_FULL=1` to include full rendered lines and full write buffers; leave it off for smaller logs.
+
+```bash
+SHORTCUT_TUI_RENDER_TRACE=1 shortcut
+SHORTCUT_TUI_RENDER_TRACE=C:\temp\shortcut-tui.jsonl SHORTCUT_TUI_RENDER_TRACE_FULL=1 shortcut
+```
+
 Set `SHORTCUT_TUI_WRITE_LOG` to capture the raw ANSI stream written to stdout.
 
 ```bash
 SHORTCUT_TUI_WRITE_LOG=/tmp/tui-ansi.log npx tsx packages/tui/test/chat-simple.ts
 ```
 
+Summarize a captured trace with:
+
+```bash
+npm run analyze:tui-trace -- C:\temp\shortcut-tui.jsonl
+npm run analyze:tui-trace -- C:\temp\shortcut-tui.jsonl --json
+```
+
+For deterministic repro coverage, run the PTY render matrix:
+
+```bash
+npm run test:pty -- tests/interactive/tui-render-matrix/tui-render-matrix.pty.test.ts
+```
+
 ## Performance
 
 Cache rendered output when possible:

package/agent-docs/examples/rpc-extension-ui.ts

@@ -274,7 +274,7 @@ async function main() {
 
   // -- TUI setup --
 
-  const terminal = new ProcessTerminal();
+  const terminal = new ProcessTerminal({ useAlternateBuffer: true });
   const tui = new TUI(terminal);
 
   const outputLog = new OutputLog();

package/dist/app/agent-session.d.ts

@@ -137,7 +137,7 @@ export interface PromptOptions {
     expandPromptTemplates?: boolean;
     /** Image attachments */
     images?: ImageContent[];
-    /** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). Required if streaming. */
+    /** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). Defaults to "steer". */
     streamingBehavior?: 'steer' | 'followUp';
     /** Source of input for extension input event handlers. Defaults to "interactive". */
     source?: InputSource;
@@ -322,9 +322,8 @@ export declare class AgentSession {
     /**
      * Send a prompt to the agent.
      * - Expands file-based prompt templates by default
-     * - During streaming, queues via steer() or followUp() based on streamingBehavior option
+     * - During streaming, queues via steer() by default, or followUp() when requested
      * - Validates model and API key before sending (when not streaming)
-     * @throws Error if streaming and no streamingBehavior specified
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     prompt(text: string, options?: PromptOptions): Promise<void>;

package/dist/app/agent-session.js

@@ -734,9 +734,8 @@ export class AgentSession {
     /**
      * Send a prompt to the agent.
      * - Expands file-based prompt templates by default
-     * - During streaming, queues via steer() or followUp() based on streamingBehavior option
+     * - During streaming, queues via steer() by default, or followUp() when requested
      * - Validates model and API key before sending (when not streaming)
-     * @throws Error if streaming and no streamingBehavior specified
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     async prompt(text, options) {
@@ -756,12 +755,9 @@ export class AgentSession {
             currentText = parsedBudget.task;
         }
         const expandedText = currentText;
-        // If streaming, queue via steer() or followUp() based on option
+        // If streaming, queue via steer() by default; follow-up is opt-in.
         if (this.isStreaming) {
-            if (!options?.streamingBehavior) {
-                throw new Error("AgentController is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
-            }
-            if (options.streamingBehavior === 'followUp') {
+            if (options?.streamingBehavior === 'followUp') {
                 await this._queueFollowUp(expandedText, currentImages);
             }
             else {

package/dist/app/index.d.ts

@@ -46,7 +46,7 @@ export { default as skillProposalsExtension } from './skill-proposals/extension.
 export { getSkillProposalRoots, type ProposalRoots } from './skill-proposals/proposal-fs.js';
 export { readSkillProposalReviewSnapshot, type SkillProposalReviewSnapshot } from './skill-proposals/review.js';
 export type { StartupInfoEntry } from './startup-info.js';
-export { downloadSkillsWithApproval, syncSkillsConservatively } from './sync/skills-download.js';
+export { downloadSkillsWithApproval } from './sync/skills-download.js';
 export type { SkillDownloadApprovalHandler, SkillDownloadApprovalRequest, SkillsDownloadResult } from './sync/skills-download.js';
 export { uploadSkills } from './sync/skills-upload.js';
 export type { SkillUploadApprovalRequest, SkillsUploadResult } from './sync/skills-upload.js';

package/dist/app/index.js

@@ -36,7 +36,7 @@ export { countSkillProposals, listSkillProposals } from './skill-proposals/catal
 export { default as skillProposalsExtension } from './skill-proposals/extension.js';
 export { getSkillProposalRoots } from './skill-proposals/proposal-fs.js';
 export { readSkillProposalReviewSnapshot } from './skill-proposals/review.js';
-export { downloadSkillsWithApproval, syncSkillsConservatively } from './sync/skills-download.js';
+export { downloadSkillsWithApproval } from './sync/skills-download.js';
 export { uploadSkills } from './sync/skills-upload.js';
 export * from './tools/index.js';
 export { buildWorkbookPromptContext, fetchWorkbookConnectionState, formatWorkbookScopePromptContext } from './workbook-context/workbook-summary.js';

package/dist/app/modes/action/agent.js

@@ -5,12 +5,17 @@
  * for making changes to the spreadsheet. Can switch to plan or installation mode.
  */
 import { MODE } from '../../../mode-names.js';
-import { ACTION_SWITCH_MODE, BASH, EXECUTE_CODE, EXECUTE_TOOL, GET_TOOL_INFO, MCP_TOOL_NAMES, SEND_MESSAGE, TASK, TODO_LIST, WRITE } from '../../../tool-names.js';
+import { ACTION_SWITCH_MODE, BASH, EDIT, EXECUTE_CODE, EXECUTE_TOOL, FIND, GET_TOOL_INFO, GREP, LS, MCP_TOOL_NAMES, READ, SEND_MESSAGE, TASK, TODO_LIST, WRITE } from '../../../tool-names.js';
 import { buildActionPrompt } from './prompt.js';
 const DESCRIPTION = 'Execute changes to the spreadsheet.';
 const TOOLS = [
+    READ,
     BASH,
+    EDIT,
     WRITE,
+    GREP,
+    FIND,
+    LS,
     EXECUTE_CODE,
     TASK,
     SEND_MESSAGE,

package/dist/app/prompts/com-api-reference.json

@@ -1,146 +1,146 @@
-{
-  "interfaces": {
-    "Workbook": {
-      "docstring": "Workbook wrapper.\nUsage:\n    wb = Workbook(app.Workbooks(\"MyFile.xlsx\"))\n\nRaw COM access:\n    wb._wb  \u2014 the underlying COM Workbook object for direct platform API calls.\n    Example: wb._wb.Worksheets(\"Sheet1\").Visible = False",
-      "functions": {
-        "getSheetNames": {
-          "signature": "def getSheetNames() -> list[str]",
-          "docstring": "Get the names of all sheets in the workbook.",
-          "tags": ["action", "ask"]
-        },
-        "getWorkbookSummary": {
-          "signature": "def getWorkbookSummary() -> str",
-          "docstring": "Get sheet names and used ranges for this workbook.\nReturns lines like:\n    Sheets and their used ranges:\n      Sheet1: A1:D10 (active)\n      Inputs: (empty)",
-          "tags": ["action", "ask"]
-        },
-        "getSheet": {
-          "signature": "def getSheet(name: str) -> 'Worksheet'",
-          "docstring": "Get a sheet by name, returned as a wrapped Worksheet.",
-          "tags": ["action", "ask"]
-        },
-        "addSheet": {
-          "signature": "def addSheet(name: str, index: int | None = None) -> 'Worksheet'",
-          "docstring": "Add a new sheet at 0-based index. index=0 inserts before the first sheet.\nOmit index for Excel's default position.\nExample: wb.addSheet(\"NewSheet\", 0)  # insert as first sheet",
-          "tags": ["action"]
-        },
-        "moveSheet": {
-          "signature": "def moveSheet(name: str, index: int) -> None",
-          "docstring": "Move a sheet to 0-based index. index=0 moves to first, index=Count-1 moves to last.\nExample: wb.moveSheet(\"Data\", 0)  # move to first position",
-          "tags": ["action"]
-        },
-        "calculate": {
-          "signature": "def calculate() -> None",
-          "docstring": "Recalculate the entire workbook.\nDependent formulas don't update until after code block completes \u2014 read in a follow-up block.",
-          "tags": ["action"]
-        },
-        "errorCheck": {
-          "signature": "def errorCheck(ranges: list[str] | None = None) -> str",
-          "docstring": "Scan for errors (#REF!, #DIV/0!, #NAME?, #VALUE!, #N/A, #NULL!, #NUM!). Ranges MUST include a sheet name (\"Sheet1\" or \"Sheet1!A1:D50\") \u2014 bare ranges like \"A1:D50\" will fail.\n      Args:\n          ranges: Optional sheet names (\"Sheet1\") or ranges (\"Sheet1!A1:D50\"). Omit to check all.\n      Returns:\n          \"No issues found.\" or \"Errors (N):\nSheet1!A1: #REF!\n...\"",
-          "tags": ["action", "ask"]
-        },
-        "copyPasteRange": {
-          "signature": "def copyPasteRange(from_range: str, to_address: str, paste_type: str = 'all', ) -> None",
-          "docstring": "Copy range within same workbook via range.Copy + PasteSpecial.\nAddresses must include sheet name. Do NOT use Sheet.Copy (broken via pywin32).\nExample: wb.copyPasteRange(\"Sheet1!A1:D10\", \"Sheet2!A1\", paste_type=\"values\")",
-          "tags": ["action"]
-        },
-        "getNamedRangeInfo": {
-          "signature": "def getNamedRangeInfo(max_count: int = 50) -> str",
-          "docstring": "Get named ranges. Returns formatted string with name, reference, scope, and comment.\nExample output: \"Named Ranges (2):\\n  Name: TaxRate | Ref: =Settings!$B$2 | Scope: workbook | Comment: ...\"\nReturns \"No named ranges found.\" if none exist.",
-          "tags": ["action", "ask"]
-        }
-      }
-    },
-    "Worksheet": {
-      "docstring": "Worksheet wrapper.\nUsage:\n    sheet = wb.getSheet(\"Sheet1\")\n\nRaw COM access:\n    sheet._ws  \u2014 the underlying COM Worksheet object for direct platform API calls.\n    Use for borders, text orientation, cell protection, and other properties not covered by the wrapper.\n    Example: sheet._ws.Range(\"A1\").Borders(9).LineStyle = 1  # xlEdgeBottom, xlContinuous",
-      "functions": {
-        "getSheetSummary": {
-          "signature": "def getSheetSummary() -> str",
-          "docstring": "Overview: name, used range, tables (with style/banded/header/total props),\npivots (with range), conditional formats (type/range/priority/stopIfTrue),\nautofilter (with filtering status), charts (with type).",
-          "tags": ["action", "ask"]
-        },
-        "getUsedRange": {
-          "signature": "def getUsedRange() -> str",
-          "docstring": "Get the used range address like \"A1:F20\", or \"\" if empty.",
-          "tags": ["action", "ask"]
-        },
-        "getCell": {
-          "signature": "def getCell(address: str, include_style: bool = True) -> str",
-          "docstring": "Formatted cell string: \"value(=FORMULA) (style_json)\". Formula always included.\nZero with custom format appends [0]: \"$ - [0]\".\nExample:\n    print(sheet.getCell(\"A1\"))\n    print(sheet.getCell(\"A1\", include_style=False))",
-          "tags": ["action", "ask"]
-        },
-        "getCellRange": {
-          "signature": "def getCellRange(range_addr: str, include_style: bool = True) -> str",
-          "docstring": "Markdown-like range: \"A1:Name | B1:Value\\nA2:Alice | B2:100\". Uses display text. Max 3000 cells; read larger areas in smaller chunks.\nAppends \"--- Style patterns ---\" section when include_style=True.",
-          "tags": ["action", "ask"]
-        },
-        "getRawCellData": {
-          "signature": "def getRawCellData(address: str, formula: bool = False) -> Any",
-          "docstring": "Get raw data value from a cell, preserving data type. Set formula=True to get the formula string.",
-          "tags": ["action", "ask"]
-        },
-        "getRawRangeData": {
-          "signature": "def getRawRangeData(range_addr: str, formula: bool = False) -> list[list[Any]]",
-          "docstring": "Get raw data for a range as 2D list. Always returns 2D list even for single row/column.",
-          "tags": ["action", "ask"]
-        },
-        "regexSearch": {
-          "signature": "def regexSearch(patterns: list[str], match_case: bool = False) -> list[dict]",
-          "docstring": "Regex search across used range using display text. Returns [{\"address\": \"A1\", \"value\": \"display text\"}, ...].\nExample: sheet.regexSearch([\"revenue\", \"cost\"])",
-          "tags": ["action", "ask"]
-        },
-        "setCell": {
-          "signature": "def setCell(address: str, value: Any, number_format: str | None = None, note: str | None = None, ) -> None",
-          "docstring": "Write value or formula. \"=\" prefix = formula. None or \"\" clears the cell.\nExamples:\n    sheet.setCell(\"A1\", 8000)\n    sheet.setCell(\"C1\", 0.15, number_format=\"0%\", note=\"Tax rate\")\n    sheet.setCell(\"B1\", \"=SUM(A1:A10)\")",
-          "tags": ["action"]
-        },
-        "setCellRange": {
-          "signature": "def setCellRange(range_addr: str, values: list[list[Any]], number_format: str | None = None, ) -> None",
-          "docstring": "Bulk write \u2014 ALWAYS use for >100 cells. \"=\" prefix = formula.\nExamples:\n    sheet.setCellRange(\"A1:B2\", [[1, 2], [3, 4]])\n    sheet.setCellRange(\"A1:B2\", [[\"=SUM(C1)\", \"=SUM(D1)\"], [5, 6]], number_format=\"$#,##0\")",
-          "tags": ["action"]
-        },
-        "autoFill": {
-          "signature": "def autoFill(source_range: str, target_range: str, fill_mode: str = 'auto', ) -> None",
-          "docstring": "Drag-fill. Source must be contained within target. Default \"auto\" increments hardcoded numeric literals; use fill_mode=\"constant\" to copy literal values, then read back destination cells and check for empty/NaN values.\nUse fill_mode=\"constant\" when copying a single value without incrementing.\nWARNING: Single numeric value with \"auto\" creates incrementing sequence (0,1,2,3...).\nExample: sheet.autoFill(\"A1:A2\", \"A1:A10\")",
-          "tags": ["action"]
-        },
-        "addPicture": {
-          "signature": "def addPicture(name: str, base64_data: str, anchor_cell: str) -> None",
-          "docstring": "Add a picture from base64-encoded PNG or JPEG data. No data URI prefix.\nExample: sheet.addPicture(\"chart1\", base64_string, \"F2\")",
-          "tags": ["action"]
-        },
-        "setIBTextColors": {
-          "signature": "def setIBTextColors(range_addr: str, ignored_constants: list[int] | None = None, colors: dict | None = None, ) -> None",
-          "docstring": "IB text colors for numeric inputs only. Text strings and booleans are left untouched.\n- Blue/16711680: hard-coded numeric constants (int/float)\n- Black/0: formulas (same-sheet references)\n- Green/32768: formulas with cross-sheet references (contains '!')\nColors are BGR integers (native COM format).\nExample: sheet.setIBTextColors(\"A1:D10\", ignored_constants=[0])",
-          "tags": ["action"]
-        }
-      }
-    }
-  },
-  "helpers": {
-    "hex_to_bgr": {
-      "signature": "def hex_to_bgr(hex_str: str) -> int",
-      "docstring": "Convert \"#RRGGBB\" hex string to BGR integer for Excel COM.\nExample: ws.Range(\"A1\").Font.Color = hex_to_bgr(\"#FF0000\")  # red",
-      "tags": ["action", "ask"]
-    },
-    "index_to_address": {
-      "signature": "def index_to_address(row: int, col: int) -> str",
-      "docstring": "Convert 0-based (row, col) to Excel address: index_to_address(0, 0) \u2192 \"A1\".",
-      "tags": ["action", "ask"]
-    },
-    "address_to_index": {
-      "signature": "def address_to_index(address: str) -> tuple[int, int]",
-      "docstring": "Parse \"A1\" into (row, col) 0-based tuple: address_to_index(\"B3\") \u2192 (2, 1).",
-      "tags": ["action", "ask"]
-    },
-    "col_letter": {
-      "signature": "def col_letter(index: int) -> str",
-      "docstring": "Convert 0-based column index to letter: col_letter(26) \u2192 \"AA\".",
-      "tags": ["action", "ask"]
-    },
-    "col_index": {
-      "signature": "def col_index(letter: str) -> int",
-      "docstring": "Convert column letter to 0-based index: col_index(\"AA\") \u2192 26.",
-      "tags": ["action", "ask"]
-    }
-  }
-}
+{
+  "interfaces": {
+    "Workbook": {
+      "docstring": "Workbook wrapper.\nUsage:\n    wb = Workbook(app.Workbooks(\"MyFile.xlsx\"))\n\nRaw COM access:\n    wb._wb  \u2014 the underlying COM Workbook object for direct platform API calls.\n    Example: wb._wb.Worksheets(\"Sheet1\").Visible = False",
+      "functions": {
+        "getSheetNames": {
+          "signature": "def getSheetNames() -> list[str]",
+          "docstring": "Get the names of all sheets in the workbook.",
+          "tags": ["action", "ask"]
+        },
+        "getWorkbookSummary": {
+          "signature": "def getWorkbookSummary() -> str",
+          "docstring": "Get sheet names and used ranges for this workbook.\nReturns lines like:\n    Sheets and their used ranges:\n      Sheet1: A1:D10 (active)\n      Inputs: (empty)",
+          "tags": ["action", "ask"]
+        },
+        "getSheet": {
+          "signature": "def getSheet(name: str) -> 'Worksheet'",
+          "docstring": "Get a sheet by name, returned as a wrapped Worksheet.",
+          "tags": ["action", "ask"]
+        },
+        "addSheet": {
+          "signature": "def addSheet(name: str, index: int | None = None) -> 'Worksheet'",
+          "docstring": "Add a new sheet at 0-based index. index=0 inserts before the first sheet.\nOmit index for Excel's default position.\nExample: wb.addSheet(\"NewSheet\", 0)  # insert as first sheet",
+          "tags": ["action"]
+        },
+        "moveSheet": {
+          "signature": "def moveSheet(name: str, index: int) -> None",
+          "docstring": "Move a sheet to 0-based index. index=0 moves to first, index=Count-1 moves to last.\nExample: wb.moveSheet(\"Data\", 0)  # move to first position",
+          "tags": ["action"]
+        },
+        "calculate": {
+          "signature": "def calculate() -> None",
+          "docstring": "Recalculate the entire workbook.\nDependent formulas don't update until after code block completes \u2014 read in a follow-up block.",
+          "tags": ["action"]
+        },
+        "errorCheck": {
+          "signature": "def errorCheck(ranges: list[str] | None = None) -> str",
+          "docstring": "Scan for errors (#REF!, #DIV/0!, #NAME?, #VALUE!, #N/A, #NULL!, #NUM!). Ranges MUST include a sheet name (\"Sheet1\" or \"Sheet1!A1:D50\") \u2014 bare ranges like \"A1:D50\" will fail.\n      Args:\n          ranges: Optional sheet names (\"Sheet1\") or ranges (\"Sheet1!A1:D50\"). Omit to check all.\n      Returns:\n          \"No issues found.\" or \"Errors (N):\nSheet1!A1: #REF!\n...\"",
+          "tags": ["action", "ask"]
+        },
+        "copyPasteRange": {
+          "signature": "def copyPasteRange(from_range: str, to_address: str, paste_type: str = 'all', ) -> None",
+          "docstring": "Copy range within same workbook via range.Copy + PasteSpecial.\nAddresses must include sheet name. Do NOT use Sheet.Copy (broken via pywin32).\nExample: wb.copyPasteRange(\"Sheet1!A1:D10\", \"Sheet2!A1\", paste_type=\"values\")",
+          "tags": ["action"]
+        },
+        "getNamedRangeInfo": {
+          "signature": "def getNamedRangeInfo(max_count: int = 50) -> str",
+          "docstring": "Get named ranges. Returns formatted string with name, reference, scope, and comment.\nExample output: \"Named Ranges (2):\\n  Name: TaxRate | Ref: =Settings!$B$2 | Scope: workbook | Comment: ...\"\nReturns \"No named ranges found.\" if none exist.",
+          "tags": ["action", "ask"]
+        }
+      }
+    },
+    "Worksheet": {
+      "docstring": "Worksheet wrapper.\nUsage:\n    sheet = wb.getSheet(\"Sheet1\")\n\nRaw COM access:\n    sheet._ws  \u2014 the underlying COM Worksheet object for direct platform API calls.\n    Use for borders, text orientation, cell protection, and other properties not covered by the wrapper.\n    Example: sheet._ws.Range(\"A1\").Borders(9).LineStyle = 1  # xlEdgeBottom, xlContinuous",
+      "functions": {
+        "getSheetSummary": {
+          "signature": "def getSheetSummary() -> str",
+          "docstring": "Overview: name, used range, tables (with style/banded/header/total props),\npivots (with range), conditional formats (type/range/priority/stopIfTrue),\nautofilter (with filtering status), charts (with type).",
+          "tags": ["action", "ask"]
+        },
+        "getUsedRange": {
+          "signature": "def getUsedRange() -> str",
+          "docstring": "Get the used range address like \"A1:F20\", or \"\" if empty.",
+          "tags": ["action", "ask"]
+        },
+        "getCell": {
+          "signature": "def getCell(address: str, include_style: bool = True) -> str",
+          "docstring": "Formatted cell string: \"value(=FORMULA) (style_json)\". Formula always included.\nZero with custom format appends [0]: \"$ - [0]\".\nExample:\n    print(sheet.getCell(\"A1\"))\n    print(sheet.getCell(\"A1\", include_style=False))",
+          "tags": ["action", "ask"]
+        },
+        "getCellRange": {
+          "signature": "def getCellRange(range_addr: str, include_style: bool = True) -> str",
+          "docstring": "Markdown-like range: \"A1:Name | B1:Value\\nA2:Alice | B2:100\". Uses display text. Max 3000 cells; read larger areas in smaller chunks.\nAppends \"--- Style patterns ---\" section when include_style=True.",
+          "tags": ["action", "ask"]
+        },
+        "getRawCellData": {
+          "signature": "def getRawCellData(address: str, formula: bool = False) -> Any",
+          "docstring": "Get raw data value from a cell, preserving data type. Set formula=True to get the formula string.",
+          "tags": ["action", "ask"]
+        },
+        "getRawRangeData": {
+          "signature": "def getRawRangeData(range_addr: str, formula: bool = False) -> list[list[Any]]",
+          "docstring": "Get raw data for a range as 2D list. Always returns 2D list even for single row/column.",
+          "tags": ["action", "ask"]
+        },
+        "regexSearch": {
+          "signature": "def regexSearch(patterns: list[str], match_case: bool = False) -> list[dict]",
+          "docstring": "Regex search across used range using display text. Returns [{\"address\": \"A1\", \"value\": \"display text\"}, ...].\nExample: sheet.regexSearch([\"revenue\", \"cost\"])",
+          "tags": ["action", "ask"]
+        },
+        "setCell": {
+          "signature": "def setCell(address: str, value: Any, number_format: str | None = None, note: str | None = None, ) -> None",
+          "docstring": "Write value or formula. \"=\" prefix = formula. None or \"\" clears the cell.\nExamples:\n    sheet.setCell(\"A1\", 8000)\n    sheet.setCell(\"C1\", 0.15, number_format=\"0%\", note=\"Tax rate\")\n    sheet.setCell(\"B1\", \"=SUM(A1:A10)\")",
+          "tags": ["action"]
+        },
+        "setCellRange": {
+          "signature": "def setCellRange(range_addr: str, values: list[list[Any]], number_format: str | None = None, ) -> None",
+          "docstring": "Bulk write \u2014 ALWAYS use for >100 cells. \"=\" prefix = formula.\nExamples:\n    sheet.setCellRange(\"A1:B2\", [[1, 2], [3, 4]])\n    sheet.setCellRange(\"A1:B2\", [[\"=SUM(C1)\", \"=SUM(D1)\"], [5, 6]], number_format=\"$#,##0\")",
+          "tags": ["action"]
+        },
+        "autoFill": {
+          "signature": "def autoFill(source_range: str, target_range: str, fill_mode: str = 'auto', ) -> None",
+          "docstring": "Drag-fill. Source must be contained within target. Default \"auto\" increments hardcoded numeric literals; use fill_mode=\"constant\" to copy literal values, then read back destination cells and check for empty/NaN values.\nUse fill_mode=\"constant\" when copying a single value without incrementing.\nWARNING: Single numeric value with \"auto\" creates incrementing sequence (0,1,2,3...).\nExample: sheet.autoFill(\"A1:A2\", \"A1:A10\")",
+          "tags": ["action"]
+        },
+        "addPicture": {
+          "signature": "def addPicture(name: str, base64_data: str, anchor_cell: str) -> None",
+          "docstring": "Add a picture from base64-encoded PNG or JPEG data. No data URI prefix.\nExample: sheet.addPicture(\"chart1\", base64_string, \"F2\")",
+          "tags": ["action"]
+        },
+        "setIBTextColors": {
+          "signature": "def setIBTextColors(range_addr: str, ignored_constants: list[int] | None = None, colors: dict | None = None, ) -> None",
+          "docstring": "IB text colors for numeric inputs only. Text strings and booleans are left untouched.\n- Blue/16711680: hard-coded numeric constants (int/float)\n- Black/0: formulas (same-sheet references)\n- Green/32768: formulas with cross-sheet references (contains '!')\nColors are BGR integers (native COM format).\nExample: sheet.setIBTextColors(\"A1:D10\", ignored_constants=[0])",
+          "tags": ["action"]
+        }
+      }
+    }
+  },
+  "helpers": {
+    "hex_to_bgr": {
+      "signature": "def hex_to_bgr(hex_str: str) -> int",
+      "docstring": "Convert \"#RRGGBB\" hex string to BGR integer for Excel COM.\nExample: ws.Range(\"A1\").Font.Color = hex_to_bgr(\"#FF0000\")  # red",
+      "tags": ["action", "ask"]
+    },
+    "index_to_address": {
+      "signature": "def index_to_address(row: int, col: int) -> str",
+      "docstring": "Convert 0-based (row, col) to Excel address: index_to_address(0, 0) \u2192 \"A1\".",
+      "tags": ["action", "ask"]
+    },
+    "address_to_index": {
+      "signature": "def address_to_index(address: str) -> tuple[int, int]",
+      "docstring": "Parse \"A1\" into (row, col) 0-based tuple: address_to_index(\"B3\") \u2192 (2, 1).",
+      "tags": ["action", "ask"]
+    },
+    "col_letter": {
+      "signature": "def col_letter(index: int) -> str",
+      "docstring": "Convert 0-based column index to letter: col_letter(26) \u2192 \"AA\".",
+      "tags": ["action", "ask"]
+    },
+    "col_index": {
+      "signature": "def col_index(letter: str) -> int",
+      "docstring": "Convert column letter to 0-based index: col_index(\"AA\") \u2192 26.",
+      "tags": ["action", "ask"]
+    }
+  }
+}

package/dist/app/resources/package-manager.js

@@ -191,37 +191,6 @@ function collectSkillEntries(dir, includeRootFiles = true, ignoreMatcher, rootDi
 function collectAutoSkillEntries(dir, includeRootFiles = true) {
     return collectSkillEntries(dir, includeRootFiles);
 }
-function findGitRepoRoot(startDir) {
-    let dir = resolve(startDir);
-    while (true) {
-        if (existsSync(join(dir, '.git'))) {
-            return dir;
-        }
-        const parent = dirname(dir);
-        if (parent === dir) {
-            return null;
-        }
-        dir = parent;
-    }
-}
-function collectAncestorAgentsSkillDirs(startDir) {
-    const skillDirs = [];
-    const resolvedStartDir = resolve(startDir);
-    const gitRepoRoot = findGitRepoRoot(resolvedStartDir);
-    let dir = resolvedStartDir;
-    while (true) {
-        skillDirs.push(join(dir, '.agents', 'skills'));
-        if (gitRepoRoot && dir === gitRepoRoot) {
-            break;
-        }
-        const parent = dirname(dir);
-        if (parent === dir) {
-            break;
-        }
-        dir = parent;
-    }
-    return skillDirs;
-}
 function collectAutoPromptEntries(dir) {
     const entries = [];
     if (!existsSync(dir))
@@ -1370,8 +1339,6 @@ export class DefaultPackageManager {
             prompts: join(projectBaseDir, 'prompts'),
             themes: join(projectBaseDir, 'themes')
         };
-        const userAgentsSkillsDir = join(homedir(), '.agents', 'skills');
-        const projectAgentsSkillDirs = collectAncestorAgentsSkillDirs(this.cwd);
         const addResources = (resourceType, paths, metadata, overrides, baseDir) => {
             const target = this.getTargetMap(accumulator, resourceType);
             for (const path of paths) {
@@ -1380,17 +1347,11 @@ export class DefaultPackageManager {
             }
         };
         addResources('extensions', collectAutoExtensionEntries(projectDirs.extensions), projectMetadata, projectOverrides.extensions, projectBaseDir);
-        addResources('skills', [
-            ...collectAutoSkillEntries(projectDirs.skills),
-            ...projectAgentsSkillDirs.flatMap((dir) => collectAutoSkillEntries(dir))
-        ], projectMetadata, projectOverrides.skills, projectBaseDir);
+        addResources('skills', collectAutoSkillEntries(projectDirs.skills), projectMetadata, projectOverrides.skills, projectBaseDir);
         addResources('prompts', collectAutoPromptEntries(projectDirs.prompts), projectMetadata, projectOverrides.prompts, projectBaseDir);
         addResources('themes', collectAutoThemeEntries(projectDirs.themes), projectMetadata, projectOverrides.themes, projectBaseDir);
         addResources('extensions', collectAutoExtensionEntries(userDirs.extensions), userMetadata, userOverrides.extensions, globalBaseDir);
-        addResources('skills', [
-            ...collectAutoSkillEntries(userDirs.skills),
-            ...collectAutoSkillEntries(userAgentsSkillsDir)
-        ], userMetadata, userOverrides.skills, globalBaseDir);
+        addResources('skills', collectAutoSkillEntries(userDirs.skills), userMetadata, userOverrides.skills, globalBaseDir);
         // Bundled default skills shipped with the package
         const bundledMetadata = {
             source: 'auto',

package/dist/app/settings-manager.d.ts

@@ -336,7 +336,7 @@ export declare class SettingsManager {
     /** Whether session traces and ClickHouse logs are uploaded. Default: true. */
     getTelemetry(): boolean;
     setTelemetry(enabled: boolean): void;
-    /** Whether dev mode is enabled (file tools, AGENTS.md, verbose logging). Default: false. */
+    /** Whether dev mode is enabled (AGENTS.md, dev resources, verbose logging). Default: false. */
     getDevMode(): boolean;
     setDevMode(enabled: boolean): void;
     /** Get all connection metadata (names, types, field names — no secrets). */

package/dist/app/settings-manager.js

@@ -955,7 +955,7 @@ export class SettingsManager {
         this.markModified('telemetry');
         this.save();
     }
-    /** Whether dev mode is enabled (file tools, AGENTS.md, verbose logging). Default: false. */
+    /** Whether dev mode is enabled (AGENTS.md, dev resources, verbose logging). Default: false. */
     getDevMode() {
         return this.settings.devMode ?? false;
     }

package/dist/app/skill-proposals/catalog.d.ts

@@ -1,5 +1,9 @@
 import { type ProposalRoots } from './proposal-fs.js';
-export type ProposalKind = 'create' | 'update';
+export declare const PROPOSAL_KIND: {
+    readonly CREATE: "create";
+    readonly UPDATE: "update";
+};
+export type ProposalKind = (typeof PROPOSAL_KIND)[keyof typeof PROPOSAL_KIND];
 export interface SkillProposalSummary {
     name: string;
     proposalDir: string;

package/dist/app/skill-proposals/catalog.js

@@ -8,6 +8,10 @@ import { lstatSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { initializeSkillProposalRoots, liveSkillDir, proposalDir } from './proposal-fs.js';
 const SKILL_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+export const PROPOSAL_KIND = {
+    CREATE: 'create',
+    UPDATE: 'update'
+};
 /** Passive discovery for status/prompt/reviewer; it must not mutate proposal folders. */
 export function listSkillProposals(roots) {
     initializeSkillProposalRoots(roots);
@@ -15,7 +19,9 @@ export function listSkillProposals(roots) {
         .filter((entry) => isValidProposalDirectoryEntry(roots, entry))
         .map((entry) => {
         const targetLiveSkillDir = liveSkillDir(roots, entry.name);
-        const kind = pathExistsForLstat(targetLiveSkillDir) ? 'update' : 'create';
+        const kind = pathExistsForLstat(targetLiveSkillDir)
+            ? PROPOSAL_KIND.UPDATE
+            : PROPOSAL_KIND.CREATE;
         return {
             name: entry.name,
             proposalDir: proposalDir(roots, entry.name),

package/dist/app/skill-proposals/review.d.ts

@@ -1,4 +1,4 @@
-import type { ProposalKind } from './catalog.js';
+import { type ProposalKind } from './catalog.js';
 import { type ProposalRoots } from './proposal-fs.js';
 export interface SkillProposalReviewSnapshot {
     name: string;