dsh-aris-panel 0.1.0

package/skills/novelty-check/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: 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
+---
+
+# Novelty Check Skill
+
+Check whether a proposed method/idea has already been done in the literature: **$ARGUMENTS**
+
+## Constants
+
+- REVIEWER_MODEL = `gpt-5.6-sol` — Model used via Codex MCP. Must be an OpenAI model (e.g., `gpt-5.6-sol`, `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.
+When the method description plus the Phase-B paper list is more than a short
+note, avoid pasting it inline into the MCP prompt. Write a dossier file such as
+`NOVELTY_DOSSIER.md` (or a project-local equivalent) containing the method
+description, core claims, candidate papers, and the exact questions below, then
+send only the file path:
+```
+mcp__codex__codex:
+  model: gpt-5.6-sol
+  config: {"model_reasoning_effort": "xhigh"}
+  prompt: |
+    Read the novelty dossier at <absolute path to NOVELTY_DOSSIER.md> and
+    follow all instructions in it.
+```
+Dossier contents 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
+- **Anti-hallucination for Closest Prior Work.** Every paper in the prior-work table must pass pre-search verification via `verify_papers.py` (canonical name resolved per [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2; 3-layer arXiv / CrossRef / Semantic Scholar fallback inside the helper itself). Policy D1 (primary + degraded-output fallback): if the helper is unresolved **or** its invocation fails, tag candidate entries `[UNVERIFIED]` and surface the uncertainty rather than dropping them. Never fabricate arXiv IDs, DOIs, or titles from memory. Full protocol in [`shared-references/citation-discipline.md`](../shared-references/citation-discipline.md) § Pre-Search Verification Protocol.
+
+## Review Tracing
+
+After each `mcp__codex__codex` or `mcp__codex__codex-reply` reviewer 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/skills/openalex/SKILL.md

@@ -0,0 +1,237 @@
+---
+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** — Create `.claude/.env` in project root:
+   ```bash
+   # Copy from template
+   cp .claude/.env.example .claude/.env
+   
+   # Edit and add your keys
+   # .claude/.env
+   OPENALEX_API_KEY=your-key-here
+   OPENALEX_EMAIL=your-email@example.com
+   ```
+   
+   Claude Code automatically loads `.claude/.env` as environment variables.
+
+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.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
+OPENALEX_FETCHER=".aris/tools/openalex_fetch.py"
+[ -f "$OPENALEX_FETCHER" ] || OPENALEX_FETCHER="tools/openalex_fetch.py"
+[ -f "$OPENALEX_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && OPENALEX_FETCHER="$ARIS_REPO/tools/openalex_fetch.py"; }
+[ -f "$OPENALEX_FETCHER" ] || {
+  echo "ERROR: openalex_fetch.py not resolved at .aris/tools/, tools/, \$ARIS_REPO/tools/, or via ~/.aris/repo." >&2
+  echo "       Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), export ARIS_REPO, or copy the helper to tools/." >&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)

package/skills/overleaf-sync/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: overleaf-sync
+description: "Two-way sync between a local paper directory and an Overleaf project, so ARIS audit/edit workflows stay on the local copy while collaborators edit in the Overleaf web UI. Use when user says \"同步 overleaf\", \"overleaf sync\", \"推送到 overleaf\", \"connect overleaf\", \"Overleaf 桥接\", \"pull overleaf\", \"push overleaf\", or wants to bridge their ARIS paper directory with an Overleaf project."
+argument-hint: "[setup <project-id> | pull | push | status]"
+allowed-tools: Bash(*), Read, Grep, Glob, Edit, Write
+---
+
+# Overleaf Sync
+
+Bridge a local paper directory with an Overleaf project so that:
+
+- **You** can keep editing in the Overleaf web UI (or share editing access with collaborators)
+- **ARIS** can read your changes, run audits (`/paper-claim-audit`, `/citation-audit`, `/auto-paper-improvement-loop`), and push fixes back
+
+This uses the official **Overleaf Git bridge** (Premium feature). The agent **never sees your authentication token** — you do the one-time auth manually so the token lives in macOS Keychain, not in chat history or `.git/config`.
+
+## When to Use This Skill
+
+- You want to use Overleaf as the editing surface (better collaboration, shared with team) but still run ARIS pipelines locally
+- You want to take an existing local ARIS paper and push it to Overleaf for a co-author to edit
+- A collaborator made changes in Overleaf and you want to pull + diff them before continuing local work
+
+## Constants
+
+- **CLONE_DIR_DEFAULT** = `paper-overleaf` (sibling of existing `paper/`, NOT inside `paper/`)
+- **CREDENTIAL_HELPER** = `osxkeychain` (macOS) / `manager` (Windows) / `cache` (Linux fallback)
+- **TOKEN_HANDLING** = **NEVER write token to disk, env var, or chat**. User pastes it once into the terminal credential prompt; the OS keychain stores it from then on.
+
+## Architecture
+
+```
+┌─────────────────┐       git pull/push      ┌─────────────────┐
+│  Local paper/   │ ◄─── rsync ──── ►       │ paper-overleaf/ │ ◄──► Overleaf web
+│  (ARIS audits)  │                          │ (git bridge)    │     (collaborators)
+└─────────────────┘                          └─────────────────┘
+```
+
+The `paper-overleaf/` directory is a **git clone of the Overleaf project**. The `paper/` directory is the working copy where ARIS skills run. They are kept in sync via `rsync`.
+
+**Single-source-of-truth rule**: at any given time, treat *one* of them as authoritative for active editing. Switch directions explicitly with `pull` or `push`, and run a `status` check before either to surface unexpected divergence.
+
+## Sub-commands
+
+### `setup <project-id>` — one-time
+
+Sets up the bridge for a new Overleaf project. **The user runs this in their own terminal, never through the agent.** The skill ships with a hardened setup script that:
+
+1. Refuses to run unless stdin/stdout are a TTY (won't run inside an agent harness)
+2. Reads the token from a hidden prompt (no chat history, no shell history)
+3. Strips the token from the remote URL immediately after cloning
+4. Primes the OS keychain so subsequent agent operations are auth-free
+5. **Auto-installs a `pre-commit` hook in `paper-overleaf/.git/hooks/` that refuses to commit any blob containing the token pattern `olp_[A-Za-z0-9]{20,}`** — a hard technical block, not a behavioral rule
+
+The agent's only role here is to print the user instruction:
+
+```
+Run this in your own terminal (NOT through me):
+
+    bash <ARIS_REPO>/tools/overleaf_setup.sh <project-id-or-url>
+
+When it finishes, tell me "setup done" and I'll verify.
+```
+
+After the user reports "setup done", the agent verifies (token-free):
+
+```bash
+cd paper-overleaf
+git remote -v                    # must show URL WITHOUT token
+git config --get credential.helper
+git fetch && git log --oneline -3   # must succeed without prompting
+ls .git/hooks/pre-commit         # must exist
+bash <ARIS_REPO>/tools/overleaf_audit.sh .   # must report "Audit clean"
+```
+
+If `paper-overleaf/` exists but is empty (new Overleaf project), the agent then mirrors local `paper/` into it (see `push` workflow).
+
+### `pull` — before each editing session
+
+```bash
+cd paper-overleaf && git pull --ff-only
+
+# Show what changed since last pull
+LAST=$(git rev-parse HEAD@{1})
+git diff --stat $LAST..HEAD
+git diff $LAST..HEAD -- 'sec/*.tex'        # detailed view for prose changes
+```
+
+**Diff protocol — DO NOT blindly merge into local `paper/`.** Overleaf edits frequently include:
+
+- **Half-finished sentences** (collaborator clicked save mid-thought)
+- **Typos** that aren't in canonical references (`Lrage` for `Large`)
+- **Commented-out blocks** that may be intentional or may be a stash
+- **Number changes** that should re-trigger `/paper-claim-audit`
+- **Cite key changes** that should re-trigger `/citation-audit`
+
+For each diff hunk, decide one of:
+
+| Hunk character | Action |
+|----------------|--------|
+| Clean editorial improvement | Sync into `paper/`, no audit needed |
+| Numerical / claim change | Sync, then re-run `/paper-claim-audit` |
+| New `\cite{...}` | Sync, then re-run `/citation-audit` |
+| Half-sentence / obvious typo | Flag to user, do NOT auto-sync |
+| New section / restructure | Stop, ask user before syncing |
+
+After deciding per-hunk:
+
+```bash
+# Sync only the files the user approved into local paper/
+rsync -av paper-overleaf/sec/0.abstract.tex paper/sec/0.abstract.tex
+# (or use Edit tool for surgical changes that skip half-sentences)
+```
+
+### `push` — after local editing
+
+Use after ARIS skills have edited `paper/` and you want collaborators on Overleaf to see the changes.
+
+```bash
+# 1. Always pull first to surface remote drift
+cd paper-overleaf && git pull --ff-only
+
+# 2. If pull was a no-op, sync local paper → paper-overleaf
+rsync -av --delete \
+  --exclude='.git' --exclude='.DS_Store' \
+  --exclude='*.aux' --exclude='*.log' --exclude='*.bbl' --exclude='*.blg' \
+  --exclude='*.fls' --exclude='*.fdb_latexmk' --exclude='*.out' \
+  --exclude='*.synctex.gz' --exclude='*.toc' \
+  paper/ paper-overleaf/
+
+# 3. Show what would be pushed
+git status --short
+git diff --stat
+
+# 4. Commit + push
+git add -A
+git commit -m "<descriptive message — what ARIS changed and why>"
+git push
+```
+
+**Commit message protocol**: include the ARIS skill that produced the change so collaborators on Overleaf understand provenance. Examples:
+
+- `paper-write: regenerated sec/3.assurance after audit cascade refactor`
+- `citation-audit: fix 14 metadata entries (madaan2023, lee2024, ...)`
+- `paper-claim-audit: correct sec/5 numbers vs results/run_2026_04_19.json`
+
+**Confirmation gate**: `push` writes to a shared resource. ALWAYS show the user `git diff --stat` (and a representative hunk for prose changes) before running `git push`. Wait for explicit confirmation unless the user said `auto: true` upfront.
+
+### `status` — diagnostic
+
+```bash
+cd paper-overleaf
+git fetch
+echo "=== Remote-vs-local divergence ==="
+git log --oneline HEAD..origin/master    # remote ahead
+git log --oneline origin/master..HEAD    # local ahead
+echo "=== paper/ vs paper-overleaf/ divergence ==="
+diff -rq --brief paper/ paper-overleaf/ 2>/dev/null \
+  | grep -v "Only in paper/.*\.\(aux\|log\|out\|fls\|fdb_latexmk\|bbl\|blg\|synctex\|toc\)" \
+  | grep -v "Only in paper-overleaf/.git" \
+  | grep -v "DS_Store"
+```
+
+Three-way state assessment:
+
+| Remote ahead? | paper/ vs paper-overleaf/ differ? | Meaning | Recommended action |
+|:-------------:|:---------------------------------:|---------|--------------------|
+| No  | No  | Clean       | Nothing to do |
+| Yes | No  | Overleaf has new edits | Run `pull`, then re-run status |
+| No  | Yes | Local ARIS edits unsynced | Run `push` |
+| Yes | Yes | Diverged — needs merge | Stop, surface to user, do NOT auto-resolve |
+
+## Conflict Resolution
+
+If `git pull --ff-only` fails because of true divergence:
+
+1. **Do not** run `git pull` (which would auto-merge).
+2. **Do not** run `git reset --hard` or `git push --force` (destructive).
+3. Show the user `git log origin/master ^HEAD` (their Overleaf commits) and `git log HEAD ^origin/master` (local ARIS commits).
+4. Ask the user which side to take per file, or to manually merge in Overleaf and then re-pull.
+
+## Token Security — Defense in Depth
+
+Behavioral rules alone are not enough — the next agent reading this skill might forget them. The skill therefore relies on **technical guards** that hold even if the agent misbehaves:
+
+| Layer | Guard | Where enforced |
+|-------|-------|---------------|
+| 1. Setup | `overleaf_setup.sh` refuses to run without an interactive TTY (agents don't have one) | `tools/overleaf_setup.sh` |
+| 2. Input | Token is read by `read -s` (hidden prompt, no shell history, never enters chat) | `tools/overleaf_setup.sh` |
+| 3. Storage | Token goes straight into OS keychain via `git credential approve`; remote URL is stripped to a token-free form | `tools/overleaf_setup.sh` |
+| 4. Commits | `paper-overleaf/.git/hooks/pre-commit` greps staged content for `olp_[A-Za-z0-9]{20,}` and aborts | auto-installed by setup script |
+| 5. Audit | `overleaf_audit.sh` scans working tree, remote URLs, git history, credential files | `tools/overleaf_audit.sh` |
+
+Behavioral rules (still apply, but secondary):
+
+- **Never** ask the user to paste a token into chat. If they do anyway: (a) acknowledge it, (b) tell them to revoke it at https://www.overleaf.com/user/settings, (c) recover via keychain if already primed.
+- **Never** write a token to a file (`.env`, `.netrc`, `tools/*.sh`, etc.) committed to any repo.
+- **Never** include a token in a `git remote -v` URL — strip it after clone.
+- On `401 Unauthorized` from push/pull, tell the user the keychain entry expired and to re-run `overleaf_setup.sh`. Do **not** ask for a fresh token.
+
+## Mutual-Exclusion Rule
+
+The single biggest source of pain in two-way sync is **simultaneous editing on both sides**.
+
+- If the user is in an active Overleaf editing session, ARIS skills should **read-only** access `paper/` until the user runs `/overleaf-sync pull`.
+- If ARIS is in the middle of `/auto-paper-improvement-loop` or `/paper-write`, the user should pause Overleaf editing until the loop finishes and `/overleaf-sync push` is run.
+
+When in doubt, run `status` first.
+
+## Output Contract
+
+- `paper-overleaf/` directory at repo root, git clone of Overleaf project (origin URL has NO token)
+- `paper/` directory unchanged in role — still the ARIS working copy
+- Each `pull`/`push` operation: a one-line summary back to the user (commits pulled / pushed, file count, link to Overleaf project URL)
+
+## See Also
+
+- `/paper-claim-audit` — re-run after pulling Overleaf changes that touch numbers
+- `/citation-audit` — re-run after pulling Overleaf changes that add/edit `\cite{...}`
+- `/paper-compile` — local LaTeX build; Overleaf compiles independently in the cloud
+- Overleaf Git bridge docs: https://www.overleaf.com/learn/how-to/Using_Git_and_GitHub