@components-kit/open-workbook 0.1.3 → 0.1.5

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

@@ -12,13 +12,11 @@ Use Open Workbook MCP for live desktop Excel work. Prefer it over manual UI auto
 Start every workbook session with:
 
 ```text
-excel.runtime.get_status
-excel.runtime.get_active_context
-excel.runtime.get_capabilities
-excel.workbook.get_workbook_map
-excel.collab.get_status
+excel.workflow.prepare_session
 ```
 
+If `excel.workflow.prepare_session` is unavailable, call `excel.runtime.get_status`, `excel.runtime.get_active_context`, `excel.runtime.get_capabilities`, `excel.workbook.get_workbook_map`, and `excel.collab.get_status`.
+
 If the add-in is disconnected, ask the user to start their agent UI so it launches the configured Open Workbook MCP command, then open Excel and load the Open Workbook add-in. For manual troubleshooting, run `npx -y @components-kit/open-workbook@latest mcp` and retry. Do not fake workbook state from stale assumptions.
 
 ## Tool Selection
@@ -28,6 +26,12 @@ If the add-in is disconnected, ask the user to start their agent UI so it launch
 - Use `excel.template.*`, `excel.style.*`, and `excel.formula.*` when preserving or repairing templates matters.
 - Use `excel.plan.*` for previewable multi-step changes that need rollback and stale-target checks.
 - Use `excel.batch.*` for compact, direct range mutations that still need backups, fingerprints, permissions, and transaction logging.
+- Use `excel.workflow.create_formula_sheet` for standard sheet creation with values, formulas, number formats, and formula validation in one response.
+- Use `excel.workflow.repair_formula_errors` for formula error repair when you have an error range plus a source formula range or exact formulas to write.
+- Use `excel.workflow.preview_risky_edit` for scoped risky edits that need before/after snapshots, a diff, and rollback preview in one response. Provide at least one minimal scoped operation and leave `apply` enabled unless the user asked for preview only.
+- Use `excel.workflow.create_template_report` for standard template report creation that needs region clear/fill, style comparison/repair, and validation in one response.
+- Use `excel.workflow.create_pivot_chart_summary` for standard PivotTable plus chart summary tasks that need create, refresh, and validation in one response.
+Combined mutating workflows include a read-only preflight payload before mutation; still prefer `excel.workflow.prepare_session` first when possible.
 - Use `excel.validate.*` before and after risky changes.
 - Use `excel.backup.*`, `excel.snapshot.*`, and `excel.transaction.*` for recovery, audit, rollback previews, and rollback chains.
 - Use `excel.task.*`, `excel.lock.*`, `excel.collab.*`, and `excel.conflict.*` for multi-agent workbook work.
@@ -38,11 +42,22 @@ For detailed routing, read `references/tool-selection.md`.
 
 - Never bypass Open Workbook's safety lifecycle for mutations: permissions, scoped locks, snapshots, backups, fingerprints, Office.js execution, validation, transaction records, and rollback metadata.
 - 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.
 - 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.
 
+## 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: inspect with `excel.table.get_info` and 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`. 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: read collaboration status, create or inspect the task, acquire the narrowest lock, follow conflict guidance, perform or plan the scoped operation, then release locks.
+
 ## Workflow References
 
 - Read `references/tool-selection.md` to choose the most efficient MCP interface.

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

@@ -5,13 +5,14 @@ Choose the narrowest Open Workbook MCP interface that preserves workbook intent.
 ## Session And Discovery
 
 - Runtime health: `excel.runtime.get_status`
