diff --git a/docs/mlkem_top_rtl.svg b/docs/mlkem_top_rtl.svg
new file mode 100644
index 0000000..a7057f5
--- /dev/null
+++ b/docs/mlkem_top_rtl.svg
@@ -0,0 +1,229 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="1480" height="1020" viewBox="0 0 1480 1020" font-family="'DejaVu Sans Mono','Consolas',monospace">
+  <defs>
+    <marker id="arr" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L7,3 L0,6 z" fill="#444"/>
+    </marker>
+    <marker id="arrB" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L7,3 L0,6 z" fill="#1763a6"/>
+    </marker>
+    <marker id="arrR" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L7,3 L0,6 z" fill="#a33"/>
+    </marker>
+    <style>
+      .lbl{font-size:13px;fill:#111;}
+      .sub{font-size:10.5px;fill:#555;}
+      .port{font-size:11px;fill:#1763a6;}
+      .net{font-size:10px;fill:#666;}
+      .ttl{font-size:14px;font-weight:bold;fill:#111;}
+      .big{font-size:20px;font-weight:bold;fill:#111;}
+      .wire{stroke:#444;stroke-width:1.4;fill:none;}
+      .wireB{stroke:#1763a6;stroke-width:1.4;fill:none;}
+      .wireR{stroke:#a33;stroke-width:1.4;fill:none;}
+    </style>
+  </defs>
+
+  <rect x="0" y="0" width="1480" height="1020" fill="#fbfbf9"/>
+  <text x="40" y="34" class="big">mlkem_top  —  ML-KEM KeyGen / Encaps / Decaps  (op_i: 0/1/2, runtime k_i)</text>
+  <text x="40" y="54" class="sub">实线=数据/系数通路   蓝=BRAM 端口   红=隐式拒绝 / 共享 keccak 仲裁   方框内为 RTL 实例名 / 信号名</text>
+
+  <!-- ================= INPUTS (left) ================= -->
+  <rect x="24" y="90" width="200" height="318" rx="7" fill="#eef4fb" stroke="#9bb8d6"/>
+  <text x="124" y="110" class="ttl" text-anchor="middle">输入端口</text>
+  <text x="36" y="134" class="port">k_i[2:0]  op_i[1:0]</text>
+  <text x="36" y="154" class="port">start_i</text>
+  <text x="36" y="178" class="lbl">d_i[255:0]</text>
+  <text x="36" y="194" class="sub">KeyGen 种子 d</text>
+  <text x="36" y="214" class="lbl">z_i[255:0]</text>
+  <text x="36" y="230" class="sub">隐式拒绝种子 z</text>
+  <text x="36" y="250" class="lbl">msg_i[255:0]</text>
+  <text x="36" y="266" class="sub">Encaps 消息 m</text>
+  <line x1="36" y1="280" x2="212" y2="280" stroke="#9bb8d6" stroke-dasharray="3 3"/>
+  <text x="36" y="300" class="port">ek_in_*  (Encaps)</text>
+  <text x="36" y="316" class="sub">公钥 ek → u_ek_bram</text>
+  <text x="36" y="338" class="port">dk_in_*  (Decaps)</text>
+  <text x="36" y="354" class="sub">私钥 dk → 各区路由</text>
+  <text x="36" y="376" class="port">c_in_*   (Decaps)</text>
+  <text x="36" y="392" class="sub">密文 c → u_c_in_bram</text>
+
+  <!-- ================= FSM / CONTROL ================= -->
+  <rect x="270" y="90" width="250" height="220" rx="8" fill="#fff3e0" stroke="#e0a440"/>
+  <text x="395" y="112" class="ttl" text-anchor="middle">控制 FSM  (st, st_next)</text>
+  <text x="284" y="136" class="sub">KeyGen: G→A→C→N→M→E→H</text>
+  <text x="284" y="153" class="sub">Encaps: ENC_H→G→LOAD→A→TDEC</text>
+  <text x="284" y="167" class="sub">  →C→N→U→C1→E2MV→V→C2</text>
+  <text x="284" y="184" class="sub">Decaps: DEC_LOAD→DECOMP→SDEC</text>
+  <text x="284" y="198" class="sub">  →NTT→W→MENC→G→J→(重加密)→CMP</text>
+  <line x1="284" y1="210" x2="506" y2="210" stroke="#e0a440" stroke-dasharray="3 3"/>
+  <text x="284" y="230" class="lbl">相位选择 sel_*</text>
+  <text x="284" y="246" class="sub">sel_sha3 / sel_snt / sel_cbd</text>
+  <text x="284" y="266" class="lbl">op_r  k_r  (start 锁存)</text>
+  <text x="284" y="286" class="lbl">busy_o = (st≠IDLE)</text>
+  <text x="284" y="302" class="lbl">done_o = (st==DONE)</text>
+
+  <!-- registers -->
+  <rect x="270" y="326" width="250" height="150" rx="8" fill="#fdeef0" stroke="#d68a96"/>
+  <text x="395" y="346" class="ttl" text-anchor="middle">状态寄存器 (256b)</text>
+  <text x="284" y="368" class="lbl">rho_r / sigma_r   <tspan class="sub">(ρ,σ=G)</tspan></text>
+  <text x="284" y="388" class="lbl">m_r   <tspan class="sub">m / Decaps m'</tspan></text>
+  <text x="284" y="408" class="lbl">r_r   <tspan class="sub">PRF 种子 r / r'</tspan></text>
+  <text x="284" y="428" class="lbl">hek_r <tspan class="sub">H(ek)</tspan>   z_r <tspan class="sub">z</tspan></text>
+  <text x="284" y="448" class="lbl">ss_r  <tspan class="sub">K / K'</tspan>   kbar_r <tspan class="sub">K̄=J(z‖c)</tspan></text>
+  <text x="284" y="468" class="lbl">dec_reject <tspan class="sub">c'≠c 标志</tspan></text>
+
+  <!-- ================= SHARED KECCAK ================= -->
+  <rect x="560" y="92" width="300" height="196" rx="8" fill="#fbecec" stroke="#c98b8b"/>
+  <text x="710" y="114" class="ttl" text-anchor="middle">共享 Keccak (单核 + 相位 mux)</text>
+  <rect x="586" y="128" width="248" height="44" rx="6" fill="#fff" stroke="#c98b8b"/>
+  <text x="710" y="155" class="lbl" text-anchor="middle">u_keccak  (keccak_core)</text>
+  <text x="586" y="196" class="net">kc_state_i_mux / kc_valid_i_mux  ◄ 3-way</text>
+  <text x="586" y="214" class="net">kc_state_o / kc_valid_o  ► 门控广播</text>
+  <text x="586" y="236" class="net">kc_valid_o_sha3 · _snt · _cbd</text>
+  <text x="586" y="258" class="sub">G/H/J、SampleNTT、CBD 分时复用 1 个核</text>
+  <text x="586" y="276" class="sub">(相位互斥 → sel_sha3/snt/cbd 选通)</text>
+
+  <!-- ================= HASH ENGINE ================= -->
+  <rect x="560" y="312" width="300" height="120" rx="8" fill="#eef7ee" stroke="#86b886"/>
+  <text x="710" y="334" class="ttl" text-anchor="middle">u_sha3  (sha3_top_shared)</text>
+  <text x="574" y="356" class="lbl">SHA3-512  G(·) → ρ‖σ / K‖r / K'‖r'</text>
+  <text x="574" y="376" class="lbl">SHA3-256  H(ek)  (多块吸收)</text>
+  <text x="574" y="396" class="lbl">SHAKE-256 J(z‖c) → K̄  (多块)</text>
+  <text x="574" y="416" class="sub">mb_en / mb_block_i 多块；mode 选 G/H/J</text>
+
+  <!-- ================= SAMPLERS ================= -->
+  <rect x="560" y="456" width="300" height="76" rx="8" fill="#eef7ee" stroke="#86b886"/>
+  <text x="710" y="478" class="ttl" text-anchor="middle">u_snt (sample_ntt_sync_shared)</text>
+  <text x="574" y="498" class="lbl">Â[i][j] = SampleNTT(ρ‖j‖i)  → bank_a</text>
+  <text x="574" y="518" class="sub">snt_coeff / snt_valid / snt_last</text>
+
+  <rect x="560" y="548" width="300" height="76" rx="8" fill="#eef7ee" stroke="#86b886"/>
+  <text x="710" y="570" class="ttl" text-anchor="middle">u_cbd (sample_cbd_sync_shared)</text>
+  <text x="574" y="590" class="lbl">CBD_η: s/e (KeyGen), y/e1/e2 (Encaps)</text>
+  <text x="574" y="610" class="sub">cbd_coeff → cbd_modq → bank_se / bank_t</text>
+
+  <!-- ================= ARITH ENGINES ================= -->
+  <rect x="560" y="648" width="300" height="80" rx="8" fill="#e9f1f7" stroke="#7fa8cc"/>
+  <text x="710" y="670" class="ttl" text-anchor="middle">u_ntt  (ntt_core)</text>
+  <text x="574" y="690" class="lbl">前向 NTT(mode0) / INTT(mode1, ×3303)</text>
+  <text x="574" y="710" class="sub">ntt_in ◄ bank_se/bank_t；ntt_coeff ► 写回</text>
+
+  <rect x="560" y="744" width="300" height="80" rx="8" fill="#e9f1f7" stroke="#7fa8cc"/>
+  <text x="710" y="766" class="ttl" text-anchor="middle">u_pmul (poly_mul_sync)</text>
+  <text x="574" y="786" class="lbl">NTT 域逐点乘 Σ Â∘ŝ / Âᵀ∘ŷ / t̂∘ŷ / ŝ∘û</text>
+  <text x="574" y="806" class="sub">pm_a_in ◄ bank_a, pm_b_in ◄ bank_se → pm_coeff</text>
+
+  <rect x="560" y="840" width="300" height="80" rx="8" fill="#e9f1f7" stroke="#7fa8cc"/>
+  <text x="710" y="862" class="ttl" text-anchor="middle">u_comp (comp_decomp_sync)</text>
+  <text x="574" y="882" class="lbl">Compress_d (mode0) / Decompress_d (mode1)</text>
+  <text x="574" y="902" class="sub">Encaps C1/C2 压缩；Decaps DECOMP 解压</text>
+
+  <!-- accumulate / mod-add inline note -->
+  <rect x="270" y="500" width="250" height="120" rx="8" fill="#f4f0fa" stroke="#a78bc9"/>
+  <text x="395" y="522" class="ttl" text-anchor="middle">顶层内联运算</text>
+  <text x="284" y="544" class="sub">modQ 累加 (ST_M / U / V / W)</text>
+  <text x="284" y="562" class="sub">m_accq · u_accq · u_uq · u_vq · u_wq</text>
+  <text x="284" y="582" class="sub">byteEncode12 (ST_E)  e_wbyte</text>
+  <text x="284" y="600" class="sub">byteDecode12 (TDEC/SDEC) td_c0/td_c1</text>
+  <text x="284" y="618" class="sub">bit-packer cp_* / 解包 dec_* / 比较 cmp_*</text>
+
+  <!-- ================= STORAGE BANKS (right) ================= -->
+  <rect x="900" y="90" width="340" height="470" rx="8" fill="#eef4fb" stroke="#9bb8d6"/>
+  <text x="1070" y="112" class="ttl" text-anchor="middle">系数存储库 (sd_bram, 1R/1W, 1拍读)</text>
+
+  <rect x="922" y="128" width="296" height="92" rx="6" fill="#fff" stroke="#9bb8d6"/>
+  <text x="934" y="148" class="lbl">u_bank_a  <tspan class="sub">12×4096 (PA_AW=12)</tspan></text>
+  <text x="934" y="167" class="sub">Â[i][j] 矩阵；Decaps 中转 ŝ / e2 / v'</text>
+  <text x="934" y="185" class="net">ba_rd_addr/ba_rd_data  ba_we/ba_wa/ba_wd</text>
+  <text x="934" y="205" class="net">slot: i*K+j</text>
+
+  <rect x="922" y="230" width="296" height="92" rx="6" fill="#fff" stroke="#9bb8d6"/>
+  <text x="934" y="250" class="lbl">u_bank_se <tspan class="sub">12×2048 (PSE_AW=11)</tspan></text>
+  <text x="934" y="269" class="sub">ŝ/ê (KeyGen) · ŷ (Encaps) · û (Decaps)</text>
+  <text x="934" y="287" class="net">bse_rd_addr/bse_rd_data  bse_we/wa/wd</text>
+  <text x="934" y="307" class="net">slot_s=K²  slot_e=K²+K</text>
+
+  <rect x="922" y="332" width="296" height="92" rx="6" fill="#fff" stroke="#9bb8d6"/>
+  <text x="934" y="352" class="lbl">u_bank_t  <tspan class="sub">12×1024 (PT_AW=10)</tspan></text>
+  <text x="934" y="371" class="sub">t̂ · psum · Encaps v · Decaps w</text>
+  <text x="934" y="389" class="net">bt_rd_addr/bt_rd_data  bt_we/wa/wd</text>
+  <text x="934" y="409" class="net">slot_t=K²+2K  UPSUM=rel1</text>
+
+  <rect x="922" y="434" width="143" height="58" rx="6" fill="#fff" stroke="#9bb8d6"/>
+  <text x="934" y="453" class="lbl">u_ek_bram</text>
+  <text x="934" y="469" class="sub">8×2048</text>
+  <text x="934" y="485" class="sub">ek=Enc12(t̂)‖ρ</text>
+
+  <rect x="1075" y="434" width="143" height="58" rx="6" fill="#fff" stroke="#9bb8d6"/>
+  <text x="1087" y="453" class="lbl">u_dkp_bram</text>
+  <text x="1087" y="469" class="sub">8×2048</text>
+  <text x="1087" y="485" class="sub">dk_pke=Enc12(ŝ)</text>
+
+  <rect x="922" y="500" width="143" height="50" rx="6" fill="#fff" stroke="#9bb8d6"/>
+  <text x="934" y="519" class="lbl">u_ct_bram</text>
+  <text x="934" y="537" class="sub">8×2048  c / c'</text>
+
+  <rect x="1075" y="500" width="143" height="50" rx="6" fill="#fff" stroke="#9bb8d6"/>
+  <text x="1087" y="519" class="lbl">u_c_in_bram</text>
+  <text x="1087" y="537" class="sub">8×2048  输入 c</text>
+
+  <!-- ================= OUTPUTS ================= -->
+  <rect x="900" y="590" width="340" height="330" rx="8" fill="#eef9ee" stroke="#86b886"/>
+  <text x="1070" y="612" class="ttl" text-anchor="middle">输出 / 回读</text>
+  <text x="914" y="638" class="lbl">ss_o = dec_reject ? kbar_r : ss_r</text>
+  <text x="914" y="654" class="sub">共享密钥 K (Encaps/Decaps)</text>
+  <line x1="914" y1="666" x2="1226" y2="666" stroke="#86b886" stroke-dasharray="3 3"/>
+  <text x="914" y="688" class="lbl">dbg_ct_o ◄ u_ct_bram</text>
+  <text x="914" y="704" class="sub">密文 c 逐字节</text>
+  <text x="914" y="726" class="lbl">dbg_byte_o ◄ ek / dk_pke</text>
+  <text x="914" y="742" class="sub">sel: 0=ek_bram 1=dkp_bram</text>
+  <text x="914" y="764" class="lbl">dbg_dk_o ◄ dk_pke‖ek‖H(ek)‖z</text>
+  <text x="914" y="780" class="sub">完整 dk 逐字节 (1632/2400/3168B)</text>
+  <text x="914" y="802" class="lbl">dbg_coeff_o ◄ bank_a/se/t</text>
+  <text x="914" y="818" class="sub">按 dbg_slot_i 选库, 系数回读</text>
+  <line x1="914" y1="830" x2="1226" y2="830" stroke="#86b886" stroke-dasharray="3 3"/>
+  <text x="914" y="852" class="sub">调试抽头: dbg_rho_o dbg_sigma_o</text>
+  <text x="914" y="868" class="sub">  dbg_r_o dbg_hek_o dbg_mprime_o</text>
+  <text x="914" y="884" class="sub">  dbg_kbar_o dbg_decz_o dbg_dech_o</text>
+  <text x="914" y="906" class="sub">done_o / busy_o</text>
+
+  <!-- ============ WIRES ============ -->
+  <!-- inputs -> FSM/regs -->
+  <path class="wire" d="M224,150 L268,150" marker-end="url(#arr)"/>
+  <path class="wire" d="M224,182 L268,182 L268,378" marker-end="url(#arr)"/>
+  <path class="wire" d="M224,218 L256,218 L256,440 L268,440" marker-end="url(#arr)"/>
+  <path class="wire" d="M224,254 L260,254 L260,388 L268,388" marker-end="url(#arr)"/>
+
+  <!-- inputs(ek/dk/c) -> banks (blue) -->
+  <path class="wireB" d="M224,300 L240,300 L240,68 L1300,68 L1300,460 L1218,460" marker-end="url(#arrB)"/>
+  <path class="wireB" d="M224,338 L236,338 L236,72 L1296,72 L1296,463 L1218,463" marker-end="url(#arrB)"/>
+  <path class="wireB" d="M224,376 L232,376 L232,76 L1292,76 L1292,525 L1218,525" marker-end="url(#arrB)"/>
+
+  <!-- FSM sel -> keccak mux (red) -->
+  <path class="wireR" d="M520,230 L540,230 L540,180 L558,180" marker-end="url(#arrR)"/>
+  <!-- keccak <-> sha3/snt/cbd -->
+  <path class="wireR" d="M710,288 L710,310" marker-end="url(#arrR)"/>
+  <path class="wireR" d="M560,210 L546,210 L546,494 L558,494" marker-end="url(#arrR)"/>
+  <path class="wireR" d="M560,214 L544,214 L544,586 L558,586" marker-end="url(#arrR)"/>
+
+  <!-- regs <-> sha3 (rho/sigma/r/ss/kbar) -->
+  <path class="wire" d="M520,372 L536,372 L536,360 L558,360" marker-end="url(#arr)"/>
+  <path class="wire" d="M558,392 L538,392 L538,448 L520,448" marker-end="url(#arr)"/>
+
+  <!-- datapath engines -> banks (blue) -->
+  <path class="wireB" d="M860,494 L884,494 L884,174 L920,174" marker-end="url(#arrB)"/>
+  <path class="wireB" d="M860,590 L880,590 L880,276 L920,276" marker-end="url(#arrB)"/>
+  <path class="wireB" d="M860,688 L876,688 L876,378 L920,378" marker-end="url(#arrB)"/>
+  <!-- pmul reads bank_a/se -->
+  <path class="wireB" d="M920,200 L888,200 L888,772 L860,772" marker-end="url(#arrB)"/>
+  <path class="wireB" d="M920,300 L892,300 L892,776 L860,776" marker-end="url(#arrB)"/>
+  <!-- comp <-> ct/c_in -->
+  <path class="wireB" d="M860,884 L896,884 L896,524 L920,524" marker-end="url(#arrB)"/>
+
+  <!-- regs -> ss_o (red reject mux) -->
+  <path class="wireR" d="M520,448 L528,448 L528,948 L898,948 L898,634 L912,634" marker-end="url(#arrR)"/>
+
+  <!-- banks -> outputs (data already adjacent; show coeff readback) -->
+  <path class="wire" d="M1218,478 L1240,478 L1240,808 L1226,808" marker-end="url(#arr)"/>
+
+  <text x="40" y="1000" class="sub">注:同一套叶子算子 / 存储库被 KeyGen·Encaps·Decaps 三条数据通路按 FSM 相位分时复用;Decaps 重加密直接复用整条 Encaps 流水 (ENC_LOAD…ENC_C2)。</text>
+</svg>