fix: Update Guix package definition for enhanced stash functionality

- Update version to 0.2.0 to reflect GNU Stow replacement features
- Fix wrapper script installation and path handling
- Update package description to mention enhanced functionality
- Ensure proper installation of wrapper script with GUILE_LOAD_PATH setup
- Package now supports all new features: deploy mode, dot syntax, restoration

The minimal-package.scm now correctly installs the enhanced stash with:
- Deploy mode (-d) for GNU Stow-like functionality
- Intelligent stashing and restoration capabilities
- Proper module loading via wrapper script

.dev-notes.md

@@ -0,0 +1,125 @@
+# Stash Development Notes
+
+## Project Status (as of last update)
+
+### Version
+
+- Current Version: 0.1.0-alpha.1
+
+### Core Components
+
+1. Main Script
+   - Location: `stash.scm`
+   - Status: Functional with recursive stashing support
+   - Features: Command-line interface, recursive mode, help system
+
+2. Modules
+   - Location: `modules/stash/`
+   - Components:
+     - help.scm: Help text and command documentation
+     - colors.scm: Terminal color support
+     - log.scm: Logging functionality
+     - paths.scm: Path manipulation utilities
+     - conflict.scm: Conflict resolution
+     - file-ops.scm: File operations
+     - package.scm: Package information
+     - tree.scm: Directory tree handling
+
+### Guix Integration
+
+1. Channel Configuration
+   - Location: `.guix-channel/`
+   - Status: Configured for distribution
+   - URL: <https://codeberg.org/glenneth/stash>~~~~
+   - Branch: main
+
+2. Package Definition
+   - Location: `.guix-channel/stash/packages/stash.scm`
+   - Build System: GNU Build System
+   - Dependencies: guile-3.0
+
+### Documentation
+
+1. README.md
+   - Basic installation instructions
+   - Key features
+   - Usage examples
+   - Recently updated with Guix installation method
+
+2. USER_GUIDE.md
+   - Comprehensive installation guide
+   - Shell configuration (Fish, Bash, Zsh)
+   - Usage examples
+   - Troubleshooting
+   - Recently added with detailed setup instructions
+
+3. channels.scm.example
+   - Example Guix channel configuration
+   - Updated to use Codeberg repository
+
+### Development Environment
+
+- Build System: Copy Build System (for local development)
+- Test Environment: Created test-source/ directory with sample files
+- Shell Integration: Configured for Fish, Bash, and Zsh
+
+### Recent Changes
+
+1. Documentation Updates
+   - Added USER_GUIDE.md with comprehensive setup instructions
+   - Updated README.md with Guix installation method
+   - Improved markdown formatting in documentation
+   - Updated repository links to Codeberg
+
+2. Package System
+   - Configured proper Guix channel distribution
+   - Updated package definition for channel distribution
+   - Added minimal-package.scm for local development
+
+### Next Steps
+
+1. Testing
+   - Implement comprehensive test suite
+   - Add more test cases for recursive mode
+
+2. Documentation
+   - Add API documentation for modules
+   - Include more advanced usage examples
+
+3. Features
+   - Enhance conflict resolution
+   - Add backup functionality
+   - Improve error reporting
+
+### Known Issues
+
+1. Warnings
+   - Intermittent warning about canonicalize-path override
+   - Auto-compilation messages (resolved with GUILE_AUTO_COMPILE=0)
+
+### Repository Structure
+
+```sh
+stash/
+├── .guix-channel/
+│   └── stash/
+│       └── packages/
+│           └── stash.scm
+├── modules/
+│   └── stash/
+│       ├── colors.scm
+│       ├── conflict.scm
+│       ├── file-ops.scm
+│       ├── help.scm
+│       ├── log.scm
+│       ├── package.scm
+│       ├── paths.scm
+│       └── tree.scm
+├── test-source/
+├── .gitignore
+├── README.md
+├── USER_GUIDE.md
+├── channels.scm.example
+├── minimal-package.scm
+└── stash.scm
+```

.gitignore

@@ -17,3 +17,8 @@ Thumbs.db
 .\#*
 *.swp
 *.swo
+
+# Test and build files
+test-channels.scm
+test-package.scm
+*.tar.gz

.guix-channel/channel.scm

