@components-kit/open-workbook 0.1.6 → 0.1.8

package/assets/excel-addin/manifest.xml

@@ -5,7 +5,7 @@
   xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides"
   xsi:type="TaskPaneApp">
   <Id>6f2d2ac1-69b0-4eb6-a256-0a1fcb000001</Id>
-  <Version>0.1.6.0</Version>
+  <Version>0.1.8.0</Version>
   <ProviderName>ComponentsKit</ProviderName>
   <DefaultLocale>en-US</DefaultLocale>
   <DisplayName DefaultValue="OpenWorkbook" />

package/assets/instructions/open-workbook-excel/SKILL.md

@@ -21,6 +21,10 @@ If the add-in is disconnected, ask the user to start their agent UI so it launch
 
 ## Tool Selection
 
+- When the target is unknown, use lookup first: `excel.lookup.search_workbook`, `excel.lookup.find_headers`, `excel.lookup.find_tables_by_columns`, `excel.lookup.find_entity`, or `excel.lookup.resolve_range`, then inspect one candidate with `excel.lookup.inspect_match`.
+- Start with compact context tools for known large scopes: `excel.workbook.get_summary`, `excel.workbook.get_used_range_summary`, `excel.sheet.get_summary`, `excel.table.get_schema`, and `excel.range.get_summary`.
+- Prefer `excel.range.read_compact` and `excel.table.read_compact` for exploratory data reads. Page or project only the rows, columns, and facets needed for the current task.
+- Use `excel.validate.compact` for validation proof when counts/examples are enough. Fetch `excel://compact/{resource_id}` details only if the user or task needs the full report.
 - Use `excel.range.read_*` for scoped cell data and metadata.
 - Use `excel.table.*` for structured table rows, filters, sorts, totals, and table resizing.
 - Use `excel.template.*`, `excel.style.*`, and `excel.formula.*` when preserving or repairing templates matters.
@@ -45,19 +49,19 @@ For detailed routing, read `references/tool-selection.md`.
 - Never write cell-by-cell loops. Batch values, formulas, number formats, and styles as 2D matrices over contiguous ranges.
 - Never pad a broad range write with `null` or blanks when only a smaller range is intended. Write the smallest changed rectangle or use explicit clear tools.
 - Read only the workbook properties needed for the task. Avoid broad workbook scans unless the task is audit, validation, search, or repair.
+- Do not use full range/table reads when compact summaries, schemas, samples, or projected pages are enough. Full reads are for explicit user requests, audits, exports, or exact-data tasks.
 - Treat `CAPABILITY_UNAVAILABLE`, partial capability warnings, and Office.js host limits as real results. Explain them and choose a supported path.
 - Preserve existing template conventions over generic formatting rules.
 - After mutation, validate the affected area and surface backups, transaction IDs, warnings, diffs, and rollback options.
+- Treat `compactProof` on mutation results as the default reportable proof. Do not read back whole changed sheets unless exact cell data is required.
 
 ## Critical Recipes
 
-- Sheet with formulas: prefer `excel.workflow.create_formula_sheet`; if using separate tools, create the sheet, write labels/constants with `excel.range.write_values`, write formulas with `excel.range.write_formulas`, write number formats with `excel.range.write_number_formats`, then validate with `excel.formula.validate` or `excel.validate.no_formula_errors`. Do not put formula strings into `write_values`.
-- Large table reorder/filter/sort/append/update: always inspect the table first with `excel.table.get_info` or `excel.workbook.get_workbook_map`. Use bounded `excel.table.read` only when row data is needed, then use `excel.table.reorder_columns`, `excel.table.apply_filters`, `excel.table.sort`, `excel.table.append_rows`, or `excel.table.update_rows`. For table filters, prefer `excel.table.apply_filters` over generic filter tools. After mutation, validate with `excel.validate.tables` for table changes and `excel.validate.filters` for filter/sort changes. Never clear, recreate, or rewrite the whole table for these tasks.
-- Formula repair: prefer `excel.workflow.repair_formula_errors` when the error range and source formula range are known. Otherwise find errors, read nearby formula patterns, inspect dependencies, repair with `excel.formula.repair_patterns`, `excel.formula.fill_down`, `excel.formula.fill_right`, or scoped `excel.range.write_formulas`, recalculate if needed, then validate. Never convert formulas to values unless explicitly requested.
-- Template report: prefer `excel.workflow.create_template_report`; if using separate tools, create the sheet from template, clear/fill declared regions, compare styles, repair style drift, and validate against the template.
-- Snapshot/diff/rollback preview: after discovery, prefer `excel.workflow.preview_risky_edit` for a scoped risky edit with a non-empty minimal operation list. If using separate tools, create a before snapshot, make the scoped change, create an after snapshot, call `excel.diff.summarize` or `excel.snapshot.compare` with both snapshot IDs, then use rollback preview tools without actually rolling back unless asked.
-- Pivot/chart summary: prefer `excel.workflow.create_pivot_chart_summary`; if using separate tools, check capability, create the PivotTable, refresh it, create/update the chart, refresh/update the chart source, and validate the PivotTable source before reporting success.
-- Multi-agent work: start with `excel.collab.get_status`, create or inspect the task, acquire the narrowest lock, follow conflict guidance, perform or plan the scoped operation, then release locks.
+- Sheet/formula, template-report, pivot/chart, risky-edit, and formula-repair tasks: prefer the matching `excel.workflow.*` tool, then validate compactly.
+- Large table work: inspect schema first, read compact pages only when row data is needed, mutate with table-native tools, then validate tables/filters.
+- Unknown target work: resolve the sheet/table/column/range with lookup tools before reading data.
+- Snapshot/diff/rollback proof: prefer compact diff or risky-edit workflow results; fetch full compact resources only for detailed review.
+- Multi-agent work: use collaboration/task/lock tools before mutation.
 
 ## Workflow References
 

