From 625984ee0ef1219b860717d7053b2a66164547c7 Mon Sep 17 00:00:00 2001
From: Noah Brier <nbrier@gmail.com>
Date: Mon, 6 Oct 2025 17:09:29 -0400
Subject: [PATCH 1/5] feat: add iCloud vault support and launcher command
 installation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add new /install-claudesidian-command to create shell alias for launching vault from anywhere
- Add automatic iCloud Drive vault detection in init-bootstrap
- Add iCloud-specific search path with maxdepth 5 for nested structure
- Add fallback prompt asking about iCloud if vault not found
- Update README with launcher command documentation and usage examples
- Shell command auto-resumes existing sessions or starts new ones

This addresses user feedback about iCloud vault detection and adds convenient
shell launcher similar to obsidian-cli pattern.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .claude/commands/init-bootstrap.md            |  58 +++++++-
 .../commands/install-claudesidian-command.md  | 131 ++++++++++++++++++
 README.md                                     |  26 ++++
 3 files changed, 210 insertions(+), 5 deletions(-)
 create mode 100644 .claude/commands/install-claudesidian-command.md

diff --git a/.claude/commands/init-bootstrap.md b/.claude/commands/init-bootstrap.md
index 79cc795..8ea63dc 100644
--- a/.claude/commands/init-bootstrap.md
+++ b/.claude/commands/init-bootstrap.md
@@ -51,7 +51,12 @@ Then generate a customized CLAUDE.md file tailored to their needs.
 
 3. **Gather Vault Information**
    - Search common locations for existing Obsidian vaults (.obsidian folder)
-   - Check: ~/Documents, ~/Desktop, home directory, current directory parent
+   - Check these paths with appropriate depth limits:
+     - `~/Documents` (maxdepth 3)
+     - `~/Desktop` (maxdepth 3)
+     - `~/Library/Mobile Documents/iCloud~md~obsidian/Documents` (maxdepth 5 - iCloud vaults)
+     - Home directory `~/` (maxdepth 2)
+     - Current directory parent (maxdepth 2)
    - 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
@@ -64,8 +69,11 @@ Then generate a customized CLAUDE.md file tailored to their needs.
      - 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, ask for path to existing vault
-   - If no existing vault, they're starting fresh
+   - If not the right one or none found:
+     - Ask: "Is your vault stored in iCloud Drive? (yes/no)"
+     - If yes: "Please enter the full path to your vault (e.g., ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVault)"
+     - If no: "Please enter the path to your existing vault, or type 'skip' to start fresh"
+   - If no existing vault or user skips, they're starting fresh
 
 4. **Ask Configuration Questions**
    - "What's your name?" (for personalization)
@@ -349,6 +357,26 @@ If the user's response is unclear:
 - Example: "I want to make sure I import the right vault. Please type the number
   of your choice (1, 2, or 3)."
 
