diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md deleted file mode 100644 index adfdcb1..0000000 --- a/.claude/CLAUDE.md +++ /dev/null @@ -1,7 +0,0 @@ - -# Recent Activity - - - -*No recent activity* - \ No newline at end of file diff --git a/.claude/commands/add-frontmatter.md b/.claude/commands/add-frontmatter.md index cdbbd0f..ff85342 100644 --- a/.claude/commands/add-frontmatter.md +++ b/.claude/commands/add-frontmatter.md @@ -1,3 +1,6 @@ +risk: medium +writes: 00-03 .md frontmatter + --- description: Add or update YAML frontmatter properties to enhance note organization diff --git a/.claude/commands/compact-sessions.md b/.claude/commands/compact-sessions.md index fb4a032..a8b7ddf 100644 --- a/.claude/commands/compact-sessions.md +++ b/.claude/commands/compact-sessions.md @@ -1,3 +1,6 @@ +risk: low +writes: .claude/sessions/ + --- allowed-tools: Read description: Summarize and compress conversation history to reduce token usage diff --git a/.claude/commands/create-command.md b/.claude/commands/create-command.md index f118708..f8f85ee 100644 --- a/.claude/commands/create-command.md +++ b/.claude/commands/create-command.md @@ -1,3 +1,6 @@ +risk: low +writes: .claude/commands/ + --- allowed-tools: Write, Read, Bash(ls:*, mkdir:*), Edit description: Create a new Claude Code slash command diff --git a/.claude/commands/daily-review.md b/.claude/commands/daily-review.md index 914eeab..5859ae8 100644 --- a/.claude/commands/daily-review.md +++ b/.claude/commands/daily-review.md @@ -1,4 +1,6 @@ # Daily Review +risk: medium +writes: 00_Inbox/ daily notes Conduct an end-of-day review to capture progress and set up tomorrow. diff --git a/.claude/commands/de-ai-ify.md b/.claude/commands/de-ai-ify.md index c2fc215..a5fa141 100644 --- a/.claude/commands/de-ai-ify.md +++ b/.claude/commands/de-ai-ify.md @@ -1,3 +1,6 @@ +risk: medium +writes: note content 00-03 + --- allowed-tools: Read, Write, Edit description: Remove AI-generated jargon and restore human voice to text diff --git a/.claude/commands/download-attachment.md b/.claude/commands/download-attachment.md index 3b6ecd1..849c0a7 100644 --- a/.claude/commands/download-attachment.md +++ b/.claude/commands/download-attachment.md @@ -1,4 +1,6 @@ # download-attachment +risk: low +writes: 05_Attachments/ Download files from URLs to attachments folder and organize them with descriptive names. diff --git a/.claude/commands/git-commit-msg.md b/.claude/commands/git-commit-msg.md index f4260a8..c1fd8de 100644 --- a/.claude/commands/git-commit-msg.md +++ b/.claude/commands/git-commit-msg.md @@ -1,3 +1,6 @@ +risk: low +writes: none (generates text) + --- allowed-tools: Bash, AskUserQuestion description: AI-generated git commit messages from staged changes diff --git a/.claude/commands/inbox-processor.md b/.claude/commands/inbox-processor.md index 5223019..444a52a 100644 --- a/.claude/commands/inbox-processor.md +++ b/.claude/commands/inbox-processor.md @@ -1,4 +1,6 @@ # Inbox Processor +risk: medium +writes: 00_Inbox → 01-03 Help organize and process items in the 00_Inbox folder according to the PARA method. diff --git a/.claude/commands/init-bootstrap.md b/.claude/commands/init-bootstrap.md deleted file mode 100644 index 81dd938..0000000 --- a/.claude/commands/init-bootstrap.md +++ /dev/null @@ -1,854 +0,0 @@ ---- -name: init-bootstrap -description: - Interactive setup wizard that helps new users create a personalized CLAUDE.md - file based on their Obsidian workflow preferences -allowed-tools: [Read, Write, MultiEdit, Bash, Task] -argument-hint: "(optional) path to existing vault or 'new' for fresh setup" ---- - -# Initialize Bootstrap Configuration - -This command helps you create a personalized CLAUDE.md configuration file by -asking questions about your Obsidian workflow and preferences. - -## Task - -Read the CLAUDE-BOOTSTRAP.md template and interactively gather information about -the user's: - -- Existing vault structure (if any) -- Workflow preferences -- Note-taking style -- Organization methods -- Specific requirements - -Then generate a customized CLAUDE.md file tailored to their needs. - -## Process - -1. **Initial Environment Setup** - - Get current date with `date` command for timestamps - - Check current folder name and ask if they want to rename it - - If yes, guide them through renaming (handle parent directory move) - - Check for package.json and install dependencies: - - Try `pnpm install` first (faster, better) - - Fall back to `npm install` if pnpm not available - - Verify core dependencies are installed - - Check git status: - - If no .git folder: Initialize git repository - - If has remote origin: Ask about development work - - Personal vault: Remove origin and .github folder - - Contributing: Keep origin and workflows intact - - If clean local repo: Ready to go - - Don't create folders yet - wait until after asking about organization - method - -2. **Check Existing Configuration** - - Look for existing CLAUDE.md - - If exists, ask if they want to update or start fresh - - Check for CLAUDE-BOOTSTRAP.md template - -3. **Gather Vault Information** - - Search common locations for existing Obsidian vaults (.obsidian folder) - - Check these paths with appropriate depth limits: - - `~/Documents` (maxdepth 3) - all platforms - - `~/Desktop` (maxdepth 3) - all platforms - - `~/Library/Mobile Documents/iCloud~md~obsidian/Documents` (maxdepth 5 - - **macOS only**, iCloud vaults) - - Home directory `~/` (maxdepth 2) - all platforms - - Current directory parent (maxdepth 2) - all platforms - - If found, ask: "Found Obsidian vault at [path]. Is this the vault you want - to import?" - - Count files correctly: `find [path] -type f -name "*.md" | wc -l` (no depth - limit) - - Show vault size: `du -sh [path]` - - If confirmed, analyze vault structure: - - Run `tree -L 3 -d [path]` to see folder hierarchy - - Sample 10-15 random notes to understand content types - - List 30-50 recent file names to detect naming patterns - - Check for daily notes folder and format - - Identify most active folders by file count - - Detect if using PARA, Zettelkasten, Johnny Decimal, or custom - - If not the right one or none found: - - **On macOS only:** Ask: "Is your vault stored in iCloud Drive? (yes/no)" - - If yes (macOS): "Please enter the full path to your vault (e.g., - ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVault)" - - If no, or on Linux/Windows: "Please enter the path to your existing - vault, or type 'skip' to start fresh" - - **Validate user-provided paths** (see "User Path Validation" section - below) - - If no existing vault or user skips, they're starting fresh - -4. **Ask Configuration Questions** - - "What's your name?" (for personalization) - - "Would you like me to research your public work to better understand your - context?" - - If yes: Search for information - - ALWAYS show findings and ask "Is this correct?" for confirmation - - If multiple people found, list them numbered for selection - - If wrong person, offer to search again or skip - - Save relevant context about their work, writing style, areas of expertise - - "Do you follow the PARA method or have a different organization system?" - - "What are your main use cases? (research, writing, project management, - knowledge base, daily notes)" - - **If using PARA, ask specific setup questions:** - [PARA Method by Tiago Forte](https://fortelabs.com/blog/para/) - - "What active projects are you working on?" (Create folders in 01_Projects) - - "What areas of responsibility do you maintain?" (e.g., Work, Health, - Finance, Family) - - "What topics do you research frequently?" (Set up in 03_Resources) - - "Any projects you recently completed?" (Can archive with summaries) - - **General preferences:** - - Check .obsidian/community-plugins.json to see what plugins they use - - Analyze existing files to detect naming convention automatically - - Check for attachments folder to see if they work with media files - - "Do you use git for version control?" - - "Any specific websites or resources you reference often?" - - "Do you have any specific writing style preferences?" - - "Are there any workflows or patterns you want Claude to follow?" - - "Would you like a weekly review ritual? (e.g., Thursday project review)" - - "Do you prefer 'thinking mode' (questions/exploration) vs 'writing mode'?" - -5. **Optional Tool Setup** - - **Gemini Vision (already included)** - - Ask: "Gemini Vision is already included for analyzing images, PDFs, and - videos. Would you like to activate it? (yes/no/later)" - - Explain: "You just need a free API key from Google. This lets Claude - analyze any visual content in your vault." - - If later: "No problem! You can set it up anytime by running - `/setup-gemini`" - - If yes: - - Guide to get API key from https://aistudio.google.com/apikey (free, takes - 30 seconds) - - Help add to shell profile (.zshrc, .bashrc, etc.) - - Run - `claude mcp add --scope project gemini-vision node .claude/mcp-servers/gemini-vision.mjs` - - Configure .mcp.json with API key - - Test the connection with a sample command - - **Firecrawl (already included)** - - Ask: "Firecrawl is included for web research. Would you like to set it up? - (yes/no/later)" - - Explain: "This is a game-changer for research! When you find an article or - website, you can save it directly to your vault as markdown - preserving - the content forever, making it searchable, and letting Claude analyze it. - Perfect for building a research library." - - Example: "Just tell Claude: 'Save this article to my vault: [URL]' and it's - done!" - - If later: "You can set it up anytime by running `/setup-firecrawl`" - - If yes: - - Guide to get API key from https://firecrawl.dev (free tier available) - - Help configure the scripts in .scripts/ - - Show example usage: `.scripts/firecrawl-scrape.sh https://example.com` - -6. **Generate Custom Configuration** - - Get current date: `date +"%B %d, %Y"` for the CLAUDE.md header - - Save preferences to `.claude/vault-config.json`: - ```json - { - "user": { - "name": "Jane Smith", - "background": { - "companies": ["Variance", "Percolate"], - "roles": ["Co-founder", "Writer"], - "publications": ["Why Is This Interesting?", "every.to"], - "expertise": [ - "Developer tools", - "Marketing tech", - "Systems thinking" - ], - "interests": ["AI for thinking", "Note-taking systems", "Creativity"] - }, - "profileSources": [ - "https://whyisthisinteresting.com/about", - "https://every.to/@username" - ], - "customContext": "Focuses on AI as thinking augmentation, not just writing", - "publicProfile": true - }, - "vaultPath": "/path/to/existing/vault", - "fileNamingPattern": "detected-pattern", - "organizationMethod": "PARA", - "primaryUses": ["research", "writing", "projects"], - "tools": { - "geminiVision": true, - "firecrawl": false - }, - "projects": ["Book - Productivity", "SaaS App"], - "areas": ["Newsletter", "Health"], - "importedAt": "2025-01-13", - "lastUpdated": "2025-01-13" - } - ``` - - Start with CLAUDE-BOOTSTRAP.md as base - - Add user-specific sections: - - Custom folder structure with their actual projects/areas - - Personal workflows - - Preferred tools and scripts - - Specific guidelines - - MCP configuration if set up - - Include their websites/resources if provided - - Add any custom naming conventions - - Pre-populate with their projects and areas: - - Create project folders in 01_Projects/ - - Create area folders in 02_Areas/ - - Create resource topics in 03_Resources/ - - Add README files explaining each project/area - -7. **Import Existing Vault (if applicable)** - - If user has existing vault: - - Create OLD_VAULT folder: `mkdir OLD_VAULT` - - Copy entire vault preserving structure: - `cp -r [vault-path]/* ./OLD_VAULT/` - - Copy Obsidian configuration: `cp -r [vault-path]/.obsidian ./` - - Check for and copy other important files: - - `.trash/` (Obsidian's trash folder) - - `.smart-connections/` (if using that plugin) - - Any workspace files: `.obsidian.vimrc`, etc. - - Skip copying: `.git/` (they'll have their own), `.claude/` (using ours) - - Show summary: "Imported your vault to OLD_VAULT/ (X files, Y folders)" - - Explain: "Your original structure is preserved in OLD_VAULT. You can - gradually migrate files to the PARA folders as needed." - -8. **Create Supporting Files** - - Generate initial folder structure if new vault - - Create README files for main folders - - For each project folder, create subfolders: - - Research/ (source materials) - - Chats/ (AI conversations) - - Daily Progress/ (running log) - - Create 05_Attachments/Organized/ directory - - Set up .gitignore if using git (include .mcp.json, node_modules) - - Create initial templates if requested - - Create WEEKLY_REVIEW.md if user wants review ritual - - Remove FIRST_RUN marker file if it exists - - Make initial git commit if repository was initialized - -9. **Run Test Commands** - - Execute `pnpm vault:stats` to verify scripts work - - Test attachment commands if folders exist - - Test MCP tools if configured - - Verify git is tracking files correctly - -10. **Provide Next Steps** - -- Summary of what was created and configured -- Quick start guide specific to their setup -- List of available commands they can use -- Test commands to verify everything works -- Suggestions for first tasks based on their use cases -- How to modify configuration later - -## Example Output - -```markdown -# Your Obsidian Vault Configuration - -Generated on: [Run `date +"%B %d, %Y"` to get current date] Last updated: [Same -date] Based on your preferences for: [main use cases] Setup completed with: ✅ -Dependencies ✅ Folder structure ✅ Git initialized - -## Your Custom Folder Structure - -[Their specific structure with explanations] - -## Your Workflows - -### Daily Routine - -[Based on their answers] - -### Project Management - -[Their specific approach] - -### Research Method (Noah Brier Style) - -- Capture everything you read -- Let important ideas naturally resurface -- Start with writing to test understanding -- Use search, not tags, to find things -- [Learn more from Noah's system](https://every.to/superorganizers/ceo-by-day-internet-sleuth-by-night-267452) - -### Weekly Review Ritual - -[If enabled: Every Thursday at 4pm, review all projects] - -## Your Preferences - -### File Naming - -- Pattern: [their convention] -- Examples: [specific examples] - -### Tools & Scripts - -[Relevant scripts for their workflow] - -## MCP Servers (if configured) - -### Gemini Vision - -- Status: ✅ Configured and tested -- API Key: Set in .mcp.json -- Test with: `Use gemini-vision to analyze [image path]` - -## Available Commands - -### Vault Management - -- `pnpm vault:stats` - Show vault statistics -- `pnpm attachments:list` - List unprocessed attachments -- `pnpm attachments:organized` - Count organized files - -### Claude Commands - -- `claude run thinking-partner` - Collaborative thinking mode -- `claude run daily-review` - Review your day -- `claude run init-bootstrap` - Re-run this setup - -## Quick Start - -1. [Personalized first step] -2. [Next action based on their goals] -3. [Specific to their workflow] - -## Pro Tips from Research Masters - -- **Be a token maximalist**: Provide lots of context to Claude -- **Writing scales**: Document everything for future reference - ([Noah Brier](https://every.to/superorganizers/ceo-by-day-internet-sleuth-by-night-267452)) -- **Trust emergence**: Important ideas will keep surfacing -- **Start with writing**: Always begin projects in text form -- **Review regularly**: Set aside time weekly to prune and update -- **PARA Method**: Projects, Areas, Resources, Archive - ([Tiago Forte](https://fortelabs.com/blog/para/)) - -## Setup Summary - -✅ Dependencies installed (pnpm/npm) ✅ Folder structure created ✅ Git -repository initialized and disconnected from original ✅ CLAUDE.md personalized -✅ First-run setup completed [✅ MCP Gemini Vision configured - if set up] [✅ -First commit made - if git was initialized] -``` - -## Important Implementation Notes - -### Handling Multiple Vaults - -When multiple vaults are detected: - -1. **Always list all vaults found** with clear numbering and details -2. **Require explicit selection** - don't assume which vault to use -3. **Confirm the selection** before proceeding with import -4. **Handle ambiguous responses** - if user provides unclear input (like pasting - a screenshot), ask for clarification: - - "I see you've shared a screenshot. Could you please type the number (1-3) - of the vault you'd like to import?" - - "I need a clear selection. Please type '1', '2', or '3' to choose a vault, - or 'skip' to start fresh." - -### Never Proceed Without Clear Confirmation - -If the user's response is unclear: - -- Don't guess or assume -- Ask for explicit confirmation -- Provide clear options again -- Example: "I want to make sure I import the right vault. Please type the number - of your choice (1, 2, or 3)." - -### Platform Compatibility - -This command is designed to work across Linux, macOS, and Windows (WSL/Git -Bash), with platform-specific features: - -**All Platforms:** - -- Search ~/Documents, ~/Desktop, home directory -- Standard Obsidian vault detection -- Full vault import and setup - -**macOS Only:** - -- iCloud Drive vault detection and import -- Obsidian's iCloud sync is macOS-only, so iCloud features are disabled on other - platforms - -**Platform Detection:** - -```bash -# Check platform -if [[ "$OSTYPE" == "darwin"* ]]; then - # macOS - enable iCloud features - PLATFORM="macOS" - ICLOUD_SUPPORTED=true -elif [[ "$OSTYPE" == "linux-gnu"* ]]; then - # Linux - PLATFORM="Linux" - ICLOUD_SUPPORTED=false -elif [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" ]]; then - # Windows (Git Bash or WSL) - PLATFORM="Windows" - ICLOUD_SUPPORTED=false -fi -``` - -### iCloud Vault Search Implementation - -When searching for vaults, use this find command pattern: - -```bash -# Standard locations (shallow search) -# Note: 2>/dev/null suppresses expected permission errors from system directories -# If no vaults are found, we'll ask the user for their vault path -find ~/Documents ~/Desktop -maxdepth 3 -type d -name ".obsidian" 2>/dev/null - -# iCloud location (deeper search needed due to nested structure) -# Only search on macOS -if [[ "$OSTYPE" == "darwin"* ]]; then - find ~/Library/Mobile\ Documents/iCloud~md~obsidian/Documents -maxdepth 5 -type d -name ".obsidian" 2>/dev/null -fi - -# Home directory (shallow to avoid deep recursion) -find ~ -maxdepth 2 -type d -name ".obsidian" 2>/dev/null -``` - -The iCloud path requires: - -- Higher maxdepth (5) due to nested folder structure -- Escaped spaces in path name -- Silent error handling (2>/dev/null) as many users won't have iCloud -- Platform check (macOS only) - -**Error Handling Note:** Permission errors are suppressed (2>/dev/null) because -they're expected when searching system directories. If no vaults are found, the -script gracefully prompts the user for their vault path. - -### User Path Validation - -When users manually provide a vault path, validate it thoroughly with helpful -error messages: - -```bash -# User provided path -USER_PATH="$1" - -# Expand tilde and resolve to absolute path -USER_PATH="${USER_PATH/#\~/$HOME}" -REAL_PATH=$(realpath "$USER_PATH" 2>/dev/null) - -# Validation 1: Path exists -if [ -z "$REAL_PATH" ]; then - echo "❌ Error: Path does not exist: $USER_PATH" - echo "" - echo "💡 Suggestions:" - echo " • Check for typos in the path" - echo " • Make sure you're using the full path (e.g., /Users/name/vault)" - echo " • You can use ~ for your home directory (e.g., ~/Documents/vault)" - exit 1 -fi - -# Validation 2: Is a directory -if [ ! -d "$REAL_PATH" ]; then - echo "❌ Error: Not a directory: $REAL_PATH" - echo "" - echo "💡 The path exists but points to a file, not a folder." - exit 1 -fi - -# Validation 3: Contains .obsidian folder -if [ ! -d "$REAL_PATH/.obsidian" ]; then - echo "❌ Error: Not a valid Obsidian vault (no .obsidian folder)" - echo " Looking in: $REAL_PATH" - echo "" - echo "💡 Suggestions:" - echo " • Make sure the path points to your vault root (not a subfolder)" - echo " • Check that you've opened this vault in Obsidian at least once" - echo " • Try the path without trailing slash" - echo " • For iCloud: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVault" - exit 1 -fi - -# Validation 4: Readable permissions -if [ ! -r "$REAL_PATH/.obsidian" ]; then - echo "❌ Error: Cannot read vault directory (permission denied)" - echo " Path: $REAL_PATH" - echo "" - echo "💡 You may need to:" - echo " • Check file permissions with: ls -la \"$REAL_PATH\"" - echo " • Make sure you own this directory" - exit 1 -fi - -# Show resolved path if different from input -if [ "$USER_PATH" != "$REAL_PATH" ]; then - echo "✓ Resolved path: $REAL_PATH" -fi - -# Valid vault path -VAULT_PATH="$REAL_PATH" -echo "✓ Valid Obsidian vault found" -``` - -This validation: - -- Expands `~` to home directory properly -- Resolves symlinks and relative paths to absolute paths -- Checks all essential requirements (exists, is directory, has .obsidian, - readable) -- Provides helpful, actionable error messages with suggestions -- Shows the resolved path so users understand what's being checked -- Trusts users (allows symlinks, paths outside home directory) -- Cross-platform compatible (works on Linux, macOS, Windows/WSL) - -### iCloud Sync State Checking - -When a user selects an iCloud vault, check sync state and warn if needed: - -```bash -# After user confirms vault selection -if [[ "$OSTYPE" == "darwin"* ]] && [[ "$vault_path" == *"iCloud"* ]]; then - # Check for common iCloud sync indicators - if [ -f "$vault_path/.icloud" ] || [ -f "$vault_path/.obsidian/.icloud" ]; then - echo "" - echo "📱 iCloud Sync Notice:" - echo " This vault appears to be still downloading from iCloud." - echo " For best results, open it in Obsidian first to ensure files are synced." - echo "" - read -p "Continue anyway? (yes/no): " sync_answer - if [[ ! "$sync_answer" =~ ^[Yy] ]]; then - echo "No problem! Open the vault in Obsidian, then re-run /init-bootstrap" - exit 0 - fi - else - echo "" - echo "📱 iCloud vault detected. If import seems incomplete, make sure sync is complete." - echo "" - fi -fi -``` - -This provides a soft warning that: - -- Only runs on macOS for iCloud paths -- Checks for placeholder files that indicate incomplete download -- Asks for confirmation if sync issues detected -- Gives gentle reminder even when no issues found -- Lets users proceed if they choose - -## Interactive Example - -```` -User: claude run init-bootstrap -Assistant: Welcome! I'll help you set up your personalized Obsidian + Claude configuration. - -📅 Today's date: [Gets from `date +"%B %d, %Y"`] - -First, let me check your setup... - -📁 **Folder Name Check** -Current folder: claudesidian -Would you like to rename this folder to something more personal? (e.g., my-vault, knowledge-base, obsidian-notes) -*Why: Your vault should have a name that makes sense to you - you'll see it every day!* - -[If yes: Handles the rename by moving to parent directory and back] - -Now setting up your environment... - -📦 **Installing Dependencies** -[Checks for pnpm, uses npm if not available] -[Installs dependencies with pnpm/npm] -*Why: These tools enable Claude Code to work with your vault effectively* - -🔓 **Repository Setup** - -**Will you be contributing to claudesidian development?** -- **No** (Personal vault only) → I'll remove GitHub workflows and disconnect from the repo -- **Yes** (I want to contribute) → I'll keep the development setup intact - -[Implementation:] -```bash -# If user says "No" (personal vault): -rm -rf .github # Remove GitHub workflows -git remote remove origin # Disconnect from claudesidian repo - -# If user says "Yes" (contributing): -# Keep .github folder and origin remote -echo "Development setup preserved for contributing" -```` - -_Why: Personal vaults don't need GitHub Actions, but contributors benefit from -the automation_ - -📂 **Creating Folder Structure** [Creates folders based on your chosen -organization method] _Why: A good structure helps you organize and find your -knowledge effectively_ - -🎯 **Finalizing Setup** [Checks git status and removes first-run marker] _Why: -Git gives you version control, and removing the marker ensures you won't see the -welcome message again_ - -✅ Folder renamed (if requested) ✅ Dependencies installed ✅ Core folders -created ✅ Git repository ready (disconnected from original claudesidian) ✅ -First-run marker removed - -Now let me ask you a few questions to customize your setup: - -🔍 **Searching for existing Obsidian vaults...** [Searches ~/Documents, -~/Desktop, home directory, and parent directories. On macOS, also searches -iCloud Drive] - -### Case 1: Single Vault Found - -Found Obsidian vault at: ~/Documents/MyNotes 📊 Vault stats: 2,517 markdown -files, 1.1GB total size Would you like to import this vault? - -- **yes** - Import this vault -- **no** - Search for a different vault -- **skip** - Start fresh without importing -- **path** - Specify a different path manually - -User: yes - -### Case 2: Multiple Vaults Found - -🔍 **Found multiple Obsidian vaults:** - -1. **~/Documents/MyNotes** (2,517 files, 1.1GB) - - Last modified: 2 hours ago - - Contains: Daily notes, projects, resources - -2. **~/Desktop/WorkVault** (892 files, 450MB) - - Last modified: 3 days ago - - Contains: Client projects, meeting notes - -3. **~/Documents/ObsidianVault** (156 files, 23MB) - - Last modified: 2 weeks ago - - Contains: Personal notes, drafts - -**Which vault would you like to import?** - -- Enter **1-3** to select a vault -- **all** - Import all vaults (each to a separate folder) -- **skip** - Start fresh without importing -- **path** - Specify a different path manually - -User: 1 - -**Confirming your selection:** You selected: ~/Documents/MyNotes (2,517 files, -1.1GB) - -Is this correct? (yes/no) - -User: yes - -Great! I'll import your vault to OLD_VAULT/ where it will be safely preserved. -You can migrate files to the PARA folders at your own pace. - -### Case 3: No Vaults Found (Platform-Aware) - -🔍 **No Obsidian vaults found in common locations.** - -**On macOS:** Is your vault stored in iCloud Drive? (yes/no) - -User: yes - -Please enter the full path to your vault: (Example: ~/Library/Mobile -Documents/iCloud~md~obsidian/Documents/YourVault) - -User: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault - -[Validates path and shows vault stats] - -Found vault at: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault -📊 Vault stats: 1,248 markdown files, 523MB total size - -Would you like to import this vault? (yes/skip) - -**On Linux/Windows:** Please enter the path to your existing Obsidian vault, or -type 'skip' to start fresh: (Example: ~/Documents/MyVault or -/home/user/obsidian-vault) - -User: ~/Documents/MyVault - -[Validates path and shows vault stats] - -Found vault at: ~/Documents/MyVault 📊 Vault stats: 1,248 markdown files, 523MB -total size - -Would you like to import this vault? (yes/skip) - -📦 **Analyzing your vault structure...** [Running tree to see folder hierarchy] -[Sampling notes to understand content] [Detecting naming patterns from recent -files] - -I can see you're using: - -- A modified PARA structure with custom folders -- Date-prefixed files for daily notes (YYYY-MM-DD) -- Project folders with nested research -- Heavy use of the Resources folder for reference material - -📦 **Importing your vault...** [Copying files to OLD_VAULT/] [Preserving -.obsidian settings] [Checking for plugin folders] - -✅ Imported 2,517 files (1.1GB) to OLD_VAULT/ Your original structure is -completely preserved! - -Now let's personalize your setup: - -1. **What's your name?** - - _Why I'm asking:_ I'll use this to personalize your CLAUDE.md file and help - me understand your context better. This creates a more tailored experience - where I can reference your work and interests naturally. - -User: Noah Brier - -2. **Would you like me to research your public work?** - - _Why this helps:_ By understanding your background, expertise, and interests, - I can: - - Tailor suggestions to your specific field and workflow - - Reference relevant examples from your domain - - Better understand the context of your questions - - Build a profile that helps me be a more effective thinking partner - -User: Yes - -Great! To make sure I find information about the real you, could you provide any -of these details? - -- Your company or organization -- Your location (city/country) -- A unique project you've worked on -- Your website or social media handle -- Any other distinguishing information - -This helps me avoid confusion with others who share your name. - -User: I co-founded Variance and Percolate, I write at every.to - -Perfect! Let me search for you with those details... - -[Searches for information using the provided identifying information] - -Based on your details, I found you - Noah Brier, co-founder of Variance and -Percolate, writer at every.to. - -Let me confirm this is correct: - -- Co-founded Variance (developer tools) and Percolate (marketing software) -- Write at every.to and Why Is This Interesting? newsletter -- Focus on systems thinking, creativity, and technology - -Is this you? (yes/no) - -User: yes - -Excellent! I've identified the right profile. - -**Building Your Profile** Would you like me to read any specific pages to better -understand your work? - -- Your personal website or blog -- Recent articles or papers you've written -- Company/project pages -- LinkedIn or other profiles - -Enter URLs (comma-separated) or 'skip' to continue: - -User: https://whyisthisinteresting.com/about, https://every.to/@noahbrier - -[Fetches and analyzes the provided URLs] - -I've built a comprehensive profile: - -- You co-founded Variance (developer tools) and Percolate (marketing software) -- You write Why Is This Interesting? newsletter with Colin Nagy -- You explore creativity, technology, and systems thinking -- You've written about writing as thinking, note-taking systems, and AI - -Is there anything else I should know about your work or interests? - -User: I'm really interested in how AI can augment thinking, not just writing - -Got it! I'll remember that you focus on AI as a thinking tool, not just a -writing assistant. - -3. **What will you primarily use this vault for?** (research, writing, project - management, daily notes, knowledge base, or combination?) - -User: I'll use it for research and writing, plus managing client projects - -Assistant: Great! I'll configure your vault for research, writing, and client -project management. - -2. **What specific projects are you currently working on?** (I'll create folders - for each in 01_Projects) - -User: I'm writing a book about productivity systems, building a SaaS app, and -planning a conference talk - -Assistant: Perfect! I'll set up project folders for: - -- 01_Projects/Book - Productivity Systems/ -- 01_Projects/SaaS App Development/ -- 01_Projects/Conference Talk/ - -3. **What ongoing areas of responsibility do you maintain?** (These go in - 02_Areas - things without an end date) - -User: My newsletter, health & fitness, personal finances, and family activities - -Assistant: I'll create area folders for: - -- 02_Areas/Newsletter/ -- 02_Areas/Health & Fitness/ -- 02_Areas/Finances/ -- 02_Areas/Family/ - -4. **What topics do you frequently research or reference?** (I'll organize these - in 03_Resources) - -User: AI tools, productivity methods, SaaS metrics, and writing techniques - -Assistant: Setting up resource folders for: - -- 03_Resources/AI Tools/ -- 03_Resources/Productivity Methods/ -- 03_Resources/SaaS Metrics/ -- 03_Resources/Writing Techniques/ - -[Continues with questions...] - -**Gemini Vision Setup** Gemini Vision is already included in claudesidian! It -can analyze images, PDFs, and videos in your vault. To activate it, you just -need a free Google API key (takes 30 seconds). Would you like to set it up now? -(yes/no/later) - -User: later - -No problem! You can set it up anytime by running `/setup-gemini` when you're -ready. - -**Firecrawl Setup** Firecrawl is a game-changer for research! Save any article -or website directly to your vault as markdown. Perfect for building a permanent, -searchable research library. Would you like to set it up? (yes/no/later) - -User: yes - -Great choice! Firecrawl will transform how you collect research. - -Assistant: Excellent! Here's how to get your API key: - -1. Go to https://aistudio.google.com/apikey -2. Click "Create API Key" -3. Copy the key (starts with AIzaSy...) - -Once you have it, paste it here and I'll configure everything for you. diff --git a/.claude/commands/install-claudesidian-command.md b/.claude/commands/install-claudesidian-command.md deleted file mode 100644 index 44abedd..0000000 --- a/.claude/commands/install-claudesidian-command.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -allowed-tools: [Read, Write, Bash] -description: Install claudesidian shell command to launch Claude Code from anywhere -argument-hint: (optional shell: bash/zsh/fish) ---- - -# Install Claudesidian Command - -Creates a shell alias/function that allows you to run `claudesidian` from -anywhere to open your vault in Claude Code. - -## Task - -Install a shell command that: - -1. Changes to your claudesidian vault directory -2. Launches Claude Code -3. Works from any directory in your terminal - -Similar to having a quick launcher for your vault. - -## Process - -### 1. **Detect Current Setup** - -- Check which shell the user is using (bash/zsh/fish) -- Find the current working directory (vault path) -- Determine the appropriate config file - -### 2. **Create the Command** - -The command will be an alias that: - -- Changes to the vault directory: `cd /path/to/your/vault` -- Tries to resume existing session: `claude --resume 2>/dev/null` -- Falls back to new session if no existing one: `|| claude` -- All in one command with properly escaped path: - `(cd "/path/to/vault" && (claude --resume 2>/dev/null || claude))` - -**Important:** The path must be properly escaped to handle spaces and special -characters. - -This automatically enters resume mode if there's an existing session, or starts -a new one if not. - -### 3. **Install to Shell Config** - -Add the alias to the appropriate config file: - -- **Bash**: `~/.bashrc` or `~/.bash_profile` -- **Zsh**: `~/.zshrc` -- **Fish**: `~/.config/fish/config.fish` - -### 4. **Verify Installation** - -- Show the added line -- Remind user to reload their shell or source the config -- Provide test command - -## Shell Detection - -Detects the user's default shell, with support for command-line override: - -```bash -# Check if shell specified as argument (/install-claudesidian-command zsh) -if [ -n "$1" ]; then - # User provided shell type as argument - SHELL_TYPE="$1" -else - # Auto-detect from $SHELL (user's default shell, not current shell) - SHELL_TYPE=$(basename "$SHELL") -fi - -# Validate shell type and set appropriate config file -case "$SHELL_TYPE" in - zsh) - CONFIG_FILE="$HOME/.zshrc" - ;; - bash) - # Prefer .bashrc on Linux, .bash_profile on macOS - if [ -f "$HOME/.bashrc" ]; then - CONFIG_FILE="$HOME/.bashrc" - else - CONFIG_FILE="$HOME/.bash_profile" - fi - ;; - fish) - CONFIG_FILE="$HOME/.config/fish/config.fish" - ;; - *) - echo "❌ Unsupported shell: $SHELL_TYPE" - echo " Supported shells: bash, zsh, fish" - echo " Usage: /install-claudesidian-command [bash|zsh|fish]" - exit 1 - ;; -esac - -echo "🐚 Installing for: $SHELL_TYPE" -echo "📝 Config file: $CONFIG_FILE" -``` - -**Key improvements:** - -- Uses `$SHELL` to detect default shell (not `$ZSH_VERSION`/`$BASH_VERSION` - which detect current session) -- Supports command-line argument to override auto-detection -- Shows detected shell and config file for transparency -- Validates shell type and provides clear error message for unsupported shells - -## Installation Steps - -1. **Detect shell**: Use argument if provided, otherwise auto-detect from - `$SHELL` -2. **Get vault path**: Use `pwd` to get current directory -3. **Escape the path**: Properly escape quotes and special characters for shell - safety - ```bash - # Escape any double quotes in the path - ESCAPED_PATH="${VAULT_PATH//\"/\\\"}" - # Also escape backslashes - ESCAPED_PATH="${ESCAPED_PATH//\\/\\\\}" - ``` -4. **Check if already installed**: Search config file for existing - `claudesidian` alias/function - ```bash - # Check for existing alias/function - if grep -q "alias claudesidian\|function claudesidian" "$CONFIG_FILE"; then - echo "⚠️ Found existing claudesidian command:" - grep -A 3 "claudesidian" "$CONFIG_FILE" - echo "" - read -p "Replace it? (yes/no): " replace_answer - if [[ ! "$replace_answer" =~ ^[Yy] ]]; then - echo "Installation cancelled. Existing command preserved." - exit 0 - fi - # Mark for replacement (will remove before adding new one) - REPLACING=true - fi - ``` -5. **Get user confirmation**: Show what will be added and get final confirmation -6. **Create backup**: Only if proceeding with modification - ```bash - # Create backup with timestamp - BACKUP_FILE="$CONFIG_FILE.backup-$(date +%Y%m%d-%H%M%S)" - cp "$CONFIG_FILE" "$BACKUP_FILE" - echo "💾 Backup created: $BACKUP_FILE" - ``` -7. **Build the safe alias/function command**: Use the escaped path from step 3 - ```bash - # CRITICAL: Use $ESCAPED_PATH in the command (not raw $VAULT_PATH) - if [ "$SHELL_TYPE" = "fish" ]; then - # Fish uses function syntax, not alias - COMMAND_TEXT="function claudesidian - cd \"$ESCAPED_PATH\" && (claude --resume 2>/dev/null; or claude) - cd - - end" - else - # Bash/Zsh use alias syntax - # IMPORTANT: Use double quotes around $ESCAPED_PATH to preserve escaping - COMMAND_TEXT="alias claudesidian='(cd \"$ESCAPED_PATH\" && (claude --resume 2>/dev/null || claude))'" - fi - ``` -8. **Remove old command if replacing**: - ```bash - if [ "$REPLACING" = true ]; then - # Remove old alias/function before adding new one - sed -i.tmp '/alias claudesidian\|function claudesidian/,/^end$/d' "$CONFIG_FILE" - rm -f "$CONFIG_FILE.tmp" - fi - ``` -9. **Add command to config file**: Append using the escaped command text - ```bash - echo "$COMMAND_TEXT" >> "$CONFIG_FILE" - ``` -10. **Show success message**: With instructions to reload shell - -## Example Output - -**Bash/Zsh Example (with spaces in path to demonstrate escaping):** - -``` -🔧 Installing claudesidian command... - -📁 Vault path: /home/user/My Obsidian Vault -🐚 Shell detected: zsh -📝 Config file: /home/user/.zshrc - -💾 Backup created: /home/user/.zshrc.backup-20250107-143025 - -✅ Installed! Added to /home/user/.zshrc: - alias claudesidian='(cd "/home/user/My Obsidian Vault" && (claude --resume 2>/dev/null || claude))' - -🔄 To activate, run: - source ~/.zshrc - - Or start a new terminal session. - -✨ Test it: Type 'claudesidian' from any directory! -``` - -**Fish Shell Example:** - -``` -🔧 Installing claudesidian command... - -📁 Vault path: /home/user/My Obsidian Vault -🐚 Shell detected: fish -📝 Config file: /home/user/.config/fish/config.fish - -💾 Backup created: /home/user/.config/fish/config.fish.backup-20250107-143025 - -✅ Installed! Added to /home/user/.config/fish/config.fish: - function claudesidian - cd "/home/user/My Obsidian Vault" && (claude --resume 2>/dev/null; or claude) - cd - -end - -🔄 To activate, run: - source ~/.config/fish/config.fish - - Or start a new terminal session. - -✨ Test it: Type 'claudesidian' from any directory! -``` - -## Handling Special Characters - -The implementation properly handles paths with: - -- Spaces: `/Users/noah/My Vault` -- Quotes: `/Users/noah/vault's backup` -- Special characters that need escaping - -Paths are double-quoted and any embedded quotes/backslashes are escaped. - -## Fish Shell Support - -Fish shell uses different syntax than Bash/Zsh: - -**Bash/Zsh (alias):** - -```bash -alias claudesidian='(cd "/path" && command)' -``` - -**Fish (function):** - -```fish -function claudesidian - cd "/path" && (command; or fallback) - cd - -end -``` - -Key differences: - -- Fish uses `function` keyword instead of `alias` for complex commands -- Fish uses `; or` instead of `||` for fallback logic -- Fish uses `cd -` to return to previous directory (instead of subshell) -- Multi-line function definition instead of single-line alias - -The installation automatically detects Fish and uses the correct syntax. - -## Security Considerations - -This command modifies your shell configuration file (a sensitive operation). -Safety measures: - -- **You'll see exactly what will be added** before any changes -- **Timestamped backup is automatically created** before modification -- **Vault path is properly escaped** to prevent injection attacks -- **Only the claudesidian command is modified** - nothing else in your config -- **Asks permission** before replacing existing commands - -If anything goes wrong, restore from: `$CONFIG_FILE.backup-YYYYMMDD-HHMMSS` - -## Important Notes - -- The command uses a subshell `()` (or `cd -` in Fish) so it returns to your - original directory after -- Automatically tries to resume existing sessions, falls back to new session -- If alias/function already exists, asks user if they want to replace it -- Always shows what will be added before modifying config files -- **Always creates timestamped backup** of config file before modifying (format: - `YYYYMMDD-HHMMSS`) -- Backups are kept indefinitely - users can manually clean up old backups if - needed -- Shows backup location so users know where to restore from if needed - -## Usage Examples - -Install for your default shell (auto-detected): - -``` -/install-claudesidian-command -``` - -Install for specific shell (override auto-detection): - -``` -/install-claudesidian-command zsh -/install-claudesidian-command bash -/install-claudesidian-command fish -``` - -**When to specify shell:** - -- You use multiple shells and want to install for a specific one -- Auto-detection picked the wrong shell -- You're setting up for someone else - -## How It Works - -**Bash/Zsh (alias with subshell):** - -```bash -alias claudesidian='(cd "/path/to/vault" && (claude --resume 2>/dev/null || claude))' -``` - -1. `(cd "/path/to/vault" && ...)` - Subshell that changes directory temporarily - (path is double-quoted for safety) -2. `claude --resume 2>/dev/null` - Tries to resume existing session, suppresses - error -3. `|| claude` - If resume fails (no session), starts new session -4. After Claude exits, subshell closes and returns to original directory - automatically - -**Fish (function with cd -):** - -```fish -function claudesidian - cd "/path/to/vault" && (claude --resume 2>/dev/null; or claude) - cd - -end -``` - -1. `cd "/path/to/vault"` - Changes to vault directory (path is double-quoted for - safety) -2. `claude --resume 2>/dev/null` - Tries to resume existing session, suppresses - error -3. `; or claude` - If resume fails (no session), starts new session (Fish - syntax) -4. `cd -` - Returns to previous directory after Claude exits diff --git a/.claude/commands/pragmatic-review.md b/.claude/commands/pragmatic-review.md index 32c7ae6..9371c52 100644 --- a/.claude/commands/pragmatic-review.md +++ b/.claude/commands/pragmatic-review.md @@ -1,3 +1,6 @@ +risk: low +writes: none (read-only) + --- name: pragmatic-review description: diff --git a/.claude/commands/pull-request.md b/.claude/commands/pull-request.md index ef526d4..1cb02dd 100644 --- a/.claude/commands/pull-request.md +++ b/.claude/commands/pull-request.md @@ -1,4 +1,6 @@ # Pull Request Command +risk: high +writes: git remote (push + PR) Creates a new feature branch, commits changes, pushes to GitHub, and opens a pull request - all in one command. Perfect for contributing features or fixes. diff --git a/.claude/commands/release.md b/.claude/commands/release.md index 826f094..2ff7647 100644 --- a/.claude/commands/release.md +++ b/.claude/commands/release.md @@ -1,3 +1,6 @@ +risk: high +writes: git remote (tag + push) + --- name: release description: diff --git a/.claude/commands/research-assistant.md b/.claude/commands/research-assistant.md index 60307f0..2247bf4 100644 --- a/.claude/commands/research-assistant.md +++ b/.claude/commands/research-assistant.md @@ -1,4 +1,6 @@ # Research Assistant +risk: medium +writes: 03_Resources/ Conduct thorough research on topics by searching the vault and synthesizing findings. diff --git a/.claude/commands/thinking-partner.md b/.claude/commands/thinking-partner.md index 59bca5d..c8e648e 100644 --- a/.claude/commands/thinking-partner.md +++ b/.claude/commands/thinking-partner.md @@ -1,4 +1,6 @@ # Thinking Partner +risk: low +writes: none (conversation) You are a collaborative thinking partner specializing in helping people explore complex problems. Your role is to facilitate thinking through careful diff --git a/.claude/commands/upgrade.md b/.claude/commands/upgrade.md deleted file mode 100644 index 4463448..0000000 --- a/.claude/commands/upgrade.md +++ /dev/null @@ -1,645 +0,0 @@ ---- -name: upgrade -description: - Intelligently upgrade claudesidian with new features while preserving user - customizations using AI-powered semantic analysis -allowed-tools: [Read, Write, Edit, MultiEdit, Bash, WebFetch, Grep, Glob] -argument-hint: - "(optional) 'check' to preview changes, 'force' to skip confirmations" ---- - -# Smart Upgrade Command - -Intelligently upgrades your claudesidian installation by fetching the latest -release from GitHub and using AI-powered semantic analysis to merge new features -with your existing customizations. Preserves user intent while adding new -capabilities. - -## Task - -1. Check GitHub for the latest claudesidian release -2. Download and analyze what has changed since your version -3. Use Claude's semantic understanding to identify user customizations -4. Intelligently merge new features with existing customizations -5. Safely apply updates while preserving user data and preferences -6. Create backups and provide rollback options - -## Process - -### 1. **Version Check & Setup** - -- Get current version from package.json -- Check if already on latest version: - - ```bash - # Use cut instead of sed to avoid zsh parentheses escaping issues - CURRENT=$(grep '"version"' package.json | head -1 | cut -d'"' -f4) - LATEST=$(curl -s https://raw.githubusercontent.com/heyitsnoah/claudesidian/main/package.json | grep '"version"' | head -1 | cut -d'"' -f4) - - if [ "$CURRENT" = "$LATEST" ]; then - echo "✅ You're already on the latest version ($CURRENT)" - exit 0 - fi - ``` - -- Create timestamped backup in `.backup/upgrade-YYYY-MM-DD-HHMMSS/`: - - ```bash - # Create backup directory - BACKUP_DIR=".backup/upgrade-$(date +%Y-%m-%d-%H%M%S)" - mkdir -p "$BACKUP_DIR" - - # Copy all important files to backup - cp -r .claude "$BACKUP_DIR/" - cp -r .scripts "$BACKUP_DIR/" - cp package.json "$BACKUP_DIR/" - cp CHANGELOG.md "$BACKUP_DIR/" 2>/dev/null || true - cp README.md "$BACKUP_DIR/" 2>/dev/null || true - - echo "✅ Backup created in $BACKUP_DIR" - ``` - -- Clone latest claudesidian to temp directory (doesn't affect user's repo): - ```bash - # Get fresh copy in .tmp dir (hidden from Obsidian) - user's repo stays disconnected - git clone --depth=1 --branch=main https://github.com/heyitsnoah/claudesidian.git .tmp/claudesidian-upgrade - ``` -- Now we have latest version to compare against - -### 2. **Create Upgrade Checklist** - -- Compare system files between current directory and .tmp/claudesidian-upgrade/: - - ```bash - # Find all system files that differ AND new files in upstream - # First, find files that exist in both but differ - diff -qr . .tmp/claudesidian-upgrade/ --include="*.md" --include="*.sh" --include="*.json" | - grep -E '(\.claude/|\.scripts/|package\.json|CHANGELOG\.md|README\.md)' | - grep -v '(00_|01_|02_|03_|04_|05_|06_|\.obsidian|CLAUDE\.md)' - - # Also find NEW files in upstream (like new commands) - find .tmp/claudesidian-upgrade/.claude/commands -name "*.md" | while read f; do - local_file=${f#.tmp/claudesidian-upgrade/} - [ ! -f "$local_file" ] && echo "NEW: $local_file" - done - ``` - -- Create checklist of files that need review -- Explicitly EXCLUDE: - - User content folders (00_Inbox, 01_Projects, etc.) - - User's CLAUDE.md (their personalized version) - - vault-config.json (user's vault configuration) - - .obsidian/ (user's Obsidian settings) - - Any .md files in the root except README and CHANGELOG -- Create `.upgrade-checklist.md` with only system files that differ -- Mark each file with status: `[ ] pending`, `[x] updated`, `[-] skipped` -- Group files by type for easier review: - - ```markdown - ## Commands (12 files) - - [ ] .claude/commands/init-bootstrap.md [ ] .claude/commands/release.md [ ] - .claude/commands/thinking-partner.md ... - - ## Settings (2 files) - - [ ] .claude/settings.json [ ] .claude/settings.local.json - - ## Core Files (3 files) - - [ ] package.json [ ] CHANGELOG.md [ ] README.md - ``` - -### 3. **File-by-File Review** - -**⚠️ CRITICAL IMPLEMENTATION REQUIREMENT:** - -- **NEVER blindly overwrite files without showing diffs first** -- **ALWAYS show diffs to the user first** -- **ALWAYS ask for confirmation before replacing files** -- **Skipping these steps can lose user customizations!** -- **NEVER use `cp` or `cp -f` (both can cause prompts on protected files)** -- **ALWAYS USE `cat source > dest` for guaranteed non-interactive replacement** -- **WAIT for actual user input - don't automatically choose option 1** - -For EACH file in the checklist: - -1. Read current checklist status from `.upgrade-checklist.md` -2. **MANDATORY: Show the diff between local and upstream**: - ```bash - # ALWAYS show this to the user! - diff -u current/file .tmp/claudesidian-upgrade/file - ``` -3. Determine update strategy: - - **No local changes**: Direct replace from upstream - - **Never update**: User's CLAUDE.md, vault-config.json, .mcp.json - - **Local changes detected**: Ask user: - - ``` - File: .claude/commands/thinking-partner.md has local modifications - - Options: - 1. Keep your version (skip update) - 2. Take upstream version (lose your changes) - 3. View diff and decide - 4. Try to merge both (AI-assisted) - - Choice (1/2/3/4): [WAIT FOR USER TO TYPE NUMBER AND PRESS ENTER] - ``` - - **IMPORTANT**: Actually WAIT for the user to type their choice! Do NOT - automatically select any option. The user must manually type 1, 2, 3, or 4 - and press Enter. - -4. Apply the chosen strategy: - - **For option 1 (Apply update/Take upstream)**: - ```bash - # IMPORTANT: Check if file exists first, then use cat with redirection - if [ -f ".tmp/claudesidian-upgrade/path/to/file" ]; then - cat .tmp/claudesidian-upgrade/path/to/file > path/to/file && echo "✅ Updated" - else - echo "⚠️ File not found in upstream - keeping local version" - fi - ``` - - **For option 2 (Keep your version)**: - ```bash - echo "✅ Kept your version" - ``` - - **For option 4 (AI merge)**: Read both files and create merged version -5. **CRITICAL: Update the checklist file immediately**: - ```markdown - [ ] .claude/commands/init-bootstrap.md → becomes → [x] - .claude/commands/init-bootstrap.md - ``` -6. Save `.upgrade-checklist.md` after EVERY file update -7. Move to next file - -### 4. **Update Types** - -- **Safe to replace**: `.claude/commands/*.md`, `.claude/agents/*.md`, - `.scripts/*` -- **Needs review**: `package.json` (preserve user's custom scripts) -- **Never touch**: User content folders, CLAUDE.md, API configs - -#### Batch Updates for Similar Files - -For commands that have only formatting changes, you can batch update: - -```bash -# Batch update multiple command files with same type of changes -for file in thinking-partner.md daily-review.md inbox-processor.md; do - if [ -f ".tmp/claudesidian-upgrade/.claude/commands/$file" ]; then - cat ".tmp/claudesidian-upgrade/.claude/commands/$file" > ".claude/commands/$file" - echo "✅ Updated $file" - fi -done -``` - -#### Handling Missing Upstream Files - -Some files may exist locally but not in upstream (like deprecated agents): - -```bash -# Check if file exists in upstream before trying to update -if [ ! -f ".tmp/claudesidian-upgrade/$filepath" ]; then - echo "⚠️ $filepath not in upstream - keeping local version" - # Mark as skipped in checklist: [-] -fi -``` - -### 5. **Progress Tracking** - -- Use TodoWrite tool to track progress alongside the checklist -- Save progress after each file in `.upgrade-checklist.md` -- **MUST mark items in checklist**: - - `[x]` = completed - - `[-]` = skipped (user customization) - - `[ ]` = still pending -- If interrupted, can resume from where you left off -- Show progress: "Updating file 5 of 23..." -- Clear indication of what's been done and what's remaining - -### 6. **Verification Check** - -- Re-check all system files against the checklist -- Compare with checklist to identify: - - Files marked `[ ]` pending = likely missed (problem) - - Files marked `[-]` skipped = intentionally kept different (fine) - - Files marked `[x]` updated but still in diff = merge issues or user edits - (review) -- Show verification results: - ``` - ✅ All required files updated successfully - ℹ️ 2 files intentionally kept with user customizations: - - .claude/commands/thinking-partner.md (user's concise style) - - package.json (user's custom scripts preserved) - - or - - ⚠️ Warning: 2 files appear to be missed (still marked pending): - - .claude/commands/release.md - - .scripts/vault-stats.sh - ``` -- Only flag as problem if files are still marked `[ ]` pending in checklist - -### 7. **Final Steps** - -- Update version in package.json -- Verify all commands work -- Clean up temp directory: `rm -rf .tmp/claudesidian-upgrade` -- Save final checklist for reference (shows what was updated vs skipped) -- Show summary of what was updated - -## Update Categories - -### 🤖 AI-Powered Intelligent Merge - -**Commands** (`.claude/commands/*.md`): - -- Analyze user's prompt style, output preferences, workflow modifications -- Merge new features with existing customizations -- Preserve user's tone, structure, and specific requirements - -**Agents** (`.claude/agents/*.md`): - -- Understand user's interaction preferences -- Combine new capabilities with existing personality -- Maintain user's established workflows - -**Templates** (`06_Metadata/Templates/*.md`): - -- Preserve custom fields and structure -- Add new template features -- Maintain user's formatting preferences - -### ⚡ Automatic Safe Updates - -- **New commands/agents**: Purely additive, no conflicts -- **Scripts** (`.scripts/*`): Utility functions, safe to replace -- **Dependencies** (`package.json`): Security and feature updates -- **Documentation**: README, CONTRIBUTING updates - -### 🛡️ Never Modified - -- **User content**: All `00_*` through `06_*` folders (except templates) -- **Personal config**: User's `CLAUDE.md` -- **API keys**: `.mcp.json`, environment variables -- **Git history**: User's commits and branches - -## Smart Conflict Resolution - -When Claude detects conflicts: - -### Example Scenarios: - -**Scenario 1: Command Enhancement** - -``` -📝 thinking-partner command has updates: - -YOUR VERSION: Custom concise output format, specific industry focus -NEW VERSION: Added video analysis capability, improved questioning flow - -🤖 SMART MERGE PROPOSAL: -✅ Keep your concise output style -✅ Keep your industry-specific prompts -✅ Add new video analysis features -✅ Integrate improved questioning (adapted to your style) - -Options: -1. 🎯 Apply smart merge (recommended) -2. 👀 Show detailed diff first -3. 🚫 Skip this update -4. 💾 Replace with new version (backup yours) -``` - -**Scenario 2: Template Updates** - -``` -📋 Project Template has changes: - -YOUR VERSION: Added custom fields for client info, budget tracking -NEW VERSION: Enhanced metadata structure, new automation hooks - -🤖 SMART MERGE PROPOSAL: -✅ Preserve your custom client/budget fields -✅ Add new metadata enhancements -✅ Integrate automation hooks -✅ Maintain your field ordering - -Apply merge? (y/n/preview) -``` - -## Command Usage - -### Preview Mode (Recommended First Run) - -``` -/upgrade check -``` - -- Shows what would be updated -- Displays intelligent merge previews -- No changes made to files -- Safe to run anytime - -### Interactive Upgrade - -``` -/upgrade -``` - -- Step-by-step confirmation for each change -- Shows before/after for modified files -- Allows selective application of updates -- Creates automatic backups - -### Batch Upgrade (Advanced) - -``` -/upgrade force -``` - -- Applies all safe updates automatically -- Still prompts for complex merges -- Faster for users comfortable with the process -- Full backup created before starting - -## Safety Features - -### Automatic Backups - -- Complete backup before any changes: `.backup/upgrade-[timestamp]/` -- Individual file backups for each modification -- Backup includes current git state and uncommitted changes - -### Rollback Support - -``` -# If upgrade causes issues: -/rollback-upgrade [timestamp] -# Restores from specific backup -``` - -### Verification Steps - -- Post-upgrade functionality testing -- Command validation (runs test commands) -- MCP server connectivity check -- Git repository integrity verification - -### Incremental Application - -- Updates applied one file at a time -- Validation after each critical change -- Stops on first error with clear diagnostics -- Easy to identify which change caused issues - -## Common Pitfalls to Avoid - -### ⚠️ Selective Updates Problem - -**Never cherry-pick files based only on release notes!** This leads to: - -- Missing critical command updates -- Incomplete feature implementations -- Broken dependencies between files -- Users not getting all improvements - -**Always use `git diff HEAD upstream/main --name-only`** to get the complete -list of changed files, then update ALL relevant files systematically. - -## Error Handling - -### Common Scenarios - -- **No internet connection**: Graceful failure with offline options -- **GitHub API rate limits**: Intelligent retry with backoff -- **Merge conflicts**: Clear explanation and manual resolution options -- **Permission issues**: Helpful guidance on fixing file permissions - -### Recovery Options - -- **Partial failure**: Continue from last successful step -- **Complete failure**: Full rollback to pre-upgrade state -- **Git conflicts**: Merge upstream changes with local commits -- **Dependency issues**: Fallback to previous working versions - -## Advanced Features - -### Custom Merge Rules - -Users can create `.upgrade-rules.json` to specify: - -- Files to always skip -- Custom merge preferences -- Automatic approval for specific change types -- Backup retention policies - -### Integration with Git - -- Commits each major change separately -- Meaningful commit messages describing updates -- Preserves user's branch structure -- Handles git conflicts intelligently - -### Selective Updates - -``` -/upgrade commands-only # Update just commands -/upgrade agents-only # Update just agents -/upgrade scripts-only # Update just scripts -/upgrade deps-only # Update just dependencies -``` - -## CORRECT Implementation Example - -**THIS is how the upgrade should work:** - -```bash -📄 File 1/3: .claude/commands/release.md - -# Step 1: ALWAYS show the diff first -Checking for differences... - ---- .claude/commands/release.md -+++ .tmp/claudesidian-upgrade/.claude/commands/release.md -@@ -58,6 +58,11 @@ - - ### Semantic Versioning (MAJOR.MINOR.PATCH) - -+**Quick Decision Guide:** -+- Can users do something they couldn't do before? → **MINOR** -+- Did something that worked break? → **MAJOR** (if breaking) or **PATCH** (if fixing) -+- Did something that worked get better? → **PATCH** -+ - **MAJOR** (1.0.0 → 2.0.0): - -# Step 2: Ask user what to do -This file has updates available. What would you like to do? - -1. Apply update (take upstream version) -2. Keep your version (skip this update) -3. View full diff again -4. Try to merge changes (AI-assisted) - -Your choice (1-4): 1 - -Applying update... -[x] Updated .claude/commands/release.md -``` - -**WRONG Implementation (what happened in the test):** - -```bash -📄 File 1/3: .claude/commands/release.md - -# NO DIFF SHOWN - WRONG! -# Just blindly overwrites: -Bash(cat .tmp/claudesidian-upgrade/.claude/commands/release.md > .claude/commands/release.md) - -# No user confirmation - WRONG! -# Could lose customizations! -``` - -## Example Session - -``` -> /upgrade - -🔍 Checking for updates... -📦 Current version: 0.8.2 -🆕 Latest version: 0.8.3 - -💾 Creating backup to .backup/upgrade-2025-09-13-142030/ - -📋 Creating upgrade checklist... -Checking system files only (not your personal notes)... -Found 15 system files with updates available - -Created .upgrade-checklist.md to track updates: - -## Commands (8 files) -[ ] .claude/commands/init-bootstrap.md -[ ] .claude/commands/release.md -[ ] .claude/commands/thinking-partner.md -[ ] .claude/commands/upgrade.md -[ ] .claude/commands/daily-review.md -[ ] .claude/commands/inbox-processor.md -[ ] .claude/commands/research-assistant.md -[ ] .claude/commands/weekly-synthesis.md - -## Settings (1 file) -[ ] .claude/settings.json - -## Core Files (3 files) -[ ] package.json -[ ] CHANGELOG.md -[ ] README.md - -## Scripts (3 files) -[ ] .scripts/vault-stats.sh -[ ] .scripts/firecrawl-scrape.sh -[ ] .scripts/setup-mcp.sh - -Starting file-by-file review... - -📄 File 1/15: .claude/commands/init-bootstrap.md - Status: No local changes detected - Action: Direct update from upstream - [x] Updated - -📄 File 2/15: .claude/commands/release.md - Status: No local changes detected - Action: Direct update from upstream - [x] Updated - -📄 File 3/15: .claude/settings.json - Status: Has local changes (your custom hooks) - Showing diff... - Action: Merge needed - preserving your hooks, adding new features - [x] Merged - -[... continues through all files ...] - -🔍 **Verification Check** -Re-checking for any missed system files... - -✅ All system files successfully updated! -No claudesidian system files remain out of sync with upstream. - -🎉 Upgrade complete! -📈 claudesidian 0.8.2 → 0.8.3 - -✅ Updated: 14 files -⏭️ Skipped: 1 file (CLAUDE.md - user customization) -✅ Verified: All system files match upstream - -Summary of changes: -- Fixed init-bootstrap vault selection -- Improved SessionStart hooks -- Enhanced user identification prompts -- Updated all commands to latest versions -``` - -### Example: Verification Catches Missed Files - -``` -🔍 **Verification Check** -Re-checking for any missed system files... - -⚠️ Warning: 2 files appear to be missed (still marked pending in checklist): -- .claude/commands/thinking-partner.md [ ] -- .scripts/vault-stats.sh [ ] - -These files haven't been processed yet. - -Would you like to complete the upgrade for these files? (y/n) > y - -📄 Completing upgrade for missed files... - -📄 File: .claude/commands/thinking-partner.md - Status: Reviewing diff... - Action: Direct update from upstream - [x] Updated - -📄 File: .scripts/vault-stats.sh - Status: Reviewing diff... - Action: Direct update from upstream - [x] Updated - -✅ Verification complete - all system files now match upstream! -``` - -### Example: Verification with User Customizations - -``` -🔍 **Verification Check** -Re-checking for any missed system files... - -Files still differing from upstream: -- .claude/commands/thinking-partner.md [x] ← Updated but user customized -- package.json [x] ← Merged, kept user's custom scripts -- .claude/commands/daily-review.md [ ] ← Not processed yet! - -✅ 2 files intentionally preserve user customizations -⚠️ 1 file appears to be missed (still pending) - -Would you like to: -1. Review the missed file (.claude/commands/daily-review.md) -2. Skip verification (keep current state) -3. See details about customized files - -Choice (1/2/3) > 1 - -📄 File: .claude/commands/daily-review.md - Status: Reviewing diff... - Action: Direct update from upstream - [x] Updated - -✅ Verification complete! -- All required updates applied -- User customizations preserved where intended -``` - -This intelligent upgrade system leverages Claude's semantic understanding to -provide the smoothest possible upgrade experience while ensuring no user -customizations are lost. diff --git a/.claude/commands/weekly-synthesis.md b/.claude/commands/weekly-synthesis.md index d869357..f57bcbd 100644 --- a/.claude/commands/weekly-synthesis.md +++ b/.claude/commands/weekly-synthesis.md @@ -1,4 +1,6 @@ # Weekly Synthesis +risk: medium +writes: 00_Inbox/ weekly notes Create a comprehensive synthesis of the week's work and thinking. diff --git a/.claude/memory/instructions/git.md b/.claude/memory/instructions/git.md deleted file mode 100644 index 6742b6c..0000000 --- a/.claude/memory/instructions/git.md +++ /dev/null @@ -1,23 +0,0 @@ -# Git Workflow - -## Session Workflow -```bash -# Always start sessions with -git pull - -# After significant work -git add . && git commit -m "vault backup: $(date)" && git push -``` - -## Commit Format -- Standard: `vault backup: YYYY-MM-DD HH:MM:SS` -- Feature: `feat: description` -- Fix: `fix: description` -- Docs: `docs: description` - -## Best Practices -- Pull before starting work -- Commit frequently (after significant changes) -- Push at end of session -- Use descriptive messages for non-backup commits -- Never force push without approval diff --git a/.claude/memory/instructions/linking.md b/.claude/memory/instructions/linking.md deleted file mode 100644 index e1b4cd4..0000000 --- a/.claude/memory/instructions/linking.md +++ /dev/null @@ -1,19 +0,0 @@ -# Linking Strategy & Connections - -## Core Principles -- Use `[[wikilinks]]` for all internal connections -- Link liberally - prefer over-linking to under-linking -- Always check and update links after reorganizing files -- Proactively suggest connections when relevant - -## When to Create Links -- User mentions existing topics/notes -- New content relates to existing knowledge -- Concepts connect across PARA categories -- Creating connections aids discovery - -## Link Maintenance -- After moving files, verify all backlinks updated -- Periodically check for broken links -- Suggest creating MOCs (Maps of Content) for clustered topics -- Identify orphaned notes (no connections) diff --git a/.claude/memory/instructions/organization.md b/.claude/memory/instructions/organization.md deleted file mode 100644 index ecff068..0000000 --- a/.claude/memory/instructions/organization.md +++ /dev/null @@ -1,27 +0,0 @@ -# PARA Organization System - -## Folder Structure -``` -00_Inbox/ → Temporary capture, process weekly -01_Projects/ → Time-bound work with deadlines -02_Areas/ → Ongoing responsibilities -03_Resources/ → Reference materials -04_Archive/ → Completed items -05_Attachments/ → Media files -06_Metadata/ → Docs & templates -``` - -## Quick Decision Tree -- Has deadline? → 01_Projects/ -- Ongoing responsibility? → 02_Areas/ -- Reference material? → 03_Resources/ -- Unsure? → 00_Inbox/ - -## Organization Principles -- Inbox is temporary - process weekly -- One idea per note (atomic notes) -- Flat structure over deep nesting (max 4 levels for new notes) -- Use links not folders for relationships - -## Clipper Boundary -- `04_Archive/Inbox-Clippings/**` permanently uses the web clipper schema (`date`/`page-title`/`url`). Never migrate. diff --git a/.claude/memory/instructions/safety.md b/.claude/memory/instructions/safety.md deleted file mode 100644 index 6f1b36b..0000000 --- a/.claude/memory/instructions/safety.md +++ /dev/null @@ -1,17 +0,0 @@ -# Data Safety & File Operations - -## Core Principles -- **Never delete without approval** - Always ask before removing content -- **Preserve everything when merging** - Only remove verified exact duplicates -- **Verify before moving** - Check destination exists, update all `[[wikilinks]]` after -- **Read before writing** - Use Read tool before editing any file - -## File Operations -- Use `mv` not `cp` (avoid duplicates) -- Never move numbered folders (00-06) from vault root -- Get approval for bulk operations affecting 5+ files - -When proposing bulk operations: -- Explain what's changing and why -- List files affected -- Provide rollback approach diff --git a/.claude/memory/instructions/standards.md b/.claude/memory/instructions/standards.md deleted file mode 100644 index a27b88d..0000000 --- a/.claude/memory/instructions/standards.md +++ /dev/null @@ -1,24 +0,0 @@ -# Note Standards & Frontmatter - -## Required Frontmatter -```yaml ---- -created: YYYY-MM-DD -modified: YYYY-MM-DD -tags: [specific, tags] -status: draft|active|complete|archived ---- -``` - -## File Naming -- **Daily notes**: YYYY-MM-DD.md (e.g., 2026-01-08.md) -- **Project notes**: Clear, descriptive names with context -- **Resource notes**: Topic-based naming -- **Avoid**: Special characters except hyphens and underscores - -## Note Types -- **Atomic Notes**: Single concept, highly linkable -- **MOCs**: Topic hubs with curated links -- **Daily Notes**: Journal entries, meeting notes, quick captures -- **Project Notes**: Actionable items with clear outcomes -- **Evergreen Notes**: Permanent, well-developed ideas diff --git a/.claude/project-instructions.md b/.claude/project-instructions.md deleted file mode 100644 index dcb27bf..0000000 --- a/.claude/project-instructions.md +++ /dev/null @@ -1,129 +0,0 @@ -# Obsidian PKM Assistant - -> Core principles only. See `06_Metadata/WORKFLOWS.md` for detailed procedures. - ---- - -## Safety First - -### Data Integrity -- **Never delete without approval** - Always ask before removing content -- **Preserve everything when merging** - Only remove verified exact duplicates -- **Verify before moving** - Check destination exists, update all `[[wikilinks]]` after -- **Read before writing** - Use Read tool before editing any file - -### File Operations -- Use `mv` not `cp` (avoid duplicates) -- Never move numbered folders (00-06) from vault root -- Get approval for bulk operations affecting 5+ files - ---- - -## PARA Structure - -``` -00_Inbox/ → Temporary capture, process weekly -01_Projects/ → Time-bound work with deadlines -02_Areas/ → Ongoing responsibilities -03_Resources/ → Reference materials -04_Archive/ → Completed items -05_Attachments/ → Media files -06_Metadata/ → Docs & templates -``` - -**Quick Decision**: Deadline? → Projects | Ongoing? → Areas | Reference? → Resources | Unsure? → Inbox - ---- - -## Git Essentials - -```bash -# Always start sessions with -git pull - -# After significant work -git add . && git commit -m "vault backup: $(date)" && git push -``` - -Commit format: `vault backup: YYYY-MM-DD HH:MM:SS` - ---- - -## Memory Integration - -Use Memvid MCP for persistent context across sessions: - -### Core Workflow -1. **Query first**: Always search memory at task start: `memvid_search` -2. **Work**: Complete task using retrieved context -3. **Write back**: Save decisions: `memvid_add_text` + `memvid_commit` - -### What to Store -- **DO**: User preferences, decisions, constraints, patterns, project context -- **DON'T**: Secrets, credentials, errors, logs, temporary data - -### Memory File Location -- Default: `.claude/memory/memvid.mv2` -- Project-specific: `.claude/memory/[project-name].mv2` - -### Tagging Strategy -Use consistent tags for retrieval: -- `type:preference` - User preferences and settings -- `type:decision` - Architectural and design decisions -- `type:constraint` - Project limitations and requirements -- `type:pattern` - Code patterns and conventions -- `project:[name]` - Project-specific context -- `area:[name]` - Area-specific information - -### Quick Reference -``` -Search: memvid_search(query, top_k=5) -Add: memvid_add_text(content, tags={"type": "decision"}) -Commit: memvid_commit() -List: memvid_list_contents(limit=20) -Info: memvid_info() -``` - -See `06_Metadata/WORKFLOWS.md#memvid-workflows` for detailed procedures. - ---- - -## Note Standards - -### Frontmatter -```yaml ---- -created: YYYY-MM-DD -modified: YYYY-MM-DD -tags: [specific, tags] -status: draft|active|complete|archived ---- -``` - -### Linking -- Use `[[wikilinks]]` for internal connections -- Link liberally, prefer over-linking -- Check and update links after reorganizing - -### Organization -- Inbox is temporary - process weekly -- One idea per note (atomic notes) -- Flat structure over deep nesting (max 4 levels for new notes) -- Use links not folders for relationships - ---- - -## Work Approach - -**Simple tasks** → Execute directly -**Complex changes** → Propose plan first (affected files, steps, rollback) -**Uncertain info** → Mark `[待确认]` and ask - -For bulk operations, provide: -- What's changing and why -- Files affected -- Rollback approach - ---- - -**Detailed workflows, templates, troubleshooting**: → `06_Metadata/WORKFLOWS.md` diff --git a/.claude/settings.json b/.claude/settings.json index fe2ec4d..3d33fb5 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -3,42 +3,19 @@ "permissions": { "allow": [ "Bash(npm run | grep daily-note)", - "Edit(06_Metadata/Templates/Daily Note Template.md)", - "Edit(06_Metadata/Reference/DAILY_NOTE_GUIDE.md)", - "Edit(.obsidian/plugins/quickadd/data.json)", - "Edit(04_Archive/Projects/Airport/Chengdu/Office Test Env.md)", "Bash(wc:*)", "Bash(find:*)", "Bash(git add:*)" ], - "deny": [], - "ask": [] - }, - "hooks": { - "SessionStart": [ - { - "hooks": [ - { - "type": "command", - "command": "[ -f FIRST_RUN ] && echo '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"\\n\\n# 🚀 Welcome to Claudesidian!\\n\\n**This appears to be your first time using this vault.**\\n\\n## Quick Start\\n\\nRun the setup wizard:\\n\\n⬇\\n/init-bootstrap\\n⬆\\n\\n## What this will do:\\n\\n✅ Set up your personalized configuration\\n✅ Disconnect from the original repository\\n✅ Help you import any existing Obsidian vault\\n✅ Configure your preferred workflow\\n✅ Create your PARA folder structure\\n\\nThe setup wizard will guide you through everything!\\n\\n\"}}' || true" - }, - { - "type": "command", - "command": "npm run check-updates --silent 2>/dev/null || true" - } - ] - } + "deny": [ + "Edit(.obsidian/plugins/*/data.json)", + "Edit(04_Archive/**)", + "Bash(git push:*)", + "Bash(git add .:*)" ], - "UserPromptSubmit": [ - { - "hooks": [ - { - "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-discovery.sh", - "timeout": 5000, - "type": "command" - } - ] - } + "ask": [ + "Edit(.obsidian/**)" ] - } + }, + "hooks": {} } diff --git a/.obsidian/CLAUDE.md b/.obsidian/CLAUDE.md deleted file mode 100644 index 51c5bb7..0000000 --- a/.obsidian/CLAUDE.md +++ /dev/null @@ -1,11 +0,0 @@ - -# Recent Activity - - - -### Feb 25, 2026 - -| ID | Time | T | Title | Read | -|----|------|---|-------|------| -| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 | - \ No newline at end of file diff --git a/.obsidian/plugins/claudian/CLAUDE.md b/.obsidian/plugins/claudian/CLAUDE.md deleted file mode 100644 index adfdcb1..0000000 --- a/.obsidian/plugins/claudian/CLAUDE.md +++ /dev/null @@ -1,7 +0,0 @@ - -# Recent Activity - - - -*No recent activity* - \ No newline at end of file diff --git a/.obsidian/plugins/obsidian-excalidraw-plugin/CLAUDE.md b/.obsidian/plugins/obsidian-excalidraw-plugin/CLAUDE.md deleted file mode 100644 index adfdcb1..0000000 --- a/.obsidian/plugins/obsidian-excalidraw-plugin/CLAUDE.md +++ /dev/null @@ -1,7 +0,0 @@ - -# Recent Activity - - - -*No recent activity* - \ No newline at end of file diff --git a/00_Inbox/CLAUDE.md b/00_Inbox/CLAUDE.md deleted file mode 100644 index 83efc5a..0000000 --- a/00_Inbox/CLAUDE.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -created: 2026-01-26 ---- - -# Recent Activity - - - -### Feb 25, 2026 - -| ID | Time | T | Title | Read | -|----|------|---|-------|------| -| #1213 | 10:29 AM | 🔵 | Vault underwent formal review and improvement planning in February 2026 | ~630 | - \ No newline at end of file diff --git a/01_Projects/Home-Automation/CLAUDE.md b/01_Projects/Home-Automation/CLAUDE.md deleted file mode 100644 index c450bdf..0000000 --- a/01_Projects/Home-Automation/CLAUDE.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -created: 2026-01-26 ---- - -# Recent Activity - - - -### Feb 25, 2026 - -| ID | Time | T | Title | Read | -|----|------|---|-------|------| -| #1214 | 10:29 AM | 🔵 | Inconsistent frontmatter usage and exposed credentials in vault | ~384 | -| #1206 | 10:25 AM | 🔵 | Personal vault structure and content patterns | ~372 | - \ No newline at end of file diff --git a/01_Projects/Infrastructure/Services/CLAUDE.md b/01_Projects/Infrastructure/Services/CLAUDE.md deleted file mode 100644 index a4da2f4..0000000 --- a/01_Projects/Infrastructure/Services/CLAUDE.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -created: 2026-01-26 ---- - -# Recent Activity - - - -### Feb 25, 2026 - -| ID | Time | T | Title | Read | -|----|------|---|-------|------| -| #1214 | 10:29 AM | 🔵 | Inconsistent frontmatter usage and exposed credentials in vault | ~384 | - \ No newline at end of file diff --git a/02_Areas/Blog/CLAUDE.md b/02_Areas/Blog/CLAUDE.md deleted file mode 100644 index 0f65d9b..0000000 --- a/02_Areas/Blog/CLAUDE.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -created: 2026-02-25 ---- - -# Recent Activity - - - -### Feb 25, 2026 - -| ID | Time | T | Title | Read | -|----|------|---|-------|------| -| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 | -| #1214 | " | 🔵 | Inconsistent frontmatter usage and exposed credentials in vault | ~384 | - \ No newline at end of file diff --git a/02_Areas/Finance/CLAUDE.md b/02_Areas/Finance/CLAUDE.md deleted file mode 100644 index c551034..0000000 --- a/02_Areas/Finance/CLAUDE.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -created: 2026-02-25 ---- - -# Recent Activity - - - -### Feb 25, 2026 - -| ID | Time | T | Title | Read | -|----|------|---|-------|------| -| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 | -| #1206 | 10:25 AM | 🔵 | Personal vault structure and content patterns | ~372 | - \ No newline at end of file diff --git a/02_Areas/Health/CLAUDE.md b/02_Areas/Health/CLAUDE.md deleted file mode 100644 index cd26140..0000000 --- a/02_Areas/Health/CLAUDE.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -created: 2026-01-26 ---- - -# Recent Activity - - - -### Feb 25, 2026 - -| ID | Time | T | Title | Read | -|----|------|---|-------|------| -| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 | - \ No newline at end of file diff --git a/02_Areas/House/CLAUDE.md b/02_Areas/House/CLAUDE.md deleted file mode 100644 index cd26140..0000000 --- a/02_Areas/House/CLAUDE.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -created: 2026-01-26 ---- - -# Recent Activity - - - -### Feb 25, 2026 - -| ID | Time | T | Title | Read | -|----|------|---|-------|------| -| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 | - \ No newline at end of file diff --git a/02_Areas/Productivity/CLAUDE.md b/02_Areas/Productivity/CLAUDE.md deleted file mode 100644 index cd26140..0000000 --- a/02_Areas/Productivity/CLAUDE.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -created: 2026-01-26 ---- - -# Recent Activity - - - -### Feb 25, 2026 - -| ID | Time | T | Title | Read | -|----|------|---|-------|------| -| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 | - \ No newline at end of file diff --git a/03_Resources/Cooking/CLAUDE.md b/03_Resources/Cooking/CLAUDE.md deleted file mode 100644 index df71b13..0000000 --- a/03_Resources/Cooking/CLAUDE.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -created: 2026-01-26 ---- - -# Recent Activity - - - -### Feb 25, 2026 - -| ID | Time | T | Title | Read | -|----|------|---|-------|------| -| #1206 | 10:25 AM | 🔵 | Personal vault structure and content patterns | ~372 | - \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index c502994..ff4b805 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,176 +1,105 @@ -# Agent Coding Guidelines +# AGENTS.md — Vault Operations Manual -**Purpose**: Code style and workflow for agentic coding assistants in this vault -**Last Updated**: 2026-01-06 +**Purpose**: Single source of truth for AI agents operating in this Obsidian vault. +**Last Updated**: 2026-09-26 --- -## Build & Lint Commands +## Directory Structure (PARA) + +``` +00_Inbox/ Temporary capture, process weekly +01_Projects/ Time-bound work with deadlines +02_Areas/ Ongoing responsibilities (Health, Finance, etc.) +03_Resources/ Reference materials and knowledge base +04_Archive/ Completed items and clippings +05_Attachments/ Media files (images, PDFs) +06_Metadata/ Templates and reference docs (8 files) + +.claude/ Agent config, commands, hooks +.config/ ESLint, Prettier, TypeScript config +.scripts/ Utility scripts (JS/Python) +.github/ CI workflows +.obsidian/ Obsidian app config (do not rewrite) +``` + +## Permission Table + +| Path | Rule | +|---|---| +| `00_Inbox/` | Free to create and edit | +| `01_Projects/` | Edit on request | +| `03_Resources/` | Edit on request | +| `02_Areas/` | **Ask before editing** | +| `04_Archive/` | **Never rewrite** — read-only historical record | +| `06_Metadata/Templates/` | **Never rewrite** — wired to Obsidian plugins | +| `.obsidian/` | **Never rewrite** — app config | +| `.obsidian/plugins/*/data.json` | **Hard deny** — may contain secrets | +| Credential files (see .gitignore) | **Never read or write** | + +## Frontmatter Conventions + +Active notes (00–03) use these core keys: +- `created` (required) — ISO date `YYYY-MM-DD` +- `status` — one of: `draft`, `active`, `done`, `archived` +- `tags`, `type`, `updated` — optional + +Content keys (never delete): `title`, `description`, `source`, `date`, `author`, `published`, `aliases` + +**Clipper boundary**: `04_Archive/Inbox-Clippings/**` permanently uses the web clipper schema (`date`/`page-title`/`url`). Never migrate. + +## Safety Rules + +1. **Read before writing** — always read a file before editing it +2. **Never delete without approval** — ask before removing content +3. **Preserve everything when merging** — only remove verified exact duplicates +4. **Verify before moving** — check destination exists, update all `[[wikilinks]]` after move +5. **Never move numbered folders** (00–06) from vault root +6. **Get approval for bulk operations** affecting 5+ files +7. **Never commit secrets** — run `.scripts/verify-vault.mjs` before pushing + +## Git Workflow ```bash -# Lint & format (auto-fixes issues) -pnpm lint # Run eslint + prettier with auto-fix - -# Check only (no fixes) -pnpm lint:check # Verify code style compliance - -# Format only -pnpm format # Prettier format all files -pnpm format:check # Check formatting without changes - -# Run scripts directly (no test framework configured) -node .scripts/update-attachment-links.js -GEMINI_API_KEY=xxx node .claude/mcp-servers/gemini-vision.mjs -python3 .scripts/rename-chinese-to-english.py +pnpm lint # Auto-fix before committing +pnpm lint:check # Verify without changes +node .scripts/verify-vault.mjs # Secret scanner (CI runs this too) ``` +- Commit after each work session with descriptive messages +- Pull before starting work +- Never force-push to main + +## Organization Principles + +- Inbox is temporary — process weekly +- One idea per note (atomic notes) +- Flat structure over deep nesting (max 4 levels for new notes) +- Use links not folders for relationships +- Link liberally, prefer over-linking + +## Work Approach + +- **Simple tasks** — execute directly +- **Complex changes** — propose plan first (affected files, steps, rollback) + --- -## Code Style Guidelines +## Scripts — Code Style -### TypeScript/JavaScript +### JavaScript/TypeScript -#### Imports +- Single quotes, semicolons, `node:` prefix for built-in imports +- `camelCase` functions/variables, `UPPER_SNAKE_CASE` constants, `PascalCase` classes +- Prefix unused params with `_` +- Handle errors in async functions, check env vars early -```javascript -import type { Server } from '@modelcontextprotocol/sdk/server/index.js' -import { readFile } from 'node:fs/promises' -import path from 'node:path' -import fs from 'node:fs' -``` +### Python -#### Formatting +- `snake_case` functions/variables, `UPPER_SNAKE_CASE` constants +- Type hints on function signatures -```javascript -// Single quotes for strings, use semicolons -const value = 'string' -const obj = { name, value } -const msg = `Hello ${name}` -``` - -#### Error Handling - -```javascript -// Always handle errors in async functions -try { - await fs.access(filePath) -} catch { - throw new Error(`File not found: ${filePath}`) -} - -// Check environment variables early -if (!process.env.API_KEY) { - console.error('❌ API_KEY environment variable is required') - process.exit(1) -} -``` - -#### Naming Conventions - -```javascript -function analyzeImage(args) {} // camelCase -const MAX_ATTEMPTS = 60 // UPPER_SNAKE_CASE -const imagePath = 'path/to/file.png' // camelCase -class ImageAnalyzer {} // PascalCase -function process(data, _unused) {} // Prefix unused with _ -``` - -### Python Scripts - -```python -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- - -from pathlib import Path -from typing import List, Dict - -path = Path('05_Attachments/Organized') - -def process_files(files: List[str]) -> Dict[str, str]: - """Process list of files.""" - return {f: f for f in files} - -file_path = 'path/to/file.md' # snake_case -MAX_RETRIES = 3 # UPPER_SNAKE_CASE -``` - ---- - -## File Organization - -```bash -.claude/mcp-servers/ # MCP server implementations -.scripts/ # Utility scripts (JS/Python) -.config/ # Config files (eslint, prettier, tsconfig) -``` - -### Script Structure - -```javascript -#!/usr/bin/env node - -import fs from 'node:fs' - -const args = process.argv.slice(2) -if (args.length !== 1) { - console.log('Usage: node script.js ') - process.exit(1) -} - -async function main() { - // Implementation -} - -main().catch(console.error) -``` - ---- - -## Common Patterns - -### File Walking - -```javascript -function walkDir(dir, callback) { - fs.readdirSync(dir).forEach((f) => { - const dirPath = path.join(dir, f) - const isDirectory = fs.statSync(dirPath).isDirectory() - if (isDirectory && !f.includes('node_modules') && !f.includes('.git')) { - walkDir(dirPath, callback) - } else if (!isDirectory) { - callback(dirPath) - } - }) -} -``` - -### Processing Files - -```javascript -walkDir('.', (filepath) => { - if (filepath.endsWith('.md')) { - let content = fs.readFileSync(filepath, 'utf8') - // Process content - if (content !== originalContent) { - fs.writeFileSync(filepath, content, 'utf8') - } - } -}) -``` - ---- - -## Before Making Changes - -1. Read existing files to understand patterns -2. Check package.json for available scripts/dependencies -3. Run lint before committing: `pnpm lint` -4. Test changes by running scripts directly -5. Commit with descriptive message after verification - ---- - -**Resources**: +### Config - ESLint: `.config/eslint.config.js` - Prettier: `.config/.prettierrc.js` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5c11c21 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +See AGENTS.md diff --git a/README.md b/README.md index d9ff1e8..e0776a8 100644 --- a/README.md +++ b/README.md @@ -1,477 +1,34 @@ -# Claudesidian: Claude Code + Obsidian Starter Kit +# My Obsidian Vault -Turn your Obsidian vault into an AI-powered second brain using Claude Code. +Personal knowledge base using the PARA method, version-controlled with Git. -## What is this? +## Structure -This is a pre-configured Obsidian vault structure designed to work seamlessly -with Claude Code, enabling you to: +``` +00_Inbox/ Capture → process weekly +01_Projects/ Time-bound work +02_Areas/ Ongoing responsibilities +03_Resources/ Reference materials +04_Archive/ Completed items & clippings +05_Attachments/ Media files +06_Metadata/ Templates & reference docs +``` -- Use AI as a thinking partner, not just a writing assistant -- Organize knowledge using the PARA method -- Maintain version control with Git -- Access your vault from anywhere (including mobile) +## Entry Points -## Authoritative Entry Points +- `AGENTS.md` — operations manual for AI agents (permission table, safety rules, code style) +- `06_Metadata/Reference/PARA_METHOD.md` — PARA methodology reference +- `06_Metadata/Reference/GIT_WORKFLOW.md` — git workflow guide -- `README.md` = Project entry point and navigation -- `06_Metadata/QUICK_REFERENCE.md` = One-page quick reference -- `06_Metadata/WORKFLOWS.md` = Detailed workflows and rules - -## Quick Start - -### 1. Get the Starter Kit - -**Option A: Clone with Git** +## Scripts ```bash -# Clone with your preferred folder name (replace 'my-vault' with any name you like) -git clone https://github.com/heyitsnoah/claudesidian.git my-vault -cd my-vault - -# Examples: -# git clone https://github.com/heyitsnoah/claudesidian.git obsidian-notes -# git clone https://github.com/heyitsnoah/claudesidian.git knowledge-base -# git clone https://github.com/heyitsnoah/claudesidian.git second-brain +pnpm lint # Lint + format (auto-fix) +pnpm lint:check # Check only +pnpm format # Prettier format +pnpm vault:stats # Vault statistics ``` -**Option B: Download ZIP (no Git required)** +## CI -1. Click "Code" → "Download ZIP" on GitHub -2. Extract to your desired location -3. Open the folder in Claude Code - -### 2. Run the Setup Wizard - -```bash -# Start Claude Code in the directory -claude - -# Run the interactive setup wizard (in Claude Code) -/init-bootstrap -``` - -This will: - -- Install dependencies automatically -- Disconnect from the original claudesidian repository -- **Intelligently analyze** your existing vault structure and patterns -- **Import your existing Obsidian vault** safely to OLD_VAULT/ (if you have one) -- **Research your public work** for personalized context (with your permission) -- Ask you about your workflow preferences -- Create a personalized CLAUDE.md configuration -- Set up your folder structure -- Optionally configure Gemini Vision for image/video analysis -- Optionally configure Firecrawl for web research -- Initialize Git for version control - -### 3. Open in Obsidian (Optional but Recommended) - -- Download [Obsidian](https://obsidian.md) -- Open vault from the claudesidian folder -- This gives you a visual interface alongside Claude Code - -### 4. Your First Session - -Tell Claude Code: - -``` -I'm starting a new project about [topic]. -I'm in thinking mode, not writing mode. -Please search my vault for any relevant existing notes, -then help me explore this topic by asking questions. -``` - -Or use one of the pre-configured commands (in Claude Code): - -``` -/thinking-partner # For collaborative exploration -/daily-review # For end-of-day reflection -/research-assistant # For deep dives into topics -``` - -## Folder Structure - -``` -claudesidian/ -├── 00_Inbox/ # Temporary capture point for new ideas -├── 01_Projects/ # Active, time-bound initiatives -├── 02_Areas/ # Ongoing responsibilities -├── 03_Resources/ # Reference materials and knowledge base -├── 04_Archive/ # Completed projects and inactive items -├── 05_Attachments/ # Images, PDFs, and other files -├── 06_Metadata/ # Vault configuration and templates -│ ├── Reference/ # Documentation and guides -│ └── Templates/ # Reusable note templates -└── .scripts/ # Helper scripts for automation -``` - -## Key Concepts - -### Thinking Mode vs Writing Mode - -**Thinking Mode** (Research & Exploration): - -- Claude asks questions to understand your goals -- Searches existing notes for relevant content -- Helps make connections between ideas -- Maintains a log of insights and progress - -**Writing Mode** (Content Creation): - -- Generates drafts based on your research -- Helps structure and edit content -- Creates final deliverables - -### The PARA Method - -**Projects**: Have a deadline and specific outcome - -- Example: "Q4 2025 Marketing Strategy" -- Create a folder in `01_Projects/` - -**Areas**: Ongoing without an end date - -- Example: "Health", "Finances", "Team Management" -- Lives in `02_Areas/` - -**Resources**: Topics of ongoing interest - -- Example: "AI Research", "Writing Tips" -- Store in `03_Resources/` - -**Archive**: Inactive items - -- Completed projects with their outputs -- Old notes no longer relevant - -## Claude Code Commands - -Pre-configured AI assistants ready to use: - -- `thinking-partner` - Explore ideas through questions -- `inbox-processor` - Organize your captures -- `research-assistant` - Deep dive into topics -- `daily-review` - End of day reflection -- `weekly-synthesis` - Find patterns in your week -- `create-command` - Build new custom commands -- `de-ai-ify` - Remove AI writing patterns from text -- `upgrade` - Update to the latest claudesidian version -- `init-bootstrap` - Re-run the setup wizard -- `install-claudesidian-command` - Install shell command to launch vault from - anywhere - -Run with: `/[command-name]` in Claude Code - -### Staying Updated with `/upgrade` - -Claudesidian automatically checks for updates when you start Claude Code and -will remind you to run `/upgrade` when new features are available. - -The upgrade command intelligently merges new features while preserving your -customizations: - -```bash -# Preview what would be updated (recommended first) -/upgrade check - -# Run the interactive upgrade -/upgrade - -# Skip confirmations for safe updates (advanced) -/upgrade force -``` - -**What the upgrade does:** - -- Creates a timestamped backup before making any changes -- Shows you diffs for each file before updating -- Preserves your personal notes and customizations -- Only updates system files (commands, agents, scripts) -- Never touches your content folders (00_Inbox, 01_Projects, etc.) -- Provides rollback capability if needed - -**Safety features:** - -- All your personal content is protected -- Complete backup created in `.backup/upgrade-[timestamp]/` -- File-by-file review and confirmation -- Progress tracked in `.upgrade-checklist.md` -- Can be stopped and resumed at any time - -## Vision & Document Analysis (Optional) - -With [Google Gemini](https://ai.google.dev/) MCP configured, Claude Code can -process your attachments directly without having to describe them. This means: - -- **Direct image analysis**: Claude sees the actual image, not your description -- **PDF text extraction**: Full document text without copy-pasting -- **Bulk processing**: Analyze multiple screenshots or documents at once -- **Smart organization**: Auto-generate filenames based on image content -- **Comparison tasks**: Compare before/after screenshots, designs, etc. - -**Why this matters**: Instead of describing "a screenshot showing an error -message", Claude Code directly sees and reads the error. Perfect for debugging -UI issues, analyzing charts, or processing scanned documents. - -**Getting a Gemini API key:** - -1. Visit [Google AI Studio](https://aistudio.google.com) -2. Sign in with your Google account -3. Click "Get API key" in the left sidebar -4. Create a new API key (it's free!) -5. Set it in your environment: `export GEMINI_API_KEY="your-key-here"` - -See `.claude/mcp-servers/README.md` for full setup instructions - -## Web Research (Optional) - -With [Firecrawl](https://www.firecrawl.dev/) configured, our helper scripts -fetch and save full web content directly to your vault. This means: - -- **Full text capture**: Scripts pipe complete article text to files, not - summaries -- **Context preservation**: Claude doesn't need to hold web content in memory -- **Batch processing**: Save multiple articles at once with `firecrawl-batch.sh` -- **Clean markdown**: Web pages converted to readable, searchable markdown -- **Permanent archive**: Your research stays in your vault forever - -**Why this matters**: Instead of Claude reading a webpage and summarizing it -(losing detail), the scripts save the FULL text. Claude can then search and -analyze thousands of saved articles without hitting context limits. Perfect for -research projects, documentation archives, or building a knowledge base. - -**Example workflow:** - -```bash -# Save a single article -pnpm firecrawl:scrape -- "https://example.com/article" "03_Resources/Articles" - -# Batch save multiple URLs -pnpm firecrawl:batch -- urls.txt "03_Resources/Research" -``` - -**Getting a Firecrawl API key:** - -1. Visit [Firecrawl](https://www.firecrawl.dev) and sign up -2. Get 300 free credits to start (open-source, can self-host) -3. Go to your dashboard to find your API key -4. Copy the key (format: `fc-xxxxx...`) -5. Set it in your environment: `export FIRECRAWL_API_KEY="fc-your-key-here"` - -## Helper Scripts - -Run these with `pnpm`: - -- `attachments:list` - Show unprocessed attachments -- `attachments:organized` - Count organized files -- `attachments:sizes` - Find large files -- `attachments:orphans` - Find unreferenced attachments -- `vault:stats` - Show vault statistics - -If you do not have `pnpm` installed, use `npm run