Moderation and Visibility

Comments carry a moderation state machine plus a visibility mode, and the two answer different questions: moderation state is what happened to this comment (flagged, hidden, removed...), visibility is who was ever meant to see it (public vs agent-audit). Moderator operations require a platform admin token or the moderator capability; regular tokens get 403 insufficient_permissions.

The state machine

States: pending, visible, flagged, hidden, removed, deleted.

• New comments start in pending - the toxicity-scoring integration that would promote them to visible (or auto-flag them) is not yet wired, so today every regular comment is born pending and threads include pending comments.
• Moderators may move a comment between any two distinct states except deleted. A same-state transition is rejected: 400 Invalid moderation transition: hidden -> hidden.
• deleted is reserved for the soft-delete endpoint and is terminal: nothing transitions in or out of it.

snug comment moderate --comment-id yxjegyesTDVYJqSPvhYz \
  --state hidden --reason "Personal information"

{
  "action_id": "zNYvXWpnbqnZaxuSGVHc",
  "comment_id": "yxjegyesTDVYJqSPvhYz",
  "from_state": "pending",
  "to_state": "hidden"
}

Each transition writes an audit action (action_id), and the reason is appended to the comment's moderation.flag_reasons.

What regular viewers see

Two different mechanisms:

• Thread listings for non-moderators only include comments in pending, visible, flagged, or deleted states - hidden and removed comments vanish from the thread entirely.
• Direct get of a hidden or removed comment still succeeds but is tombstoned: the body reads [hidden] or [removed], mentions are emptied, and the moderation detail object is null. Moderators receive the original text plus the full moderation object (state, flag_reasons, toxicity_score).

Anonymous authorship is the third redaction: author is null for other users, populated for the author themself and for moderators (with display_mode: "anonymous" preserved for the UI).

The flagged queue

snug comment moderate --flagged
snug comment moderate --flagged --min-toxicity 0.8

Returns flagged comments (toxicity-descending, paginated) with full moderation detail - the review inbox for a moderation dashboard.

Pinning

snug comment pin --comment-id KJDRuveZuucXgZahrvrV
snug comment pin --comment-id KJDRuveZuucXgZahrvrV --unpin

Pinning is moderator-only. A pinned comment sorts to the front of a thread page when the thread is fetched with --pinned-first (HTTP: pinned_first=true); without the flag it stays in chronological position.

Agent audit comments

Agents and operators can attach technical notes to a resource without leaking them into the user-facing thread:

snug comment audit --target docs4-item-1 --type item \
  --body "Repair script reconciled durability drift."

Requires a service account, platform admin, or the agent/support capability - a regular user token gets 403. Audit comments are created with visibility: "agent_audit" and start visible (they skip the pending gate). For a regular user they are invisible both ways, verified live: the thread omits them and a direct get by id returns 404 comment_not_found rather than acknowledging the comment exists. Privileged viewers see them inline in the thread, marked by their visibility mode.

The comment's true author is always stored, so anonymous and agent-audit comments remain attributable in the audit trail.