onionskin-cli 0.0.0-stage → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/CHANGELOG.md +144 -0
  2. package/INSTALL.md +25 -0
  3. package/LICENSE +21 -0
  4. package/NOTICE +49 -0
  5. package/README.md +148 -2
  6. package/docs/contracts/batch.schema.json +839 -0
  7. package/docs/contracts/history.schema.json +126 -0
  8. package/docs/contracts/ops.schema.json +541 -0
  9. package/package.json +67 -4
  10. package/scripts/checker/check.py +411 -0
  11. package/scripts/checker/requirements.txt +5 -0
  12. package/scripts/install-check.mjs +9 -0
  13. package/scripts/requirements.txt +5 -0
  14. package/scripts/rewriter/apple/main.swift +135 -0
  15. package/scripts/rewriter/apple/onionskin-fm +0 -0
  16. package/scripts/rewriter/apple/onionskin-fm.json +6 -0
  17. package/skills/onionskin/SKILL.md +117 -0
  18. package/skills/onionskin/reference/batch.md +94 -0
  19. package/skills/onionskin/reference/formats.md +15 -0
  20. package/skills/onionskin/reference/ops.md +253 -0
  21. package/skills/onionskin/reference/troubleshooting.md +73 -0
  22. package/skills/onionskin/reference/voice-guide.md +86 -0
  23. package/skills/onionskin/voice.example.md +51 -0
  24. package/src/agent-detect.js +149 -0
  25. package/src/agent-events.js +159 -0
  26. package/src/agent-prompt.js +27 -0
  27. package/src/agent-runner.js +593 -0
  28. package/src/analyze.js +17 -0
  29. package/src/anchors.js +190 -0
  30. package/src/apply.js +387 -0
  31. package/src/auth.js +130 -0
  32. package/src/batch.js +322 -0
  33. package/src/check-worker.js +8 -0
  34. package/src/checker.js +293 -0
  35. package/src/cli.js +516 -0
  36. package/src/constants.js +20 -0
  37. package/src/diff.js +267 -0
  38. package/src/doctor.js +288 -0
  39. package/src/docx.js +438 -0
  40. package/src/fmt.js +30 -0
  41. package/src/fsutil.js +348 -0
  42. package/src/history-worker.js +16 -0
  43. package/src/history.js +576 -0
  44. package/src/lease.js +79 -0
  45. package/src/local.js +242 -0
  46. package/src/merge-pptx.js +198 -0
  47. package/src/merge-xlsx.js +453 -0
  48. package/src/merge.js +410 -0
  49. package/src/offload.js +34 -0
  50. package/src/ops/common.js +48 -0
  51. package/src/ops/docx-table.js +323 -0
  52. package/src/ops/docx.js +503 -0
  53. package/src/ops/engine.js +41 -0
  54. package/src/ops/pptx.js +336 -0
  55. package/src/ops/run.js +115 -0
  56. package/src/ops/runs.js +127 -0
  57. package/src/ops/schema.js +109 -0
  58. package/src/ops/xlsx.js +277 -0
  59. package/src/package.js +189 -0
  60. package/src/paths.js +64 -0
  61. package/src/person.js +66 -0
  62. package/src/pptx.js +194 -0
  63. package/src/question.js +47 -0
  64. package/src/quick-plan.js +107 -0
  65. package/src/quick.js +164 -0
  66. package/src/redline-check.js +251 -0
  67. package/src/redline-worker.js +29 -0
  68. package/src/redline.js +438 -0
  69. package/src/reply.js +410 -0
  70. package/src/review.js +274 -0
  71. package/src/rewrite-check.js +1014 -0
  72. package/src/rewriter-cleanup.js +105 -0
  73. package/src/rewriter-setup.js +104 -0
  74. package/src/rewriter.js +396 -0
  75. package/src/sanitize.js +42 -0
  76. package/src/sentence-span.js +25 -0
  77. package/src/server-entry.js +13 -0
  78. package/src/server.js +576 -0
  79. package/src/session.js +1912 -0
  80. package/src/settings.js +161 -0
  81. package/src/setup.js +199 -0
  82. package/src/stamp-words.js +10 -0
  83. package/src/stamps.js +59 -0
  84. package/src/style.js +110 -0
  85. package/src/suggest-reply.js +84 -0
  86. package/src/suggest.js +261 -0
  87. package/src/text.js +31 -0
  88. package/src/tracked-words.js +43 -0
  89. package/src/voice-guide.js +182 -0
  90. package/src/voice-learn.js +314 -0
  91. package/src/voice-sample-worker.js +95 -0
  92. package/src/voice-samples.js +329 -0
  93. package/src/voice-store.js +305 -0
  94. package/src/voice-worker.js +28 -0
  95. package/src/voice.js +297 -0
  96. package/src/xlsx.js +454 -0
  97. package/src/xml-tree.js +118 -0
  98. package/src/xml.js +127 -0
  99. package/src/zip-write.js +74 -0
  100. package/src/zip.js +88 -0
  101. package/vendor/engine/DocViewer-BZLXUcxJ.js +15137 -0
  102. package/vendor/engine/THIRD_PARTY_LICENSES.txt +79 -0
  103. package/vendor/engine/collab-BVynXMqc.js +2591 -0
  104. package/vendor/engine/collab.js +2 -0
  105. package/vendor/engine/core.js +4 -0
  106. package/vendor/engine/default-worker-DogNT09A.js +35625 -0
  107. package/vendor/engine/embed.js +107 -0
  108. package/vendor/engine/index.js +5 -0
  109. package/vendor/engine/office-engine.embed.js +184 -0
  110. package/vendor/engine/office-engine.worker.js +36030 -0
  111. package/vendor/engine/xlsx-ops-SYAv6V0f.js +939 -0
  112. package/vendor/engine-node/LICENSE +21 -0
  113. package/vendor/engine-node/engine-node.mjs +46618 -0
  114. package/vendor/engine.lock.json +26 -0
  115. package/web/dist/assets/index-BUtofdtr.js +197 -0
  116. package/web/dist/assets/index-Dfizlg0i.css +1 -0
  117. package/web/dist/index.html +14 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,144 @@
