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 an explicit comment moderator grant or containing workspace manager authority. A JWT role/capability label alone does not confer that authority; ordinary readers 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 0199e100-0000-7000-8000-00000000000a \
  --state hidden --reason "Personal information"

{
  "action_id": "0199e100-0000-7000-8000-75eb65b8fa9b",
  "comment_id": "0199e100-0000-7000-8000-00000000000a",
  "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 --filter 'toxicity_score[gte]=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. Sorting a thread by pinned puts pinned comments at the top of the whole thread, not just one page: --sort -pinned,created_at (HTTP: sort=-pinned,created_at). Without it they stay 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). The creator also needs workspace creation authority. Read access comes from authorship, explicit audience sharing or scoped moderation authority, not the token's audit-ingress capability alone. Other viewers cannot discover the row in the thread and get 404 comment_not_found on direct reads. Authorized viewers see it inline, marked by its visibility mode.

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

Enterprise authority

Moderation authority comes from an explicit comment moderator grant or the containing workspace's manager rule, subject to a current eligible principal. Organization ownership and JWT role strings do not automatically expose unrelated private workspaces. An author manages their comment's sharing; grant moderator explicitly when they should also perform moderation transitions or pinning.

Hidden/removed public comments remain redacted tombstones on direct HTTP reads and are excluded from ordinary thread lists. Authorized moderators retain their full view. Soft deletion preserves the reply tree and suppresses queued content delivery.