At hackathon scale you embed once and query a thousand times, and the GPU sits right under the desk. So the embedding step lives in the same FastAPI process that serves search, and the index is a single Chroma collection on disk. The chunker walks each PDF with PyMuPDF, slides a 512-word window with 64-word overlap, and writes (arxiv_id, chunk_index, char_start, char_end) alongside every vector. Storing char offsets per chunk costs nothing during ingest and pays for itself the first time someone wants a citation badge that deep-links to the source PDF.

Two implementation gotchas were worth more time than the rest of the pipeline combined. Harrier expects an instruction prefix on every query ("Instruct: Given a scientific query, retrieve relevant paper passages\nQuery: "); without it the cosine scores collapse because the query vectors land in a different region of the space than the indexed chunks. And llama.cpp's batched embedding path errors on this model, so the script falls back to one create_embedding(text) call per chunk. Slower, reliable, and worth the warm-up time on the first /search request.

The Plate plugin in citation-suggest-kit.tsx tracks the active block in module-scope refs (no React re-renders on every keystroke). After 1.2 seconds of inactivity on a paragraph with at least 30 characters, the block text is sent to the FastAPI /search endpoint via a Next.js proxy that holds the shared secret. The top hit becomes a ghost-text pill anchored at the caret. Tab inserts it as a Plate citation inline element carrying the full search trace. Esc dismisses, and the plugin remembers the dismissed text in a Map<blockId, lastQueriedText> so it doesn't re-fire on the next keystroke that lands the cursor back on the block.

Three small behaviors took most of the time. The plugin re-checks refs.blockId and refs.blockText when the response comes back, so if the user kept typing while the request was in flight, the result is dropped and no ghost pill appears. The same memoization map prevents re-querying an unchanged paragraph after every cursor move. And when the top-k contains several closely-tied scores (top.score - score ≤ 0.08), Tab inserts up to maxInsert = 3 badges instead of one, because most paragraphs cite one paper but the ones that need a cluster really need a cluster.

The inserted citation node carries the entire search trace (query, latency, top-k candidates), so clicking the badge opens a popover that shows why the agent picked this paper. That trace is the affordance that makes auto-cite trustworthy enough to leave on while you write.

The moment a citation is accepted, the editor fires a ground_citation agent run with the inserted node's identity and the surrounding paragraph as a claim. Nia's document/agent endpoint reads the actual cited PDF and returns a structured verdict against a JSON schema we hand it. The browser is listening on the agent's SSE stream; when a finding event arrives with kind: 'grounded_citation', the verification driver finds the matching node by (arxivId, chunkIndex, searchedAt) (stable across Yjs reorderings) and merges the verdict into its verification field. The badge re-renders in place.

The schema we send is intentionally strict, so the agent has to answer the verification question rather than wax on. Page number and section path nullable, confidence bounded to [0, 1], exact quote required (with the contract that it must be verbatim, not paraphrased).

The bridge opens a Hocuspocus direct connection to the live document and mutates the Yjs fragment inside a Y.transact block, with the agent's identity stamped on the origin so undo and presence stay sane. It is a small Bun HTTP server with a deliberately small surface: discovery, snapshot, full state, edit, presence, and a dev-only repair endpoint. Edits are validated, applied as a single transaction, and broadcast through the same WebSocket every browser is already on.

Because the bridge is just HTTP and a documented op vocabulary, any agent can drive the document. The "Connect agent" dialog in the editor hands you a copy-paste prompt prefilled with this document's bridge URL, ID, headers, and op reference, ready to paste into Claude Code or ChatGPT. Within a minute of opening the dialog, you can have an external LLM rewriting your introduction in real time.

Hocuspocus is the only thing that owns presence. Browsers publish their cursors through the standard @platejs/yjs awareness binding. Agents publish through the bridge's POST /presence endpoint, which writes into the same awareness map from the bridge's openDirectConnection handle. The avatar stack in the top-right of the editor renders both the same way (a colored circle with initials, agents marked with a soft pulse ring).

The agent in literature_search.py is a planner-then-searcher with optional discovery. The planner uses gpt-4o-mini (cheap, fast, perfectly fine at this; the rest of the system uses Claude Sonnet 4 but the planner doesn't need it) to fan the topic out into 4 short sub-queries. Each sub-query gets its own Chroma top-k pass, and the results are merged best-per-paper so you don't see the same arXiv ID four times.

The interesting bit is discovery. If the user opts in, the agent also queries arXiv directly for fresh papers that aren't in the local Chroma yet. Each candidate is downloaded, chunked, embedded with Harrier, and inserted into the same collection during the run. By the time the search step runs, the new papers are queryable like everything else. Every step of the way (plan, discover, discover_ingest, search, rank, each finding) is published as an SSE event, so the agents panel renders the run live: planner queries appear, new papers download, the rankings update.

This is the AgentMail integration, and it is the feature that most concretely shows the value of the bridge: an external event becomes a document event with no human in the loop. The shipped UX is a paste-text form in the agents panel; the agent itself accepts both modes (paste-text or AgentMail by inbox_id+message_id), and the bridge end of the pipeline is identical either way.

The agent in review_response.py snapshots the doc, asks Claude Sonnet 4 to map the email into a structured action list ({kind, anchor_ref, replacement, rationale}), validates each anchor_ref against the snapshot (Claude doesn't get to invent block IDs), and posts each surviving action through the bridge as an addNote op with idempotency key review:{run_id}:{anchor_ref}:{kind}. Same key on retry, same response, no double-applied edits.

The crucial UX decision is that the agent never edits prose destructively. Every textual change goes in as an addNote with kind: 'suggestion', rendered in the editor as an accept/reject card anchored under the original block. It is the peer-review experience everyone already knows from Word, with an LLM as the proposer instead of a human.