Delivery Formats

Every output is a file in the job folder, beside the text. None of them is written into the author's document. suggestions.json is the source of truth; the other files are views of it, rewritten by suggest, apply and render. The examples are from the job on Commands.

File	Made by	For
suggestions.md	suggest, render, apply	reading the suggestions, grouped by level
review.md	suggest, render, apply	the text with every change and query inline, in CriticMarkup
provenance-ledger.md and provenance.json	suggest, render, apply, ledger	the AI-written word count (see Provenance and AI-text rules)
review.docx	export	Word or Google Docs, with tracked changes and comments
edited.md and its changelog (edited.docx with --docx)	apply	the text with the accepted changes
editorial-letter.md	the agent	the developmental letter; ew.py does not write it

suggestions.md

One entry per suggestion, grouped by level from developmental down to proof. Each says the ID, category, paragraph, severity and AI-written words, then the quote, the problem, why it matters, the options and the proposed change with its word count. A suggestion without a change ends "Query: the fix is yours to write."

$ cat works/the-salt-road/jobs/*/suggestions.md
# Suggestions: The Salt Road

Level of edit: full. Genre: short-story. Mode: human-authored. Paragraph numbers (P) match clean.md.
Nothing here has been applied. Tell the editor which IDs you accept; queries need your own words.

## Developmental (1)

### S-005 · stakes · P9 · severity 3
> She realized the stranger was her cousin.

- Problem: The reveal has no setup, so it reads as coincidence.
- Why it matters: Readers accept a surprise they could have seen coming.
- Option 1: Plant the cousin earlier in the story.
- Option 2: Move the reveal so the reader learns it with Nell.
- Query: the fix is yours to write.

## Line (2)

### S-004 · rhythm · P7 · severity 1 · AI words: 3
> as mules do

- Problem: The aside is flat.
- Proposed change: {~~as mules do~>the way mules will~~}
- Words: removed as, do; AI-written: the way will (3)

### S-002 · repetition · P8 · severity 1
> very hard, 

- Problem: The repeat softens the sentence instead of stressing it.
- Why it matters: The cracked axle already shows how hard the cart was driven.
- Option 1: Cut the repeat.
- Option 2: Keep it if Nell's voice leans on repeats elsewhere.
- Proposed change: {--very hard, --}
- Words: a cut, no new words; removed very, hard

## Copy (2)

### S-003 · tense · P8 · severity 2
> walks

- Problem: Tense slip: the story is told in the past tense.
- Proposed change: {~~walks~>walked~~}
- Words: corrected walks>walked

### S-006 · punctuation · P8 · severity 2
> hard, very

- Problem: A full stop would give the repeat its own beat.
- Proposed change: {~~hard, very~>hard. Very~~}
- Words: punctuation only, no new words

## Proof (1)

### S-001 · typo · P5 · severity 2
> teh

- Problem: Typo.
- Proposed change: {~~teh~>the~~}
- Words: corrected teh>the

review.md (CriticMarkup)

The cleaned text with each change marked in CriticMarkup and tagged with its ID, and each query as a highlight with a comment:

Mark	Meaning
{++text++}	insertion
{--text--}	deletion
{~~old~>new~~}	substitution
{==span==}{>>note<<}	a comment on a span

$ cat works/the-salt-road/jobs/*/review.md
# The Salt Road

Nell had walked the salt road every morning for nine years. She knew where the ruts ran deep and where the gulls waited for scraps.

"You're late," said her brother when she reached the gate.

"The tide was high," Nell said. "I had to go round by the old mill."

She saw the cart standing empty by the well. Nobody had unloaded {~~teh~>the~~}{>>S-001<<} barrels, and the mule was gone.

* * *

By noon the village was talking. Some said the mule had wandered off, {~~as mules do~>the way mules will~~}{>>S-004<<}. Others said a stranger had come in the night and taken it.

Nell {~~walks~>walked~~}{>>S-003<<} to the well again and looked at the cart. The axle was cracked. Someone had driven it {~~hard, very~>hard. Very~~}{>>S-006<<} hard, and then left it.

{==She realized the stranger was her cousin.==}{>>S-005: The reveal has no setup, so it reads as coincidence.<<}

Where two changes overlap, the one that starts first wins in this view. S-002 (cut "very hard, ") is not in it, because S-006 starts one word earlier; S-002 is still in suggestions.md. A query on text that a change also touches is placed as a comment at the end of its paragraph.

CriticMarkup reads as plain text. GitHub and VS Code show the braces as typed. The kb names two tools that act on it, neither tried for these pages: Obsidian's Commentator plugin, which gives accept and reject, and MultiMarkdown 6, where -a accepts all and -r rejects all.

review.docx

ew.py export writes clean.md as a Word document with each proposed change as a tracked change (author "editwright suggestion S-nnn") and each suggestion as a comment (author "editwright"). It is built with the standard library: no python-docx, no pandoc.

$ python3 ew.py --works works export the-salt-road
wrote /tmp/demo/works/the-salt-road/jobs/20261009-1-full/review.docx: 4 tracked suggestion(s) and 5 comment(s) on a copy of clean.md
left out (they overlap an earlier change; they are in suggestions.md): S-002
open it in Word, or upload it to Google Drive and open with Google Docs; accepting there is the author's act

The parts in the file, and the tracked changes in it:

$ python3 -c "import zipfile, glob; print('\n'.join(zipfile.ZipFile(glob.glob('works/the-salt-road/jobs/*/review.docx')[0]).namelist()))"
[Content_Types].xml
_rels/.rels
word/_rels/document.xml.rels
word/document.xml
word/styles.xml
word/comments.xml

$ python3 -c "import zipfile, glob, re; x = zipfile.ZipFile(glob.glob('works/the-salt-road/jobs/*/review.docx')[0]).read('word/document.xml').decode(); print(len(re.findall('<w:ins ', x)), 'insertions,', len(re.findall('<w:del ', x)), 'deletions')"
4 insertions, 4 deletions

Overlapping changes are left out of the document, as the message says. Headings become Word headings; the text is set in Times New Roman, 12 point, on a US Letter page.

What has and has not been opened, per the skill's kb/delivery.md (checked 2026-10-08): pandoc 3.12 (--track-changes=all) and LibreOffice read editwright's output as insertions, deletions and anchored comments. It has not yet been opened in Microsoft Word. These pages did not open it in any word processor.

Google Docs

Upload review.docx to Google Drive and open it with Google Docs. Google's help says "Any tracked changes in Microsoft Office become suggestions in Google Docs" (support.google.com/docs/answer/6033474). The result is a new Doc beside the original, so the original is untouched. Comments coming across is untested with editwright's output. The kb also records a Docs API route (suggest mode in batchUpdate, generally available since 2026-09-30) that editwright does not use yet.

edited.md and its changelog

apply writes the accepted changes to edited.md (then edited-2.md and so on), with edited-changelog.md beside it. The changelog's table has the ID, paragraph, before, after, a word note and who wrote the new words. --docx also writes edited.docx, a plain document without tracked changes. Examples are on Commands.

The edited file is built from clean.md, so it carries the cleanup: joined hard-wrapped lines, * * * scene breaks and the quote style intake chose. The source file is never touched.