flonat-research 0.1.0

package/docs/scripts.md

@@ -0,0 +1,303 @@
+# Scripts & CLI Tools
+
+Quick reference for command-line tools in your task management system.
+
+## Overview
+
+| Command | Purpose |
+|---------|---------|
+| `task "..."` | Create a task |
+| `tasks` | List tasks |
+| `done "..."` | Mark task done |
+| `focus "..."` | Update current focus |
+| `papers` | Show research pipeline |
+| `inbox` | Tasks needing dates |
+| `week` | Weekly summary |
+| `conf` | Conference deadlines |
+| `query "..."` | Search files + Notion |
+
+## Setup (one time)
+
+### Option A: Using .env file (recommended)
+
+1. **Get a Notion token:** https://www.notion.so/my-integrations
+2. **Add token to `.env`** (already created):
+   ```bash
+   export NOTION_TOKEN="your-token-here"
+   ```
+3. **Run scripts with uv:**
+   ```bash
+   cd "Task Management"
+   uv run python .scripts/tasks
+   ```
+
+### Option B: Add to PATH
+
+1. **Add to `~/.zshrc`:**
+   ```bash
+   export PATH="$PATH:$HOME/path/to/Task Management/.scripts"
+   source "$HOME/path/to/Task Management/.env"
+   ```
+2. **Reload:** `source ~/.zshrc`
+
+### For both options
+
+**Share databases** with your integration in Notion (Tasks Tracker + Research Pipeline)
+
+---
+
+## task — Create Tasks
+
+Creates tasks with **Inbox** status by default (GTD-style capture).
+
+```bash
+task "Review paper feedback"                           # basic (goes to Inbox)
+task "Email supervisor" -p "Paper Revision"            # with project
+task "Submit paper" --priority high                    # with priority
+task "Read Smith 2024" -d friday                       # due Friday
+task "Follow up" -s "Meeting"                          # from meeting
+task "Exercise" -a personal                            # with area
+task --list-projects                                   # show projects
+```
+
+| Flag | Description |
+|------|-------------|
+| `-p, --project` | Project name |
+| `-a, --area` | Area: research, teaching, career, personal, health, learning |
+| `--priority` | high, medium, low |
+| `-d, --due` | Due date (today, tomorrow, friday, 2024-03-15) |
+| `-s, --source` | Meeting, Email, Supervisor request, etc. |
+| `--desc` | Additional description |
+
+---
+
+## tasks — Query Tasks
+
+```bash
+tasks                        # all active tasks
+tasks --overdue              # overdue only
+tasks --today                # due today
+tasks -p "Paper Revision"    # filter by project
+tasks --priority high        # filter by priority
+tasks --all                  # include completed
+```
+
+| Flag | Description |
+|------|-------------|
+| `--overdue` | Show overdue tasks |
+| `--today` | Show tasks due today |
+| `-p, --project` | Filter by project |
+| `--priority` | Filter by priority |
+| `--status` | Filter by status |
+| `--all` | Include completed tasks |
+
+---
+
+## done — Complete Tasks
+
+```bash
+done "paper feedback"        # mark matching task as done
+done --list                  # show tasks to choose from
+```
+
+If multiple tasks match, you'll be prompted to choose.
+
+---
+
+## focus — Update Current Focus
+
+```bash
+focus "Working on paper section 4"         # what you're working on
+focus --left-off "Finished draft"          # where you left off
+focus --next "Review with supervisor"      # add next step
+focus --question "Check methodology?"      # add open question
+focus --show                               # show current focus
+focus --clear                              # start fresh
+```
+
+Updates `.context/current-focus.md` directly.
+
+---
+
+## papers — Research Pipeline
+
+```bash
+papers                              # show all papers
+papers --active                     # show papers in progress
+papers --update "Paper A" "R&R"     # update paper stage
+papers --stages                     # list available stages
+```
+
+**Stages:** Idea > Literature Review > Drafting > Internal Review > Submitted > Under Review > R&R > Revising > Accepted > Published
+
+---
+
+## inbox — Tasks Without Dates
+
+```bash
+inbox                   # show inbox tasks
+inbox --assign          # interactively assign due dates
+```
+
+**Shortcuts in assign mode:**
+- `t` = today
+- `tm` = tomorrow
+- `w` = +1 week
+- `m` = +1 month
+- `fri` = next Friday
+- `s` = skip
+- `q` = quit
+
+---
+
+## week — Weekly Summary
+
+```bash
+week              # this week's summary
+week --last       # last week's summary
+```
+
+Shows: completed, due this week, overdue, in progress.
+
+---
+
+## conf — Conference Tracking
+
+```bash
+conf                    # show upcoming deadlines
+conf --search           # open Google CFP search links in browser
+conf --add              # interactively add a conference
+conf --remind           # weekly reminder checklist
+conf --deadlines        # show all deadlines
+conf --all              # include past conferences
+conf --topics           # list available topics
+```
+
+**Weekly routine:**
+1. Run `conf --remind` on Mondays
+2. Run `conf --search` to find new conferences
+3. Add with `conf --add`
+
+---
+
+## query — Search Everything
+
+```bash
+query "game theory"              # search files + Notion
+query --files "topic"            # search only context files
+query --notion "keyword"         # search only Notion
+query --papers "collaboration"   # search Research Pipeline
+query --tasks "meeting"          # search Tasks Tracker
+query --conferences "deadline"   # search Conferences
+```
+
+| Flag | Description |
+|------|-------------|
+| `--files` | Search only local context files |
+| `--notion` | Search only Notion |
+| `--papers` | Search Research Pipeline database |
+| `--tasks` | Search Tasks Tracker database |
+| `--conferences` | Search Conferences database |
+
+---
+
+## How It Works
+
+All scripts are Python CLI tools in `.scripts/` that talk to the Notion API:
+
+| File | Type | Purpose |
+|------|------|---------|
+| `task` | CLI tool | Create tasks |
+| `tasks` | CLI tool | Query tasks |
+| `done` | CLI tool | Complete tasks |
+| `focus` | CLI tool | Update current focus |
+| `papers` | CLI tool | Research pipeline |
+| `inbox` | CLI tool | Inbox management |
+| `week` | CLI tool | Weekly summary |
+| `conf` | CLI tool | Conference tracking |
+| `query` | CLI tool | Cross-system search |
+| `config.py` | Helper | Database IDs, project lists, constants |
+| `notion_helpers.py` | Helper | Notion API utilities, project inference |
+| `daily_digest.py` | Helper | Daily digest generation |
+| `extract_meeting_actions.py` | Helper | Meeting transcript action extraction |
+| `openalex/` | Library | OpenAlex API client for scholarly search |
+
+## Configuration
+
+### `config.py`
+
+The central configuration file contains:
+
+- **Database IDs** — Notion database and page IDs for your workspace
+- **Projects list** — Project names for task categorisation (keep in sync with `.context/projects/_index.md`)
+- **Universities list** — Institutions for task tagging
+- **Source types, priorities, statuses** — Dropdown values matching your Notion schema
+
+### `notion_helpers.py`
+
+Shared utilities including:
+
+- **Task formatting** — Converts CLI arguments to Notion API properties
+- **Deadline parsing** — Natural language dates ("friday", "end of month")
+- **Project inference** — Keyword and people-based project matching
+- **Priority inference** — Context-aware priority assignment
+- **Action extraction** — Regex-based meeting transcript parsing
+
+## Extending
+
+### Adding a new CLI tool
+
+1. Create a Python file in `.scripts/` (no `.py` extension for CLI commands)
+2. Add a shebang: `#!/usr/bin/env python3`
+3. Import from `config.py` and `notion_helpers.py`
+4. Use `argparse` for flags
+5. Make executable: `chmod +x .scripts/your-tool`
+
+### Customising for your workspace
+
+1. Update database IDs in `config.py` to match your Notion workspace
+2. Update the `PROJECTS` list to match your project names
+3. Update `project_keywords` and `people_projects` in `notion_helpers.py` for auto-categorisation
+4. Update `SEARCH_KEYWORDS` and `TOPICS` in `conf` for conference tracking
+
+## Date Formats
+
+| Input | Result |
+|-------|--------|
+| `today` | Today's date |
+| `tomorrow` | Tomorrow |
+| `monday` | Next Monday |
+| `friday` | Next Friday |
+| `2024-03-15` | Specific date |
+| `15/03/2024` | UK format |
+
+## Areas of Responsibility
+
+| Area | Description |
+|------|-------------|
+| Research | Papers, conferences, supervision |
+| Teaching | Course prep, marking |
+| Career | Applications, networking |
+| Personal | Admin, finance, relationships |
+| Health | Medical, fitness, wellbeing |
+| Learning | Courses, certifications |
+
+## Troubleshooting
+
+### "NOTION_TOKEN not set"
+```bash
+export NOTION_TOKEN="your-token-here"
+```
+
+### "command not found"
+```bash
+export PATH="$PATH:$HOME/path/to/Task Management/.scripts"
+```
+
+### "Error 401/404"
+Make sure your Notion integration has access to:
+- Tasks Tracker database
+- Research Pipeline database
+- Conferences database
+
+(In Notion: ... > Connections > Add integration)

