flonat-research 0.1.0

package/skills/latex/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: latex
+description: "Use when you need to compile a LaTeX document or manage LaTeX projects."
+allowed-tools: Bash(latexmk*), Bash(xelatex*), Bash(pdflatex*), Bash(biber*), Bash(bibtex*), Bash(mkdir*), Bash(ls*), Read, Write, Edit
+argument-hint: [tex-file-path]
+---
+
+# LaTeX Document Compilation
+
+## Critical Rules
+
+1. **Build artifacts go to `out/`, but the PDF stays in the source directory.** Before compiling, check for `.latexmkrc` — if missing, create one with the standard config (see Output Directory section). The `.latexmkrc` uses a Perl `END {}` block to copy the PDF back to the source directory after each build.
+2. **NEVER write BibTeX entries from memory.** Always verify against web sources (CrossRef, Google Scholar, DOI lookup) before writing. See the `literature` skill.
+3. **Check document class before adding packages.** Some classes load packages internally (e.g., `elsarticle` loads `natbib` — adding `\usepackage{natbib}` causes errors).
+
+## Overleaf-Synced Projects
+
+When a project is synced to Overleaf (via Dropbox or Git):
+- The `out/` directory will sync to Overleaf but Overleaf ignores it — this is fine
+- Always use `.latexmkrc` to enforce `out/` — Overleaf ignores this file too
+- Overleaf compiles independently on its server; local compilation is for verification only
+- The `.bst` file (e.g., `elsarticle-harv.bst`) lives in the source directory, not `out/`
+
+## When NOT to Use
+
+- Markdown documents — use plain markdown, not LaTeX
+- Quick notes or drafts — LaTeX overhead not worth it
+- Documents that don't need citations, equations, or precise formatting
+
+## Local-Only Projects (No Overleaf)
+
+Not all projects sync to Overleaf. For local-only projects:
+- The same `out/` and `.latexmkrc` conventions apply — this keeps the working directory clean regardless of sync method
+- There is no `paper/` symlink — `.tex` files live directly in the project root or a subdirectory
+- Use `/latex-autofix` for compilation — it handles `.latexmkrc` creation if missing
+
+## Templates
+
+### Working Paper Template
+
+When creating a **new working paper**, use the template. The canonical location is the local git repo:
+
+1. `templates/latex-wp/` (in Task Management — canonical source, git-tracked)
+
+The template contains:
+
+| File | Purpose |
+|------|---------|
+| `main.tex` | Document entry point with structure |
+| `your-template.sty` | Packages, layout, formatting, math environments |
+| `your-bib-template.sty` | Bibliography config (biblatex, source cleanup, Harvard style) |
+| `references.bib` | Bibliography file (initially empty) |
+| `out/` | Compilation output directory |
+
+**To create a new working paper:**
+
+1. Copy the template files to your new project folder
+2. Rename as needed
+3. Update `main.tex` with your title, author, abstract
+4. Add references to `references.bib`
+5. Compile with `latexmk main.tex`
+
+### Citation Style Toggle
+
+The template uses **biblatex/biber** with a toggle for Harvard vs generic authoryear style.
+
+In `main.tex`, control the style via package option:
+
+```latex
+\usepackage[harvard]{your-bib-template}    % Harvard style (default)
+\usepackage[noharvard]{your-bib-template}  % Generic authoryear style
+```
+
+**Harvard style features:**
+- Author names: Family, G.
+- Volume in bold, issue in parentheses
+- DOI/URL shown as "Available at: ..."
+- No dashes for repeated authors
+
+### Bibliography File Naming
+
+**Always name the bibliography file `references.bib`** — for any paper, whether using the working paper template or not. This is the standard naming convention across all projects.
+
+### Bibliography Commands
+
+The template uses biblatex. In `main.tex`:
+
+```latex
+\printbibliography  % (not \bibliography{references})
+```
+
+If you need natbib instead, do not load `your-bib-template` and use:
+```latex
+\bibliographystyle{agsm}
+\bibliography{references}
+```
+
+**Note:** This template is for working papers only. Other document types (presentations, theses, etc.) may require different templates.
+
+---
+
+## Output Directory
+
+All LaTeX build artifacts (`.aux`, `.log`, `.bbl`, `.fls`, etc.) go to an `out/` subfolder relative to the source file. The **PDF is copied back** to the source directory after each successful build, so it lives alongside the `.tex` file for easy access. This keeps the working directory clean while keeping the deliverable visible.
+
+## Configuration
+
+The PDF-copy convention is enforced in **two places** — keep them in sync when making changes:
+
+1. **`.latexmkrc`** (per-project) — Perl `END {}` block copies PDF after terminal/Claude Code builds
+2. **VS Code `.vscode/settings.json`** (per-workspace) — explicit latexmk args in LaTeX Workshop tool definition
+
+Place a `.latexmkrc` in the project root to enforce output directory automatically.
+
+VS Code integration, engine auto-detection (pdfLaTeX/XeLaTeX/LuaLaTeX), manual override configs, reference checking scripts, and manual compilation commands:
+
+**[references/latex-configs.md](references/latex-configs.md)**
+
+---
+
+## LaTeX Skill Hierarchy
+
+Three compilation skills exist for different scopes. Use this decision tree:
+
+```
+Need to compile LaTeX?
+├── Single project, want auto error resolution?
+│   └── /latex-autofix  (default — 5 iterations, citation audit, quality score)
+├── Single project, need manual control or config reference?
+│   └── /latex  (this skill — .latexmkrc setup, engine selection, VS Code config)
+└── Multiple projects / fleet-wide health check?
+    └── /latex-health-check  (project discovery, 3 iterations per project, cross-project checks)
+```
+
+| Skill | Scope | Iterations | Extra features |
+|-------|-------|------------|----------------|
+| `/latex` | Single project | Manual | Config reference, engine auto-detection, VS Code integration |
+| `/latex-autofix` | Single project | Up to 5 | Auto error fix, citation audit, quality score |
+| `/latex-health-check` | All projects | Up to 3 each | Project discovery, symlink integrity, Overleaf separation, template drift |
+
+**Rule of thumb:** Use `/latex-autofix` by default. Use `/latex` when you need to understand or configure the build system. Use `/latex-health-check` for periodic maintenance.

