@bohuyeshan/openagent-labforge-core 3.11.1 → 3.11.3

package/generated/skills-bundles/full/skills/research/document-authoring/auto-claude__paper-writing/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: "auto-claude/paper-writing"
+description: "Workflow 3: Full paper writing pipeline. Orchestrates paper-plan → paper-figure → paper-write → paper-compile → ULTRAWORK QA to go from a narrative report to a polished, submission-ready PDF. Use when user says \"写论文全流程\", \"write paper pipeline\", \"从报告到PDF\", \"paper writing\", or wants the complete paper generation workflow."
+argument-hint: ["narrative-report-path-or-topic"]
+allowed-tools: "Bash(*), Read, Write, Edit, Grep, Glob, Agent, Skill, mcp__codex__codex, mcp__codex__codex-reply"
+metadata:
+  category: "research/document-authoring"
+---
+
+# Workflow 3: Paper Writing Pipeline
+
+Orchestrate a complete paper writing workflow for: **$ARGUMENTS**
+
+## Overview
+
+This skill chains five sub-skills into a single automated pipeline:
+
+```
+/paper-plan → /paper-figure → /paper-write → /paper-compile → /ulw-loop
+  (outline)     (plots)        (LaTeX)        (build PDF)       (final QA + Oracle verify)
+```
+
+Each phase builds on the previous one's output. The final deliverable is a polished, reviewed `paper/` directory with LaTeX source and compiled PDF.
+
+## Constants
+
+- **VENUE = `ICLR`** — Target venue. Options: `ICLR`, `NeurIPS`, `ICML`. Affects style file, page limit, citation format.
+- **REVIEWER_MODEL = `gpt-5.4`** — Model used via Codex MCP for plan review, figure review, and writing review.
+- **AUTO_PROCEED = true** — Auto-continue between phases. Set `false` to pause and wait for user approval after each phase.
+
+> Override inline: `/paper-writing "NARRATIVE_REPORT.md" — venue: NeurIPS`
+
+## Inputs
+
+This pipeline accepts one of:
+
+1. **`NARRATIVE_REPORT.md`** (best) — structured research narrative with claims, experiments, results, figures
+2. **Research direction + experiment results** — the skill will help draft the narrative first
+3. **Existing `PAPER_PLAN.md`** — skip Phase 1, start from Phase 2
+
+The more detailed the input (especially figure descriptions and quantitative results), the better the output.
+
+## Pipeline
+
+### Phase 1: Paper Plan
+
+Invoke `/paper-plan` to create the structural outline:
+
+```
+/paper-plan "$ARGUMENTS"
+```
+
+**What this does:**
+- Parse NARRATIVE_REPORT.md for claims, evidence, and figure descriptions
+- Build a **Claims-Evidence Matrix** — every claim maps to evidence, every experiment supports a claim
+- Design section structure (5-8 sections depending on paper type)
+- Plan figure/table placement with data sources
+- Scaffold citation structure
+- GPT-5.4 reviews the plan for completeness
+
+**Output:** `PAPER_PLAN.md` with section plan, figure plan, citation scaffolding.
+
+**Checkpoint:** Present the plan summary to the user.
+
+```
+📐 Paper plan complete:
+- Title: [proposed title]
+- Sections: [N] ([list])
+- Figures: [N] auto-generated + [M] manual
+- Target: [VENUE], [PAGE_LIMIT] pages
+
+Shall I proceed with figure generation?
+```
+
+- **User approves** (or AUTO_PROCEED=true) → proceed to Phase 2.
+- **User requests changes** → adjust plan and re-present.
+
+### Phase 2: Figure Generation
+
+Invoke `/paper-figure` to generate data-driven plots and tables:
+
+```
+/paper-figure "PAPER_PLAN.md"
+```
+
+**What this does:**
+- Read figure plan from PAPER_PLAN.md
+- Generate matplotlib/seaborn plots from JSON/CSV data
+- Generate LaTeX comparison tables
+- Create `figures/latex_includes.tex` for easy insertion
+- GPT-5.4 reviews figure quality and captions
+
+**Output:** `figures/` directory with PDFs, generation scripts, and LaTeX snippets.
+
+> **Scope:** Auto-generates ~60% of figures (data plots, comparison tables). Architecture diagrams, pipeline figures, and qualitative result grids must be created manually and placed in `figures/` before proceeding. See `/paper-figure` SKILL.md for details.
+
+**Checkpoint:** List generated vs manual figures.
+
+```
+📊 Figures complete:
+- Auto-generated: [list]
+- Manual (need your input): [list]
+- LaTeX snippets: figures/latex_includes.tex
+
+[If manual figures needed]: Please add them to figures/ before I proceed.
+[If all auto]: Shall I proceed with LaTeX writing?
+```
+
+### Phase 3: LaTeX Writing
+
+Invoke `/paper-write` to generate section-by-section LaTeX:
+
+```
+/paper-write "PAPER_PLAN.md"
+```
+
+**What this does:**
+- Write each section following the plan, with proper LaTeX formatting
+- Insert figure/table references from `figures/latex_includes.tex`
+- Build `references.bib` from citation scaffolding
+- Clean stale files from previous section structures
+- Automated bib cleaning (remove uncited entries)
+- De-AI polish (remove "delve", "pivotal", "landscape"...)
+- GPT-5.4 reviews each section for quality
+
+**Output:** `paper/` directory with `main.tex`, `sections/*.tex`, `references.bib`, `math_commands.tex`.
+
+**Checkpoint:** Report section completion.
+
+```
+✍️ LaTeX writing complete:
+- Sections: [N] written ([list])
+- Citations: [N] unique keys in references.bib
+- Stale files cleaned: [list, if any]
+
+Shall I proceed with compilation?
+```
+
+### Phase 4: Compilation
+
+Invoke `/paper-compile` to build the PDF:
+
+```
+/paper-compile "paper/"
+```
+
+**What this does:**
+- `latexmk -pdf` with automatic multi-pass compilation
+- Auto-fix common errors (missing packages, undefined refs, BibTeX syntax)
+- Up to 3 compilation attempts
+- Post-compilation checks: undefined refs, page count, font embedding
+- Precise page verification via `pdftotext`
+- Stale file detection
+
+**Output:** `paper/main.pdf`
+
+**Checkpoint:** Report compilation results.
+
+```
+🔨 Compilation complete:
+- Status: SUCCESS
+- Pages: [X] (main body) + [Y] (references) + [Z] (appendix)
+- Within page limit: YES/NO
+- Undefined references: 0
+- Undefined citations: 0
+
+Shall I proceed with the ULTRAWORK final QA?
+```
+
+### Phase 5: ULTRAWORK Final QA
+
+Invoke `/ulw-loop` to do a final evidence-based QA pass:
+
+```
+/ulw-loop "Final QA for paper/: verify claims vs figures, references, and compile output" --max-iterations=2
+```
+
+**What this does (recommend 1-2 rounds):**
+
+- Verify claims vs figures and tables
+- Check references, citations, and build artifacts
+- Fix inconsistencies, missing evidence, and presentation gaps
+- Oracle verifies completion; if not verified, iterate
+
+**Output:** `paper/main.pdf` plus a `ULTRAWORK_LOG.md` describing evidence and fixes.
+
+**Format check** (included in improvement loop Step 8): After final recompilation, auto-detect and fix overfull hboxes (content exceeding margins), verify page count vs venue limit, and ensure compact formatting. Any overfull > 10pt is fixed before generating the final PDF.
+
+### Phase 6: Final Report
+
+```markdown
+# Paper Writing Pipeline Report
+
+**Input**: [NARRATIVE_REPORT.md or topic]
+**Venue**: [ICLR/NeurIPS/ICML]
+**Date**: [today]
+
+## Pipeline Summary
+
+| Phase | Status | Output |
+|-------|--------|--------|
+| 1. Paper Plan | ✅ | PAPER_PLAN.md |
+| 2. Figures | ✅ | figures/ ([N] auto + [M] manual) |
+| 3. LaTeX Writing | ✅ | paper/sections/*.tex ([N] sections, [M] citations) |
+| 4. Compilation | ✅ | paper/main.pdf ([X] pages) |
+| 5. ULTRAWORK QA | ✅ | ULTRAWORK_LOG.md |
+
+## Deliverables
+- paper/main.pdf — Final polished paper
+- paper/ULTRAWORK_LOG.md — QA log with evidence and fixes
+
+## Remaining Issues (if any)
+- [items from final review that weren't addressed]
+
+## Next Steps
+- [ ] Visual inspection of PDF
+- [ ] Add any missing manual figures
+- [ ] Submit to [venue] via OpenReview / CMT / HotCRP
+```
+
+## Key Rules
+
+- **Don't skip phases.** Each phase builds on the previous one — skipping leads to errors.
+- **Checkpoint between phases** when AUTO_PROCEED=false. Present results and wait for approval.
+- **Manual figures first.** If the paper needs architecture diagrams or qualitative results, the user must provide them before Phase 3.
+- **Compilation must succeed** before entering the improvement loop. Fix all errors first.
+- **Preserve all PDFs.** The user needs round0/round1/round2 for comparison.
+- **Document everything.** The pipeline report should be self-contained.
+- **Respect page limits.** If the paper exceeds the venue limit, suggest specific cuts before the improvement loop.
+
+## Composing with Other Workflows
+
+```
+/idea-discovery "direction"         ← Workflow 1: find ideas
+implement                           ← write code
+/run-experiment                     ← deploy experiments
+/ulw-loop "paper topic"     ← Workflow 2: iterate research
+/paper-writing "NARRATIVE_REPORT.md"  ← Workflow 3: you are here
+                                         submit! 🎉
+
+Or use /research-pipeline for the Workflow 1+2 end-to-end flow,
+then /paper-writing for the final writing step.
+```
+
+## Typical Timeline
+
+| Phase | Duration | Can sleep? |
+|-------|----------|------------|
+| 1. Paper Plan | 5-10 min | No |
+| 2. Figures | 5-15 min | No |
+| 3. LaTeX Writing | 15-30 min | Yes ✅ |
+| 4. Compilation | 2-5 min | No |
+| 5. Improvement | 15-30 min | Yes ✅ |
+
+**Total: ~45-90 min** for a full paper from narrative report to polished PDF.

