iWork Studio

Safe reads and edits of Numbers, Keynote and Pages files. Every write is backed up first, applied to a scratch copy, re-read and checked, then swapped in atomically. If anything doesn't match, the user's file is left untouched and you get a typed error. Arabic/RTL text round-trips exactly.

How to work (every request)

1. Read before you write. iwork_read the file and use what's actually there (real slide numbers, cell refs, exact text to replace).
2. Confirm destructive or broad changes in one line before doing them (or show a preview: every write takes dry_run=true and returns what would change): deleting slides, pages_set_body (it resets the body's formatting), or a find/replace that hits many places.
3. Write with one tool call per change. Don't retry a failed write with a different trick; report the error (see the table below).
4. Tell the user what changed and that a backup exists. After an important change, offer iwork_verify_render (macOS) to confirm it's visibly there.
5. Mistake? Undo with iwork_list_backups → iwork_restore_backup.

What you can do

Formatting tips: inspect first; ranges are A1 or A1:D9; colours are #RRGGBB; only the attributes you pass change. Merges are refused if they'd hide data. Numbers has no scriptable table styles; Pages margins/page setup/paragraph styles and Keynote shape fill/text alignment are not exposed — say so, don't improvise.

Building a spreadsheet: numbers_create (or numbers_import_csv) → format the header with numbers_set_cell_style → numbers_set_number_format for money/% → numbers_set_dimensions → numbers_set_formula for totals (Mac). After no-app edits to a file with formulas (the result says formulas_need_recalc), run numbers_recalculate: Numbers otherwise keeps showing the old totals. New files are never overwritten. In a table with formulas, rows/columns can only be appended headlessly.

Slide numbers are 1-based. keynote_move_slide(slide, to) puts the slide at position to. keynote_add_slide(after=0) adds at the front, no after adds at the end. The last slide can't be deleted.

When a tool says no

Arabic / RTL

• Write Arabic exactly as given; it round-trips byte-exact.
• For iwork_verify_render, assert one Arabic word, not a phrase: PDF text layers reorder multi-word RTL text and the check would fail falsely.
• Numbers keeps values as typed (CSV import too): Arabic-Indic digits (١٢٣) and strings like "$1,234.56" stay text. Pass a real number (e.g. 2500) when the user wants a number.

Never

• Convert to docx/pptx/xlsx and back (lossy).
• Use AppleScript save in <path> on the user's files (the iWork sandbox denies it).
• Edit the files directly or with other tools while bypassing these routes.

Install (if the tools aren't available yet)

• Claude desktop app (Mac): curl -LsSf https://raw.githubusercontent.com/Arkanji/iwork-studio/main/install.sh | sh, then quit Claude (Cmd-Q) and reopen.
• Claude Code: claude mcp add iwork-studio -- uvx --from iwork-studio@latest iwork-studio-mcp
• Other MCP clients: uvx --from iwork-studio@latest iwork-studio-mcp config prints the JSON entry.

No Python install needed; uv brings its own.

No MCP? Use the scripts

Run from this skill's folder. Prefixing with uvx --from iwork-studio@latest needs no prior install (or use a Python 3.12 with the package installed). Output is JSON.

U="uvx --from iwork-studio@latest"
$U python scripts/read.py <file.numbers|.key|.pages>
$U python scripts/edit_numbers.py edit-cell <file> --ref B3 --value "قيمة" [--sheet NAME] [--table NAME]
$U python scripts/edit_key.py replace <file.key> "old text" "new text" [--regex]
$U python scripts/edit_pages.py preflight
$U python scripts/edit_pages.py replace-all <file.pages> "old" "new"
$U python scripts/edit_pages.py set-body <file.pages> "new body"      # or '-' for stdin
$U python scripts/verify_render.py <file> --assert-text "word"

Slide ops and undo from Python (the MCP tools wrap exactly these):

from iwork_studio import keynote_slides as ks, backups
ks.set_presenter_notes("deck.key", 1, "ملاحظات")
ks.duplicate_slide("deck.key", 2); ks.move_slide("deck.key", 3, 1)
ks.add_slide("deck.key", after=0); ks.set_skipped("deck.key", 4, True); ks.delete_slide("deck.key", 5)
backups.restore_backup("deck.key", backups.list_backups("deck.key")[0]["name"])

References

• references/design-guide.md — how to make decks and tables look designed (read before building a deck)
• references/capability-matrix.md — what each route supports and refuses
• references/jxa-traps.md — scripting traps, if you are extending this
• references/sandbox-trap.md, references/keynote-1700-defect.md, references/tcc-preflight.md — background on specific macOS/iWork behaviour