@research-copilot/plugin 1.1.17 → 1.1.18

package/dist/skills/meta-optimize/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: meta-optimize
+description: "Analyze ARIS usage logs and propose optimizations to SKILL.md files, reviewer prompts, and workflow defaults. Outer-loop harness optimization inspired by Meta-Harness (Lee et al., 2026). Use when user says \"优化技能\", \"meta optimize\", \"improve skills\", \"分析使用记录\", or wants to optimize ARIS's own harness components based on accumulated experience."
+argument-hint: [target-skill-or-all]
+allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob
+---
+
+# Meta-Optimize: Outer-Loop Harness Optimization for ARIS
+
+Analyze accumulated usage logs and propose optimizations for: **$ARGUMENTS**
+
+## Context
+
+ARIS is a **research harness** — a system of skills, bridges, workflows, and artifact contracts that wraps around LLMs to orchestrate research. This skill implements a prototype **outer loop** that observes how the harness is used and proposes improvements to the harness itself (not to the research artifacts it produces).
+
+Inspired by Meta-Harness (Lee et al., 2026): the key insight is that harness design matters as much as model weights, and harness engineering can be partially automated by logging execution traces and using them to guide improvements.
+
+## What This Skill Optimizes (Harness Components)
+
+| Component | Example | Optimizable? |
+|-----------|---------|:---:|
+| SKILL.md prompts | Reviewer instructions, quality gates, step descriptions | Yes |
+| Default parameters | `difficulty: medium`, `MAX_ROUNDS: 4`, `threshold: 6/10` | Yes |
+| Convergence rules | When to stop the review loop, retry counts | Yes |
+| Workflow ordering | Skill chain sequence within a workflow | Yes |
+| Artifact schemas | What fields go in EXPERIMENT_LOG.md, idea-stage/IDEA_REPORT.md | Cautious |
+| MCP bridge config | Which reviewer model, routing rules | No (infra) |
+
+**Not optimized**: The research artifacts themselves (papers, code, experiments). That's what the regular workflows do.
+
+## Prerequisites
+
+1. **Logging must be active.** Codex mirror installs do not create Claude Code hooks. Provide `.aris/meta/events.jsonl` from a Codex-compatible event logger, an external wrapper, or a manually exported trace log before running this skill.
+2. **Sufficient data.** At least 5 complete workflow runs logged in `.aris/meta/events.jsonl`. The skill will check and warn if insufficient.
+
+## Workflow
+
+### Step 0: Check Data Availability
+
+```bash
+EVENTS_FILE=".aris/meta/events.jsonl"
+if [ ! -f "$EVENTS_FILE" ]; then
+    echo "ERROR: No event log found at $EVENTS_FILE"
+    echo "Enable Codex-compatible logging first: create .aris/meta/events.jsonl from your Codex wrapper, external event logger, or exported trace log."
+    exit 1
+fi
+
+EVENT_COUNT=$(wc -l < "$EVENTS_FILE")
+SKILL_INVOCATIONS=$(grep -c '"skill_invoke"' "$EVENTS_FILE" || echo 0)
+SESSIONS=$(grep -c '"session_start"' "$EVENTS_FILE" || echo 0)
+
+echo "📊 Event log: $EVENT_COUNT events, $SKILL_INVOCATIONS skill invocations, $SESSIONS sessions"
+
+if [ "$SKILL_INVOCATIONS" -lt 5 ]; then
+    echo "⚠️  Insufficient data (<5 skill invocations). Continue using ARIS normally and re-run later."
+    exit 0
+fi
+```
+
+### Step 1: Analyze Usage Patterns
+
+Read `.aris/meta/events.jsonl` and compute:
+
+**Frequency analysis:**
+- Which skills are invoked most often?
+- Which slash commands do users type most?
+- What parameter overrides are most common? (These suggest bad defaults.)
+
+**Failure analysis:**
+- Which tools fail most often? In which skills?
+- What error patterns repeat? (OOM, import, compilation, timeout)
+- How many auto-debug retries per workflow run?
+
+**Convergence analysis (for auto-review-loop):**
+- Average rounds to reach threshold
+- Score trajectory shape (fast improvement? plateau? oscillation?)
+- Which review round catches the most critical issues?
+- Do users override difficulty mid-run?
+
+**Human intervention analysis:**
+- Where do users interrupt with manual prompts during workflows?
+- What manual corrections do users make most? (These indicate skill gaps.)
+
+Present findings as a structured summary table.
+
+### Step 2: Identify Optimization Targets
+
+Based on Step 1, rank optimization opportunities by expected impact:
+
+```markdown
+## Optimization Opportunities (ranked)
+
+| # | Target | Signal | Proposed Change | Expected Impact |
+|---|--------|--------|-----------------|-----------------|
+| 1 | auto-review-loop default threshold | Users override to 7/10 in 60% of runs | Change default from 6/10 to 7/10 | Fewer manual overrides |
+| 2 | experiment-bridge retry count | 40% of runs hit max retries on OOM | Add OOM-specific recovery (reduce batch size) | Fewer failed experiments |
+| 3 | paper-write de-AI patterns | Users manually fix "delve" in 80% of runs | Add "delve" to default watchword list | Fewer manual edits |
+```
+
+If `$ARGUMENTS` specifies a target skill, focus analysis on that skill only.
+If `$ARGUMENTS` is empty or "all", analyze all skills with sufficient data.
+
+### Step 3: Generate Patch Proposals
+
+For each optimization target, generate a concrete diff:
+
+```diff
+--- a/skills/auto-review-loop/SKILL.md
++++ b/skills/auto-review-loop/SKILL.md
+@@ -15,7 +15,7 @@
+ ## Constants
+ 
+-- **SCORE_THRESHOLD = 6** — Minimum review score to accept.
++- **SCORE_THRESHOLD = 7** — Minimum review score to accept. (Raised based on usage data: 60% of users overrode to 7+.)
+```
+
+**Rules for patch generation:**
+- One patch per optimization target
+- Each patch must include a comment explaining WHY (with data from the log)
+- Patches must be minimal — change only what the data supports
+- Never change artifact schemas or MCP bridge config in v1
+- Never change behavior that would break existing user workflows
+
+### Step 4: Cross-Model Review of Patches
+
+Send each patch to GPT-5.5 xhigh for adversarial review:
+
+```text
+spawn_agent:
+  model: gpt-5.5
+  reasoning_effort: xhigh
+  message: |
+    You are reviewing a proposed optimization to an ARIS SKILL.md file.
+    
+    ## Original Skill (relevant section)
+    [paste original]
+    
+    ## Proposed Patch
+    [paste diff]
+    
+    ## Evidence from Usage Log
+    [paste summary stats]
+    
+    Review this patch:
+    1. Does the evidence support the change?
+    2. Could this change hurt other use cases?
+    3. Is the change minimal and safe?
+    4. Score 1-10: should this be applied?
+    
+    If score < 7, explain what additional evidence would be needed.
+```
+
+### Step 5: Present Results
+
+Output a structured report:
+
+```markdown
+# ARIS Meta-Optimization Report
+
+**Date**: [today]
+**Data**: [N] events, [M] skill invocations, [K] sessions
+**Target**: [skill name or "all"]
+
+## Proposed Changes
+
+### Change 1: [title]
+- **Target**: [skill/file:line]
+- **Signal**: [what the data shows]
+- **Patch**: [diff]
+- **Reviewer Score**: [X/10]
+- **Reviewer Notes**: [summary]
+- **Status**: ✅ Recommended / ⚠️ Needs more data / ❌ Rejected
+
+### Change 2: ...
+
+## Changes NOT Made (insufficient evidence)
+- [pattern observed but too few samples]
+
+## Recommendations
+- [ ] Apply Change 1 (reviewer approved)
+- [ ] Collect more data for Change 3 (need N more runs)
+- [ ] Consider manual review of Change 2
+
+## Next Steps
+Run `/meta-optimize apply 1` to apply a specific change, or
+`/meta-optimize apply all` to apply all recommended changes.
+```
+
+### Step 6: Apply Changes (if user approves)
+
+If user runs `/meta-optimize apply [N]`:
+1. Back up original SKILL.md to `.aris/meta/backups/`
+2. Apply the patch
+3. Log the change to `.aris/meta/optimizations.jsonl`
+4. Remind user to test the changed skill on their next run
+
+**Never auto-apply without user approval.**
+
+## Key Rules
+
+- **Log-driven, not speculative.** Every proposed change must cite specific data from the event log. No "I think this would be better."
+- **Minimal patches.** Change one thing at a time. Don't rewrite entire skills.
+- **Reviewer-gated.** Every patch goes through cross-model review before recommendation.
+- **Reversible.** Always back up before applying. Always log what changed.
+- **User-approved.** Never auto-apply. Present, explain, let the user decide.
+- **Honest about uncertainty.** If the data is insufficient, say so. Don't optimize on noise.
+- **Portable.** Optimizations should improve the skill for all users, not just one user's style. If a change seems user-specific, flag it.
+
+## Event Schema Reference
+
+The log at `.aris/meta/events.jsonl` contains JSONL records with these shapes:
+
+```jsonl
+{"ts":"...","session":"...","event":"skill_invoke","skill":"auto-review-loop","args":"difficulty: hard"}
+{"ts":"...","session":"...","event":"PostToolUse","tool":"Bash","input_summary":"pdflatex main.tex"}
+{"ts":"...","session":"...","event":"spawn_agent","tool":"spawn_agent","input_summary":"review..."}
+{"ts":"...","session":"...","event":"tool_failure","tool":"Bash","input_summary":"python train.py"}
+{"ts":"...","session":"...","event":"slash_command","command":"/auto-review-loop","args":""}
+{"ts":"...","session":"...","event":"user_prompt","prompt_preview":"change difficulty to hard"}
+{"ts":"...","session":"...","event":"session_start","source":"startup","model":"claude-opus-4-6"}
+{"ts":"...","session":"...","event":"session_end"}
+```
+
+## Triggering
+
+This skill is NOT part of the standard W1→W1.5→W2→W3→W4 pipeline. It is a **maintenance workflow** with three trigger mechanisms:
+
+1. **Passive logging** (always on): Claude Code hooks record events to `.aris/meta/events.jsonl` automatically during normal usage. Zero user effort.
+
+2. **Automatic readiness check** (SessionEnd hook): When a Claude Code session ends, `check_ready.sh` counts skill invocations since the last `/meta-optimize` run. If ≥5 new invocations have accumulated, it prints a reminder:
+   ```
+   📊 ARIS has logged 8 skill runs since last optimization. Run /meta-optimize to check for improvement opportunities.
+   ```
+   This is a **suggestion only** — it does not auto-run optimization.
+
+3. **Manual trigger**: User runs `/meta-optimize` when they see the reminder or whenever they want.
+
+**After each `/meta-optimize` run**, the skill writes the current timestamp to `.aris/meta/.last_optimize` so the readiness check only counts new invocations.
+
+## Acknowledgements
+
+Inspired by [Meta-Harness](https://arxiv.org/abs/2603.28052) (Lee et al., 2026) — end-to-end optimization of model harnesses via filesystem-based experience access and agentic code search.
+
+## Output Protocols
+
+> Follow these shared protocols for all output files:
+> - **[Output Versioning Protocol](../shared-references/output-versioning.md)** — write timestamped file first, then copy to fixed name
+> - **[Output Manifest Protocol](../shared-references/output-manifest.md)** — log every output to MANIFEST.md
+> - **[Output Language Protocol](../shared-references/output-language.md)** — respect the project's language setting
+
+## Review Tracing
+
+After each reviewer agent call, save the trace following `shared-references/review-tracing.md` (Policy C — forensic; never silently skip). Use `save_trace.sh` (resolved per the chain in `shared-references/integration-contract.md` §2) or write files directly to `.aris/traces/<skill>/<date>_run<NN>/`. Respect the `--- trace:` parameter (default: `full`).

package/dist/skills/monitor-experiment/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: "monitor-experiment"
+description: "Monitor running experiments, check progress, collect results. Use when user says \"check results\", \"is it done\", \"monitor\", or wants experiment output."
+---
+
+# Monitor Experiment Results
+
+Monitor: $ARGUMENTS
+
+## Workflow
+
+### Step 1: Check What's Running
+
+First identify the backend from `AGENTS.md`, run notes, or launch summary: local, SSH, Vast.ai, or Modal. Monitor the backend that was actually used; do not assume a plain SSH screen session when the run was launched through Vast.ai or Modal.
+
+```bash
+ssh <server> "screen -ls"
+```
+
+For Vast.ai, also check instance state, SSH reachability, hourly cost, and whether `auto_destroy` is pending. For Modal, check the Modal run/app logs, function status, timeout, volume outputs, and cloud cost exposure.
+
+### Step 2: Collect Output from Each Screen
+For each screen session, capture the last N lines:
+```bash
+ssh <server> "screen -S <name> -X hardcopy /tmp/screen_<name>.txt && tail -50 /tmp/screen_<name>.txt"
+```
+
+If hardcopy fails, check for log files or tee output.
+
+### Step 3: Check for JSON Result Files
+```bash
+ssh <server> "ls -lt <results_dir>/*.json 2>/dev/null | head -20"
+```
+
+If JSON results exist, fetch and parse them:
+```bash
+ssh <server> "cat <results_dir>/<latest>.json"
+```
+
+### Step 3.5: Pull W&B Metrics (when `wandb: true` in AGENTS.md)
+
+If the project enables W&B, pull metrics before interpreting results. Prefer W&B as the source of training curves and recent eval state, while still checking logs for crashes.
+
+List recent runs:
+
+```bash
+python3 - <<'PY'
+import wandb
+api = wandb.Api()
+for run in api.runs("<entity>/<project>", per_page=20):
+    print(run.name, run.state, run.url)
+PY
+```
+
+Pull recent history for a specific run:
+
+```bash
+python3 - <<'PY'
+import wandb
+api = wandb.Api()
+run = api.run("<entity>/<project>/<run_id>")
+for row in run.history(samples=50, keys=["train/loss", "eval/loss", "eval/accuracy", "train/lr"]):
+    print(row)
+print("summary:", dict(run.summary))
+PY
+```
+
+If W&B is configured but unavailable, report the connectivity problem and fall back to screen/log/json evidence. Do not interpret missing W&B data as experiment failure by itself.
+
+Always include W&B dashboard links (`run.url`) when available so later review and paper-writing agents can inspect the exact training curves.
+
+### Step 4: Summarize Results
+
+Present results in a comparison table:
+```
+| Experiment | Metric | Delta vs Baseline | Status |
+|-----------|--------|-------------------|--------|
+| Baseline  | X.XX   | —                 | done   |
+| Method A  | X.XX   | +Y.Y              | done   |
+```
+
+### Step 5: Interpret
+- Compare against known baselines
+- Flag unexpected results (negative delta, NaN, divergence)
+- Suggest next steps based on findings
+
+### Step 6: Feishu Notification (if configured)
+
+After results are collected, check `~/.codex/feishu.json`:
+- Send `experiment_done` notification: results summary table, delta vs baseline
+- If config absent or mode `"off"`: skip entirely (no-op)
+
+## Key Rules
+- Always show raw numbers before interpretation
+- Compare against the correct baseline (same config)
+- Note if experiments are still running (check progress bars, iteration counts)
+- If results look wrong, check training logs for errors before concluding
+- Include backend cost/risk notes for long-running Vast.ai or Modal jobs

package/dist/skills/novelty-check/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: "novelty-check"
+description: "Verify research idea novelty against recent literature. Use when user says \"\u67e5\u65b0\", \"novelty check\", \"\u6709\u6ca1\u6709\u4eba\u505a\u8fc7\", \"check novelty\", or wants to verify a research idea is novel before implementing."
+---
+
+# Novelty Check Skill
+
+Check whether a proposed method/idea has already been done in the literature: **$ARGUMENTS**
+
+## Constants
+
+- REVIEWER_MODEL = `gpt-5.5` — Model used via a secondary Codex agent. Must be an OpenAI model (e.g., `gpt-5.5`, `o3`, `gpt-4o`)
+- **REVIEWER_BACKEND = `codex`** — Default: Codex xhigh reviewer. Use `--reviewer: oracle-pro` only when explicitly requested; if Oracle is unavailable, warn and fall back to Codex xhigh.
+
+## 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 `spawn_agent` (`spawn_agent`) with xhigh reasoning:
+```
+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
+
+## Review Tracing
+
+After each `spawn_agent` or optional `oracle-pro` reviewer call, save the trace following `../shared-references/review-tracing.md`. Write files directly to `.aris/traces/novelty-check/<date>_run<NN>/` and record searched claims, closest papers, reviewer route, raw response, and final novelty decision. Respect the `--- trace:` parameter when present (default: `full`).

package/dist/skills/openalex/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: openalex
+description: Search academic papers via OpenAlex API for open citation data, institutional affiliations, and funding information. Use when user says "openalex search", "search openalex", "open citation graph", or wants comprehensive academic metadata beyond arXiv/Semantic Scholar.
+argument-hint: [search-query]
+allowed-tools: Bash(*), Read, Write
+---
+
+# OpenAlex Academic Search
+
+Search query: $ARGUMENTS
+
+## Role & Positioning
+
+This skill uses OpenAlex as a **comprehensive open academic graph** source:
+
+| Skill | Source | Best for |
+|-------|--------|----------|
+| `/arxiv` | arXiv API | Latest preprints, cutting-edge unrefereed work |
+| `/semantic-scholar` | Semantic Scholar API | Published venue papers (IEEE, ACM, Springer) with citation counts |
+| `/openalex` | OpenAlex API | **Open citation graph, institutional affiliations, funding data, comprehensive metadata** |
+| `/deepxiv` | DeepXiv CLI | Layered reading: search, brief, section map, section reads |
+| `/exa-search` | Exa API | Broad web search: blogs, docs, news, companies, research papers |
+| `/gemini-search` | Gemini MCP / CLI | AI-powered broad literature discovery |
+
+Use OpenAlex when you want:
+- **Open citation data** — fully open citation graph (no API key required for basic use)
+- **Institutional affiliations** — author institutions and collaborations
+- **Funding information** — NSF, NIH, and other funding sources
+- **Comprehensive metadata** — topics, keywords, abstract, open access status
+- **Cross-database coverage** — indexes 250M+ works from multiple sources
+
+## Constants
+
+- **MAX_RESULTS = 10** — Default number of results. Override with `— max: 20`.
+- **DEFAULT_SORT = relevance** — Sort by relevance. Override with `— sort: citations` or `— sort: date`.
+- **OPENALEX_FETCHER** — canonical name `openalex_fetch.py`, resolved per
+  [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2
+  (Policy D1 — standalone `/openalex` has no documented inline fallback,
+  so unresolved helper terminates with an explicit error).
+
+> Overrides (append to arguments):
+> - `/openalex "topic" — max: 20` — return up to 20 results
+> - `/openalex "topic" — year: 2023-` — papers from 2023 onward
+> - `/openalex "topic" — year: 2020-2023` — papers from 2020 to 2023
+> - `/openalex "topic" — type: article` — only journal articles
+> - `/openalex "topic" — type: preprint` — only preprints
+> - `/openalex "topic" — open-access` — only open access papers
+> - `/openalex "topic" — min-citations: 50` — minimum 50 citations
+> - `/openalex "topic" — sort: citations` — sort by citation count (descending)
+> - `/openalex "topic" — sort: date` — sort by publication date (newest first)
+
+## Setup
+
+### Prerequisites
+
+1. **Python 3.7+** with `requests` library:
+   ```bash
+   pip install requests
+   ```
+
+2. **Optional: API keys** — Export them in your shell or project environment:
+   ```bash
+   export OPENALEX_API_KEY=your-key-here
+   export OPENALEX_EMAIL=your-email@example.com
+   ```
+
+3. **Get API keys** (optional but recommended):
+   - **OpenAlex API key**: Free tier $1/day (10,000 list calls, 1,000 search calls) from [openalex.org](https://openalex.org/)
+   - **Email for polite pool**: Faster response times (no registration needed)
+
+### Verify Setup
+
+```bash
+python3 "$OPENALEX_FETCHER" search "machine learning" --max 3
+```
+
+(Resolve `$OPENALEX_FETCHER` via the canonical chain first — see Step 2 below.)
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for:
+- **query**: The research topic (required)
+- **max**: Override MAX_RESULTS
+- **year**: Publication year filter (e.g., `2023-`, `2020-2023`)
+- **type**: Work type filter (`article`, `preprint`, `book`, `book-chapter`, `dataset`, `dissertation`)
+- **open-access**: Only include open access papers
+- **min-citations**: Minimum citation count threshold
+- **sort**: Sort order (`relevance`, `citations`, `date`)
+
+### Step 2: Locate Script
+
+Resolve `$OPENALEX_FETCHER` via the canonical strict-safe chain (see
+[`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2).
+Policy D1: there is no native inline fallback for OpenAlex
+(retrieval requires the `requests` SDK + optional API key — the
+fetcher script encapsulates pagination, throttling, and per-source
+parameters), so unresolved helper terminates with explicit remediation.
+
+```bash
+cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
+if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
+    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
+fi
+OPENALEX_FETCHER=""
+[ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/openalex_fetch.py" ] && OPENALEX_FETCHER="$ARIS_REPO/tools/openalex_fetch.py"
+[ -z "$OPENALEX_FETCHER" ] && [ -f tools/openalex_fetch.py ] && OPENALEX_FETCHER="tools/openalex_fetch.py"
+[ -z "$OPENALEX_FETCHER" ] && [ -f ~/.codex/skills/openalex/openalex_fetch.py ] && OPENALEX_FETCHER="$HOME/.codex/skills/openalex/openalex_fetch.py"
+[ -f "$OPENALEX_FETCHER" ] || {
+  echo "ERROR: openalex_fetch.py not resolved at \$ARIS_REPO/tools/, tools/, or ~/.codex/skills/openalex/." >&2
+  echo "       Fix: rerun install_aris_codex.sh, export ARIS_REPO, or copy the helper to ~/.codex/skills/openalex/." >&2
+  echo "       Also ensure 'requests' is installed: pip install requests" >&2
+  exit 1
+}
+```
+
+### Step 3: Execute Search
+
+**Basic search:**
+```bash
+python3 "$OPENALEX_FETCHER" search "QUERY" --max 10
+```
+
+**With filters:**
+```bash
+python3 "$OPENALEX_FETCHER" search "QUERY" --max 10 \
+  --year 2023- \
+  --type article \
+  --open-access \
+  --min-citations 20 \
+  --sort citations
+```
+
+**Get specific work by DOI:**
+```bash
+python3 "$OPENALEX_FETCHER" work "10.1109/TWC.2024.1234567"
+```
+
+**Get specific work by OpenAlex ID:**
+```bash
+python3 "$OPENALEX_FETCHER" work "W2741809807"
+```
+
+### Step 4: Parse Results
+
+The script returns structured JSON with:
+- `title`: Paper title
+- `authors`: List of author names
+- `publication_year`: Year published
+- `venue`: Journal/conference name
+- `venue_type`: Type of venue (journal, repository, conference, etc.)
+- `cited_by_count`: Number of citations
+- `is_oa`: Boolean for open access status
+- `oa_status`: Open access type (gold, green, bronze, hybrid, closed)
+- `oa_url`: Direct PDF link if available
+- `doi`: DOI identifier
+- `openalex_id`: OpenAlex work ID
+- `abstract`: Full abstract text
+- `topics`: Top 3 research topics
+- `keywords`: Top 5 keywords
+- `type`: Work type (article, preprint, etc.)
+
+### Step 5: Present Results
+
+Format results as a structured table:
+
+```
+| # | Title | Venue | Year | Citations | OA | Summary |
+|---|-------|-------|------|-----------|----|---------|
+| 1 | ... | IEEE TWC | 2024 | 156 | ✓ | ... |
+| 2 | ... | NeurIPS | 2023 | 89 | ✓ | ... |
+```
+
+For each paper, also show:
+- **DOI**: Canonical identifier
+- **OpenAlex ID**: For cross-reference
+- **Open Access**: Status (gold/green/bronze/hybrid/closed) and PDF link
+- **Topics**: Top research topics
+- **Abstract**: First 200 characters or full text
+
+### Step 6: Offer Follow-up
+
+After presenting results, suggest:
+
+```text
+/semantic-scholar "DOI:..."     — get S2 citation context and related papers
+/arxiv "arXiv:XXXX.XXXXX"      — fetch arXiv preprint if available
+/research-lit "topic" — sources: openalex, semantic-scholar  — combined multi-source review
+/novelty-check "idea"          — verify novelty against literature
+```
+
+## Key Rules
+
+- **OpenAlex is fully open** — no API key required for basic use, but recommended for higher rate limits
+- **Comprehensive metadata** — OpenAlex provides richer metadata than most sources (institutions, funding, topics)
+- **Citation data is open** — unlike Semantic Scholar, all citation data is freely accessible
+- **Rate limits**: Without API key, very limited (~$0.01/day). With free API key: 10,000 list calls/day, 1,000 search calls/day.
+- **Polite pool**: Set `OPENALEX_EMAIL` environment variable for faster response times
+- **Cross-reference with other sources**: OpenAlex indexes papers from arXiv, PubMed, Crossref, etc. — use DOI/arXiv ID to cross-reference
+- If OpenAlex API is unreachable or rate-limited, suggest using `/semantic-scholar`, `/arxiv`, or `/research-lit "topic" — sources: web` as alternatives.
+
+## OpenAlex vs Other Sources
+
+| Feature | OpenAlex | Semantic Scholar | arXiv |
+|---------|----------|------------------|-------|
+| **Coverage** | 250M+ works | 200M+ papers | 2.4M+ preprints |
+| **Citation data** | Fully open | Partially open | None |
+| **Institutions** | ✓ Full affiliations | ✓ Limited | ✗ |
+| **Funding** | ✓ NSF, NIH, etc. | ✗ | ✗ |
+| **Open access** | ✓ Full OA status | ✓ PDF links | ✓ All papers |
+| **API key** | Optional (free) | Optional (free) | Not required |
+| **Rate limits** | 1,000 searches/day (free key) | Unknown | 1 req/3s |
+| **Abstract** | ✓ Full text | ✓ TLDR | ✓ Full text |
+| **Best for** | Comprehensive metadata, institutions, funding | Citation counts, venue info | Latest preprints |
+
+**When to use OpenAlex over S2:**
+- Need institutional affiliation data
+- Need funding information
+- Want fully open citation graph
+- Need comprehensive topic/keyword metadata
+- Working with non-CS fields (OpenAlex covers all disciplines)
+
+**When to use S2 over OpenAlex:**
+- Need real-time citation counts (S2 updates faster)
+- Need "highly influential citations" metric
+- Need paper recommendations
+- CS/AI-focused research (S2 has better CS coverage)