Enhance README and CLI with remote persistence features

- Updated README to clarify the purpose of `monodev` and introduced the concept of Local-First Overlays.
- Added new CLI commands for managing remote persistence: `push` and `pull`, allowing users to share stores across machines and teams.
- Implemented functionality to configure remote settings, including selecting a remote and setting the persistence branch.
- Enhanced commit logic to notify users of removed paths that are no longer tracked.
- Introduced a SnapshotManager for materializing and dematerializing stores between local and remote directories.
- Added tests for remote configuration management and snapshot functionality.

Author: danieljhkim

README.md

@@ -1,19 +1,13 @@
 # monodev
 
-I frequently work with a giant monorepo consisting of countless components nested at varying depths. Because of its scale, it has a noticeable memory footprint on my machine and imposes subotimal landscape for AI agents. 
+Most codebases suffer from "local file drift." We generate debug scripts, AI scratchpads (.cursorrules, .claude, etc.), and task notes that live alongside our code but don't belong in the repo. These files are either accidentally committed (clutter) or deleted too soon (lost knowledge).
 
-To work around this, I selectively open individual components as isolated IDE workspaces, manually excluding irrelevant directories via settings.json. And during developing, I would additionally add various component-specific artifacts such as .cursor, Makefile, AGENTS.md, run.py, etc. 
+`monodev` introduces a third space: **Local-First Overlays**. It keeps your dev-only artifacts persistent and portable without ever leaking them into your Git history.
 
-Long story short, these dev/component specific artifacts cannot easily be commited and persisted methodically, making their reusability difficult across different branches and sessions.
-
-So I created `monodev`.
-
-`monodev` is a local-only CLI for managing **reusable development overlays** (scripts, editor config, agent-instructions, Makefiles, etc.) across large monorepos.
-
-It lets you:
-- keep dev-only files out of git
-- persist them safely per component or profile
-- re-apply and remove them deterministically
+The Monodev Way:
+- **Invisible**: Keeps "git status" clean.
+- **Persistent**: Your notes, scripts, and agent files survive branch switches.
+- **Portable**: Push/Pull your local state via hidden orphan branches.
 
 ---
 
@@ -22,9 +16,19 @@ It lets you:
 Platform support: macOS (Apple Silicon only)
 
 ```bash
+# 1. Install
 brew install danieljhkim/tap/monodev
 
-monodev version
+# 2. Create your first store and track a file
+monodev checkout -n my-debug-tools
+monodev track debug_helper.py
+monodev commit --all
+
+# 3. Remove the overlay after done working
+monodev unapply
+
+# 4. Reapply again later when needed
+monodev apply
 
 monodev help
 ```