package/skills/latex/references/latex-configs.md

@@ -0,0 +1,183 @@
+# LaTeX Configuration Reference
+
+> VS Code integration, engine auto-detection, manual overrides, and reference checking scripts.
+> Referenced from `SKILL.md` — the parent file has a summary + pointer.
+
+## VS Code LaTeX Workshop Gotchas
+
+1. **`.latexmkrc` in subdirectories is NOT picked up.** LaTeX Workshop runs latexmk from the workspace root, not the `.tex` file's directory. Subdirectory `.latexmkrc` files are ignored. Fix: pass `-cd -lualatex -outdir=out` (or `-cd -pdf -outdir=out` for pdfLaTeX) explicitly in the VS Code tool args. The `-cd` flag makes latexmk change to the `.tex` file's directory before running.
+2. **`% !TEX program` magic comments override custom recipes.** LaTeX Workshop looks for a tool whose name matches the program (e.g., `lualatex`). If no match, it falls back to a default recipe that ignores `-outdir`. Fix: set `"latex-workshop.latex.build.forceRecipeUsage": true` in `.vscode/settings.json`.
+
+### Recommended `.vscode/settings.json` for LuaLaTeX projects
+
+```json
+{
+  "latex-workshop.latex.tools": [
+    {
+      "name": "latexmk",
+      "command": "latexmk",
+      "args": [
+        "-cd",
+        "-lualatex",
+        "-outdir=out",
+        "-interaction=nonstopmode",
+        "-halt-on-error",
+        "-synctex=1",
+        "%DOC%"
+      ],
+      "env": {}
+    }
+  ],
+  "latex-workshop.latex.recipes": [
+    {
+      "name": "latexmk (LuaLaTeX → out/)",
+      "tools": ["latexmk"]
+    }
+  ],
+  "latex-workshop.latex.outDir": "%DIR%/out",
+  "latex-workshop.latex.build.forceRecipeUsage": true
+}
+```
+
+Swap `-lualatex` for `-pdf` (pdfLaTeX) or `-xelatex` as needed. The `.latexmkrc` remains the authority for terminal builds.
+
+---
+
+## Auto-detecting Engine
+
+This config automatically uses XeLaTeX if the document or any `\input{}`/`\include{}` file contains `\usepackage{fontspec}`, otherwise falls back to pdfLaTeX:
+
+```perl
+# .latexmkrc
+$out_dir = 'out';
+
+# Copy PDF back to source directory after build
+END { system("cp $out_dir/*.pdf . 2>/dev/null") if defined $out_dir; }
+
+# Recursively check for fontspec in main file and all \input{}/\include{} files
+sub needs_xelatex {
+    my ($file, $seen) = @_;
+    $seen //= {};
+
+    # Normalize and check if already visited
+    return 0 if $seen->{$file};
+    $seen->{$file} = 1;
+
+    # Try with and without .tex extension
+    my $filepath = -e $file ? $file : -e "$file.tex" ? "$file.tex" : undef;
+    return 0 unless $filepath;
+
+    open(my $fh, '<', $filepath) or return 0;
+    my $dir = $filepath =~ s|/[^/]*$||r;  # Directory of current file
+    $dir = '.' if $dir eq $filepath;
+
+    while (<$fh>) {
+        return 1 if /\\usepackage.*\{fontspec\}/;
+
+        # Recurse into \input{} and \include{} files
+        if (/\\(?:input|include)\{([^}]+)\}/) {
+            my $subfile = $1;
+            $subfile = "$dir/$subfile" unless $subfile =~ m|^/|;
+            return 1 if needs_xelatex($subfile, $seen);
+        }
+    }
+    close($fh);
+    return 0;
+}
+
+# Auto-detect engine
+$pdf_mode = 1;  # Default to pdflatex
+foreach my $file (@ARGV) {
+    if (needs_xelatex($file)) {
+        $pdf_mode = 5;  # Switch to xelatex
+        last;
+    }
+}
+
+$pdflatex = 'pdflatex -interaction=nonstopmode -halt-on-error %O %S';
+$xelatex = 'xelatex -interaction=nonstopmode -halt-on-error %O %S';
+```
+
+---
+
+## Manual Override Configs
+
+If auto-detection doesn't suit a project, use one of these explicit configs:
+
+**pdfLaTeX** (standard LaTeX fonts):
+```perl
+# .latexmkrc
+$out_dir = 'out';
+$pdf_mode = 1;
+$pdflatex = 'pdflatex -interaction=nonstopmode -halt-on-error %O %S';
+END { system("cp $out_dir/*.pdf . 2>/dev/null") if defined $out_dir; }
+```
+
+**XeLaTeX** (system fonts, Unicode, OpenType features):
+```perl
+# .latexmkrc
+$out_dir = 'out';
+$pdf_mode = 5;
+$xelatex = 'xelatex -interaction=nonstopmode -halt-on-error %O %S';
+END { system("cp $out_dir/*.pdf . 2>/dev/null") if defined $out_dir; }
+```
+
+---
+
+## Reference Checking
+
+Every compilation must verify that all references resolve correctly. After compilation, check the log and report any issues found.
+
+### Reference Check Script
+
+After running latexmk, check for issues and display them as warnings:
+
+```bash
+# Compile
+latexmk document.tex
+
+# Check for reference issues and report exact problems
+LOGFILE="out/document.log"
+ISSUES=$(grep -E "(Reference.*undefined|Citation.*undefined|multiply defined)" "$LOGFILE" 2>/dev/null)
+
+if [ -n "$ISSUES" ]; then
+    echo ""
+    echo "⚠️  REFERENCE ISSUES DETECTED:"
+    echo "================================"
+    echo "$ISSUES" | while read -r line; do
+        echo "  • $line"
+    done
+    echo "================================"
+    echo ""
+fi
+```
+
+### What to Check For
+
+| Pattern | Meaning |
+|---------|---------|
+| `Reference .* undefined` | `\ref{}` or `\autoref{}` pointing to non-existent label |
+| `Citation .* undefined` | `\cite{}` referencing missing BibTeX entry |
+| `Label .* multiply defined` | Same `\label{}` used more than once |
+
+### Manual Compilation (if not using latexmk)
+
+For biblatex (default in working paper template):
+```bash
+mkdir -p out
+xelatex -output-directory=out document.tex
+biber out/document
+xelatex -output-directory=out document.tex
+xelatex -output-directory=out document.tex
+cp out/document.pdf ./document.pdf
+```
+
+For natbib (if using that instead):
+```bash
+mkdir -p out
+pdflatex -output-directory=out document.tex
+bibtex out/document
+pdflatex -output-directory=out document.tex
+pdflatex -output-directory=out document.tex
+cp out/document.pdf ./document.pdf
+```

