Overleaf Setup

---
name: overleaf-setup
description: Use once when a LaTeX project needs Overleaf synchronization with Warranted citation enforcement. Installs/authenticates leaf, binds a local LaTeX directory to an Overleaf project, and writes the Stop hook that pushes staged source with prop_N citations expanded.
---

## Goal

Configure automatic Overleaf push so that every `.tex` edit triggers a push without further agent involvement. The skill ends when the hook is written to `settings.local.json` and the user has been told to restart Claude Code.

---

## Step 1 — Install

```bash
uv tool install overleaf-for-agents
```

Verify:

```bash
leaf --version
```

---

## Step 2 — Authenticate

```bash
leaf login
```

A browser window opens. Tell the user: "Log in to Overleaf and wait for your project dashboard to appear. Let me know when ready."

Verify after confirmation:

```bash
leaf list
```

**Fallback** — if `leaf login` fails (no Chrome / CDP error):
1. Ask the user to open https://www.overleaf.com, log in, then go to DevTools → Application → Cookies → copy the value of `overleaf_session2` (starts with `s%3A`)
2. Write the value to `~/.olauth`
3. Retry `leaf list`

---

## Step 3 — Choose or create project, and local directory

Ask the user whether they want to sync to an existing project or create a new one.

**Existing project**: run `leaf list`, show the output, ask which project to use. Record `PROJECT_ID` (24-char hex).

**New project**: ask for a project name, then run:
```bash
leaf create "NAME"
```
Record `PROJECT_ID` from the output.

Also ask which local directory contains the LaTeX files. Record `LATEX_DIR` (absolute path).

---

## Step 4 — Init

```bash
leaf init --project PROJECT_ID --dir LATEX_DIR
```

This writes `leaf.toml` into `LATEX_DIR`. The push script copies it into staging on each run.

---

## Step 5 — Write the hook

Determine `SKILL_DIR` (absolute path to `${CLAUDE_PLUGIN_ROOT}/skills/overleaf-setup`) and `DB_PATH` (absolute path to `.toulmin/graph.db`).

Merge the following into `.claude/settings.local.json`, preserving any existing hooks:

```json
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "uv run SKILL_DIR/scripts/overleaf-push.py --dir LATEX_DIR --db DB_PATH --require-prop-cites",
        "timeout": 120,
        "statusMessage": "Checking citations and pushing to Overleaf..."
      }]
    }]
  }
}
```

Replace `LATEX_DIR`, `SKILL_DIR`, and `DB_PATH` with the actual absolute paths before writing.

---

## Step 6 — Done

Tell the user:

> "Hook configured. **Please restart Claude Code** to activate it — hooks only take effect after a restart, and restarting also clears this setup context.
> After restart, Overleaf will be updated automatically at the end of each conversation turn. Turns where no files under `LATEX_DIR` changed are skipped."

The skill is complete. Do not proceed further.

---

## Error handling reference

| Error | Fix |
|-------|-----|
| `leaf.toml not found` on push | Re-run Step 4 |
| CSRF / 401 / 403 | Session expired — re-run Step 2 |
| HTTP 422 | Re-run Step 4 |
| `~/.olauth` missing | Not logged in — re-run Step 2 |
| Proposition IDs not in map | The proposition has no PDF attached — attach the paper file in Warranted before the next edit |
| Proposition does not exist | Repoint `prop_N` to an existing proposition; never create a replacement merely to preserve an obsolete number |
| Only non-PDF attachments | Attach the original paper PDF. Notes, tables, and extracted text may remain attached but cannot provide a bibliography key |
| Attached PDF is missing | Restore the file at the reported project-relative path, or update the proposition attachment before retrying |
| PDF stem absent from `.bib` | Rename the PDF so its stem equals the intended BibTeX key, or add the matching entry to the LaTeX project's `.bib` file |
| Several PDF attachments | Supported: `\cite{prop_N}` expands to every distinct PDF stem. Every PDF must exist and every stem must appear in a project `.bib` file |
| Several attachments including notes | Supported: non-PDF attachments remain audit evidence but are ignored for citation expansion; at least one valid original-paper PDF is still required |
| `legacy citation key statement_N` | The key points into the archived Statement graph. Re-identify the finding it cited, create or reuse a proposition, and repoint the key — never map by number |