package/docs/skills.md

@@ -0,0 +1,70 @@
+# Skills
+
+> 38 reusable workflow definitions available across all projects.
+
+Skills are structured instruction sets (`SKILL.md` files) that turn Claude into a specialised tool for specific tasks — from compiling LaTeX to bootstrapping research projects.
+
+## Overview
+
+| Skill | Description |
+|-------|-------------|
+| `beamer-deck` | Use when you need to create an academic Beamer presentation with original theme and multi-agent review |
+| `bib-validate` | 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. Fix mode auto-adds missing entries to Zotero |
+| `code-archaeology` | Use when you need to review and understand old code, data, or analysis files |
+| `code-review` | Use when you need a quality review of R or Python research scripts |
+| `consolidate-memory` | Use when you need to prune duplicates and merge overlapping entries in MEMORY.md files |
+| `context-status` | Use when you need to check current context status and session health |
+| `creation-guard` | Use when you need a pre-flight duplicate check before creating new skills or agents |
+| `devils-advocate` | Use when you need to challenge research assumptions or stress-test arguments |
+| `init-project` | Bootstrap a new research project. Interview for details, scaffold directory structure, create Overleaf symlink, initialise git, and create project context files |
+| `init-project-course` | Use when you need to bootstrap a university course or module folder |
+| `init-project-light` | Use when you need to bootstrap a lightweight project with minimal structure |
+| `init-project-research` | Use when you need to bootstrap a full research project with directory scaffold and Overleaf symlink |
+| `insights-deck` | Use when you need a timestamped Claude Code insights report and Beamer presentation |
+| `interview-me` | Use when you need to conduct a structured interview to extract knowledge or preferences |
+| `latex` | Use when you need to compile a LaTeX document or manage LaTeX projects |
+| `latex-autofix` | Use when you need to compile LaTeX with autonomous error resolution and citation audit |
+| `latex-health-check` | Use when you need to compile all LaTeX projects and check cross-project consistency |
+| `learn` | Extract reusable knowledge from the current session into a persistent skill.\nUse when you discover something non-obvious, create a workaround, or develop\na multi-step workflow that future sessions would benefit from |
+| `lessons-learned` | Use when you need a structured post-mortem after incidents, mistakes, or stuck sessions |
+| `literature` | Use when you need academic literature discovery, synthesis, or bibliography management |
+| `multi-perspective` | Use when you need to explore a research question from multiple independent perspectives |
+| `pipeline-manifest` | Use when you need to map scripts to their inputs, outputs, and paper figures/tables |
+| `pre-submission-report` | Use when you need all quality checks run before submission, producing a single dated report |
+| `process-reviews` | Use when you need to process referee comments from a reviews PDF into tracking files |
+| `project-deck` | Use when you need to create a presentation deck to communicate project status |
+| `project-safety` | Use when you need to set up safety rules and folder structures for a research project |
+| `proofread` | Use when you need academic proofreading of a LaTeX paper (11 check categories) |
+| `python-env` | Use when you need Python environment management with uv (install, create venv, manage deps) |
+| `quarto-deck` | Use when you need to generate a Reveal.js HTML presentation from Markdown |
+| `save-context` | Use when you need to save information from the current conversation to the context library |
+| `session-log` | Use when you need to create a timestamped progress log for a research session |
+| `split-pdf` | Use when you need to download, split, and deeply read an academic PDF |
+| `sync-notion` | Use when you need to sync the current project's state to the context library and Notion |
+| `system-audit` | Use when you need to run parallel audits across skills, hooks, agents, rules, and conventions |
+| `task-management` | Use when you need help with daily planning, weekly reviews, meeting actions, or vault task queries |
+| `update-focus` | Use when you need to update current-focus.md with a structured session summary |
+| `update-project-doc` | Use when you need to update a project's own CLAUDE.md, README.md, or docs/ to reflect current state |
+| `validate-bib` | 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 |
+
+## Using Skills
+
+| Method | Example |
+|--------|---------|
+| Slash command | `/latex-autofix` |
+| Natural language | "Compile my paper" or "Proofread this" |
+
+## Skill Structure
+
+Each skill is a directory in `skills/` containing a `SKILL.md` file with:
+
+1. **YAML frontmatter** — name, description, and allowed tools
+2. **Markdown body** — structured instructions Claude follows
+
+## Creating New Skills
+
+1. Create a directory: `skills/<skill-name>/`
+2. Add a `SKILL.md` with YAML frontmatter and markdown instructions
+3. The skill is immediately available via `/skill-name`
+
+See any existing skill for the format.

