ah-25e Yonote publish lane: .task/publish.json → bot-authored docs at finalize Past Stand

Why: the operator wants agents to publish specs/reports/answers INTO Yonote instead of committing them to the project repo — with the write credential never entering the agent's environment. What: a third finalize-time file channel in the SPEC §14.4 family (tasks.json, question.json): the agent writes markdown under .task/publish/ and declares it in .task/publish.json {documents:[{title, file, collection_id?, parent_url?}]}; on successful finalize the daemon creates the docs via the internal/yonote client under the BOT token (publish:true, target = yonote.publish_collection_id or per-entry override, optional nesting under a referenced doc), comments the resulting URLs on the card, emits a yonote_published event. Publish failures never change the run outcome. wave 2.5 — implement after feat/wave2-archive-links merges. Depends on ah-gxa (client: CreateDocument/DocumentInfo) and ah-2lh (yonote config block + prepareTaskDir channel-clearing site).

# Yonote publish lane: .task/publish.json → bot-authored docs at finalize

Agents publish specs/reports/answers INTO Yonote instead of committing them to the project repo.
The agent declares intent via a file channel; the daemon executes with ITS bot token at finalize
and links results on the card.

## Why file-channel, not direct API access from the agent (DECISION)

The agent must never hold the Yonote token: worktrees run arbitrary generated code; `.task/` is
archived to tar.gz at Done (a token in env or files would fossilize into archives); per-run env
plumbing would put a write-capable credential into every zellij session. The daemon already owns a
finalize-time file-channel protocol with exactly the right semantics — `.task/tasks.json`
(delegation) and `.task/question.json` (ask-user), SPEC §14.4: agent writes declarative intent,
daemon acts with its own credentials, results land as card comments. Publishing is the third
channel of that family. Attribution lands on the BOT user — uniform and auditable.

## Channel format

`.task/publish.json` (attempt-scoped; cleared in prepareTaskDir alongside summary/tasks/question):

    {"documents": [
      {"title": "Design: frobnicator", "file": "publish/design.md",
       "collection_id": "", "parent_url": ""}
    ]}

- title: required, non-empty, ≤255 chars (Yonote bot/user name limits suggest 255 conventions).
- file: required; RELATIVE path resolved under `.task/` (convention: agents put content in
  `.task/publish/<name>.md`). Guard rigor as repo-slug F8: reject absolute paths, filepath.Clean
  must stay under .task/, and the opened file must not escape via symlink (os.Root / EvalSymlinks
  containment check).
- collection_id: optional uuid overriding the config default target.
- parent_url: optional Yonote doc URL → resolve via yonote.ParseDocRefs(single) + DocumentInfo →
  parentDocumentId, so a report can nest under the spec it answers (documents.create
  parentDocumentId is v1-spec'd; child creation itself NOT live-verified — verify in tests against
  httptest only, live during rollout).
- Caps: maxPublishDocs = 3 per run; maxPublishBytes = 512 KiB per file. No server-side text limit
  was verified — cap defensively; an oversize entry FAILS (listed in the comment), never truncated.

Read at SUCCESSFUL finalize only, same site and semantics as readTasksFile: absent → nil (common
case); present-but-unparseable → same bounce treatment as a malformed tasks.json (do not silently
drop agent intent).

## Config

The `yonote` block (introduced by the materialization bead) gains:

    publish_collection_id: "…"    # uuid; the default target collection

Validation: when set, must be a UUID shape; lane is ACTIVE only when the yonote client is
configured AND publish_collection_id is set. When the client is configured but the collection is
not, publish.json entries all fail visibly with "publishing not configured" in the card comment —
never silently ignored. Operational prerequisite (document next to the config): the BOT must have
read_write on the target collection (collections.add_user — client-bead runbook step 3).

## Daemon flow (finalize, success path, after summary/tasks/question handling)

Per entry (≤3, in file order): resolve target collection (override or default) → resolve
parent_url if set (its failure fails ONLY that entry) → read + cap content →
CreateDocument{Title, CollectionID, ParentDocumentID, Text: content, Publish: true} → record
{Title, absURL = cfg base_url + doc.URL} or {Title, err}.

