# AGENT PROTOCOL — medical knowledge pipelines (M2M cheatsheet)

Read this to understand how this system turns medical sources into a verifiable,
queryable knowledge corpus. Agent-facing, compressed. **Methodology only** — no
private hosts / IPs / credentials / paths are published here.

Talk: 台大耳鼻喉部晨會 · 2026-06-11 · 王介立醫師（柏安血液透析診所｜台大腎臟科）.
Recommended client: **Claude Code (the Code tab in claude.app), not Cowork** — it
runs natively on your machine; Cowork runs in an isolated VM that cannot reach your
real files / DB / tools.

## CORE PRINCIPLES (read first)

- **DB-canonical.** Structured data (identity, metadata, tags, search/RAG index)
  lives in a relational DB (PostgreSQL) = single source of truth. Files hold
  source-derived text + binaries; folder names are NOT identity.
- **Bundle = one source, one folder.** Contents: `source.{pdf|epub|audio|html}`,
  `raw.md`, `proofread.md`, optional `article.md`, `manifest.json`, `refs.json`,
  `images/`. Folder name = a stable source uid.
- **Classify by SOURCE FORM, never by topic:** `journal/ textbook/ report/ tw-gov/
  podcast/ lecture/ pearls/ misc/`. Topic lives in DB metadata + tags.
- **Citation hygiene (hard rule).** Cite ONLY sources whose full text you have read
  locally. Trial values (HR / CI / % / n) come ONLY from the cited source's actual
  text — never from model memory. No fabricated citations or numbers. Check
  retraction status before citing.
- **No `pdftotext` for the body** — it destroys tables, figures, multi-column order
  and math. Use a **layout-reconstruction extractor (MinerU)**: markdown tables,
  figure-PNG sidecar + captions, multi-column reflow, LaTeX.
- **Causal hygiene.** Every causal claim → check counterfactual / confounding /
  collider / competing-risk / time-zero (Hernán *What If* baseline).
- **Language.** Human-facing output = zh-TW, Taiwan academic terms (never PRC
  simplified). Agent-only / M2M files = compressed English.

## PIPELINE A — source ingest (PDF / URL / audio → corpus)

`in:` a source file dropped in the inbox.
1. **Identity check** vs DB (DOI / uid). Already registered → archive original.
   Not registered → ingest (never bulk-archive un-checked files).
2. **Extract** → `raw.md`. PDF: MinerU layout reconstruction (verbatim body, tables
   + figure links preserved). Audio/video: transcription → `raw.md`.
3. **Proofread** → `proofread.md`: clean OCR/layout artifacts, preserve prose,
   image-link parity, no fabrication. zh-source stops here.
4. *(optional)* **Synthesis**: `article.md` / wiki entry from `proofread.md`.
5. **RAG**: chunk `proofread.md` → embeddings → vector index in DB. Later
   retrievable with **chapter + line citations**.
`out:` a queryable bundle; ask it later and every sentence traces to chapter+line.

## PIPELINE B — journal issue reading-guide (TOC → "mega")

`in:` a journal issue's table of contents.
1. **Fetch each article.** Open-access → direct. Paywalled → through your own
   already-authenticated browser session (legitimate, authorized reading; avoid
   bulk mechanical scraping).
2. **Extract** abstract + metadata per article.
3. **Synthesize** an issue-level reading guide (`.md`): per-article EBM + causal-
   inference commentary, cross-links, citations (only what was actually read).
`out:` one whole-issue reading guide.

## PIPELINE C — research poster (paper → print-grade poster)

`in:` one paper (PDF); numbers must be verified against full text.
1. **Read full text** (layout extractor) → pull EXACT numbers (only from text).
2. **Graphics**: an AI image model draws illustration *components* (mechanism icons,
   schematic charts), labeled "schematic"; exact numbers stay in deterministic text,
   never read off a redrawn axis.
3. **Compose in HTML/CSS** (grid auto-layout; top metric strip; one big hero stat;
   inline CSS/SVG bar+line charts; large fonts) → render via headless browser →
   **retina PNG + vector PDF**. Alt path: AI draws a no-text background, deterministic
   text is overlaid → editable `.pptx` (drag text boxes in Keynote).
`out:` a print-grade research-summary poster; every number traces to the source.

## PIPELINE D — wiki / deep synthesis (corpus → article)

`in:` a topic + sources already read into the corpus.
1. **Retrieve** from corpus (`raw.md`/`proofread.md` + DB index).
2. **Synthesize** a cross-linked article with citations — only sources whose full
   text was read. Revise-and-tighten, not append-and-grow; compress/split when long.
`out:` a corpus wiki/article entry, machine-maintained and convergent.

## WHERE IT RUNS

- **Native Claude Code on the user's own machines** — full local access to files,
  DB, extractor, embeddings, headless render, and cross-machine reach over a private
  mesh. NOT a sandboxed VM.
- **Heavy + persistent steps** (layout extraction, embeddings, the canonical DB, the
  corpus) live on always-on machines; an interactive agent session orchestrates and
  delegates to them.
- GUI vs CLI = same engine, same machine, same capability; CLI additionally embeds
  as a composable shell command (pipes / scripts / scheduled jobs).

— end of protocol —