> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Comments

> Thin, anchored annotations that humans and agents leave on a topic, a record, or a card. Feedback that resolves into an edit, without touching the content itself.

A **comment** is a thin annotation that points AT something (a topic, a record, or a project card) and optionally at one of its fields. It is the lightweight way for humans and agents to coordinate over content **without editing it**.

A comment is deliberately *not* a topic. It has no version, no drift, and no governance of its own; its text never enters the topic body. Topics are the durable *why*; comments are transient coordination that **resolves into an edit**.

## What a comment is

* **Points at a spine object or a card.** `target_kind` is one of `topic`, `record`, or `card`; `target_id` (or, for a topic, its slug) says which one. An optional `field_key` scopes the comment to a single field (e.g. `decisions`).
* **Authored by a human or an agent.** Agent-authored comments are what set this apart: an agent can flag a contradiction on a field and a human sees it on the next refresh, or the other way around. That is what makes the workspace genuinely collaborative *between* humans and agents.
* **Has a small state machine.** `open → resolved → wont_fix`. When an edit addresses a comment, its author (human or agent) marks it resolved. There is no auto-regenerate. Comments resolve, they don't rewrite the document.
* **Async, not realtime.** Comments appear on pull/refresh. No live cursors.

## The killer placement: the Note → Knowledge gate

Promoting a Note into Knowledge is normally a coarse, binary act: approve or reject. Comments turn that gate into **fine-grained, field-level feedback at review time**. A reviewer (or an agent) can pin a precise objection to the `decisions` field of a note, the author addresses exactly that, and the merge happens faster and comes out better. Listing a topic's open comments by slug is the reviewer's view of the gate.

## Using comments

From the CLI (the surface also exists in MCP as `driftless_context_comment`):

```bash theme={"theme":"github-light"}
# Leave feedback on a topic, scoped to a field
driftless context comment add billing-flow --body "This decision contradicts the refund invariant" --field decisions

# On a card or a record (by uuid)
driftless context comment add --card <card-uuid>   --body "Blocked on the webhook fix"
driftless context comment add --record <record-uuid> --body "Duplicate of the Globex lead"

# The reviewer's view, then resolve
driftless context comment list billing-flow --status open
driftless context comment resolve <comment-id>          # or --wont-fix, or `reopen <id>`
```

Comments are workspace-scoped and respect the same tenant boundary as every other object: a comment can only point at a target that lives in the same workspace.