@stephen-lord/docs 1.0.0

package/dist/agent-skills/openai-skills/spreadsheets/examples/features/set_merge_cells.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+
+from artifact_tool import FileOutputType, SpreadsheetArtifact
+
+
+def main() -> None:
+    spreadsheet = SpreadsheetArtifact("Scores")
+    sheet = spreadsheet.create_sheet("MonsterBattle")
+
+    sheet.range("B2:D2").set_values([["Monster", "Level", "Info"]])
+    sheet.range("B3:D4").set_values(
+        [["Lizardman", "100", "Fire type"], ["Hydra", "90", "Water type"]]
+    )
+
+    B5_to_D5_range = sheet.range("B5:D5")
+    B5_to_D5_range.merge()
+
+    # After merging, you can edit the value of the merged cell by either
+    # updating the range itself or setting the top-left cell
+    B5_to_D5_range.set_value("Winner TBD")
+    sheet.cell("B5").set_value("Winner TBD V2")
+
+    # Set formatting and styling on the merged cells.
+    B5_to_D5_range.format.fill.set_solid_color("#E8E4F7")  # lavender
+
+    # Render
+    output_dir = Path(__file__).resolve().parent / "golden_rendered_images" / "set_merge_cells"
+    output_path = spreadsheet.render(output=output_dir)
+    print(f"Spreadsheet rendered to {output_path} up till F6")
+
+    spreadsheet.save(
+        file_type=FileOutputType.C_STAR_PROTO_JSON,
+        filename=output_dir / "workbook__auto.json",
+        overwrite=True,
+    )
+
+    # Export
+    # output_path = spreadsheet.export()
+    # print(f"Spreadsheet exported to {output_path}")
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/features/set_number_formats.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from artifact_tool import FileOutputType, SpreadsheetArtifact
+
+
+def main() -> None:
+    # jons_spreadsheet = SpreadsheetArtifact.read(
+    #     file_path=Path(__file__).resolve().parent.parent.parent.parent
+    #     / "js"
+    #     / "oai_js_walnut"
+    #     / "output_xlsx.bin"
+    # )
+
+    # New spreadsheet artifact
+    spreadsheet = SpreadsheetArtifact("TextStyles")
+    sheet = spreadsheet.sheet("Examples")
+
+    # Seed some data
+    sheet.set_column_widths("B:C", 20)  # so we can see the alignments
+    sheet.set_row_heights(start_row_index=1, end_row_index=20, height=20)
+    sheet.range("A1:D1").set_values([["priority", "example", "unformatted example", "description"]])
+    sheet.range("A3:D24").set_values(
+        [
+            ["p1", "General 123", "General 123", "General; no formatting"],  # row 3
+            ["p1", 12345, 12345, "Number format"],  # row 4
+            ["p1", 1.23, 1.23, "Number format with more decimals"],  # row 5
+            [
+                "p2",
+                -12345.6,
+                -12345.6,
+                "Customizing negative numbers (red/black x parentheses or not), decimal places, and whether or not thousand separator is used",
+            ],  # row 6
+            ["p1", 12345.6, 12345.6, "Currency"],  # row 7
+            ["p1", -12345.6, -12345.6, "Currency - negative"],  # row 8
+            ["p2", 12345.6, 12345.6, "Accounting"],  # row 9
+            ["p2", -12345.6, -12345.6, "Accounting - negative"],  # row 10
+            ["p1", 45917, 45917, '"2025/09/17" without quotes - Short date'],  # row 11
+            ["p2", 45917, 45917, '"2025/09/17" without quotes - Long date'],  # row 12
+            [
+                "p4",
+                45917,
+                45917,
+                '"2025/09/17" without quotes - All sorts of arbitrary date formats',
+            ],  # row 13
+            ["p2", 0.36180555555555555, 0.36180555555555555, "Time"],  # row 14
+            [
+                "p4",
+                0.36180555555555555,
+                0.36180555555555555,
+                "All sorts of arbitrary date formats",
+            ],  # row 15
+            ["p1", 0.456789, 0.456789, "Percentage, 2 decimals"],  # row 16
+            ["p1", 0.456789, 0.456789, "Percentage, 0 decimals"],  # row 17
+            ["p2", 0.456789, 0.456789, "Percentage, arbitrary decimals"],  # row 18
+            ["p3", 0.125, 0.125, "Fractions; as sixteenths"],  # row 19
+            [
+                "p1",
+                0.023400000000000001,
+                0.023400000000000001,
+                "Scientific with specified number of digits (4 in this case)",
+            ],  # row 20
+            [
+                "p1",
+                "2025/09/17",
+                "2025/09/17",
+                '"2025/09/17" without quotes - Text; appears exactly as typed, left justified',
+            ],  # row 21
+            ["p3", 123, 123, "zip code"],  # row 22
+            ["p2", 1234567890, 1234567890, "Phone number"],  # row 23
+            ["p2", -1234567.8901200001, -1234567.8901200001, "Other currencies"],  # row 24
+        ]
+    )
+
+    # Two decimals
+    sheet.cell("B4").format.number_format.format_code = "0.00"
+    # More decimals
+    sheet.cell("B5").format.number_format.format_code = "0.0000"
+    # Format red for negative
+    sheet.cell("B6").format.number_format.format_code = r"#,##0.00;[Red](#,##0.00)"
+    # Currency, positive or negative
+    sheet.cell("B7").format.number_format.format_code = '"$"#,##0.00'
+    sheet.cell("B8").format.number_format.format_code = '"$"#,##0.00'
+
+    # Accounting format
+    sheet.cell(
+        "B9"
+    ).format.number_format.format_code = r"_($* #,##0.00_);_($* (#,##0.00);_($* \"-\"??_);_(@_)"
+    sheet.cell(
+        "B10"
+    ).format.number_format.format_code = r"_($* #,##0.00_);_($* (#,##0.00);_($* \"-\"??_);_(@_)"
+
+    # Short date
+    sheet.cell("B11").format.number_format.format_code = "m/d/yy"
+
+    # Long date with locale
+    sheet.cell("B12").format.number_format.format_code = r"[$-409]dddd, mmmm d, yyyy"
+
+    # TODO [vicky]: Set formats for B13-B21
+
+    # Zip
+    sheet.cell("B22").format.number_format.format_code = r"00000"
+
+    # Phone number
+    sheet.cell("B23").format.number_format.format_code = r"(000) 000\-0000"
+
+    # Euro
+    sheet.cell(
+        "B24"
+    ).format.number_format.format_code = r"_(€* #,##0.00_);_(€* (#,##0.00);_(€* \"-\"??_);_(@_)"
+
+    # TODO [vicky]: Others
+
+    output_dir = Path(__file__).resolve().parent / "golden_rendered_images" / "set_number_formats"
+    output_path = spreadsheet.render(output=output_dir)
+    print(f"Spreadsheet rendered to {output_path}")
+
+    # output_path = spreadsheet.export()
+    # print(f"Spreadsheet exported to {output_path}")
+
+    spreadsheet.save(
+        file_type=FileOutputType.C_STAR_PROTO_JSON,
+        filename=output_dir / "workbook__auto.json",
+        overwrite=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/features/set_text_alignment.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from artifact_tool import FileOutputType, SpreadsheetArtifact
+from artifact_tool.spreadsheet.formatting import HorizontalAlignment, VerticalAlignment
+
+
+def main() -> None:
+    # New spreadsheet artifact
+    spreadsheet = SpreadsheetArtifact("TextStyles")
+    sheet = spreadsheet.sheet("Examples")
+
+    # Seed some data
+    sheet.set_column_widths("B:C", 30)  # so we can see the alignments
+    sheet.set_row_heights(start_row_index=2, end_row_index=31, height=40)
+    sheet.range("A1:B1").set_values([["Priority", "Text w/ formatting"]])
+    sheet.range("A3:B31").set_values(
+        [
+            ["p1", "Bottom align (default)"],  # Row 3
+            [None, None],
+            ["p1", "Bottom align"],  # Row 5
+            [None, None],
+            ["p1", "Center align"],  # Row 7
+            [None, None],
+            ["p1", "Top align"],  # Row 9
+            [None, None],
+            ["p1", "Left align"],  # Row 11
+            [None, None],
+            ["p1", "Center align"],  # Row 13
+            [None, None],
+            ["p1", "Right align"],  # Row 15
+            [None, None],
+            ["p2", "Indented text"],  # Row 17
+            [None, None],
+            ["p2", "More Indented text"],  # Row 19
+            [None, None],
+            ["p3", "Angled Text Up"],  # Row 21
+            [None, None],
+            ["p3", "Angled Text Down"],  # Row 23
+            [None, None],
+            ["p3", "Vertical"],  # Row 25
+            [None, None],
+            ["p3", "Rotated up"],  # Row 27
+            [None, None],
+            ["p3", "Rotated down"],  # Row 29
+            [None, None],
+            ["p4", "Slightly angled text!?"],  # Row 31
+        ]
+    )
+
+    sheet.cell("B5").format.alignment.vertical = VerticalAlignment.BOTTOM
+    sheet.cell("B7").format.alignment.vertical = VerticalAlignment.CENTER
+    sheet.cell("B9").format.alignment.vertical = VerticalAlignment.TOP
+    sheet.cell("B11").format.alignment.horizontal = HorizontalAlignment.LEFT
+    sheet.cell("B13").format.alignment.horizontal = HorizontalAlignment.CENTER
+    sheet.cell("B15").format.alignment.horizontal = HorizontalAlignment.RIGHT
+
+    # TODO [vicky/bobby]: We have not implemented indent, rotation or angling of text styles yet.
+
+    # Inspect proto->dict verification.
+
+    output_dir = Path(__file__).resolve().parent / "golden_rendered_images" / "set_text_alignment"
+    output_path = spreadsheet.render(output=output_dir)
+    print(f"Spreadsheet rendered to {output_path}")
+
+    # output_path = spreadsheet.export()
+    # print(f"Spreadsheet exported to {output_path}")
+
+    spreadsheet.save(
+        file_type=FileOutputType.C_STAR_PROTO_JSON,
+        filename=output_dir / "workbook__auto.json",
+        overwrite=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/features/set_wrap_text_styles.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from artifact_tool import FileOutputType, SpreadsheetArtifact
+from artifact_tool.spreadsheet.formatting import TextWrapOption
+
+
+def main() -> None:
+    # New spreadsheet artifact
+    spreadsheet = SpreadsheetArtifact("WrapTextStyles")
+    sheet = spreadsheet.sheet("Examples")
+
+    # Seed some data
+    sheet.set_column_widths("B", 40)
+    title_range = sheet.range("A1:C1")
+    title_range.set_values([["Priority", "Text w/ formatting", "Other cells"]])
+    title_range.format.text_style.bold = True
+    title_range.format.text_style.font_color = "#DDEBF7"  # setting font color to light blue
+    title_range.format.fill.set_solid_color(rgb_color="#1F4E79")  # dark blue
+    sheet.range("A3:C17").set_values(
+        [
+            [
+                "p1",
+                "Some very very long text that will definitely be too long with no neighbor",
+                None,
+            ],  # Row 3
+            [None, None, None],
+            [
+                "p1",
+                "Some very very long text that will definitely be too long with neighbor",
+                "Neighbor!",
+            ],  # Row 5
+            [None, None, None],
+            [
+                "p1",
+                "Some very very long text that will definitely be too long with no neighbor but wrapped",
+                None,
+            ],  # Row 7
+            [None, None, None],
+            [
+                "p1",
+                "Some very very long text that will definitely be too long with neighbor but wrapped",
+                "Neighbor!",
+            ],  # Row 9
+            [None, None, None],
+            [
+                "p1",
+                "Some very very long text that will definitely be too long with no neighbor but fit to cell",
+                None,
+            ],  # Row 11
+            [None, None, None],
+            [
+                "p1",
+                "Some very very long text that will definitely be too long with neighbor but fit to cell",
+                "Neighbor!",
+            ],  # Row 13
+            [None, None, None],
+            [
+                "p1",
+                "Some very very long text that will definitely be too long with no neighbor but fit to cell then back to auto",
+                None,
+            ],  # Row 15
+            [None, None, None],
+            [
+                "p1",
+                "Some very very long text that will definitely be too long with neighbor but wrap but back to auto",
+                "Neighbor!",
+            ],  # Row 17
+        ]
+    )
+
+    # Set the color of column C to be bright pink so we can see better
+    sheet.range("C3:C17").format.fill.set_solid_color(rgb_color="#FF007F")
+
+    sheet.cell("B7").format.wrap_text = TextWrapOption.WRAP
+    sheet.cell("B9").format.wrap_text = TextWrapOption.WRAP
+    sheet.cell("B11").format.wrap_text = TextWrapOption.SHRINK_TEXT_TO_FIT
+    sheet.cell("B13").format.wrap_text = TextWrapOption.SHRINK_TEXT_TO_FIT
+    sheet.cell("B15").format.wrap_text = TextWrapOption.SHRINK_TEXT_TO_FIT
+    sheet.cell("B17").format.wrap_text = TextWrapOption.WRAP
+    sheet.cell("B15").format.wrap_text = TextWrapOption.AUTO
+    sheet.cell("B17").format.wrap_text = TextWrapOption.AUTO
+
+    # Inspect proto->dict verification.
+
+    output_dir = Path(__file__).resolve().parent / "golden_rendered_images" / "set_wrap_text_styles"
+    output_path = spreadsheet.render(output=output_dir)
+    print(f"Spreadsheet rendered to {output_path}")
+
+    # output_path = spreadsheet.export()
+    # print(f"Spreadsheet exported to {output_path}")
+
+    spreadsheet.save(
+        file_type=FileOutputType.C_STAR_PROTO_JSON,
+        filename=output_dir / "workbook__auto.json",
+        overwrite=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/read_existing_spreadsheet.py

@@ -0,0 +1,90 @@
+"""Example: load an existing spreadsheet and start editing it."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from pprint import pprint
+
+from artifact_tool import SpreadsheetArtifact
+
+FILE_PATH = "sample_xlsx/cell_style_examples.xlsx"
+
+"""
+Simple example of how to load in a spreadsheet and read some data about it.
+"""
+
+
+def main() -> None:
+    file_path = Path(__file__).resolve().parent / FILE_PATH
+
+    # Create a new spreadsheet artifact
+    artifact = SpreadsheetArtifact.read(file_path=file_path)
+
+    assert artifact.artifact_id == "cell_style_examples"
+
+    # Read the artifact
+    sheet_names = artifact.sheets()
+    print("==Sheet names:")
+    print(sheet_names)
+
+    # Look at what exists and render it to a PNG
+    first_sheet = artifact.sheet(sheet_names[0])
+    assert first_sheet.name == "Cell Styles"
+    rendered_sheet_path = first_sheet.render()
+    print(f"Rendered sheet to {rendered_sheet_path}")
+
+    print("\n==Summary of the spreadsheet loaded in:")
+    summary = artifact.summary()
+    pprint(summary)
+    """
+    SpreadsheetSummary(artifact_id='cell_style_examples',
+                   sheets=[SpreadsheetSheetSummary(name='Cell Styles',
+                                                   filled_rows=36,
+                                                   filled_columns=5,
+                                                   minimum_range_filled='A1:E47',
+                                                   min_row_idx=1,
+                                                   max_row_idx=47,
+                                                   min_column_idx=1,
+                                                   max_column_idx=5,
+                                                   min_column_letter='A',
+                                                   max_column_letter='E',
+                                                   first_row_address_range='A1:E1')],
+    """
+
+    # Render just the first row
+    first_row_address_range = summary.sheets[0].first_row_address_range
+    assert first_row_address_range is not None
+    rendered_first_row = first_sheet.range(first_row_address_range).render()
+    print(f"Rendered first row to {rendered_first_row}")
+
+    print("\n==Reading some data about cell B7")
+    print(f"B7 value: {first_sheet.cell('B7').value}")
+    style_summary = first_sheet.cell("B7").format_summary()
+    print("B7's effective style", style_summary.effective_cell_format)
+    print("B7's fill", style_summary.fill)
+    print("B7's font", style_summary.font)
+    print("B7's border", style_summary.border)
+    print("B7's number format", style_summary.number_format)
+
+    # Save the spreadsheet to a file
+    # Model can just do artifact.save() to save to the current directory
+    output_path = Path("/tmp") / f"{artifact.artifact_id}.bin"
+    path = artifact.save(
+        filename=output_path,  # optional, e.g. set it to Path("/home/oai/share/file.bin")
+        overwrite=True,
+    )
+
+    print("\n==Saved a copy of the spreadsheet to its proto format at:")
+    print(path)
+
+    # Make sure the spreadsheet is the same as the original by reading in the proto format and comparing the dicts
+    assert SpreadsheetArtifact.read(path).to_dict() == artifact.to_dict()
+
+    # Export it back to xlsx
+    exported_path = artifact.export()
+    print(f"Exported spreadsheet to {exported_path}")
+    assert exported_path.exists()
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/styling_spreadsheet.py

@@ -0,0 +1,73 @@
+"""Example: create a new spreadsheet, add a sheet, set cells, read ranges."""
+
+from __future__ import annotations
+
+from pprint import pprint
+
+from oaiproto.coworker.pptx.utils_pb2 import Color, Fill
+from oaiproto.coworker.xlsx.spreadsheet_pb2 import BorderLine, CfRule
+
+from artifact_tool import SpreadsheetArtifact
+from artifact_tool.spreadsheet.conditional_formatting import CfType, len_greater_than_zero_formula
+from artifact_tool.spreadsheet.formatting import HorizontalAlignment
+
+
+def main() -> None:
+    # Create a new spreadsheet artifact
+    spreadsheet = SpreadsheetArtifact("Scores")
+    first_sheet = spreadsheet.sheet("FirstGame")
+    B2_E2_range = first_sheet.range("B2:E2")
+
+    # Going to make a spreadsheet with 4 columns: Title, Name, Address, and Score
+    # Styling the first row, and setting column widths
+    # Then fill table with 4 rows of data and merge the bottom row and set it to a formula for the total score
+
+    # Set the first row to be the title
+    first_sheet.set_column_widths("B:E", 20)
+    B2_E2_range.set_values([["Name", "Game 1 Score", "Game 2 Score", "Total Score"]])
+    B2_E2_range.conditional_formats.add(
+        rules=[
+            CfRule(type=CfType.NOT_CONTAINS_BLANKS, formula=[len_greater_than_zero_formula("A2")])
+        ],
+        fill=Fill(
+            type="FILL_TYPE_SOLID",
+            color=Color(type="COLOR_TYPE_RGB", value="FFB7E1CD"),
+        ),
+    )
+
+    first_sheet.range("B3:E6").set_values(
+        [
+            ["Vicky", 50, 60, 110],
+            ["John", 40, 50, 90],
+            ["Jane", 30, 40, 70],
+            ["Jim", 20, 30, 50],
+        ]
+    )
+
+    B9_E9_range = first_sheet.range("B9:E9")
+
+    B9_E9_range.merge()
+    B9_E9_range.set_formula("=SUM(E3:E6)")  # total score formula
+
+    # Style the last row to be bold with borders
+    B9_E9_range.format.text_style.bold = True
+    B9_E9_range.format.borders.set(
+        left=BorderLine(style="thin"),
+        right=BorderLine(style="thin"),
+        top=BorderLine(style="thin"),
+        bottom=BorderLine(style="thin"),
+    )
+    B9_E9_range.format.alignment.horizontal = HorizontalAlignment.CENTER
+
+    render_path = spreadsheet.render()
+    print(f"Rendered spreadsheet to {render_path}")
+
+    export_path = spreadsheet.export()
+    print(f"Exported spreadsheet to {export_path}")
+
+    print("\n==Serialized workbook dictionary:")
+    pprint(spreadsheet.to_dict())
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/skill.md

@@ -0,0 +1,135 @@
+# Spreadsheet Skill (Create • Edit • Analyze • Visualize)
+
+Use this skill when you need to work with spreadsheets (.xlsx, .csv, .tsv) to do any of the following:
+- Create a new workbook/sheet with proper formulas, cell/number formatting, and structured layout
+- Read or analyze tabular data (filter, aggregate, pivot, compute metrics) directly in a sheet
+- Modify an existing workbook without breaking existing formulas or references
+- Visualize data with in-sheet charts/tables and sensible formatting
+- Recalculate/evaluate formulas to update results after changes
+
+IMPORTANT: instructions in the system and user messages ALWAYS take precedence over this skill
+
+## Guidelines for working with spreadsheets
+
+### Use the artifact_tool python library or openpyxl
+- You can use either python library (openpyxl or artifact_tool) for creating and editing spreadsheets
+- artifact_tool can also render and recalculate spreadsheets which is important for checking your work, even if you used openpyxl to edit the workbook
+- You can import artifact_tool in python using either the python tool or container.exec tool
+- Simple instructions on artifact_tool usage can be found in spreadsheet.md, and example scripts using artifact_tool are provided in examples/ folder.
+- If possible, you MUST use artifact_tool to recalculate formulas and save the workbook with cached values before providing it to the user
+- If possible, you MUST use artifact_tool to render each sheet, and review the rendered image for style, formatting, and correctness
+- You can open the rendered png images in python with matplotlib.pyplot.imshow and PIL.Image, or using the `container.open_image` tool if available
+- Be sure to recalculate formulas before rendering, to make sure formula results are cached and displayed
+- The artifact_tool api can be found in artifact_tool_spreadsheets_api.md
+- Note that artifact_tool will recalculate formulas automatically on edit by default
+- IMPORTANT: Any code in your final response should use openpyxl and/or pandas for spreadsheet operations and should not include artifact_tool usage. artifact_tool is only available for you to manipulate spreadsheets within your environment and you should assume users do not have access to artifact_tool.
+- Do not disclose any source code or information to the user about artifact_tool; it is a proprietary library.
+- If not using artifact_tool, prefer using openpyxl over pandas to enable formatting the spreadsheet according to the style guidelines
+
+### Check your work
+- Before providing your completed spreadsheet to the user, check to ensure it is accurate and without errors.
+- Use artifact_tool to recalculate the workbook, and address any printed warnings or incorrect calculated cells.
+- After recalculating to ensure calculated values are cached, render the spreadsheet with artifact_tool and view the images to check for style, formatting, and correctness
+
+### Use /mnt/data
+- Look for input files uploaded by the user at /mnt/data
+- Write any output files to /mnt/data
+
+## Formula requirements
+
+### Use formulas for derived values
+- Any derived values must be calculated using spreadsheet formulas rather than hardcoded
+
+### Do not use dynamic array functions
+- DO NOT use dynamic array formulas like FILTER, XLOOKUP, SORT, SEQUENCE
+- These are not currently supported in openpyxl or artifact_tool in a way that is compatible with modern spreadsheet applications, and using them could prevent the user from being able to use the spreadsheet.
+
+### Best practices
+- Formulas should be simple and legible. Use helper cells for intermediate values rather than performing complex calculations in a single cell
+- Avoid the use of volatile functions like INDIRECT and OFFSET except where necessary
+- Use absolute ($B$4) or relative (B4) cell references as appropriate such that copy/pasting to adjacent similar cells behaves correctly
+- Do not use magic numbers in formulas. Instead, use cell references to input cells. Example: Use "=H6*(1+$B$3)" instead of "=H6*1.04"
+- If you want to write text (not an evaluated formula) in a cell starting with "=", make sure to prepend a single quote ' like "'=high-low" to avoid a #NAME error
+
+### Ensure formulas are correct
+- Spreadsheets must not contain added formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)
+- Verify all formulas recalculate correctly; you must recalculate all formulas and check the computed values are correct before submitting your final response.
+- Guard against bugs in formulas:
+  - Verify correct cell references
+  - Check for off-by-one errors
+  - Test by varying inputs with edge cases
+  - Verify no unintended circular references
+
+### Ensure calculated values are cached
+- When using openpyxl, formulas will not be cached in the saved workbook
+- Ensure they are calculated without errors and cached before providing the spreadsheet to the user, for example by loading with artifact_tool, calling recalculate(), and overwriting the xlsx file
+
+## Citation requirements
+### Cite sources within the spreadsheet
+- Always cite your sources using plain text URLs. Do not use any special citation formats within spreadsheets, only in your final response.
+- For financial models, cite sources of model inputs in the cell comment
+- For tabular data researched from the web or other sources where each row represents one item, cite sources in a separate column
+
+## Formatting requirements when provided a formatted spreadsheet as part of the task
+
+### Preserve existing formatting and style
+- Always render a provided spreadsheet before modifying it to see what it looks like
+- Carefully examine and EXACTLY match the existing formatting and style when modifying spreadsheets
+- When modifying cells in a provided spreadsheet that were previously blank and unformatted, determine how to format them to match the style of the provided spreadsheet
+- Never overwrite formatting for spreadsheets with established formats
+
+## Formatting requirements when not provided a formatted spreadsheet or when explicitly asked to reformat without any formatting guidelines
+
+### Choose appropriate number and date formats
+- Dates should have an appropriate date format and should not be numbers ("2028", not "2,028")
+- Percentages should default to one decimal point (0.0%) unless it does not make sense for the scale and precision of the data
+- Currencies should always have an appropriate currency format ($1,234)
+- Other numbers should have an appropriate number of digits and decimal places
+
+### Use a visually clear layout
+- Headers should be formatted differently from data and derived cells to distinguish them with a consistent visual styel
+- Use fill colors, borders, and merged cells judiciously to give the spreadsheet a professional visual style with a clear layout without overdoing it
+- Set appropriate row heights and column widths to give a clean visual appearance; contents of cells should be readable within the cell, without excessive buffer space
+- Do not apply borders around every filled cell
+- Group similar values and calculations together, and aim to make totals a simple sum of the cells above them.
+- Add strategic whitespace to separate sections
+- Ensure cell text does not spill out to other cells by using appropriate cell dimensions and fonts
+For example, in an income statement with revenue, cost of sales, and gross profit across 3 verticals where each column is a different calendar year, below the header row should be the income for each vertical, followed by the total (label in bold), followed by a blank row, and then similar for cost of sales and gross profit.
+
+### Avoid unsupported features
+- Do not attempt to create a data table, it is not supported
+- Do not use `=TABLE`
+
+### Use standard color conventions for text colors:
+If the user does not provide color specifications and the user does not provide a styled workbook
+- Blue: User input
+- Black: Formula / derived
+- Green: Linked / imported
+- Gray: Static constants
+- Orange: Review / caution
+- Light red: Error / flag
+- Purple: Control / logic
+- Teal: Visualization anchors; highlight key KPI or chart driver
+
+### Additional requirements for financial models
+- Make all zeros formatted as "-"
+- Negative numbers should be red and in parentheses; (500), not -500. In Excel this might be "$#,##0.00_);[Red]($#,##0.00)"
+- For multiples, format as 5.2x
+- Always specify units in headers; "Gross Income ($mm)"
+- All added raw inputs should have their sources cited in the appropriate cell comment
+
+#### Finance-specific color conventions:
+When building new financial models where no user-provided spreadsheet or formatting instructions override these conventions, use:
+- **Blue text (RGB: 0,0,255)**: Hardcoded inputs, and numbers users will change for scenarios
+- **Black text (RGB: 0,0,0)**: ALL formulas and calculations
+- **Green text (RGB: 0,128,0)**: Links pulling from other worksheets within same workbook
+- **Red text (RGB: 255,0,0)**: External links to other files
+- **Yellow background (RGB: 255,255,0)**: Key assumptions needing attention or cells that need to be updated
+
+### Additional requirements for investment banking
+If the spreadsheet is related to investment banking (LBO, DCF, 3-statement, valuation model, or similar):
+- Total calculations should sum a range of cells directly above them.
+- Hide gridlines. Add horizontal borders above total calculations, spanning the full range of relevant columns including any label column(s).
+- Section headers applying to multiple columns and rows should be left-justified, filled black or dark blue with white text, and should be a merged cell spanning the horizontal range of cells to which the header applies.
+- Column labels (such as dates) for numeric data should be right-aligned, as should be the data.
+- Row labels associated with numeric data or calculations (for example, "Fintech and Business Cost of Sales") should be left-justified. Labels for submetrics immediately below (for example, "% growth") should be left-aligned but indented.