+- Full workflow setup: `excel.workflow.prepare_session`
 - 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`
 - Open workbooks: `excel.workbook.list_open_workbooks`
 - Sheets: `excel.sheet.list`, `excel.sheet.get_info`, `excel.sheet.get_used_range`
 
-If capabilities are unknown because the add-in is disconnected, stop and ask for runtime setup instead of guessing.
+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
 
@@ -31,11 +32,19 @@ Use explicit sheet/address ranges whenever possible. Use used-range or workbook-
 - Simple formulas: `excel.range.write_formulas`
 - Number formats: `excel.range.write_number_formats`
 - Styles: `excel.range.write_styles`
+- Combined formula sheet creation: `excel.workflow.create_formula_sheet`
+- Combined formula error repair: `excel.workflow.repair_formula_errors`
 - Multiple related range edits: `excel.batch.validate`, `excel.batch.dry_run`, `excel.batch.apply`
+- Scoped risky edit with diff and rollback preview: `excel.workflow.preview_risky_edit`
 - Previewable or user-reviewable edits: `excel.plan.create`, `excel.plan.preview`, `excel.plan.apply`
 - Stale plan handling: `excel.plan.refresh_preview`, `excel.plan.rebase`
 
-Prefer `excel.plan.*` when a user should review a diff, when formulas/templates are at risk, or when rollback clarity matters. Prefer `excel.batch.*` for compact, well-scoped range mutations.
+Prefer `excel.workflow.create_formula_sheet` for standard new sheets that need values, formulas, number formats, and validation. Prefer `excel.workflow.repair_formula_errors` for formula error repair when an error range and source formula range are known. Prefer `excel.workflow.preview_risky_edit` when a risky scoped edit should apply and return before/after snapshots, a diff, transaction id, and rollback preview in one response. Provide at least one minimal scoped operation and leave `apply` enabled unless the user asked for preview only. Prefer `excel.plan.*` when a user should review a diff before applying, when formulas/templates are at risk, or when rollback clarity matters. Prefer `excel.batch.*` for compact, well-scoped range mutations.
+Combined mutating workflows include an internal read-only preflight payload before mutation; still prefer `excel.workflow.prepare_session` first when possible.
+Values, formulas, formats, and styles are separate workbook facets. Use `excel.range.write_values` for constants only, `excel.range.write_formulas` for formulas beginning with `=`, and `excel.range.write_number_formats` for display formats. Do not merge formulas into a values write just because the matrix is convenient.
+Do not pad a large range write with `null`, blank strings, or unchanged cells when only one cell or a smaller rectangle should change. Use the smallest changed target range, or use `excel.range.clear_values_keep_format` for intentional clearing.
+
+When a noninteractive agent run cannot apply a mutation, create an `excel.plan.create` draft with operations that use actual MCP tool names and nested `args`. Example operations should look like `{ "tool": "excel.range.write_formulas", "args": { ... } }`, not vague prose or broad workbook rewrites.
 
 ## Tables, Filters, And Sorts
 
@@ -48,27 +57,31 @@ Prefer `excel.plan.*` when a user should review a diff, when formulas/templates
 
 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.
 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.
 
 ## Templates, Styles, And Formulas
 
 - Template discovery and registration: `excel.template.detect_templates`, `excel.template.register`, `excel.template.list`
+- Combined template report creation: `excel.workflow.create_template_report`
 - New period/report sheet: `excel.template.create_sheet_from_template`
 - Template data fills: `excel.template.clear_data_regions`, `excel.template.fill_regions`
 - Template validation/repair: `excel.template.validate_sheet_against_template`, `excel.template.repair_sheet_from_template`
 - Style fingerprints and copy: `excel.style.get_fingerprint`, `excel.style.compare_fingerprint`, `excel.style.copy_from_template`
-- Formula patterns and repair: `excel.formula.read_patterns`, `excel.formula.copy_patterns`, `excel.formula.validate`, `excel.formula.repair_patterns`
+- Formula patterns and repair: `excel.workflow.repair_formula_errors`, `excel.formula.read_patterns`, `excel.formula.copy_patterns`, `excel.formula.validate`, `excel.formula.repair_patterns`
 - Formula dependency safety: `excel.formula.get_dependency_graph`, `excel.formula.trace_precedents`, `excel.formula.trace_dependents`
 
-Use these tools when the workbook has established formatting, formula patterns, reports, print layout, or period templates.
+Use `excel.workflow.create_template_report` for standard period/report creation from a registered template. Use these tools when the workbook has established formatting, formula patterns, reports, print layout, or period templates.
+Formula repair requires both diagnosis and a repair action: use `excel.workflow.repair_formula_errors` when possible, or find formula errors, read formula patterns, inspect dependencies when references may shift, repair with formula-aware tools, then validate. Do not use `excel.formula.convert_to_values` as a repair.
 
 ## Pivots And Charts
 
 - Pivot inspect/refresh: `excel.pivot.list`, `excel.pivot.get_info`, `excel.pivot.refresh`, `excel.pivot.refresh_all`
+- Combined pivot/chart summary: `excel.workflow.create_pivot_chart_summary`
 - Pivot create/rebuild: `excel.pivot.create`, `excel.pivot.rebuild_with_source`
 - Pivot template work: `excel.pivot.get_fingerprint`, `excel.pivot.compare_fingerprint`, `excel.pivot.copy_from_template`, `excel.pivot.repair_from_template`
 - Chart inspect/create/update: `excel.chart.list`, `excel.chart.get_info`, `excel.chart.create`, `excel.chart.update_data_source`, `excel.chart.copy_from_template`
 
-For host-limited pivot/chart dimensions, report capability warnings and avoid claiming deterministic replay.
+Use `excel.workflow.create_pivot_chart_summary` for standard summary requests that need a PivotTable plus chart and post-create validation. For host-limited pivot/chart dimensions, report capability warnings and avoid claiming deterministic replay.
 
 ## Validation And Recovery
 
@@ -77,8 +90,10 @@ For host-limited pivot/chart dimensions, report capability warnings and avoid cl
 - 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`
