Arxiv Package

---
name: arxiv-package
description: 'Package a TeX/LaTeX project into a clean tarball or zip for arXiv upload: file selection, build-artifact exclusion, 00README.XXX generation, ancillary file organization, archive validation. Triggers on: "package for arXiv", "create arXiv tarball", "bundle submission", "zip for arXiv", "prepare arXiv upload", "arXiv submission archive". Companion to arxiv-preflight and arxiv-figures.'
metadata:
  version: 1.0.0
  complements: [arxiv-preflight, arxiv-figures, manuscript-review]
  category: review
  tags: [arxiv, packaging, tarball, latex, submission]
  difficulty: intermediate
  phase: ship
---

# arXiv Submission Packager

## Purpose

Assemble a TeX/LaTeX project into a clean, correctly structured `.tar.gz` or
`.zip` archive ready for arXiv upload. Handles file selection, artifact
exclusion, directory structure, 00README generation, and validation of the
final package.

Companion skills:
- `arxiv-preflight` — validate before packaging
- `arxiv-figures` — optimize figures before packaging

## Workflow

### 1. Inventory

Scan the project directory. Classify every file:

**INCLUDE — Required**
- Main `.tex` file(s)
- All `\input`/`\include` targets (recursively trace)
- All `\includegraphics` targets
- `.bbl` files (pre-processed bibliography)
- `.ind` files (pre-processed index)
- `.gls`/`.nls` files (glossary/nomenclature)
- Custom `.sty`, `.cls`, `.bst` files not in TeX Live
- `00README.XXX` (if present)
- `anc/` directory contents (ancillary files)

**EXCLUDE — Build Artifacts**
- `.aux`, `.log`, `.toc`, `.lot`, `.lof`, `.out`, `.nav`, `.snm`, `.vrb`
- `.dvi`, `.ps`, `.pdf` (except figure PDFs and ancillary PDFs)
- `.synctex`, `.synctex.gz`, `.fls`, `.fdb_latexmk`
- `.blg`, `.ilg`, `.glg`, `.nlg` (log files from bib/index/glossary processing)
- `*.bak`, `*~`, `*.swp`, `*.swo` (editor backups)
- `.DS_Store`, `Thumbs.db`, `desktop.ini` (OS artifacts)

**EXCLUDE — Should Not Submit**
- Journal templates / style guides (unless custom `.sty` needed for compilation)
- Referee letters, cover letters
- Build scripts (`Makefile`, `latexmkrc`) — not needed by arXiv
- `.git/`, `.svn/`, version control directories
- IDE configs (`.vscode/`, `.idea/`, `.texpadtmp/`)

**FLAG — Needs Decision**
- `.bib` files (include alongside `.bbl` or omit — arXiv processes both)
- Multiple `.tex` files with `\documentclass` (needs `00README.XXX` with `toplevelfile`)
- Large data files (ancillary or exclude)

### 2. Generate 00README.XXX

Create or update the `00README.XXX` file when needed:

```
# Auto-generated by arxiv-package

# Main TeX file (only if ambiguous — multiple \documentclass files)
main.tex toplevelfile

# Files to exclude from processing
cover-letter.pdf ignore
notes.txt ignore

# Optional directives
# nostamp
# nohypertex
```

Only generate if:
- Multiple `.tex` files contain `\documentclass` (declare `toplevelfile`)
- Files need explicit `ignore` directives
- User requests `nostamp` or other directives

### 3. Validate Structure

Before creating the archive:

1. All `\input`/`\include` targets resolve to files in the package
2. All `\includegraphics` targets resolve to files in the package
3. All `\bibliography` targets have corresponding `.bbl` files
4. No absolute paths in any TeX source
5. No filenames with spaces or special characters
6. `anc/` directory contains no `.tex` files
7. No hidden files (will be deleted by arXiv upon announcement)
8. Total uncompressed size is reasonable (flag >50MB — may need exception request)

### 4. Create Archive

```bash
# From project root, create tar.gz excluding unwanted files
tar czf submission.tar.gz \
  --exclude='*.aux' --exclude='*.log' --exclude='*.toc' \
  --exclude='*.lot' --exclude='*.lof' --exclude='*.out' \
  --exclude='*.nav' --exclude='*.snm' --exclude='*.vrb' \
  --exclude='*.dvi' --exclude='*.synctex*' \
  --exclude='*.fls' --exclude='*.fdb_latexmk' \
  --exclude='*.blg' --exclude='*.ilg' --exclude='*.glg' \
  --exclude='*.bak' --exclude='*~' --exclude='*.swp' \
  --exclude='.git' --exclude='.svn' \
  --exclude='.DS_Store' --exclude='Thumbs.db' \
  --exclude='.vscode' --exclude='.idea' \
  [list of files/directories to include]

# Or create zip
zip -r submission.zip [files] \
  -x '*.aux' -x '*.log' -x '*.toc' ...
```

Prefer explicit file inclusion over directory-wide inclusion with exclusions.
This prevents accidental inclusion of sensitive or unnecessary files.

### 5. Verify Archive

After creation:

1. List archive contents — verify no unexpected files
2. Extract to temporary directory
3. Attempt compilation in the extracted directory (if TeX toolchain available)
4. Report archive size (compressed and uncompressed)
5. Compare file list against the include/exclude inventory

### 6. Report

```markdown
# arXiv Package Report

**Archive:** submission.tar.gz
**Compressed size:** [size]
**Uncompressed size:** [size]
**File count:** [count]

## Contents

| File | Size | Type |
|------|------|------|
| main.tex | 45 KB | Source |
| references.bbl | 12 KB | Bibliography |
| fig1.pdf | 380 KB | Figure |
| anc/data.csv | 1.2 MB | Ancillary |

## Excluded

| File | Reason |
|------|--------|
| main.aux | Build artifact |
| main.log | Build artifact |
| referee-response.pdf | Not for submission |

## 00README.XXX

[Contents if generated]

## Verification

- [ ] Archive extracts cleanly
- [ ] All source references resolve
- [ ] Compilation succeeds (if tested)
- [ ] No sensitive files included
```

## Archive Format Notes

- `.tar.gz` preferred over `.zip` (standard in academic TeX workflows)
- arXiv accepts both `.tar` (gzipped) and `.zip`
- Do not nest archives (no `.tar.gz` inside a `.zip`)
- Files should be at root level or in logical subdirectories — no wrapper directory
  unless the project uses subdirectories for organization

## Core Principles

- **Explicit inclusion over blanket exclusion.** Build the file list from what's
  needed, not from everything minus what's not needed. This catches files that
  shouldn't be submitted but aren't in the exclusion list.
- **Verify after packaging.** The archive is the submission. Test it, not the
  source directory.
- **Preserve directory structure.** If the project uses subdirectories for figures
  or sections, maintain that structure. TeX paths depend on it.
- **No sensitive files.** Check for `.env`, credentials, personal notes, referee
  correspondence before packaging.