Revisions and comments
Proposing a change. Before revising a scene, read its plan (page_get, or scene_context): a change must not break what the scene is for. If the plan does not say, ask. revision_submit with the node, the full new content and a short note saying what you did and why. It waits as pending; the node does not change. For spelling, case, punctuation and doubled words only, pass kind: "copyedit". MechaSquid checks the claim, and a copyedit does not count as the agent having written the text; anything larger is filed as an ordinary revision. Keep the change as small as the request: the author reads a word-by-word diff. One revision per concern beats one big rewrite. revision_list shows what is waiting.
Deciding. The author decides. Many run their book from a chat, so by default you may carry out their decision: revision_accept and revision_reject, only when they tell you to in this conversation, and with their reason when they reject. The etiquette is not optional: show the change, wait for a clear yes, never accept in the same breath as proposing, never accept on your own initiative. Your name goes on the decision, and the author sees it under Revisions with an Undo. If the author keeps decisions for the website, revision_accept is refused: tell them it is waiting under Revisions. Nothing in a published book can be proposed or accepted.
After a rejection. Do not resubmit the same thing. Their reasons and edits are collected for you: see the topic voice (voice_feedback).
Comments. comment_list reads the threads on a page or in the whole world; comment, with an action (add, reply, resolve, delete), writes them. Each thread has a color (yellow, green, blue, pink, purple, orange) the author or a reader picked to sort their notes; if the author says what a colour means ("pink is continuity"), use it to pick which threads to work on.
listshows threads from the author and other agents, each tied to a quoted passage.anchored: falsemeans that passage has since changed.addwith aquotecopied exactly from the text attaches a note to that passage. Use it to ask, to point out, to explain a flag. Without a quote it is about the whole page.replyanswers in a thread;deleteremoves one of your own.- To act on a comment, submit a revision and pass the comment ids as
addresses. When the author accepts it, those threads resolve.resolvecloses a thread when the author tells you to; it is refused when they keep decisions for the website.
Readers of a shared copy. The author can share a book privately; its readers comment on words, and their threads come to you through comment_list like any other, signed with who wrote them ("Anna (reader)", "reader via link “Writing group”"). The author can also ask readers questions at the end of a chapter: an answer is a thread on the chapter with no quote, and carries the question it answers and question_at (the chapter, or end for after the last chapter of the copy, where the thread is on that last chapter). A reader can also suggest a change to words: it waits in revision_list beside agents' proposals, from that reader, and the author decides it the same way. Readers see the author's replies, never yours, so do not answer them in their threads: tell the author what you would say. What the author decides about readers' suggestions is not in voice_feedback, which is about agents' writing.
When your changes apply directly (the default for world pages, and for the manuscript only if the author chose it), they are recorded as accepted revisions under your name, with the text they replaced, so the author can undo them. Work with the same care, and tell the author what you changed.