package/assets/instructions/open-workbook-excel/references/performance.md

@@ -9,6 +9,8 @@ Fast Excel automation is part of correctness. Slow workflows push agents toward
 - Use table APIs for table-shaped work.
 - Group writes by workbook, sheet, and contiguous range.
 - Read only requested properties.
+- Start unknown targets with lookup tools, then inspect one candidate.
+- Start known large scopes with compact summaries and schemas.
 - Use `excel.runtime.get_capabilities` before trying expensive or host-limited features.
 
 ## Reads
@@ -18,9 +20,14 @@ Fast Excel automation is part of correctness. Slow workflows push agents toward
 - For formula review, read formulas or formula patterns.
 - For formatting review, read number formats or styles only for the relevant range.
 - For table analysis, read the table instead of a sheet-sized range.
+- For unknown sheet/table/header/entity targets, use `excel.lookup.*` before reading cells.
+- For exploratory reads, use `excel.range.read_compact` or `excel.table.read_compact` before full reads.
 
 Avoid workbook-wide reads unless the task is search, validation, audit, or discovery.
 
+Compact reads return payload/token telemetry, truncation status, and continuation metadata. Page only when more rows or columns are needed.
+When a compact response includes `resourceUri`, fetch it only if the full detail is required.
+
 ## Writes
 
 - Use one batch or plan for related edits.
@@ -43,3 +50,5 @@ Automatic timeout retry is limited to style-only batches because repeating the s
 ## Telemetry
 
 Read tool results for duration, sync count, payload bytes, cells read/written, range count, chunk count, engine, and warnings. Use that telemetry to explain unusually slow or partial work.
+For compact reads, also inspect `estimatedTokens`, `truncated`, and `nextPage` before requesting more workbook data.
+For mutation results, prefer the returned `compactProof` summary over reading changed ranges back into the model.

package/assets/instructions/open-workbook-excel/references/tool-selection.md

@@ -9,22 +9,29 @@ Choose the narrowest Open Workbook MCP interface that preserves workbook intent.
 - Active workbook and selection context: `excel.runtime.get_active_context`
 - Host/tool capability matrix: `excel.runtime.get_capabilities`
 - Workbook structure: `excel.workbook.get_workbook_map`
+- Compact workbook structure: `excel.workbook.get_summary`, `excel.workbook.get_used_range_summary`
+- Workbook lookup: `excel.lookup.search_workbook`, `excel.lookup.find_headers`, `excel.lookup.find_tables_by_columns`, `excel.lookup.find_entity`, `excel.lookup.resolve_range`, `excel.lookup.inspect_match`
 - Open workbooks: `excel.workbook.list_open_workbooks`
-- Sheets: `excel.sheet.list`, `excel.sheet.get_info`, `excel.sheet.get_used_range`
+- Sheets: `excel.sheet.list`, `excel.sheet.get_info`, `excel.sheet.get_summary`, `excel.sheet.get_used_range`
 
 Prefer `excel.workflow.prepare_session` as the first call. If capabilities are unknown because the add-in is disconnected, stop and ask for runtime setup instead of guessing.
 
 ## Reading Data
 
+- Compact range/table discovery: `excel.range.get_summary`, `excel.table.get_schema`
+- Unknown target lookup: `excel.lookup.search_workbook`, `excel.lookup.find_headers`, `excel.lookup.find_tables_by_columns`, `excel.lookup.find_entity`, `excel.lookup.resolve_range`
+- Focused candidate preview: `excel.lookup.inspect_match`
+- Compact bounded reads: `excel.range.read_compact`, `excel.table.read_compact`
+- Stored compact details: `excel.compact.get_resource`, `excel.compact.list_resources`
 - Values only: `excel.range.read_values`
 - Formulas only: `excel.range.read_formulas`
 - Display text for user-visible output: `excel.range.read_display_text`
 - Formatting: `excel.range.read_number_formats`, `excel.range.read_styles`
 - Full cell payload: `excel.range.read_full`
 - Search and diagnostics: `excel.range.search`, `excel.range.find_blank_cells`, `excel.range.find_errors`
