flonat-research 0.1.0

package/skills/update-focus/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: update-focus
+description: "Use when you need to update current-focus.md with a structured session summary."
+allowed-tools: Read, Edit, Bash(git log*), Bash(date*), Bash(ls*)
+---
+
+# Update Focus Skill
+
+> Structured end-of-session update to `.context/current-focus.md` that preserves the document's full structure.
+
+## Purpose
+
+The stop hook nudges to update `current-focus.md` at session end, but ad-hoc edits risk flattening its rich structure. This skill handles session rotation, open loop management, and targeted questions — so the file stays useful as a working memory between sessions.
+
+## When to Use
+
+- At the end of a work session (triggered by stop hook or manually)
+- When the user says "update my focus", "save where I left off", "update current focus"
+- After `/session-log` if `current-focus.md` wasn't updated
+
+## Canonical Document Structure
+
+`current-focus.md` follows this structure — **always preserve it**:
+
+```markdown
+# Current Focus
+
+> Update this file regularly...
+
+## This Week's Focus (w/c YYYY-MM-DD)
+
+### Primary Goal
+[One sentence]
+
+### Active Projects (Top 3)
+1. **[Project]** - [Status/phase]
+2. **[Project]** - [Status/phase]
+3. **[Project]** - [Status/phase]
+
+### Waiting On
+- [ ] [Person] - [What] - [Since when]
+
+### Upcoming Deadlines
+| Deadline | What | Project |
+|----------|------|---------|
+
+## Recent Context
+
+### Last Session Summary (YYYY-MM-DD — [Title])
+- [Bullet points of what happened]
+
+### Previous Session (YYYY-MM-DD — [Title])
+- [Bullet points]
+
+### Previous Session (YYYY-MM-DD — [Title])
+- [Bullet points]
+
+### Previous Session (YYYY-MM-DD — [Title])
+- [Bullet points]
+
+### Open Loops
+Things I started but haven't finished:
+- [ ] [Item]
+- [x] [Completed item — remove on next update]
+
+### Mental State
+[Optional: How are you feeling about work?]
+
+---
+
+## Quick Reference
+
+### Key Meetings This Week
+- [Day]: [Meeting] with [Person] about [Topic]
+
+### Papers in Active Revision
+- [Paper title] - [Journal] - [Stage]
+
+---
+```
+
+## Workflow
+
+### Step 1: Read current state
+
+Read these three sources to understand what happened:
+
+1. `.context/current-focus.md` — current file contents
+2. Latest file in `log/` — most recent session log (if one was created)
+3. `git log --oneline -10` — recent commits for concrete evidence of work done
+
+Also note today's date for week rollover detection.
+
+### Step 2: Detect week rollover
+
+Compare the `w/c` date in `## This Week's Focus (w/c YYYY-MM-DD)` against today's date.
+
+- If today is in a **new week** (Monday-based), flag that weekly sections need updating.
+- If same week, skip weekly section updates.
+
+Week rollover means: Primary Goal, Active Projects Top 3, Waiting On, Upcoming Deadlines, and Key Meetings may all need refreshing.
+
+### Step 3: Draft session summary
+
+From the session context (conversation history, commits, log), draft a summary in the **same bullet-point format** as existing entries:
+
+```markdown
+### Last Session Summary (YYYY-MM-DD — [Short Title])
+- [What was done, in bullet points]
+- [Key decisions or outputs]
+- [Files/commits if relevant]
+```
+
+Keep it concise — 3-6 bullet points. Match the style of existing entries.
+
+### Step 4: Ask targeted questions (2-4 max)
+
+Ask only what's needed. Skip questions where the answer is obvious from context.
+
+**Always ask:**
+1. "Does this session summary look right?" (show the draft)
+2. "Any open loops to add or check off?" (show current list with proposed changes marked)
+
+**Ask only if relevant:**
+3. "How are you feeling about work?" — only if Mental State is still a placeholder (`[Optional: ...]`)
+4. "Has your primary goal or top 3 changed?" — only on **week rollover**
+
+Present questions concisely with proposed answers. Let the user confirm or adjust.
+
+### Step 5: Apply the update
+
+Use `Edit` to make targeted changes. **Never rewrite the whole file.**
+
+#### Session rotation rules
+
+- **Rename** the current `### Last Session Summary (...)` to `### Previous Session (...)`
+- **Insert** the new `### Last Session Summary (...)` in its place
+- **Keep a maximum of 4 session entries** in Recent Context (1 Last + 3 Previous)
+- If there are already 4 entries, **delete the oldest** Previous Session
+- Preserve the exact header format: `### Last Session Summary (YYYY-MM-DD — Title)` for the newest, `### Previous Session (YYYY-MM-DD — Title)` for older ones
+
+#### Open loop management
+
+- **Check off** items that were completed this session (change `- [ ]` to `- [x]`)
+- **Remove** items marked `[x]` from previous sessions (they've been acknowledged)
+- **Add** new open loops identified during the session
+- Keep the intro line: `Things I started but haven't finished:`
+
+#### Other updates
+
+- Update **Mental State** if the user provided one
+- Update **weekly sections** if week rollover was detected and the user confirmed changes
+- Update **Quick Reference** if meetings or paper revisions changed
+- Update **Waiting On** if new blockers emerged or old ones resolved
+
+### Step 6: Confirm
+
+Report what was changed:
+
+```
+Updated .context/current-focus.md:
+- Session: [title] added to Recent Context
+- Open loops: [N checked off, M added]
+- [Any other changes]
+```
+
+If no session log was created this session, offer: "Want me to run `/session-log` too?"
+
+## Integration with Other Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `/session-log` | Creates the detailed log; `/update-focus` updates the working memory. Often run together. |
+| `/save-context` | For ad-hoc saves to any context file. Defers to `/update-focus` for structured focus updates. |
+| `vault sync (edit vault files directly)` | Updates `projects/_index.md` and vault. For full session-level focus updates, defers to `/update-focus`. |
+
+## Example Interaction
+
+**Claude:** Here's what I'd update in `current-focus.md`:
+
+**Session summary:**
+```
+### Last Session Summary (2026-02-08 — Update Focus Skill)
+- Created `/update-focus` skill for structured current-focus.md updates
+- Updated stop hook, session-log, and update-context with cross-references
+- Updated CLAUDE.md skills list (16 → 17)
+```
+
+**Open loops — proposed changes:**
+- [x] ~~Commit all pending changes~~ (done this session)
+- [ ] Test new skills on CAPE-MOBO or MRes paper *(keep)*
+- [ ] Try replication protocol on a real paper *(keep)*
+- **New:** [ ] Test `/update-focus` skill end-to-end
+
+Does this look right? Any open loops to add or change?
+
+**the user:** Looks good, also check off the replication one, I decided to skip it.
+
+**Claude:** Got it. *[Applies edits]* Updated `.context/current-focus.md`:
+- Session: "Update Focus Skill" added to Recent Context
+- Open loops: 2 checked off, 1 added
+- Previous sessions rotated (oldest dropped)
+
+Want me to run `/session-log` too?

package/skills/update-project-doc/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: update-project-doc
+description: "Use when you need to update a project's own CLAUDE.md, README.md, or docs/ to reflect current state."
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash(ls*), Bash(git log*), Bash(git diff*), Bash(readlink*), Bash(wc*), Bash(date*), AskUserQuestion
+argument-hint: (no arguments)
+---
+
+# Update Project Doc — Refresh Stale Documentation
+
+> Scan a project's documentation files and update sections that have drifted from reality: file trees, timestamps, bibliography counts, next steps, skill/hook tallies, and more.
+
+## When to Use
+
+- After significant project work (new files, completed milestones, structural changes)
+- During `/general-session-recap` when offered
+- When the user says "update project docs", "refresh docs", "sync my docs", "update my README"
+- Periodically to keep documentation accurate
+
+## What It Does NOT Do
+
+- Never rewrites research content (hypotheses, arguments, literature, design decisions)
+- Never deletes sections — only updates factual/structural content within existing sections
+- Never creates new documentation files — only updates existing ones
+
+---
+
+## Protocol
+
+### Step 1: Detect Documentation Files
+
+Find all documentation files in the project:
+
+1. Check for `CLAUDE.md` in project root
+2. Check for `README.md` in project root
+3. Scan `docs/` and `docs/*/` for `.md` files containing file trees or counts
+4. Note which files exist — only update what's present
+
+**Special case:** Some projects (e.g., the political information paper) have no `CLAUDE.md` because they use a committed `README.md` as their primary project documentation instead. This is intentional for repos meant to be shared or published. In these cases, treat `README.md` as the main documentation file and apply all the same checks to it.
+
+Read each detected file to understand its current content.
+
+### Step 2: Gather Current State
+
+Collect the actual state of the project:
+
+1. **File tree** — use `ls -R` or `Glob` to build the actual directory structure (respect `.gitignore` patterns, skip `out/`, `__pycache__/`, `.venv/`, `node_modules/`)
+2. **Recent git history** — `git log --oneline -20` for recent commits
+3. **Session logs** — read the latest 1-2 files in `log/` (if the directory exists)
+4. **Bibliography count** — count entries in any `.bib` file(s): `grep -c '@' *.bib`
+5. **Symlink targets** — `readlink` on any documented symlinks
+6. **Context files** — read `.context/current-focus.md` or `.context/project-recap.md` if present
+
+**Task Management only** (detected by presence of `skills/` directory):
+7. **Skill count** — count directories in `skills/` that contain `SKILL.md`
+8. **Hook count** — count `.sh` files in `hooks/` (if present)
+9. **Skill lengths** — `wc -l skills/*/SKILL.md` to identify bloated skills
+
+**Leanness data** (all projects):
+10. **CLAUDE.md line count** — `wc -l CLAUDE.md`
+11. **CLAUDE.md section sizes** — count lines per `##` section
+12. **README.md line count** — `wc -l README.md`
+13. **SKILL.md line counts** — (Task Management only) `wc -l skills/*/SKILL.md`
+14. **Duplication scan** — check if CLAUDE.md content duplicates what's already in README.md, docs/, or .context/ files
+15. **Agent line counts** — `wc -l .claude/agents/*.md` (if present)
+16. **Context file line counts** — `wc -l .context/*.md` (if present)
+
+### Step 3: Run Staleness Checks
+
+Compare gathered state against documented content. Flag any mismatches:
+
+| Check | How to Detect |
+|-------|--------------|
+| **File tree** | Generate actual tree, compare against any tree/structure block in docs (look for ``` blocks or indented listings with file paths) |
+| **Timestamps** | Flag "Last updated", "w/c", or date stamps older than 7 days |
+| **Bibliography count** | Compare actual `.bib` entry count vs any documented count (e.g., "42 references") |
+| **Next steps / roadmap** | Cross-reference items against recent commits and session logs — flag items that appear completed |
+| **Manuscript status** | Flag sections marked "TODO", "incomplete", or "placeholder" that now have content |
+| **Symlinks** | Verify documented symlink targets still resolve with `readlink` |
+| **Skill/hook counts** | (Task Management only) Compare actual count vs documented numbers in CLAUDE.md, README.md, and `.tex` files |
+| **Venue/target info** | If CLAUDE.md documents a target journal, check it matches `.context/projects/_index.md` (if accessible) |
+
+### Step 3b: Leanness Audit
+
+Using the data gathered in Step 2 (items 10-14), check infrastructure file sizes against thresholds. This applies to **all projects**, not just Task Management.
+
+| File | Threshold | What to flag | Fix |
+|------|-----------|-------------|-----|
+| `CLAUDE.md` | > 200 lines total | Current line count | Extract reference sections to `docs/`, replace with pointers (see `lean-claude-md` rule) |
+| `CLAUDE.md` sections | Any `##` section > 15 lines of reference material | Section name + line count | Extract to `docs/` with a one-line summary + link |
+| `CLAUDE.md` duplication | Content duplicated from README/docs/.context | Which content is duplicated and where | Keep only the pointer in CLAUDE.md |
+| `README.md` | > 300 lines total | Current line count | Extract long sections to `docs/` |
+| `SKILL.md` files | > 300 lines each (TM only) | File name + line count | Move templates/examples/report formats to `references/` or `templates/` subdirectory |
+| Project agents (`.claude/agents/*.md`) | > 400 lines each | File name + line count | Extract verbose prompt sections to companion files |
+| Context files (`.context/*.md`) | > 200 lines each | File name + line count | Archive stale content, keep current |
+
+**What counts as "reference material"** (extractable): assessment guidelines, detailed literature notes, long examples, report templates, checklists, reviewer feedback.
+
+**What does NOT count** (keep in place): safety rules, conventions, folder structure trees, session continuity pointers.
+
+Present leanness findings separately from staleness findings in Step 4.
+
+### Step 4: Propose Changes
+
+Present findings grouped by file:
+
+```
+Staleness report for [Project Name]:
+
+CLAUDE.md:
+  - File structure tree is outdated (missing: X, Y; removed: Z)
+  - Skill count says 23, actual is 26
+  - "Last updated" date is 3 weeks old
+
+README.md:
+  - Directory structure block needs updating
+  - Next steps: "Write introduction" appears completed (commit abc1234)
+  - Bibliography count says 38, actual is 42
+
+docs/overview.md:
+  - No issues detected
+
+Leanness:
+  - CLAUDE.md: 237 lines (threshold: 200) — ## Assessment section is 42 lines of guidelines
+  - README.md: OK (189 lines)
+```
+
+If nothing is stale, report that and stop.
+
+### Step 5: Ask for Confirmation
+
+#### Step 5a: Staleness Fixes
+
+Use `AskUserQuestion` to let the user approve, modify, or skip staleness fixes:
+
+- **Apply all** — update everything proposed
+- **Select by file** — choose which files to update
+- **Skip** — make no changes
+
+#### Step 5b: Offer Leanness Fixes
+
+If Step 3b found leanness issues, present each as an individually actionable item:
+
+```
+Leanness fixes available:
+
+| # | File | Issue | Current | Fix |
+|---|------|-------|---------|-----|
+| 1 | CLAUDE.md | >200 lines | 237 | Extract ## Assessment section → docs/ |
+| 2 | skills/X/SKILL.md | >300 lines | 382 | Move checklists → references/ |
+```
+
+Use `AskUserQuestion` with `multiSelect: true`:
+- **Question:** "Which leanness fixes do you want to apply?"
+- One option per fix with current size and proposed outcome
+- Include an **"All of them"** option as the first choice
+
+**Do not defer or merely report leanness findings.** Always present them as actionable items alongside staleness fixes.
+
+### Step 6: Apply and Report
+
+For each approved change:
+
+1. Use **targeted `Edit` operations** — never rewrite entire files
+2. Preserve all surrounding content
+3. When updating file trees, match the existing formatting style (├──, |--, indented, etc.)
+4. When updating counts, find the exact number and replace it
+5. When marking next-step items as done, use strikethrough (~~item~~) rather than deleting
+
+After all edits, print a summary:
+
+```
+Updated project docs:
+  CLAUDE.md:  file tree, skill count (23 → 26)
+  README.md:  directory structure, bib count (38 → 42), 1 next-step marked complete
+  Total: 5 edits across 2 files
+```
+
+---
+
+## Key Rules
+
+1. **Targeted edits only** — never rewrite entire files. Use `Edit` with precise `old_string` / `new_string`.
+2. **Preserve research content** — hypotheses, questions, literature reviews, design decisions, and arguments are sacred. Only update factual/structural sections.
+3. **Always show before applying** — never make silent edits. The proposal step is mandatory.
+4. **Match existing style** — if the project uses `├──` trees, don't switch to `|--`. If counts use "X total", don't change to "X skills".
+5. **Works in any project** — not just Task Management. Adapt checks to what's present.
+6. **Idempotent** — running twice in a row should produce no changes the second time.
+
+## Cross-References
+
+- `/general-session-recap` — offers to run this skill at Step 3.5
+- `/sync-repo private` — Task Management-specific superset: propagates counts across all private TM docs including LaTeX files. Run after this skill when in the TM project.
+- `vault sync (edit vault files directly)` — syncs state to the central context library (complementary; run after this)
+- `/update-focus` — updates `current-focus.md` (different purpose: session state, not doc accuracy)

package/skills/validate-bib/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: validate-bib
+description: "Cross-reference \\cite{} keys against .bib files or embedded \\bibitem entries. Finds missing, unused, and typo'd citation keys. Deep verification mode spawns parallel agents for DOI/metadata validation at scale. Read-only in standard mode."
+allowed-tools: Read, Glob, Grep, Task, Write, Bash(mkdir*), Bash(ls*), Bash(rm*)
+argument-hint: [project-path or tex-file]
+---
+
+# Bibliography Validation
+
+**Read-only skill.** Never edit source files — produce a categorised report only.
+
+**Citation key rule:** the user's existing keys always take precedence. They come from Paperpile (his reference management system) and are canonical. When suggesting replacements (typo corrections, preprint upgrades, metadata fixes), always keep the user's key and update the `.bib` entry metadata around it — never suggest renaming a key to match some "standard" format.
+
+## When to Use
+
+- Before compiling a final version of a paper
+- After adding new citations to check nothing was missed
+- When `biber`/`bibtex` reports undefined citations
+- As part of a pre-submission checklist (pair with `/proofread`)
+
+## When NOT to Use
+
+- **Finding new references** — use `/literature` for discovery
+- **Building a bibliography from scratch** — use `/literature` with `.bib` generation
+- **General proofreading** — use `/proofread` (which also flags citation format issues)
+
+## Phase 0: Session Log (Suggested)
+
+Bibliography validation with preprint staleness checks can be context-heavy (OpenAlex lookups, web searches for published versions). Before starting, **suggest** running `/session-log` to capture prior work as a recovery checkpoint. If the user declines, proceed without it.
+
+## Convention
+
+**Default bibliography file is `paperpile.bib`** — this is the standard across all projects (per the `/latex` skill convention). However, the skill also supports:
+
+- Any `.bib` file found in the same directory as the `.tex` files being audited
+- Embedded bibliographies using `\begin{thebibliography}` / `\bibitem{key}` blocks
+- Both external and embedded simultaneously (rare but possible)
+
+## Bibliography Detection
+
+At the start of validation, detect which bibliography method the project uses:
+
+### 1. External `.bib` file (standard)
+
+Look for `.bib` files in the project directory. Priority order:
+1. `paperpile.bib` (preferred — standard naming convention across all projects)
+2. Any other `.bib` file in the same directory as the `.tex` files
+
+If **multiple `.bib` files** are found, validate all of them and produce a combined report. Note which file each issue belongs to. If `paperpile.bib` exists alongside other `.bib` files, flag the extras as a potential cleanup opportunity (the project may have migrated from a different naming convention).
+
+Full validation applies: cross-reference checks **and** quality checks.
+
+### 2. Embedded `\begin{thebibliography}` / `\bibitem{key}`
+
+Some LaTeX documents define references inline rather than using an external `.bib` file. Detect by scanning `.tex` files for `\begin{thebibliography}`.
+
+Extract keys from `\bibitem` entries:
+- `\bibitem{key}` — standard form, key is the argument in braces
+- `\bibitem[label]{key}` — optional label form (e.g., `\bibitem[Smith et al., 2020]{smith2020}`), key is in the **second** set of braces
+
+Only **cross-reference checks** apply (missing keys, unused keys, typos). Quality checks (required fields, year, author formatting) are **skipped** because embedded bibliographies don't have structured metadata.
+
+### 3. Both (rare)
+
+If a project has both a `.bib` file and `\begin{thebibliography}` blocks, validate both:
+- Run full validation on the `.bib` file
+- Run cross-reference checks on `\bibitem` entries
+- Merge both key sets when checking for missing citations
+
+## Workflow
+
+1. **Find files**: Locate all `.tex` files in the project
+2. **Detect bibliography type**: Check for `.bib` files and/or `\begin{thebibliography}` blocks
+3. **Extract citation keys from .tex**: Scan for all citation commands
+4. **Extract entry keys from bibliography source(s)**:
+   - External: Parse all `@type{key,` entries from `.bib` file(s)
+   - Embedded: Parse all `\bibitem{key}` and `\bibitem[label]{key}` entries
+5. **Cross-reference**: Compare the two sets
+6. **Quality checks**: Validate `.bib` entry completeness (external only)
+7. **Produce report**: Write results to stdout (or save if requested)
+
+## Citation Commands to Scan
+
+Scan `.tex` files for all of these patterns:
+
+| Command | Example |
+|---------|---------|
+| `\cite{key}` | Basic citation |
+| `\citet{key}` | Textual: Author (Year) |
+| `\citep{key}` | Parenthetical: (Author, Year) |
+| `\textcite{key}` | biblatex textual |
+| `\autocite{key}` | biblatex auto |
+| `\parencite{key}` | biblatex parenthetical |
+| `\citeauthor{key}` | Author name only |
+| `\citeyear{key}` | Year only |
+| `\nocite{key}` | Include in bibliography without in-text citation |
+
+Also handle **multi-key citations**: `\citep{key1, key2, key3}`
+
+## Cross-Reference Checks
+
+### Critical: Missing Entries
+
+Citation keys used in `.tex` but not defined in the bibliography source (`.bib` file or `\bibitem` entries).
+
+These will cause compilation errors.
+
+### Warning: Unused Entries
+
+Keys defined in the bibliography source but never cited in any `.tex` file.
+
+Not errors, but may indicate:
+- Forgotten citations (should they be `\nocite`?)
+- Leftover entries from earlier drafts
+- Entries intended for a different paper
+
+### Warning: Possible Typos (Fuzzy Match)
+
+For each missing key, check if a similar key exists in the bibliography using edit distance:
+- Edit distance = 1: Very likely a typo
+- Edit distance = 2: Possibly a typo
+- Flag these with the suggested correction
+
+Common typo patterns:
+- Year off by one: `smith2020` vs `smith2021`
+- Missing/extra letter: `santanna` vs `sant'anna` vs `santana`
+- Underscore vs camelCase: `smith_jones` vs `smithjones`
+
+## Quality Checks on .bib Entries
+
+**These checks apply only to external `.bib` files.** Embedded bibliographies lack structured metadata, so quality checks are skipped for them.
+
+### Required Fields by Entry Type
+
+| Entry Type | Required Fields |
+|-----------|----------------|
+| `@article` | author, title, journal, year |
+| `@book` | author/editor, title, publisher, year |
+| `@incollection` | author, title, booktitle, publisher, year |
+| `@inproceedings` | author, title, booktitle, year |
+| `@techreport` | author, title, institution, year |
+| `@unpublished` | author, title, note, year |
+| `@phdthesis` | author, title, school, year |
+
+### Year Reasonableness
+
+- Flag entries with year < 1900 or year > current year + 1
+- Flag entries with no year at all
+
+### Author Formatting
+
+- Check for inconsistent author formats within the file
+- **Flag entries where author field contains "and others" or "et al."** — this is never valid in BibTeX. All authors must be listed explicitly. Severity: **Warning**.
+- Flag entries with organisation names that might need `{{braces}}` to prevent splitting
+
+### DOI Resolution (optional — triggered by `--verify-dois` flag or when issues are suspected)
+
+**Preferred method: biblio MCP `scholarly_verify_dois`.** Collect all DOIs from the `.bib` file and call `scholarly_verify_dois` (up to 50 per call). This batch-verifies each DOI against all enabled sources (OpenAlex, Scopus, WoS). Results:
+- **VERIFIED** (2+ sources confirm) — DOI is valid, metadata can be trusted
+- **SINGLE_SOURCE** (1 source only) — DOI exists but warrants a manual spot-check
+- **NOT_FOUND** — DOI not found in any source; resolve manually via WebFetch
+
+**Fallback for NOT_FOUND DOIs:** Resolve via `https://doi.org/[DOI]` and confirm the returned metadata matches the entry:
+
+1. **Title match**: Does the DOI landing page title match the `.bib` title?
+2. **Author match**: Does the first author on the landing page match the `.bib` first author?
+3. **Journal match**: Does the venue match?
+
+Flag mismatches as:
+- **Warning: DOI mismatch** — DOI resolves to a different paper than claimed. This usually means the DOI is wrong (adjacent DOI in the same journal volume) or the authors are wrong (conflation of researchers in the same subfield).
+
+This check catches:
+- Wrong DOIs (e.g., off-by-one in the DOI suffix)
+- Author conflation (real researchers incorrectly attributed to a paper)
+- Metadata copied from secondary sources without verification
+
+For manual WebFetch resolution, process in batches of 5 to avoid rate limiting. Only flag confirmed mismatches — if the DOI cannot be resolved (404, timeout), note it as "unresolvable" at Info level.
+
+### Preprint Staleness Check
+
+**For every entry that looks like a preprint**, check whether a peer-reviewed version has since been published. Full detection signals, lookup protocol, and classification: [`references/preprint-check.md`](references/preprint-check.md)
+
+## Severity Levels
+
+| Level | Meaning |
+|-------|---------|
+| **Critical** | Missing entry for a cited key — will cause compilation error |
+| **Warning** | Unused entry, possible typo, missing required field |
+| **Info** | Year oddity, formatting suggestion, bibliography type note |
+
+## Bibliography Output
+
+After validation, offer these actions if applicable:
+
+- **Embedded bibliography → offer to create `paperpile.bib`**: If the project uses `\begin{thebibliography}`, offer to extract the references into a proper `paperpile.bib` file (one `@misc` entry per `\bibitem`, with the full text as a `note` field). The author can then enrich the entries with proper metadata.
+- **Non-standard `.bib` name → offer to rename**: If the existing `.bib` file is not named `paperpile.bib`, offer to rename it to `paperpile.bib` and update the `\bibliography{}` command in the `.tex` file.
+
+These are **offers only** — do not make changes without explicit confirmation.
+
+## Report Format
+
+Full report template with all sections: [`references/report-template.md`](references/report-template.md)
+
+Sections: Summary table → Critical (missing entries) → Warning (typos, unused, missing fields, DOI mismatches, stale preprints) → Info (year issues) → Limitations (for embedded bibliographies).
+
+## Optional: Metadata Verification via Biblio MCP
+
+When missing entries or suspicious metadata are flagged, use the biblio MCP tools:
+
+- **`scholarly_search`** — search by title to find the correct entry across OpenAlex + Scopus + WoS
+- **`scholarly_verify_dois`** — batch-verify DOIs across all sources (preferred over manual DOI resolution)
+- **`openalex_lookup_doi`** — look up full metadata for a specific DOI
+
+For Python client fallback (citation networks, institution analysis): [`references/openalex-verification.md`](references/openalex-verification.md)
+
+## Deep Verification Mode (Parallel, Disk-Based)
+
+Triggered by: `--deep-verify` flag, 40+ entries, or "deep verify" / "verify all references". Spawns parallel sub-agents that verify batches and write results to disk. Full architecture, batch JSON format, and assembly: [references/deep-verify.md](references/deep-verify.md)
+
+## Council Mode (Optional)
+
+For high-stakes submissions. Trigger: "council validate-bib", "thorough bib check". Full details: [references/council-mode.md](references/council-mode.md)
+
+## Quality Scoring
+
+When producing a full validation report, apply numeric quality scoring using the shared framework:
+
+- **Framework:** [`../shared/quality-scoring.md`](../shared/quality-scoring.md) — severity tiers, thresholds, verdict rules
+
+Map validation findings to the framework tiers:
+- **Critical** (-15 to -25): Missing entry for a cited key (compilation error)
+- **Major** (-5 to -14): DOI mismatch, stale preprint with published version available, "et al." in author field
+- **Minor** (-1 to -4): Missing optional fields, year oddities, unused entries
+
+Compute the score and include the Score Block in the report after the summary table.
+
+## Cross-References
+
+- **`/proofread`** — For overall paper quality including citation format
+- **`/literature`** — For finding and adding new references (includes full OpenAlex workflows)
+- **`/latex`** — For compilation with reference checking
+- **`/latex-autofix`** — For compilation and error resolution. Run after fixing bibliography issues to verify citations compile cleanly.

package/skills/validate-bib/references/council-mode.md

@@ -0,0 +1,34 @@
+# Council Mode for Bibliography Validation
+
+> For high-stakes submissions, run bibliography validation in council mode. Different models have different knowledge of the academic literature -- one model may know a paper's correct DOI while another catches a metadata mismatch that the first misses.
+
+## When to Trigger
+
+- "Council validate-bib"
+- "Thorough bib check"
+
+## How It Works
+
+1. The main session collects all `\cite{}` keys and `.bib` entries
+2. The prompt is sent to 3 models via `cli-council`
+3. Each model independently cross-references keys, checks for typos, and verifies metadata
+4. Cross-review catches false positives (flagged entries that are actually correct) and surfaces additional issues
+5. Chairman synthesis produces a single `VALIDATION-REPORT.md`
+
+## Invocation (CLI backend -- free)
+
+```bash
+cd packages/cli-council
+uv run python -m cli_council \
+    --prompt-file /tmp/validate-bib-prompt.txt \
+    --context-file /tmp/bib-and-tex-content.txt \
+    --output-md /tmp/validate-bib-council.md \
+    --chairman claude \
+    --timeout 180
+```
+
+See `skills/shared/council-protocol.md` for the full orchestration protocol.
+
+## Value
+
+Moderate to high -- most valuable in deep verification mode where DOI/metadata accuracy matters. Different models have genuinely different bibliographic knowledge.