dsh-aris-panel 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "dsh-aris-panel",
+  "version": "0.1.0",
+  "description": "ARIS research-workflow skills + interactive workbench panel for DeepSeek Harness (user fork of dsh-aris: 82 skills, cross-model Codex review, idea/workflow launcher, research status board).",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "aris",
+    "research",
+    "agent",
+    "workbench"
+  ],
+  "exports": {
+    ".": "./dsh/index.mjs",
+    "./client": "./dsh/client.js",
+    "./scope-limits": "./dsh/scope-limits.mjs",
+    "./cordis.patch.yml": "./dsh/cordis.patch.yml",
+    "./checkout.patch.yml": "./dsh/checkout.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dsh",
+    "skills",
+    "tools",
+    "templates",
+    "mcp-servers",
+    "README.md",
+    "README_CN.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./dsh/cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-connection"
+      ]
+    }
+  }
+}

package/skills/ablation-planner/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: ablation-planner
+description: "Use when main results pass result-to-claim (claim_supported=yes or partial) and ablation studies are needed for paper submission."
+argument-hint: "[method-description-or-claim]"
+allowed-tools: Bash(*), Read, Grep, Glob, Write, Edit, mcp__codex__codex, mcp__codex__codex-reply
+---
+
+# Ablation Planner
+
+Systematically design ablation studies that answer the questions reviewers will ask. Codex leads the design (reviewer perspective), CC reviews feasibility and implements.
+
+## Context: $ARGUMENTS
+
+## When to Use
+
+- Main results pass `/result-to-claim` with claim_supported = yes or partial
+- User explicitly requests ablation planning
+- `/auto-review-loop` reviewer identifies missing ablations
+
+## Workflow
+
+### Step 1: Prepare Context
+
+CC reads available project files to build the full picture:
+- Method description and components (from `idea-stage/docs/research_contract.md`, legacy `docs/research_contract.md`, or project CLAUDE.md)
+- Current experiment results (from EXPERIMENT_LOG.md, EXPERIMENT_TRACKER.md, or W&B)
+- Confirmed and intended claims (from result-to-claim output or project notes)
+- Available compute resources (from CLAUDE.md server config, if present)
+
+### Step 2: Codex Designs Ablations
+
+```
+mcp__codex__codex:
+  model: gpt-5.6-sol
+  config: {"model_reasoning_effort": "xhigh"}
+  prompt: |
+    You are a rigorous ML reviewer planning ablation studies.
+    Given this method and results, design ablations that:
+
+    1. Isolate the contribution of each novel component
+    2. Answer questions reviewers will definitely ask
+    3. Test sensitivity to key hyperparameters
+    4. Compare against natural alternative design choices
+
+    Method: [description from project files]
+    Components: [list of removable/replaceable components]
+    Current results: [key metrics from experiments]
+    Claims: [what we claim and current evidence]
+
+    For each ablation, specify:
+    - name: what to change (e.g., "remove module X", "replace Y with Z")
+    - what_it_tests: the specific question this answers
+    - expected_if_component_matters: what we predict if the component is important
+    - priority: 1 (must-run) to 5 (nice-to-have)
+
+    Also provide:
+    - coverage_assessment: what reviewer questions these ablations answer
+    - unnecessary_ablations: experiments that seem useful but won't add insight
+    - suggested_order: run order optimized for maximum early information
+    - estimated_compute: total GPU-hours estimate
+```
+
+### Step 3: Parse Ablation Plan
+
+Normalize Codex response into structured format:
+
+```markdown
+## Ablation Plan
+
+### Component Ablations (highest priority)
+| # | Name | What It Tests | Expected If Matters | Priority |
+|---|------|---------------|---------------------|----------|
+| 1 | remove module X | contribution of X | performance drops on metric Y | 1 |
+| 2 | replace X with simpler Z | value of learned vs fixed | drops, especially on dataset A | 2 |
+
+### Hyperparameter Sensitivity
+| # | Parameter | Values to Test | What It Tests | Priority |
+|---|-----------|---------------|---------------|----------|
+| 3 | lambda | [0.01, 0.1, 1.0] | sensitivity to regularization | 3 |
+
+### Design Choice Comparisons
+| # | Name | What It Tests | Priority |
+|---|------|---------------|----------|
+| 4 | joint vs separate matching | whether joint adds value | 4 |
+
+### Coverage Assessment
+[What reviewer questions these ablations answer]
+
+### Unnecessary Ablations
+[Experiments that seem useful but won't add insight — skip these]
+
+### Run Order
+[Optimized for maximum early information]
+
+### Estimated Compute
+[Total GPU-hours]
+```
+
+### Step 4: CC Reviews Feasibility
+
+Before running anything, CC checks:
+- Compute budget: can we afford all ablations with available GPUs?
+- Code changes: which ablations need code modifications vs config-only changes?
+- Dependencies: which ablations can run in parallel?
+- Cuts: if budget is tight, propose removing lower-priority ablations and ask Codex to confirm
+
+### Step 5: Implement and Run
+
+1. Create configs/scripts for each ablation (config-only changes first)
+2. Smoke test each ablation before full run
+3. Run in suggested order, using descriptive names (e.g., `ablation-no-module-X`)
+4. Track results in EXPERIMENT_LOG.md
+5. After all ablations complete → update findings.md with insights
+
+## Rules
+
+- **Codex leads the design. CC does not pre-filter or bias the ablation list** before Codex sees it. Codex thinks like a reviewer; CC thinks like an engineer.
+- Every ablation must have a clear `what_it_tests` and `expected_if_component_matters`. No "just try it" experiments.
+- Config-only ablations take priority over those needing code changes (faster, less error-prone).
+- If total compute exceeds budget, CC proposes cuts and asks Codex to re-prioritize — don't silently drop ablations.
+- Component ablations (remove/replace) take priority over hyperparameter sweeps.
+- Do not generate ablations for components identical to the baseline (no-op ablations).
+- Record all ablation results in EXPERIMENT_LOG.md, including negative results (component removal had no effect = important finding).