package/generated/skills-bundles/full/skills/research/literature-and-web-search/auto-claude__arxiv/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: "auto-claude/arxiv"
+description: "Search, download, and summarize academic papers from arXiv using MCP tools. Use when user says \"search arxiv\", \"download paper\", \"fetch arxiv\", \"arxiv search\", \"get paper pdf\", or wants to find and save papers from arXiv to the local paper library."
+argument-hint: ["query-or-arxiv-id"]
+allowed-tools: "Read, Write"
+metadata:
+  category: "research/literature-and-web-search"
+---
+# arXiv Paper Search & Download
+
+Search topic or arXiv paper ID: $ARGUMENTS
+
+## Constants
+
+- **PAPER_DIR** - Local directory to save downloaded PDFs. Default: `papers/` in the current project directory.
+- **MAX_RESULTS = 10** - Default number of search results.
+
+> Overrides (append to arguments):
+> - `/arxiv "attention mechanism" - max: 20` - return up to 20 results
+> - `/arxiv "2301.07041" - download` - download a specific paper by ID
+> - `/arxiv "query" - dir: literature/` - save PDFs to a custom directory
+> - `/arxiv "query" - download: all` - download all result PDFs
+
+## MCP Requirement (No Script Fallback)
+
+This skill uses MCP only. Ensure at least one of these is enabled:
+
+- `paper_search_mcp` (preferred, multi-source)
+- `arxiv_mcp` (arXiv-only)
+
+If MCP tools are missing, enable them in config:
+
+```json
+{
+  "mcp_policy": {
+    "enable": ["paper_search_mcp", "arxiv_mcp"]
+  }
+}
+```
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for directives:
+
+- **Query or ID**: main search term or a bare arXiv ID such as `2301.07041` or `cs/0601001`
+- **`- max: N`**: override MAX_RESULTS (e.g., `- max: 20`)
+- **`- dir: PATH`**: override PAPER_DIR (e.g., `- dir: literature/`)
+- **`- download`**: download the first result's PDF after listing
+- **`- download: all`**: download PDFs for all results
+
+If the argument matches an arXiv ID pattern (`YYMM.NNNNN` or `category/NNNNNNN`), skip the search and go directly to Step 3.
+
+### Step 2: Search arXiv (MCP)
+
+Use MCP tools to search:
+
+- Prefer `paper_search_mcp` if available (multi-source).
+- Otherwise use `arxiv_mcp` (arXiv-only).
+
+Call the search tool exposed by the MCP server (the exact tool name appears in your MCP tool list). Pass the query and `MAX_RESULTS`.
+
+Present results as a table:
+
+```text
+| # | arXiv ID   | Title               | Authors        | Date       | Category |
+|---|------------|---------------------|----------------|------------|----------|
+| 1 | 2301.07041 | Attention Is All... | Vaswani et al. | 2017-06-12 | cs.LG    |
+```
+
+### Step 3: Fetch Details for a Specific ID (MCP)
+
+Use the MCP server's fetch/details tool (if provided) to retrieve metadata for a specific arXiv ID.
+
+Display: title, all authors, categories, full abstract, published date, PDF URL, abstract URL.
+
+### Step 4: Download PDFs (MCP)
+
+When download is requested:
+
+- Use MCP download/fetch tool if available.
+- If the MCP server only returns URLs, create the directory and save the URL list so the user can fetch later.
+
+If a local file path is returned:
+
+- Confirm file size > 10 KB (reject smaller files - likely an error HTML page)
+- Add a 1-second delay between consecutive downloads to avoid rate limiting
+- Report: `Downloaded: papers/2301.07041.pdf (842 KB)`
+
+### Step 5: Summarize
+
+For each paper (downloaded or fetched by API):
+
+```markdown
+## [Title]
+
+- **arXiv**: [ID] - [abs_url]
+- **Authors**: [full author list]
+- **Date**: [published]
+- **Categories**: [cs.LG, cs.AI, ...]
+- **Abstract**: [full abstract]
+- **Key contributions** (extracted from abstract):
+  - [contribution 1]
+  - [contribution 2]
+  - [contribution 3]
+- **Local PDF**: papers/[ID].pdf (if downloaded)
+```
+
+### Step 6: Final Output
+
+Summarize what was done:
+
+- `Found N papers for "query"`
+- `Downloaded: papers/2301.07041.pdf (842 KB)` (for each download)
+- Any warnings (rate limit hit, file too small, already exists)
+
+Suggest follow-up skills:
+
+```text
+/research-lit "topic"     - multi-source review: Zotero + Obsidian + local PDFs + web
+/novelty-check "idea"     - verify your idea is novel against these papers
+```
+
+## Key Rules
+
+- Always show the arXiv ID prominently - users need it for citations and reproducibility
+- Verify downloaded PDFs: file must be > 10 KB; warn and delete if smaller
+- Rate limit: wait 1 second between consecutive PDF downloads; retry once after 5 seconds on HTTP 429
+- Never overwrite an existing PDF at the same path - skip it and report "already exists"
+- Handle both arXiv ID formats: new (`2301.07041`) and old (`cs/0601001`)
+- PAPER_DIR is created automatically if it does not exist
+- If the arXiv API is unreachable, report the error clearly and suggest using `/research-lit` with `- sources: web` as a fallback