@@ -0,0 +1,9 @@
+(channel
+  (version 0)
+  (url "https://codeberg.org/glenneth/stash")
+  (name 'stash)
+  (introduction
+   (make-channel-introduction
+    "581e2fea9d15e3f9626a2f9bca817354d5b2fcc2"  ; Current commit hash
+    (openpgp-fingerprint
+     "581e2fea9d15e3f9626a2f9bca817354d5b2fcc2"))))

.guix-channel/stash/packages/stash.scm

@@ -0,0 +1,55 @@
+(define-module (stash packages stash)
+  #:use-module (guix packages)
+  #:use-module (guix build-system gnu)
+  #:use-module (guix git-download)
+  #:use-module (guix gexp)
+  #:use-module ((guix licenses) #:prefix license:)
+  #:use-module (gnu packages guile))
+
+(define-public stash
+  (package
+    (name "stash")
+    (version "0.1.0-alpha.1")
+    (source (origin
+              (method git-fetch)
+              (uri (git-reference
+                    (url "https://codeberg.org/glenneth/stash.git")
+                    (commit (string-append "v" version))))
+              (file-name (git-file-name name version))
+              (sha256
+               (base32
+                "0rpir37xdk8f500fdrkbcixjc1q0mis9yi6a6b7r17lmkdn8vx4q"))))
+    (build-system gnu-build-system)
+    (arguments
+     `(#:phases
+       (modify-phases %standard-phases
+         (delete 'configure)
+         (replace 'build
+           (lambda _
+             #t))
+         (replace 'install
+           (lambda* (#:key outputs #:allow-other-keys)
+             (let* ((out (assoc-ref outputs "out"))
+                    (bin (string-append out "/bin"))
+                    (site (string-append out "/share/guile/site/3.0"))
+                    (go   (string-append out "/lib/guile/3.0/site-ccache")))
+               ;; Install binary
+               (install-file "stash.scm" bin)
+               (rename-file (string-append bin "/stash.scm")
+                          (string-append bin "/stash"))
+               (chmod (string-append bin "/stash") #o755)
+               ;; Install modules
+               (for-each
+                (lambda (file)
+                  (install-file file
+                               (string-append site "/stash")))
+                (find-files "modules/stash" "\\.scm$"))
+               #t))))))
+    (inputs
+     (list guile-3.0))
+    (native-inputs
+     (list guile-3.0))  ; For compilation
+    (synopsis "Symlink management utility")
+    (description "Stash is a command-line utility for managing symbolic links")
+    (home-page "https://codeberg.org/glenneth/stash")
+    (license license:gpl3+)))

DEVLOG.md

@@ -60,7 +60,7 @@ The project is organized into several modules:
 
 ## Current Operation
 
-Stash now supports two main modes of operation:
+Stash now supports three main modes of operation:
 
 1. Dot Syntax:
 
@@ -82,6 +82,16 @@ Stash now supports two main modes of operation:
    - Moves package from source to target
    - Creates symlink at original location
 
+3. Interactive Mode:
+
+   ```scheme
+   stash --source=~/.config/package --interactive
+   ```
+
+   - Takes source directory as input
+   - Interactively prompts for target directory
+   - Ideal for first-time users and exploratory stashing
+
 ### Symlink Creation Process
 
 1. Determines source and target paths

README.md

@@ -1,9 +1,34 @@
-# Stash
+# Stash - Enhanced GNU Stow Replacement
 
-`stash` is a command-line utility written in Guile Scheme that helps organize your files by moving them to a target location and creating symbolic links (symlinks) in their original location. While it's great for managing dotfiles, it works with any directories you want to organize.
+`stash` is a powerful command-line utility written in Guile Scheme that serves as an enhanced replacement for GNU Stow. It helps organize your files by moving them to a target location and creating symbolic links (symlinks) in their original location. With intelligent stashing, restoration capabilities, and GNU Stow-like deployment features, it's perfect for managing dotfiles and any other directory organization needs.
 
 ## Installation
 
+There are two ways to install Stash:
+
+### Method 1: Using Guix (Recommended)
+
+```sh
+# Install from the local package definition
+guix package --install-from-file=minimal-package.scm
+
+# Configure your shell environment:
+
+# For Fish shell (add to ~/.config/fish/config.fish):
+set -gx GUIX_PROFILE $HOME/.guix-profile
+set -gx PATH $GUIX_PROFILE/bin $PATH
+
+# For Bash (add to ~/.bashrc):
+export GUIX_PROFILE="$HOME/.guix-profile"
+. "$GUIX_PROFILE/etc/profile"
+
+# For Zsh (add to ~/.zshrc):
+export GUIX_PROFILE="$HOME/.guix-profile"
+. "$GUIX_PROFILE/etc/profile"
+```
+
+### Method 2: Manual Installation
+
 1. **Prerequisites**:
    - Guile Scheme 3.0.9 or later
    - A Unix-like environment (Linux/macOS)
@@ -31,50 +56,92 @@
    stash --help
    ```
 
+## Shell Integration
+
+After installation, you might want to ensure the `stash` command is easily accessible:
+
+1. **Using Guix Installation**:
+   - The command should be available after setting up your shell environment as shown above
+   - If not, create a symbolic link: `ln -sf ~/.guix-profile/bin/stash ~/.local/bin/stash`
+
+2. **Using Manual Installation**:
+
+   - Add an alias to your shell config:
+
+     ```sh
+     # For Fish (in ~/.config/fish/config.fish):
+     alias stash="guile -L /path/to/stash /path/to/stash/stash.scm"
+
+     # For Bash/Zsh:
+     alias stash='guile -L /path/to/stash /path/to/stash/stash.scm'
+     ```
+
 ## Key Features
 
+### GNU Stow Replacement Capabilities
+- **Deploy Mode**: Batch deployment of all packages (`stash -d`)
+- **Package Deployment**: Deploy specific packages (`stash package-name`)
+- **Dot Syntax**: Reverse symlinking from current directory (`stash .`)
+- **Intelligent Stashing**: Automatically detects existing symlinks and adapts behavior
+- **Restoration**: Complete file restoration with metadata tracking (`stash -R`)
+
+### Core Functionality
 - **Flexible Usage**: Works with any directories, not just config files
 - **Interactive Mode**: Option to interactively specify target directory
 - **Recursive Processing**: Can process entire directory trees
 - **Advanced Path Handling**: Supports home directory expansion and relative paths
 - **Symlink Management**: Creates and manages symlinks while maintaining directory structure
 - **Ignore Patterns**: Supports local and global ignore patterns
+- **Metadata Tracking**: Each stashed file includes restoration metadata
 
 ## Usage
 
-Stash offers several ways to organize your files:
+### GNU Stow-like Deployment (Recommended)
 
-1. **Interactive Mode** (easiest for beginners):
+```sh
+# Deploy all packages from dotfiles repository
+cd ~/.dotfiles && stash -d
 
-   ```sh
-   # Move Pictures directory to a backup location
-   guile -L . stash.scm --source ~/Pictures --interactive
-   ```
+# Deploy specific package
+cd ~/.dotfiles && stash shell
 
-2. **Explicit Paths**:
+# Using dot syntax (reverse symlinking)
+cd ~/.dotfiles/shell && stash .
+```
 
-   ```sh
-   # Move Documents to backup while keeping symlink
-   guile -L . stash.scm --source ~/Documents/notes --target ~/backup/notes
-   
-   # Move project to code archive
-   guile -L . stash.scm --source ~/projects/webapp --target ~/code/archive/webapp
-   ```
+### Traditional Stashing (File Organization)
 
-3. **Recursive Mode** (for entire directory trees):
+```sh
+# Stash individual files
+stash -s ~/.zshrc -t ~/.files
 
-   ```sh
-   # Archive entire projects directory
-   guile -L . stash.scm --source ~/projects --target ~/archive/projects --recursive
-   ```
+# Stash with interactive target selection
+stash -s ~/.config -i
 
-4. **Dot Syntax** (after files are stashed):
+# Recursive stashing
+stash -s ~/.config -t ~/.files -r
+```
 
-   ```sh
-   # Recreate symlink for previously stashed directory
-   cd ~/backup/notes
-   guile -L . stash.scm .
-   ```
+### Restoration
+
+```sh
+# Restore stashed files back to original locations
+stash -R -s ~/.files/config/app/config.yml
+```
+
+### Complete Dotfiles Workflow
+
+```sh
+# 1. Stash your configurations
+stash -s ~/.zshrc -t ~/.files
+stash -s ~/.config/app -t ~/.files
+
+# 2. On a new machine, deploy everything
+cd ~/.files && stash -d
+
+# 3. If needed, restore individual files
+stash -R -s ~/.files/config/app/config.yml
+```
 
 ## Common Use Cases
 
@@ -136,9 +203,10 @@ stash/
 │       ├── conflict.scm   # Conflict resolution
 │       ├── colors.scm     # Terminal colors
 │       └── help.scm       # Help messages
-├── README.md
-├── DEVLOG.md             # Development log
-└── LICENSE
+├── README.md             # Project overview
+├── USER-GUIDE.md         # Comprehensive user documentation
+├── DEVLOG.md            # Development log
+└── LICENSE              # GNU GPL v3
 ```
 
 ## Dependencies

USER_GUIDE.md

@@ -0,0 +1,412 @@
+# Stash User Guide - Enhanced GNU Stow Replacement
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Installation](#installation)
+   - [Using Guix](#using-guix)
+   - [Manual Installation](#manual-installation)
+3. [Shell Configuration](#shell-configuration)
+4. [GNU Stow-like Features](#gnu-stow-like-features)
+   - [Deploy Mode](#deploy-mode)
+   - [Dot Syntax](#dot-syntax)
+   - [Package Management](#package-management)
+5. [Traditional Stashing](#traditional-stashing)
+6. [Restoration](#restoration)
+7. [Intelligent Stashing](#intelligent-stashing)
+8. [Common Use Cases](#common-use-cases)
+9. [Advanced Features](#advanced-features)
+10. [Configuration](#configuration)
+11. [Troubleshooting](#troubleshooting)
+12. [Tips and Best Practices](#tips-and-best-practices)
+
+## Introduction
+
+Stash is a powerful symlink management utility written in Guile Scheme that serves as an enhanced replacement for GNU Stow. It helps you organize your files by moving them to a target location while maintaining easy access through symbolic links. With intelligent stashing, restoration capabilities, and GNU Stow-like deployment features, it's perfect for managing dotfiles and any other directory organization needs.
+
+### Why Use Stash?
+
+- **Keep Your Files Organized**: Move files to logical storage locations while maintaining easy access
+- **Backup with Access**: Store files in backup locations without changing your workflow
+- **Dotfile Management**: Perfect for managing configuration files across different machines
+- **Project Organization**: Archive old projects while keeping them accessible
+- **Cross-device File Management**: Safely manage files across different storage devices
+
+## Installation
+
+### Prerequisites
+
+- Guile Scheme 3.0.9 or later
+- Unix-like environment (Linux/macOS)
+
+### Using Guix
+
+The recommended way to install Stash is using the Guix package manager:
+
+```sh
+# Install from local package definition
+guix package --install-from-file=minimal-package.scm
+```
+
+After installation, the `stash` executable will be available in your Guix profile at `~/.guix-profile/bin/stash`.
+
+### Manual Installation
+
+If you're not using Guix, you can install Stash manually:
+
+1. Install prerequisites:
+
+   ```sh
+   # Debian/Ubuntu
+   sudo apt-get install guile-3.0
+
+   # Fedora
+   sudo dnf install guile30
+
+   # Arch Linux
+   sudo pacman -S guile
+   ```
+
+2. Clone and set up the repository:
+
+   ```sh
+   git clone https://codeberg.org/glenneth/stash.git
+   cd stash
+   mkdir -p ~/.guile.d/site/3.0
+   ln -s $(pwd)/modules/stash ~/.guile.d/site/3.0/
+   ```
+
+## Shell Configuration
+
+### Fish Shell
+
+1. Add to `~/.config/fish/config.fish`:
+
+   ```fish
+   # Guix environment setup
+   set -gx GUIX_PROFILE $HOME/.guix-profile
+   set -gx PATH $GUIX_PROFILE/bin $PATH
+
+   # Load Guix environment variables
+   if test -f $GUIX_PROFILE/etc/profile
+       for line in (cat $GUIX_PROFILE/etc/profile | grep '^export' | string replace 'export ' '')
+           set var (string split '=' $line)
+           set -gx $var[1] (eval echo $var[2])
+       end
+   end
+   ```
+
+2. Alternative method using symlink:
+
+   ```fish
+   ln -sf ~/.guix-profile/bin/stash ~/.local/bin/stash
+   ```
+
+### Bash Shell
+
+Add to `~/.bashrc`:
+
+```bash
+# Guix environment setup
+export GUIX_PROFILE="$HOME/.guix-profile"
+if [ -f "$GUIX_PROFILE/etc/profile" ]; then
+    . "$GUIX_PROFILE/etc/profile"
+fi
+```
+
+### Zsh Shell
+
+Add to `~/.zshrc`:
+
+```zsh
+# Guix environment setup
+export GUIX_PROFILE="$HOME/.guix-profile"
+if [ -f "$GUIX_PROFILE/etc/profile" ]; then
+    . "$GUIX_PROFILE/etc/profile"
+fi
+```
+
+## GNU Stow-like Features
+
+Stash provides enhanced GNU Stow replacement functionality with intelligent behavior and additional features.
+
+### Deploy Mode
+
+Deploy mode (`-d`) allows you to batch deploy all packages from a dotfiles repository, similar to GNU Stow:
+
+```sh
+# Deploy all packages from current directory
+cd ~/.dotfiles && stash -d
+
+# Deploy all packages with explicit path
+stash -d /path/to/dotfiles
+```
+
+**How it works:**
+- Scans the current directory for subdirectories (packages)
+- Creates symlinks from each package's contents to the home directory
+- Automatically handles directory structure creation
+- Skips system files like `.git`, `README.md`, etc.
+
+### Dot Syntax
+
+The dot syntax (`.`) provides reverse symlinking - creating a symlink from the current directory back to its corresponding location in the home directory:
+
+```sh
+# From within a dotfiles package directory
+cd ~/.dotfiles/shell
+stash .
+# Creates: ~/.shell -> ~/.dotfiles/shell
+```
+
+**Use cases:**
+- Quick reverse linking from dotfiles repo
+- Testing configurations before full deployment
+- Selective package activation
+
+### Package Management
+
+Deploy specific packages by name:
+
+```sh
+# Deploy only the shell package
+cd ~/.dotfiles && stash shell
+
+# Deploy only the emacs package  
+cd ~/.dotfiles && stash emacs
+```
+
+**Package structure example:**
+```
+~/.dotfiles/
+├── shell/
+│   ├── zshrc
+│   └── bashrc
+├── emacs/
+│   ├── config.org
+│   └── init.el
+└── git/
+    └── gitconfig
+```
+
+## Restoration
+
+Stash includes complete restoration capabilities with metadata tracking:
+
+```sh
+# Restore a specific file
+stash -R -s ~/.files/config/app/config.yml
+
+# Restore using metadata
+stash -R -s /path/to/stashed/file
+```
+
+**Features:**
+- Each stashed file includes `.stash-meta` metadata
+- Metadata contains original path information
+- Automatic directory structure recreation
+- Safe restoration with conflict detection
+
+## Intelligent Stashing
+
+Stash automatically detects existing symlinks and adapts its behavior:
+
+**File-level stashing:** When a directory already contains symlinks, stash operates at the file level to avoid "symlink to symlink" issues.
+
+**Directory-level stashing:** When no symlinks exist, stash can move entire directories.
+
+```sh
+# First file - directory level stashing
+stash -s ~/.config/app/config.yml -t ~/.files
+
+# Second file - detects existing symlink, uses file-level stashing  
+stash -s ~/.config/app/theme.json -t ~/.files
+```
+
+## Traditional Stashing
+
+### How Stash Works
+
+1. **Source Directory**: The original location of your files
+2. **Target Directory**: Where you want to store the files
+3. **Symbolic Links**: Created in the source location, pointing to the target
+
+### Key Terms
+
+- **Stashing**: The process of moving files to a target location and creating symlinks
+- **Dot Syntax**: A shorthand way to create symlinks for previously stashed files
+- **Recursive Mode**: Processing entire directory trees
+
+## Usage Patterns
+
+### 1. Interactive Mode
+
+Best for beginners or when you want to choose the target location interactively.
+
+```sh
+stash --source ~/Pictures --interactive
+```
+
+### 2. Explicit Paths
+
+When you know exactly where you want to store files.
+
+```sh
+stash --source ~/Documents/notes --target ~/backup/notes
+```
+
+### 3. Dot Syntax
+
+Quick way to create symlinks for previously stashed files.
+
+```sh
+cd ~/.dotfiles/config/nvim
+stash .    # Creates symlink in ~/.config/nvim
+```
+
+### 4. Recursive Mode
+
+For processing entire directory trees.
+
+```sh
+stash --source ~/.config --target ~/.dotfiles/config --recursive
+```
+
+## Common Use Cases
+
+### 1. Managing Dotfiles
+
+Keep configuration files in a git repository:
+
+```sh
+# Initial stash
+stash --source ~/.config/nvim --target ~/.dotfiles/config/nvim
+
+# Later, on another machine
+cd ~/.dotfiles/config/nvim
+stash .
+```
+
+### 2. Project Organization
+
+Archive old projects while keeping them accessible:
+
+```sh
+stash --source ~/projects/old-webapp --target ~/archive/projects/webapp
+```
+
+### 3. Cross-device File Management
+
+Store large files on external drives:
+
+```sh
+stash --source ~/Videos --target /media/external/videos --recursive
+```
+
+## Advanced Features
+
+### 1. Path Handling
+
+- Supports home directory expansion (~)
+- Handles both absolute and relative paths
+- Maintains directory structure in target location
+
+### 2. Symlink Management
+
+- Creates intermediate directories as needed
+- Handles existing symlinks gracefully
+- Preserves original file permissions
+
+### 3. Ignore Patterns
+
+- Create `.stashignore` in source directory
+- Add patterns similar to `.gitignore`
+
+```sh
+*.tmp
+.DS_Store
+node_modules/
+```
+
+### 4. Conflict Resolution
+
+- Automatically detects existing files/symlinks
+- Interactive prompts for resolution
+- Options to skip, replace, or backup
+
+## Configuration
+
+### Environment Variables
+
+- `GUILE_AUTO_COMPILE=0`: Disable auto-compilation
+- `GUILE_LOAD_PATH`: Add custom module paths
+- `GUIX_PROFILE`: Set Guix profile location
+
+### Global Configuration
+
+- System-wide ignore patterns in `/etc/stash/ignore`
+- User-specific patterns in `~/.config/stash/ignore`
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+1. **Command Not Found**
+   - Verify Guix profile is sourced correctly
+   - Check PATH includes `~/.guix-profile/bin`
+   - Try creating symlink in `~/.local/bin`
+
+2. **Module Loading Issues**
+   - Ensure GUILE_LOAD_PATH includes module directory
+   - Check module permissions and ownership
+   - Verify Guile version compatibility
+
+3. **Permission Errors**
+   - Check file/directory permissions
+   - Ensure write access to target location
+   - Verify symlink creation permissions
+
+4. **Common Warnings**
+   - "canonicalize-path override": Normal, can be ignored
+   - "auto-compilation enabled": Set GUILE_AUTO_COMPILE=0
+
+### Cross-device Issues
+
+- Use the recursive flag for cross-device operations
+- Ensure target location has sufficient space
+
+## Tips and Best Practices
+
+1. **Organization**
+
+   - Keep related files together in the target location
+   - Use meaningful directory names
+   - Document your stash organization
+
+2. **Backup**
+
+   - Always back up important files before stashing
+   - Test symlinks after creation
+   - Use version control for dotfiles
+
+3. **Maintenance**
+
+   - Regularly check for broken symlinks
+   - Keep your stash locations organized
+   - Document your stash structure
+
+## Command Reference
+
+### Basic Commands
+
+```sh
+stash --help                 # Display help
+stash --version             # Show version
+stash --source DIR          # Specify source directory
+stash --target DIR          # Specify target directory
+stash --recursive           # Process directories recursively
+stash --interactive         # Interactive target selection
+```
+
+For more information or to report issues, visit:
+<https://codeberg.org/glenneth/stash>

channels.scm.example

@@ -0,0 +1,7 @@
+(list (channel
+        (name 'guix)
+        (url "https://git.savannah.gnu.org/git/guix.git"))
+      (channel
+        (name 'stash)
+        (url "https://codeberg.org/glenneth/stash")
+        (branch "main")))

minimal-package.scm

@@ -0,0 +1,46 @@
+(define-module (stash-package)
+  #:use-module (guix packages)
+  #:use-module (guix build-system copy)
+  #:use-module (guix licenses)
+  #:use-module (guix gexp)
+  #:use-module (gnu packages guile))
+
+(define-public stash
+  (package
+    (name "stash")
+    (version "0.2.0")
+    (source (local-file "." "stash-checkout"
+                       #:recursive? #t))
+    (build-system copy-build-system)
+    (arguments
+     '(#:install-plan
+       '(("stash.scm" "share/guile/site/3.0/stash.scm")
+         ("stash" "bin/stash")
+         ("modules/stash" "share/guile/site/3.0/stash"))
+       #:phases
+       (modify-phases %standard-phases
+         (add-after 'install 'setup-wrapper
+           (lambda* (#:key outputs #:allow-other-keys)
+             (let* ((out (assoc-ref outputs "out"))
+                    (bin (string-append out "/bin"))
+                    (wrapper (string-append bin "/stash")))
+               ;; Make wrapper executable
+               (chmod wrapper #o755)
+               ;; Update wrapper script paths
+               (substitute* wrapper
+                 (("/home/glenn/Projects/Code/stash/stash")
+                  (string-append out "/share/guile/site/3.0/stash.scm"))
+                 (("/home/glenn/Projects/Code/stash")
+                  out "/share/guile/site/3.0"))
+               #t))))))
+    (inputs
+     (list guile-3.0))
+    (synopsis "Enhanced GNU Stow replacement - symlink management utility")
+    (description "Stash is a powerful command-line utility written in Guile Scheme 
+that serves as an enhanced replacement for GNU Stow. It provides intelligent stashing, 
+restoration capabilities, and GNU Stow-like deployment features for managing dotfiles 
+and organizing any directories through symlink management.")
+    (home-page "https://codeberg.org/glenneth/stash")
+    (license gpl3+)))
+
+stash

modules/stash/help.scm

@@ -9,35 +9,49 @@
 (define (display-help)
   "Display help message explaining how to use the program."
   (display "\
-Usage: stash.scm [OPTION...] [.]
+Usage: stash [OPTION...] [PACKAGE|.]
 
-Stash is a symlink management utility that helps organize your files by moving them
-to a target location and creating symbolic links in their original location.
+Enhanced Stash with GNU Stow-like functionality for dotfiles management.
 
 Options:
   -s, --source=DIR    Source directory to stash
   -t, --target=DIR    Target directory where files will be stashed
   -r, --recursive     Recursively process directories under source
   -i, --interactive   Interactively prompt for target directory
+  -d, --deploy        Deploy mode: create symlinks from dotfiles repo
+  -R, --restore       Restore stashed files back to original locations
   -h, --help         Display this help
   -v, --version      Display version information
 
-Examples:
-  # Using dot syntax (after files are stashed):
-  cd ~/.dotfiles/config/nvim
-  stash.scm .                    # Creates symlink in ~/.config/nvim
-
+Stashing Examples (moving files to storage):
   # Stash a single directory:
-  stash.scm -s ~/Documents/notes -t ~/backup/notes  # Move notes and create symlink
-  
+  stash -s ~/Documents/notes -t ~/backup/notes
+
   # Stash with interactive target selection:
-  stash.scm -s ~/Pictures -i     # Will prompt for target directory
+  stash -s ~/Pictures -i
 
   # Recursively stash an entire directory:
-  stash.scm -s ~/.config -t ~/.dotfiles/config -r  # Stash all config files
+  stash -s ~/.config -t ~/.dotfiles/config -r
 
-  # Stash any directory to any location:
-  stash.scm -s ~/projects/web -t ~/backup/code/web  # Not limited to dotfiles
+Deployment Examples (GNU Stow-like functionality):
+  # Deploy all packages from dotfiles directory:
+  cd ~/.dotfiles && stash -d
+
+  # Deploy specific package:
+  cd ~/.dotfiles && stash shell
+
+  # Using dot syntax (create symlink from current dir to home):
+  cd ~/.dotfiles/shell && stash .
+
+Restoration Examples:
+  # Restore a stashed file back to original location:
+  stash -R -s ~/.files/config/guix/channels.scm
+
+Dotfiles Workflow:
+  1. Collect dotfiles: ~/.files/collect-dotfiles.sh
+  2. Stash to dotfiles repo: stash -s ~/.zshrc -t ~/.files
+  3. On new machine: cd ~/.files && stash -d
+  4. Restore if needed: stash -R -s ~/.files/config/guix/channels.scm
 
 Note: Stash works with any directories, not just config files or dotfiles.
       You can use it to organize any files by moving them to a backup/storage

modules/stash/tree.scm

@@ -21,7 +21,7 @@
   (make-tree-node path type children)
   tree-node?
   (path node-path)
-  (type node-type)  ; 'file or 'directory
+  (type node-type)  ; 'file, 'directory, or 'symlink
   (children node-children))
 
 ;; Check if a path should be ignored based on patterns
@@ -37,16 +37,20 @@
     (let analyze ((path root-path))
       (if (should-ignore? path ignore-patterns)
           #f
-          (if (file-is-directory? path)
-              (let* ((entries (scandir path))
-                     (children (filter-map
-                               (lambda (entry)
-                                 (if (member entry '("." ".."))
-                                     #f
-                                     (analyze (string-append path "/" entry))))
-                               entries)))
-                (make-tree-node path 'directory children))
-              (make-tree-node path 'file '()))))))
+          (cond
+           ((file-is-symlink? path)
+            (make-tree-node path 'symlink '()))
+           ((file-is-directory? path)
+            (let* ((entries (scandir path))
+                   (children (filter-map
+                             (lambda (entry)
+                               (if (member entry '("." ".."))
+                                   #f
+                                   (analyze (string-append path "/" entry))))
+                             entries)))
+              (make-tree-node path 'directory children)))
+           (else
+            (make-tree-node path 'file '())))))))
 
 ;; Determine if a directory tree can be folded
 (define (can-fold-tree? node target-base)

stash

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# Stash - Enhanced symlink management utility
+# Wrapper script that sets up the proper Guile load path
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Set up Guile load path to include both project root and modules directory
+export GUILE_LOAD_PATH="$SCRIPT_DIR:$SCRIPT_DIR/modules:$GUILE_LOAD_PATH"
+export GUILE_AUTO_COMPILE=0
+
+# Run the modular stash.scm with proper module loading
+exec guile "$SCRIPT_DIR/stash.scm" "$@"

stash.scm

@@ -1,38 +1,3 @@
-;;; stash.scm --- A Guile script for moving directories and creating symlinks with conflict resolution
-;;;
-;;; Author: Glenn Thompson <glenn@kirstol.org>
-;;; Version: 0.1.0-alpha.1
-;;; Created: 2024-12-03
-;;; Compatibility: Guile 3.0.9
-;;; Keywords: symlink, file management, conflict resolution, backup
-;;;
-;;; Commentary:
-;;;
-;;; Stash is a command-line utility written in Guile Scheme designed to facilitate the movement of directories and
-;;; creation of symbolic links (symlinks) for files and directories. It allows users to specify a source directory
-;;; and a target directory where the symlink should be created. The utility handles potential conflicts with existing
-;;; files or directories at the target location, offering users the choice to overwrite, back up, or skip the creation of new symlinks.
-;;;
-;;; Main Features:
-;;; - Command-line argument parsing for specifying source and target paths.
-;;; - Conflict detection with interactive user resolution options (overwrite, backup, skip, or cancel).
-;;; - Moving directories and creating symlinks.
-;;; - Simple and interactive user interface for easy use.
-;;;
-;;; Usage:
-;;;
-;;; guile -L . stash.scm --target=<target-dir> --source=<source-dir>
-;;;
-;;; Replace <target-dir> with the directory where you want the symlink to be created,
-;;; and <source-dir> with the path to the source directory.
-;;;
-;;; License:
-;;;
-;;; This project is licensed under the GNU General Public License v3.
-;;;
-
-;;; CODE
-
 (define-module (stash)
   #:use-module (ice-9 getopt-long)
   #:use-module (ice-9 ftw)
@@ -46,12 +11,8 @@
   #:use-module (stash package)
   #:use-module (stash tree)
   #:use-module (srfi srfi-1)
-  #:use-module (srfi srfi-19))
-
-;;; Color constants
-(define blue-text "\x1b[0;34m")
-(define yellow-text "\x1b[0;33m")
-(define red-text "\x1b[0;31m")
+  #:use-module (srfi srfi-19)
+  #:export (main))
 
 ;;; Command-line options
 (define %options
@@ -59,62 +20,11 @@
     (source    (value #t)  (single-char #\s))
     (recursive (value #f)  (single-char #\r))
     (interactive (value #f) (single-char #\i))
+    (deploy    (value #f)  (single-char #\d))
+    (restore   (value #f)  (single-char #\R))
     (help      (value #f)  (single-char #\h))
     (version   (value #f)  (single-char #\v))))
 
-;;; Function to handle dot directory stashing
-(define (handle-dot-stash)
-  "Handle stashing when using the '.' syntax. Uses parent directory as target."
-  (let* ((current-dir (canonicalize-path (getcwd)))
-         (pkg-dir (if (file-is-symlink? current-dir)
-                     (canonicalize-path (readlink current-dir))
-                     current-dir))
-         (pkg-name (basename pkg-dir))
-         (stow-dir (dirname pkg-dir))
-         (target-dir (dirname stow-dir))
-         (ignore-patterns (read-ignore-patterns pkg-dir)))
-    (format #t "Package directory: ~a~%" pkg-dir)
-    (format #t "Stow directory: ~a~%" stow-dir)
-    (format #t "Target directory: ~a~%" target-dir)
-    (if (file-is-symlink? current-dir)
-        (format #t "Directory is already stashed at: ~a~%" pkg-dir)
-        (let ((package (make-package pkg-name pkg-dir target-dir ignore-patterns)))
-          (process-package package)))))
-
-;;; Version function
-(define (display-version)
-  "Display the current version of the program."
-  (newline)
-  (display "Stash version 0.1.0-alpha.1\n")
-  (exit 0))
-
-;;; Helper function to check for version flag and display version
-(define (check-for-version args)
-  "Check if --version or -v is in the arguments list."
-  (if (or (member "--version" args)
-          (member "-v" args))
-      (display-version)))
-
-;;; Main function to handle stowing operations
-(define (handle-stow package options)
-  (let* ((tree (analyze-tree package))
-         (simulate? (assoc-ref options 'simulate))
-         (no-folding? (assoc-ref options 'no-folding)))
-    (plan-operations tree package)))
-
-;;; Prompt user for target directory path
-(define (prompt-for-target source-path)
-  "Prompt user for target directory path."
-  (display (color-message (string-append "\nSource directory: " source-path "\n") blue-text))
-  (display (color-message "Enter target directory path (where files will be stashed): " yellow-text))
-  (let ((input (read-line)))
-    (if (string-null? input)
-        (begin
-          (display (color-message "Target directory cannot be empty. Please try again.\n" red-text))
-          (prompt-for-target source-path))
-        (canonicalize-path (expand-home input)))))
-
-;;; Main entry point
 (define (main args)
   "Main function to parse arguments and execute the program."
   (setenv "GUILE_AUTO_COMPILE" "0")
@@ -122,29 +32,41 @@
   (let* ((options (getopt-long args %options))
          (help-wanted? (option-ref options 'help #f))
          (version-wanted? (option-ref options 'version #f))
+         (source (option-ref options 'source #f))
+         (target (option-ref options 'target #f))
          (recursive? (option-ref options 'recursive #f))
          (interactive? (option-ref options 'interactive #f))
-         (source (option-ref options 'source #f))
-         (target (option-ref options 'target #f)))
+         (deploy? (option-ref options 'deploy #f))
+         (restore? (option-ref options 'restore #f))
+         (remaining-args (option-ref options '() '())))
     
     (cond
-     (help-wanted? (display-help) (exit 0))
-     (version-wanted? (display-version) (exit 0))
-     
-     ;; Handle dot syntax
-     ((and (= (length (option-ref options '() '())) 1)
-           (string=? (car (option-ref options '() '())) "."))
-      (handle-dot-stash))
-     
-     ;; Handle interactive mode
-     ((and source interactive?)
-      (let ((target-path (prompt-for-target (canonicalize-path source))))
-        (handle-explicit-stash source target-path recursive?)))
-     
-     ;; Handle explicit paths with optional recursion
+     (help-wanted?
+      (display-help)
+      (exit 0))
+     (version-wanted?
+      (display-version)
+      (exit 0))
+     (deploy?
+      (handle-deploy-mode remaining-args)
+      #t)
+     (restore?
+      (handle-restore-mode source)
+      #t)
      ((and source target)
-      (handle-explicit-stash source target recursive?))
-     
+      (handle-explicit-stash source target recursive?)
+      #t)
+     ((and source interactive?)
+      (handle-interactive-stash source recursive?)
+      #t)
+     ;; Handle dot syntax: stash .
+     ((and (= (length remaining-args) 1) (string=? (car remaining-args) "."))
+      (handle-dot-syntax)
+      #t)
+     ;; Handle package deployment: stash package-name
+     ((and (= (length remaining-args) 1) (not (string=? (car remaining-args) ".")))
+      (handle-package-deploy (car remaining-args))
+      #t)
      (else
       (display-help)
       (exit 1)))))
@@ -152,45 +74,287 @@
 (define (handle-explicit-stash source target recursive?)
   "Handle stashing with explicit source and target paths."
   (let* ((source-path (canonicalize-path source))
-         (target-path (canonicalize-path target))
-         (package-name (basename source-path))
-         (ignore-patterns (read-ignore-patterns source-path)))
-    (if recursive?
-        (handle-recursive-stash source-path target-path)
-        (let ((package (make-package package-name source-path target-path ignore-patterns)))
-          (process-package package)))))
+         (target-base (canonicalize-path target))
+         (target-path (create-smart-target-path source source-path target-base)))
+    
+    (cond
+     ;; Handle individual files
+     ((file-is-regular? source-path)
+      (handle-file-stash source-path target-path))
+     
+     ;; Handle directories
+     ((file-is-directory? source-path)
+      (if (directory-has-symlinks? (dirname source-path))
+          ;; Parent directory has symlinks, use file-level stashing
+          (handle-directory-file-level source-path target-path recursive?)
+          ;; No symlinks in parent, use directory-level stashing
+          (handle-directory-level source-path target-path recursive?)))
+     
+     (else
+      (display (format #f "Error: ~a is not a regular file or directory\n" source-path))
+      (exit 1)))))
 
-(define (handle-recursive-stash source target)
-  "Recursively process directories under source."
-  (let* ((source-path (canonicalize-path source))
-         (target-path (canonicalize-path target))
-         (source-name (basename source-path))
-         (target-config-path (string-append target-path "/" source-name))
-         (entries (if (file-is-directory? source-path)
-                     (scandir source-path)
-                     (list (basename source-path))))
-         (valid-entries (filter (lambda (entry)
-                                (and (not (member entry '("." "..")))
-                                     (file-is-directory? (string-append source-path "/" entry))))
-                              entries)))
-    ;; First ensure the config directory exists in target
-    (if (not (file-exists? target-config-path))
-        (mkdir-p target-config-path))
-    ;; Then process each subdirectory
+(define (create-smart-target-path original-source source-path target-base)
+  "Create intelligent target path that preserves directory structure."
+  (let* ((home-dir (getenv "HOME"))
+         ;; Use the original source string if it's relative, otherwise extract from absolute path
+         (source-relative 
+          (cond
+           ;; If original source is relative (doesn't start with /), use it directly
+           ((not (string-prefix? "/" original-source))
+            original-source)
+           ;; If source is under home directory, make it relative to home
+           ((string-prefix? home-dir source-path)
+            (string-drop source-path (+ (string-length home-dir) 1)))
+           ;; Otherwise just use basename
+           (else (basename source-path))))
+         ;; Remove leading dot from hidden files/dirs for cleaner organization
+         (clean-relative (if (string-prefix? "." source-relative)
+                             (string-drop source-relative 1)
+                             source-relative)))
+    ;; Create clean target path
+    (string-append target-base "/" clean-relative)))
+
+(define (create-path-metadata source-path target-path)
+  "Create metadata file to track original path structure for restoration."
+  (let* ((metadata-file (string-append target-path ".stash-meta"))
+         (home-dir (getenv "HOME"))
+         (original-relative (if (string-prefix? home-dir source-path)
+                               (string-drop source-path (+ (string-length home-dir) 1))
+                               source-path))
+         (timestamp (strftime "%Y-%m-%d %H:%M:%S" (localtime (time-second (current-time))))))
+    (call-with-output-file metadata-file
+      (lambda (port)
+        (write `((original-path . ,original-relative)
+                 (timestamp . ,timestamp)
+                 (stash-version . "0.2.0")) port)))))
+
+;; Helper functions for intelligent stashing
+
+(define (file-is-regular? path)
+  "Check if a path is a regular file."
+  (and (file-exists? path)
+       (not (file-is-directory? path))
+       (not (file-is-symlink? path))))
+
+(define (directory-has-symlinks? dir-path)
+  "Check if a directory contains any symlinks."
+  (if (file-exists? dir-path)
+      (let ((entries (scandir dir-path)))
+        (any (lambda (entry)
+               (and (not (member entry '("." "..")))
+                    (file-is-symlink? (string-append dir-path "/" entry))))
+             entries))
+      #f))
+
+(define (handle-file-stash source-path target-path)
+  "Handle stashing of individual files."
+  (display (format #f "Stashing file: ~a -> ~a\n" source-path target-path))
+  ;; Create target directory if it doesn't exist
+  (let ((target-dir (dirname target-path)))
+    (when (not (file-exists? target-dir))
+      (mkdir-p target-dir)))
+  ;; Create metadata for restoration
+  (create-path-metadata source-path target-path)
+  ;; Move file to target
+  (rename-file source-path target-path)
+  ;; Create symlink back to original location
+  (symlink target-path source-path)
+  (display (format #f "Created symlink: ~a -> ~a\n" source-path target-path)))
+
+(define (handle-directory-level source-path target-path recursive?)
+  "Handle directory-level stashing (traditional stash behavior)."
+  (display (format #f "Directory-level stashing: ~a -> ~a\n" source-path target-path))
+  ;; Create target directory if it doesn't exist
+  (let ((target-dir (dirname target-path)))
+    (when (not (file-exists? target-dir))
+      (mkdir-p target-dir)))
+  ;; Create metadata for restoration
+  (create-path-metadata source-path target-path)
+  ;; Move directory to target
+  (rename-file source-path target-path)
+  ;; Create symlink back to original location
+  (symlink target-path source-path)
+  (display (format #f "Created directory symlink: ~a -> ~a\n" source-path target-path)))
+
+(define (handle-directory-file-level source-path target-path recursive?)
+  "Handle file-level stashing within a directory that has symlinks."
+  (display (format #f "File-level stashing in directory: ~a\n" source-path))
+  (let ((entries (scandir source-path)))
     (for-each
      (lambda (entry)
-       (let* ((source-dir (string-append source-path "/" entry))
-              (package-name entry)
-              (ignore-patterns (read-ignore-patterns source-dir)))
-         (let ((package (make-package package-name source-dir target-config-path ignore-patterns)))
-           (process-package package))))
-     valid-entries)))
+       (when (not (member entry '("." "..")))
+         (let* ((entry-source (string-append source-path "/" entry))
+                (entry-target (string-append target-path "/" entry)))
+           (cond
+            ;; Skip existing symlinks
+            ((file-is-symlink? entry-source)
+             (display (format #f "Skipping existing symlink: ~a\n" entry-source)))
+            ;; Stash regular files
+            ((file-is-regular? entry-source)
+             (handle-file-stash entry-source entry-target))
+            ;; Recursively handle subdirectories if recursive mode
+            ((and recursive? (file-is-directory? entry-source))
+             (handle-directory-file-level entry-source entry-target recursive?))))))
+     entries)))
+
+(define (handle-recursive-stash source-path target-path)
+  "Handle recursive stashing of directories."
+  (let* ((base-name (basename source-path))
+         (ignore-patterns (read-ignore-patterns source-path))
+         (package (make-package base-name source-path target-path ignore-patterns)))
+    (process-package package)
+    #t))
 
 (define (process-package package)
   "Process a single package for stashing."
   (let* ((tree (analyze-tree package))
          (operations (plan-operations tree package)))
-    (execute-operations operations)))
+    (execute-operations operations)
+    #t))
+
+;;; Enhanced handler functions for GNU Stow-like functionality
+
+(define (handle-interactive-stash source recursive?)
+  "Handle interactive stashing where user selects target directory."
+  (display "Interactive target selection:\n")
+  (display (format #f "Source: ~a\n" source))
+  (display "Enter target directory: ")
+  (let ((target (read-line)))
+    (if (string-null? target)
+        (begin
+          (display "No target specified. Exiting.\n")
+          (exit 1))
+        (handle-explicit-stash source target recursive?))))
+
+(define (handle-dot-syntax)
+  "Handle dot syntax: create symlink from current directory to home."
+  (let* ((current-dir (getcwd))
+         (home-dir (getenv "HOME"))
+         (relative-path (string-drop current-dir (+ (string-length home-dir) 1)))
+         (target-path (string-append home-dir "/" relative-path)))
+    (display (format #f "Creating symlink: ~a -> ~a\n" target-path current-dir))
+    (when (file-exists? target-path)
+      (if (file-is-symlink? target-path)
+          (delete-file target-path)
+          (begin
+            (display (format #f "Error: ~a already exists and is not a symlink\n" target-path))
+            (exit 1))))
+    (let ((target-dir (dirname target-path)))
+      (when (not (file-exists? target-dir))
+        (mkdir-p target-dir)))
+    (symlink current-dir target-path)
+    (display (format #f "Created symlink: ~a -> ~a\n" target-path current-dir))))
+
+(define (handle-package-deploy package-name)
+  "Deploy a specific package from current directory."
+  (let* ((package-dir (string-append (getcwd) "/" package-name))
+         (home-dir (getenv "HOME")))
+    (if (file-exists? package-dir)
+        (deploy-package package-dir home-dir)
+        (begin
+          (display (format #f "Error: Package directory ~a not found\n" package-dir))
+          (exit 1)))))
+
+(define (handle-deploy-mode args)
+  "Handle deploy mode: deploy all packages or specific package."
+  (let ((current-dir (getcwd))
+        (home-dir (getenv "HOME")))
+    (if (null? args)
+        ;; Deploy all packages in current directory
+        (deploy-all-packages current-dir home-dir)
+        ;; Deploy specific package
+        (handle-package-deploy (car args)))))
+
+(define (deploy-all-packages dotfiles-dir home-dir)
+  "Deploy all packages from dotfiles directory."
+  (display (format #f "Deploying all packages from ~a to ~a\n" dotfiles-dir home-dir))
+  (let ((entries (scandir dotfiles-dir)))
+    (for-each
+     (lambda (entry)
+       (let ((entry-path (string-append dotfiles-dir "/" entry)))
+         (when (and (not (member entry '("." ".." ".git" "README.md" "collect-dotfiles.sh" "STASH_GUIDE.md")))
+                    (file-is-directory? entry-path))
+           (display (format #f "Deploying package: ~a\n" entry))
+           (deploy-package entry-path home-dir))))
+     entries)))
+
+(define (deploy-package package-dir home-dir)
+  "Deploy a single package by creating symlinks."
+  (let ((package-name (basename package-dir)))
+    (display (format #f "Deploying package: ~a\n" package-name))
+    (deploy-directory-contents package-dir home-dir)))
+
+(define (deploy-directory-contents source-dir target-base)
+  "Recursively deploy directory contents by creating symlinks."
+  (let ((entries (scandir source-dir)))
+    (for-each
+     (lambda (entry)
+       (when (not (member entry '("." "..")))
+         (let* ((source-path (string-append source-dir "/" entry))
+                (target-path (string-append target-base "/." entry)))
+           (cond
+            ((file-is-directory? source-path)
+             ;; For directories, create the directory and recurse
+             (when (not (file-exists? target-path))
+               (mkdir target-path #o755))
+             (deploy-directory-contents source-path (dirname target-path)))
+            (else
+             ;; For files, create symlink
+             (when (file-exists? target-path)
+               (if (file-is-symlink? target-path)
+                   (delete-file target-path)
+                   (display (format #f "Warning: ~a exists and is not a symlink, skipping\n" target-path))))
+             (let ((target-dir (dirname target-path)))
+               (when (not (file-exists? target-dir))
+                 (mkdir-p target-dir)))
+             (symlink source-path target-path)
+             (display (format #f "Created symlink: ~a -> ~a\n" target-path source-path)))))))
+     entries)))
+
+;;; Restoration functionality
+
+(define (handle-restore-mode source-path)
+  "Handle restoration of stashed files back to original locations."
+  (if source-path
+      (restore-stashed-item source-path)
+      (begin
+        (display "Error: --restore requires --source to specify what to restore\n")
+        (exit 1))))
+
+(define (restore-stashed-item stashed-path)
+  "Restore a stashed file or directory back to its original location."
+  (let* ((metadata-file (string-append stashed-path ".stash-meta"))
+         (home-dir (getenv "HOME")))
+    (if (file-exists? metadata-file)
+        (let* ((metadata (call-with-input-file metadata-file read))
+               (original-relative (assoc-ref metadata 'original-path))
+               (original-path (string-append home-dir "/" original-relative)))
+          (display (format #f "Restoring: ~a -> ~a\n" stashed-path original-path))
+          
+          ;; Remove existing symlink if it exists
+          (when (and (file-exists? original-path) (file-is-symlink? original-path))
+            (delete-file original-path))
+          
+          ;; Create parent directory if needed
+          (let ((parent-dir (dirname original-path)))
+            (when (not (file-exists? parent-dir))
+              (mkdir-p parent-dir)))
+          
+          ;; Move file/directory back
+          (rename-file stashed-path original-path)
+          
+          ;; Remove metadata file
+          (delete-file metadata-file)
+          
+          (display (format #f "Restored: ~a\n" original-path)))
+        (begin
+          (display (format #f "Error: No metadata found for ~a\n" stashed-path))
+          (display "Cannot restore without metadata file\n")
+          (exit 1)))))
 
 ;; Entry point for stash
-(main (command-line))
+(let ((result (main (command-line))))
+  (if result
+      (exit 0)
+      (exit 1)))

test-source/dir1/file1.txt

@@ -0,0 +1 @@
+content1

test-source/dir1/subdir1/file2.txt

@@ -0,0 +1 @@
+content2

test-source/dir2/file3.txt

@@ -0,0 +1 @@
+content3

test-source/dir2/subdir2/file4.txt

@@ -0,0 +1 @@
+content4