+### iCloud Vault Search Implementation
+
+When searching for vaults, use this find command pattern:
+
+```bash
+# Standard locations (shallow search)
+find ~/Documents ~/Desktop -maxdepth 3 -type d -name ".obsidian" 2>/dev/null
+
+# iCloud location (deeper search needed due to nested structure)
+find ~/Library/Mobile\ Documents/iCloud~md~obsidian/Documents -maxdepth 5 -type d -name ".obsidian" 2>/dev/null
+
+# 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
+
 ## Interactive Example
 
 ````
@@ -407,8 +435,8 @@ First-run marker removed
 
 Now let me ask you a few questions to customize your setup:
 
-🔍 **Searching for existing Obsidian vaults...** [Searches ~/Documents,
-~/Desktop, ~/, and parent directories]
+🔍 **Searching for existing Obsidian vaults...**
+[Searches ~/Documents, ~/Desktop, iCloud Drive, home directory, and parent directories]
 
 ### Case 1: Single Vault Found
 
@@ -457,6 +485,26 @@ 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 (iCloud Check)
+
+🔍 **No Obsidian vaults found in common locations.**
+
+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)
+
 📦 **Analyzing your vault structure...** [Running tree to see folder hierarchy]
 [Sampling notes to understand content] [Detecting naming patterns from recent
 files]
diff --git a/.claude/commands/install-claudesidian-command.md b/.claude/commands/install-claudesidian-command.md
new file mode 100644
index 0000000..97dddf9
--- /dev/null
+++ b/.claude/commands/install-claudesidian-command.md
@@ -0,0 +1,131 @@
+---
+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: `(cd /path/to/vault && (claude --resume 2>/dev/null || claude))`
+
+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
+
+```bash
+# Detect current shell
+if [ -n "$ZSH_VERSION" ]; then
+  SHELL_TYPE="zsh"
+  CONFIG_FILE="$HOME/.zshrc"
+elif [ -n "$BASH_VERSION" ]; then
+  SHELL_TYPE="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
+elif [ -n "$FISH_VERSION" ]; then
+  SHELL_TYPE="fish"
+  CONFIG_FILE="$HOME/.config/fish/config.fish"
+fi
+```
+
+## Installation Steps
+
+1. **Get vault path**: Use `pwd` to get current directory
+2. **Check if already installed**: Search config file for existing `claudesidian` alias
+3. **Add alias**: Append to config file if not present
+4. **Show success message**: With instructions to reload shell
+
+## Example Output
+
+```
+🔧 Installing claudesidian command...
+
+📁 Vault path: /home/user/my-vault
+🐚 Shell detected: zsh
+📝 Config file: /home/user/.zshrc
+
+✅ Installed! Added to /home/user/.zshrc:
+   alias claudesidian='(cd /home/user/my-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!
+```
+
+## Important Notes
+
+- The command uses a subshell `()` so it returns to your original directory after
+- Automatically tries to resume existing sessions, falls back to new session
+- If alias already exists, ask user if they want to replace it
+- Always show what will be added before modifying config files
+- Create backup of config file before modifying
+
+## Usage Examples
+
+Install for current shell:
+```
+/install-claudesidian-command
+```
+
+Install for specific shell:
+```
+/install-claudesidian-command zsh
+/install-claudesidian-command bash
+```
+
+## How It Works
+
+The alias uses a clever pattern:
+```bash
+alias claudesidian='(cd /path/to/vault && (claude --resume 2>/dev/null || claude))'
+```
+
+1. `(cd /path/to/vault && ...)` - Subshell that changes directory temporarily
+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, returns to original directory automatically
diff --git a/README.md b/README.md
index e8d9786..cc544ff 100644
--- a/README.md
+++ b/README.md
@@ -152,6 +152,7 @@ Pre-configured AI assistants ready to use:
 - `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
 
@@ -263,6 +264,31 @@ Run these with `pnpm`:
 
 ## Advanced Setup
 
+### Quick Launch from Anywhere
+
+Install a shell command to launch your vault from any directory:
+
+```bash
+# In Claude Code, run:
+/install-claudesidian-command
+```
+
+This creates a `claudesidian` alias that:
+- Changes to your vault directory automatically
+- Tries to resume your existing session (if one exists)
+- Falls back to starting a new session
+- Returns to your original directory when done
+
+**Usage:**
+```bash
+# From anywhere in your terminal:
+claudesidian
+
+# It will automatically resume your last session or start a new one
+```
+
+The command is added to your shell config (~/.zshrc, ~/.bashrc, etc.) so it persists across terminal sessions.
+
 ### Git Integration
 
 Initialize Git for version control:

From 1c9a9eead0e50b91d282b47112f6deeb6608797b Mon Sep 17 00:00:00 2001
From: Noah Brier <nbrier@gmail.com>
Date: Mon, 6 Oct 2025 17:11:44 -0400
Subject: [PATCH 2/5] chore: apply linting fixes to iCloud support and launcher
 command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .claude/commands/init-bootstrap.md            | 18 +++++++------
 .../commands/install-claudesidian-command.md  | 25 +++++++++++++------
 README.md                                     |  8 ++++--
 3 files changed, 35 insertions(+), 16 deletions(-)

diff --git a/.claude/commands/init-bootstrap.md b/.claude/commands/init-bootstrap.md
index 8ea63dc..9ff957a 100644
--- a/.claude/commands/init-bootstrap.md
+++ b/.claude/commands/init-bootstrap.md
@@ -54,7 +54,8 @@ Then generate a customized CLAUDE.md file tailored to their needs.
    - Check these paths with appropriate depth limits:
      - `~/Documents` (maxdepth 3)
      - `~/Desktop` (maxdepth 3)
-     - `~/Library/Mobile Documents/iCloud~md~obsidian/Documents` (maxdepth 5 - iCloud vaults)
+     - `~/Library/Mobile Documents/iCloud~md~obsidian/Documents` (maxdepth 5 -
+       iCloud vaults)
      - Home directory `~/` (maxdepth 2)
      - Current directory parent (maxdepth 2)
    - If found, ask: "Found Obsidian vault at [path]. Is this the vault you want
