@forwardimpact/basecamp 0.1.0

package/template/.claude/skills/extract-entities/references/TEMPLATES.md

@@ -0,0 +1,131 @@
+# Note Templates
+
+Templates for creating new knowledge base notes.
+
+## People
+
+```markdown
+# {Full Name}
+
+## Info
+**Role:** {role or inferred role with qualifier}
+**Organization:** [[Organizations/{organization}]]
+**Email:** {email}
+**Aliases:** {comma-separated variants}
+**First met:** {YYYY-MM-DD}
+**Last seen:** {YYYY-MM-DD}
+
+## Summary
+{2-3 sentences: who they are, why you know them, what you're working on}
+
+## Connected to
+- [[Organizations/{Org}]] — works at
+- [[People/{Person}]] — {relationship}
+- [[Projects/{Project}]] — {role}
+
+## Activity
+- **{YYYY-MM-DD}** ({meeting|email|voice memo}): {Summary with [[Folder/Name]] links}
+
+## Key facts
+{substantive facts only — leave empty if none}
+
+## Open items
+{commitments and next steps only — leave empty if none}
+```
+
+## Organizations
+
+```markdown
+# {Organization Name}
+
+## Info
+**Type:** {company|team|institution}
+**Industry:** {industry}
+**Relationship:** {customer|prospect|partner|vendor}
+**Domain:** {primary email domain}
+**Aliases:** {comma-separated}
+**First met:** {YYYY-MM-DD}
+**Last seen:** {YYYY-MM-DD}
+
+## Summary
+{2-3 sentences}
+
+## People
+- [[People/{Person}]] — {role}
+
+## Contacts
+{for transactional contacts who don't get their own notes}
+
+## Projects
+- [[Projects/{Project}]] — {relationship}
+
+## Activity
+- **{YYYY-MM-DD}** ({type}): {Summary}
+
+## Key facts
+
+## Open items
+```
+
+## Projects
+
+```markdown
+# {Project Name}
+
+## Info
+**Type:** {deal|product|initiative|hiring}
+**Status:** {active|planning|on hold|completed|cancelled}
+**Started:** {YYYY-MM-DD}
+**Last activity:** {YYYY-MM-DD}
+
+## Summary
+{2-3 sentences}
+
+## People
+- [[People/{Person}]] — {role}
+
+## Organizations
+- [[Organizations/{Org}]] — {relationship}
+
+## Related
+- [[Topics/{Topic}]] — {relationship}
+
+## Timeline
+**{YYYY-MM-DD}** ({type})
+{What happened with [[links]]}
+
+## Decisions
+- **{YYYY-MM-DD}**: {Decision}. {Rationale}.
+
+## Open items
+
+## Key facts
+```
+
+## Topics
+
+```markdown
+# {Topic Name}
+
+## About
+{1-2 sentences}
+
+**Keywords:** {comma-separated}
+**Aliases:** {other references}
+**First mentioned:** {YYYY-MM-DD}
+**Last mentioned:** {YYYY-MM-DD}
+
+## Related
+- [[People/{Person}]] — {relationship}
+- [[Organizations/{Org}]] — {relationship}
+
+## Log
+**{YYYY-MM-DD}** ({type}: {title})
+{Summary with [[links]]}
+
+## Decisions
+
+## Open items
+
+## Key facts
+```