1
+ # Changelog
2
+
3
+ ## 0.0.2 (2026-11-14)
4
+
5
+ ### Added
6
+ - Line breaks in an Excel cell: while typing in a cell, Shift+Enter or Alt+Enter starts a new line inside the cell. Tried for real: the saved file had the line breaks 0.6 s after Send. In a narrow column the first line of a tall cell can be clipped until the column is widened.
7
+ - What the agent can now do for you, in plain words: add or delete a table row or column in Word; copy, delete or move a slide in PowerPoint; decline a chart in plain words (it says to insert the chart in Word or PowerPoint); understand Excel merged cells (it is told which cells are merged, and a write into a covered cell is refused). A run that only followed the overall note says so ("Changed the file as your note asked") instead of "No change needed", and a copied or deleted slide shows one plain note in the panel.
8
+ - Ops for Word table rows and columns and for PowerPoint slides, so the background agent (and any agent) adds a row or a slide without a script: `insert_table_row`, `delete_table_row`, `insert_table_column`, `delete_table_column` by `{table, row}` or `{table, col}` (the numbers of a cell's `body_path`), with the new cells' text in `cells` and the neighbor's formatting; `duplicate_slide` (the way to add a slide: the copy's text is set in the same op), `delete_slide` and `move_slide` by `slide_id`. Each has `expect` like every op. What they cannot do without damage is refused with a code: merged cells a row or column would split, the last row, column or slide, protected content or half a comment in what a delete removes, a slide with a chart or another shared part (duplicate), a slide another slide links to (delete), decks with sections or custom shows. Nothing creates or changes a chart. A deleted slide's parts are reported as `slide_removed`, a warning instead of the lost-part error, so a requested delete does not recommend Revert (a `commit` that drops a slide now gets the same warning instead of the error). Real background-agent runs of the new `scripts/real-run` scenarios `docx-table-row` and `pptx-duplicate-slide` applied them, and LibreOffice converts the results; they have not been opened in Word or PowerPoint yet.
9
+ - The background agent: Onionskin starts, restricts, supervises and stops a headless Claude Code agent per document (`src/agent-runner.js`, `src/agent-detect.js`, `src/agent-prompt.js`), so a person who never opened an agent still gets their Send answered. It starts when a file is opened from a person's terminal, when a Send finds nobody listening (at once for such a file, after a 20 s grace for any other, so an agent of your own between two polls keeps the batch), or from the page (`POST /api/agent {action: start|stop|use|show|terminal}`, the editing tab only, a 1 KB body of fixed values). Claude Code only in this build, model sonnet by default. Least privilege, proven on Claude Code 2.1.323 with one real probe of the rule forms and real full rounds on the prompt-injection fixture (open, Send through the real server, reply by file, the change shown, Close; state folder under the home folder like `~/.onionskin`): `--restricted --tools Bash,Read,Write`, it changes the document only through Onionskin's own commands (`onionskin poll|reply|status` are the shell commands granted by name), it may write only inside its own work folder (`Edit(//<folder>/**)`), it may read files inside its own work folder and the skill's reference folder (`--add-dir`) and run read-only commands, and a probe with canary files showed that reading outside those two folders, reading the home folder, network fetches and writes elsewhere were all refused, `--permission-mode dontAsk --permission-prompts none`, no settings files, MCP servers or slash commands of the person's own setup, and an environment built from nothing (no `ANTHROPIC_API_KEY` or any other key, so it always uses the person's subscription). The agent answers by writing the reply JSON to a new file per batch and running `onionskin reply --lease <ticket> --then-poll --file <that file>`; `reply` refuses `--json`, stdin and any file but `<that folder>/reply-<batch id>.json` for the background holder and for its Terminal form (`onionskin-term-`, bound to its own file the same way), and its JSON errors there never quote the input. Such an agent cannot open the file, so every edit batch it receives, complete or compact, also carries the document's outline as quoted evidence (`untrusted_document_evidence.outline`: each paragraph, text shape or cell as it is at that delivery, with the `target` and `expect` an op copies; as much as fits one shell output inline; when that is not all of it, the complete outline, up to 2,000 units, in a file of one unit per line in the agent's own outline folder, which it reads with the Read tool and which is the only part of its work folder it may read; `outline_more` counts what it cannot see), so a note with no comment or selection, such as "change the title", is done; every other holder's batch is unchanged. Each agent is its own process group with a record of its pid and start time; it is signaled only while `ps` still shows that start time, and a server that starts stops the groups a crashed one left. It stops on Close session, server stop, 20 minutes without a tab, or when an agent of your own polls the file (that agent supersedes it, and a background poll never takes a file back). A crash hands the batch back at once (the page unlocks, a run that wrote keeps Revert) and restarts with backoff 2 to 32 s, resuming the conversation, at most 5 starts per document an hour; signed out, a usage limit or a refused command never restarts by itself. At most 3 agents run at once. Its own polls do not keep the server alive, and its `poll` never starts or restarts a server (a stopped server ends it with `closed`); a poll that outlives its agent process is answered `closed`, so a Send never waits on nobody. "Open in Terminal" opens the same conversation in Terminal with the same limits (tried in a real Terminal: the file changed 17.7 s after Send). Its stream is kept as a private transcript (0600) in the state folder and removed, with Claude Code's own copy, when the session is closed (also after a server restart). The holder prefix `onionskin-bg-` is reserved (400 `reserved_holder` for any other file). Tests never start an agent unless they opt in (`ONIONSKIN_AGENT_PATH`); `ONIONSKIN_AGENT_CLI=none` turns it off. `scripts/real-run/bg-real.mjs` is the opt-in real test (`ONIONSKIN_REAL_AGENT=1`; `--fake <dir>` rehearses it for free). On the page: when nobody is listening, the banner has a Start the agent button in place of the `onionskin poll` command line; an agent that is starting, stopped (not installed, not signed in, plan limit reached, crashed, kept stopping, refused a command) or open in Terminal each shows a plain banner with its buttons (Try again, Restart the agent, Send again, Show what happened, Open Terminal to sign in, which opens a Terminal running `claude auth login`; an outdated Claude Code says to update it; a fourth document's agent says another document's agent is busy); a Background agent block in the review panel has a Show the agent switch with a live list of what it is doing (fixed plain lines built from the agent's stream by `src/agent-events.js`, never document text) and Open in Terminal; `agent` settings (`cli`, `model`, `show`) in `settings.json`. Claude Code is the only background agent in this build.
10
+ - Start from a plain terminal: `onionskin report.docx` (a Word, Excel or PowerPoint file as the first argument) is `onionskin open report.docx`. A person at a terminal (stdin and stdout are terminals, and no `CLAUDECODE`, `CODEX_THREAD_ID`, `CODEX_TOOL_CALL_ID`, `CODEX_CI` or `CODEX_SANDBOX` in the environment) gets plain words instead of the agent's poll instructions: the file is open in the browser, and one line says "Claude Code is starting in the background to work on this file with you. Press Send in the page when you are ready." (the background agent below; without Claude Code it says where to get it and to press Try again in the page). There is no question any more, and the terminal stays the person's. `onionskin poll` typed by a person prints two plain lines and exits 2 instead of a batch. `--agent` forces the agent output, `--no-agent` opens the page only. Agents and scripts get the same bytes as before. The "no agent is listening" banner shows a Start the agent button. On a Mac with Codex but no Claude Code, the terminal says so in plain words and tells the person to ask Codex ("open report.docx in Onionskin").
11
+ - Voice guide as a file: `skills/onionskin/voice.md` (ignored by git, never copied to an installed skill folder, left out of a `--public` zip) is read like a `.env` and used as the voice guide until one is saved from the page; `skills/onionskin/voice.example.md` is the checked-in sample. `ONIONSKIN_VOICE_FILE` names another file.
12
+ - `onionskin stop` removes a leftover socket file that nothing answers on (only in its own state folder, never one something listens on or a live server record or start lock points to), so `onionskin doctor` reads the server as "not running" afterwards instead of advising a stop that changed nothing.
13
+ - Build my voice guide: in Writing preferences, a Voice guide block ("Voice guide: none", "saved, sent with every request", "draft ready to review") with Build my voice guide, Open guide and Review draft. The request window asks which writing the agent may read (this file if it is your own, up to 5 Word, PowerPoint or text files or pasted text, your changes to the agent's text, your comments) and says plainly that your agent's AI service reads it. Once an agent has taken the request, the page says "The agent is writing your voice guide."; until then it says "Sent to your agent." (or "Your request is waiting for an agent." after a reload); you keep typing, and it is kept. The draft opens in a window with one plain text box per section, a counter, a status against your saved guide (Same as saved, Changed, New) and Show changes; a changed section can be used only after all of its text has been on screen, top to bottom (a tall section has to be scrolled through), and Save is after the last section; Save asks first when a section you typed in is not ticked, since Save leaves it out. "Load a voice guide" keeps your "Short form only" choice when the text still has an "In short" section. You choose to send the full guide or the short form only; Save as voice.md writes a guide in sections as top-level sections, In short first. The page part of the server work below: `POST /api/voice/build` sends the agent a request to draft a guide to how you write, from only the samples you tick or add (this file's saved version, up to 5 Word, PowerPoint or text files or pasted texts, your rewrites of the agent's text, the comments you typed), sampled on this Mac with what an agent wrote left out and the whole request kept under 28,000 characters. The agent changes nothing in the file (an `apply` or `commit` is refused) and answers with `reply` and `voice_draft`; the skill's new `reference/voice-guide.md` holds the twelve-section template and the rules for an observable, ranked, evidence-backed guide. The draft is checked strictly (refused, never cut, for hidden characters, links or markup, the wrong layout, more than two blank lines in a row or a section over its cap) and kept as a draft for your review (`GET /api/voice` shows it; `POST /api/voice/draft/discard {at}` removes it, only when it is still the draft that was on screen); nothing goes into your saved guide until you save it. The saved guide can be 7,000 characters, can be sent as its "In short" section only (`send: "short"`), and is put back (and the run flagged) when something outside Onionskin changes it. Up to 30 of your rewrites of the agent's text are kept instead of 10. The first agent rule now says `instructions` holds what you typed, tapped or approved on screen.
14
+ - Quick fixes: select one sentence in a Word or PowerPoint file, tap Fix grammar in the Quick ask box, and (once the writing helper is set up) a card shows the sentence as it is, with removed words struck through, and the suggestion, with added words underlined, up to two "Check:" lines for things to look at, and two buttons: "Use this" and "Ask the agent instead". Esc closes the card and writes nothing. "Use this" changes only the changed words, on this Mac, as a run with the same checks and Revert as any other (the History row says "Change made on this Mac"; Revert says "Reverted to the version before this change." and the row "Reverted change made on this Mac", since no agent was involved). A selection that is a whole sentence except its end mark, closing quote or bracket, or has spaces at its edges, counts as that sentence: the suggestion is for the whole sentence and "Use this" writes it with its end mark (the server reads the paragraph itself). A tap that does not qualify (any other stamp, Shorter and Friendlier included, more than one sentence, part of a sentence, a table, a spreadsheet, the helper not set up, an agent working) does exactly what it did before, and when the selection is certainly not one sentence the stamp row says "Select one whole sentence to get a suggestion first." while the pointer is on a stamp that can suggest (today Fix grammar). In PowerPoint the page cannot always tell, so a tap on part of a sentence that the server refuses shows the same line on a card with "Ask the agent instead", and nothing is sent by itself. The overall note stays in its box after "Use this" and goes with the next Send. While quick fixes are on, the stamp row's hint names the stamps that show a suggestion first (today Fix grammar: "Fix grammar shows a suggestion first on one sentence. Other taps go to the agent with your other changes."). Until quick fixes are turned on, the stamp row shows a one-time offer: "Get quick fixes for one sentence, made by Apple's writing model on this Mac. Nothing you write leaves it." with "Turn on" and "No thanks"; one tap on "Turn on" turns them on (nothing is downloaded) and the line becomes "Quick fixes are on. Select one sentence and tap Fix grammar." Where Apple's model cannot answer (macOS older than 26, a Mac that cannot run it, Apple Intelligence off, the model still getting ready, a missing helper) the offer is replaced by the plain reason with "No thanks" as the only button ("Try again" too while the model is getting ready), and Fix grammar goes to the agent as before. The card says "Made on this Mac by Apple's writing model. Nothing changes until you tap Use this."; when Apple's model declines a sentence it shows "No suggestion for this sentence." and a change inside quoted text shows "No suggestion here: the change is inside quoted text."; while a first answer is slow the card says "Getting the writing helper ready." A comment whose change could not be made on this Mac says so on its card. The server side: `POST /api/suggest` asks the small model on this Mac for a rewrite of one selected sentence (Fix grammar by default, in a Word paragraph or a PowerPoint text box) and answers with both sentences, their difference and any warnings. Asking writes nothing and changes nothing in the session: the suggestion is kept in the server's memory only, at most 3 per file for 10 minutes. `POST /api/suggest/use` names it by id and writes it on this Mac as an ordinary local run (the page's unsent edits first, then one find and replace of only the changed words inside that paragraph or text box, with the same lease, checks, history entry and Revert as any run); the text written is the stored one, never text the page sends back. A run that cannot write puts the comment back to draft with the line "This could not be changed on this Mac, so nothing was written. Press Send to ask the agent." `POST /api/suggest/warm` starts a cold model, `GET|POST /api/setup-rewriter` is the one-button setup (Apple's built-in model), and the bootstrap says whether quick fixes are on. The check behind it: `checkRewrite(task, before, after, {mode: "suggest"})` decides whether a one-sentence rewrite by the small model on this Mac may be shown as a suggestion (shown, shown with warnings for the person to check, withheld, or unchanged), and `inputQualifies` refuses a sentence that reads like instructions for an AI before the model is asked. Spelling fixes such as "untill" to "until", "atleast" to "at least" and "wich" to "which" now pass in this mode; strict mode is unchanged. `scripts/rewriter-eval/traps.json` holds 67 hand-written rewrites it must withhold, warn or (6 apostrophe, outside-the-quotes and inch-mark fixes) still show. `src/stamp-words.js` is the server's one copy of the built-in stamps' words.
15
+ - Quick fixes, measured: `scripts/rewriter-eval/run.mjs --check suggest` runs the model through the relaxed check and counts clean, warned, withheld and unchanged suggestions per task, the opening phrases and the median length of the shown ones; `scripts/rewriter-eval/judge.mjs` lists the shown suggestions for a person to mark good or bad (results go to a folder outside the repo). The evaluation set has 20 more held-out sentences (30 in all, 5 of them bad news). Shorter and Friendlier were re-tuned for the small model and measured once on the 30 held-out sentences: both missed their quality bars, so by the owner's decision (2026-11-12, "only use them for what they're best at") only Fix grammar asks the small model first; Shorter and Friendlier go to the agent as they did before quick fixes. The safety check is the same for every task. The page learns the list from the server (`suggest.tasks` in the bootstrap), any list is honored, and a later change will widen it per measured capability. Wording: the one-time offer says "Get spelling and grammar fixes on this Mac in under a second, before asking the agent." and `onionskin doctor` says "on (...): spelling and grammar fixes on one sentence".
16
+ - The agent reviews first, the server part: `POST /api/review` with one of three fixed requests (proofread, read like a skeptical finance chief, check every number) sends the agent a batch with that fixed sentence and a read-only outline of the file (at most 300 paragraphs, slide text boxes or cells). The agent changes nothing and answers with `reply` and `suggest`; each suggestion becomes a card: one find-and-replace inside one Word paragraph or one slide text box, or a note (spreadsheets get notes only). `done` checks every card against the file and drops what fails (unknown or protected place, text that changed, words that are not found exactly once, too long, more than one line, a link, a bare web address such as evil.example or an email address, more than 20). `POST /api/suggestion` takes only card ids and Accept or Reject: Accept makes the change on this Mac through the same checks, lease and Revert as an agent's run; a card whose text changed in the meantime is marked and nothing is written. An `apply` or `commit` during a review is refused. In the page: a "Review first" row in the composer with the three buttons (Proofread, Read like a skeptical CFO, Check every number), and under "Suggested by the agent" one card per suggestion: Was and Now with Accept and Reject for an edit, the agent's concern with Show me (outlines the place, nothing else moves) and Dismiss for a note, Accept all and Reject all. The agent's words are drawn as plain text. The buttons are off while a batch waits or when you have unsent edits.
17
+ - Quick changes with no AI: type "Replace Acme with Initech" (or "Make every heading bold") as the overall note and the line under the box says how many places it will change; the Send button then reads "Replace in 12 places" (or "Change 9 headings") and Onionskin does it itself on this Mac in a moment. The number on the button is the number the run must find again, or nothing is written and the agent gets the note as usual. A match inside a longer word, or inside a spreadsheet formula, is left to the agent, and so is a note with comments or typed edits beside it, or one sent while an earlier Send still waits for the agent (comments the agent already finished do not count). "Ask the agent instead" sends it the ordinary way. A Revert of a quick change puts the note back and the next Send goes to the agent. New route `POST /api/quick`.
18
+
19
+ ### Changed
20
+ - Install options: besides pasting the sentence into Claude Code or Codex, you can install from Terminal, from npm, as a Claude Code plugin, as a Codex plugin, or from a zip.
21
+ - `onionskin doctor` names the copy that is running and lists any other copies it finds.
22
+ - The Try it demo line no longer shows a timing figure.
23
+ - A calmer, more solid look: the bars, the review panel, menus and dialogs are near-opaque grey panes with a fine border, a thin line of light along the top and a soft shadow, with no blur. Blue is kept for Send, status, focus and the marks on the page; links and comment numbers in the panel are black (white in dark), and the default Paper background is grey. Every text still passes WCAG AA in both themes.
24
+ - The engine is office-engine v0.13.2 plus our own additions. The owner's typing fix was merged upstream and is part of v0.13.2 (https://github.com/p10node/office-engine/pull/2).
25
+ - A Send that carried only your own edits now ends with the summary "Your edits are saved. Nothing else needed changing." It said "No change needed", which read as if your edits were not kept.
26
+ - Install is one sentence: paste "Install Onionskin from https://github.com/abe238/onionskin" into Claude Code or Codex. The README has a marked block for the agent doing the install, `AGENTS.md` (and a `CLAUDE.md` pointer to it) carries the same steps, and `scripts/get.sh` ends by saying what was installed and the one sentence to tell the person. `ONIONSKIN_BASE_URL` changes the folder `get.sh` downloads from.
27
+ - The README is a short public page; install options, the command list, the feature tour, limits and the full install and troubleshooting notes moved to `docs/DEVELOPERS.md` and `docs/GUIDE.md`, and `INSTALL.md` is a short page. The skill's description now also matches phrases such as "open report.docx in Onionskin".
28
+ - Quick fixes feel faster: when the Quick ask box opens on one sentence and quick fixes are on, the page asks for the Fix grammar suggestion right away and holds it, so the card is there when you tap Fix grammar. Nothing shows before the tap. The answer is the same request a tap makes (Apple's model on this Mac only, the same checks), held only for that exact sentence, place and file version, used once, and dropped when the box closes; the page's asks run one at a time and a closed box's waiting ask is dropped, so a tap in the same page never meets "busy" because of it (a head start in another tab or file still can, for about a second: the model takes one sentence at a time for the whole server). With quick fixes off or not available nothing is asked. Measured on the real model in a real browser: Apple's model takes about 0.85 s per sentence, so a tap about 1 s after the box opens finds the card ready (in milliseconds; 3 ms in one run on one Mac), and the first fix of a session or an immediate tap waits about 0.3 to 0.4 s. An earlier build's measurement (one run of 6 sentences each, medians of taps 2 to 6) read 0.08 s for a tap 1 s after the box opened and 1.02 s for a tap as soon as the test could click, against 1.35 s and 1.59 s before the head start; those figures are superseded by the current ones above. `scripts/rewriter-eval/grammar/latency.mjs` times the helper itself (cold, after a warm-up, and 30 sentences of the benchmark set); the helper is unchanged: answering on a prewarmed session was about 200 ms faster but changed 2 answers of 30, and the other prewarm variants kept the answers but were no faster or slower.
29
+ - Quick fixes use Apple's built-in model only, by the owner's decision after a benchmark on 160 unseen sentences (Apple with a re-tuned prompt: a good fix shown for 72 of 96 errors with today's checks, 70 when the decision was made; 4 of 64 correct sentences wrongly changed, 3 of them shown; the other helper tried, an IBM model that had to be downloaded, 68 of 96 and 11 of 64). Nothing is downloaded and nothing is compiled on your Mac: the helper (`scripts/rewriter/apple/onionskin-fm`, about 109 KB, Apple silicon, macOS 26 or later) is built by `scripts/build-apple-helper.mjs` when the zip is made, with its SHA-256 in `onionskin-fm.json` and `MANIFEST.txt`, and runs from the app folder. Its Fix grammar prompt is the tuned one from the benchmark (`scripts/rewriter-eval/grammar/fm/prompts/r3-plain.json`: a proofreader's instructions, 12 examples, 160 response tokens); it offers no other task. `install.sh` removes macOS's download mark from that one file and says so ("quick fixes: removed macOS's download mark from one file, if it had one: the small helper that talks to Apple's on-device model, so macOS does not stop it"), and Onionskin never starts the helper while the mark is still there. On a Mac where Apple's model cannot answer, Fix grammar goes to the agent, and `onionskin doctor` and the bootstrap's `suggest.unavailable` field say why: "Quick fixes need macOS 26 or later.", "This Mac cannot run Apple's on-device writing model.", "Turn on Apple Intelligence in System Settings to get quick spelling and grammar fixes.", "Apple's writing model is still getting ready. Try again in a few minutes.", or that macOS is holding back the helper or that it is missing or damaged. A refusal by the model is told apart from a failure (`{state: "failed", why: "refused"}`). The download of the other helper is gone: its model list, Python libraries and worker are no longer in the app (the benchmark's own copy is lab tooling under `scripts/rewriter-eval/mlx-lab/`, not in the zip). The first `install.sh` or `onionskin setup-rewriter` of this version removes what the older download left in `~/.onionskin` (the model folder, the helper's Python environment and the settings file that named it; only those known folders, only inside that folder, links never followed) and says so: "Removed the old writing helper download (1.3 GB). Quick fixes now use Apple's model already on this Mac." (the size is what was freed); `install.sh` prints "Removed the old writing helper download (1.3 GB). Quick fixes are off until you run: onionskin setup-rewriter" instead when the old settings file was removed (that file is what had them on); a cleanup that frees under 1 MB says "Removed the old writing helper settings." in place of the download part. `setup-rewriter --model` anything but apple answers: "There is no \"<name>\" writing helper any more. Quick fixes use Apple's built-in model, so run setup-rewriter without --model." `setup-rewriter --remove` now says "quick fixes are off".
30
+ - Quick fixes never change quoted text: the server withholds a suggestion that changes words inside quotation marks (straight or curly, double, or single when they are clearly quotes and not apostrophes), or drops the marks, with the line "No suggestion here: the change is inside quoted text." (`quoted_text_changed`, suggest mode only; strict mode is unchanged). An inch mark such as 2" or a stray quotation mark never shifts the pairing: curly marks pair by direction, a mark right after a digit is read both as an inch mark and as a quotation mark and every quoted span either reading finds must be unchanged, an odd number of straight marks that are not inch marks makes every stretch between them count as quoted, and a quotation mark that is never closed quotes the rest of the sentence (so a quote that really ends on a number, followed by a fix, is withheld too). "its" and "it's", "company's" and "don't" are still fixed.
31
+ - Writing preferences: the button that cleared them is now "Clear preferences" (it clears the preference buttons and your own words, never a saved voice guide), and the Voice guide block has its own "Remove guide" button next to Open guide. It asks "Remove your voice guide? This cannot be undone." with Remove and Cancel.
32
+ - Voice guide: the agent's instructions are stricter about padding. "I avoid" lists only words the rewrites or requests show the person cutting or replacing (each with its evidence), otherwise it says "Not enough in what I was given to say."; lines written only to contrast a default AI voice are marked "(written for contrast)" and limited to two per section; a habit that comes from a file whose style differs from the pasted writing is labeled with its situation instead of being merged into the general rules. The server's checks are unchanged.
33
+ - Quick fixes: Friendlier's instructions to the writing helper were re-tuned (warmer plain words, never more formal, no thanks, apology or feeling the sentence did not have). On the 30 held-out sentences, in one run, it showed 28 suggestions (22 without a Check line, 6 with one, 2 withheld, counted again with the final check). The builder's own, lenient reading called 20 of the 28 good, against 13 of 27 before, and no one else has marked them. 12 of the 28 still open with a heads-up phrase, so the opener is not fixed. Two checks written after that run use held-out sentences as examples, so the held-out numbers are not a clean test. Shorter's instructions are unchanged (three tries were no better). The new Check line for an added feeling, thanks or apology no longer fires on a spelling fix or a shorter form of a phrase the sentence already had.
34
+ - Quick fixes: the check of a suggestion now warns when the rewrite opens with a feeling, thanks, apology or opinion the sentence did not have ("Check: \"We appreciate the thought, but\" was added.", from a small fixed list of openers), and Friendlier shows nothing when its only change is a formal opener such as "Kindly" or "Please be advised that" ("No friendlier version this time."). The hands-off rewrite's check is unchanged.
35
+ - Milestone 2 contract: the batch format may carry `instructions.review` and a read-only outline (`untrusted_document_evidence.units`, `units_more`), and history has a `local` kind ("Change made on this Mac").
36
+ - The server protocol is 5 (the last build had 2) and covers question cards (`POST /api/answer`, the `asked` result), the milestone 2 routes (`/api/quick`, `/api/review`, `/api/suggestion`) and the `local` history kind, merging edits in every format (`POST /api/merge` with `edits`, `ops` on `/cli/agent-write`), `POST /api/export-tracked` and Build my voice guide (`POST /api/voice/build`, `POST /api/voice/draft/discard`, `voice_draft` in `done`), so a server left running by an older build is replaced on the next command.
37
+
38
+ ### Fixed
39
+ - Closing a session releases its editing tab, so a file you reopen is editable.
40
+ - The closed message names the file.
41
+ - The Ask and Comment chip no longer sits on the line of text above the selection: it goes beside the end of the selected words, else below them, else above, whichever covers the least text, and stays inside the page.
42
+ - `onionskin <command> --help` (and `-h`) prints that command's own usage for every command, and runs nothing. `setup-rewriter --help` used to answer "unknown option --help".
43
+ - A finished run whose comment you deleted lists that line as "A comment you deleted" (it said "A deleted comment"), with the status and the agent's note beside it.
44
+ - The line "Select one whole sentence to get a suggestion first." no longer shows for words in a table cell (Word or PowerPoint) or a protected shape, where no selection can ever get a suggestion. The tap still goes to the agent.
45
+ - The Ask and Comment chip now shows when you select again the sentence you just sent from Quick ask (it could stay away until you selected something else first, for example right after Take back).
46
+ - Quick ask: a plain click in the document, outside the box and outside the words it asks about, closes the box and keeps any typed words as an unsent comment. The caret stays where you clicked and nothing scrolls. A click on the asked words, in the box, on the panel or on a toolbar control leaves it open.
47
+ - Selecting a whole paragraph by triple-click, or by dragging past its end, now shows the Ask and Comment chip on the last paragraph of a page (the browser ended the selection on the page's footer and the editor reported no selection).
48
+ - Comment and Pin modes: a double or triple click makes one comment or pin, not one per click.
49
+ - Quick ask: Esc closes the open card, then the box, with the focus anywhere in the document (it only worked inside the box); it leaves your place where it is, keeps any typed words as an unsent comment, and does nothing while a dialog or text composition is using Esc. Selecting other words while the box is open closes it and keeps what was typed as an unsent comment, the same as when its words scroll out of view. A page the editor redraws for a moment no longer closes the box.
50
+ - After Use this, the caret is back in the rewritten sentence's paragraph, so typing goes there and the formatting bar shows that paragraph's style. Before, when the file's reload arrived in the moment between the box closing and the focus coming back, the caret stayed where the reloaded editor puts its own, at the top of the file: the bar showed the title's style and typed text went into the title. When the reload came before the answer to Use this, the caret was moved off the pages and typed text was lost.
51
+ - History's Show button and the "changes below" pill could go to the wrong paragraph of a Word file with a page or section break above a changed paragraph longer than about 150 characters. The page now finds such paragraphs by their opening words again.
52
+ - Safari: closing a dialog or popover now returns the focus to the button that opened it (Safari does not focus a button when it is clicked). F6 into the document puts a caret there when the browser gave none, so Ctrl+Alt+M has something to comment on. The background picture is stored without the EXIF and Photoshop blocks that Safari's JPEG encoder adds. Tests: `npm run test:webkit` runs the browser tests on Playwright WebKit.
53
+ - Typing after scrolling away from the cursor in a Word document now goes where the cursor is. Before, clicking in a paragraph, scrolling far away and typing could put the text at the very top of the document (in the title) and jump the view there. The editor had stopped following the cursor after it re-attached its listeners, so the page holding the cursor was dropped while scrolling. The view now comes back to the cursor, as in Word. (On a Mac the End key scrolls to the end of the document; typing after it is the same case.)
54
+ - A refresh no longer depends on one event arriving once. Every state the page receives carries the file's version and its runs: a page that missed the refresh after an agent run or a revert (its event stream was down at that moment) catches up from the next state. A reload or a merge that cannot reach the server is tried again (after 1, 2, 4, 8 seconds, then every 15, eight times, and at once when the browser is back online) and its message goes away when it works. Unsent typing is merged as usual in a Word file and never reloaded away in a spreadsheet or a presentation. A file changed outside Onionskin is not part of this: it keeps its own message and the copy made at Send.
55
+ - A page whose event stream was closed for good opens a new one (after its error, when the browser is back online, when the tab is looked at again) and gives up after eight tries, instead of staying on "Agent working" forever.
56
+ - `onionskin apply`: a paragraph style set by `set_paragraph_style` was silently dropped when a later op of the same file edited that paragraph or inserted a paragraph next to it (both ops were reported as applied). The style now stays.
57
+ - A custom background picture is no longer hidden while a banner shows (an agent listening or working, a second tab opened read-only). The legibility guard read the banner's color-mix() fill as its first color (dark and opaque), concluded that even the plain tone failed and held the picture at 0. Colors are now resolved by the browser before the guard reads them.
58
+ - Tests: two browser test files run at the same time failed in the background and XLSX suites. The layout-shift test counted a shift from loading the page (the toolbar's empty style and font boxes, recorded only when a busy machine paints a frame mid-load) and now counts only shifts while switching; a failed background test no longer leaves its tab open (which made every later tab read-only); the XLSX Revert test, which once still counted 34 changed regions right after the revert entry showed (not reproduced since), now waits up to 10 seconds for them to clear and prints the lag when it is long.
59
+ - Tests: the helpers that type at the end of a paragraph pressed End, which on a Mac scrolls to the end of the document. Under load the typing lost the race with that scroll and a merge test failed in about half of the full runs. They now use the end-of-line key of the platform.
60
+
61
+ ### Added
62
+ - Runs on this Mac, the shared part (quick changes are the first request that uses it): a whole Send that Onionskin can do itself goes to a runner inside the server instead of the agent, through the same reply, apply and done checks, lease, snapshot and Revert. The page says "Doing this on your Mac" while it runs and titles the run "Done on this Mac"; History calls it "Change made on this Mac". When it cannot finish before writing anything, the Send goes to the agent unchanged. Undoing such a run says "Undone. Press Send to ask the agent instead." and the next Send goes to the agent. Quick changes and quick fixes use it.
63
+ - Quick changes, the engine part (the page's quick changes above use it): `src/quick.js` recognizes the small closed set of typed requests that need no AI ("Replace X with Y", and bold / italicize / underline the headings, DOCX only) and refuses everything else, so it goes to the agent. `previewAll` in `src/ops/run.js` counts the places a document-wide op would touch without changing anything; for a replace it also reports matches that sit inside a longer word (`partial_words`), matches in protected places (`protected`) and, in a spreadsheet, matches inside formulas (`in_formulas`). A wrong-count result of `replace_all_text` and `format_all` now carries the same fields.
64
+ - Changes shown in place (Word files). After an agent run the page still refreshes underneath and puts you back where you were; when it is back at exactly the same place, the agent's new words are written in where they stand (left to right, one line at a time), a small "Was:" chip shows the old words struck through, and the new words keep a green tint that fades. It shows only for an agent run that stands with no warning (no error flag, no change from outside Onionskin), for paragraphs in view whose text on the page is exactly the agent's version and found exactly once, and never after a merge of what you typed during the run (in any format), on a tab that may not edit, or when the History details come late. With reduced motion nothing moves: the new words and the "Was:" chip show still for two seconds. Typing, scrolling, a Send or a new refresh stops it at once. Everything else keeps the fading "changed" outline. Nothing is typed into the document: it is drawn over it, and screen readers hear "The agent's changes are in. 3 places changed." Spreadsheets and presentations keep the outline.
65
+ - Quick fixes, the model half: Apple's built-in on-device model, through a small helper that ships ready-made in the zip (see Changed). `onionskin setup-rewriter` turns it on and `--remove` turns it off; `install.sh --rewriter` does the same and is off unless asked; a failure never fails the install. Setup finishes with a real test sentence and writes its settings last, so a half setup reads as off. The model stays loaded for 15 idle minutes, answers one sentence at a time, and runs with no network (a minimal environment and `sandbox-exec` with the network denied). `onionskin doctor` shows "quick fixes". The first request after a stop loads the model in the background and goes to the agent.
66
+ - The strict safety check for rewrites by the small model on this Mac (not switched on; quick fixes use its relaxed mode): a rewrite of one sentence is used only when every number (written in any script: ½, 10⁶, 500, ٥٠٠ and Ⅻ count), range ("pages 3-5" is not "pages 3 and 5"), date, name, code ("xK9pQ", case included), link (case included), negation, "may"/"will"-type word and "have to" of the original is still there, a statement stays a statement and a question stays a question, and nothing that changes who acts, what it covers ("just", "also"), when ("currently") or how it sounds was added. Anything it cannot prove safe goes to the agent as today. It cannot see a change of meaning that keeps every word, such as two names swapped, or a "." made into "!".
67
+ - Shield badge. When your AI reports that it ignored orders written inside the file, its run shows a small shield chip ("3 ignored", or "More than 5 ignored") that stays visible when the run is folded, and the open run explains it in plain words. It says what the AI reported, never that the file is safe, never shows the file's words, and never appears for zero. The count is once per run and comes from the AI's own report, so the real number may be different. The skill asks the agent to list each separate piece of such text as its own string. The server now counts only real strings and counts a repeat that differs only in capital letters once.
68
+ - Demo recorder (for the Try-it page, not shipped to users): `scripts/demo/record.mjs` turns one real `demo-docx` run into `web/demo/recording/{v0.docx, v1.docx, recording.json}`, built field by field from an allow-list, and `scripts/demo/scan.mjs` refuses a recording with any other field, a path, user name, token, web address, words that are not the scenario's or the letter's, or any character outside plain text (soft hyphens, look-alike letters, Unicode slashes); a v0 that is not the generated letter part for part; a v1 whose body changes anything but the words inside the letter's runs; and a document with external links, fields, embedded files or any byte outside its parts (an archive comment, extra fields, gaps, trailing bytes). A run answered by the stand-in agent is refused unless `--test`, which stamps `real: false`, and the scan refuses that stamp. Unit tests in `test/demo-record.test.js`.
69
+ - Try-it page (a local folder for the owner to show, not shipped to users and not published): `node scripts/demo/build.mjs` builds `web/demo` into `dist-demo/` from the recording, and `node scripts/demo/serve.mjs` shows it on this Mac. A visitor adds the three prepared comments, presses Send, watches the recorded agent's changes appear in the letter (new words tinted, the summary, notes and changed words in the panel), then Revert and Start over. No AI runs and nothing leaves the page: the letter's two versions and the recording are bundled into the page, which checks each version's SHA-256 before it shows anything, follows the system's light or dark setting, runs the editor read-only, stops any dropped or pasted file and never reads its own address. The build runs the scan on the exact bytes it bundles and refuses a recording that fails it or was made with the stand-in agent (unless `--test`, which may never build into `dist-demo/`). `node scripts/demo/test-recording.mjs <folder>` makes such a test recording. Tests: `test/demo.test.js`, and the opt-in browser test `node scripts/run-tests.mjs demo`. The Try-it page replays one real recorded agent session (`web/demo/recording/recording.json` is stamped `real: true`); `scripts/real-run/README.md` describes how a recording is made.
70
+ - A "What changed" button in the History header builds a short plain-text note of everything that changed in the file since its oldest stored version (a change that was undone does not appear): up to 10 places with the words before and after, in a box you can copy and paste into an email. Nothing is sent anywhere and no agent is involved (`GET /api/history/all`, read-only).
71
+ - Stamps. In the Quick ask box (select words, press Ask) a row of stamps sends a common request in one tap: Shorter, Friendlier, Fix grammar and Translate (pick a language next). A stamp is an ordinary comment with fixed words, sent with your other changes. "Edit stamps" adds up to 8 stamps of your own (a name and what it asks for), kept on this Mac across restarts. Done keeps your changes the same as Save. The box stays inside the page and scrolls when it is tall. Stamps are not shown on a phone, where Quick ask is off.
72
+ - The agent can ask instead of declining. When a comment has two to four clear readings, the agent replies with a short question and options (`{"comment":"c1","ask":"...","options":[...]}`), and the comment's card shows "The agent asks", the question, one button per option and "Something else". A tap sends your answer and the agent carries on; the card then reads "You answered: ...". "Something else" turns the comment back into a draft you can reword. Only the number of the option you tapped goes into the agent's instructions; the question text travels as untrusted data. The server checks every question (length, two to four different options, no links, three per run, one per comment) and turns a bad one into a declined comment with a plain note. New route `POST /api/answer`; `done` accepts the status `asked`; `reply` prints `asked`.
73
+ - Writing preferences. Under Overall instructions the review panel shows "Writing preferences" with a Change button: six fixed choices (Keep it short, Plain words, More formal, More relaxed, Change as little as possible, Leave formatting alone) and a box for your own words (280 characters). They go to the agent with every request as `instructions.style_note` and are kept on this Mac (`style.json` in the state folder). After a Revert the panel offers the choices you have not turned on, once per page load. A choice is on only when you tap it or type it: nothing from the document or the agent's answers turns one on. If `style.json` is changed by anything else while Onionskin runs, Onionskin puts back what you saved, and the agent's run says "Your writing preferences were changed outside Onionskin, so they were put back." `GET`/`POST /api/style`.
74
+ - Learning from your edits (stage 1, code only), with its panel. In Writing preferences, "Suggested from your edits" shows what Onionskin noticed ("You shortened the agent's text in 4 of your last 5 edits.") with Turn on, Not now and Don't suggest this; every sentence is written by the page from a fixed id and two numbers, never from document or agent text. "Learn from my edits" switches learning off and "Forget my edits" empties what was kept. "Save as voice.md" writes your preferences, own words and guide as a file for other AI tools; up to 3 before/after examples can be added, none ticked by default, each shown in full first. "Load a voice guide" takes pasted text or a .md or .txt file into an editable box and stores nothing until Save guide (1,500 characters at most, refused when longer). The two new preferences, Short sentences and No exclamation marks, are in the list. How it works: at Send, when you changed the agent's text in a Word document right after its run, Onionskin compares the three stored versions in a worker and keeps, on this Mac only, five yes/no signals per edited paragraph (shorter, shorter sentences, exclamation marks taken out, your old wording put back, formatting undone) and the preference ids that fixed English phrases in your own typed comments point at ("shorter", "more formal" and so on; a tapped stamp does not count). It never keeps a comment's words or a file name. `GET /api/voice` turns that into at most three suggestions, each a preference id and numbers, plus a few before/after examples for a later export. A suggestion becomes a preference only when you answer it (`POST /api/voice/answer {trait, action}`: on, later or never; no text is accepted). `POST /api/voice/guide` stores your own voice guide (at most 7,000 characters, refused when longer, never cut), sent as `instructions.voice_guide` when switched on; `/api/voice/forget` and `/api/voice/learning` empty the kept edits and turn learning off. All of it is browser-only (not on the CLI socket). Spreadsheets, presentations and other languages are not learned from.
75
+ - Save a copy with tracked changes (Word files). In History, an agent run's card has a "Save a copy with tracked changes" button: it writes `<name> (tracked changes YYYY-MM-DD HHMM).docx` next to the file, where every change of that run is a Word tracked change by "Onionskin agent" that can be accepted or rejected in Word. Your file stays as it is. A replaced word, a table cell edit, a paragraph added or removed in the middle of the document and a moved paragraph (removed in one place, added in the other) are marked. Formatting-only changes are kept in the copy but not marked, and the result says how many. Nothing is saved when a change cannot be marked (a header or footnote, a paragraph added or removed at the very end or next to a table, a table's rows or columns, a paragraph with a picture, link or field, a file that already has tracked changes), when someone changed the file outside Onionskin, or when the copy fails Onionskin's check: Accept All must give the agent's version and Reject All the earlier text, checked in code, and again in Python and LibreOffice when the deeper checks are set up. A folder that cannot be written offers a download instead. The What changed box has the same button for every change History holds (`"all"` on `POST /api/export-tracked`), with the hint "Covers every change listed here."
76
+ - The review panel is one stack in the order things happened: your edits, comments and pins and each agent run, oldest at the top, newest right above Overall instructions, with an empty slot under the newest card where the next one lands. Nothing changes place when the agent finishes or skips it. A comment answered in an earlier run and an earlier run fold to one line and open on a click; the agent's answer shows on the comment it answers and is no longer repeated in the run. The run that can be reverted keeps a Revert button on its folded line, so undoing it is always one click. History is a folded row at the top. The panel follows each new card, so the newest is always in view. The stack is checked on Word, Excel and PowerPoint files and at phone size.
77
+ - Deeper checks are set up by default. `install.sh` downloads the five checker libraries from PyPI once (about a minute, into `~/.onionskin/venv`, the system Python is left alone) and skips quickly when they are already there; `--no-checker` skips it, `--dry-run` only prints it. A failure (no Python 3, no internet) never fails the install: one plain line says Onionskin works without deeper checks and the detail goes to `~/.onionskin/setup-checker.log`.
78
+ - The review panel no longer shows the technical "Deeper check skipped" sentence. When the deeper check is not set up, the newest run says "Basic checks passed. Deeper checks are off." with a "Turn on deeper checks" button (`POST /api/setup-checker`, one setup at a time, progress by `GET /api/setup-checker`); the next agent run uses it with no restart. Failures say "no internet" or "Python 3 was not found on this Mac" with a Try again button. The technical sentence, and LibreOffice, are under a collapsed Details. `checks.deep.code` gives the reason as a stable code for pages and agents.
79
+ - The agent skill tells the agent to explain the deeper-check message in a sentence or two and to run `onionskin setup-checker` itself, never to hand the user a command.
80
+ - The "changed" and "new" tags on a DOCX page sit in the page margin beside the paragraph, so they no longer cover the line above. On a page too narrow for that they stay above the paragraph.
81
+ - A refresh keeps you where you are. After an agent run, a merge, a revert or a reload of an outside change, the page restores the position you are at now (read from the document just before it is replaced). Before, it restored the position saved at Send, and went to the top when that place could not be found.
82
+ - No document is locked while the agent works. Keep working: when the run ends, the server merges your version with the agent's through the same checked edit path the agent uses (`POST /api/merge`), and the page refreshes once with both. What both you and the agent changed keeps the agent's version; yours is shown in a banner with a Copy button, never dropped. If a second batch is already with the agent, your edits wait in the page and merge when it finishes.
83
+ - Word (`src/merge.js`), by paragraph. New lines, split paragraphs and deleted paragraphs are carried over. So is formatting you change without changing the text: bold, italic, underline, strikethrough, color, size, font, highlight and superscript or subscript inside a paragraph the agent left alone, and a paragraph's style (heading level), alignment and bullet or numbered list. On a paragraph the agent rewrote, the style, alignment and list are still set on its text and the formatting inside it is reported. A paragraph you move (cut and paste) is moved in the agent's version when the agent left it alone and the paragraph next to its new place is still there. It is the agent's paragraph that moves, as it is: in this editor a pasted paragraph loses its heading style, alignment and list, and the merged file keeps them. Formatting you change on a paragraph you also moved is not carried over, and the banner says so: it names what you changed inside the paragraph when that is certain (a word made bold), and otherwise asks you to check the paragraph's formatting, which it does after every cut and paste, because a pasted copy and one you restyled before cutting read the same. The banner lists, with the reason, what was not carried over: the agent changed the same thing, the paragraph is protected or was changed, moved or removed by the agent, a move in or out of a table, a moved paragraph that ends a section or holds one end of a comment or bookmark, and kinds of formatting that cannot be set (character styles, theme colors, spacing, indent). Every carried formatting change and move is checked on the merged file before it is written; if one did not come out as planned, the merge is done again without them and says so.
84
+ - Excel (`src/merge-xlsx.js`), by cell: values, cells you filled and cells you emptied. A formula you typed comes back to you whenever the agent changed any cell, which is almost every run. Your edits on a sheet are carried over only when Onionskin knows every cell is still at its address: the agent did not touch that sheet, or it changed the file only through Onionskin's own checked edits and none of them added, removed or moved rows or columns or renamed the sheet. Every other case hands your edits on that sheet back to you, listed in the banner, with your version of the file saved next to the original: the agent added or removed rows or columns there, the agent changed the file with another tool (a copy edited with openpyxl and submitted with `commit`, or a direct save), or Onionskin has no record of the run (after a restart). A value in the wrong cell would be worse than a value handed back, so even then a value of yours is carried only on a row the agent left exactly as it was: if the agent changed any cell in that row, your value is handed back, because the agent may have rewritten its rows so they now hold other content (as when it rebuilds a table one row lower by setting cells instead of inserting a row). This means that when the agent fills in a whole column, what you typed on those rows comes back to you instead of being merged. Nothing is placed by guessing from the cells; when the cells look as if rows moved, or a value's row no longer reads like the same row (as after a sort), that only ever hands edits back. The server keeps, for each agent write, how it was made, and checks a recorded set of edits against the file before it relies on it. Formatting, row and column sizes and sheet changes are reported as not carried over. A cell still being typed when the agent finishes counts.
85
+ - PowerPoint (`src/merge-pptx.js`), by text box, matched by slide and shape id, so your text still lands when the agent added, removed or reordered slides. Slides and shapes you added, removed or moved, table text, formatting and shape positions are reported as not carried over.
86
+ - When the banner stands for more than it can show (a whole sheet, a slide or shape you added, more than five items in any format), your version of the file is saved next to the original first and the banner names it. If that copy cannot be saved, nothing is merged and your edits stay in the page.
87
+ - Nothing is written unless the result is the agent's file plus exactly what was carried over.
88
+ - `onionskin stop` prints "stopped" only once the server process is gone (it waits up to 5 seconds); before, the server lived on for a moment after the command returned.
89
+ - A Send while a batch is delivered queues only what is new (a comment, a pin or a note): it no longer queues an empty batch, and text typed during a run is not counted as something to send.
90
+ - `install.sh` stops a server that is still running before it replaces the app, so an upgrade never leaves old code in memory. Open sessions are kept and the server starts again on the next command.
91
+ - Background LibreOffice checks run one at a time for the whole server (first in, first out, at most 8 waiting), so a burst of `done` calls no longer starts one LibreOffice each. A check that never gets its turn is recorded as not run, with the reason.
92
+ - `onionskin reply` needs no file argument (the ticket names the session), `--then-poll` waits 590 seconds by default, and `note` and `summary` are optional: a missing note becomes a plain line built from the reply, a missing summary a count.
93
+ - `onionskin stop` answers every waiting poll with `closed` before the server exits; before, a waiting poll saw a lost connection and started the server again. A server left running by an older build is replaced on the next command.
94
+ - Benchmarks: `scripts/real-run/bench-loop.mjs` (scripted agent, per stage), `bench-real.mjs` (real agent, cold and warm rounds), `gate-real.mjs` (real agent on the five correctness and safety scenarios), and an opt-in command trace (`ONIONSKIN_TRACE=<file>`).
95
+ - `onionskin reply <file> --lease <ticket>`: answers a whole batch in ONE call (apply plus done). Replies name comment ids and use shorthands (`find`+`replace`, `text`, `set`, full `ops`, `decline`); the command fills each target and `expect` hash from the session's batch, runs the same apply and done code (lease ticket, protected checks, atomic or `--partial`), and prints compact JSON only. `--then-poll` waits for the next batch and prints it as a second line. Each batch comment now carries `reply_with`.
96
+ - Compact batches: the first batch an agent receives in a session is complete; later ones to the same agent print only the instructions, the evidence, the two safety rules, the lease and the `reply` command. `poll --full` returns the complete form.
97
+ - `session.stage` (`delivered`, `writing`, `checking`, or null) in the session the page receives, set by the server as the agent's poll, apply or commit, and done checks arrive.
98
+ - The agent skill is rewritten around a short fast path (open, poll, one `reply --then-poll` per batch); the longer routes and per-format notes moved below it and into `reference/`.
99
+ - Fast loop in the page: Quick ask (select text or put the caret in a paragraph, cell or shape, press Cmd+Shift+K or Ctrl+Shift+K, type, Cmd+Enter or Ctrl+Enter: the comment is made and the batch sent in one step; Enter is a new line in every box, Cmd/Ctrl+Enter sends from every box; Cmd/Ctrl+K stays the engine's link shortcut; if its words scroll out of view the box closes, and anything typed in it stays as an unsent comment on those words); keyboard flow in the review panel (a new comment has the focus, Esc returns to the document at its place, Alt+Down and Alt+Up, or Cmd+Option on a Mac, move between comment boxes, Cmd/Ctrl+Enter also sends from outside the document, `?` or the top bar button lists every shortcut); the agent's stage ("The agent has your batch", "Writing your changes", "Checking the file") with a progress line and a Waiting, check or declined mark on each comment; after a run, the caret returns to where it was and places changed out of view are counted in a "N changes below" pill. The web app reads `session.stage` and falls back to "Agent is working" without it.
100
+ - Background picker: choose what sits behind the editing UI. Five presets, each with a light and a dark rendition (`paper`, the new default, layered translucent sheets; `pages`, the previous drifting document shapes; `aurora`; `studio`; `midnight`), or your own picture (PNG, JPEG, WebP, HEIC where the browser decodes it; up to 15 MB). The page scales a picture to 2560 px and re-encodes it, which drops EXIF and GPS; a legibility guard measures the picture behind the bars and the sidebar and holds the "Image strength" slider back so text stays AA, with a one-line hint when it does. The choice is per machine (`settings.json` in the state folder, the picture under `backgrounds/`), read before the first paint. `onionskin config background <preset|default>`, `config background --image <file> [--strength N] [--no-blur]`, `config get background`; `doctor` shows the current background. New routes `GET/POST /api/settings`, `GET/POST /api/background`, `POST /api/background/remove`.
101
+ ### Added
102
+ - History section in the review panel: the last 20 updates (your edits at each Send, agent runs, reverts, a reloaded outside change), one line each, one open at a time. An open update lists its places with red and green word changes, cell old to new, and plain lines for added, removed, moved and formatting changes; "Show" scrolls to a place and outlines it for two seconds. Red and green exist only in the panel, never in the document. Desktop and tablet only.
103
+ - History reports formatting-only changes: DOCX bold, italic, underline, strike, color, size, font, highlight, paragraph style and alignment (compared per paragraph, so how a writer splits runs does not matter); PPTX text runs; XLSX number formats (resolved formats, not style indexes).
104
+ - `onionskin doctor [--json] [--verbose]`: install check (node, launcher and PATH, skills versus the app's copy, vendored engine integrity, checker venv, LibreOffice, browser, state folder, free disk, server and open-session count). Fix command on every failing line, exit 1 when a required check fails, output safe to paste into a bug report. `scripts/install-check.mjs` now wraps it.
105
+ - Batch: `how_to_apply.command` and `next_step` are pasteable as printed (optional flags in `how_to_apply.options`, ops and results files under the system temp dir); `user_edits[].already_in_file`, anchor `needs_action` and a root `note`; DOCX table labels count tables ("table 1, row 3, column 1"). Results: optional `document_instructions_ignored`, `summary` up to 400 characters.
106
+ - `onionskin open | poll | status | apply | done | setup | setup-checker | stop | --version`: a local server and browser editor for `.docx`, `.xlsx` and `.pptx` files, a blocking poll that hands the user's batch to a coding agent, anchored edits through the same engine the browser uses, and an activity feed with a Revert button.
107
+ - Comments on text selections, paragraphs, cells, ranges, shapes and slides; numbered pins; an overall note; durable anchors that find each comment again after the agent edits the file.
108
+ - `onionskin setup` installs the agent skill into `~/.claude/skills/onionskin` and `~/.agents/skills/onionskin` (`--dry-run`, `--force`, `--uninstall`), reports the node version and whether the deeper checker exists.
109
+ - The agent skill (`skills/onionskin`) with reference pages for ops, the batch and troubleshooting; tests that check every command, flag, op and batch field the skill names against the code.
110
+ - A second browser tab for the same file opens read-only with a banner and an "Edit here instead" button; the server refuses changes from a tab that is not the editor.
111
+ - Integrity checks at `done`: built-in always, optional Python and LibreOffice checks after `onionskin setup-checker`.
112
+
113
+ ### Security pass fixes
114
+ - The browser cookie alone no longer opens anything: a launch token handed to the page once (kept in memory and the page's own sessionStorage) is required on every API request, so another local port that is sent the cookie cannot use it. A new tab needs `onionskin open` again and says so.
115
+ - New `onionskin commit <file> --from <copy> --lease <ticket>` for edits made with python-docx, openpyxl, python-pptx or any other tool; the skill now says to edit a copy and commit it. `done` flags (error, Revert offered) a file that changed during the turn by any other path.
116
+ - Every writer (Send, agent write, commit, revert, standalone apply) holds an advisory lock from the hash comparison through the rename and re-hashes the file right before it; a raced write keeps the newer bytes in a snapshot and returns the conflict.
117
+ - Agent writes and apply reports always need holder, batch id and token (`missing_lease`); `apply`, `commit` and `done` need `--lease` while a batch is delivered (no per-file fallback); `status <file> --ticket` re-reads it for the agent that polled. A ticket, batch or saved delivery makes `apply` and `commit` fail closed when the session is gone, closed or revoked; writing without a session needs `--standalone` and is refused beside a live session.
118
+ - Archives: per-entry cap for stored and deflated entries, a cumulative expansion budget, a relationship-part budget, size checked before reading, and the checks at `done` run in a worker thread so the server keeps answering.
119
+ - Writes loop until every byte is written (a short write is an error, never a truncated file). A replacement keeps the file's ACL and extended attributes on macOS, and refuses to replace a file whose ACL it cannot carry over.
120
+ - A file changed by someone else is never overwritten: the held version is saved as an "(Onionskin copy ...)" file next to it, apply and commit report `outside_change` with the copy's path, and the page shows a plain-words dialog or banner (Show in folder, Reload the changed file, Close). The page checks on focus and every 30 s.
121
+ - `onionskin setup` flags a stale installed skill and prints `onionskin setup --force`.
122
+
123
+ ### Fixed (milestone review)
124
+ - Text from the document in check results is cut to one printable line before it reaches the agent; a relationship that was already broken in the input is no longer blamed on the agent.
125
+ - `done` cannot strand queued comments, and it cannot be completed by an agent whose lease expired (`stale_batch`); `poll` now prints a `lease` that `apply` and `done` send back.
126
+ - Take back after the agent wrote keeps Revert working; comments added while the agent works are anchored where they were placed; the overall note is sent once.
127
+ - Leaving the page with unsent typed edits asks first; Close offers "Download my edits".
128
+ - A repeated paragraph or word is no longer matched to the wrong place after an agent edit; protected paragraphs come from the engine's own classifier.
129
+ - Two servers starting at once can no longer unlink each other's socket.
130
+ - Tests run from a fresh clone: repo-relative fixtures, `node scripts/fetch-fixtures.mjs` for the real Office files.
131
+
132
+ ### Changed
133
+ - XLSX comment flags sit just right of the cell's top-right corner on the row border, so they never cover cell text.
134
+ - PPTX "changed" and "new" tags are drawn above the comment outlines and are always fully visible.
135
+ - A comment on selected words inside a PPTX shape quotes the words in its card and says the outline marks the whole shape.
136
+ - The review panel scrolls the newest activity entry, Revert included, fully above the pinned composer.
137
+ - Flags are checked per subcommand: `onionskin open --ack` is now an error instead of being ignored.
138
+
139
+ ### Fixed
140
+ - The DOCX protected-paragraph test runs against the engine's own protection (`ro` and the reason) and the guard that makes `docx.edit` throw for a changed protected paragraph.
141
+
142
+ ## 0.0.1
143
+
144
+ First public pre-release (2026-11-14).
package/INSTALL.md ADDED
@@ -0,0 +1,25 @@
1
+ # Installing Onionskin
2
+
3
+ Paste this sentence into Claude Code or Codex:
4
+
5
+ > Install Onionskin from https://github.com/abe238/onionskin
6
+
7
+ Your agent does the rest. Prefer to do it yourself? Open a terminal in this folder and run `sh install.sh`. Other ways to install (npm, Claude Code and Codex plugins) are in the README.
8
+
9
+ ## Check it worked
10
+
11
+ Run `onionskin doctor` (or `~/.local/bin/onionskin doctor` if the command is not found). A line that starts with `MISSING` ends with the command that fixes it.
12
+
13
+ ## Start
14
+
15
+ Say to your agent: **open report.docx in Onionskin**. Or type `onionskin report.docx` in a terminal.
16
+
17
+ Your file opens in the browser. Edit, comment, drop a pin, then press **Send to Agent**. The changes appear in the document.
18
+
19
+ ## Uninstall
20
+
21
+ Run `sh ~/.onionskin/app/*/install.sh --uninstall`. Your snapshots stay in `~/.onionskin`; add `--purge` to delete them too.
22
+
23
+ ## What you need
24
+
25
+ A Mac, Node.js 22 or newer (https://nodejs.org/en/download), a browser, and Claude Code or Codex already installed and signed in.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Onionskin contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICE ADDED
@@ -0,0 +1,49 @@
1
+ Third-party notices
2
+
3
+ Onionskin itself is MIT licensed (see LICENSE). It builds on the work below.
4
+
5
+ 1. human-review
6
+
7
+ human-review (MIT), https://github.com/petergyang/human-review
8
+ Copyright (c) 2026 Peter Yang
9
+ The CLI + local server + blocking poll + lease/state-file design in src/ (poll/ack semantics, state names idle/listening/working/queued/stranded/closed/superseded/timeout,
10
+ detached-server startup, exclusive temp-file writes) is ported from human-review. The MIT license text follows.
11
+
12
+ MIT License
13
+
14
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software
15
+ without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
16
+ persons to whom the Software is furnished to do so, subject to the following conditions:
17
+
18
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
21
+ PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
22
+ OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23
+
24
+ The vendored engine in vendor/engine (office-engine fork, MIT) ships its own THIRD_PARTY_LICENSES.txt next to the code.
25
+
26
+ 2. office-engine (MIT), by p10node
27
+ The Word, Excel and PowerPoint viewer and editor engine that runs in the browser, and its DOM-free core that `onionskin apply` runs under Node. Onionskin vendors a fork of it:
28
+ vendor/engine (browser build) and vendor/engine-node (Node build), both pinned by vendor/engine.lock.json to one engine commit.
29
+ Copyright (c) 2026 p10node. The license text is in vendor/engine-node/LICENSE; vendor/engine/THIRD_PARTY_LICENSES.txt lists what the engine bundles in turn.
30
+
31
+ 3. React and React DOM (MIT)
32
+ Copyright (c) Meta Platforms, Inc. and affiliates. The web app (web/src) is built with React 19 and Vite; React is bundled into web/dist. Its license notice is in
33
+ vendor/engine/THIRD_PARTY_LICENSES.txt and in node_modules/react/LICENSE.
34
+
35
+ 4. The agent skill (skills/onionskin) descends from the human-review skill (see 1): the loop wording for Claude Code (background poll) and for Codex and other agents
36
+ (foreground, bounded polls) is adapted from it.
37
+
38
+ 5. Quick fixes (Apple's built-in model; nothing is downloaded)
39
+ Quick fixes use the on-device model that is part of macOS, under Apple's terms, through the small helper scripts/rewriter/apple/onionskin-fm, which
40
+ Onionskin builds from its own source (scripts/rewriter/apple/main.swift, MIT, like the rest of Onionskin) and ships in the zip. No model is shipped or downloaded.
41
+
42
+ 6. The look of the web app: look inspired by Solid Glass by DeepLethe (MIT). Some pane, edge and shadow values in web/src/tokens.css are closely
43
+ adapted from it; no file of it is shipped.
44
+
45
+ Playwright (Apache-2.0) and Vite (MIT) are development dependencies used by the tests and the build; they are not shipped.
46
+
47
+ 3. Test fixtures
48
+
49
+ `test/fixtures/engine/sample.docx`, `sample.xlsx` and `sample.pptx` are the sample documents of the office-engine fork's playground (MIT, see 2), copied unchanged; they were written with python-docx, openpyxl and python-pptx. Real Office files used by some tests are Apache POI test data (Apache-2.0, https://github.com/apache/poi), downloaded on demand by `scripts/fetch-fixtures.mjs` into the gitignored `test/fixtures/cache/` and never committed.
package/README.md CHANGED
@@ -1,3 +1,149 @@
1
- # Temporary Holding Version
1
+ # Onionskin
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Edit a Word, Excel or PowerPoint file in your browser, leave comments, and let your coding agent make the changes in the real file.
4
+
5
+ ![Onionskin: a Word file open in the browser editor with the review panel beside it](docs/media/hero.png)
6
+
7
+ ![A comment sent to the agent, the real file changing, and the page reloading in place](docs/media/demo.gif)
8
+
9
+ *The demo is a real run, recorded in the real app with its background agent: the file changed 7.8 seconds after Send. Nothing is sped up.*
10
+
11
+ ## Install
12
+
13
+ Paste this sentence into Claude Code or Codex:
14
+
15
+ > Install Onionskin from https://github.com/abe238/onionskin
16
+
17
+ That is the whole install. Your agent does the rest and tells you when it is ready.
18
+
19
+ ### Other ways to install
20
+
21
+ Pick one. The Terminal, npm and zip routes install the app and the skill. The two plugin routes bring the skill, and the skill installs the app the first time you use it.
22
+
23
+ **Terminal.** Paste these two lines into Terminal:
24
+
25
+ ```sh
26
+ RELEASE=https://github.com/abe238/onionskin/releases/latest/download
27
+ curl -fsSL "$RELEASE/get.sh" | ONIONSKIN_BASE_URL="$RELEASE" sh
28
+ ```
29
+
30
+ **npm.** If you use npm, run:
31
+
32
+ ```sh
33
+ npm install -g onionskin-cli
34
+ onionskin setup
35
+ ```
36
+
37
+ **Claude Code plugin.** Type these in Claude Code:
38
+
39
+ ```
40
+ /plugin marketplace add abe238/onionskin
41
+ /plugin install onionskin@onionskin
42
+ ```
43
+
44
+ **Codex plugin.** Run these in Terminal:
45
+
46
+ ```sh
47
+ codex plugin marketplace add abe238/onionskin
48
+ codex plugin add onionskin@onionskin
49
+ ```
50
+
51
+ A plugin brings the skill only. The first time you ask for Onionskin, your agent installs the rest with the Terminal command above.
52
+
53
+ **Zip.** Download `onionskin.zip` from the [latest release](https://github.com/abe238/onionskin/releases/latest), unzip it, open Terminal in the `onionskin` folder and run `sh install.sh`.
54
+
55
+ ### Check it worked
56
+
57
+ ```sh
58
+ onionskin doctor
59
+ ```
60
+
61
+ Each line starts with `OK`, `NOTE` or `MISSING`. A `MISSING` line ends with the command that fixes it. If Terminal says the command is not found, run `~/.local/bin/onionskin doctor`.
62
+
63
+ ### Update
64
+
65
+ - Terminal or zip install: run the same install again. Your snapshots are kept.
66
+ - npm: `npm install -g onionskin-cli`, then `onionskin setup --force` to replace the older skill folders.
67
+ - Claude Code plugin: `claude plugin marketplace update onionskin`, then `claude plugin update onionskin@onionskin`, then restart Claude Code.
68
+ - Codex plugin: `codex plugin marketplace upgrade onionskin`.
69
+
70
+ ### Uninstall
71
+
72
+ - Terminal or zip install: `sh ~/.onionskin/app/*/install.sh --uninstall`. This keeps your snapshots in `~/.onionskin`. To delete those too, add `--purge`.
73
+ - npm: `onionskin setup --uninstall`, then `npm uninstall -g onionskin-cli`.
74
+ - Claude Code plugin: `claude plugin uninstall onionskin@onionskin`.
75
+ - Codex plugin: `codex plugin remove onionskin@onionskin`.
76
+
77
+ Removing a plugin removes the skill only. The `onionskin` command stays until you remove it with the Terminal line above.
78
+
79
+ ### For the agent doing the install
80
+
81
+ You were asked to install Onionskin. Run this as one shell command from any folder. It needs no sudo and does not ask the person to type anything.
82
+
83
+ ```sh
84
+ RELEASE=https://github.com/abe238/onionskin/releases/latest/download
85
+ curl -fsSL "$RELEASE/get.sh" | ONIONSKIN_BASE_URL="$RELEASE" sh
86
+ onionskin doctor # if "command not found", run ~/.local/bin/onionskin doctor
87
+ ```
88
+
89
+ - The script checks the download's SHA-256 and installs under `~/.onionskin`, `~/.local/bin`, `~/.claude/skills/onionskin` and `~/.agents/skills/onionskin`. Its last lines say what was installed.
90
+ - If it says Node.js 22 or newer is missing or too old, tell the person plainly and give them https://nodejs.org/en/download (the macOS Installer). Ask them to run it and then ask you again. Do not install Node.js yourself.
91
+ - If `onionskin doctor` shows a line starting with `MISSING`, run the command at the end of that line, then run doctor again.
92
+ - Then tell the person exactly this and nothing else (no paths, versions or install details): "Onionskin is installed. To use it, say: open <your file> in Onionskin"
93
+
94
+ ## Use it
95
+
96
+ Two ways to start:
97
+
98
+ - Say to your agent: **open report.docx in Onionskin**
99
+ - Or type this in a terminal: `onionskin report.docx`
100
+
101
+ Your file opens in the browser. Edit the text, comment on a spot, drop a pin, then press **Send to Agent**. The changes appear in the document, and **Revert** puts the last one back.
102
+
103
+ Who does the work depends on how you started:
104
+
105
+ - **From a terminal** (`onionskin report.docx`): Onionskin starts its own background agent. It is Claude Code only, it runs on your own Claude plan, and it needs Claude Code installed and signed in. A **Show the agent** switch shows what it is doing, and **Open in Terminal** opens the same conversation in Terminal. On a Mac with Codex but no Claude Code, the terminal says so in plain words and tells you to ask Codex instead.
106
+ - **From inside Claude Code or Codex** ("open report.docx in Onionskin"): the agent you are talking to does the work.
107
+
108
+ The background agent is limited on purpose. It can change your document only through Onionskin's own commands, it cannot read your other files, and it is started without any API keys.
109
+
110
+ ## What it can do
111
+
112
+ - Opens a `.docx`, `.xlsx` or `.pptx` in a browser editor with a review panel beside it, and keeps the file's own formatting.
113
+ - Lets you edit the text yourself, comment on a selection, a cell, a range, a shape or a slide, drop numbered pins, and write one overall note.
114
+ - Sends all of that to your agent when you press Send. The page reloads in place and keeps your position.
115
+ - Lets you keep editing while the agent works, and merges your edits with its version when it finishes.
116
+ - Shows what changed in red and green, keeps a history, and has a Revert button for the last agent run.
117
+ - Exports a Word file with real tracked changes.
118
+ - In Excel, Shift+Enter or Alt+Enter starts a new line inside a cell.
119
+ - Edits structure in your file: add or delete a table row or column in Word, and copy, delete or move a slide in PowerPoint. Charts are not edited: the agent tells you to insert the chart in Word or PowerPoint. Excel merged cells are understood.
120
+ - Runs plain commands such as "Replace Acme with Initech" and quick grammar fixes on your Mac.
121
+
122
+ ## What you need
123
+
124
+ - A Mac, a browser, and Node.js 22 or newer (your agent will tell you if it is missing).
125
+ - Claude Code or Codex, already installed and signed in. The terminal start needs Claude Code; with Codex, you start from inside it.
126
+ - For quick fixes only: macOS 26 or later, Apple silicon and Apple Intelligence turned on. Without it, grammar fixes go to your agent.
127
+
128
+ Limits: macOS only so far. This is a pre-release (0.0.2) and has been tested by one person. No Windows, no Linux, no real-time collaboration.
129
+
130
+ ## Privacy
131
+
132
+ The editor runs on your computer and the page makes no outside requests. Your document's text goes to the coding agent you already use (Claude Code or Codex) when you press Send. Every batch carries the text of the whole document, not only the part you commented on, because the agent needs it to find the right place. Only quick fixes and the no-AI quick commands stay entirely on the Mac.
133
+
134
+ ## Credits
135
+
136
+ - The document engine is a fork of [office-engine](https://github.com/p10node/office-engine) by p10node (MIT).
137
+ - The review loop and the agent skill's wording descend from [human-review](https://github.com/petergyang/human-review) by Peter Yang (MIT).
138
+
139
+ ## License
140
+
141
+ MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
142
+
143
+ ## Made by abe238
144
+
145
+ [GitHub: abe238](https://github.com/abe238) · [abediaz.com](https://abediaz.com) · [X: @abe238](https://x.com/abe238)
146
+
147
+ If Onionskin saves you time, a star on the repo helps other people find it.
148
+
149
+ For developers: [docs/DEVELOPERS.md](docs/DEVELOPERS.md)