ARS Setup

Prerequisites and optional setup for Academic Research Skills. If you only need Markdown output and the default Claude pipeline (the inherited session model), you can skip most of this — see "Minimum viable setup" below.

---

Minimum viable setup

1. Install Claude Code (see below).
2. Export ANTHROPIC_API_KEY.
3. claude in this repo (or any project that has ARS in .claude/skills/).

That is enough for Markdown output + DOCX conversion instructions. Everything else in this document is optional.

Python (optional)

The core skills (research / write / review) need no Python — they are prompt-driven. A real Python interpreter is needed only for: the PreToolUse write-scope guard (optional subagent hardening — if no real Python is found it cleanly no-ops and the guard is simply inactive; core skills are unaffected), plus a few opt-in features that shell out to Python (revision-patch mode, the submission-package verifier, and the /ars-cache-invalidate / /ars-mark-read / /ars-unmark-read commands). On Windows, note that python3 is often a non-functional Microsoft Store placeholder rather than real Python; install Python from python.org (or via winget) so the launcher can find a real interpreter. The guard launcher is a POSIX shell script and hooks.json invokes it through bash, so on Windows it needs Git Bash (bundled with Git for Windows). With Git Bash present, a missing real Python degrades cleanly (the guard no-ops, silently). Without Git Bash, Claude Code falls back to PowerShell, which cannot run the .sh launcher at all: the guard is inactive and the PreToolUse hook will log an error per call rather than no-op quietly (accepted degradation — the guard is optional and never blocks your writes, but the hook noise is the trade-off until Git Bash is installed).

---

---

Install Claude Code

Recommended: Native installer (no Node.js required, auto-updates):

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