@@ -71,8 +72,10 @@ Then generate a customized CLAUDE.md file tailored to their needs.
      - Detect if using PARA, Zettelkasten, Johnny Decimal, or custom
    - If not the right one or none found:
      - Ask: "Is your vault stored in iCloud Drive? (yes/no)"
-     - If yes: "Please enter the full path to your vault (e.g., ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVault)"
-     - If no: "Please enter the path to your existing vault, or type 'skip' to start fresh"
+     - If yes: "Please enter the full path to your vault (e.g., ~/Library/Mobile
+       Documents/iCloud~md~obsidian/Documents/YourVault)"
+     - If no: "Please enter the path to your existing vault, or type 'skip' to
+       start fresh"
    - If no existing vault or user skips, they're starting fresh
 
 4. **Ask Configuration Questions**
@@ -373,6 +376,7 @@ 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
@@ -435,8 +439,8 @@ First-run marker removed
 
 Now let me ask you a few questions to customize your setup:
 
-🔍 **Searching for existing Obsidian vaults...**
-[Searches ~/Documents, ~/Desktop, iCloud Drive, home directory, and parent directories]
+🔍 **Searching for existing Obsidian vaults...** [Searches ~/Documents,
+~/Desktop, iCloud Drive, home directory, and parent directories]
 
 ### Case 1: Single Vault Found
 
@@ -493,8 +497,8 @@ 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)
+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
 
diff --git a/.claude/commands/install-claudesidian-command.md b/.claude/commands/install-claudesidian-command.md
index 97dddf9..49e6cf7 100644
--- a/.claude/commands/install-claudesidian-command.md
+++ b/.claude/commands/install-claudesidian-command.md
@@ -6,12 +6,13 @@ 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.
+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
@@ -29,16 +30,20 @@ Similar to having a quick launcher for your vault.
 ### 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: `(cd /path/to/vault && (claude --resume 2>/dev/null || claude))`
+- All in one command:
+  `(cd /path/to/vault && (claude --resume 2>/dev/null || claude))`
 
-This automatically enters resume mode if there's an existing session, or starts a new one if not.
+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`
@@ -73,7 +78,8 @@ fi
 ## Installation Steps
 
 1. **Get vault path**: Use `pwd` to get current directory
-2. **Check if already installed**: Search config file for existing `claudesidian` alias
+2. **Check if already installed**: Search config file for existing
+   `claudesidian` alias
 3. **Add alias**: Append to config file if not present
 4. **Show success message**: With instructions to reload shell
 
@@ -99,7 +105,8 @@ fi
 
 ## Important Notes
 
-- The command uses a subshell `()` so it returns to your original directory after
+- The command uses a subshell `()` so it returns to your original directory
+  after
 - Automatically tries to resume existing sessions, falls back to new session
 - If alias already exists, ask user if they want to replace it
 - Always show what will be added before modifying config files
@@ -108,11 +115,13 @@ fi
 ## Usage Examples
 
 Install for current shell:
+
 ```
 /install-claudesidian-command
 ```
 
 Install for specific shell:
+
 ```
 /install-claudesidian-command zsh
 /install-claudesidian-command bash
@@ -121,11 +130,13 @@ Install for specific shell:
 ## How It Works
 
 The alias uses a clever pattern:
+
 ```bash
 alias claudesidian='(cd /path/to/vault && (claude --resume 2>/dev/null || claude))'
 ```
 
 1. `(cd /path/to/vault && ...)` - Subshell that changes directory temporarily
-2. `claude --resume 2>/dev/null` - Tries to resume existing session, suppresses error
+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, returns to original directory automatically
diff --git a/README.md b/README.md
index cc544ff..132db7a 100644
--- a/README.md
+++ b/README.md
@@ -152,7 +152,8 @@ Pre-configured AI assistants ready to use:
 - `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
+- `install-claudesidian-command` - Install shell command to launch vault from
+  anywhere
 
 Run with: `/[command-name]` in Claude Code
 
@@ -274,12 +275,14 @@ Install a shell command to launch your vault from any directory:
 ```
 
 This creates a `claudesidian` alias that:
+
 - Changes to your vault directory automatically
 - Tries to resume your existing session (if one exists)
 - Falls back to starting a new session
 - Returns to your original directory when done
 
 **Usage:**
