flonat-research 0.1.0

package/docs/getting-started.md

@@ -0,0 +1,245 @@
+<!-- Governed by: skills/shared/project-documentation.md -->
+
+# Getting Started
+
+## How to Use Claude Code
+
+Claude Code is the AI engine that reads your CLAUDE.md, runs skills, and executes hooks. You can access it in several ways:
+
+| Interface | Best for | Install |
+|-----------|----------|---------|
+| **[Terminal CLI](https://docs.anthropic.com/en/docs/claude-code)** | Power users, full control, scripting | See install table below |
+| **[VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropics.claude-code)** | Integrated coding + chat in one window | Install from VS Code marketplace |
+| **[JetBrains extension](https://plugins.jetbrains.com/plugin/27189-claude-code)** | IntelliJ, PyCharm, WebStorm users | Install from JetBrains marketplace |
+| **[Web app](https://claude.ai/code)** | Quick access from any browser, no install | Visit claude.ai/code |
+| **[Desktop app](https://claude.ai/download)** | GUI chat (Mac/Windows) | Download from claude.ai |
+
+All interfaces share the same skills, agents, hooks, and rules once you run the setup script. The terminal CLI is the most full-featured and what this guide focuses on, but you can use whichever interface suits your workflow.
+
+**You need an Anthropic account with a Claude subscription** (Max plan recommended for heavy research use).
+
+## Prerequisites
+
+### 1. Package Manager
+
+Install a package manager first — it makes installing everything else easy:
+
+| Platform | Package manager | Install command |
+|----------|----------------|-----------------|
+| **macOS** | [Homebrew](https://brew.sh/) | `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` |
+| **Ubuntu / Debian** | apt | Already included |
+| **Fedora / RHEL** | dnf | Already included |
+| **Arch** | pacman | Already included |
+| **Windows** | [WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/) | Built into Windows 11. On Windows 10, install [App Installer](https://apps.microsoft.com/detail/9nblggh4nns1) from the Microsoft Store. |
+
+### 2. Python (3.11 or later)
+
+Python is required for several hooks (context monitor, compact save/restore) and the bibliography MCP server.
+
+| Platform | Install command | Verify |
+|----------|----------------|--------|
+| **macOS** | `brew install python@3.12` | `python3 --version` |
+| **Ubuntu 24.04+** | `sudo apt install python3.12 python3.12-venv` | `python3 --version` |
+| **Ubuntu 22.04 / Debian 11** | See note below | `python3 --version` |
+| **Fedora 39+** | `sudo dnf install python3.12` | `python3 --version` |
+| **Arch** | `sudo pacman -S python` (ships 3.12+) | `python3 --version` |
+| **Windows** | `winget install Python.Python.3.12` | `python --version` |
+
+> **Why Python 3.11+?** The hooks and MCP servers use modern Python features (`tomllib`, `match` statements, type hints) that require 3.11 or later. Python 3.12 is recommended as the current stable release.
+
+> **Ubuntu 22.04 / Debian 11:** These ship Python 3.10, which is too old. Add the [deadsnakes PPA](https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa) first:
+> ```bash
+> sudo add-apt-repository ppa:deadsnakes/ppa
+> sudo apt update
+> sudo apt install python3.12 python3.12-venv
+> ```
+
+> **Windows note:** The Windows Python installer adds `python` (not `python3`) to your PATH. The hooks in `settings.json` reference `python3` — you may need to adjust these to `python` on Windows, or create an alias. See the [Windows Setup](#windows-setup) section below.
+
+### 3. uv (Python package manager)
+
+| Platform | Install command | Verify |
+|----------|----------------|--------|
+| **macOS** | `brew install uv` | `uv --version` |
+| **Linux** | `curl -LsSf https://astral.sh/uv/install.sh \| sh` | `uv --version` |
+| **Windows** | `winget install astral-sh.uv` | `uv --version` |
+
+> **Why uv instead of pip?** [uv](https://docs.astral.sh/uv/) is a fast Python package manager that handles virtual environments automatically. When Claude runs Python code or installs dependencies, it uses `uv run python` and `uv pip install` instead of bare `python` or `pip`. This prevents conflicts between projects (each gets its own isolated environment) and avoids polluting your system Python. The `settings.json` included with this repo enforces this by blocking bare `python` and `pip` commands.
+
+### 4. Other tools
+
+| Tool | What it's for | macOS | Ubuntu/Debian | Fedora | Arch | Windows |
+|------|--------------|-------|---------------|--------|------|---------|
+| [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) | The engine | `curl -fsSL https://claude.ai/install.sh \| bash` | same | same | same | `winget install Anthropic.ClaudeCode` |
+| [Git](https://git-scm.com/) | Version control | Included | `sudo apt install git` | `sudo dnf install git` | `sudo pacman -S git` | `winget install Git.Git` |
+| [TeX Live](https://tug.org/texlive/) | LaTeX compilation | `brew install --cask mactex` | `sudo apt install texlive-full` | `sudo dnf install texlive-scheme-full` | `sudo pacman -S texlive` | [install guide](https://tug.org/texlive/windows.html) |
+
+**Optional but recommended:**
+- [VS Code](https://code.visualstudio.com/) with the [LaTeX Workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) extension — handles both code and LaTeX in one window
+- [Obsidian](https://obsidian.md/) — for browsing and editing the Research Vault
+
+> **TeX Live on Windows:** The [TeX Live install guide](https://tug.org/texlive/windows.html) walks you through the installer. Alternatively, install [MiKTeX](https://miktex.org/download) which auto-installs missing packages on first use. Either works — just make sure `latexmk` is available in your terminal after installation.
+
+> **TeX Live on Arch:** The `texlive` group installs a minimal set. For full coverage (recommended), use `sudo pacman -S texlive-most texlive-lang`.
+
+## Installation
+
+### macOS / Linux
+
+```bash
+git clone https://github.com/flonat/claude-research.git
+cd claude-research
+./scripts/setup.sh
+```
+
+### Windows
+
+Open **PowerShell** (not Command Prompt) and run:
+
+```powershell
+git clone https://github.com/flonat/claude-research.git
+cd claude-research
+.\scripts\setup.ps1
+```
+
+> **If you get an execution policy error:** Run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` first, then retry. This allows PowerShell to run local scripts.
+
+The setup script creates links in `~/.claude/` so Claude Code can find your skills, agents, hooks, and rules from any project directory.
+
+### What the setup script does
+
+1. Creates `~/.claude/` if it doesn't exist
+2. Links `skills/`, `agents/`, `rules/`, and `hooks/` into `~/.claude/`
+3. Copies `settings.json` (first install only — preserved on updates)
+4. Checks that Python, uv, Git, and LaTeX are installed
+5. Creates `log/` directories for session continuity
+
+## Linux Notes
+
+Linux is the most straightforward platform — hooks run natively and paths work out of the box. A few things to check:
+
+### Hook permissions
+
+After cloning, make sure hook scripts are executable:
+
+```bash
+chmod +x hooks/*.sh hooks/*.py
+```
+
+The setup script handles this, but if you copy files manually or reset permissions, hooks will silently fail without `+x`.
+
+### Python version
+
+Many distros ship an older Python as the system default. Check with `python3 --version`. If it's below 3.11, install a newer version alongside it (the deadsnakes PPA on Ubuntu, or your distro's package for Python 3.12). The system Python is untouched — uv manages its own environments.
+
+### `~/.claude/` location
+
+On Linux, `~` resolves to `/home/youruser/`. Claude Code looks for `~/.claude/` there. If you use a non-standard `$HOME`, verify the symlinks point correctly after setup.
+
+## Windows Setup
+
+Windows works well with Claude Code but needs a few adjustments:
+
+### Shell hooks
+
+The `.sh` hook scripts require a Unix-like shell. Two options:
+
+1. **Git Bash (recommended):** Installed automatically with Git for Windows. Claude Code can use Git Bash to run `.sh` scripts. Make sure Git Bash is in your PATH (the Git installer does this by default).
+
+2. **WSL (Windows Subsystem for Linux):** If you prefer a full Linux environment, [install WSL](https://learn.microsoft.com/en-us/windows/wsl/install) with `wsl --install`. You can then run the Linux setup inside WSL.
+
+### Python command name
+
+Windows installs Python as `python` (not `python3`). The hook configuration in `settings.json` uses `python3`. You have two options:
+
+**Option A — Create a `python3` alias** (recommended):
+```powershell
+# Find where python.exe is
+where python
+# Create a copy named python3.exe in the same directory
+Copy-Item (Get-Command python).Source ((Get-Command python).Source -replace 'python\.exe','python3.exe')
+```
+
+**Option B — Edit `settings.json`** to replace `python3` with `python`:
+Open `~/.claude/settings.json` and replace every occurrence of `"python3 "` with `"python "` in the hooks section.
+
+### Path separators
+
+Claude Code handles path separators automatically. You don't need to change `/` to `\` in any configuration files.
+
+## Customise Your Context
+
+Edit these files with your own details:
+
+- `.context/profile.md` — Your name, institution, research areas, supervisors
+- `.context/current-focus.md` — What you're working on right now
+- `.context/projects/_index.md` — Your active research projects
+- `CLAUDE.md` — Conventions and tool preferences
+
+## Configure Settings
+
+Edit `.claude/settings.json` to adjust:
+- Allowed/denied commands
+- Hook configuration
+- Model preferences
+
+## Start Using It
+
+```bash
+cd ~/your-research-project
+claude
+```
+
+Claude will automatically load your context, skills, and rules. Try:
+
+- "Plan my day" — Daily planning with task queries
+- "Extract actions from my meeting" — Turn transcripts into tasks
+- `/proofread` — Academic proofreading for a LaTeX paper
+- `/latex-autofix` — Compile LaTeX with automatic error fixing
+- `/bib-validate` — Check citation keys against your `.bib` file
+- `/literature` — Search for academic papers and manage bibliography
+- `/session-recap` — End-of-session checklist (update focus, log, sync)
+- `/code-review` — 11-category quality review for R/Python scripts
+
+## Adding a New Research Project
+
+1. Create a directory for your project
+2. Add a `CLAUDE.md` in the project with project-specific instructions
+3. Symlink `paper/` to your Overleaf directory (if applicable)
+4. Add the project to `.context/projects/_index.md`
+5. Create a paper file in `.context/projects/papers/`
+
+## Adding Your Own Skills
+
+Create a new directory in `skills/` with a `SKILL.md` file:
+
+```
+skills/my-custom-skill/
+└── SKILL.md
+```
+
+The `SKILL.md` needs YAML frontmatter with `name`, `description`, and optionally `allowed-tools`. See any existing skill for the format.
+
+## Troubleshooting
+
+### "uv: command not found"
+
+uv isn't installed or isn't in your PATH. Install it using the commands in the [uv section](#3-uv-python-package-manager) above, then restart your terminal.
+
+### "python3: command not found" (Windows)
+
+Windows uses `python` instead of `python3`. See the [Python command name](#python-command-name) section above.
+
+### Hooks not running
+
+1. Check that `~/.claude/settings.json` exists and contains the `"hooks"` section
+2. Verify the hook files are executable: `ls -la ~/.claude/hooks/` (macOS/Linux) or check they exist in `%USERPROFILE%\.claude\hooks\` (Windows)
+3. On Windows, ensure Git Bash is in your PATH for `.sh` hooks
+
+### LaTeX skills fail with "latexmk not found"
+
+Install a TeX distribution — see the [Other tools](#4-other-tools) section. After installing, restart your terminal so `latexmk` is in your PATH.
+
+### "Execution policy" error on Windows
+
+Run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` in PowerShell, then retry the setup script.

package/docs/hooks.md

@@ -0,0 +1,38 @@
+# Hooks
+
+> 8 hook scripts that run automatically at key moments in Claude Code sessions.
+
+Hook scripts live in `hooks/` and are configured in `~/.claude/settings.json` under the `"hooks"` key.
+
+## Overview
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `block-destructive-git.sh` | Before Bash | catches dangerous git/shell commands |
+| `context-monitor.py` | After tool use | tracks tool call count as a heuristic for context usage |
+| `postcompact-restore.py` | After compact | restores state after context compression |
+| `precompact-autosave.py` | Before compact | saves state before context compression |
+| `promise-checker.sh` | Session stop | catches "performative compliance": Claude says it remembered/noted/saved |
+| `protect-source-files.sh` | Before edit/write | prompts confirmation for files outside |
+| `resume-context-loader.sh` | Session resume | surfaces current focus and latest session log |
+| `startup-context-loader.sh` | Session start | auto-detects and surfaces project documentation |
+
+## Hook Events
+
+| Event | When it fires | Matcher options |
+|-------|---------------|-----------------|
+| `SessionStart` | Session begins | `startup` (fresh), `resume` (continuing), `compact` (after compaction) |
+| `PreToolUse` | Before a tool runs | Tool name(s), e.g. `Bash`, `Edit\|Write` |
+| `PostToolUse` | After a tool runs | Tool name(s), e.g. `Bash\|Task` |
+| `Stop` | Claude stops responding | *(empty = always)* |
+| `PreCompact` | Before context compression | *(empty = always)* |
+
+## Configuration
+
+All hooks are configured in `~/.claude/settings.json`. See the `settings.json` file for the full configuration.
+
+## Creating New Hooks
+
+1. Write a shell or Python script in `hooks/`
+2. Add an entry to `~/.claude/settings.json` under the appropriate event key
+3. Set the `matcher` to control when it fires

package/docs/mcp-servers.md

@@ -0,0 +1,82 @@
+# MCP Servers
+
+MCP (Model Context Protocol) servers extend Claude with external tools and data sources. This infrastructure uses several MCP servers across Claude Code and Claude Desktop.
+
+## Server Inventory
+
+| Server | Claude Code | Claude Desktop | Type | Purpose |
+|--------|:-----------:|:--------------:|------|---------|
+| **bibliography** | `.mcp.json` | `claude_desktop_config.json` | Self-hosted | Multi-source scholarly search (OpenAlex + Scopus + WoS) |
+| **user-papers** | `.mcp.json` | `claude_desktop_config.json` | Self-hosted | Zotero library management (search, PDF, semantic, BibTeX) |
+| **context7** | `.mcp.json` | `claude_desktop_config.json` | npm | Up-to-date library/API documentation lookup |
+| **github** | `~/.claude.json` (user) | `claude_desktop_config.json` | HTTP remote | GitHub repos, PRs, issues, code search |
+| **filesystem** | -- | `claude_desktop_config.json` | npm | Read/write access to project folder (Desktop only) |
+| **skills-server** | -- | `claude_desktop_config.json` | Self-hosted | Exposes skills, agents, and context library to Desktop |
+| **cloudflare** | `.mcp.json` | `claude_desktop_config.json` | npm | Cloudflare Workers, KV, R2, D1 (optional) |
+| **gcloud** | `.mcp.json` | `claude_desktop_config.json` | npm | Google Cloud Platform via gcloud CLI (optional) |
+
+**Config locations:**
+
+| Config | Scope | Servers |
+|--------|-------|---------|
+| `.mcp.json` | Project-level | bibliography, user-papers, context7, cloudflare, gcloud |
+| `~/.claude.json` (user scope) | Global (all projects) | github |
+| `claude_desktop_config.json` | Claude Desktop | All servers above |
+
+## Custom Servers
+
+### Bibliography MCP Server
+
+Multi-source scholarly search across OpenAlex (free, always available), Scopus, and Web of Science.
+
+**Setup guide:** [`bibliography-setup.md`](bibliography-setup.md)
+
+### Flonat-Papers MCP Server (Zotero)
+
+Zotero library management with 14 tools: search, PDF text extraction, semantic retrieval (ChromaDB), BibTeX export, and write operations.
+
+**Location:** `packages/user-papers/`
+
+**Skills bundled:** `bib-validate`, `bib-parse` (symlinked to `skills/`)
+
+### Skills Server (Desktop only)
+
+Exposes skills, agents, and the context library to Claude Desktop. Claude Code loads these directly from `~/.claude/skills/` and `.claude/agents/`.
+
+**Location:** `.mcp-server-desktop/` (or `.mcp-server-biblio/` in the public repo)
+
+## Third-Party Servers
+
+### Context7
+
+Fetches up-to-date documentation for any library or framework. Useful because Claude's training data has a knowledge cutoff.
+
+- `resolve-library-id` — finds the library's documentation source
+- `query-docs` — fetches relevant documentation pages and code examples
+
+**Install:** `npx -y @upstash/context7-mcp` (add to `.mcp.json`)
+
+### GitHub
+
+GitHub integration via Copilot MCP endpoint. Provides repos, PRs, issues, commits, and code search.
+
+**Type:** HTTP remote at `api.githubcopilot.com/mcp` with OAuth token
+
+### Filesystem (Desktop only)
+
+Standard `@modelcontextprotocol/server-filesystem` — gives Claude Desktop read/write access to the project folder. Not needed in Claude Code (which has direct file access).
+
+### Cloudflare (optional)
+
+Cloudflare developer platform — Workers, KV, R2, D1, routes, zones, secrets, cron triggers. Only needed if you deploy web applications on Cloudflare.
+
+### gcloud (optional)
+
+Google Cloud Platform via the gcloud CLI. Only needed if you use GCP services.
+
+## Adding a New MCP Server
+
+1. **Stdio servers** (self-hosted or npm): add to `.mcp.json` (project-level)
+2. **HTTP remote servers**: add to `~/.claude.json` with user scope
+3. **Claude Desktop**: add to `~/Library/Application Support/Claude/claude_desktop_config.json`
+4. Always configure both clients if the server should be available everywhere

package/docs/notion-setup.md

@@ -0,0 +1,109 @@
+<!-- Governed by: skills/shared/project-documentation.md -->
+
+# Notion Integration Setup
+
+The task management system uses **two Notion databases** to track your work:
+
+1. **Tasks Tracker** — individual tasks with status, priority, due dates, and project links
+2. **Research Pipeline** — paper-level tracking with stages (Idea → Literature Review → Drafting → Submitted → R&R → Published), target journals, and co-authors
+
+Together with the local context library (`.context/`), these create a hybrid system: Notion handles dynamic task data, while local files handle persistent context that Claude reads every session.
+
+## How It Works
+
+```
+You say "plan my day"
+        │
+        ▼
+Claude reads .context/current-focus.md     ← what you're working on
+Claude reads .context/workflows/daily-review.md  ← how to help you plan
+Claude queries Notion Tasks Tracker        ← overdue/due today/high priority
+        │
+        ▼
+Claude asks orientation questions           ← energy, commitments, yesterday's work
+        │
+        ▼
+Claude helps you prioritise                 ← based on your answers + context
+        │
+        ▼
+Claude updates .context/current-focus.md   ← so next session picks up where you left off
+```
+
+## Available Workflows
+
+| You say | What happens |
+|---------|-------------|
+| "Plan my day" | Reads context, queries Notion for tasks, asks questions, creates a plan |
+| "What should I work on?" | Reviews priorities and helps you decide |
+| "Extract actions from my meeting" | Finds transcript, extracts tasks, creates them in Notion |
+| "Weekly review" | Guides reflection: what got done, what didn't, what emerged, next week's Big 3 |
+| "What's overdue?" | Queries Notion and summarises |
+| "Update my research pipeline" | Shows paper status, helps update stages and target journals |
+| "Sync this project" (`/sync-notion`) | Propagates project state: CLAUDE.md → context library → Notion |
+
+## Step 1: Enable the Notion MCP
+
+The Notion integration uses **Claude.ai's managed Notion integration** — a built-in MCP server that Claude Code can connect to. No self-hosted server needed.
+
+1. Go to [claude.ai/settings/integrations](https://claude.ai/settings/integrations)
+2. Connect your Notion workspace
+3. Grant access to the pages/databases Claude should see
+
+Once connected, Claude Code automatically has access to Notion tools (`notion-search`, `notion-fetch`, `notion-create-pages`, `notion-update-page`, etc.).
+
+## Step 2: Create the Databases
+
+You need two Notion databases. Create them anywhere in your workspace.
+
+**Tasks Tracker** — for individual tasks:
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| Task name | Title | Action verb + specific object (e.g., "Draft methods section") |
+| Status | Select | Not started, In progress, Done |
+| Priority | Select | High, Medium, Low |
+| Due date | Date | When it's due |
+| Project | Select | Which research project this belongs to |
+| Source | Select | Meeting, Email, Supervisor request, Self-initiated |
+| Task type | Select | Writing, Reading, Research, Meeting, Admin, Communication |
+
+**Research Pipeline** — for paper-level tracking:
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| Paper name | Title | Working title of the paper |
+| Stage | Select | Idea, Literature Review, Drafting, Data Collection, Analysis, Submitted, R&R, Published |
+| Target Journal | Rich text | Where you plan to submit |
+| Co-authors | Rich text | Collaborators |
+| Priority | Select | High, Medium, Low |
+| Status | Rich text | Brief status note |
+
+## Step 3: Add Database IDs to CLAUDE.md
+
+1. Open each database in Notion
+2. Copy the database ID from the URL (the 32-character hex string after your workspace name: `notion.so/workspace/DATABASE_ID_HERE?v=...`)
+3. Add them to `CLAUDE.md`:
+
+```markdown
+## Notion Databases
+
+| Database | ID |
+|----------|-----|
+| Tasks Tracker | `your-tasks-database-id-here` |
+| Research Pipeline | `your-pipeline-database-id-here` |
+```
+
+Claude reads these IDs from `CLAUDE.md` and uses them to query and update your databases.
+
+## Step 4: Start Using It
+
+```bash
+claude
+> Plan my day
+```
+
+Claude will read your context, query Notion, ask you orientation questions, and help you prioritise.
+
+## Graceful Degradation
+
+If the Notion MCP is unavailable (not connected, network issues), skills automatically fall back to local-only mode — they still read `.context/` files and help you plan, they just can't query or update Notion. You'll see a note when this happens.

package/docs/rules.md

@@ -0,0 +1,33 @@
+# Rules
+
+> 9 auto-loaded instruction files that shape Claude's behavior in every session.
+
+Rule files live in `.claude/rules/` and are automatically loaded into every Claude Code session.
+
+## Overview
+
+| Rule | File | What it does |
+|------|------|-------------|
+| Design Before Results | `design-before-results.md` | Lock the research design before examining point estimates. |
+| Ignore AGENTS.md Files | `ignore-agents-md.md` | Never read, process, or act on files named `AGENTS.md` |
+| Ignore GEMINI.md Files | `ignore-gemini-md.md` | Never read, process, or act on files named `GEMINI.md` |
+| Keep CLAUDE.md Lean | `lean-claude-md.md` | CLAUDE.md is loaded into context every session — every line costs tokens. |
+| Record Learnings with [LEARN] Tags | `learn-tags.md` | Record Learnings with [LEARN] Tags |
+| Overleaf Separation — No Code or Data in Paper Directories | `overleaf-separation.md` | The `paper/` directory (Overleaf symlink inside `paper-{venue}/paper/`) is for LaTeX source files ONLY. |
+| Plan Before Implementing | `plan-first.md` | Plan Before Implementing |
+| Read Documentation Before Searching | `read-docs-first.md` | Never explore when documentation already answers your question. |
+| Scope Discipline | `scope-discipline.md` | Only make changes the user explicitly requested. |
+
+## How Rules Work
+
+- All `.md` files in `.claude/rules/` are auto-loaded as system instructions
+- They apply before any user message is processed
+- Rules are global via symlink: `~/.claude/rules/` points to this repo's `.claude/rules/`
+
+## Creating New Rules
+
+1. Create a `.md` file in `.claude/rules/`
+2. Write clear, directive instructions (imperative mood)
+3. Include "When This Applies" and "When to Skip" sections
+
+Rules should be short and focused — one concern per file.