Suggest changes

Suggestions are the "I'd like to propose an edit" flow. The recipient of a share submits a full proposed new version; the owner approves (and the suggestion becomes the live content) or rejects (and the proposal is archived in version history).

It's the same mental model as Google Docs' "Suggesting" mode, but the unit of proposal is a whole-content version rather than per-line diffs. The diff is computed on the fly when the owner reviews.

Who can suggest#

A user can submit a suggestion against a share if they satisfy any of:

• Org admin of the share's owner org. (Admins can also edit directly — they go through the suggest flow when reviewing a recipient's work as if they were a recipient.)
• Project member (viewer or editor) on the share's project.
• Share editor (granted via share_members — see Doc-level roles).
• Org viewer (cross-project read access — see Doc-level roles).
• Anyone with the URL, if the share's access rung is suggest (see Access and passwords). Submitting still requires signing in.

Anonymous suggestions (no Anchorify account, link permission can_suggest) are explicitly deferred — they require captcha + rate-limit hardening (V4 #20). Today the suggester must be signed in.

Recipient flow#

1. Open the share. The renderer shows a Suggest changes button under the body when the caller satisfies suggestion.create.
2. Click it. The page opens an editor pre-filled with the current content.
3. Make edits, click Submit suggestion. The proposal lands as a suggested version on the share's history.
4. The share's owner gets a suggestion.submitted notification and an email, linking to that share's suggestions page where approve/reject live. (An unapproved suggestion is invisible to everyone except the owner, so a missed bell would silently strand your work.) When they decide, you get a suggestion.approved or suggestion.rejected notification and an email — so you find out without having to keep a dashboard open.

Track all your open suggestions across every share at /dashboard/suggestions — or via GET /api/v1/me/suggestions.

Owner flow#

The owner sees pending suggestions in four places:

• On the document itself — the ⋮ menu in the share's header carries a dot when something is waiting, and the menu reads Suggestions (2). This is the one that finds you: you are usually reading the document, not scanning an inbox.
• Bell notification + email — both arrive on submit; the email links straight to the review page. Mail delivery is best-effort and never gates the suggestion itself.
• Inbox — /dashboard/inbox lists every pending decision across the org (access requests + suggestions).
• Per-share — the share's version history (/<org>/<project>/<slug>/versions) shows suggestions inline with the approved versions, marked suggested.

The per-share suggestions page and the dot are org-admin only — they authorize on membership of the org that owns the share. A project editor or a share-level editor can suggest and can edit, but reviewing someone else's suggestion is the owning org's call.

Open a suggestion to see:

• A diff of the suggested content against the current live content.
• The suggester's username + timestamp.
• The full proposed body (collapsible).
• Approve and Reject buttons.

Approving#

Approving copies the suggested content into shares.content, flips the version row to status='approved', and emits a suggestion.approved notification and an email to the suggester, linking to the share so they can see the change live. The audit log records the approval (share.suggestion.approve).

The approved version becomes the new live content; older approved versions are still in history. Restoring rolls back to any prior version, including the one that was live before the approval.

Rejecting#

Rejecting flips the version row to status='rejected' (no content copy) and emits suggestion.rejected to the suggester, also by notification and email — that one carries no link, since there is nothing to go and look at. The rejected version stays in history for audit. A rejected suggestion cannot be re-approved — the suggester must submit a new one.

Neither mail fires when the person deciding is the person who suggested (an owner acting on their own draft), and neither can hold up the decision: delivery is best-effort and sits outside the transaction that commits it.

API#

• POST /api/v1/shares/:id/suggestions — submit.
• POST /api/v1/shares/:id/suggestions/:vid/approve — approve.
• POST /api/v1/shares/:id/suggestions/:vid/reject — reject.
• GET /api/v1/me/suggestions — your submitted suggestions across every share.
• GET /api/v1/shares/:id/versions?status=suggested — pending suggestions on a specific share you own.

What's not in here#

• Per-line suggestions — proposals are whole-content. Per-line markup is a follow-up.
• Inline reply threads on a suggestion — comment on the share itself for discussion; the suggestion is a single submit-then-decide event.
• Withdrawing a suggestion — a suggester can't currently retract a pending suggestion. Workaround: ask the owner to reject it.
• Anonymous suggestions — gated behind V4 #20 (captcha + rate-limit hardening).