Platform support. macOS and Linux are the tested platforms; CI runs on Ubuntu only. Windows is best-effort: the scripts that lock files share one helper (scripts/file_lock.py) with an msvcrt backend, no Windows CI job exists, and Windows behaviour rests on contributor verification (#843, #845). On Windows, shared read locks degrade to exclusive locks with a short wait, indefinite lock waits are capped at 30 seconds, and the inquiry branch ledger alpha refuses to run.

<details> <summary>Alternative: npm install (deprecated)</summary>

Requires Node.js 18+.

npm install -g @anthropic-ai/claude-code

</details>

Set up API key

Get an Anthropic API key at https://console.anthropic.com/.

# Claude Code will prompt for your API key on first run
claude

Or set it as an environment variable:

export ANTHROPIC_API_KEY=sk-ant-xxxxx

DOCX output (optional)

Direct .docx generation uses Pandoc. If Pandoc is unavailable, the formatter falls back to Markdown + DOCX conversion instructions.

# macOS
brew install pandoc

# Linux (Debian/Ubuntu)
sudo apt-get install pandoc

# Windows — download from https://pandoc.org/installing.html

LaTeX / PDF output (optional)

PDF output requires tectonic and specific fonts. This is optional — Markdown output and DOCX conversion instructions work without any of this.

# macOS
brew install tectonic

# Linux (Debian/Ubuntu)
curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net | sh

# Windows — download from https://tectonic-typesetting.github.io/en-US/install.html

Required fonts (for APA 7.0 CJK output):

• Times New Roman — usually pre-installed on macOS/Windows; on Linux install ttf-mscorefonts-installer
• Source Han Serif TC VF (思源宋體) — download from Google Fonts or Adobe GitHub
• Courier New — usually pre-installed

If you only need Markdown output or DOCX conversion instructions, skip this entirely. Direct .docx generation requires Pandoc, and PDF generation requires tectonic.

---

Material Passport literature_corpus[] adapters (v3.6.4+, optional)

If you maintain a curated literature corpus (Zotero, Obsidian, a folder of PDFs, etc.), you can pre-load it into a Material Passport so Phase 1 ARS agents read your library before searching external databases. This is opt-in and presence-based — when no corpus is supplied, ARS runs the external-DB-only flow unchanged.

Three reference Python adapters ship with v3.6.4 at scripts/adapters/:

# 1. Install the dev dependencies (the adapter requirements are declared in requirements-dev.txt)
pip install -r requirements-dev.txt

# 2. Run a reference adapter (pick one that matches your corpus source).
#    Both --passport and --rejection-log are required.
python scripts/adapters/folder_scan.py --input /path/to/pdfs               --passport passport.yaml --rejection-log rejection_log.yaml
python scripts/adapters/zotero.py      --input my-zotero-export.json       --passport passport.yaml --rejection-log rejection_log.yaml
python scripts/adapters/obsidian.py    --input ~/Obsidian/Lit\ Notes       --passport passport.yaml --rejection-log rejection_log.yaml

# 3. Pass the resulting passport.yaml into your ARS session
#    (concrete invocation depends on which skill you're running — see scripts/adapters/README.md)

Each adapter emits two files: passport.yaml (Schema 9 with literature_corpus[] populated) and rejection_log.yaml (always emitted, empty when no rejections — closed enum of categorical reasons). Users with non-reference corpus sources are expected to write their own adapters following academic-pipeline/references/adapters/overview.md.

v3.6.5 wires bibliography_agent (deep-research, Phase 1) and literature_strategist_agent (academic-paper, Phase 1) as the consumers — both run the corpus-first / search-fills-gap flow when a non-empty corpus is present and parses cleanly. See academic-pipeline/references/literature_corpus_consumers.md for the consumer protocol.

Optional environment flags (v3.5.1+)

ARS exposes a few opt-in flags. All default to OFF; setting them changes behaviour for the current session only. These flags are behavior toggles; for standing content preferences (citation style, search inclusion), see §"Standing preferences via CLAUDE.md" below.

| Flag | Since | What it does | Reference | |---|---|---|---| | ARS_CROSS_MODEL | v3.0 | Enable cross-model verification (see next section) | §"Cross-model verification" | | ARS_CROSS_MODEL_TRANSPORT=codex | #630 | Use ChatGPT subscription transport for citation-integrity calls only; all DA/reviewer/judgment paths remain API-key based | shared/cross_model_verification.md | | ARS_SOCRATIC_READING_PROBE=1 | v3.5.1 | Activate the Socratic reading-check probe layer in socratic_mentor_agent. Goal-oriented intent only; fires at most once per session when user has cited a specific paper; decline logged without penalty. | deep-research/agents/socratic_mentor_agent.md | | ARS_PASSPORT_RESET=1 | v3.6.3 | Promote every FULL and MANDATORY checkpoint to a context-reset boundary. Required to emit boundary entries; not required to invoke resume_from_passport=<hash> in a fresh session. With the flag ON in systematic-review mode, reset is mandatory at every FULL and MANDATORY checkpoint. | academic-pipeline/references/passport_as_reset_boundary.md | | ARS_AUDIT_ARTIFACT_GATE=1 | #925 | Turn on the v3.6.7 Audit Artifact Gate, which has you run scripts/run_codex_audit.sh outside the session at each transition after a synthesis_agent / research_architect_agent (survey-designer) / report_compiler_agent (abstract-only) deliverable; the wrapper sends the deliverable to an external model, and the gate blocks on its findings. The flag is configuration, not consent: the gate runs only after you agree for the run. Off by default; the Stage 2.5 / 4.5 integrity gates run either way. | academic-pipeline/agents/pipeline_orchestrator_agent.md § 3.5 | | ARS_CROSS_MODEL_SAMPLE_INTERVAL | v3.5.0 | With cross-model on, run the second-model collaboration-depth observer every N checkpoints instead of every one (default 1; the Stage 6 whole-pipeline pass always runs). It does not change integrity-gate sampling. | academic-pipeline/agents/pipeline_orchestrator_agent.md § Collaboration Depth Observer | | ARS_CLAIM_AUDIT=1 | v3.8 | Turn on the claim-faithfulness audit: claims are judged against their cited sources, and unsupported ones block final output. In pipeline runs it first runs at Stage 4.5, so a finding can still be corrected. | academic-pipeline/agents/pipeline_orchestrator_agent.md § 3.6 | | ARS_SOCRATIC_ADJACENT_PROBE=1 | v3.13.0 (#461) | Let the Socratic Mentor raise one adjacent framing at a time, as a question, at most twice per session. | deep-research/agents/socratic_mentor_agent.md | | ARS_RE_REVIEW_LEGACY=1 | v3.20.0 (#576) | Run Stage 3' re-review with the archived pre-contract schemas and checker instead of the three-gate contract. | academic-paper-reviewer/references/re_review_mode_protocol.md § Legacy Mode | | ARS_INQUIRY_LEDGER=1 | v3.21.1 (#743) | Alpha inquiry branch ledger. It needs a research-workflow profile binding, which no pipeline step creates; without one the run stays linear and says so. | academic-pipeline/agents/pipeline_orchestrator_agent.md § Inquiry Branch Ledger | | ARS_VERIFICATION_CACHE_PATH | v3.11 | Override the citation-verification cache location (see below). Not an on/off flag — the cache is on by default; this only relocates it. | scripts/verification_cache.py | | ARS_CACHE_STALE_ADVISORY_DAYS | v3.18.0 (#541) | Age threshold (days) for the cache-staleness advisory: cache-served verifications older than this surface as ADV-CACHE advisory rows at the integrity checkpoints (never gating). Default 30; 0 disables; malformed/negative values fall back to the default. | scripts/verification_cache.py | | ARS_CACHE_REVALIDATE=1 | v3.18.0 (#541) | Opt-in live re-verification at the gate: cached rows past the staleness threshold are re-verified live (per-row bypass, then re-populated) instead of served. Cost scales with the stale-row count. Default off = advisory-only. | scripts/verification_gate/__init__.py + integrity_verification_agent.md § A0.5 | | ARS_MODEL_TIERING | v3.16.0 (#517) | Opt-in model tiering: economy (frontier session — execution-type agents step down one tier, floor Opus-class) or quality-boost (below-frontier session — judgment-type agents jump up to the frontier tier at the checkpoint surfaces: Stage 2.5/4.5 gates, the opt-in Stage 4→5 claim–ref audit, and final review). Unset = session model everywhere; unknown values warn once and behave as unset. | shared/model_tiering.md |

---

Standing preferences via CLAUDE.md

ARS deliberately ships no user-level configuration file. The supported way to get "set once, applies every run" behavior for content preferences is a preferences block in your project's CLAUDE.md: Claude Code loads it at session start, and every ARS agent dispatched in that session inherits it as context. This is a stated design position, not a missing feature — search-related preferences are per-project inclusion/exclusion criteria that belong in the Annotated Bibliography's search_strategy (Schema 2), and a machine-global config silently inherited across projects would be a methodological hazard for systematic-review work. Decision record: #634.

Copy-pasteable template (adjust to taste):

## ARS standing preferences

- Citation style: APA 7th unless a venue template says otherwise.
- Literature search: exclude preprints unless I explicitly ask; prefer
  peer-reviewed journal articles.
- Journal tier: when ranking or shortlisting sources, prefer higher-tier
  journals in the field, and say so when unsure of a journal's tier.
- Open access: prefer OA versions when citing, and link the OA copy.

Two honest limitations:

• Journal tiers are model judgment. None of the four lookup indexes (Semantic Scholar, OpenAlex, Crossref, arXiv) serves quartile or tier data, so a tier preference is applied from the model's own knowledge and should be stated as such — treat tier claims as advisory, never as verified metadata.
• There is intentionally no output-directory setting. The user-supplied Material Passport path is the single discovery anchor (v3.6.8 design round, decision R4-003); a standing output-location preference would create a second source of truth. Name the destination per run.

If a preference changes what a systematic review may include (preprint exclusion, language limits, date windows), record it in that project's search_strategy rather than relying on the ambient block — the ambient block sets defaults, the Schema 2 search_strategy is the auditable record.

Re-evaluation trigger (recorded in #634): an ARS-owned preferences surface gets revisited only if additional users independently request it, or a platform port lacks a CLAUDE.md equivalent. If ever built, the architecturally consistent shape is a Material Passport-level user_preferences input aggregate (like literature_corpus[]), not a machine-global config file.

---

Citation verification cache (v3.11, #182)

The deterministic citation-existence gate (#182) cross-checks each reference against Semantic Scholar, OpenAlex, Crossref, and arXiv. To avoid re-querying the same paper across drafts, results are cached in a local SQLite store.

• No setup required. The cache is created automatically at ~/.cache/ars/verification.db on first use; entries expire after 90 days. The arXiv resolver needs no API key.
• Relocate it by exporting ARS_VERIFICATION_CACHE_PATH=/your/path.db (e.g. to share one cache across projects, or to keep it on a faster disk).
• Invalidate one citation with /ars-cache-invalidate <citation_key> — removes every cached row for that key (all four resolvers, all query forms); idempotent no-op if nothing is cached.

The cache is single-process (SQLite WAL); concurrent multi-user access to one cache file is out of scope.

For the complete picture of what leaves the machine (resolvers, optional cross-model calls, the update check) and every local store's lifetime and deletion path, see DATA_FLOWS.md.

---

Cross-model verification (optional)

ARS works with the inherited Claude session model alone. For higher confidence, you can optionally enable a second AI model to independently verify integrity checks and challenge the devil's advocate.

Quick setup

# Step 1: Set your API key (choose one or both)
export OPENAI_API_KEY="sk-your-key-here"        # For GPT-6 Astra / GPT-5.6 Sol / GPT-5.5
export GOOGLE_AI_API_KEY="AIza-your-key-here"    # For Gemini 4 Argon / Gemini 3.1 Pro

# Step 2: Choose your cross-verification model
export ARS_CROSS_MODEL="gpt-6-astra"            # Current OpenAI flagship — provisional pending ARS validation (run scripts/cross_model_smoke_test.sh)
# or: export ARS_CROSS_MODEL="gemini-4-argon"  # Current Google flagship — provisional pending ARS validation (no Gemini smoke script; check one known citation first)
# or: export ARS_CROSS_MODEL="gemini-3.1-pro-preview"  # Previous Google generation — validated, strong at factual verification
# or: export ARS_CROSS_MODEL="gpt-5.6-sol"      # Previous generation — validated on the ChatGPT-subscription citation transport, provisional on this API route
# or: export ARS_CROSS_MODEL="gpt-5.5"          # Previous generation — validated (designated API-route bakeoff baseline)

# Optional: reasoning effort for OpenAI verifier calls (unset = provider default)
# GPT-6 Astra API: low|medium|high|xhigh|max (the Codex citation transport rejects ultra)
# export ARS_CROSS_MODEL_REASONING_EFFORT="medium"

# Step 3: Run Claude Code as normal — cross-verification activates automatically
claude

What changes when enabled

| Feature | Without cross-model | With cross-model | |---|---|---| | Integrity verification | Single-model 100% check | + risk-stratified verification by 2nd model: 100% of high-impact references (final gate adds 100% of new/changed-claim references) + a sampled remainder | | Devil's Advocate | Single-model DA | + Cross-model generates a blind, separately executed critique; novel findings added | | Peer Review | 5 reviewers (same model) | Same 5 reviewers + cross-model DA critique/calibration support | | Irreversible checkpoints | Single-model decision | + Blind cross-model decision at design freeze + final editorial decision; divergence escalated to you, never averaged |

Cost

Full pipeline adds ~$0.60-1.10 in cross-model API costs (order-of-magnitude; measured at GPT-5.4 Pro pricing). See shared/cross_model_verification.md for the current model lineup and detailed breakdown.

No API key? No problem

Without ARS_CROSS_MODEL set, everything works exactly as before. The cross-model features are invisible and add zero overhead.

ChatGPT subscription transport (citation integrity only)

If Codex CLI 0.147.0+ is logged in through a ChatGPT subscription, citation-integrity calls can use that subscription without an OpenAI API key. This does not cover Devil's Advocate, Reviewer 2, calibration, re-review, or checkpoint judgments.

# Citation-integrity calls only. General DA/reviewer/judgment calls remain on API transport.
export ARS_CROSS_MODEL_TRANSPORT="codex"
# gpt-6-astra: current OpenAI flagship — provisional on this transport (entry-gate
# smoke PASS 2026-09-05 on codex-cli 0.153.4; no bakeoff run yet).
export ARS_CROSS_MODEL="gpt-6-astra"
# gpt-5.6-sol is validated for THIS transport (2026-08-19 codex-transport bakeoff,
# superiority on recall + latency — audits/bakeoff-gpt-5-6-sol-codex-2026-08-19.md):
# export ARS_CROSS_MODEL="gpt-5.6-sol"

python3 scripts/cross_model_codex_transport.py detect
# The producer sends one closed codex_citation_request/1.0 object on stdin:
printf '%s' "$CITATION_REQUEST_JSON" | scripts/cross_model_codex_verify.sh

The detector honors custom CODEX_HOME and requires the exact subscription attestation Logged in using ChatGPT; it never prints credentials. The adapter uses an auth-only ephemeral home, empty working root, read-only sandbox, no local tools, and binds accepted source URLs to structured search results. The optional live smoke scripts/cross_model_smoke_test_codex.sh spends subscription/model/network capacity and is never run by CI.

---

Installation methods

Claude discovers skills at <install-root>/<skill-name>/SKILL.md. This repo contains five separate skills, each with its own SKILL.md:

• deep-research
• academic-paper
• academic-paper-reviewer
• academic-pipeline
• sr-screener

Do not install the whole repository as one nested skill folder under .claude/skills/academic-research-skills/; that buries the five SKILL.md files one level too deep for discovery. See Anthropic's Claude Code Skills documentation.

The methods below differ in more than convenience: hooks, slash commands, the tools allowlist, subagent orchestration, and script-backed checks are each available in some channels and degraded or absent in others. Before relying on any of those mechanisms, check the per-channel map: CONTROL_AVAILABILITY.md.

Method 0: Claude Code Plugin (v3.7.0+, recommended for