package/generated/skills-bundles/full/skills/research/literature-and-web-search/auto-claude__novelty-check/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: "auto-claude/novelty-check"
+description: "Verify research idea novelty against recent literature. Use when user says \"查新\", \"novelty check\", \"有没有人做过\", \"check novelty\", or wants to verify a research idea is novel before implementing."
+argument-hint: ["method-or-idea-description"]
+allowed-tools: "WebSearch, WebFetch, Grep, Read, Glob, mcp__codex__codex"
+metadata:
+  category: "research/literature-and-web-search"
+---
+# Novelty Check Skill
+
+Check whether a proposed method/idea has already been done in the literature: **$ARGUMENTS**
+
+## Constants
+
+- REVIEWER_MODEL = `gpt-5.4` — Model used via Codex MCP. Must be an OpenAI model (e.g., `gpt-5.4`, `o3`, `gpt-4o`)
+
+## Instructions
+
+Given a method description, systematically verify its novelty:
+
+### Phase A: Extract Key Claims
+1. Read the user's method description
+2. Identify 3-5 core technical claims that would need to be novel:
+   - What is the method?
+   - What problem does it solve?
+   - What is the mechanism?
+   - What makes it different from obvious baselines?
+
+### Phase B: Multi-Source Literature Search
+For EACH core claim, search using ALL available sources:
+
+1. **Web Search** (via `WebSearch`):
+   - Search arXiv, Google Scholar, Semantic Scholar
+   - Use specific technical terms from the claim
+   - Try at least 3 different query formulations per claim
+   - Include year filters for 2024-2026
+
+2. **Known paper databases**: Check against:
+   - ICLR 2025/2026, NeurIPS 2025, ICML 2025/2026
+   - Recent arXiv preprints (2025-2026)
+
+3. **Read abstracts**: For each potentially overlapping paper, WebFetch its abstract and related work section
+
+### Phase C: Cross-Model Verification
+Call REVIEWER_MODEL via Codex MCP (`mcp__codex__codex`) with xhigh reasoning:
+```
+config: {"model_reasoning_effort": "xhigh"}
+```
+Prompt should include:
+- The proposed method description
+- All papers found in Phase B
+- Ask: "Is this method novel? What is the closest prior work? What is the delta?"
+
+### Phase D: Novelty Report
+Output a structured report:
+
+```markdown
+## Novelty Check Report
+
+### Proposed Method
+[1-2 sentence description]
+
+### Core Claims
+1. [Claim 1] — Novelty: HIGH/MEDIUM/LOW — Closest: [paper]
+2. [Claim 2] — Novelty: HIGH/MEDIUM/LOW — Closest: [paper]
+...
+
+### Closest Prior Work
+| Paper | Year | Venue | Overlap | Key Difference |
+|-------|------|-------|---------|----------------|
+
+### Overall Novelty Assessment
+- Score: X/10
+- Recommendation: PROCEED / PROCEED WITH CAUTION / ABANDON
+- Key differentiator: [what makes this unique, if anything]
+- Risk: [what a reviewer would cite as prior work]
+
+### Suggested Positioning
+[How to frame the contribution to maximize novelty perception]
+```
+
+### Important Rules
+- Be BRUTALLY honest — false novelty claims waste months of research time
+- "Applying X to Y" is NOT novel unless the application reveals surprising insights
+- Check both the method AND the experimental setting for novelty
+- If the method is not novel but the FINDING would be, say so explicitly
+- Always check the most recent 6 months of arXiv — the field moves fast