package/docs/system.md

@@ -0,0 +1,159 @@
+# System Architecture
+
+> How the components fit together.
+
+## Directory Structure
+
+```
+claude-research/
+├── CLAUDE.md                         # Main instruction file
+├── README.md                         # Setup guide
+├── MEMORY.md                         # Accumulated knowledge
+├── .gitignore
+│
+├── .claude/
+│   ├── agents/                       # 6 specialised review agents
+│   │   ├── referee2-reviewer.md
+│   │   ├── peer-reviewer.md
+│   │   ├── proposal-reviewer.md
+│   │   ├── paper-critic.md
+│   │   ├── domain-reviewer.md
+│   │   └── fixer.md
+│   ├── rules/                        # 9 auto-loaded policy rules
+│   │   ├── plan-first.md
+│   │   ├── scope-discipline.md
+│   │   ├── learn-tags.md
+│   │   ├── read-docs-first.md
+│   │   ├── lean-claude-md.md
+│   │   ├── overleaf-separation.md
+│   │   ├── ignore-agents-md.md
+│   │   ├── ignore-gemini-md.md
+│   │   └── design-before-results.md
+│   └── settings.json                 # Permissions, hooks, model config
+│
+├── skills/                           # 30 slash commands
+│   ├── shared/                       # Shared utilities
+│   │   ├── palettes.md
+│   │   ├── quality-scoring.md
+│   │   └── rhetoric-principles.md
+│   ├── proofread/
+│   ├── latex-autofix/
+│   ├── literature/
+│   └── ...
+│
+├── hooks/                            # 8 automated guardrails
+│   ├── block-destructive-git.sh
+│   ├── context-monitor.py
+│   ├── postcompact-restore.py
+│   ├── precompact-autosave.py
+│   ├── promise-checker.sh
+│   ├── protect-source-files.sh
+│   ├── resume-context-loader.sh
+│   └── startup-context-loader.sh
+│
+├── .context/                         # AI context library
+│   ├── profile.md                    # Your identity and background
+│   ├── current-focus.md              # What you're working on NOW
+│   ├── projects/
+│   │   ├── _index.md                 # All projects overview
+│   │   └── papers/                   # Individual paper metadata
+│   ├── preferences/
+│   │   ├── priorities.md             # Priority framework
+│   │   └── task-naming.md            # Task naming conventions
+│   ├── workflows/                    # Process guides
+│   │   ├── daily-review.md
+│   │   ├── weekly-review.md
+│   │   ├── meeting-actions.md
+│   │   └── replication-protocol.md
+│   └── resources/                    # Reference data
+│       ├── journal-rankings.md
+│       └── conference-rankings.md
+│
+├── .mcp-server-openalex/             # OpenAlex scholarly search
+│   ├── server.py
+│   ├── formatters.py
+│   ├── pyproject.toml
+│   └── uv.lock
+│
+├── docs/                             # Documentation
+│   ├── system.md                     # This file
+│   ├── skills.md
+│   ├── agents.md
+│   ├── hooks.md
+│   └── rules.md
+│
+├── log/                              # Session logs
+│   ├── .gitkeep
+│   └── plans/                        # Saved plans
+│       └── .gitkeep
+│
+└── scripts/
+    └── setup.sh                      # Initial setup script
+```
+
+## Symlink Architecture
+
+The `setup.sh` script creates four symlinks in `~/.claude/`:
+
+```
+~/.claude/skills/  → <repo>/skills/
+~/.claude/agents/  → <repo>/.claude/agents/
+~/.claude/rules/   → <repo>/.claude/rules/
+~/.claude/hooks/   → <repo>/hooks/
+```
+
+This makes all components globally available from any project directory.
+
+## How Components Interact
+
+```
+Session Start
+    │
+    ├── startup-context-loader.sh  →  Reads .context/ files
+    │                                  Outputs to Claude as additionalContext
+    │
+    ├── Rules loaded                →  All 9 rules active
+    │
+    └── Claude ready
+         │
+         ├── User: "/proofread"    →  Skill invoked (same session)
+         │
+         ├── User: "Review paper"  →  Agent launched (separate context via Task tool)
+         │
+         ├── Claude: "git push -f" →  block-destructive-git.sh BLOCKS
+         │
+         ├── Claude uses Bash      →  context-monitor.py tracks usage
+         │
+         ├── Context compression   →  precompact-autosave.py saves state
+         │                             postcompact-restore.py restores state
+         │
+         └── Session ends          →  promise-checker.sh verifies claims
+```
+
+## Configuration
+
+All configuration lives in `~/.claude/settings.json`:
+
+- **`permissions.allow`**: Commands Claude can run without prompting
+- **`permissions.deny`**: Commands that are always blocked (bare python/pip)
+- **`hooks`**: Which scripts run at which events
+- **`model`**: Default model preference
+
+## Extending the System
+
+### Adding a new skill
+1. Create `skills/my-skill/SKILL.md`
+2. Available immediately as `/my-skill`
+
+### Adding a new agent
+1. Create `.claude/agents/my-agent.md`
+2. Available immediately via Task tool
+
+### Adding a new hook
+1. Create script in `hooks/`
+2. Make executable: `chmod +x hooks/my-hook.sh`
+3. Add to `~/.claude/settings.json`
+
+### Adding a new rule
+1. Create `.claude/rules/my-rule.md`
+2. Auto-loaded in every session