package/template/.claude/skills/extract-entities/scripts/state.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""Manage graph_processed state for entity extraction.
+
+Commands:
+  check   - Find unprocessed or changed source files
+  update  - Mark a file as processed (updates its hash in state)
+
+Usage:
+  python3 scripts/state.py check                    # List new/changed files
+  python3 scripts/state.py update <file-path>        # Mark file as processed
+  python3 scripts/state.py update <file1> <file2> …  # Mark multiple files
+
+State file: ~/.cache/fit/basecamp/state/graph_processed (TSV: path<TAB>hash)
+"""
+
+import hashlib
+import os
+import sys
+from pathlib import Path
+
+STATE_FILE = Path.home() / ".cache/fit/basecamp/state/graph_processed"
+SOURCE_DIRS = [
+    Path.home() / ".cache/fit/basecamp/apple_mail",
+    Path.home() / ".cache/fit/basecamp/apple_calendar",
+]
+
+
+def file_hash(path):
+    """Compute SHA-256 hash of a file."""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def load_state():
+    """Load the state file into a dict of {path: hash}."""
+    state = {}
+    if STATE_FILE.exists():
+        for line in STATE_FILE.read_text().splitlines():
+            parts = line.split("\t", 1)
+            if len(parts) == 2:
+                state[parts[0]] = parts[1]
+    return state
+
+
+def save_state(state):
+    """Write the full state dict back to the state file."""
+    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    lines = [f"{path}\t{h}" for path, h in sorted(state.items())]
+    STATE_FILE.write_text("\n".join(lines) + "\n" if lines else "")
+
+
+def check():
+    """Find source files that are new or have changed since last processing."""
+    state = load_state()
+    new_files = []
+    for source_dir in SOURCE_DIRS:
+        if not source_dir.is_dir():
+            continue
+        for f in source_dir.iterdir():
+            if not f.is_file():
+                continue
+            path_str = str(f)
+            h = file_hash(f)
+            if state.get(path_str) != h:
+                new_files.append(path_str)
+    for f in sorted(new_files):
+        print(f)
+    return len(new_files)
+
+
+def update(file_paths):
+    """Mark files as processed by updating their hashes in state."""
+    state = load_state()
+    for fp in file_paths:
+        p = Path(fp)
+        if not p.exists():
+            print(f"Warning: File not found: {fp}", file=sys.stderr)
+            continue
+        state[str(p)] = file_hash(p)
+    save_state(state)
+    print(f"Updated {len(file_paths)} file(s) in graph state")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(__doc__, file=sys.stderr)
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+    if cmd == "check":
+        count = check()
+        print(f"\n{count} file(s) to process", file=sys.stderr)
+    elif cmd == "update" and len(sys.argv) >= 3:
+        update(sys.argv[2:])
+    else:
+        print(__doc__, file=sys.stderr)
+        sys.exit(1)

package/template/.claude/skills/meeting-prep/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: meeting-prep
+description: Prepare for meetings by gathering context from the knowledge base and calendar. Use when the user asks to prep for a meeting or wants a briefing on upcoming meetings. Creates personalized briefings with attendee history, open items, and suggested talking points.
+---
+
+# Meeting Prep
+
+Help the user prepare for meetings by gathering context from the knowledge base
+and calendar. Creates personalized briefing documents with attendee history,
+open items, and suggested talking points.
+
+## Trigger
+
+Run when the user asks to prep for a meeting, or wants a briefing on upcoming
+meetings.
+
+## Prerequisites
+
+- Calendar data synced in `~/.cache/fit/basecamp/apple_calendar/`
+- Knowledge base populated (from `extract-entities` skill)
+
+## Inputs
+
+- `~/.cache/fit/basecamp/apple_calendar/*.json` — calendar events
+- `knowledge/People/*.md` — attendee context
+- `knowledge/Organizations/*.md` — company context
+- `knowledge/Projects/*.md` — project context
+
+## Outputs
+
+- Meeting brief printed to the user (not saved to a file)
+
+---
+
+## Critical: Always Look Up Context First
+
+**BEFORE creating any meeting brief, you MUST look up the attendees in the
+knowledge base.**
+
+When the user asks to prep for a meeting:
+
+1. **STOP** — Do not create a generic brief
+2. **SEARCH** — Look up each attendee: `rg -l "Attendee Name" knowledge/`
+3. **READ** — Read their notes: `cat "knowledge/People/Attendee Name.md"`
+4. **UNDERSTAND** — Extract role, organization, history, open items
+5. **THEN BRIEF** — Create the meeting brief using this context
+
+## Key Principles
+
+**Ask, don't guess:**
+
+- If unclear which meeting, ASK
+- If multiple upcoming meetings, offer choices
+- **WRONG:** "Here's a generic meeting prep template"
+- **RIGHT:** "I see meetings with Sarah (2pm) and John (4pm). Which one?"
+
+**Be thorough, not generic:**
+
+- Include specific history, open items, and context from knowledge base
+- Reference actual past interactions and commitments
+
+## Processing Flow
+
+### Step 1: Identify the Meeting
+
+If specified, look it up in calendar:
+
+```bash
+ls ~/.cache/fit/basecamp/apple_calendar/ 2>/dev/null
+cat "$HOME/.cache/fit/basecamp/apple_calendar/event123.json"
+```
+
+If "prep me for my next meeting":
+
+- List upcoming events
+- Find the next meeting with external attendees
+- Confirm with user if unclear
+
+### Step 2: Parse Calendar Event
+
+Extract: summary, start/end time, attendees (names and emails), description.
+
+### Step 3: Gather Context from Knowledge Base
+
+For each attendee:
+
+```bash
+rg -l "attendee_name" knowledge/People/
+rg -l "attendee_email" knowledge/People/
+cat "knowledge/People/Attendee Name.md"
+cat "knowledge/Organizations/Their Company.md"
+rg -l "attendee_name" knowledge/Projects/
+```
+
+Extract: role/title, company, key facts, previous interactions, open items.
+
+### Step 4: Create Meeting Brief
+
+Format:
+
+```markdown
+Meeting Brief: {Attendee Name}
+{Time} today / {Company}
+
+About {First Name}
+{Role at company}. {Key background — 1-2 sentences}. {What they focus on}.
+
+Your History
+- {Date}: {Brief description of interaction/outcome}
+- {Date}: {Brief description}
+- {Date}: {Brief description}
+
+Open Items
+- {Action item} (they asked {date})
+- {Action item}
+
+Suggested Talking Points
+- {Concrete suggestion based on history}
+- {Reference relevant entities with [[wiki-links]]}
+```
+
+**Guidelines:**
+
+- Use `[[Name]]` wiki-link syntax for cross-references
+- Keep "About" section to 2-3 sentences max
+- History: reverse chronological, 3-5 most relevant items
+- Talking points: concrete, not generic
+- If no notes exist for a person, mention that and offer to create one
+
+## Constraints
+
+- Only prep for meetings with external attendees
+- Skip internal calendar blocks (DND, Focus Time, Lunch)
+- For meetings with multiple attendees, create sections for each key person
+- Prioritize recent interactions (last 30 days)

package/template/.claude/skills/organize-files/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: organize-files
+description: Organize, tidy up, and find files in ~/Desktop/ and ~/Downloads/. Use when the user asks to find, organize, clean up, or tidy files on their Mac. Always previews changes before acting and never deletes without explicit confirmation. Extracts entities from document files using the extract-entities skill.
+compatibility: Requires macOS filesystem access
+---
+
+# Organize Files
+
+Organize, tidy up, and find files in `~/Desktop/` and `~/Downloads/`. Always
+previews changes before acting and never deletes without explicit confirmation.
+
+After organizing, extract entities from document files by invoking the
+**`extract-entities`** skill.
+
+## Trigger
+
+Run when the user asks to find, organize, clean up, or tidy files on their Mac.
+
+## Prerequisites
+
+- macOS filesystem access
+
+## Inputs
+
+- User's description of what to organize or find
+- Source directories: `~/Desktop/` and `~/Downloads/`
+
+## Outputs
+
+- Organized files moved to logical subdirectories within `~/Desktop/` and
+  `~/Downloads/`
+- Entity extraction triggered on document files via the **`extract-entities`**
+  skill
+- Summary of actions taken
+
+---
+
+## Core Capabilities
+
+1. **Find files** — Locate files by name, type, or content in `~/Desktop/` and
+   `~/Downloads/`
+2. **Organize files** — Move files into logical subfolders
+3. **Tidy up** — Clean up cluttered `~/Desktop/` and `~/Downloads/`
+4. **Create structure** — Set up folder hierarchies
+5. **Extract entities** — After organizing, invoke the **`extract-entities`**
+   skill on document files to populate the knowledge graph
+
+## Key Principles
+
+**Always preview before acting:**
+
+- Show what files will be affected BEFORE moving/deleting
+- List proposed changes and ask for confirmation
+
+**Be conservative with destructive operations:**
+
+- Never delete without explicit confirmation
+- Prefer moving to a "to-review" folder over deleting
+
+## Summarizing Contents
+
+Get an overview of both directories:
+
+    bash scripts/summarize.sh
+
+## Finding Files
+
+```bash
+find ~/Downloads -maxdepth 1 -name "*.pdf" -type f
+find ~/Desktop -maxdepth 1 -iname "*AI*" -type f
+find ~/Desktop -maxdepth 1 -type f \( -name "*.png" -o -name "*.jpg" \)
+find ~/Downloads -maxdepth 1 -type f -mtime -7     # last 7 days
+find ~/Downloads -maxdepth 1 -type f -mtime +30    # older than 30 days
+find ~/Desktop -maxdepth 1 \( -name "Screenshot*" -o -name "Screen Shot*" \)
+```
+
+## Organizing by File Type
+
+Organize a directory into type-based subdirectories (Documents, Images,
+Archives, Installers, Screenshots):
+
+    bash scripts/organize-by-type.sh ~/Downloads
+    bash scripts/organize-by-type.sh ~/Desktop
+
+The script creates subdirectories and moves matching files. It does NOT delete
+anything.
+
+## Entity Extraction
+
+After organizing files, identify document files that may contain entity
+information (people, organizations, projects, topics) and invoke the
+**`extract-entities`** skill to process them.
+
+### Which files to send for extraction
+
+**Include:** `.pdf`, `.txt`, `.md`, `.rtf`, `.doc`, `.docx`, `.csv`, `.xlsx`
+
+**Exclude:** Images, installers, archives, media, system files
+
+### How to invoke
+
+After organizing, collect the paths of document files and invoke the
+**`extract-entities`** skill, passing the file paths as ad-hoc file inputs.
+
+## Output Format
+
+**Plan:**
+
+```
+Organization Plan: Desktop & Downloads Cleanup
+
+Found 47 files to organize:
+- 23 screenshots → ~/Desktop/Screenshots/
+- 12 PDFs → ~/Downloads/Documents/
+- 8 images → ~/Downloads/Images/
+- 4 DMGs → ~/Downloads/Installers/
+
+Document files for entity extraction: 12
+→ Will invoke extract-entities skill after organizing
+
+Should I proceed?
+```
+
+**Results:**
+
+```
+Organization Complete
+
+Moved 47 files:
+- 23 screenshots to ~/Desktop/Screenshots/
+- 12 PDFs to ~/Downloads/Documents/
+- 8 images to ~/Downloads/Images/
+- 4 DMGs to ~/Downloads/Installers/
+
+Entity extraction: invoked extract-entities on 12 document files
+```
+
+## Safety Rules
+
+1. **Never delete without permission** — "cleanup" means organize, not delete
+2. **Don't touch system folders** — /System, /Library, /Applications
+3. **Don't touch hidden files** — files starting with `.` unless asked
+4. **Limit scope** — only operate on `~/Desktop/` and `~/Downloads/`
+5. **Limit depth** — use `-maxdepth 1` unless user wants recursive
+6. **Show before doing** — always preview first
+7. **Quote paths** — handle spaces: `"$HOME/My Documents"`

package/template/.claude/skills/organize-files/scripts/organize-by-type.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Organize files in a directory by type into subdirectories.
+#
+# Usage: bash scripts/organize-by-type.sh <directory>
+#
+# Creates subdirectories (Documents, Images, Archives, Installers, Screenshots)
+# and moves matching files. Only operates on top-level files (-maxdepth 1).
+# Prints each move with -v flag. Does NOT delete any files.
+
+set -euo pipefail
+
+if [ $# -ne 1 ]; then
+  echo "Usage: bash scripts/organize-by-type.sh <directory>" >&2
+  exit 1
+fi
+
+DIR="$1"
+
+if [ ! -d "$DIR" ]; then
+  echo "Error: Directory not found: $DIR" >&2
+  exit 1
+fi
+
+# Create subdirectories
+mkdir -p "$DIR"/{Documents,Images,Archives,Installers,Screenshots}
+
+# Screenshots
+find "$DIR" -maxdepth 1 -type f \( -name "Screenshot*" -o -name "Screen Shot*" \) -exec mv -v {} "$DIR/Screenshots/" \;
+
+# Documents
+find "$DIR" -maxdepth 1 -type f \( -name "*.pdf" -o -name "*.doc*" -o -name "*.txt" -o -name "*.md" -o -name "*.rtf" -o -name "*.csv" -o -name "*.xlsx" \) -exec mv -v {} "$DIR/Documents/" \;
+
+# Images (excluding screenshots already moved)
+find "$DIR" -maxdepth 1 -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.webp" \) -exec mv -v {} "$DIR/Images/" \;
+
+# Archives
+find "$DIR" -maxdepth 1 -type f \( -name "*.zip" -o -name "*.tar.gz" -o -name "*.rar" \) -exec mv -v {} "$DIR/Archives/" \;
+
+# Installers
+find "$DIR" -maxdepth 1 -type f -name "*.dmg" -exec mv -v {} "$DIR/Installers/" \;
+
+echo "Organization complete: $DIR"

package/template/.claude/skills/organize-files/scripts/summarize.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Summarize the contents of ~/Desktop/ and ~/Downloads/.
+#
+# Usage: bash scripts/summarize.sh
+#
+# Counts files by type in both directories (top-level only).
+
+set -euo pipefail
+
+for dir in "$HOME/Desktop" "$HOME/Downloads"; do
+  [ -d "$dir" ] || continue
+  echo "=== $(basename "$dir") ==="
+  echo "Screenshots: $(find "$dir" -maxdepth 1 \( -name 'Screenshot*' -o -name 'Screen Shot*' \) 2>/dev/null | wc -l | tr -d ' ')"
+  echo "PDFs:        $(find "$dir" -maxdepth 1 -name '*.pdf' 2>/dev/null | wc -l | tr -d ' ')"
+  echo "Images:      $(find "$dir" -maxdepth 1 \( -name '*.png' -o -name '*.jpg' -o -name '*.jpeg' -o -name '*.gif' -o -name '*.webp' \) 2>/dev/null | wc -l | tr -d ' ')"
+  echo "Documents:   $(find "$dir" -maxdepth 1 \( -name '*.doc*' -o -name '*.txt' -o -name '*.md' -o -name '*.rtf' \) 2>/dev/null | wc -l | tr -d ' ')"
+  echo "Archives:    $(find "$dir" -maxdepth 1 \( -name '*.zip' -o -name '*.tar.gz' -o -name '*.rar' \) 2>/dev/null | wc -l | tr -d ' ')"
+  echo "Installers:  $(find "$dir" -maxdepth 1 -name '*.dmg' 2>/dev/null | wc -l | tr -d ' ')"
+  echo "Other:       $(find "$dir" -maxdepth 1 -type f ! \( -name 'Screenshot*' -o -name 'Screen Shot*' -o -name '*.pdf' -o -name '*.png' -o -name '*.jpg' -o -name '*.jpeg' -o -name '*.gif' -o -name '*.webp' -o -name '*.doc*' -o -name '*.txt' -o -name '*.md' -o -name '*.rtf' -o -name '*.zip' -o -name '*.tar.gz' -o -name '*.rar' -o -name '*.dmg' -o -name '.DS_Store' -o -name '.localized' \) 2>/dev/null | wc -l | tr -d ' ')"
+  echo ""
+done

package/template/.claude/skills/sync-apple-calendar/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: sync-apple-calendar
+description: Sync calendar events from the macOS Calendar app's local SQLite database into ~/.cache/fit/basecamp/apple_calendar/ as JSON files. Use on a schedule or when the user asks to sync their calendar. Requires macOS with Calendar app configured and Full Disk Access granted.
+compatibility: Requires macOS with Apple Calendar configured and Full Disk Access granted to the terminal
+---
+
+# Sync Apple Calendar
+
+Sync calendar events from the macOS Calendar app's local SQLite database into
+`~/.cache/fit/basecamp/apple_calendar/` as JSON files. This is an automated data
+pipeline skill — it ingests raw calendar data that other skills (like
+`extract-entities` and `meeting-prep`) consume downstream.
+
+## Trigger
+
+Run this skill on a schedule (every 5 minutes) or when the user asks to sync
+their calendar.
+
+## Prerequisites
+
+- macOS with the built-in Calendar app configured
+- Full Disk Access granted to the terminal (System Settings → Privacy & Security
+  → Full Disk Access)
+
+## Inputs
+
+- `~/Library/Group Containers/group.com.apple.calendar/Calendar.sqlitedb` —
+  Apple Calendar SQLite database (Sonoma+/macOS 14+)
+- `~/Library/Calendars/Calendar.sqlitedb` — fallback path for older macOS
+
+## Outputs
+
+- `~/.cache/fit/basecamp/apple_calendar/{event_id}.json` — one JSON file per
+  event (14-day sliding window)
+
+---
+
+## Implementation
+
+Run the sync as a single Python script. This avoids N+1 sqlite3 invocations (one
+per event for attendees) and handles all data transformation in one pass:
+
+    python3 scripts/sync.py
+
+The script:
+
+1. Finds the Calendar database (Sonoma+ path first, then fallback)
+2. Queries all events in a 14-day past/future window with a single SQL query
+3. Batch-fetches all attendees for those events in one query
+4. Writes one JSON file per event to `~/.cache/fit/basecamp/apple_calendar/`
+5. Cleans up JSON files for events now outside the window
+6. Reports summary (events synced, files cleaned up)
+
+## Database Schema
+
+See [references/SCHEMA.md](references/SCHEMA.md) for the complete Apple Calendar
+SQLite schema including table structures, column names, and important caveats
+(e.g., Identity uses `address` not `email`, Participant has no `display_name`).
+
+## Output Format
+
+Each `{event_id}.json` file:
+
+```json
+{
+  "id": "apple_cal_123",
+  "summary": "Meeting with Sarah Chen",
+  "start": { "dateTime": "2025-02-12T15:00:00+01:00", "timeZone": "Europe/Paris" },
+  "end": { "dateTime": "2025-02-12T16:00:00+01:00", "timeZone": "Europe/Paris" },
+  "allDay": false,
+  "location": "Zoom",
+  "description": "Discuss Q2 roadmap",
+  "conferenceUrl": null,
+  "calendar": "Calendar",
+  "organizer": { "email": "sarah@acme.com", "name": "Chen, Sarah" },
+  "attendees": [
+    {
+      "email": "sarah@acme.com",
+      "name": "Chen, Sarah",
+      "status": "accepted",
+      "role": "required",
+      "self": false
+    }
+  ]
+}
+```
+
+## Error Handling
+
+- Database not found → Calendar not configured, report and stop
+- Permission denied → Full Disk Access not granted, report and stop
+- Database locked → wait 2 seconds, retry once
+- Skip events with no summary (likely cancelled or placeholder)
+
+## Constraints
+
+- Open database read-only (`-readonly`)
+- This sync is stateless — always queries the current 14-day window
+- All-day events may have null end times — use start date as end date
+- All-day events have timezone `_float` — omit timezone from output
+- Output format matches Google Calendar event format for downstream consistency