+`;
+```
+
+- [ ] **Step 5: Run focused tests**
+
+Run:
+
+```bash
+UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/test_ui.py tests/test_api.py -q
+```
+
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/zotero_kb/templates/index.html
+git commit -m "feat: switch import modal to direct-item selection"
+```
+
+### Task 4: Add Delayed Abstract Preview And Touch Fallback
+
+**Files:**
+- Modify: `src/zotero_kb/templates/index.html`
+- Test: `tests/test_ui.py`
+
+- [ ] **Step 1: Add preview helpers**
+
+Add these helpers near the modal item rendering code:
+
+```javascript
+function clearAbstractPreviewTimer() {
+ if (state.hoverTimerId !== null) {
+ window.clearTimeout(state.hoverTimerId);
+ state.hoverTimerId = null;
+ }
+}
+
+function cancelAbstractPreview() {
+ clearAbstractPreviewTimer();
+ state.hoveredItemKey = null;
+ state.previewItemKey = null;
+ elements.previewPopover.hidden = true;
+ elements.previewPopover.textContent = "";
+}
+
+function showAbstractPreview(item, target) {
+ clearAbstractPreviewTimer();
+ const abstract = typeof item.abstract === "string" ? item.abstract.trim() : "";
+ if (!abstract) {
+ cancelAbstractPreview();
+ return;
+ }
+ state.previewItemKey = item.item_key;
+ elements.previewPopover.textContent = abstract;
+ elements.previewPopover.hidden = false;
+}
+
+function scheduleAbstractPreview(item, target) {
+ const abstract = typeof item.abstract === "string" ? item.abstract.trim() : "";
+ if (!abstract) {
+ return;
+ }
+ cancelAbstractPreview();
+ state.hoveredItemKey = item.item_key;
+ state.hoverTimerId = window.setTimeout(() => {
+ if (state.hoveredItemKey === item.item_key) {
+ showAbstractPreview(item, target);
+ }
+ }, ABSTRACT_PREVIEW_DELAY_MS);
+}
+```
+
+- [ ] **Step 2: Wire preview behavior into item rows**
+
+Bind these events in `renderCollectionItems()`:
+
+```javascript
+checkbox.addEventListener("change", () => {
+ cancelAbstractPreview();
+ toggleItemSelection(item.item_key);
+});
+
+titleButton.addEventListener("mouseenter", () => scheduleAbstractPreview(item, titleButton));
+titleButton.addEventListener("mouseleave", cancelAbstractPreview);
+
+detailsButton.addEventListener("click", (event) => {
+ event.preventDefault();
+ if (state.previewItemKey === item.item_key && !elements.previewPopover.hidden) {
+ cancelAbstractPreview();
+ return;
+ }
+ showAbstractPreview(item, detailsButton);
+});
+```
+
+Also add:
+
+```javascript
+elements.collectionItems.addEventListener("scroll", cancelAbstractPreview);
+```
+
+and call `cancelAbstractPreview()` inside:
+
+- `loadCollectionItems()`
+- `toggleItemSelection()`
+- `clearSelectedItems()`
+- `importSelectedItems()`
+- `openImportModal()`
+- `closeImportModal()`
+
+- [ ] **Step 3: Add compact-row and preview styles**
+
+Add:
+
+```css
+.collection-item {
+ display: grid;
+ grid-template-columns: auto minmax(0, 1fr);
+ gap: 0.75rem;
+ align-items: center;
+ padding: 0.75rem 0.9rem;
+ border: 1px solid var(--line);
+ border-radius: 14px;
+ background: rgba(255, 255, 255, 0.72);
+}
+.item-row-body {
+ display: flex;
+ align-items: center;
+ gap: 0.55rem;
+ min-width: 0;
+}
+.title-button {
+ flex: 1;
+ min-width: 0;
+ padding: 0;
+ border: 0;
+ border-radius: 0;
+ background: transparent;
+ color: var(--ink);
+ text-align: left;
+ font-weight: 600;
+}
+.details-button {
+ width: 2.2rem;
+ min-width: 2.2rem;
+ padding: 0.45rem 0;
+}
+.preview-popover {
+ position: fixed;
+ z-index: 60;
+}
+```
+
+- [ ] **Step 4: Run the UI test and full suite**
+
+Run:
+
+```bash
+UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/test_ui.py::test_index_contains_import_modal_controls -v
+UV_CACHE_DIR=/tmp/uv-cache uv run pytest -q
+```
+
+Expected:
+
+- first command: PASS
+- second command: all tests PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/zotero_kb/templates/index.html tests/test_ui.py
+git commit -m "feat: add delayed preview to fullscreen import modal"
+```
+
+### Task 5: Update The User Walkthrough
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Replace the old inline-import instructions**
+
+Replace the current import walkthrough bullets with:
+
+```md
+5. 在左侧点击 `导入文献`
+
+- 先选择一个项目
+- 点击 `导入文献` 打开全屏导入界面
+- 左侧点击一个 Zotero collection
+- 右侧会显示该 collection 直接包含的文献
+- 逐篇勾选需要导入的文献
+- 点击顶部 `导入所选`
+- 鼠标悬停标题 3 秒会显示摘要预览
+- 在窄屏或不方便 hover 的场景下，可点击 `i` 按钮查看摘要
+```
+
+- [ ] **Step 2: Run the full test suite**
+
+Run:
+
+```bash
+UV_CACHE_DIR=/tmp/uv-cache uv run pytest -q
+```
+
+Expected: PASS
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: describe fullscreen import modal flow"
+```
+
+## Self-Review Checklist
+
+- Spec coverage:
+ - full-screen modal shell: Task 2
+ - direct-item-only collection loading: Task 3
+ - one-by-one selection semantics: Task 3
+ - delayed abstract preview and details-button fallback: Task 4
+ - updated user walkthrough: Task 5
+- Placeholder scan:
+ - no `TODO`, `TBD`, or vague “handle later” instructions remain
+- Type consistency:
+ - ids and helpers remain consistent across tasks:
+ - `open-import-modal-button`
+ - `import-modal`
+ - `import-modal-project-label`
+ - `modal-selected-count`
+ - `modal-clear-selection-button`
+ - `modal-import-selected-items-button`
+ - `modal-collection-tree`
+ - `modal-collection-items`
+ - `scheduleAbstractPreview`
+ - `cancelAbstractPreview`
+ - `showAbstractPreview`
diff --git a/docs/superpowers/plans/2026-04-15-zotero-collection-import-modal.md b/docs/superpowers/plans/2026-04-15-zotero-collection-import-modal.md
new file mode 100644
index 0000000..8c20696
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-15-zotero-collection-import-modal.md
@@ -0,0 +1,711 @@
+# Zotero Collection Import Modal Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the crowded inline Zotero importer with a modal-based importer that preserves session selection state, keeps rows title-only by default, and shows abstracts through delayed preview.
+
+**Architecture:** Keep the existing FastAPI backend and current collection/item endpoints unchanged. Refactor the single-page `index.html` template so the main page only renders an import trigger, while a hidden modal owns the collection tree, item list, sticky actions, and preview popover state. Reuse the existing in-page state object and fetch helpers, extending them for modal lifecycle and delayed preview behavior.
+
+**Tech Stack:** FastAPI, inline HTML/CSS/vanilla JavaScript, pytest
+
+---
+
+## File Structure
+
+- Modify: `src/zotero_kb/templates/index.html`
+ - Replace the inline importer markup with a single trigger button
+ - Add modal shell, overlay, sticky action bar, and abstract preview popover
+ - Update the in-page JavaScript state and event handlers for modal lifecycle and delayed preview
+- Modify: `tests/test_ui.py`
+ - Replace assertions for the old inline importer with assertions for the trigger button, modal shell, and preview hooks
+- Modify: `README.md`
+ - Update the UI walkthrough so it describes opening the import modal instead of using the inline importer
+
+### Task 1: Lock The Modal UI Contract In Tests
+
+**Files:**
+- Modify: `tests/test_ui.py`
+- Read: `src/zotero_kb/templates/index.html`
+
+- [ ] **Step 1: Write the failing test**
+
+Replace the existing inline-import assertions with this test body:
+
+```python
+from zotero_kb.api import create_app
+from zotero_kb.config import AppConfig
+
+
+def test_index_contains_import_modal_controls(tmp_path) -> None:
+ app = create_app(
+ AppConfig(
+ workspace_dir=tmp_path / "workspace",
+ zotero_data_dir=tmp_path / "zotero",
+ bridge_file=tmp_path / "bridge.json",
+ )
+ )
+
+ for route in app.routes:
+ if getattr(route, "path", None) == "/" and "GET" in getattr(route, "methods", set()):
+ html = route.endpoint()
+ break
+ else:
+ raise AssertionError("GET / route not found")
+
+ assert 'id="create-project-form"' in html
+ assert 'id="open-import-modal-button"' in html
+ assert 'id="import-modal"' in html
+ assert 'id="close-import-modal-button"' in html
+ assert 'id="modal-collection-tree"' in html
+ assert 'id="modal-collection-items"' in html
+ assert 'id="modal-selected-count"' in html
+ assert 'id="modal-select-descendants-button"' in html
+ assert 'id="modal-clear-selection-button"' in html
+ assert 'id="modal-import-selected-items-button"' in html
+ assert 'id="item-preview-popover"' in html
+ assert 'const ABSTRACT_PREVIEW_DELAY_MS = 3000;' in html
+ assert 'isImportModalOpen: false' in html
+ assert 'id="recommend-form"' in html
+ assert 'id="plan-form"' in html
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/test_ui.py::test_index_contains_import_modal_controls -v
+```
+
+Expected: FAIL because the template still contains `collection-tree`, `collection-items`, and the old inline action ids instead of the modal ids.
+
+- [ ] **Step 3: Update the test file**
+
+Make `tests/test_ui.py` exactly:
+
+```python
+from zotero_kb.api import create_app
+from zotero_kb.config import AppConfig
+
+
+def test_index_contains_import_modal_controls(tmp_path) -> None:
+ app = create_app(
+ AppConfig(
+ workspace_dir=tmp_path / "workspace",
+ zotero_data_dir=tmp_path / "zotero",
+ bridge_file=tmp_path / "bridge.json",
+ )
+ )
+
+ for route in app.routes:
+ if getattr(route, "path", None) == "/" and "GET" in getattr(route, "methods", set()):
+ html = route.endpoint()
+ break
+ else:
+ raise AssertionError("GET / route not found")
+
+ assert 'id="create-project-form"' in html
+ assert 'id="open-import-modal-button"' in html
+ assert 'id="import-modal"' in html
+ assert 'id="close-import-modal-button"' in html
+ assert 'id="modal-collection-tree"' in html
+ assert 'id="modal-collection-items"' in html
+ assert 'id="modal-selected-count"' in html
+ assert 'id="modal-select-descendants-button"' in html
+ assert 'id="modal-clear-selection-button"' in html
+ assert 'id="modal-import-selected-items-button"' in html
+ assert 'id="item-preview-popover"' in html
+ assert 'const ABSTRACT_PREVIEW_DELAY_MS = 3000;' in html
+ assert 'isImportModalOpen: false' in html
+ assert 'id="recommend-form"' in html
+ assert 'id="plan-form"' in html
+```
+
+- [ ] **Step 4: Run test to verify it still fails for the right reason**
+
+Run:
+
+```bash
+UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/test_ui.py::test_index_contains_import_modal_controls -v
+```
+
+Expected: FAIL on missing modal ids in `index.html`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/test_ui.py
+git commit -m "test: define modal import ui contract"
+```
+
+### Task 2: Replace The Inline Importer Markup With A Modal Shell
+
+**Files:**
+- Modify: `src/zotero_kb/templates/index.html`
+- Test: `tests/test_ui.py`
+
+- [ ] **Step 1: Write the failing implementation target**
+
+In `src/zotero_kb/templates/index.html`, replace the old inline import section:
+
+```html
+
+
从 Zotero 导入
+
按当前 Zotero collection 结构浏览，选择目录后批量导入该目录及子目录的文献。
+
+
+
+ Collections
+
+
+
+ Collection Items
+
+
+
+
已选 0 篇
+
+
+
+
+
+
+```
+
+with a trigger plus modal shell:
+
+```html
+
+
导入文献
+
打开子界面浏览 Zotero collection 树，再批量导入到当前项目。
+
+
+
+
+
+
+
+
+
Import From Zotero
+
未选择项目
+
+
+
已选 0 篇
+
+
+
+
+
+
+ Collections
+
+
+
+ Collection Items
+
+
+
+
+
+
+
+```
+
+- [ ] **Step 2: Run the UI test to verify the markup is still missing**
+
+Run:
+
+```bash
+UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/test_ui.py::test_index_contains_import_modal_controls -v
+```
+
+Expected: FAIL until the new markup and ids are present.
+
+- [ ] **Step 3: Add the modal CSS and markup**
+
+In the `
@@ -371,36 +422,27 @@