package/generated/skills-bundles/full/skills/research/literature-and-web-search/auto-claude__research-lit/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: "auto-claude/research-lit"
+description: "Search and analyze research papers, find related work, summarize key ideas. Use when user says \"find papers\", \"related work\", \"literature review\", \"what does this paper say\", or needs to understand academic papers."
+argument-hint: ["paper-topic-or-url"]
+allowed-tools: "Bash(*), Read, Glob, Grep, WebSearch, WebFetch, Write, Agent, mcp__zotero__*, mcp__obsidian-vault__*"
+metadata:
+  category: "research/literature-and-web-search"
+---
+# Research Literature Review
+
+Research topic: $ARGUMENTS
+
+## Constants
+
+- **PAPER_LIBRARY** — Local directory containing user's paper collection (PDFs). Check these paths in order:
+  1. `papers/` in the current project directory
+  2. `literature/` in the current project directory
+  3. Custom path specified by user in `CLAUDE.md` under `## Paper Library`
+- **MAX_LOCAL_PAPERS = 20** — Maximum number of local PDFs to scan (read first 3 pages each). If more are found, prioritize by filename relevance to the topic.
+- **ARXIV_DOWNLOAD = false** — When `true`, download top 3-5 most relevant arXiv PDFs to PAPER_LIBRARY after search. When `false` (default), only fetch metadata (title, abstract, authors) via arXiv API — no files are downloaded.
+- **ARXIV_MAX_DOWNLOAD = 5** — Maximum number of PDFs to download when `ARXIV_DOWNLOAD = true`.
+
+> 💡 Overrides:
+> - `/research-lit "topic" — paper library: ~/my_papers/` — custom local PDF path
+> - `/research-lit "topic" — sources: zotero, local` — only search Zotero + local PDFs
+> - `/research-lit "topic" — sources: zotero` — only search Zotero
+> - `/research-lit "topic" — sources: web` — only search the web (skip all local)
+> - `/research-lit "topic" — arxiv download: true` — download top relevant arXiv PDFs
+> - `/research-lit "topic" — arxiv download: true, max download: 10` — download up to 10 PDFs
+
+## Data Sources
+
+This skill checks multiple sources **in priority order**. All are optional — if a source is not configured or not requested, skip it silently.
+
+### Source Selection
+
+Parse `$ARGUMENTS` for a `— sources:` directive:
+- **If `— sources:` is specified**: Only search the listed sources (comma-separated). Valid values: `zotero`, `obsidian`, `local`, `web`, `all`.
+- **If not specified**: Default to `all` — search every available source in priority order.
+
+Examples:
+```
+/research-lit "diffusion models"                        → all (default)
+/research-lit "diffusion models" — sources: all         → all
+/research-lit "diffusion models" — sources: zotero      → Zotero only
+/research-lit "diffusion models" — sources: zotero, web → Zotero + web
+/research-lit "diffusion models" — sources: local       → local PDFs only
+/research-lit "topic" — sources: obsidian, local, web   → skip Zotero
+```
+
+### Source Table
+
+| Priority | Source | ID | How to detect | What it provides |
+|----------|--------|----|---------------|-----------------|
+| 1 | **Zotero** (via MCP) | `zotero` | Try calling any `mcp__zotero__*` tool — if unavailable, skip | Collections, tags, annotations, PDF highlights, BibTeX, semantic search |
+| 2 | **Obsidian** (via MCP) | `obsidian` | Try calling any `mcp__obsidian-vault__*` tool — if unavailable, skip | Research notes, paper summaries, tagged references, wikilinks |
+| 3 | **Local PDFs** | `local` | `Glob: papers/**/*.pdf, literature/**/*.pdf` | Raw PDF content (first 3 pages) |
+| 4 | **Web search** | `web` | Always available (WebSearch) | arXiv, Semantic Scholar, Google Scholar |
+
+> **Graceful degradation**: If no MCP servers are configured, the skill works exactly as before (local PDFs + web search). Zotero and Obsidian are pure additions.
+
+## Workflow
+
+### Step 0a: Search Zotero Library (if available)
+
+**Skip this step entirely if Zotero MCP is not configured.**
+
+Try calling a Zotero MCP tool (e.g., search). If it succeeds:
+
+1. **Search by topic**: Use the Zotero search tool to find papers matching the research topic
+2. **Read collections**: Check if the user has a relevant collection/folder for this topic
+3. **Extract annotations**: For highly relevant papers, pull PDF highlights and notes — these represent what the user found important
+4. **Export BibTeX**: Get citation data for relevant papers (useful for `/paper-write` later)
+5. **Compile results**: For each relevant Zotero entry, extract:
+   - Title, authors, year, venue
+   - User's annotations/highlights (if any)
+   - Tags the user assigned
+   - Which collection it belongs to
+
+> 📚 Zotero annotations are gold — they show what the user personally highlighted as important, which is far more valuable than generic summaries.
+
+### Step 0b: Search Obsidian Vault (if available)
+
+**Skip this step entirely if Obsidian MCP is not configured.**
+
+Try calling an Obsidian MCP tool (e.g., search). If it succeeds:
+
+1. **Search vault**: Search for notes related to the research topic
+2. **Check tags**: Look for notes tagged with relevant topics (e.g., `#diffusion-models`, `#paper-review`)
+3. **Read research notes**: For relevant notes, extract the user's own summaries and insights
+4. **Follow links**: If notes link to other relevant notes (wikilinks), follow them for additional context
+5. **Compile results**: For each relevant note:
+   - Note title and path
+   - User's summary/insights
+   - Links to other notes (research graph)
+   - Any frontmatter metadata (paper URL, status, rating)
+
+> 📝 Obsidian notes represent the user's **processed understanding** — more valuable than raw paper content for understanding their perspective.
+
+### Step 0c: Scan Local Paper Library
+
+Before searching online, check if the user already has relevant papers locally:
+
+1. **Locate library**: Check PAPER_LIBRARY paths for PDF files
+   ```
+   Glob: papers/**/*.pdf, literature/**/*.pdf
+   ```
+
+2. **De-duplicate against Zotero**: If Step 0a found papers, skip any local PDFs already covered by Zotero results (match by filename or title).
+
+3. **Filter by relevance**: Match filenames and first-page content against the research topic. Skip clearly unrelated papers.
+
+4. **Summarize relevant papers**: For each relevant local PDF (up to MAX_LOCAL_PAPERS):
+   - Read first 3 pages (title, abstract, intro)
+   - Extract: title, authors, year, core contribution, relevance to topic
+   - Flag papers that are directly related vs tangentially related
+
+5. **Build local knowledge base**: Compile summaries into a "papers you already have" section. This becomes the starting point — external search fills the gaps.
+
+> 📚 If no local papers are found, skip to Step 1. If the user has a comprehensive local collection, the external search can be more targeted (focus on what's missing).
+
+### Step 1: Search (external)
+- Use WebSearch to find recent papers on the topic
+- Check arXiv, Semantic Scholar, Google Scholar
+- Focus on papers from last 2 years unless studying foundational work
+- **De-duplicate**: Skip papers already found in Zotero, Obsidian, or local library
+
+**arXiv API search** (always runs, no download by default):
+
+Locate the fetch script and search arXiv directly:
+```bash
+# Try to find arxiv_fetch.py
+SCRIPT=$(find tools/ -name "arxiv_fetch.py" 2>/dev/null | head -1)
+# If not found, check ARIS install
+[ -z "$SCRIPT" ] && SCRIPT=$(find ~/.claude/skills/arxiv/ -name "arxiv_fetch.py" 2>/dev/null | head -1)
+
+# Search arXiv API for structured results (title, abstract, authors, categories)
+python3 "$SCRIPT" search "QUERY" --max 10
+```
+
+If `arxiv_fetch.py` is not found, fall back to WebSearch for arXiv (same as before).
+
+The arXiv API returns structured metadata (title, abstract, full author list, categories, dates) — richer than WebSearch snippets. Merge these results with WebSearch findings and de-duplicate.
+
+**Optional PDF download** (only when `ARXIV_DOWNLOAD = true`):
+
+After all sources are searched and papers are ranked by relevance:
+```bash
+# Download top N most relevant arXiv papers
+python3 "$SCRIPT" download ARXIV_ID --dir papers/
+```
+- Only download papers ranked in the top ARXIV_MAX_DOWNLOAD by relevance
+- Skip papers already in the local library
+- 1-second delay between downloads (rate limiting)
+- Verify each PDF > 10 KB
+
+### Step 2: Analyze Each Paper
+For each relevant paper (from all sources), extract:
+- **Problem**: What gap does it address?
+- **Method**: Core technical contribution (1-2 sentences)
+- **Results**: Key numbers/claims
+- **Relevance**: How does it relate to our work?
+- **Source**: Where we found it (Zotero/Obsidian/local/web) — helps user know what they already have vs what's new
+
+### Step 3: Synthesize
+- Group papers by approach/theme
+- Identify consensus vs disagreements in the field
+- Find gaps that our work could fill
+- If Obsidian notes exist, incorporate the user's own insights into the synthesis
+
+### Step 4: Output
+Present as a structured literature table:
+
+```
+| Paper | Venue | Method | Key Result | Relevance to Us | Source |
+|-------|-------|--------|------------|-----------------|--------|
+```
+
+Plus a narrative summary of the landscape (3-5 paragraphs).
+
+If Zotero BibTeX was exported, include a `references.bib` snippet for direct use in paper writing.
+
+### Step 5: Save (if requested)
+- Save paper PDFs to `literature/` or `papers/`
+- Update related work notes in project memory
+- If Obsidian is available, optionally create a literature review note in the vault
+
+## Key Rules
+- Always include paper citations (authors, year, venue)
+- Distinguish between peer-reviewed and preprints
+- Be honest about limitations of each paper
+- Note if a paper directly competes with or supports our approach
+- **Never fail because a MCP server is not configured** — always fall back gracefully to the next data source
+- Zotero/Obsidian tools may have different names depending on how the user configured the MCP server (e.g., `mcp__zotero__search` or `mcp__zotero-mcp__search_items`). Try the most common patterns and adapt.