package/skills/alphaxiv/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: alphaxiv
+description: Quick single-paper lookup via AlphaXiv LLM-optimized summaries with tiered source fallback. Use when user says "explain this paper", "summarize paper", pastes an arXiv/AlphaXiv URL, or provides a bare arXiv ID for quick understanding - not for broad literature search.
+argument-hint: "[arxiv-id-or-url]"
+allowed-tools: Bash(*), Read, Write, Glob
+---
+
+# AlphaXiv Paper Lookup
+
+Lookup paper: $ARGUMENTS
+
+> Quick single-paper reader with tiered source fallback (overview → full markdown → LaTeX source). Powered by [AlphaXiv](https://alphaxiv.org).
+
+## Role & Positioning
+
+This skill is the **quick single-paper reader** that returns LLM-optimized summaries:
+
+| Skill | Source | Best for |
+|-------|--------|----------|
+| `/arxiv` | arXiv API | Batch search, PDF download, metadata |
+| `/deepxiv` | DeepXiv SDK | Progressive section-level reading |
+| `/semantic-scholar` | S2 API | Published venue metadata, citation counts |
+| **`/alphaxiv`** | **alphaxiv.org** | **Instant LLM-optimized summary of one paper, with LaTeX source fallback** |
+
+**Do NOT use this skill for** topic discovery, broad literature search, or multi-paper surveys — use `/research-lit` or `/arxiv` instead.
+
+## Constants
+
+- **OVERVIEW_URL** = `https://alphaxiv.org/overview/{PAPER_ID}.md`
+- **ABS_URL** = `https://alphaxiv.org/abs/{PAPER_ID}.md`
+- **ARXIV_SRC_URL** = `https://arxiv.org/src/{PAPER_ID}`
+- **ALPHAXIV_UA** = `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36` — any modern browser UA works; update the version numbers if AlphaXiv starts blocking this value again
+
+> Overrides (append to arguments):
+> - `/alphaxiv 2401.12345` — quick overview
+> - `/alphaxiv "https://arxiv.org/abs/2401.12345"` — auto-extract ID
+> - `/alphaxiv 2401.12345 - depth: src` — force LaTeX source inspection
+> - `/alphaxiv 2401.12345 - depth: abs` — force full markdown
+
+## Workflow
+
+### Step 1: Parse Arguments & Extract Paper ID
+
+Parse `$ARGUMENTS` to extract a bare arXiv paper ID. Accept these input formats:
+
+- `https://arxiv.org/abs/2401.12345` or `https://arxiv.org/abs/2401.12345v2`
+- `https://arxiv.org/pdf/2401.12345`
+- `https://alphaxiv.org/overview/2401.12345`
+- `https://alphaxiv.org/abs/2401.12345`
+- `2401.12345` or `2401.12345v2`
+
+Strip version suffixes (`v1`, `v2`, ...) for API calls. Store as `PAPER_ID`.
+
+Parse optional directives:
+- **`- depth: overview|abs|src`**: force a specific tier instead of cascading
+
+### Step 2: Fetch AlphaXiv Overview (Tier 1 — Fastest)
+
+Use `curl` with `{ALPHAXIV_UA}` to fetch the AlphaXiv overview. AlphaXiv may return 403 for non-browser User-Agents; setting a standard browser UA reduces false positives from bot-detection:
+
+```bash
+curl -sL --max-time 15 -A "{ALPHAXIV_UA}" "https://alphaxiv.org/overview/{PAPER_ID}.md"
+```
+
+This returns a **structured, LLM-optimized report** designed for machine consumption. Use this as the default and preferred source.
+
+If the overview answers the user's question, **stop here**. Do not fetch deeper tiers unnecessarily.
+
+If the request fails (HTTP 4xx — 403 bot-block or 404 not-yet-processed) or returns empty content, proceed to Step 3.
+
+### Step 3: Fetch Full AlphaXiv Markdown (Tier 2 — More Detail)
+
+Use `curl` with `{ALPHAXIV_UA}` to fetch the full paper markdown:
+
+```bash
+curl -sL --max-time 15 -A "{ALPHAXIV_UA}" "https://alphaxiv.org/abs/{PAPER_ID}.md"
+```
+
+This provides the full paper body as markdown. Use when the user needs:
+- Specific methodology details
+- Detailed experimental results
+- Particular sections not covered in the overview
+
+If this still does not answer the question, proceed to Step 4.
+
+### Step 4: Fetch arXiv LaTeX Source (Tier 3 — Deepest)
+
+When the overview and full markdown are both insufficient (e.g., the user asks about equations, proofs, appendix details, or implementation specifics), download the paper's LaTeX source from `https://arxiv.org/src/{PAPER_ID}`.
+
+The source is a `.tar.gz` archive. Download it to a temporary directory, extract it, and list the `.tex` files inside.
+
+Then inspect **only** the files needed to answer the question. Prioritize:
+
+1. Top-level `*.tex` files (usually the main document)
+2. Files referenced by `\input{}` or `\include{}`
+3. Appendices, tables, or sections directly related to the user's question
+
+**Do NOT read the entire source tree by default.** Read selectively.
+
+Temporary source artifacts live under `/tmp`. Do not rely on persistence.
+
+### Step 5: Present Results
+
+#### Default Answer Shape
+
+```markdown
+## [Paper Title]
+
+- **arXiv**: [PAPER_ID] — https://arxiv.org/abs/[PAPER_ID]
+- **Source depth**: overview | abs | src
+
+### Summary
+[2-3 sentence summary]
+
+### Key Points
+- [point 1]
+- [point 2]
+- [point 3]
+
+### Answer to Your Question
+[Direct answer if the user asked a specific question]
+```
+
+If the user only asks for one specific detail, answer it directly — skip the full template.
+
+**After presenting the summary, you MUST proceed to Step 6 before ending the turn.**
+
+### Step 6: Research Wiki Ingest
+
+**You MUST always run the bash block below — it checks for `research-wiki/` internally and exits silently when absent.** Do NOT skip this step based on your own directory check; the bash block handles that for you.
+
+Substitute only `<paper_arxiv_id>` and `<thesis>`; keep `${ARIS_REPO:-...}` as-is so an already-set env var is preserved.
+
+```bash
+if [ -d research-wiki/ ]; then
+  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
+  ARIS_REPO="${ARIS_REPO:-$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null)}"
+  if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
+    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
+  fi
+  WIKI_SCRIPT=".aris/tools/research_wiki.py"
+  [ -f "$WIKI_SCRIPT" ] || WIKI_SCRIPT="tools/research_wiki.py"
+  [ -f "$WIKI_SCRIPT" ] || { [ -n "${ARIS_REPO:-}" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"; }
+  [ -f "$WIKI_SCRIPT" ] || {
+    echo "WARN: research_wiki.py not found; paper summary delivered, wiki ingest skipped. Fix: bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), export ARIS_REPO, or cp <ARIS-repo>/tools/research_wiki.py tools/." >&2
+    WIKI_SCRIPT=""
+  }
+  [ -n "$WIKI_SCRIPT" ] && python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
+      --arxiv-id "<paper_arxiv_id>" \
+      [--thesis "<one-line thesis from the Tier 1 overview>"]
+fi
+```
+
+The helper handles metadata fetch, slug, dedup, page creation, index
+rebuild, and log append — **do not handwrite `papers/<slug>.md`**. See
+[`shared-references/integration-contract.md`](../shared-references/integration-contract.md).
+If wiki was not present at read time (or the helper was unreachable),
+the user can backfill via
+`python3 "$WIKI_SCRIPT" sync research-wiki/ --arxiv-ids <id>` after
+resolving `$WIKI_SCRIPT` as above.
+
+#### Suggest Follow-Up Skills (after Step 6 completes)
+
+```text
+/arxiv "PAPER_ID" - download          - download the PDF to local library
+/deepxiv "PAPER_ID" - section: Methods  - read a specific section progressively
+/research-lit "related topic"        - multi-source literature survey
+/novelty-check "idea from paper"     - verify novelty against this paper's area
+```
+
+## Key Rules
+
+- **Overview first**: `overview` is the fastest path and must always be tried before deeper tiers. Only escalate when needed.
+- **Minimal reads**: At `src` tier, read only the files that answer the question. Full-tree reads waste tokens.
+- **Cross-platform**: When downloading and extracting the source archive, prefer cross-platform approaches (e.g., Python stdlib) over platform-specific commands to ensure Windows/WSL compatibility.
+- **No PDF parsing**: This skill reads structured markdown and LaTeX source, not raw PDFs. For PDF content, suggest `/arxiv` with download.
+- **Rate limiting**: arXiv source download may rate-limit. If HTTP 429 occurs, wait 5 seconds and retry once. If still blocked, report the error and suggest `/deepxiv` as alternative.
+- **Complementary, not competing**: This skill complements `/arxiv` (search + download) and `/deepxiv` (progressive reading). Do not re-implement their functionality.
+
+## Integration with Other Skills
+
+### As enrichment in `/research-lit`
+
+`/research-lit` can use this skill's Tier 1 (overview) as a fast enrichment step between search and deep analysis. After finding arXiv papers in Step 1, fetch AlphaXiv overviews to quickly assess relevance before committing to full-text reads:
+
+```
+Step 1: Search → list of arXiv IDs
+Step 1.5: AlphaXiv overview for top 5-8 papers (this skill, Tier 1 only)
+Step 2: Deep analysis only for papers that pass the relevance filter
+```
+
+This saves significant tokens by filtering out marginally relevant papers before deep reading.
+
+### As follow-up from other skills
+
+After `/research-lit`, `/novelty-check`, or `/idea-discovery` surface a specific paper, users can invoke `/alphaxiv PAPER_ID` for a fast deep-dive without re-running the full survey.

package/skills/analyze-results/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: analyze-results
+description: Analyze ML experiment results, compute statistics, generate comparison tables and insights. Use when user says "analyze results", "compare", or needs to interpret experimental data.
+argument-hint: "[results-path-or-description]"
+allowed-tools: Bash(*), Read, Grep, Glob, Write, Edit
+---
+
+# Analyze Experiment Results
+
+Analyze: $ARGUMENTS
+
+## Workflow
+
+### Step 1: Locate Results
+Find all relevant JSON/CSV result files:
+- Check `figures/`, `results/`, or project-specific output directories
+- Parse JSON results into structured data
+
+### Step 2: Build Comparison Table
+Organize results by:
+- **Independent variables**: model type, hyperparameters, data config
+- **Dependent variables**: primary metric (e.g., perplexity, accuracy, loss), secondary metrics
+- **Delta vs baseline**: always compute relative improvement
+
+### Step 3: Statistical Analysis
+- If multiple seeds: report mean +/- std, check reproducibility
+- If sweeping a parameter: identify trends (monotonic, U-shaped, plateau)
+- Flag outliers or suspicious results
+
+### Step 4: Generate Insights
+For each finding, structure as:
+1. **Observation**: what the data shows (with numbers)
+2. **Interpretation**: why this might be happening
+3. **Implication**: what this means for the research question
+4. **Next step**: what experiment would test the interpretation
+
+### Step 5: Update Documentation
+If findings are significant:
+- Propose updates to project notes or experiment reports
+- Draft a concise finding statement (1-2 sentences)
+
+## Output Format
+Always include:
+1. Raw data table
+2. Key findings (numbered, concise)
+3. Suggested next experiments (if any)

package/skills/arxiv/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: arxiv
+description: Search, download, and summarize academic papers from arXiv. 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: Bash(*), Read, Write
+---
+
+# 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.
+- **ARXIV_FETCHER** — canonical name `arxiv_fetch.py`, resolved per
+  [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2
+  (Policy D1 — primary + fallback cascade). If unresolved (canonical
+  chain exhausted), fall back to the inline Python alternative
+  documented in Step 2.
+
+> 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
+
+## 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
+
+Resolve `$ARXIV_FETCHER` via the canonical strict-safe chain (see
+[`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2):
+
+```bash
+cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
+if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
+    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
+fi
+if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
+    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
+fi
+ARXIV_FETCHER=".aris/tools/arxiv_fetch.py"
+[ -f "$ARXIV_FETCHER" ] || ARXIV_FETCHER="tools/arxiv_fetch.py"
+[ -f "$ARXIV_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && ARXIV_FETCHER="$ARIS_REPO/tools/arxiv_fetch.py"; }
+[ -f "$ARXIV_FETCHER" ] || ARXIV_FETCHER=""
+```
+
+**If `$ARXIV_FETCHER` is non-empty**, run:
+
+```bash
+python3 "$ARXIV_FETCHER" search "QUERY" --max MAX_RESULTS
+```
+
+**If `$ARXIV_FETCHER` is empty** (Policy D1 cascade), fall back to inline Python:
+
+```bash
+python3 - <<'PYEOF'
+import json
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+
+NS = "http://www.w3.org/2005/Atom"
+query = urllib.parse.quote("QUERY")
+url = (f"http://export.arxiv.org/api/query"
+       f"?search_query={query}&start=0&max_results=MAX_RESULTS"
+       f"&sortBy=relevance&sortOrder=descending")
+with urllib.request.urlopen(url, timeout=30) as r:
+    root = ET.fromstring(r.read())
+papers = []
+for entry in root.findall(f"{{{NS}}}entry"):
+    aid = entry.findtext(f"{{{NS}}}id", "").split("/abs/")[-1].split("v")[0]
+    title = (entry.findtext(f"{{{NS}}}title", "") or "").strip().replace("\n", " ")
+    abstract = (entry.findtext(f"{{{NS}}}summary", "") or "").strip().replace("\n", " ")
+    authors = [a.findtext(f"{{{NS}}}name", "") for a in entry.findall(f"{{{NS}}}author")]
+    published = entry.findtext(f"{{{NS}}}published", "")[:10]
+    cats = [c.get("term", "") for c in entry.findall(f"{{{NS}}}category")]
+    papers.append({
+        "id": aid,
+        "title": title,
+        "authors": authors,
+        "abstract": abstract,
+        "published": published,
+        "categories": cats,
+        "pdf_url": f"https://arxiv.org/pdf/{aid}.pdf",
+        "abs_url": f"https://arxiv.org/abs/{aid}",
+    })
+print(json.dumps(papers, ensure_ascii=False, indent=2))
+PYEOF
+```
+
+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
+
+When a single paper ID is requested (either directly or from Step 2):
+
+```bash
+python3 "$ARXIV_FETCHER" search "id:ARXIV_ID" --max 1
+# or fallback:
+python3 -c "
+import urllib.request, xml.etree.ElementTree as ET
+NS = 'http://www.w3.org/2005/Atom'
+url = 'http://export.arxiv.org/api/query?id_list=ARXIV_ID'
+with urllib.request.urlopen(url, timeout=30) as r:
+    root = ET.fromstring(r.read())
+# print full details ...
+"
+```
+
+Display: title, all authors, categories, full abstract, published date, PDF URL, abstract URL.
+
+### Step 4: Download PDFs
+
+When download is requested, for each paper ID to download:
+
+```bash
+# Using fetch script:
+python3 "$ARXIV_FETCHER" download ARXIV_ID --dir PAPER_DIR
+
+# Fallback:
+mkdir -p PAPER_DIR && python3 -c "
+import pathlib
+import sys
+import urllib.request
+
+out = pathlib.Path('PAPER_DIR/ARXIV_ID.pdf')
+if out.exists():
+    print(f'Already exists: {out}')
+    sys.exit(0)
+req = urllib.request.Request(
+    'https://arxiv.org/pdf/ARXIV_ID.pdf',
+    headers={'User-Agent': 'arxiv-skill/1.0'},
+)
+with urllib.request.urlopen(req, timeout=60) as r:
+    out.write_bytes(r.read())
+print(f'Downloaded: {out} ({out.stat().st_size // 1024} KB)')
+"
+```
+
+After each download:
+
+- 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: Update Research Wiki (if active)
+
+**Required when `research-wiki/` exists in the project**; skip silently
+otherwise. When the wiki dir exists, resolve `$WIKI_SCRIPT` per the
+canonical chain at
+[`shared-references/wiki-helper-resolution.md`](../shared-references/wiki-helper-resolution.md)
+(Variant B — warn-and-skip), then ingest every paper returned by this
+invocation:
+
+```bash
+if [ -d research-wiki/ ]; then
+  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
+  ARIS_REPO="${ARIS_REPO:-$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null)}"
+  if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
+    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
+  fi
+  WIKI_SCRIPT=".aris/tools/research_wiki.py"
+  [ -f "$WIKI_SCRIPT" ] || WIKI_SCRIPT="tools/research_wiki.py"
+  [ -f "$WIKI_SCRIPT" ] || { [ -n "${ARIS_REPO:-}" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"; }
+  [ -f "$WIKI_SCRIPT" ] || {
+    echo "WARN: research_wiki.py not found; arxiv results delivered, wiki ingest skipped. Fix: bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), export ARIS_REPO, or cp <ARIS-repo>/tools/research_wiki.py tools/." >&2
+    WIKI_SCRIPT=""
+  }
+  if [ -n "$WIKI_SCRIPT" ]; then
+    for each arxiv_id in results:
+        python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
+            --arxiv-id "<arxiv_id>"
+  fi
+fi
+```
+
+The helper handles metadata fetch, slug, dedup, page creation, index
+rebuild, and log append in a single call — **do not handwrite
+`papers/<slug>.md`**. See
+[`shared-references/integration-contract.md`](../shared-references/integration-contract.md)
+for the canonical-helper rule. Missed ingests can be backfilled later
+with `python3 "$WIKI_SCRIPT" sync research-wiki/ --arxiv-ids <id1>,<id2>,...`
+after resolving `$WIKI_SCRIPT` as above.
+
+### Step 7: Final Output
+
+Summarize what was done:
+
+- `Found N papers for "query"`
+- `Downloaded: papers/2301.07041.pdf (842 KB)` (for each download)
+- `Wiki-ingested N papers` (if `research-wiki/` was present)
+- 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