+
 ```bash
 # From anywhere in your terminal:
 claudesidian
@@ -287,7 +290,8 @@ claudesidian
 # It will automatically resume your last session or start a new one
 ```
 
-The command is added to your shell config (~/.zshrc, ~/.bashrc, etc.) so it persists across terminal sessions.
+The command is added to your shell config (~/.zshrc, ~/.bashrc, etc.) so it
+persists across terminal sessions.
 
 ### Git Integration
 

From ef1ef6073e8c1e899d3cd4842bca16c636b688e7 Mon Sep 17 00:00:00 2001
From: Noah Brier <nbrier@gmail.com>
Date: Tue, 7 Oct 2025 11:19:41 -0400
Subject: [PATCH 3/5] fix: address PR #8 security and cross-platform issues
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixed all critical and high-priority issues from code review:

Security fixes:
- Fix shell injection vulnerability with proper path escaping
- Add timestamped backup creation before modifying shell configs

Reliability improvements:
- Add comprehensive user input path validation
- Add iCloud sync state checking with soft warnings
- Improve shell detection to use default shell (not current session)

Cross-platform support:
- Add platform detection for iCloud features (macOS only)
- Document error handling approach
- Add helpful error messages with actionable suggestions

All changes ensure the commands work safely across Linux, macOS, and
Windows while providing better UX and preventing common user mistakes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .claude/commands/init-bootstrap.md            | 189 ++++++++++++++++--
 .../commands/install-claudesidian-command.md  | 122 ++++++++---
 2 files changed, 271 insertions(+), 40 deletions(-)

diff --git a/.claude/commands/init-bootstrap.md b/.claude/commands/init-bootstrap.md
index 9ff957a..fbdca5e 100644
--- a/.claude/commands/init-bootstrap.md
+++ b/.claude/commands/init-bootstrap.md
@@ -52,12 +52,12 @@ Then generate a customized CLAUDE.md file tailored to their needs.
 3. **Gather Vault Information**
    - Search common locations for existing Obsidian vaults (.obsidian folder)
    - Check these paths with appropriate depth limits:
-     - `~/Documents` (maxdepth 3)
-     - `~/Desktop` (maxdepth 3)
+     - `~/Documents` (maxdepth 3) - all platforms
+     - `~/Desktop` (maxdepth 3) - all platforms
      - `~/Library/Mobile Documents/iCloud~md~obsidian/Documents` (maxdepth 5 -
-       iCloud vaults)
-     - Home directory `~/` (maxdepth 2)
-     - Current directory parent (maxdepth 2)
+       **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
@@ -71,11 +71,12 @@ Then generate a customized CLAUDE.md file tailored to their needs.
      - Identify most active folders by file count
      - Detect if using PARA, Zettelkasten, Johnny Decimal, or custom
    - If not the right one or none found:
-     - Ask: "Is your vault stored in iCloud Drive? (yes/no)"
-     - If yes: "Please enter the full path to your vault (e.g., ~/Library/Mobile
-       Documents/iCloud~md~obsidian/Documents/YourVault)"
-     - If no: "Please enter the path to your existing vault, or type 'skip' to
-       start fresh"
+     - **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**
@@ -360,16 +361,52 @@ If the user's response is unclear:
 - 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)
-find ~/Library/Mobile\ Documents/iCloud~md~obsidian/Documents -maxdepth 5 -type d -name ".obsidian" 2>/dev/null
+# 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
@@ -380,6 +417,117 @@ 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
 
@@ -440,7 +588,8 @@ First-run marker removed
 Now let me ask you a few questions to customize your setup:
 
 🔍 **Searching for existing Obsidian vaults...** [Searches ~/Documents,
-~/Desktop, iCloud Drive, home directory, and parent directories]
+~/Desktop, home directory, and parent directories. On macOS, also searches iCloud
+Drive]
 
 ### Case 1: Single Vault Found
 
@@ -489,10 +638,11 @@ 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 (iCloud Check)
+### 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
@@ -509,6 +659,19 @@ Found vault at: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault
 
 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]
diff --git a/.claude/commands/install-claudesidian-command.md b/.claude/commands/install-claudesidian-command.md
index 49e6cf7..1ab605b 100644
--- a/.claude/commands/install-claudesidian-command.md
+++ b/.claude/commands/install-claudesidian-command.md
@@ -34,8 +34,11 @@ 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:
-  `(cd /path/to/vault && (claude --resume 2>/dev/null || 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.
@@ -56,32 +59,75 @@ Add the alias to the appropriate config file:
 
 ## Shell Detection
 
+Detects the user's default shell, with support for command-line override:
+
 ```bash
