Onboarding improvements: 15-minute quickstart, fix Windows date & Obsidian path, safe mission insertion, accurate Claude init messaging, unify vault naming, update links

2025-08-08 13:34:28 -07:00
parent 3877057f7c
commit 7af954d003
6 changed files with 90 additions and 49 deletions
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Obsidian + Claude Code PKM Starter Kit 🚀

-A complete personal knowledge management system that combines Obsidian's powerful note-taking with Claude Code's AI assistance. Go from zero to a fully functional PKM in under 30 minutes.
+A complete personal knowledge management system that combines Obsidian's powerful note-taking with Claude Code's AI assistance. Go from zero to a fully functional PKM in 15 minutes or less.

 ## ✨ Features

@@ -20,23 +20,35 @@ A complete personal knowledge management system that combines Obsidian's powerfu
 - Git installed
 - GitHub account (optional, for mobile sync)

-### Setup (5 minutes)
+### 15-Minute Quickstart
 ```bash
-# Clone this repository
-git clone https://github.com/yourusername/obsidian-claude-pkm.git
+# 1) Install prerequisites (once)
+# - Obsidian: https://obsidian.md/
+# - Git: https://git-scm.com/
+# - Claude Code CLI: https://docs.anthropic.com/en/docs/claude-code
+
+# 2) Clone this repository
+git clone https://github.com/ballred/obsidian-claude-pkm.git
 cd obsidian-claude-pkm

-# Run the setup script
+# 3) Run setup (macOS/Linux)
+chmod +x scripts/setup.sh
 ./scripts/setup.sh

-# Or manually copy the vault template
-cp -r vault-template ~/Documents/MyVault
+# 3b) Windows
+scripts\setup.bat
+```
+
+### Manual Copy (alternative)
+```bash
+# Copy the vault template to your preferred location
+cp -r vault-template ~/Documents/ObsidianPKM
 ```

 ### Open in Obsidian
 1. Launch Obsidian
 2. Click "Open folder as vault"
-3. Select your vault folder
+3. Select your vault folder (e.g., ~/Documents/ObsidianPKM)
 4. Start with today's daily note!

 ## 📖 Documentation
--- a/docs/SETUP_GUIDE.md
+++ b/docs/SETUP_GUIDE.md
@@ -1,6 +1,6 @@
 # Complete Setup Guide

-This guide will walk you through setting up your Obsidian + Claude Code PKM system step by step. Total time: ~30 minutes.
+This guide will walk you through setting up your Obsidian + Claude Code PKM system step by step. Total time: ~15 minutes if prerequisites are installed.

 ## Prerequisites Checklist

@@ -29,7 +29,7 @@ claude --version

 ```bash
 # Option A: If you have git
-git clone https://github.com/yourusername/obsidian-claude-pkm.git
+git clone https://github.com/ballred/obsidian-claude-pkm.git
 cd obsidian-claude-pkm

 # Option B: Download ZIP
@@ -60,14 +60,14 @@ The setup script will:

 ```bash
 # Copy vault template to your preferred location
-cp -r vault-template ~/Documents/MyPKM
+cp -r vault-template ~/Documents/ObsidianPKM

 # The .claude/commands directory is already included in the template
 # Verify commands are present
-ls ~/Documents/MyPKM/.claude/commands/
+ls ~/Documents/ObsidianPKM/.claude/commands/

 # Initialize git
-cd ~/Documents/MyPKM
+cd ~/Documents/ObsidianPKM
 git init
 ```

@@ -103,7 +103,7 @@ When prompted:

 ```bash
 # Navigate to your vault
-cd ~/Documents/MyPKM
+cd ~/Documents/ObsidianPKM

 # Initialize Claude Code
 claude init
@@ -170,7 +170,7 @@ gh repo create my-pkm --private

 # Or create manually on GitHub.com
 # Then add remote:
-git remote add origin https://github.com/yourusername/my-pkm.git
+git remote add origin https://github.com/ballred/my-pkm.git

 # Push to GitHub
 git push -u origin main
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -12,7 +12,7 @@ Common issues and their solutions. If you can't find your issue here, check the

 2. **Check File Permissions**
   ```bash
-   ls -la ~/YourVault
+   ls -la ~/Documents/ObsidianPKM
   # Should show your user as owner
   ```