@@ -194,20 +198,59 @@ monodev stack apply [--force] [--dry-run]
 monodev stack unapply [--force] [--dry-run]
 ```
 
+### Remote persistence
+
+Share stores across machines and teams using Git-based remote persistence. Stores are pushed to a separate orphan branch (`monodev/persist` by default) to keep them isolated from your main repository history.
+
+```bash
+monodev init # initialize the .monodev directory in the repository root
+
+# Configure which Git remote to use for persistence
+monodev remote use origin
+
+# Show current remote configuration
+monodev remote show
+
+# Set a custom persistence branch (optional)
+monodev remote set-branch monodev/custom
+
+# Push existing stores to remote
+monodev push <store-id>...
+
+# Pull stores from remote
+monodev pull <store-id>...
+
+# Pull and verify checksums
+monodev pull <store-id>... --verify
+
+# Force pull (overwrite local stores)
+monodev pull <store-id>... --force
+```
+
+**How it works:**
+
+1. Remote configuration is stored locally at `.monodev/remote.json`
+2. Stores are materialized to `.monodev/persist/stores/` before pushing
+3. A separate Git repository is created at `.monodev/.git` with an orphan branch
+4. The orphan branch is pushed to your configured remote
+5. When pulling, stores are fetched and dematerialized to `~/.monodev/stores/`
+
+This approach keeps persistence separate from your main Git history while leveraging Git's compression and deduplication.
+
 ---
 
-## What monodev is (and isn’t)
+## What monodev is (and isn't)
 
 **Is**
 - per-workspace dev overlay manager
-- designed for monorepos
+- designed for monorepos and large codebases
 - deterministic
+- portable
 
 **Is not**
 - a build system
 - a dependency manager
 - a replacement for dotfiles or Nix
-- always reversible
 
 ---
 

internal/cli/commit.go

@@ -61,6 +61,11 @@ var commitCmd = &cobra.Command{
 				PrintWarning(fmt.Sprintf("Would skip %s (not found in workspace):", PrintCount(len(result.Missing), "missing path", "missing paths")))
 				PrintList(result.Missing, 1)
 			}
+			if len(result.Removed) > 0 {
+				fmt.Println()
+				PrintInfo(fmt.Sprintf("Would remove %s from store (no longer tracked):", PrintCount(len(result.Removed), "path", "paths")))
+				PrintList(result.Removed, 1)
+			}
 			return nil
 		}
 
@@ -72,6 +77,10 @@ var commitCmd = &cobra.Command{
 			PrintWarning(fmt.Sprintf("Missing %s (not found in workspace):", PrintCount(len(result.Missing), "path", "paths")))
 			PrintList(result.Missing, 1)
 		}
+		if len(result.Removed) > 0 {
+			PrintInfo(fmt.Sprintf("Removed %s from store (no longer tracked):", PrintCount(len(result.Removed), "path", "paths")))
+			PrintList(result.Removed, 1)
+		}
 		return nil
 	},
 }

internal/cli/common.go

@@ -11,8 +11,11 @@ import (
 	"github.com/danieljhkim/monodev/internal/fsops"
 	"github.com/danieljhkim/monodev/internal/gitx"
 	"github.com/danieljhkim/monodev/internal/hash"
+	"github.com/danieljhkim/monodev/internal/persist"
+	"github.com/danieljhkim/monodev/internal/remote"
 	"github.com/danieljhkim/monodev/internal/state"
 	"github.com/danieljhkim/monodev/internal/stores"
+	"github.com/danieljhkim/monodev/internal/sync"
 )
 
 // newEngine creates a new engine with real implementations of all dependencies.
@@ -40,6 +43,33 @@ func newEngine() (*engine.Engine, error) {
 	return engine.New(gitRepo, storeRepo, stateStore, fs, hasher, clk, *paths), nil
 }
 
+// newSyncer creates a new syncer with real implementations of all dependencies.
+func newSyncer() (*sync.Syncer, error) {
+	// Get default paths
+	paths, err := config.DefaultPaths()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get config paths: %w", err)
+	}
+
+	// Ensure directories exist
+	if err := paths.EnsureDirectories(); err != nil {
+		return nil, fmt.Errorf("failed to ensure directories: %w", err)
+	}
+
+	// Create real implementations
+	fs := fsops.NewRealFS()
+	hasher := hash.NewSHA256Hasher()
+	clk := &clock.RealClock{}
+	stateStore := state.NewFileStateStore(fs, paths.Workspaces)
+	storeRepo := stores.NewFileStoreRepo(fs, paths.Stores)
+	gitPersist := remote.NewRealGitPersistence()
+	configStore := remote.NewFileRemoteConfigStore(fs)
+	snapshotMgr := persist.NewSnapshotManager(fs)
+
+	// Create syncer
+	return sync.New(gitPersist, storeRepo, stateStore, snapshotMgr, configStore, fs, hasher, clk), nil
+}
+
 // formatJSON formats a value as JSON.
 func formatJSON(v interface{}) (string, error) {
 	data, err := json.MarshalIndent(v, "", "  ")

internal/cli/format.go

@@ -46,6 +46,7 @@ func PrintSubsection(title string) {
 // PrintSuccess prints a success message with a checkmark
 func PrintSuccess(msg string) {
 	initColors()
+	fmt.Println()
 	_, _ = successColor.Printf("✓ %s\n", msg)
 }
 

internal/cli/pull.go

@@ -0,0 +1,108 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/danieljhkim/monodev/internal/gitx"
+	"github.com/danieljhkim/monodev/internal/sync"
+	"github.com/spf13/cobra"
+)
+
+var pullCmd = &cobra.Command{
+	Use:   "pull [store-id...]",
+	Short: "Pull stores from remote persistence repository",
+	Long: `Pull stores from the remote persistence repository.
+
+Fetches stores from the separate Git orphan branch at monodev/persist
+and restores them to ~/.monodev/stores/.
+
+If no store IDs are specified, pulls all stores from the remote.
+
+Examples:
+  # Pull all stores from remote
+  monodev pull
+
+  # Pull a single store
+  monodev pull my-store
+
+  # Pull multiple stores
+  monodev pull store1 store2
+
+  # Pull and verify checksums
+  monodev pull my-store --verify
+
+  # Force pull (overwrite local changes)
+  monodev pull my-store --force`,
+	Args: cobra.ArbitraryArgs,
+	RunE: runPull,
+}
+
+var (
+	pullRemote string
+	pullForce  bool
+	pullVerify bool
+)
+
+func init() {
+	pullCmd.Flags().StringVar(&pullRemote, "remote", "", "Git remote to pull from (defaults to configured remote)")
+	pullCmd.Flags().BoolVar(&pullForce, "force", false, "Force pull (overwrite local stores)")
+	pullCmd.Flags().BoolVar(&pullVerify, "verify", false, "Verify store integrity with checksums after pulling")
+}
+
+func runPull(cmd *cobra.Command, args []string) error {
+	ctx := context.Background()
+
+	// Get the repository root
+	gitRepo := gitx.NewRealGitRepo()
+	repoRoot, err := gitRepo.Discover(".")
+	if err != nil {
+		return fmt.Errorf("not in a git repository: %w", err)
+	}
+
+	// Create syncer
+	syncer, err := newSyncer()
+	if err != nil {
+		return fmt.Errorf("failed to create syncer: %w", err)
+	}
+
+	// Build request
+	req := &sync.PullRequest{
+		RepoRoot: repoRoot,
+		StoreIDs: args,
+		Remote:   pullRemote,
+		Force:    pullForce,
+		Verify:   pullVerify,
+	}
+
+	// Execute pull
+	result, err := syncer.PullStore(ctx, req)
+	if err != nil {
+		return err
+	}
+
+	// Display result
+	if len(result.PulledStores) > 0 {
+		if len(args) == 0 {
+			PrintSuccess(fmt.Sprintf("Pulled all stores (%d):", len(result.PulledStores)))
+		} else {
+			PrintSuccess("Pulled stores:")
+		}
+		for _, storeID := range result.PulledStores {
+			fmt.Printf("  - %s\n", storeID)
+		}
+		PrintInfo("")
+	} else {
+		PrintInfo("No stores found in remote")
+	}
+
+	if result.Verified {
+		PrintSuccess("All stores verified successfully")
+		PrintInfo("")
+	}
+
+	PrintInfo(fmt.Sprintf("Remote: %s", result.Remote))
+	PrintInfo(fmt.Sprintf("Branch: %s", result.Branch))
+
+	return nil
+}