-# Detect current shell
-if [ -n "$ZSH_VERSION" ]; then
-  SHELL_TYPE="zsh"
-  CONFIG_FILE="$HOME/.zshrc"
-elif [ -n "$BASH_VERSION" ]; then
-  SHELL_TYPE="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
-elif [ -n "$FISH_VERSION" ]; then
-  SHELL_TYPE="fish"
-  CONFIG_FILE="$HOME/.config/fish/config.fish"
+# 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. **Get vault path**: Use `pwd` to get current directory
-2. **Check if already installed**: Search config file for existing
+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
-3. **Add alias**: Append to config file if not present
-4. **Show success message**: With instructions to reload shell
+5. **Create backup**: Before modifying, create timestamped backup of config file
+   ```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"
+   ```
+6. **Add alias**: Append to config file if not present, using double-quoted path
+7. **Show success message**: With instructions to reload shell
 
 ## Example Output
 
@@ -92,8 +138,10 @@ fi
 🐚 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-vault && (claude --resume 2>/dev/null || claude))'
+   alias claudesidian='(cd "/home/user/my-vault" && (claude --resume 2>/dev/null || claude))'
 
 🔄 To activate, run:
    source ~/.zshrc
@@ -103,6 +151,15 @@ fi
 ✨ 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.
+
 ## Important Notes
 
 - The command uses a subshell `()` so it returns to your original directory
@@ -110,32 +167,43 @@ fi
 - Automatically tries to resume existing sessions, falls back to new session
 - If alias already exists, ask user if they want to replace it
 - Always show what will be added before modifying config files
-- Create backup of config file before modifying
+- **Always create timestamped backup** of config file before modifying (format:
+  `YYYYMMDD-HHMMSS`)
+- Backups are kept indefinitely - users can manually clean up old backups if
+  needed
+- Show backup location so users know where to restore from if needed
 
 ## Usage Examples
 
-Install for current shell:
+Install for your default shell (auto-detected):
 
 ```
 /install-claudesidian-command
 ```
 
-Install for specific shell:
+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
 
 The alias uses a clever pattern:
 
 ```bash
-alias claudesidian='(cd /path/to/vault && (claude --resume 2>/dev/null || claude))'
+alias claudesidian='(cd "/path/to/vault" && (claude --resume 2>/dev/null || claude))'
 ```
 
-1. `(cd /path/to/vault && ...)` - Subshell that changes directory temporarily
+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

From eddbf61f926adbf8bee3e0d3d224eb8c656af3bb Mon Sep 17 00:00:00 2001
From: Noah Brier <nbrier@gmail.com>
Date: Tue, 7 Oct 2025 11:37:04 -0400
Subject: [PATCH 4/5] chore: apply linting fixes to PR #8 changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .claude/commands/init-bootstrap.md            | 41 ++++++++++++-------
 .../commands/install-claudesidian-command.md  |  9 +++-
 2 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/.claude/commands/init-bootstrap.md b/.claude/commands/init-bootstrap.md
index fbdca5e..81dd938 100644
--- a/.claude/commands/init-bootstrap.md
+++ b/.claude/commands/init-bootstrap.md
@@ -74,9 +74,10 @@ Then generate a customized CLAUDE.md file tailored to their needs.
      - **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, 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**
@@ -363,18 +364,23 @@ If the user's response is unclear:
 
 ### Platform Compatibility
 
-This command is designed to work across Linux, macOS, and Windows (WSL/Git Bash), with platform-specific features:
+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
+- Obsidian's iCloud sync is macOS-only, so iCloud features are disabled on other
+  platforms
 
 **Platform Detection:**
+
 ```bash
 # Check platform
 if [[ "$OSTYPE" == "darwin"* ]]; then
@@ -419,11 +425,14 @@ The iCloud path requires:
 - 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.
+**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:
+When users manually provide a vault path, validate it thoroughly with helpful
+error messages:
 
 ```bash
 # User provided path
@@ -487,9 +496,11 @@ 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)
+- 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)
@@ -523,6 +534,7 @@ 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
@@ -588,8 +600,8 @@ 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]
+~/Desktop, home directory, and parent directories. On macOS, also searches
+iCloud Drive]
 
 ### Case 1: Single Vault Found
 