+- Combined risky edit workflow: `excel.workflow.preview_risky_edit`
 - Snapshots and diffs: `excel.snapshot.create`, `excel.snapshot.compare`, `excel.diff.summarize`
 - 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`.

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

@@ -10,6 +10,8 @@ These are default Open Workbook MCP workflows. Adjust scope and validation to th
 4. Call `excel.workbook.get_workbook_map`.
 5. For a specific sheet, call `excel.sheet.get_used_range` and scoped `excel.range.read_*` tools.
 
+Use `excel.workflow.prepare_session` when available to combine the first four calls plus collaboration state.
+
 Use display text when reporting what a user sees. Use values/formulas/number formats when making calculations or edits.
 
 ## Read And Analyze Data
@@ -31,8 +33,14 @@ Do not read the whole workbook when a named table, used range, or explicit range
 
 For a one-range value update, direct `excel.range.write_values` is acceptable because it routes through the backend safety lifecycle.
 
+For new sheets with formulas and number formats, prefer `excel.workflow.create_formula_sheet`.
+
+Combined mutating workflows return an internal `preflight` payload with runtime status, active context, capabilities, workbook map, and collaboration state before they mutate. Still prefer `excel.workflow.prepare_session` first when possible; use the matched combined workflow directly when the task is standard and speed/model reliability matters.
+
 ## Create A New Period Sheet From Template
 
+Prefer `excel.workflow.create_template_report` for standard template report creation.
+
 1. Call `excel.template.list` or `excel.template.detect_templates`.
 2. Register the template if needed with `excel.template.register`.
 3. Create the sheet with `excel.template.create_sheet_from_template`.
@@ -41,14 +49,17 @@ For a one-range value update, direct `excel.range.write_values` is acceptable be
 6. Validate with `excel.template.validate_sheet_against_template`.
 
 If no registered template exists, warn before mutation. Preserve the template's formatting, formulas, filters, print layout, tables, freeze panes, and named ranges.
+Do not replace this workflow with `excel.sheet.copy` unless the user asks for a raw sheet duplicate or the template tool is unavailable.
 
 ## Repair Formulas Or Styles
 
-1. Identify the template and target sheet/range.
-2. Capture current state with `excel.snapshot.create` when the repair may affect user work.
-3. Compare fingerprints with `excel.style.compare_fingerprint` or formula patterns with `excel.formula.validate_against_template`.
-4. Repair with `excel.repair.style_from_template`, `excel.repair.formulas_from_template`, `excel.style.copy_from_template`, or `excel.formula.repair_patterns`.
-5. Validate again and report any Office.js capability-status warnings.
+Prefer `excel.workflow.repair_formula_errors` for ordinary formula error repairs when you can identify the error range plus a source formula or explicit formula matrix.
+
+1. Find formula errors with `excel.formula.find_errors`, `excel.range.find_errors`, or `excel.validate.no_formula_errors`.
+2. Read neighboring patterns with `excel.formula.read_patterns` and dependencies with `excel.formula.get_dependency_graph` or trace tools.
+3. Capture current state with `excel.snapshot.create` when the repair may affect user work.
+4. Repair with `excel.formula.repair_patterns`, `excel.formula.fill_down`, `excel.formula.fill_right`, or scoped `excel.range.write_formulas`; for styles use `excel.style.copy_from_template` or `excel.style.repair_consistency`.
+5. Recalculate when formulas changed, validate with `excel.formula.validate` or `excel.validate.no_formula_errors`, and report warnings.
 
 Do not convert formulas to values unless the user explicitly asks or the workflow requires a static export.
 
@@ -76,15 +87,32 @@ Avoid full-table rewrites for layout changes such as column reorder; they are sl
 
 ## Create Or Update Pivots And Charts
 
+For a standard summary PivotTable plus chart, prefer `excel.workflow.create_pivot_chart_summary`.
+
 1. Confirm active host support with `excel.runtime.get_capabilities`.
 2. Inspect source tables/ranges and existing objects.
-3. For pivots, use `excel.pivot.validate_source`, `excel.pivot.create`, or `excel.pivot.rebuild_with_source`.
+3. For pivots, validate first with `excel.pivot.validate_source`, then use `excel.pivot.create` or `excel.pivot.rebuild_with_source`.
 4. For charts, use `excel.chart.create` or `excel.chart.update_data_source`.
 5. For template parity, use pivot/chart fingerprint or copy-from-template tools.
-6. Refresh and validate before reporting success.
+6. Refresh pivots and charts with `excel.pivot.refresh`/`excel.pivot.refresh_all` and `excel.chart.refresh`/`excel.chart.update_data_source`, then validate before reporting success.
 
 When Office.js cannot expose deterministic pivot/chart dimensions, return the capability warning instead of inventing proof.
 
+## Snapshot, Diff, And Rollback Preview
+
+Use `excel.workflow.preview_risky_edit` after discovery when the requested edit is scoped and the user expects proof, diff, and rollback preview. Pass a non-empty minimal operation list and leave `apply` enabled unless the user asked for preview only. It creates the before snapshot, plan preview, scoped apply, after snapshot, diff, and rollback preview in one response.
+
+If the combined workflow is unavailable:
+
+1. Create a before snapshot with `excel.snapshot.create` or `excel.workbook.snapshot`.
+2. Apply only the scoped edit requested by the user.
+3. Create an after snapshot.
+4. Compare with `excel.diff.summarize`, `excel.diff.create`, or `excel.snapshot.compare`.
+5. Preview rollback with `excel.transaction.preview_rollback` or `excel.transaction.preview_rollback_chain`.
+
+Do not actually roll back unless the user explicitly asks for rollback apply.
+Do not stop after creating a plan or making the edit; a snapshot/diff/rollback-preview workflow is incomplete until the diff and rollback preview tools have both run.
+
 ## Save, Export, And Back Up
 
 1. Use `excel.workbook.save` for normal save.