@@ -38,7 +38,7 @@ Common issues and their solutions. If you can't find your issue here, check the
 **Solutions**:
 1. Check folder exists:
   ```bash
-   cd ~/Documents/YourVault
+   cd ~/Documents/ObsidianPKM
   ls -la
   ```

@@ -371,8 +371,8 @@ git config --global core.autocrlf true
 #### Permission Denied
 ```bash
 # Fix permissions
-chmod -R 755 ~/YourVault
-chown -R $USER:$USER ~/YourVault
+chmod -R 755 ~/Documents/ObsidianPKM
+chown -R $USER:$USER ~/Documents/ObsidianPKM
 ```

 #### Missing Dependencies
@@ -410,14 +410,14 @@ git checkout COMMIT_HASH -- path/to/file.md
 If vault is corrupted:
 ```bash
 # 1. Backup current vault
-cp -r ~/YourVault ~/YourVault.backup
+cp -r ~/Documents/ObsidianPKM ~/Documents/ObsidianPKM.backup

 # 2. Create fresh vault
 cp -r vault-template ~/NewVault

 # 3. Copy your notes
-cp -r ~/YourVault.backup/Daily\ Notes/* ~/NewVault/Daily\ Notes/
-cp -r ~/YourVault.backup/Projects/* ~/NewVault/Projects/
+cp -r ~/Documents/ObsidianPKM.backup/Daily\ Notes/* ~/NewVault/Daily\ Notes/
+cp -r ~/Documents/ObsidianPKM.backup/Projects/* ~/NewVault/Projects/

 # 4. Reinitialize Git
 cd ~/NewVault
@@ -477,7 +477,7 @@ rm -rf node_modules .obsidian/cache
 ### Resources
 - [Obsidian Forum](https://forum.obsidian.md/)
 - [Claude Code Docs](https://docs.anthropic.com/en/docs/claude-code)
- [GitHub Issues](https://github.com/yourusername/obsidian-claude-pkm/issues)
+- [GitHub Issues](https://github.com/ballred/obsidian-claude-pkm/issues)

 ### Debug Information
 When asking for help, provide:
@@ -496,7 +496,7 @@ git status
 git remote -v

 # Vault structure
-ls -la ~/YourVault
+ls -la ~/Documents/ObsidianPKM
 ```

 ### Community Support