@@ -642,8 +654,7 @@ You can migrate files to the PARA folders at your own pace.
 
 🔍 **No Obsidian vaults found in common locations.**
 
-**On macOS:**
-Is your vault stored in iCloud Drive? (yes/no)
+**On macOS:** Is your vault stored in iCloud Drive? (yes/no)
 
 User: yes
 
@@ -659,9 +670,9 @@ Found vault at: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault
 
 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)
+**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
 
diff --git a/.claude/commands/install-claudesidian-command.md b/.claude/commands/install-claudesidian-command.md
index 1ab605b..f036fbb 100644
--- a/.claude/commands/install-claudesidian-command.md
+++ b/.claude/commands/install-claudesidian-command.md
@@ -100,14 +100,17 @@ echo "📝 Config file: $CONFIG_FILE"
 ```
 
 **Key improvements:**
-- Uses `$SHELL` to detect default shell (not `$ZSH_VERSION`/`$BASH_VERSION` which detect current session)
+
+- 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`
+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
@@ -154,6 +157,7 @@ echo "📝 Config file: $CONFIG_FILE"
 ## 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
@@ -190,6 +194,7 @@ Install for specific shell (override auto-detection):
 ```
 
 **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

From 6c6a5675901270048af60ca254b1a2e97c695899 Mon Sep 17 00:00:00 2001
From: Noah Brier <nbrier@gmail.com>
Date: Tue, 7 Oct 2025 12:33:42 -0400
Subject: [PATCH 5/5] fix: address critical shell injection and add Fish shell
 support
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes from second PR #8 review:

Critical fixes:
- Show how to actually USE $ESCAPED_PATH in final command (not just escape it)
- Add Fish shell function syntax support (uses functions not aliases)
- Add existing alias/function replacement with user confirmation
- Reorder backup timing (after user confirms, before modifying)

Improvements:
- Example output now shows path with spaces to demonstrate escaping
- Added Fish shell syntax explanation section
- Added security considerations section
- Updated "How It Works" for both Bash/Zsh and Fish
- Clear step-by-step command generation with $ESCAPED_PATH

This ensures the shell injection vulnerability is truly fixed by showing
explicit usage of the escaped path variable in the final command generation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../commands/install-claudesidian-command.md  | 156 ++++++++++++++++--
 1 file changed, 142 insertions(+), 14 deletions(-)

diff --git a/.claude/commands/install-claudesidian-command.md b/.claude/commands/install-claudesidian-command.md
index f036fbb..44abedd 100644
--- a/.claude/commands/install-claudesidian-command.md
+++ b/.claude/commands/install-claudesidian-command.md
@@ -121,30 +121,74 @@ echo "📝 Config file: $CONFIG_FILE"
    ESCAPED_PATH="${ESCAPED_PATH//\\/\\\\}"
    ```
 4. **Check if already installed**: Search config file for existing
-   `claudesidian` alias
-5. **Create backup**: Before modifying, create timestamped backup of config file
+   `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"
    ```
-6. **Add alias**: Append to config file if not present, using double-quoted path
-7. **Show success message**: With instructions to reload shell
+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-vault
+📁 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-vault" && (claude --resume 2>/dev/null || claude))'
+   alias claudesidian='(cd "/home/user/My Obsidian Vault" && (claude --resume 2>/dev/null || claude))'
 
 🔄 To activate, run:
    source ~/.zshrc
@@ -154,6 +198,31 @@ echo "📝 Config file: $CONFIG_FILE"
 ✨ 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:
@@ -164,18 +233,59 @@ The implementation properly handles paths with:
 
 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 `()` so it returns to your original directory
-  after
+- 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 already exists, ask user if they want to replace it
-- Always show what will be added before modifying config files
-- **Always create timestamped backup** of config file before modifying (format:
+- 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
-- Show backup location so users know where to restore from if needed
+- Shows backup location so users know where to restore from if needed
 
 ## Usage Examples
 
@@ -201,7 +311,7 @@ Install for specific shell (override auto-detection):
 
 ## How It Works
 
-The alias uses a clever pattern:
+**Bash/Zsh (alias with subshell):**
 
 ```bash
 alias claudesidian='(cd "/path/to/vault" && (claude --resume 2>/dev/null || claude))'
@@ -212,4 +322,22 @@ alias claudesidian='(cd "/path/to/vault" && (claude --resume 2>/dev/null || clau
 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, returns to original directory automatically
+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