feat: Add comprehensive cloud mount CLI commands and documentation

This commit implements SPEC-7 Phase 4 by adding local file access capabilities
to the Basic Memory Cloud CLI, enabling users to mount their cloud files locally
for real-time editing.

New features:
- Cloud mount setup with automatic rclone installation
- Mount/unmount/status commands with three performance profiles
- Cross-platform rclone installer with package manager fallbacks
- Mount configuration management with tenant-specific credentials
- Comprehensive documentation with examples and troubleshooting

Mount profiles:
- fast: 5s sync for active development
- balanced: 10-15s sync (recommended)
- safe: 15s+ sync with conflict detection

Technical implementation:
- Uses rclone NFS mount (no FUSE dependencies)
- Tigris object storage with scoped credentials
- Bidirectional sync with configurable cache settings
- Process management and cleanup

Fixes Python module conflict by moving cloud.py commands to cloud/core_commands.py
to resolve typer CLI loading issues with cloud.py file vs cloud/ directory.

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

Co-Authored-By: Claude <[email protected]>
Signed-off-by: phernandez <[email protected]>

Author: phernandez

docs/cloud-cli.md

@@ -1,13 +1,14 @@
 # Basic Memory Cloud CLI Guide
 
-The Basic Memory Cloud CLI provides commands for interacting with Basic Memory Cloud instances, including authentication, project management, and file synchronization. This guide covers installation, configuration, and usage of the cloud features.
+The Basic Memory Cloud CLI provides commands for interacting with Basic Memory Cloud instances, including authentication, project management, file synchronization, and local file access. This guide covers installation, configuration, and usage of the cloud features.
 
 ## Overview
 
 The cloud CLI enables you to:
 - Authenticate with Basic Memory Cloud using OAuth
 - List and create projects on cloud instances
 - Upload local files and directories to cloud projects via WebDAV
+- Mount cloud files locally for real-time editing with rclone
 - Check the health status of cloud instances
 - Automatically filter uploads using gitignore patterns
 
@@ -141,6 +142,136 @@ Uploading 23 file(s) to project 'my-project' on https://cloud.basicmemory.com...
 Successfully uploaded 23 file(s)!
 ```
 
+## Local File Access
+
+Basic Memory Cloud supports mounting your cloud files locally using rclone, enabling real-time editing with your favorite text editor or IDE. Changes made locally are automatically synchronized to the cloud.
+
+### Setup
+
+Before mounting files, you need to set up the local access system:
+
+```bash
+bm cloud setup
+```
+
+This command will:
+1. Check if rclone is installed (and install it if needed)
+2. Retrieve your tenant information from the cloud
+3. Generate secure, scoped credentials for your tenant
+4. Configure rclone with your tenant's storage settings
+5. Display instructions for mounting your files
+
+### Mounting Files
+
+Mount your cloud files to a local directory:
+
+```bash
+# Mount with default (balanced) profile
+bm cloud mount
+
+# Mount with specific profile
+bm cloud mount --profile fast
+bm cloud mount --profile balanced
+bm cloud mount --profile safe
+```
+
+#### Mount Profiles
+
+Different profiles optimize for different use cases:
+
+- **fast**: Ultra-fast development (5s sync, higher bandwidth)
+  - Cache time: 5s, Poll interval: 3s
+  - Best for: Active development, frequent file changes
+
+- **balanced**: Fast development (10-15s sync, recommended)
+  - Cache time: 10s, Poll interval: 5s
+  - Best for: General use, good balance of speed and reliability
+
+- **safe**: Conflict-aware mount with backup (15s+ sync)
+  - Cache time: 15s, Poll interval: 10s
+  - Includes conflict detection and backup functionality
+  - Best for: Collaborative editing, important documents
+
+### Mount Status
+
+Check the current mount status:
+
+```bash
+bm cloud mount-status
+```
+
+Example output:
+```
+                               Cloud Mount Status
+┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Property         ┃ Value                                                     ┃
+┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ Tenant ID        │ 63cd4020-2e31-5c53-bdbc-07182b129183                      │
+│ Mount Path       │ ~/basic-memory-63cd4020-2e31-5c53-bdbc-07182b129183       │
+│ Status           │ ✓ Mounted                                                 │
+│ rclone Processes │ 1 running                                                 │
+└──────────────────┴───────────────────────────────────────────────────────────┘
+
+Available mount profiles:
+  fast: Ultra-fast development (5s sync, higher bandwidth)
+  balanced: Fast development (10-15s sync, recommended)
+  safe: Conflict-aware mount with backup
+```
+
+### Unmounting Files
+
+Unmount your cloud files and clean up processes:
+
+```bash
+bm cloud unmount
+```
+
+This command will:
+1. Unmount the filesystem
+2. Kill any running rclone processes
+3. Clean up temporary files
+
+### Working with Mounted Files
+
+Once mounted, your cloud files appear as a regular directory on your local system. You can:
+
+- Edit files with any text editor or IDE
+- Create new files and directories
+- Move and rename files
+- Use command-line tools like `grep`, `find`, etc.
+
+#### Example Workflow
+
+```bash
+# Set up local access
+bm cloud setup
+
+# Mount your files
+bm cloud mount --profile balanced
+
+# Navigate to your mounted files
+cd ~/basic-memory-{your-tenant-id}
+
+# Edit files with your preferred editor
+code my-notes.md
+vim research/paper.md
+
+# Changes are automatically synced to the cloud
+# Check sync status
+bm cloud mount-status
+
+# When done, unmount
+bm cloud unmount
+```
+
+### Technical Details
+
+- **Protocol**: Uses rclone with NFS mount (no FUSE dependencies)
+- **Storage**: Files are stored in Tigris object storage (S3-compatible)
+- **Sync**: Bidirectional synchronization with configurable cache settings
+- **Security**: Uses scoped, time-limited credentials for your tenant only
+- **Compatibility**: Works on macOS, Linux, and Windows
+
 ## Instance Management
 
 ### Health Check
@@ -192,7 +323,7 @@ By default, the CLI uses production authentication settings. For development or
 
 ```bash
 # For development environment