- Card comment (goes through the existing markdownToHTML comment path):
      published to Yonote:
      - <Title> → <abs url>
      - <Title> → FAILED: <message>
- appendEvent "yonote_published" {"ok": n, "failed": m}.
- Publish failures NEVER change the run outcome — the run already succeeded; publication is a
  side effect. Operator retries by re-running, or publishes manually from the archived tar.gz
  (the content survives there by construction).
- Idempotency (DECISION): re-running a card re-publishes and creates a NEW doc. Accepted for v1 —
  re-runs are rare, docs are cheap, and dedup would need a doc-id echo channel; revisit only if it
  annoys in practice (then: UpdateDocument by echoed id).

## Agent contract (role-prompt snippet, config-side; document in deploy notes)

    To publish a document to Yonote: write markdown to .task/publish/<name>.md and declare it in
    .task/publish.json as {"documents":[{"title":"…","file":"publish/<name>.md"}]}. Publication
    happens AFTER your run succeeds; resulting links are posted on the task card.

## Tests

- reader: absent → nil; malformed → tasks.json-parity bounce; >3 entries; empty title; path
  guards (absolute, .., symlink escape); oversize file.
- finalize with fake yonote writer (interface seam: CreateDocument + DocumentInfo): 2 ok + 1 fail
  → comment body lines, event payload, run outcome unchanged; lane-off (no collection id) →
  "publishing not configured" per entry; parent_url resolve failure isolates the entry;
  collection_id override honored.
- prepareTaskDir clears publish.json + the publish/ dir between attempts.

wave 2.5 — implement after feat/wave2-archive-links merges. Depends on: internal/yonote client
bead (CreateDocument/DocumentInfo), materialization bead (yonote config block + prepareTaskDir
channel-clearing site).

  ROLLOUT LIVE-SMOKE CHECKLIST (from wave-2.5 implementer, against            
  bigbes.yonote.ru after deploy): 1) mint bot per ah-gxa runbook (POST        
  /api/v2/bots + token, collections.add_user grant — grant call is spec-only, 
  NOT live-verified), AuthInfo under bot token must show IsBot=true (daemon   
  WARNs at startup otherwise); 2) documents.create with parentDocumentId      
  (child nesting unverified live) + bot WRITE rights on publish_collection_id 
  + publish:true attribution to bot; 3) archived-doc export ((archived) marker
  path); 4) ExportMarkdown empty-string cases (API-created never-edited draft,
  database-type doc) fall back to .text; 5) comments.create/list/resolve field
  names (only Q&A bead ah-ptu uses them). SEMANTICS NOTE: publish fires on    
  ROUTED successful runs too (inside firstFinalize&&success before maybeRoute)
  — a design stage with publish.json publishes before routing to review;      
  intentional. publish_collection_id (UUID) must be chosen by operator at     
  config staging.                                                             



DEPENDS ON
  → ✓ ah-2lh: Claim-time Yonote artifact materialization into .task/artifacts/ + prompt manifest ● P2
  → ✓ ah-gxa: internal/yonote: light API client (doc resolve/export, create, comments; bot-token auth) ● P2

BLOCKS
  ← ○ ah-ptu: Yonote Q&A bot loop: poll doc comments, answer via board tasks (post-wave-2.5) ● P3

ROLLOUT FACTS (2026-07-18, live-verified): bot agenthub id=34fbc9a3-ec75-4722-a01f-805db3f3ff1b (v2 create needs username field — used bigbes@gmail.com); token agent-1-daemon installed as YONOTE_TOKEN in /etc/agent-hub/env; auth.info isBot=true CONFIRMED; collections.add_user CONFIRMED; Agents collection 8656642e-0297-4d69-b6fb-4246517a015b = publish_collection_id, bot read_write. CAVEAT: bot sees ALL team-default-readable collections (not grant-scoped) — operator may tighten per-collection perms in UI. Config staging after CI deploy: yonote{base_url: https://bigbes.yonote.ru, token: ${YONOTE_TOKEN}, publish_collection_id: 8656642e-0297-4d69-b6fb-4246517a015b}.