ah-ptu Yonote Q&A bot loop: poll doc comments, answer via board tasks (post-wave-2.5) Past Stand

Why: the operator wants to ask questions as comments on Yonote docs (e.g. on agent-published reports) and have the bot answer in-thread. What: a polling loop (daemon has no public ingress — loopback-only listen — so webhooks are out for now) over events.list filtered to comments.create since a persisted cursor; qualifying comments spawn a question-answer board card whose description carries the doc URL (ah-2lh materialization then feeds the agent the doc as context); the answer is delivered via comments.create (parentCommentId threading) + optional comments.resolve under the bot identity. EXPLICITLY NOT wave 2.5: needs cursor persistence, a second poll loop, trigger-convention + mention-encoding verification, and a reply-channel decision. Depends on ah-gxa (comments methods; extend with ListEvents when picked up) and ah-25e (reply channel + bot write provisioning).

# Yonote Q&A bot loop (post-wave-2.5 — honest scope, NOT part of wave 2.5)

Goal: the operator asks questions IN Yonote (comments on docs — e.g. on agent-published reports
or on specs); the bot notices, an agent produces the answer, the bot replies in-thread and
resolves the comment.

## Verified surface this builds on (2026-07-18, bigbes.yonote.ru 1.47.1)

- comments.list {entityId, isResolved filter, threadId, limit ≤100, offset} → {data:{comments:[…]},
  pagination, total} — LIVE-verified (nested envelope; items carry threadId, isResolved,
  threadCommentsCount, attachments).
- comments.create {entityType:"document", entityId, text, parentCommentId} → {data:{comment}} —
  LIVE-verified end-to-end on a probe doc: text stored verbatim (plain string), threading via
  parentCommentId; a reply's threadId points at the root comment.
- comments.resolve {id, isResolved} → data.comment — spec'd (v2-preview), plus the product MCP
  server exposes yonote_resolve_comment, so the surface is real.
- events.list POST {name, actorId, documentId, collectionId, limit, offset, sort/direction} —
  LIVE-verified (returned {pagination, data:[{id, name, actorId, actor, documentId, collectionId,
  createdAt, data, modelId}]}); the `name` filter ("objects.verb", e.g. "comments.create") is
  spec'd — server-side event filtering makes cheap incremental polling possible.
- webhookSubscriptions.list responds LIVE (empty list) though it is UNDOCUMENTED in both Yonote
  OpenAPI specs (Outline heritage; auth.info policies include create/listWebhookSubscription).
  BUT the daemon binds loopback-only (config validateLoopback) with no public ingress, so v1
  transport = POLLING events.list; webhooks stay a documented future option if ingress appears.

## Sketch (design decisions OPEN — settle when picked up)

- Poll loop: own ticker (~60s), separate from the reconcile tick; cursor persisted in the store
  (new kv row, e.g. yonote_cursor = last seen event id/createdAt). MUST verify then: events.list
  ordering + Sorting params for reliable incremental reads (direction/sort exist in the Pagination
  /Sorting schemas but were not exercised).
- Trigger filter (pick one): (a) new unresolved comments on docs AUTHORED BY THE BOT
  (createdById == bot user id from AuthInfo) — simplest, covers "questions about agent output";
  (b) explicit @mention of the bot — mention ENCODING in comment text is UNVERIFIED (probe stored
  plain text verbatim; the editor may encode mentions as structured nodes invisible to .text);
  (c) any unresolved comment in configured collections.
- Self-trigger guard: ignore events with actorId == bot user id.
- Answer path: reuse the whole existing pipeline — create a board card (existing CreateTask port,
  agent_tasks bucket conventions) of a question-answer task type whose description contains the
  doc URL (the materialization bead then auto-exports the doc as context for the agent!) plus the
  question thread text; the agent writes the answer; the daemon replies via comments.create with
  parentCommentId = thread root and optionally comments.resolve. Reply delivery needs either a
  small extension of the publish channel ({"reply_to_comment": …}) or a dedicated
  .task/answer.json — decide at design time.

## Why not wave 2.5

Needs cursor persistence, a second poll loop, trigger-convention and mention-encoding
verification, and a reply file-channel decision — none of which artifact materialization or the
publish lane depend on. Client extensions required when picked up: ListEvents (events.list) and
possibly webhookSubscriptions.* — add to internal/yonote then, not now.

Depends on: internal/yonote client bead (comments methods land there), publish-lane bead (reply
channel shape + bot write provisioning).

Live evidence (2026-07-18): events.list POST works — {pagination, data:[{id, name, actorId, actor, documentId, collectionId, createdAt, data, modelId}]}, event names 'objects.verb' (observed documents.permanent_delete from the trash-purge cron); the name/actorId/documentId/collectionId request filters are v1-spec'd. comments.create/list verified end-to-end on the probe doc (threading via parentCommentId; replies carry threadId of the root; text stored verbatim). comments.resolve spec'd + present as yonote_resolve_comment in the product's own MCP server. webhookSubscriptions.list responds live (empty, UNDOCUMENTED in both OpenAPI specs — Outline heritage; auth.info policies include createWebhookSubscription) — future option only, blocked on public ingress. UNVERIFIED for pickup: events.list ordering/Sorting params for reliable incremental cursors; @mention encoding inside comment text (probe stored plain text; the editor may use structured nodes invisible in .text — trigger option (a) 'comments on bot-authored docs' avoids the question entirely).