-export BASIC_MEMORY_CLOUD_HOST="http://development.cloud.basicmemory.com"
+export BASIC_MEMORY_CLOUD_HOST="https://development.cloud.basicmemory.com"
 export BASIC_MEMORY_CLOUD_CLIENT_ID="client_01K46RED2BW9YKYE4N7Y9BDN2V"
 export BASIC_MEMORY_CLOUD_DOMAIN="https://exciting-aquarium-32-staging.authkit.app"
 
@@ -243,6 +374,32 @@ bm cloud upload my-project ./path --no-gitignore
 1. Verify the cloud instance is running: `bm cloud status`
 2. Check your internet connection
 
+### Mount Issues
+
+**Problem**: "rclone not found" during setup
+**Solution**: The setup command will attempt to install rclone automatically. If this fails:
+- **macOS**: `brew install rclone`
+- **Linux**: `sudo snap install rclone` or `sudo apt install rclone`
+- **Windows**: `winget install Rclone.Rclone`
+
+**Problem**: Mount fails with permission errors
+**Solution**:
+- Ensure you have proper permissions for the mount directory
+- On Linux, you may need to add your user to the `fuse` group
+- Try unmounting any existing mounts: `bm cloud unmount`
+
+**Problem**: Files not syncing or appearing outdated
+**Solution**:
+1. Check mount status: `bm cloud mount-status`
+2. Try remounting with a faster profile: `bm cloud mount --profile fast`
+3. Unmount and remount: `bm cloud unmount && bm cloud mount`
+
+**Problem**: Multiple mount processes running
+**Solution**: Clean up orphaned processes:
+```bash
+bm cloud unmount  # This will clean up all processes
+bm cloud mount    # Fresh mount
+```
 
 ## Security
 
@@ -264,8 +421,14 @@ bm cloud project add <name> [--default]
 # File operations
 bm cloud upload <project> <path>  [--no-preserve-timestamps] [--no-gitignore]
 
+# Local file access
+bm cloud setup                           # Set up local access with rclone
+bm cloud mount [--profile <profile>]     # Mount cloud files locally
+bm cloud mount-status                    # Check mount status
+bm cloud unmount                         # Unmount cloud files
+
 # Instance management
-bm cloud status 
+bm cloud status
 ```
 
 For more information about Basic Memory Cloud, visit the [official documentation](https://memory.basicmachines.co).

src/basic_memory/cli/commands/__init__.py

@@ -14,4 +14,5 @@
     "import_chatgpt",
     "tool",
     "project",
+    "cloud",
 ]

src/basic_memory/cli/commands/cloud/__init__.py

@@ -1 +1,4 @@
 """Cloud commands package."""
+
+# Import all commands to register them with typer
+from basic_memory.cli.commands.cloud.core_commands import *  # noqa: F401,F403

src/basic_memory/cli/commands/cloud.py …mory/cli/commands/cloud/core_commands.pysrc/basic_memory/cli/commands/cloud.py renamed to src/basic_memory/cli/commands/cloud/core_commands.py src/basic_memory/cli/commands/cloud.py renamed to src/basic_memory/cli/commands/cloud/core_commands.py

@@ -1,4 +1,4 @@
-"""Command module for basic-memory cloud operations."""
+"""Core cloud commands for Basic Memory CLI."""
 
 import asyncio
 from pathlib import Path
@@ -46,7 +46,7 @@ async def _login():
     asyncio.run(_login())
 
 
-# Project
+# Project commands
 
 project_app = typer.Typer(help="Manage Basic Memory Cloud Projects")
 cloud_app.add_typer(project_app, name="project")
@@ -395,4 +395,4 @@ def unmount() -> None:
 @cloud_app.command("mount-status")
 def mount_status() -> None:
     """Show current mount status."""
-    show_mount_status()
+    show_mount_status()