--- a/scripts/customize.sh
+++ b/scripts/customize.sh
@@ -67,19 +67,26 @@ customize_mission() {
    read -p "Enter your mission statement: " MISSION
    
    if [ -n "$MISSION" ]; then
-        # Update files with mission
-        for file in "CLAUDE.md" "Templates/Daily Template.md"; do
-            if [ -f "$file" ]; then
-                # Backup original
-                cp "$file" "$file.bak"
-                # Update mission (handling both macOS and Linux)
-                if [[ "$OSTYPE" == "darwin"* ]]; then
-                    sed -i '' "1s/.*/_$MISSION_/" "$file"
-                else
-                    sed -i "1s/.*/_$MISSION_/" "$file"
-                fi
+        # Update mission in CLAUDE.md placeholder
+        if [ -f "CLAUDE.md" ]; then
+            cp "CLAUDE.md" "CLAUDE.md.bak"
+            if [[ "$OSTYPE" == "darwin"* ]]; then
+                sed -i '' "s/\[CUSTOMIZE THIS: Add your personal mission statement or life purpose here\]/$MISSION/" "CLAUDE.md"
+            else
+                sed -i "s/\[CUSTOMIZE THIS: Add your personal mission statement or life purpose here\]/$MISSION/" "CLAUDE.md"
            fi
-        done
+        fi
+
+        # Update mission line in Daily Template placeholder
+        if [ -f "Templates/Daily Template.md" ]; then
+            cp "Templates/Daily Template.md" "Templates/Daily Template.md.bak"
+            if [[ "$OSTYPE" == "darwin"* ]]; then
+                sed -i '' "s/_\[CUSTOMIZE THIS: Add your personal mission statement or daily reminder here\]_/_$MISSION_/" "Templates/Daily Template.md"
+            else
+                sed -i "s/_\[CUSTOMIZE THIS: Add your personal mission statement or daily reminder here\]_/_$MISSION_/" "Templates/Daily Template.md"
+            fi
+        fi
+
        echo -e "${GREEN}✓ Mission statement updated${NC}"
    fi
    
--- a/scripts/setup.bat
+++ b/scripts/setup.bat
@@ -185,11 +185,8 @@ echo.
 echo What's your main focus right now?
 set /p FOCUS="Current focus: "

-REM Create first daily note
-for /f "tokens=1-3 delims=/ " %%a in ('date /t') do (
-    set TODAY=%%c-%%a-%%b
-)
-set TODAY=%TODAY: =%
+REM Create first daily note (locale-agnostic date via PowerShell)
+for /f %%I in ('powershell -NoProfile -Command "Get-Date -Format yyyy-MM-dd"') do set TODAY=%%I
 set DAILY_NOTE=%VAULT_PATH%\Daily Notes\%TODAY%.md

 if not exist "%DAILY_NOTE%" (
@@ -198,6 +195,11 @@ if not exist "%DAILY_NOTE%" (
    echo [OK] First daily note created: %TODAY%.md
 )

+REM Inject focus into Today's Priority if provided
+if not "%FOCUS%"=="" (
+    powershell -NoProfile -Command "(Get-Content -Raw '%DAILY_NOTE%') -replace '\\*\\*Today''s Priority:\\*\\*','**Today''s Priority:** %FOCUS%' | Set-Content -Encoding UTF8 '%DAILY_NOTE%'"
+)
+
 echo.

 REM Step 8: Final Setup
@@ -235,12 +237,17 @@ echo Read the documentation in docs\ for detailed guidance
 echo.

 REM Offer to open Obsidian
-if exist "%LOCALAPPDATA%\Obsidian\Obsidian.exe" (
-    set /p OPEN_OBSIDIAN="Open Obsidian now? (y/n): "
-    if /i "!OPEN_OBSIDIAN!"=="y" (
+set /p OPEN_OBSIDIAN="Open Obsidian now? (y/n): "
+if /i "!OPEN_OBSIDIAN!"=="y" (
+    REM Try common install locations, then PATH
+    if exist "%LOCALAPPDATA%\Programs\Obsidian\Obsidian.exe" (
+        start "" "%LOCALAPPDATA%\Programs\Obsidian\Obsidian.exe"
+    ) else if exist "%LOCALAPPDATA%\Obsidian\Obsidian.exe" (
        start "" "%LOCALAPPDATA%\Obsidian\Obsidian.exe"
-        echo [OK] Obsidian launched
+    ) else (
+        where obsidian >nul 2>nul && start "" obsidian
    )
+    echo [OK] Obsidian launched
 )

 echo.
--- a/scripts/setup.sh
+++ b/scripts/setup.sh
@@ -125,8 +125,11 @@ if command_exists claude; then
    fi
    
    # Initialize Claude in vault
-    claude init 2>/dev/null || true
-    print_success "Claude Code initialized in vault"
+    if claude init >/dev/null 2>&1; then
+        print_success "Claude Code initialized in vault"
+    else
+        print_warning "Claude Code initialization did not complete. You can run 'claude init' inside '$VAULT_PATH' later."
+    fi
 else
    print_warning "Skipping Claude Code setup (not installed)"
 fi
@@ -277,7 +280,13 @@ if [[ "$OSTYPE" == "darwin"* ]]; then
        read -p "Open Obsidian now? (y/n): " -n 1 -r
        echo
        if [[ $REPLY =~ ^[Yy]$ ]]; then
-            open -a Obsidian
+            # Try to open directly to this vault via obsidian URL
+            if command_exists python3; then
+                ENCODED_PATH=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1]))" "$VAULT_PATH")
+                open "obsidian://open?path=$ENCODED_PATH" || open -a Obsidian
+            else
+                open -a Obsidian
+            fi
            print_success "Obsidian launched"
        fi
    fi
@@ -285,7 +294,13 @@ elif command_exists obsidian; then
    read -p "Open Obsidian now? (y/n): " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
-        obsidian &
+        # On Linux, try obsidian URL first if xdg-open available
+        if command_exists xdg-open && command_exists python3; then
+            ENCODED_PATH=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1]))" "$VAULT_PATH")
+            xdg-open "obsidian://open?path=$ENCODED_PATH" >/dev/null 2>&1 || obsidian &
+        else
+            obsidian &
+        fi
        print_success "Obsidian launched"
    fi
 fi