package/skills/latex-autofix/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: latex-autofix
+description: "Use when you need to compile LaTeX with autonomous error resolution and citation audit."
+allowed-tools: Bash(latexmk*), Bash(xelatex*), Bash(pdflatex*), Bash(biber*), Bash(bibtex*), Bash(mkdir*), Bash(ls*), Bash(wc*), Bash(cp*), Read, Write, Edit, Grep, Glob
+argument-hint: [tex-file-path]
+---
+
+# LaTeX Auto-Fix Compilation
+
+> Compile LaTeX documents with autonomous error detection and resolution. Wraps the standard `/latex` workflow with a fix-loop that handles the most common compilation failures without manual intervention.
+
+## When to Use
+
+- **Default method** for all LaTeX compilation — use this instead of `/latex` unless you need manual control
+- Any `.tex` file that should compile to PDF
+- When compilation fails and you want automatic diagnosis and repair
+- When you want a post-compilation citation audit
+
+## When NOT to Use
+
+- Quick one-off compilations where you already know the document is clean — `/latex` is fine
+- Documents with exotic custom classes that need manual debugging
+
+---
+
+## Quality Scoring
+
+Apply numeric quality scoring using the shared framework and skill-specific rubric:
+
+- **Framework:** [`../shared/quality-scoring.md`](../shared/quality-scoring.md) — severity tiers, thresholds, verdict rules
+- **Rubric:** [`references/quality-rubric.md`](references/quality-rubric.md) — issue-to-deduction mappings for this skill
+
+Start at 100, deduct per issue found, apply verdict. Include the Score Block in the Phase 5 report.
+
+## Critical Rules
+
+1. **Build artifacts go to `out/`, PDF stays in the source directory.** Ensure `.latexmkrc` exists with `$out_dir = 'out'` and an `END {}` block to copy the PDF back (see pre-flight below). For VS Code builds, `.latexmkrc` in subdirectories is **not picked up** — see `/latex` skill's "VS Code LaTeX Workshop Gotchas" section for the required `.vscode/settings.json` config (`-cd`, `-outdir=out`, `forceRecipeUsage: true`).
+2. **Maximum 5 fix iterations.** If the document still has errors after 5 auto-fix cycles, stop and report the unresolved errors to the user.
+3. **Never silently swallow errors.** Every fix must be reported: what was wrong, what was changed, and which file was edited.
+4. **Preserve user intent.** Auto-fixes should be minimal and conservative. Add packages or overrides — never remove user content.
+5. **Citation audit requires clean compilation.** Only run the `\cite{}` vs `.bib` cross-check after zero errors.
+6. **Run `/bib-validate` when new citations were added.** The Phase 4 citation audit only checks key cross-references. When `.bib` entries were added or modified since the last validation, also run `/bib-validate` for full metadata quality checks (preprint staleness, DOI presence, required fields, author formatting). This is mandatory — do not skip it.
+
+---
+
+## Protocol
+
+### Phase 1: Pre-flight
+
+1. **Locate the `.tex` file.** Resolve the path (absolute or relative to CWD).
+2. **Identify the project directory** — the folder containing the `.tex` file.
+3. **Ensure `.latexmkrc` exists** in the project directory with at minimum:
+   ```perl
+   $out_dir = 'out';
+   # Copy PDF back to source directory after build
+   END { system("cp $out_dir/*.pdf . 2>/dev/null") if defined $out_dir; }
+   ```
+   If a `.latexmkrc` already exists, verify it sets `$out_dir = 'out'` and has the `END {}` block. If either is missing, add it. Do not overwrite other settings.
+4. **Create `out/` directory** if it doesn't exist: `mkdir -p <project-dir>/out`.
+5. **Identify the `.bib` file(s)** referenced in the document (scan for `\bibliography{}`, `\addbibresource{}`, or `\bibinput{}`). Note their paths for Phase 3.
+
+### Phase 2: Compile–Fix Loop
+
+Run up to **5 iterations**. Each iteration:
+
+#### Step 2a — Compile
+
+```bash
+cd <project-dir> && latexmk -interaction=nonstopmode <filename>.tex 2>&1
+```
+
+Capture the full output. The log file will be at `out/<filename>.log`.
+
+#### Step 2b — Read the log
+
+Read `out/<filename>.log` in full. Parse for errors and warnings.
+
+#### Step 2c — Classify errors
+
+Check the log against the known error patterns below. If an error matches, apply the fix and go to Step 2a. If no known pattern matches, record the error as **unresolved** and stop the loop.
+
+---
+
+### Known Error Patterns & Auto-Fixes
+
+Check the log against these patterns. Full fix instructions: [`references/known-errors.md`](references/known-errors.md)
+
+| # | Pattern | Key log signature |
+|---|---------|-------------------|
+| 1 | Missing package | `File '<pkg>.sty' not found` or undefined command from known package |
+| 2 | Font/symbol conflicts | `Command \<name> already defined` |
+| 3 | Undefined citation | `Citation '<key>' ... undefined` or biblatex entry not found |
+| 4 | Missing image/file | `File '<path>' not found` (pdftex.def or LaTeX) |
+| 5 | Stale auxiliary files | Corrupted `.aux`/`.bbl`/`.bcf`, or `no \bibstyle command` |
+| 6 | Beamer/enumitem clash | `Option clash for package enumitem` or `\item already defined` |
+| 7 | xcolor option conflicts | `Option clash for package xcolor` or undefined `\rowcolor` |
+| 8 | TikZ reserved keys | `I do not know the key '/tikz/<name>'` or pgfkeys error |
+
+If an error matches, read the full fix from the reference and apply it. If no pattern matches, record as **unresolved** and stop the loop.
+
+---
+
+### Phase 2.5: PDF Backup (paper directories only)
+
+**Only run if Phase 2 ended with a successful compilation (PDF exists).**
+
+If the `.tex` file is inside a `paper-{venue}/paper/` structure (where `paper/` is a symlink to Overleaf):
+
+1. **Identify the paper wrapper** — the parent of the `paper/` symlink (e.g., `paper-jbdm/`).
+2. **Create the backup directory:** `mkdir -p <paper-wrapper>/backup`
+3. **Copy the PDF:**
+   ```bash
+   cp <paper-wrapper>/paper/<filename>.pdf <paper-wrapper>/backup/<wrapper-name>_vcurrent.pdf
+   ```
+   Example: `paper-jbdm/paper/main.pdf` → `paper-jbdm/backup/paper-jbdm_vcurrent.pdf`
+
+**Detection logic:**
+- The project directory containing the `.tex` file is a symlink named `paper`
+- Its parent directory name starts with `paper-`
+- If either condition is false, skip this phase silently
+
+**Skip if:** compilation failed, or the `.tex` file is not inside a paper directory structure.
+
+---
+
+### Phase 3: Final Report
+
+After the loop ends (either clean compilation or max iterations reached), report:
+
+#### Compilation Status
+
+| Field | Value |
+|-------|-------|
+| **Status** | Clean / Errors remaining |
+| **Iterations** | N of 5 |
+| **Pages** | (from log: `Output written on ... (N pages)`) |
+| **Warnings** | Count of remaining warnings (overfull/underfull hbox, etc.) |
+| **Fixes applied** | List each fix: what error, what was changed, which file |
+| **Unresolved errors** | List any errors that couldn't be auto-fixed |
+
+#### How to extract page count
+
+```bash
+grep -o "Output written on .* ([0-9]* page" out/<filename>.log | grep -o "[0-9]* page"
+```
+
+#### How to count warnings
+
+```bash
+grep -c "Warning" out/<filename>.log
+```
+
+---
+
+### Phase 4: Citation Audit (clean builds only)
+
+**Only run this phase if Phase 2 ended with zero errors.**
+
+1. **Extract all `\cite` keys** from the `.tex` file (and any `\input`/`\include` files):
+   - Match `\cite{...}`, `\citep{...}`, `\citet{...}`, `\textcite{...}`, `\parencite{...}`, `\autocite{...}`, and multi-key variants like `\cite{key1,key2}`.
+2. **Extract all bib entry keys** from the `.bib` file(s): match `@<type>{<key>,`.
+3. **Cross-reference:**
+
+| Check | What it finds |
+|-------|--------------|
+| **Missing in .bib** | Keys cited in `.tex` but absent from `.bib` |
+| **Unused in .tex** | Keys defined in `.bib` but never cited |
+| **Possible typos** | Near-matches between missing cite keys and existing bib keys |
+
+4. **Report** the results as a table. Do not modify any files during the audit — report only.
+
+---
+
+### Phase 5: Quality Score
+
+After all phases complete, compute the quality score:
+
+1. Read [`references/quality-rubric.md`](references/quality-rubric.md) for deduction mappings.
+2. Log every issue from Phases 2-4 (unresolved errors, remaining warnings, citation mismatches).
+3. Compute score (100 - total deductions), apply verdict per [`../shared/quality-scoring.md`](../shared/quality-scoring.md).
+4. Append the Score Block to the compilation report:
+
+```markdown
+## Quality Score
+
+| Metric | Value |
+|--------|-------|
+| **Score** | XX / 100 |
+| **Verdict** | Ship / Ship with notes / Revise / Revise (major) / Blocked |
+
+### Deductions
+
+| # | Issue | Tier | Deduction | Category |
+|---|-------|------|-----------|----------|
+| 1 | [description] | [tier] | -X | [category] |
+| | **Total deductions** | | **-XX** | |
+```
+
+---
+
+## Integration with Other Skills
+
+| Situation | Delegate to |
+|-----------|-------------|
+| Need to find or verify a bibliography entry | `/literature` |
+| Full academic proofreading after clean compilation | `/proofread` |
+| Detailed `.bib` validation beyond cite-key matching | `/bib-validate` |
+| Beamer presentations specifically | `/beamer-deck` (which uses this skill internally for compilation) |
+
+---
+
+## Examples
+
+### Basic usage
+
+> "Compile my paper at `~/papers/mcdm-survey/main.tex`"
+
+Runs the full protocol: pre-flight → compile–fix loop → report → citation audit.
+
+### After fixing a known issue
+
+> "Recompile — I added the missing package manually"
+
+Runs from Phase 2 directly (pre-flight can be skipped if `.latexmkrc` and `out/` already exist).
+
+### Targeted fix
+
+> "My paper won't compile — something about Bbbk"
+
+Identifies as Pattern 2 (font conflict), applies the `\let\Bbbk\relax` fix, recompiles.