iWork Studio

What this machine can do right now: routes, GUI session, installed apps, Keynote slide-op status. Call first when unsure. Call first when unsure what this machine can do: which apps exist, whether a GUI session is available, which toolsets are loaded. Not needed before plain reads of .numbers or .key files.

New .numbers / .key / .pages from Apple's built-in templates (Keynote: themes); names from iwork_list_templates. Omit template for Blank / Basic White. Refuses to overwrite. Needs macOS + the app. Use for a new, empty file from Apple's templates. Instead: iwork_create_from_template to copy the user's own file, numbers_create to make a Numbers file from data, keynote_build_deck for a finished deck from an outline.

Start a new document from one of the user's own files (any .numbers / .key / .pages): copies it to `path` and checks it opens. Refuses to overwrite. Use when the user has their own template or past file to start from. For Apple's built-in templates use iwork_create.

Delete a saved design kit (presets can't be deleted). Returns the kit's contents, so it can be saved again with iwork_save_design_kit. Use only when the user asks to remove a saved kit. To change a kit, save it again with overwrite=true instead.

Export to another format. Numbers: pdf | xlsx | csv. Pages: pdf | docx | epub | txt | rtf. Keynote: pdf | pptx | images | movie. Optional password (+hint) for pdf/xlsx/docx/pptx, image_quality (good|better|best), image_format for slide images (jpeg|png|tiff). Default output sits next to the source. The export is checked against the source with a second tool and the source is verified unchanged. Needs macOS + the app. Use to hand the result over in another format (PDF, Excel, Word, PowerPoint, images). Never export to docx/pptx/xlsx to edit and convert back: edit the iWork file directly.

Make a design kit from the user's own deck or table: heading and body fonts (Latin and Arabic) and the title, body and brand colours. .numbers reads the table's header and body styles (no app); .key reads every slide's title and body (needs macOS + Keynote). Parts the file doesn't show come from the nearest preset and are listed in notes. save=true with a name keeps it for reuse by name (contrast must pass). The file is never changed. Use when the user has a deck or table that already has their brand look. If they give colours and fonts directly use iwork_save_design_kit instead.

Find Numbers / Keynote / Pages files (newest first). kind: numbers | keynote | pages; name: part of the file name. Searches `folder`, else the allowed folders, else Documents/Desktop/Downloads. Uses Spotlight on macOS. Use when the user names a file loosely ("my sales deck") or you don't know its path; then read it with iwork_read. Not needed when you already have the path.

List the versioned backups (newest first) every write left for this file, plus the Keynote write manifest. Use when the user wants to undo or compare versions: it lists the backups, then iwork_restore_backup restores one. Not needed after a failed tool call: failed writes never change the file.

Design kits for good-looking decks and tables: font pairs (Latin + Arabic, bundled with macOS), contrast-checked palettes and a type scale. Lists the presets and the kits you saved (saved: true). Use with keynote_build_deck(kit=…), keynote_apply_design, numbers_apply_design. Custom kits: pass {"fonts": {...}, "colors": {...}}. Use before any styling to pick a kit, and to see the user's saved brand kits. Pass the name as kit= to keynote_build_deck, keynote_apply_design or numbers_apply_design.

Built-in templates for Numbers or Pages, or themes for Keynote (app: numbers | pages | keynote). Needs macOS + the app. Use before iwork_create to get valid template or theme names. Not needed for iwork_create_from_template, which copies the user's own file.

What a file says about itself, without the app: kind, size, modified, template it was made from, app builds that saved it, file format version, slide count (Keynote), embedded media count. Use for file facts (template, app build, slide count) without reading content. For the content itself use iwork_read.

Read a .numbers, .key or .pages file into JSON (.pages needs the Pages app and a GUI session). Use to see a file's content before editing it. Not for formatting details: use numbers_inspect_format (Numbers) or keynote_inspect_style (Keynote). For file facts only, iwork_metadata is cheaper.

Undo: atomically restore a backup (a name from iwork_list_backups). The current version is backed up first. Use to undo a change, with a backup name from iwork_list_backups. The current version is backed up first, so a restore can itself be undone.

Copy sample files (sample-sales.numbers with English and Arabic sheets of synthetic sales data, and sample-outline.md for a deck) into a folder, so a first try needs none of the user's own files. Never overwrites. Returns try-it prompts. Use when the user wants to try iWork Studio but has no file handy, or asks for an example; then follow one of the returned try_it prompts. Not for the user's own files.

Save a design kit by name for reuse anywhere a kit is accepted. kit = {"fonts": {...}, "colors": {...}, "theme": "...", "background": "#RRGGBB"} (missing parts come from the "executive" preset, or from "base": "<preset>"), or a preset name to copy. Contrast is checked (4.5:1). Never replaces a saved kit unless overwrite=true; can't reuse a preset's name. Use when the user gives brand colours and fonts directly. To capture them from an existing file use iwork_extract_design_kit.

Extract the preview image stored in the file (first page/slide) to a JPEG and return its path — a quick look without opening the app. Reflects the app's last save. Use for a quick look at the stored first-page preview with no app. It reflects the last save in the app, not your latest edits: to see a slide as it renders now, use keynote_slide_image.

Independent check of formatting: export a PDF through the app and confirm `text` is drawn with the given font (name contains), size (pt), color (#RRGGBB), bold, and page size (pt). Needs macOS + the app. Use to prove how a piece of text is drawn (font, size, colour, page size). To check text is merely present use iwork_verify_render.

Export the file to PDF through its app and assert `assert_text` is visibly rendered. For Arabic, use one word. Use after an important write to prove the text really shows when rendered. To check font, size or colour use iwork_verify_format; to check a deck's whole design use keynote_review_deck.

Add a chart to a slide from data. rows = series names, columns = category names, data = one list of numbers per row (rows × columns). type: bar | stacked_bar | horizontal_bar | stacked_horizontal_bar | line | area | stacked_area | pie | scatter (or *_3d). group_by: row | column. Text and other charts are verified untouched. dry_run=true previews the change on a copy without touching the file. Use for a chart on an existing slide. In a new deck, put the chart in keynote_build_deck's outline instead; for exact numbers use keynote_add_table.

Place an image file (png, jpg, heic, pdf…) on a slide; optional x/y position and width in points. All text verified untouched. dry_run=true previews the change on a copy without touching the file. Use to place a picture or logo on a slide. For data, use keynote_add_chart or keynote_add_table rather than a picture of a chart.

Insert a slide after slide number `after` (0 = first, omit = end). Every other slide is verified unchanged. dry_run=true previews the change on a copy without touching the file. Use for a new blank slide in an existing deck. To copy a slide use keynote_duplicate_slide; for a whole new deck use keynote_build_deck.

Add a table to a slide (1-based). rows = [["Region", "Q1"], ["Riyadh", 1200], …]: text, numbers, or null; text starting with "=" is a formula. kit (iwork_list_design_kits name or your own) styles it: header band, fonts (Arabic-aware), banding, numbers right-aligned. Optional x, y (points from top-left) and width. Every cell, font and colour is read back; other slides and tables are checked untouched. At most 50 rows × 15 columns. dry_run=true previews the change on a copy without touching the file. Needs macOS + Keynote. Use for a table on an existing slide. In a new deck, put it in keynote_build_deck's outline; to show a trend use keynote_add_chart.

Make a deck look designed: the kit's theme (optional), then every slide's title and body fonts (Arabic-aware), sizes from a type scale, and colours from a contrast-checked palette. kit = a name from iwork_list_design_kits or your own {"fonts": {...}, "colors": {...}}. Text is verified unchanged. dry_run=true previews the change on a copy without touching the file. Use to restyle a whole deck from a kit. For one text item use keynote_format_text. Preview with dry_run, then run keynote_review_deck.

Build a new Keynote deck from an outline. slides = [{"title": "…", "body": ["bullet", "bullet"], "layout": "Title & Bullets", "notes": "…", "image": "/path/pic.png"}, …]; the first slide defaults to a title layout, the rest to Title & Bullets. theme from keynote_list_themes; optional transition for every slide (e.g. dissolve). Every slide is read back and checked; on any mismatch the new file is removed. Never overwrites. kit = a design kit (iwork_list_design_kits) for a designed deck in one call. Chart slides: add "chart": {"type": "bar", "rows": ["2025", "2026"], "columns": ["Q1", "Q2"], "data": [[1, 2], [3, 4]]} or {"type": "line", "from": "/path/report.numbers", "columns": ["Q1", "Q2"]} (header row → column names, first column → row names); chart slides default to Title Only. Table slides: "table": {"rows": [["Region", "Q1"], ["Riyadh", 1200]]} or {"from": "/path/report.numbers", "columns": ["Q1"], "max_rows": 8}; with a kit the table is styled too. Needs macOS + Keynote. Use for a new deck from an outline, including chart and table slides; then run keynote_review_deck. To change an existing deck use the slide and text tools instead.

Delete slide number `slide` (1-based). Recoverable with iwork_restore_backup. dry_run=true previews the change on a copy without touching the file. Use to remove a slide for good (the last slide can't be deleted). To keep it but hide it in the slideshow use keynote_skip_slide.

Duplicate slide number `slide` (1-based); the copy lands right after it. dry_run=true previews the change on a copy without touching the file. Use to copy an existing slide (layout and content). For a blank slide use keynote_add_slide.

Font (PostScript name, e.g. "HelveticaNeue-Bold"), size (pt) and/or colour ("#RRGGBB") of one text item on a slide — pick it by item index (from keynote_inspect_style) or by a unique piece of its text (match). Alignment and shape fill are not scriptable. dry_run=true previews the change on a copy without touching the file. Use for one text item's font, size or colour. To restyle the whole deck consistently use keynote_apply_design.

A deck's styling: current theme, available slide layouts, and per slide its layout plus each text item's text, font, size and colour. Read this before theming. Use before formatting: theme, layouts, and each text item's font, size and colour. For slide text and notes use keynote_list_slides.

Every slide with its text, presenter notes and whether it is hidden (via Keynote). Use slide numbers from here for slide operations. Use before slide operations to see slide numbers, text, notes and hidden state. For fonts and layouts use keynote_inspect_style.

Themes available in Keynote on this Mac (names to pass to keynote_set_theme). Use before keynote_set_theme or keynote_build_deck to get valid theme names.

Move slide number `slide` so it ends up at position `to` (both 1-based). dry_run=true previews the change on a copy without touching the file. Use to reorder slides. To copy a slide to a new position, duplicate it first with keynote_duplicate_slide.

Find/replace text across every slide of a .key deck (literal unless regex=true). Formatting and structure are verified unchanged. dry_run=true previews the change on a copy without touching the file. Use to change the same text everywhere in a deck (names, dates, numbers). To rewrite one slide's title or body use keynote_set_slide_text.

Design review of a deck as Keynote actually draws it: renders to PDF and reports, per slide, text drawn off the slide or past the bottom of its box (errors), text boxes drawn on top of each other, text under 18 pt, and slides that are too dense (warnings). Run it after building or restyling a deck, fix the errors, then look at a flagged slide with keynote_slide_image. The file isn't changed. Needs macOS + Keynote. Use after building or restyling a deck, before saying it's done; fix every error. To look at a flagged slide use keynote_slide_image; to check one word renders use iwork_verify_render.

Set the presenter notes of slide number `slide` (1-based). Arabic-safe. dry_run=true previews the change on a copy without touching the file. Use for speaker notes on an existing slide. For a new deck, put notes in keynote_build_deck's outline instead.

Change one slide's layout (master), e.g. "Title & Bullets". Other slides are verified untouched. dry_run=true previews the change on a copy without touching the file. Use to change one slide's layout (names from keynote_inspect_style). Not for text styling: use keynote_format_text.

Fill a slide's title and/or body box (body may be a list of bullet lines). The title box is the top-most text box, the body the largest other one. Other slides and text boxes are verified untouched. dry_run=true previews the change on a copy without touching the file. Use to fill or rewrite one slide's title and body. To change the same words across the deck use keynote_replace_text; for speaker notes use keynote_set_presenter_notes.

Apply a different Keynote theme to the whole deck. Rolled back if any slide loses text. dry_run=true previews the change on a copy without touching the file. Use to switch the deck's theme only. For a full designed look (fonts, sizes, colours) use keynote_apply_design, which can set the theme too.

Transition into a slide: effect such as dissolve, push, wipe, magic move, cube, flip, move in, reveal, "none"; duration/delay in seconds; automatic=true advances on its own. Other slides verified untouched. dry_run=true previews the change on a copy without touching the file. Use for one slide's transition. For the same transition on every slide of a new deck, pass transition= to keynote_build_deck.

Hide (skipped=true) or show a slide in the slideshow. dry_run=true previews the change on a copy without touching the file. Use to hide or show a slide in the slideshow without deleting it. To remove it use keynote_delete_slide.

One slide as an image (JPEG, `width` px wide), exported by Keynote, so you can look at the design yourself. Skipped slides aren't exported. The file isn't changed. Needs macOS + Keynote. Use to look at a slide's real rendering, e.g. one keynote_review_deck flagged. For a quick preview without Keynote use iwork_thumbnail (first slide, last saved state).

Present: action = start (needs path; from_slide 1-based) | stop | next | previous. Doesn't change the file. Needs macOS + Keynote. Use to present the deck live; it doesn't change the file. To share it instead use iwork_export.

Add a table with data to an existing sheet (`sheet`, default the first) or to a new sheet (`new_sheet`). Every existing table is verified unchanged. dry_run=true previews the change on a copy without touching the file. Use for a new, separate table on a sheet or a new sheet. To grow an existing table use numbers_insert.

Style a whole table from a design kit: header band (fill, bold, contrast-checked text), body font and colour (Arabic cells get the Arabic font), alternate-row banding, number columns right-aligned. Values never change; every other table is verified untouched. No app needed. dry_run=true previews the change on a copy without touching the file. Use to make a whole table look designed in one call (header band, fonts, banding, aligned numbers). For a few cells use numbers_set_cell_style. Preview with dry_run.

Create a new .numbers file from data. sheets = [{"name": "Sales", "tables": [{"name": "Q1", "rows": [["Region", "Revenue"], ["Riyadh", 1200]], "header_rows": 1}]}]. Numbers stay numbers, text stays text exactly (Arabic included). Refuses to overwrite. No app needed. Use to make a new Numbers file when you have the rows. From a CSV file use numbers_import_csv; to add a table to an existing file use numbers_add_table.

Delete `count` rows or columns (what = rows | columns) starting at 1-based position `at`. Remaining cells are verified. Refused in tables with formulas or merged cells. Undo with iwork_restore_backup. dry_run=true previews the change on a copy without touching the file. Use to remove rows or columns. Not for clearing values (use numbers_edit_cell with null). Refused in tables with formulas or merges; undo with iwork_restore_backup.

Set one cell (e.g. ref "B2") in a .numbers file. Backed up, verified, atomic; every other cell is checked unchanged. dry_run=true previews the change on a copy without touching the file. Use to set one value. For a formula use numbers_set_formula; to add whole rows use numbers_insert with values; for how a number displays use numbers_set_number_format.

Turn a CSV/TSV into a new .numbers file (UTF-8, delimiter auto-detected). Plain numbers become numbers (numbers=false keeps everything as text); dates, "$1,234" and Arabic-Indic digits stay text exactly as written. Refuses to overwrite. Use when the data is in a CSV/TSV file. When you already have the rows use numbers_create.

Insert rows or columns (what = rows | columns) before 1-based position `at`; omit `at` to append. Optional `values`: one list per new row (or column). Every existing cell is verified at its new position. In tables with formulas, only appending is allowed (shifting would break references). dry_run=true previews the change on a copy without touching the file. Use to add rows or columns to an existing table (optionally filled). For a separate table use numbers_add_table. In tables with formulas only appending works; do mid-table inserts in Numbers.

Current formatting of a Numbers table: column widths, row heights, header rows/cols, merges, and per-cell font/colour/fill/alignment, number format (shown_as) and borders. Read this before formatting. Use before formatting to see current styles, number formats, sizes, headers and merges. For values use iwork_read.

Merge a rectangular range ("A1:C1"). Refused if any cell other than the top-left holds data (it would be hidden) or the range crosses the header edge. dry_run=true previews the change on a copy without touching the file. Use to merge a range, e.g. a title across columns. Refused if it would hide values; avoid merging inside data you will sort.