/overleaf-sync

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):

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

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:

# 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.

# 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