-- Table-shaped data: `excel.table.read`; pass `columns`, `rowOffset`, `rowLimit`, and include flags for large tables
+- Table-shaped full data: `excel.table.read`; pass `columns`, `rowOffset`, `rowLimit`, and include flags for large tables
 
-Use explicit sheet/address ranges whenever possible. Use used-range or workbook-wide scans only for audits, validation, search, or discovery. For simple reads, use the facet-specific range tools instead of `excel.range.read_full`.
+Use lookup tools before reading when the target sheet, table, header, entity, or range is unknown. Use compact summaries or schemas before cell bodies once the target scope is known. Use explicit sheet/address ranges whenever possible. Use used-range or workbook-wide scans only for audits, validation, search, or discovery. For simple reads, use `excel.range.read_compact` or the facet-specific range tools instead of `excel.range.read_full`.
 
 ## Writing Data
 
@@ -55,7 +62,7 @@ When a noninteractive agent run cannot apply a mutation, create an `excel.plan.c
 
 ## Tables, Filters, And Sorts
 
-- Inspect tables: `excel.table.list`, `excel.table.get_info`, `excel.table.read`
+- Inspect tables: `excel.table.list`, `excel.table.get_info`, `excel.table.get_schema`, `excel.table.read_compact`
 - Append or update rows: `excel.table.append_rows`, `excel.table.update_rows`
 - Reorder columns: `excel.table.reorder_columns`
 - Resize or structure changes: `excel.table.resize`, `excel.table.copy_structure`
@@ -65,7 +72,7 @@ When a noninteractive agent run cannot apply a mutation, create an `excel.plan.c
 Use table tools instead of range tools when the target is an Excel table. This preserves headers, totals rows, filters, structured references, and table styles.
 Before table reorder, filter, sort, append, or update operations, call `excel.table.get_info` or `excel.workbook.get_workbook_map`. For table filters, use `excel.table.apply_filters` rather than generic filter tools. After table structure or row mutations, call `excel.validate.tables`; after filter/sort changes, call `excel.validate.filters`.
 Do not clear and recreate a table to reorder columns; use `excel.table.reorder_columns`, or stop for confirmation before any destructive rebuild.
-For large tables, avoid full `excel.table.read` unless the user asks for all rows. Pass `rowLimit`, `rowOffset`, and `columns` for targeted discovery, then mutate with table-native tools.
+For large tables, avoid full `excel.table.read` unless the user asks for all rows. Use `excel.table.get_schema` first, then `excel.table.read_compact` with `rowLimit`, `rowOffset`, and `columns` for targeted discovery before mutating with table-native tools.
 
 ## Templates, Styles, And Formulas
 
@@ -94,14 +101,17 @@ Use `excel.workflow.create_pivot_chart_summary` for standard summary requests th
 ## Validation And Recovery
 
 - Workbook/sheet health: `excel.validate.workbook`, `excel.validate.sheet`
+- Compact validation proof: `excel.validate.compact`
 - Formula errors: `excel.validate.no_formula_errors`, `excel.formula.find_errors`
 - Broken references: `excel.validate.no_broken_references`
 - Template/style/table/filter checks: `excel.validate.template_consistency`, `excel.validate.styles`, `excel.validate.tables`, `excel.validate.filters`
 - Unintended changes: `excel.validate.no_unintended_changes`
+
+Prefer `excel.validate.compact` when issue counts, severity counts, and a few examples are enough. It returns a compact resource URI for the full report.
 - Combined risky edit workflow: `excel.workflow.preview_risky_edit`
-- Snapshots and diffs: `excel.snapshot.create`, `excel.snapshot.compare`, `excel.diff.summarize`
+- Snapshots and diffs: `excel.snapshot.create`, `excel.snapshot.get_compact`, `excel.snapshot.compare_compact`, `excel.diff.summarize`, `excel.diff.get_compact`
 - Rollback: `excel.plan.rollback`, `excel.transaction.preview_rollback`, `excel.transaction.rollback`, `excel.transaction.preview_rollback_chain`, `excel.transaction.rollback_chain`
 - File backups: `excel.backup.create_file`, `excel.backup.verify`, `excel.backup.restore_file`
 
 Always present validation issues with severity and target, not vague success/failure language.
-Diff tools require two snapshots. For risky scoped edits, use `excel.workflow.preview_risky_edit` after discovery when available, with a non-empty minimal operation list. If using separate tools, create a before snapshot, make the scoped edit, create an after snapshot, call `excel.diff.summarize` or `excel.snapshot.compare`, then preview rollback with `excel.transaction.preview_rollback` or `excel.transaction.preview_rollback_chain`.
+Diff tools require two snapshots. For risky scoped edits, use `excel.workflow.preview_risky_edit` after discovery when available, with a non-empty minimal operation list. If using separate tools, create a before snapshot, make the scoped edit, create an after snapshot, call `excel.diff.summarize`, `excel.diff.get_compact`, or `excel.snapshot.compare_compact`, then preview rollback with `excel.transaction.preview_rollback` or `excel.transaction.preview_rollback_chain`.