package/hooks/block-destructive-git.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# Skip on non-Mac environments (cloud, mobile)
+source "$(dirname "$0")/resolve-task-mgmt.sh" || exit 0
+# block-destructive-git.sh
+# PreToolUse hook for Bash — catches dangerous git/shell commands
+# and surfaces a permission prompt. Soft block via permissionDecision: "ask".
+
+INPUT=$(cat)
+
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# No command — allow
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+REASON=""
+
+# Check destructive patterns
+if echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard'; then
+  REASON="git reset --hard will discard all uncommitted changes"
+fi
+
+if echo "$COMMAND" | grep -qE 'git\s+push\s+(-f|--force)(\s|$)' && \
+   ! echo "$COMMAND" | grep -q '\-\-force-with-lease'; then
+  REASON="git push --force can overwrite remote history (use --force-with-lease instead?)"
+fi
+
+if echo "$COMMAND" | grep -qE 'git\s+clean\s+-[a-zA-Z]*f' && \
+   ! echo "$COMMAND" | grep -qE 'git\s+clean\s+-[a-zA-Z]*n'; then
+  REASON="git clean -f will permanently delete untracked files"
+fi
+
+if echo "$COMMAND" | grep -qE 'git\s+checkout\s+\.\s*$'; then
+  REASON="git checkout . will discard all unstaged changes"
+fi
+
+if echo "$COMMAND" | grep -qE 'git\s+restore\s+\.\s*$'; then
+  REASON="git restore . will discard all unstaged changes"
+fi
+
+if echo "$COMMAND" | grep -qE 'git\s+branch\s+-D\s'; then
+  REASON="git branch -D force-deletes a branch (use -d for safe delete)"
+fi
+
+if echo "$COMMAND" | grep -qE 'rm\s+-[a-zA-Z]*r[a-zA-Z]*f|rm\s+-[a-zA-Z]*f[a-zA-Z]*r'; then
+  REASON="rm -rf is a destructive operation"
+fi
+
+# If no dangerous pattern matched, allow silently
+if [ -z "$REASON" ]; then
+  exit 0
+fi
+
+# Dangerous pattern found — ask for confirmation
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "ask",
+    "permissionDecisionReason": "$REASON"
+  }
+}
+EOF
+
+exit 0