diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
new file mode 100644
index 0000000..02fcf74
--- /dev/null
+++ b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,45 @@
+name: Deploy mdBook Documentation
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
+      
+      - name: Build book
+        run: mdbook build
+      
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./book/build
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index 0d049e3..981fbf5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,4 +30,5 @@ $RECYCLE.BIN/
 !PULL_REQUEST_TEMPLATE.md
 !CHANGELOG.md
 !CONTRIBUTING.md
-!docs/*
+!book/**
+book/build/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6d2209b..4329588 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2025-11-17
+
+### Added
+
+- **Package Management Commands**: Integrated package management with environment activation
+  - `uvup add <packages>` - Add packages to active environment (supports `--group`)
+  - `uvup remove <packages>` - Remove packages from active environment (supports `--group`)
+  - `uvup lock` - Update lockfile of active environment (supports `--upgrade`)
+  - `uvup tree` - Display dependency tree of active environment (supports `--depth`)
+- All package commands use `uv --project` internally, allowing management from any directory
+
+### Changed
+
+- **Breaking**: Renamed `uvup remove <name>` to `uvup delete <name>` for environment deletion
+  - This clarifies the distinction between deleting environments vs removing packages
+  - `remove` is now exclusively for package removal
+
+### Documentation
+
+- Updated README.md with integrated package management examples
+- Updated COMMANDS.md with complete package management command reference
+- Updated USE_CASES.md replacing all `uv add`/`uv remove` with `uvup` equivalents
+- Added design philosophy explanation for command organization
+
+### Technical
+
+- Added `commands/add.rs` for package addition
+- Renamed `commands/remove.rs` to `commands/delete.rs` for environment deletion
+- Created new `commands/remove.rs` for package removal
+- Added `commands/lock.rs` for lockfile management
+- Added `commands/tree.rs` for dependency tree display
+- Added `NoActiveEnvironment` error type for better error messages
+
 ## [0.2.0] - 2025-11-17
 
 ### Added
@@ -133,6 +166,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - clap 4.5 - CLI framework
 - dirs 6.0 - Cross-platform directory paths
 
+[0.2.1]: https://github.com/KercyDing/uvup/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/KercyDing/uvup/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/KercyDing/uvup/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/KercyDing/uvup/compare/v0.1.1...v0.1.2
diff --git a/README.md b/README.md
index 32c5861..dfb1bd2 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # uvup
 
-[![DeepWiki](https://img.shields.io/badge/DeepWiki-blue)](https://deepwiki.com/KercyDing/uvup) [![uv](https://img.shields.io/badge/uv-black?logo=github)](https://github.com/astral-sh/uv)
+[![Docs](https://img.shields.io/badge/Docs-blue)](https://kercyding.github.io/uvup/) [![DeepWiki](https://img.shields.io/badge/DeepWiki-orange)](https://deepwiki.com/KercyDing/uvup) [![uv](https://img.shields.io/badge/uv-black?logo=github)](https://github.com/astral-sh/uv)
 
 A conda-like environment manager for [uv](https://github.com/astral-sh/uv).
 
@@ -27,198 +27,71 @@ curl -fsSL https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install
 Invoke-RestMethod https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.ps1 | Invoke-Expression
 ```
 
-For detailed installation instructions, manual installation, and developer setup, see [Installation Guide](docs/INSTALL.md).
+See the [Installation Guide](https://kercyding.github.io/uvup/installation.html) for more details.
 
-## Uninstallation
+## Quick Start
 
-**Linux and macOS:**
 ```bash
-curl -fsSL -O https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/uninstall.sh
-chmod +x uninstall.sh
-./uninstall.sh
-```
-
-**Windows (PowerShell):**
-```powershell
-Invoke-WebRequest -Uri https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/uninstall.ps1 -OutFile uninstall.ps1
-.\uninstall.ps1
-```
-
-For detailed uninstallation instructions and manual removal, see [Uninstallation Guide](docs/UNINSTALL.md).
-
-## Planned Features
-
-### v0.2.0 - Completed
-
-- [x] `uvup clone <source> <target>` - Clone environments (1:1 exact copy)
-- [x] `uvup new <name> --template <template>` - Create projects from templates
-- [x] `uvup sync --template <template>` - Sync current project with template
-- [x] Template modification support (--python, --exclude, --include)
-- [x] Dry-run preview mode for all template operations
-- [x] pyproject.toml-based dependency management
-- [x] optional-dependencies support
-
-### Future Versions
-
-- Official template repository with curated project templates
-- `uvup template list` - Browse available official templates
-- Auto-download templates on first use
-- `uvup default <name>` - Set default environment
-- Package manager support (Homebrew, Scoop, Winget)
-
-## Usage
-
-### Quick Start
-
-```bash
-# Create a new environment
+# Create and activate environment
 uvup create myproject
-
-# Create with specific Python version
-uvup create myproject --python 3.12
-
-# List all environments
-uvup list
-
-# Activate an environment
 uvup activate myproject
 
-# Install packages (using uv)
-uv add numpy pandas
+# Add packages
+uvup add numpy pandas
+
+# Work with your code
+python script.py
 
 # Deactivate
 uvup deactivate
-
-# Remove an environment
-uvup remove myproject
 ```
 
-### Environment Cloning
+📖 **[Read the full documentation](https://kercyding.github.io/uvup/)** for complete usage guide.
 
-Clone an existing environment to create an exact 1:1 copy:
+## Key Features
 
+### Environment Management
 ```bash
-# Clone an environment
-uvup clone myproject myproject-backup
-
-# The cloned environment will have identical:
-# - Python version
-# - All dependencies (from pyproject.toml)
-# - Lock file (uv.lock)
+uvup create myenv          # Create environment
+uvup list                  # List all environments
+uvup activate myenv        # Activate environment
+uvup delete myenv          # Delete environment
 ```
 
-### Template-based Project Creation
-
-Create new projects from template environments with modification support:
-
+### Template System
 ```bash
-# Preview changes before creating
-uvup new myapp --template web-template --dry-run
-
-# Create a project from a template
-uvup new myapp --template web-template
-
-# Create with custom Python version
-uvup new myapp --template web-template --python 3.11
-
-# Create with package filtering
-uvup new myapp --template web-template --exclude pytest,black
-uvup new myapp --template web-template --include numpy,pandas,requests
-
-# Create in a custom directory
-uvup new myapp --template web-template --path ~/projects
-```
+# Clone existing environment
+uvup clone source target
 
-### Template Synchronization
-
-Sync an existing project with a template environment:
-
-```bash
-# Preview changes before syncing
-uvup sync --template web-template --dry-run
+# Create from template with modifications
+uvup new myapp --template web-template --exclude dev-tools
 
 # Sync current project with template
-cd myproject
-uvup sync --template web-template
-
-# Sync with Python version override
-uvup sync --template web-template --python 3.11
-
-# Sync with package filtering
-uvup sync --template web-template --exclude dev-packages
-uvup sync --template web-template --include numpy,pandas
+uvup sync --template web-template --dry-run
 ```
 
-### Command Categories
-
-uvup provides four distinct command categories:
-
-1. **Create** - Create empty environments
-   ```bash
-   uvup create myenv --python 3.12
-   ```
-
-2. **Clone** - 1:1 exact copy (no modifications)
-   ```bash
-   uvup clone source-env target-env
-   ```
-
-3. **New** - Create projects from templates (with modifications)
-   ```bash
-   uvup new myproject --template base-template --exclude pytest
-   ```
-
-4. **Sync** - Update current project from template (with modifications)
-   ```bash
-   uvup sync --template base-template --python 3.11
-   ```
-
-For complete command reference with all options and examples, see [COMMANDS.md](docs/COMMANDS.md).
-
-## Documentation
-
-### Quick Help
-
-Use the built-in help system for command-specific usage:
-
+### Package Management
 ```bash
-# General help
-uvup --help
-
-# Command-specific help
-uvup new --help
-uvup sync --help
-uvup clone --help
+# After activation, manage packages from anywhere
+uvup add requests numpy pandas
+uvup remove pandas
+uvup lock --upgrade
+uvup tree
 ```
 
-### Complete Documentation
-
-- **[COMMANDS.md](docs/COMMANDS.md)** - Complete command reference with all options and examples
-- **[USE_CASES.md](docs/USE_CASES.md)** - Real-world usage scenarios and workflows
-- **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes
-
-## Scope
-
-uvup focuses on **environment management and template-based workflows**. For package management, use uv directly:
+## Documentation
 
-```bash
-# Environment management with uvup
-uvup create myproject
-uvup activate myproject
+📖 **[Full Documentation](https://kercyding.github.io/uvup/)** - Complete user guide
 
-# Package management with uv
-uv add numpy pandas
-uv remove pandas
-uv lock
-uv sync
-```
+- [Installation](https://kercyding.github.io/uvup/installation.html) - Detailed setup instructions
+- [Quick Start](https://kercyding.github.io/uvup/quick-start.html) - Get started in minutes
+- [Command Reference](https://kercyding.github.io/uvup/commands/) - All commands with examples
+- [Use Cases](https://kercyding.github.io/uvup/use-cases/) - Real-world workflows
+- [Core Concepts](https://kercyding.github.io/uvup/core-concepts.html) - Design philosophy
 
 ## IDE Integration
 
-### VSCode
-
-Add to your `settings.json` to find your venv:
-
+**VSCode** - Add to your `settings.json`:
 ```json
 {
   "python.venvPath": "~/.uvup"
diff --git a/book.toml b/book.toml
new file mode 100644
index 0000000..0162e76
--- /dev/null
+++ b/book.toml
@@ -0,0 +1,28 @@
+[book]
+title = "uvup Documentation"
+authors = ["KercyDing"]
+language = "en"
+multilingual = false
+src = "book/src"
+description = "A conda-like environment manager for uv"
+
+[build]
+build-dir = "book/build"
+
+[output.html]
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/KercyDing/uvup"
+git-repository-icon = "fa-github"
+edit-url-template = "https://github.com/KercyDing/uvup/edit/main/{path}"
+
+[output.html.fold]
+enable = false
+
+[output.html.search]
+enable = true
+limit-results = 30
+use-boolean-and = true
+
+[output.html.print]
+enable = true
diff --git a/book/src/README.md b/book/src/README.md
new file mode 100644
index 0000000..26f4de5
--- /dev/null
+++ b/book/src/README.md
@@ -0,0 +1,50 @@
+# uvup
+
+A conda-like environment manager for [uv](https://github.com/astral-sh/uv).
+
+## What is uvup?
+
+uvup is a companion tool for uv that provides:
+
+- **Familiar Interface**: Conda-like commands (`create`, `activate`, `list`, etc.)
+- **Centralized Management**: All environments in `~/.uvup/`
+- **Template System**: Reusable project configurations
+- **Package Management**: Integrated `add`, `remove`, `lock`, `tree` commands
+- **Cross-Platform**: Works on Linux, macOS, and Windows
+
+## Quick Example
+
+```bash
+# Create and activate environment
+uvup create myproject
+uvup activate myproject
+
+# Add packages
+uvup add requests numpy pandas
+
+# Run your code
+python script.py
+
+# Deactivate
+uvup deactivate
+```
+
+## Core Philosophy
+
+- **Enhancement, not replacement**: Calls uv for actual work
+- **Familiar interface**: Conda-like commands, seamless activation
+- **Single binary**: Lightweight and cross-platform
+- **Template-driven**: Reusable project configurations
+
+## Why uvup?
+
+If you're familiar with **conda** but want to use **uv** for its speed and modern Python tooling, uvup bridges the gap by providing:
+
+1. **Global environment management** - Like conda's base environments
+2. **Simple activation** - `uvup activate` instead of manual PATH manipulation
+3. **Template-based workflows** - Share project configurations across teams
+4. **Integrated package commands** - Manage packages from anywhere after activation
+
+## Getting Started
+
+Continue to the [Installation](./installation.md) guide to get started!
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
new file mode 100644
index 0000000..5e4506a
--- /dev/null
+++ b/book/src/SUMMARY.md
@@ -0,0 +1,23 @@
+# Summary
+
+[Introduction](./README.md)
+
+# Getting Started
+
+- [Installation](./installation.md)
+- [Quick Start](./quick-start.md)
+- [Core Concepts](./core-concepts.md)
+
+# User Guide
+
+- [Command Reference](./commands/README.md)
+  - [Environment Management](./commands/environment.md)
+  - [Project Management](./commands/project.md)
+  - [Package Management](./commands/package.md)
+  - [System Commands](./commands/system.md)
+  - [Shell Commands](./commands/shell.md)
+- [Use Cases](./use-cases/README.md)
+  - [Getting Started](./use-cases/getting-started.md)
+  - [Development Workflows](./use-cases/development.md)
+  - [Team Collaboration](./use-cases/collaboration.md)
+  - [Advanced Patterns](./use-cases/advanced.md)
diff --git a/book/src/architecture.md b/book/src/architecture.md
new file mode 100644
index 0000000..c79bec1
--- /dev/null
+++ b/book/src/architecture.md
@@ -0,0 +1 @@
+# Architecture
diff --git a/book/src/changelog.md b/book/src/changelog.md
new file mode 100644
index 0000000..825c32f
--- /dev/null
+++ b/book/src/changelog.md
@@ -0,0 +1 @@
+# Changelog
diff --git a/book/src/commands/README.md b/book/src/commands/README.md
new file mode 100644
index 0000000..f3292a3
--- /dev/null
+++ b/book/src/commands/README.md
@@ -0,0 +1,70 @@
+# Command Reference
+
+Complete reference for all uvup commands.
+
+## Command Categories
+
+### Environment Management
+
+Basic CRUD operations for virtual environments:
+
+- [create](./environment.md#create) - Create new empty environment
+- [list](./environment.md#list) - List all environments
+- [delete](./environment.md#delete) - Delete an environment
+- [clone](./environment.md#clone) - Clone environment (1:1 copy)
+
+### Project Management
+
+Template-based project workflows:
+
+- [new](./project.md#new) - Create project from template
+- [sync](./project.md#sync) - Sync project with template
+
+### Package Management
+
+Manage packages in activated environments:
+
+- [add](./package.md#add) - Add packages
+- [remove](./package.md#remove) - Remove packages
+- [lock](./package.md#lock) - Update lockfile
+- [tree](./package.md#tree) - Display dependency tree
+
+### System
+
+System-level operations:
+
+- [init](./system.md#init) - Initialize shell integration
+- [update](./system.md#update) - Update uvup itself
+
+### Shell Commands
+
+Shell integration commands:
+
+- [activate](./shell.md#activate) - Activate environment
+- [deactivate](./shell.md#deactivate) - Deactivate environment
+
+## Command Decision Tree
+
+**Need to create something?**
+- Empty environment → `create`
+- Exact copy → `clone`
+- New project from template → `new`
+
+**Need to update?**
+- Current project from template → `sync`
+- uvup itself → `update`
+
+**Need to manage environments?**
+- See all environments → `list`
+- Delete environment → `delete`
+
+**Need to manage packages?** (requires activation)
+- Add packages → `add`
+- Remove packages → `remove`
+- Update lockfile → `lock`
+- View dependencies → `tree`
+
+**Need to use?**
+- Enable activation → `init`
+- Enter environment → `activate`
+- Exit environment → `deactivate`
diff --git a/book/src/commands/environment.md b/book/src/commands/environment.md
new file mode 100644
index 0000000..660efb9
--- /dev/null
+++ b/book/src/commands/environment.md
@@ -0,0 +1,135 @@
+# Environment Management
+
+Commands for creating, listing, and deleting virtual environments.
+
+## create
+
+Create a new empty virtual environment.
+
+### Usage
+
+```bash
+uvup create <name> [OPTIONS]
+```
+
+### Arguments
+
+- `<name>` - Name of the environment to create
+
+### Options
+
+- `-p, --python <version>` - Python version (default: 3.12)
+
+### Examples
+
+```bash
+# Create environment with default Python
+uvup create myproject
+
+# Create with specific Python version
+uvup create myproject --python 3.11
+uvup create --python 3.11 myproject
+```
+
+### Notes
+
+- Creates an empty pyproject.toml with minimal configuration
+- Initializes a virtual environment with uv
+- Environment is created in `~/.uvup/<name>/`
+
+---
+
+## list
+
+List all available environments.
+
+### Usage
+
+```bash
+uvup list
+```
+
+### Output
+
+- Lists all environments in `~/.uvup/`
+- Shows "No environments found." if empty
+
+### Examples
+
+```bash
+uvup list
+```
+
+---
+
+## delete
+
+Delete an existing environment.
+
+### Usage
+
+```bash
+uvup delete <name>
+```
+
+### Arguments
+
+- `<name>` - Name of the environment to delete
+
+### Examples
+
+```bash
+uvup delete myproject
+```
+
+### Notes
+
+- Permanently deletes the environment directory
+- Cannot be undone
+- Fails if environment doesn't exist
+- Only one environment can be deleted at a time
+
+---
+
+## clone
+
+Clone an existing environment to create an exact 1:1 copy.
+
+### Usage
+
+```bash
+uvup clone <source> <target>
+```
+
+### Arguments
+
+- `<source>` - Source environment name
+- `<target>` - Target environment name
+
+### Examples
+
+```bash
+# Create exact backup
+uvup clone myproject myproject-backup
+
+# Clone for testing
+uvup clone production testing
+```
+
+### What Gets Cloned
+
+- ✅ `pyproject.toml` - Project configuration
+- ✅ `hello.py` - Demo file (if exists)
+- ✅ `uv.lock` - Lock file (if exists)
+- ✅ Virtual environment - Fresh venv with same packages
+
+### What Doesn't Get Cloned
+
+- ❌ `.venv/` directory (recreated fresh)
+- ❌ Custom files (only standard files)
+
+### Notes
+
+- Pure 1:1 copy with **no modification options**
+- Use `new` if you need to modify during copy
+- Automatically syncs packages from lock file
diff --git a/book/src/commands/package.md b/book/src/commands/package.md
new file mode 100644
index 0000000..dda034f
--- /dev/null
+++ b/book/src/commands/package.md
@@ -0,0 +1,156 @@
+# Package Management
+
+Manage packages in activated environments. All commands require an activated environment and use `uv --project` internally, allowing you to manage packages from any directory.
+
+## add
+
+Add packages to the active environment.
+
+### Usage
+
+```bash
+uvup add <packages...> [OPTIONS]
+```
+
+### Arguments
+
+- `<packages...>` - One or more packages to add
+
+### Options
+
+- `--group <name>` - Add to optional dependency group
+
+### Examples
+
+```bash
+# Activate environment first
+uvup activate myproject
+
+# Add packages
+uvup add requests numpy pandas
+
+# Add with version specifiers
+uvup add "requests>=2.28.0" "numpy<2.0"
+
+# Add to development group
+uvup add --group dev pytest black mypy
+```
+
+### Notes
+
+- Requires an activated environment
+- Updates `pyproject.toml` and `uv.lock`
+- Installs packages immediately
+- Works from any directory (not just project root)
+
+---
+
+## remove
+
+Remove packages from the active environment.
+
+### Usage
+
+```bash
+uvup remove <packages...> [OPTIONS]
+```
+
+### Arguments
+
+- `<packages...>` - One or more packages to remove
+
+### Options
+
+- `--group <name>` - Remove from optional dependency group
+
+### Examples
+
+```bash
+# Activate environment first
+uvup activate myproject
+
+# Remove packages
+uvup remove requests numpy
+
+# Remove from development group
+uvup remove --group dev pytest
+```
+
+### Notes
+
+- Requires an activated environment
+- Updates `pyproject.toml` and `uv.lock`
+- Uninstalls packages immediately
+- Works from any directory (not just project root)
+
+---
+
+## lock
+
+Update the lockfile of the active environment.
+
+### Usage
+
+```bash
+uvup lock [OPTIONS]
+```
+
+### Options
+
+- `--upgrade` - Upgrade all packages to their latest compatible versions
+
+### Examples
+
+```bash
+# Activate environment first
+uvup activate myproject
+
+# Update lock file
+uvup lock
+
+# Upgrade all packages
+uvup lock --upgrade
+```
+
+### Notes
+
+- Requires an activated environment
+- Updates `uv.lock` based on `pyproject.toml`
+- Does not install packages (use `uv sync` to install)
+- Works from any directory (not just project root)
+
+---
+
+## tree
+
+Display the dependency tree of the active environment.
+
+### Usage
+
+```bash
+uvup tree [OPTIONS]
+```
+
+### Options
+
+- `--depth <n>` - Maximum depth to display
+
+### Examples
+
+```bash
+# Activate environment first
+uvup activate myproject
+
+# Show full dependency tree
+uvup tree
+
+# Limit depth
+uvup tree --depth 2
+```
+
+### Notes
+
+- Requires an activated environment
+- Shows hierarchical view of dependencies
+- Helps identify dependency conflicts
+- Works from any directory (not just project root)
diff --git a/book/src/commands/project.md b/book/src/commands/project.md
new file mode 100644
index 0000000..bc547fd
--- /dev/null
+++ b/book/src/commands/project.md
@@ -0,0 +1,184 @@
+# Project Management
+
+Template-based project creation and synchronization.
+
+## new
+
+Create a new project from a template environment with modification support.
+
+### Usage
+
+```bash
+uvup new <name> --template <template> [OPTIONS]
+```
+
+### Arguments
+
+- `<name>` - Project name
+- `--template <template>` - Template environment name
+
+### Options
+
+- `-p, --python <version>` - Override Python version
+- `--exclude <packages>` - Exclude packages (comma-separated)
+- `--include <packages>` - Include only these packages (comma-separated)
+- `--path <directory>` - Create in custom directory (default: current dir)
+- `--dry-run` - Preview changes without creating
+
+### Examples
+
+```bash
+# Basic project creation
+uvup new myapp --template web-template
+
+# Custom Python version
+uvup new myapp --template web-template --python 3.11
+
+# Exclude development tools
+uvup new myapp --template web-template --exclude pytest,black,mypy
+
+# Include only specific packages
+uvup new myapp --template web-template --include numpy,pandas,requests
+
+# Create in specific directory
+uvup new myapp --template web-template --path ~/projects
+
+# Preview without creating
+uvup new myapp --template web-template --exclude pytest --dry-run
+```
+
+### Modification Behavior
+
+1. **Project Name**: Automatically updated in pyproject.toml
+2. **Python Version**: Overridden if `--python` specified
+3. **Dependencies**: Filtered by `--exclude` or `--include`
+4. **Optional Dependencies**: Also filtered, empty groups removed
+
+### Filtering Rules
+
+- `--exclude`: Removes specified packages from both main and optional dependencies
+- `--include`: Keeps ONLY specified packages (removes all others)
+- Cannot use both `--exclude` and `--include` together
+- Package names are case-insensitive
+- Handles PEP 508 specifiers (e.g., `requests[http3]>=2.0`)
+
+### Dry-run Output
+
+```
+-- Dry Run Mode --
+
+Template: 'web-template' (Python 3.12)
+Project:  'myapp' (Python 3.11)
+Location: /Users/you/myapp
+
+Python version change:
+  3.12 → 3.11
+
+Filters applied:
+  Exclude: pytest, black
+
+Dependency changes:
+  Removed (2):
+    - pytest>=7.0.0
+    - black>=23.0.0
+  Kept (5):
+
+Optional dependencies:
+  [dev]: Removed (group is empty after filtering)
+  [viz]: No changes
+
+To create this project, run the same command without --dry-run
+```
+
+### Notes
+
+- Creates project in `<path>/<name>/` (default: `./<name>/`)
+- Fails if target directory already exists
+- Automatically runs `uv lock` and `uv sync`
+- Project is ready to use immediately
+
+---
+
+## sync
+
+Sync current project with a template environment.
+
+### Usage
+
+```bash
+uvup sync --template <template> [OPTIONS]
+```
+
+### Arguments
+
+- `--template <template>` - Template environment name
+
+### Options
+
+- `-p, --python <version>` - Override Python version
+- `--exclude <packages>` - Exclude packages (comma-separated)
+- `--include <packages>` - Include only these packages (comma-separated)
+- `--dry-run` - Preview changes without syncing
+
+### Examples
+
+```bash
+# Sync with template
+cd myproject
+uvup sync --template web-template
+
+# Sync with Python version change
+uvup sync --template web-template --python 3.11
+
+# Sync without dev dependencies
+uvup sync --template web-template --exclude pytest,black,mypy
+
+# Sync only core packages
+uvup sync --template web-template --include numpy,pandas,requests
+
+# Preview changes
+uvup sync --template web-template --dry-run
+```
+
+### Sync Behavior
+
+1. **Dependencies**: Replaced with template's dependencies (filtered)
+2. **Optional Dependencies**: Replaced with template's optional-dependencies (filtered)
+3. **Python Version**: Updated if `--python` specified
+4. **Project Name**: Preserved (NOT changed)
+
+### Safety Features
+
+- ✅ Automatic backup: `pyproject.toml.backup` created before changes
+- ✅ Rollback on error: Backup restored if `uv lock` or `uv sync` fails
+- ✅ Backup cleanup: Removed on successful completion
+
+### Dry-run Output
+
+```
+-- Dry Run Mode --
+
+Template: 'web-template' (Python 3.12)
+Current:  /Users/you/myproject (Python 3.12)
+
+Dependency changes:
+  Added (2):
+    + fastapi>=0.100.0
+    + uvicorn>=0.23.0
+  Removed (1):
+    - flask>=2.3.0
+  Kept (3):
+
+Optional dependencies:
+  [dev]: Modified (5 packages)
+  [viz]: No changes
+
+To sync this project, run the same command without --dry-run
+```
+
+### Notes
+
+- Must be run from project directory containing `pyproject.toml`
+- Fails if no `pyproject.toml` found
+- Changes take effect immediately (except in dry-run mode)
+- Backup file is left if user interrupts (Ctrl+C)
diff --git a/book/src/commands/shell.md b/book/src/commands/shell.md
new file mode 100644
index 0000000..4fee448
--- /dev/null
+++ b/book/src/commands/shell.md
@@ -0,0 +1,87 @@
+# Shell Commands
+
+Shell integration commands available after running `uvup init`.
+
+## activate
+
+Activate a virtual environment.
+
+### Usage
+
+```bash
+uvup activate <name>
+```
+
+### Arguments
+
+- `<name>` - Environment name to activate
+
+### Examples
+
+```bash
+uvup activate myproject
+```
+
+### What It Does
+
+1. Checks if the environment exists
+2. Activates the `.venv` within the environment
+3. Sets `UVUP_ACTIVE_ENV` environment variable
+4. Modifies shell prompt to show environment name
+5. Enables package management commands
+
+### Effects
+
+After activation:
+
+- Shell prompt shows `(myproject)`
+- `python` points to environment's Python
+- `pip` and other tools use environment's packages
+- Package commands (`add`, `remove`, `lock`, `tree`) are enabled
+- Works from any directory
+
+### Notes
+
+- Requires `uvup init` to be set up first
+- Only one environment can be active at a time
+- Activating a new environment automatically deactivates the current one
+
+---
+
+## deactivate
+
+Deactivate the current virtual environment.
+
+### Usage
+
+```bash
+uvup deactivate
+```
+
+### Examples
+
+```bash
+uvup deactivate
+```
+
+### What It Does
+
+1. Deactivates the current virtual environment
+2. Clears `UVUP_ACTIVE_ENV` environment variable
+3. Restores original shell prompt
+4. Restores original PATH
+5. Disables package management commands
+
+### Effects
+
+After deactivation:
+
+- Shell prompt returns to normal
+- `python` points to system Python
+- Package commands will fail with "No active environment" error
+
+### Notes
+
+- Requires `uvup init` to be set up first
+- Safe to run even if no environment is active
+- Does not delete or modify the environment
diff --git a/book/src/commands/system.md b/book/src/commands/system.md
new file mode 100644
index 0000000..ff2b05a
--- /dev/null
+++ b/book/src/commands/system.md
@@ -0,0 +1,101 @@
+# System Commands
+
+System-level operations for uvup.
+
+## init
+
+Initialize shell integration for uvup.
+
+### Usage
+
+```bash
+uvup init
+```
+
+### Supported Shells
+
+- Bash
+- Zsh
+- Fish
+- PowerShell
+
+### What It Does
+
+- Detects your current shell
+- Outputs shell integration script
+- Enables `uvup activate` and `uvup deactivate` commands
+
+### Examples
+
+```bash
+# Add to your shell config file
+eval "$(uvup init)"
+```
+
+### Shell Config Files
+
+Add the above line to your shell's configuration file:
+
+- **Bash**: `~/.bashrc` or `~/.bash_profile`
+- **Zsh**: `~/.zshrc`
+- **Fish**: `~/.config/fish/config.fish`
+- **PowerShell**: `$PROFILE`
+
+Then reload your shell:
+
+```bash
+# Bash/Zsh
+source ~/.bashrc  # or ~/.zshrc
+
+# Fish
+source ~/.config/fish/config.fish
+
+# PowerShell
+. $PROFILE
+```
+
+### Notes
+
+- Run this once after installation
+- Restart shell or source config file to apply
+- Safe to run multiple times (idempotent)
+
+---
+
+## update
+
+Update uvup to the latest version.
+
+### Usage
+
+```bash
+uvup update [OPTIONS]
+```
+
+### Options
+
+- `-c, --check` - Only check for updates without installing
+
+### Examples
+
+```bash
+# Update to latest version
+uvup update
+
+# Check if update available
+uvup update --check
+```
+
+### What It Does
+
+1. Checks GitHub releases for the latest version
+2. Downloads the appropriate binary for your platform
+3. Replaces the current binary in-place
+4. Verifies the update was successful
+
+### Notes
+
+- Downloads latest release from GitHub
+- Replaces current binary in-place
+- Preserves all environments and configuration
+- Requires internet connection
diff --git a/book/src/contributing/development.md b/book/src/contributing/development.md
new file mode 100644
index 0000000..79a9975
--- /dev/null
+++ b/book/src/contributing/development.md
@@ -0,0 +1 @@
+# Development Guide
diff --git a/book/src/contributing/guidelines.md b/book/src/contributing/guidelines.md
new file mode 100644
index 0000000..64dcef7
--- /dev/null
+++ b/book/src/contributing/guidelines.md
@@ -0,0 +1 @@
+# Code Guidelines
diff --git a/book/src/core-concepts.md b/book/src/core-concepts.md
new file mode 100644
index 0000000..b26b437
--- /dev/null
+++ b/book/src/core-concepts.md
@@ -0,0 +1,333 @@
+# Core Concepts
+
+Understanding uvup's design philosophy and architecture.
+
+## Design Philosophy
+
+### Enhancement, Not Replacement
+
+uvup doesn't replace uv - it enhances it:
+
+```bash
+# uvup calls uv internally
+uvup create myenv    # -> uv venv ~/.uvup/myenv/.venv
+uvup add requests    # -> uv --project ~/.uvup/myenv add requests
+```
+
+**Why?** Because uv is already excellent at virtual environment and package management. uvup provides:
+- Centralized environment storage
+- Conda-like activation workflow
+- Template-based project creation
+
+### Familiar Interface
+
+If you're coming from conda, uvup feels natural:
+
+```bash
+# conda workflow
+conda create -n myenv python=3.11
+conda activate myenv
+conda install numpy pandas
+
+# uvup workflow
+uvup create myenv --python 3.11
+uvup activate myenv
+uvup add numpy pandas
+```
+
+### Single Binary
+
+uvup is distributed as a single executable:
+- No runtime dependencies (except uv)
+- Cross-platform support (Linux, macOS, Windows)
+- Easy installation and updates
+
+### Template-Driven
+
+Create reusable project configurations:
+
+```bash
+# Create a template environment
+uvup create web-template
+uvup activate web-template
+uvup add fastapi uvicorn sqlalchemy pydantic
+
+# Use it to create new projects
+uvup new myapp --template web-template
+uvup new another-app --template web-template
+```
+
+## Architecture
+
+### Directory Structure
+
+```
+~/.uvup/
+├── bin/
+│   └── uvup              # The uvup binary
+└── <env-name>/
+    ├── .venv/            # Python virtual environment
+    ├── pyproject.toml    # Project dependencies
+    └── uv.lock           # Lock file
+```
+
+### Environment Activation
+
+When you run `uvup activate myenv`:
+
+1. Shell function checks if environment exists
+2. Activates `.venv/bin/activate` (or Windows equivalent)
+3. Sets `UVUP_ACTIVE_ENV=myenv` environment variable
+4. Modifies shell prompt to show `(myenv)`
+
+The `UVUP_ACTIVE_ENV` variable enables location-independent package management.
+
+### Package Management Flow
+
+```bash
+$ uvup activate myenv
+$ uvup add requests
+```
+
+Internally, uvup:
+
+1. Reads `UVUP_ACTIVE_ENV` → gets `myenv`
+2. Resolves path → `~/.uvup/myenv`
+3. Executes: `uv --project ~/.uvup/myenv add requests`
+
+This works from any directory because of the `--project` flag.
+
+## Command Categories
+
+uvup provides four distinct workflows:
+
+### 1. Environment Management
+
+Basic CRUD operations for environments:
+
+```bash
+uvup create myenv       # Create empty environment
+uvup list               # List all environments
+uvup delete myenv       # Delete environment
+```
+
+### 2. Environment Cloning
+
+Create exact 1:1 copies:
+
+```bash
+uvup clone source target
+```
+
+Copies:
+- Python version
+- All dependencies (from `pyproject.toml`)
+- Lock file (`uv.lock`)
+- Virtual environment
+
+Use cases:
+- Backup before experiments
+- Create identical environments for testing
+
+### 3. Project Creation from Templates
+
+Create new projects with modifications:
+
+```bash
+uvup new myapp --template web-template \
+  --python 3.11 \
+  --exclude pytest \
+  --dry-run
+```
+
+Features:
+- Python version override
+- Package filtering (include/exclude)
+- Custom target directory
+- Dry-run preview
+
+### 4. Project Synchronization
+
+Update existing projects from templates:
+
+```bash
+cd myproject
+uvup sync --template web-template \
+  --python 3.11 \
+  --dry-run
+```
+
+Features:
+- Automatic backup before sync
+- Rollback on failure
+- Same modification options as `new`
+
+## Dependency Management
+
+### pyproject.toml-based
+
+uvup uses modern Python packaging standards:
+
+```toml
+[project]
+name = "myproject"
+version = "0.1.0"
+dependencies = [
+    "numpy>=1.24.0",
+    "pandas>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "black>=23.0.0",
+]
+```
+
+### Lock File
+
+`uv.lock` ensures reproducible installs across machines.
+
+### Optional Dependencies
+
+Support for development, testing, and documentation dependencies:
+
+```bash
+# Add to main dependencies
+uvup add requests
+
+# Add to dev dependencies
+uvup add --group dev pytest
+
+# Add to docs dependencies
+uvup add --group docs sphinx
+```
+
+## Shell Integration
+
+uvup integrates deeply with your shell:
+
+### Activation Function
+
+The `uvup init` command generates a shell function that handles:
+- Environment activation
+- Deactivation
+- Environment variable management
+- Prompt modification
+
+### Supported Shells
+
+- **Bash** - Linux, macOS, Windows (Git Bash)
+- **Zsh** - macOS, Linux
+- **Fish** - Linux, macOS
+- **PowerShell** - Windows
+
+## Comparison with Other Tools
+
+### vs conda
+
+**Similarities:**
+- Centralized environment management
+- Activate/deactivate workflow
+- List/remove commands
+
+**Differences:**
+- uvup uses uv (faster)
+- uvup is Python-only
+- uvup uses pyproject.toml instead of environment.yml
+- uvup has template-based project creation
+
+### vs virtualenv/venv
+
+**Advantages of uvup:**
+- Centralized storage (not per-project)
+- Conda-like commands
+- Template system
+- Integrated package management after activation
+
+**When to use venv:**
+- Simple single-project needs
+- No template requirements
+- Prefer per-project .venv directories
+
+### vs uv directly
+
+**What uvup adds:**
+- Centralized environment storage
+- Shell activation integration
+- Template-based workflows
+- Conda-like command interface
+
+**When to use uv directly:**
+- Per-project workflows
+- CI/CD pipelines
+- No need for activation
+
+## Best Practices
+
+### Environment Naming
+
+Use descriptive names:
+
+```bash
+# Good
+uvup create data-analysis
+uvup create web-backend
+uvup create ml-training
+
+# Avoid
+uvup create env1
+uvup create test
+uvup create tmp
+```
+
+### Template Organization
+
+Create templates for common project types:
+
+```bash
+# Base Python
+uvup create base-template
+uvup activate base-template
+uvup add pip setuptools wheel
+
+# Web development
+uvup create web-template
+uvup activate web-template
+uvup add fastapi uvicorn sqlalchemy
+
+# Data science
+uvup create ds-template
+uvup activate ds-template
+uvup add numpy pandas matplotlib jupyter
+```
+
+### Dependency Groups
+
+Use optional dependencies for different purposes:
+
+```bash
+# Core dependencies
+uvup add requests pydantic
+
+# Development tools
+uvup add --group dev pytest black mypy ruff
+
+# Documentation
+uvup add --group docs sphinx sphinx-rtd-theme
+```
+
+### Regular Updates
+
+Keep your environments up to date:
+
+```bash
+uvup activate myenv
+uvup lock --upgrade
+```
+
+## Next Steps
+
+- [Installation](./installation.md) - Install uvup
+- [Quick Start](./quick-start.md) - Get started with uvup
+- [Commands Reference](./commands/README.md) - Detailed command documentation
diff --git a/book/src/installation.md b/book/src/installation.md
new file mode 100644
index 0000000..6a11b29
--- /dev/null
+++ b/book/src/installation.md
@@ -0,0 +1,100 @@
+# Installation
+
+## Quick Install
+
+### Linux and macOS
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.sh | sh
+```
+
+### Windows (PowerShell)
+
+```powershell
+Invoke-RestMethod https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.ps1 | Invoke-Expression
+```
+
+## What the Installer Does
+
+The installation script will:
+
+1. Download the latest uvup binary for your platform
+2. Install it to `~/.uvup/bin/uvup`
+3. Add `~/.uvup/bin` to your PATH
+4. Initialize shell integration
+
+## Shell Integration
+
+After installation, you need to initialize shell integration:
+
+```bash
+# Add this to your shell config file
+eval "$(uvup init)"
+```
+
+### Shell Config Files
+
+Add the above line to your shell's configuration file:
+
+- **Bash**: `~/.bashrc` or `~/.bash_profile`
+- **Zsh**: `~/.zshrc`
+- **Fish**: `~/.config/fish/config.fish`
+- **PowerShell**: `$PROFILE`
+
+Then reload your shell:
+
+```bash
+# Bash/Zsh
+source ~/.bashrc  # or ~/.zshrc
+
+# Fish
+source ~/.config/fish/config.fish
+
+# PowerShell
+. $PROFILE
+```
+
+## Verify Installation
+
+Check that uvup is installed correctly:
+
+```bash
+uvup --version
+```
+
+## Prerequisites
+
+uvup requires [uv](https://github.com/astral-sh/uv) to be installed:
+
+```bash
+# Install uv if you haven't already
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+## Manual Installation
+
+If you prefer to install manually:
+
+1. Download the binary for your platform from [GitHub Releases](https://github.com/KercyDing/uvup/releases)
+2. Extract the binary to a directory in your PATH
+3. Make it executable: `chmod +x uvup` (Linux/macOS)
+4. Add shell integration to your shell config file
+
+## Developer Setup
+
+For development builds from source:
+
+```bash
+# Clone the repository
+git clone https://github.com/KercyDing/uvup.git
+cd uvup
+
+# Build the project
+cargo build --release
+
+# The binary will be at target/release/uvup
+```
+
+## Next Steps
+
+Continue to [Quick Start](./quick-start.md) to start using uvup!
diff --git a/book/src/quick-start.md b/book/src/quick-start.md
new file mode 100644
index 0000000..e25a53a
--- /dev/null
+++ b/book/src/quick-start.md
@@ -0,0 +1,180 @@
+# Quick Start
+
+This guide will walk you through creating your first uvup environment and managing packages.
+
+## Basic Workflow
+
+### 1. Create an Environment
+
+```bash
+# Create a new environment
+uvup create myproject
+
+# Or with a specific Python version
+uvup create myproject --python 3.12
+```
+
+This creates a new virtual environment at `~/.uvup/myproject` with:
+- A `.venv` directory containing the Python virtual environment
+- A `pyproject.toml` file for dependency management
+- A `uv.lock` file for reproducible installs
+
+### 2. List Environments
+
+```bash
+uvup list
+```
+
+This shows all your created environments.
+
+### 3. Activate an Environment
+
+```bash
+uvup activate myproject
+```
+
+After activation:
+- Your shell prompt shows `(myproject)`
+- Python points to the environment's Python
+- You can use uvup package management commands
+
+### 4. Add Packages
+
+```bash
+# Add packages to your environment
+uvup add numpy pandas requests
+
+# Add development dependencies
+uvup add --group dev pytest black mypy
+```
+
+The packages are added to `pyproject.toml` and installed automatically.
+
+### 5. Work with Your Code
+
+```bash
+# Run Python scripts
+python script.py
+
+# Use installed tools
+pytest tests/
+jupyter notebook
+```
+
+### 6. Manage Dependencies
+
+```bash
+# Update the lockfile
+uvup lock
+
+# Upgrade all packages
+uvup lock --upgrade
+
+# View dependency tree
+uvup tree
+
+# View with depth limit
+uvup tree --depth 2
+```
+
+### 7. Remove Packages
+
+```bash
+# Remove a package
+uvup remove pandas
+
+# Remove from a specific group
+uvup remove --group dev pytest
+```
+
+### 8. Deactivate
+
+```bash
+uvup deactivate
+```
+
+This returns your shell to its original state.
+
+### 9. Delete an Environment
+
+```bash
+uvup delete myproject
+```
+
+This permanently removes the environment directory.
+
+## Example Session
+
+Here's a complete example workflow:
+
+```bash
+# Create a data science environment
+$ uvup create data-analysis --python 3.11
+Environment 'data-analysis' created successfully
+
+# List environments
+$ uvup list
+Available environments:
+  data-analysis
+
+# Activate it
+$ uvup activate data-analysis
+(data-analysis) $
+
+# Add packages
+(data-analysis) $ uvup add numpy pandas matplotlib jupyter
+Added: numpy, pandas, matplotlib, jupyter
+
+# Run your analysis
+(data-analysis) $ python analyze.py
+
+# Add development tools
+(data-analysis) $ uvup add --group dev pytest black
+Added to dev: pytest, black
+
+# Deactivate when done
+(data-analysis) $ uvup deactivate
+$
+
+# Clean up
+$ uvup delete data-analysis
+Environment 'data-analysis' removed successfully
+```
+
+## Key Concepts
+
+### Centralized Management
+
+All environments are stored in `~/.uvup/`, not scattered across project directories.
+
+### Activation Required for Package Management
+
+Package commands (`add`, `remove`, `lock`, `tree`) require an activated environment:
+
+```bash
+# This works
+$ uvup activate myproject
+(myproject) $ uvup add requests
+
+# This fails
+$ uvup add requests
+Error: No active environment
+```
+
+### Location Independence
+
+After activation, you can use uvup package commands from any directory:
+
+```bash
+$ uvup activate myproject
+(myproject) $ cd ~/work/some-other-project
+(myproject) $ uvup add numpy  # Still works!
+```
+
+This is powered by `uv --project <path>` internally.
+
+## Next Steps
+
+- [Core Concepts](./core-concepts.md) - Understand uvup's design philosophy
+- [Commands Reference](./commands/README.md) - Complete command documentation
+- [Use Cases](./use-cases/README.md) - Real-world usage scenarios
diff --git a/book/src/roadmap.md b/book/src/roadmap.md
new file mode 100644
index 0000000..437766d
--- /dev/null
+++ b/book/src/roadmap.md
@@ -0,0 +1 @@
+# Roadmap
diff --git a/book/src/use-cases/README.md b/book/src/use-cases/README.md
new file mode 100644
index 0000000..1db025a
--- /dev/null
+++ b/book/src/use-cases/README.md
@@ -0,0 +1,40 @@
+# Use Cases
+
+Real-world scenarios and workflows with uvup.
+
+## Categories
+
+### [Getting Started](./getting-started.md)
+
+First steps with uvup:
+- Initial setup and configuration
+- Creating your first environment
+- Quick project creation
+
+### [Development Workflows](./development.md)
+
+Daily development patterns:
+- Creating template environments
+- Starting new projects from templates
+- Syncing existing projects
+- Managing multiple projects
+- Experimenting safely
+- Upgrading dependencies
+
+### [Team Collaboration](./collaboration.md)
+
+Working with teams:
+- Sharing environment definitions
+- Onboarding new developers
+- Consistent development environments
+
+### [Advanced Patterns](./advanced.md)
+
+Complex workflows:
+- Multi-stage project setup
+- Microservices development
+- Educational environments
+- CI/CD integration
+- Dependency isolation testing
+- Backup strategies
+- Environment maintenance
diff --git a/book/src/use-cases/advanced.md b/book/src/use-cases/advanced.md
new file mode 100644
index 0000000..bf92529
--- /dev/null
+++ b/book/src/use-cases/advanced.md
@@ -0,0 +1,331 @@
+# Advanced Patterns
+
+Complex workflows and advanced usage scenarios.
+
+## Multi-Stage Project Setup
+
+**Scenario**: Different dependency sets for dev/test/prod.
+
+```bash
+# Base template with core dependencies
+uvup create base-template
+uvup activate base-template
+uvup add fastapi uvicorn pydantic sqlalchemy
+uvup deactivate
+
+# Development environment (full stack)
+uvup new my-project-dev --template base-template
+cd my-project-dev
+uvup activate my-project-dev
+uvup add --group dev pytest black mypy ruff ipython
+uvup add --group dev pytest-cov pytest-asyncio
+uvup deactivate
+
+# Testing environment (dev + test tools only)
+uvup new my-project-test --template base-template
+cd ../my-project-test
+uvup activate my-project-test
+uvup add --group dev pytest pytest-cov pytest-asyncio
+uvup deactivate
+
+# Production environment (minimal)
+uvup new my-project-prod --template base-template \
+  --exclude pytest,black,mypy,ruff,ipython
+```
+
+## Microservices Development
+
+**Scenario**: Multiple services with shared base, different extras.
+
+```bash
+# Create shared base template
+uvup create microservice-base
+uvup activate microservice-base
+uvup add fastapi uvicorn pydantic httpx
+uvup add --group dev pytest pytest-asyncio
+uvup deactivate
+
+# Create service-specific projects
+uvup new auth-service --template microservice-base
+cd auth-service
+uvup activate auth-service
+uvup add pyjwt passlib python-multipart
+uvup deactivate
+
+uvup new user-service --template microservice-base
+cd ../user-service
+uvup activate user-service
+uvup add sqlalchemy asyncpg alembic
+uvup deactivate
+
+uvup new notification-service --template microservice-base
+cd ../notification-service
+uvup activate notification-service
+uvup add aiosmtplib jinja2 celery
+uvup deactivate
+```
+
+## Educational Environments
+
+**Scenario**: Teaching Python with consistent student environments.
+
+```bash
+# Instructor creates course template
+uvup create course-python-basics
+uvup activate course-python-basics
+uvup add ipython jupyter notebook pytest
+uvup deactivate
+
+# Students clone for each module
+uvup new module-01-basics --template course-python-basics
+uvup new module-02-functions --template course-python-basics
+uvup new module-03-classes --template course-python-basics
+
+# Each module can have specific packages
+cd module-02-functions
+uvup activate module-02-functions
+uvup add hypothesis  # for property-based testing
+uvup deactivate
+
+cd ../module-03-classes
+uvup activate module-03-classes
+uvup add attrs pydantic  # for class examples
+uvup deactivate
+```
+
+## CI/CD Integration
+
+### Docker Integration
+
+```dockerfile
+FROM python:3.12-slim
+
+# Install uv
+RUN pip install uv
+
+# Copy project
+COPY . /app
+WORKDIR /app
+
+# Install dependencies from pyproject.toml
+RUN uv sync
+
+# Run tests
+CMD ["uv", "run", "pytest"]
+```
+
+### GitHub Actions
+
+```yaml
+name: Test
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+      
+      - name: Install uv
+        run: pip install uv
+      
+      - name: Install dependencies
+        run: uv sync
+      
+      - name: Run tests
+        run: uv run pytest
+```
+
+## Dependency Isolation Testing
+
+**Scenario**: Test with different dependency versions.
+
+```bash
+# Base template
+uvup create app-template
+uvup activate app-template
+uvup add requests flask numpy
+uvup deactivate
+
+# Test with minimum versions
+uvup new app-min-versions --template app-template
+cd app-min-versions
+# Edit pyproject.toml to set minimum versions
+uvup activate app-min-versions
+uvup lock
+uv sync
+uv run pytest
+uvup deactivate
+
+# Test with latest versions
+uvup new app-latest-versions --template app-template
+cd ../app-latest-versions
+uvup activate app-latest-versions
+uvup lock --upgrade
+uv sync
+uv run pytest
+uvup deactivate
+```
+
+## Backup Strategies
+
+### Automated Backup Script
+
+```bash
+#!/bin/bash
+# backup-environments.sh
+
+BACKUP_DIR=~/uvup-backups/$(date +%Y%m%d)
+mkdir -p "$BACKUP_DIR"
+
+# Backup all pyproject.toml files
+for env in ~/.uvup/*/; do
+  name=$(basename "$env")
+  if [ -f "$env/pyproject.toml" ]; then
+    cp "$env/pyproject.toml" "$BACKUP_DIR/$name.toml"
+    echo "Backed up $name"
+  fi
+done
+
+echo "Backups saved to $BACKUP_DIR"
+```
+
+### Restore from Backup
+
+```bash
+#!/bin/bash
+# restore-environment.sh
+
+if [ -z "$1" ] || [ -z "$2" ]; then
+  echo "Usage: $0 <backup-file> <env-name>"
+  exit 1
+fi
+
+BACKUP_FILE="$1"
+ENV_NAME="$2"
+
+# Create environment if it doesn't exist
+if ! uvup list | grep -q "$ENV_NAME"; then
+  uvup create "$ENV_NAME"
+fi
+
+# Restore pyproject.toml
+cp "$BACKUP_FILE" ~/.uvup/$ENV_NAME/pyproject.toml
+
+# Sync dependencies
+cd ~/.uvup/$ENV_NAME
+uv lock
+uv sync
+
+echo "Restored $ENV_NAME from $BACKUP_FILE"
+```
+
+## Environment Maintenance
+
+### Monthly Maintenance Script
+
+```bash
+#!/bin/bash
+# monthly-maintenance.sh
+
+# Update uvup itself
+echo "Updating uvup..."
+uvup update
+
+# List all environments
+echo "Current environments:"
+uvup list
+
+# Update templates with latest packages
+for template in web-template ds-template cli-template; do
+  if uvup list | grep -q "$template"; then
+    echo "Updating $template..."
+    uvup activate $template
+    uvup lock --upgrade
+    uv sync
+    # Run tests if they exist
+    if [ -d "tests" ]; then
+      uv run pytest || echo "Tests failed for $template"
+    fi
+    uvup deactivate
+  fi
+done
+
+echo "Maintenance complete!"
+```
+
+### Cleanup Old Environments
+
+```bash
+#!/bin/bash
+# cleanup-old-environments.sh
+
+# List all environments with modification time
+for env in ~/.uvup/*/; do
+  name=$(basename "$env")
+  
+  # Skip if it's a template
+  if [[ $name == *"-template" ]]; then
+    continue
+  fi
+  
+  # Check if older than 30 days
+  if [ -n "$(find "$env" -maxdepth 0 -mtime +30)" ]; then
+    echo "Old environment: $name (>30 days)"
+    read -p "Remove? (y/n) " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+      uvup delete "$name"
+      echo "Removed $name"
+    fi
+  fi
+done
+```
+
+## Performance Optimization
+
+### Parallel Environment Creation
+
+```bash
+#!/bin/bash
+# create-environments-parallel.sh
+
+# Array of environments to create
+envs=("project-a" "project-b" "project-c" "project-d")
+template="base-template"
+
+# Create environments in parallel
+for env in "${envs[@]}"; do
+  (
+    uvup new "$env" --template "$template"
+    echo "Created $env"
+  ) &
+done
+
+# Wait for all background jobs
+wait
+echo "All environments created!"
+```
+
+### Shared Cache
+
+Leverage uv's cache for faster installs:
+
+```bash
+# uv automatically caches packages
+# Multiple environments share the same cache
+
+# First environment (downloads packages)
+uvup create env1
+uvup activate env1
+uvup add numpy pandas  # Downloads and caches
+
+# Second environment (uses cache)
+uvup create env2
+uvup activate env2
+uvup add numpy pandas  # Much faster!
+```
diff --git a/book/src/use-cases/collaboration.md b/book/src/use-cases/collaboration.md
new file mode 100644
index 0000000..f400522
--- /dev/null
+++ b/book/src/use-cases/collaboration.md
@@ -0,0 +1,255 @@
+# Team Collaboration
+
+Working with teams using uvup.
+
+## Sharing Environment Definitions
+
+**Scenario**: Team wants consistent development environments.
+
+### Creating a Team Template
+
+```bash
+# Team lead creates template
+uvup create team-base-template --python 3.11
+uvup activate team-base-template
+uvup add requests httpx pydantic sqlalchemy
+uvup add --group dev pytest black mypy ruff pre-commit
+uvup add --group docs sphinx sphinx-rtd-theme
+uvup deactivate
+
+# Team lead shares the pyproject.toml
+cp ~/.uvup/team-base-template/pyproject.toml ./templates/team-base.toml
+git add templates/team-base.toml
+git commit -m "Add team base template"
+git push
+```
+
+### Team Members Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/company/project
+cd project
+
+# Create template from shared config
+uvup create team-base-template
+cp ./templates/team-base.toml ~/.uvup/team-base-template/pyproject.toml
+cd ~/.uvup/team-base-template
+uv lock
+uv sync
+cd -
+
+# Now create projects from template
+uvup new my-feature --template team-base-template
+```
+
+## Onboarding New Developers
+
+### Automated Onboarding Script
+
+```bash
+#!/bin/bash
+# onboard.sh - Run this to set up new developer
+
+echo "Installing uvup..."
+curl -fsSL https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.sh | sh
+
+echo "Initializing shell..."
+uvup init
+source ~/.bashrc  # or ~/.zshrc
+
+echo "Creating templates..."
+for template in backend frontend ml; do
+  uvup create ${template}-template
+  cp templates/${template}.toml ~/.uvup/${template}-template/pyproject.toml
+  cd ~/.uvup/${template}-template && uv sync && cd -
+done
+
+echo "Done! Available templates:"
+uvup list
+```
+
+### Documentation for New Team Members
+
+Create a SETUP.md in your repository:
+
+```markdown
+# Development Setup
+
+## Prerequisites
+
+1. Install uvup:
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.sh | sh
+   ```
+
+2. Initialize shell integration:
+   ```bash
+   uvup init
+   source ~/.bashrc  # or your shell config
+   ```
+
+## Quick Start
+
+1. Run the onboarding script:
+   ```bash
+   ./scripts/onboard.sh
+   ```
+
+2. Create your working environment:
+   ```bash
+   uvup new my-work --template backend-template
+   cd my-work
+   ```
+
+3. Start developing!
+```
+
+## Consistent Environments Across Team
+
+### Lock File Strategy
+
+```bash
+# Team lead creates and locks dependencies
+uvup create shared-env
+uvup activate shared-env
+uvup add requests pandas numpy
+uvup lock  # Creates uv.lock
+
+# Commit both files
+git add ~/.uvup/shared-env/pyproject.toml
+git add ~/.uvup/shared-env/uv.lock
+git commit -m "Lock dependencies for team"
+```
+
+Team members use the locked versions:
+
+```bash
+# Pull latest
+git pull
+
+# Update local template
+uvup create shared-env
+cp project/templates/pyproject.toml ~/.uvup/shared-env/
+cp project/templates/uv.lock ~/.uvup/shared-env/
+cd ~/.uvup/shared-env
+uv sync --locked  # Install exact versions
+```
+
+## Code Review Environments
+
+### Reviewing Pull Requests
+
+```bash
+# Create clean environment for PR review
+uvup clone main-env pr-123-review
+uvup activate pr-123-review
+
+# Checkout PR branch
+git fetch origin pull/123/head:pr-123
+git checkout pr-123
+
+# Sync with any new dependencies
+uvup sync --template main-template
+
+# Test the changes
+python -m pytest
+uvup deactivate
+
+# Clean up after review
+uvup delete pr-123-review
+```
+
+## Shared Template Repository
+
+### Repository Structure
+
+```
+team-templates/
+├── README.md
+├── web-api.toml
+├── data-pipeline.toml
+├── ml-training.toml
+└── scripts/
+    └── sync-templates.sh
+```
+
+### Sync Script
+
+```bash
+#!/bin/bash
+# sync-templates.sh - Update local templates from repository
+
+TEMPLATE_REPO="https://github.com/company/team-templates"
+TEMP_DIR=$(mktemp -d)
+
+git clone "$TEMPLATE_REPO" "$TEMP_DIR"
+
+for toml in "$TEMP_DIR"/*.toml; do
+  name=$(basename "$toml" .toml)
+  template="${name}-template"
+  
+  echo "Updating $template..."
+  
+  # Create if doesn't exist
+  if ! uvup list | grep -q "$template"; then
+    uvup create "$template"
+  fi
+  
+  # Update pyproject.toml
+  cp "$toml" ~/.uvup/$template/pyproject.toml
+  cd ~/.uvup/$template
+  uv lock
+  uv sync
+  cd -
+done
+
+rm -rf "$TEMP_DIR"
+echo "Templates updated!"
+```
+
+## Cross-Platform Considerations
+
+### Platform-Specific Dependencies
+
+```bash
+# Template for cross-platform project
+uvup create cross-platform-template
+uvup activate cross-platform-template
+
+# Core dependencies (all platforms)
+uvup add requests pydantic
+
+# Platform-specific in pyproject.toml
+# [project.dependencies]
+# requests = ">=2.28.0"
+# pydantic = ">=2.0.0"
+# pywin32 = {version = ">=305", markers = "platform_system == 'Windows'"}
+# pyobjc = {version = ">=9.0", markers = "platform_system == 'Darwin'"}
+```
+
+### Testing on Multiple Platforms
+
+```bash
+# CI/CD configuration example (.github/workflows/test.yml)
+# Test on Linux, macOS, Windows
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install uvup
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.sh | sh
+      - name: Create environment
+        run: |
+          uvup create test-env
+          cp pyproject.toml ~/.uvup/test-env/
+          cd ~/.uvup/test-env && uv sync
+      - name: Run tests
+        run: cd ~/.uvup/test-env && uv run pytest
+```
diff --git a/book/src/use-cases/development.md b/book/src/use-cases/development.md
new file mode 100644
index 0000000..c3a4feb
--- /dev/null
+++ b/book/src/use-cases/development.md
@@ -0,0 +1,172 @@
+# Development Workflows
+
+Daily development patterns with uvup.
+
+## Creating Template Environments
+
+Create reusable templates for different project types:
+
+```bash
+# 1. Create base web template
+uvup create web-template
+uvup activate web-template
+uvup add fastapi uvicorn pydantic
+uvup add --group dev pytest black mypy ruff
+uvup deactivate
+
+# 2. Create data science template
+uvup create ds-template
+uvup activate ds-template
+uvup add numpy pandas matplotlib seaborn scikit-learn
+uvup add --group dev jupyter ipykernel pytest
+uvup deactivate
+
+# 3. Create CLI tool template
+uvup create cli-template
+uvup activate cli-template
+uvup add click rich typer
+uvup add --group dev pytest pytest-cov
+uvup deactivate
+```
+
+## Starting New Projects from Templates
+
+### Basic Project Creation
+
+```bash
+# Start a new web API project
+uvup new my-api --template web-template
+
+# Start without dev tools (for production containers)
+uvup new my-api --template web-template --exclude pytest,black,mypy,ruff
+
+# Start with only core dependencies
+uvup new minimal-api --template web-template --include fastapi,uvicorn,pydantic
+```
+
+### Preview Before Creating
+
+Always use `--dry-run` to preview changes:
+
+```bash
+uvup new my-api --template web-template --exclude pytest --dry-run
+```
+
+## Syncing Existing Projects
+
+### Basic Sync
+
+Update project with latest template changes:
+
+```bash
+cd my-existing-project
+uvup sync --template web-template --dry-run
+# Review changes...
+uvup sync --template web-template
+```
+
+### Selective Sync
+
+Sync but keep dev tools separate:
+
+```bash
+uvup sync --template web-template --exclude pytest,black,mypy
+```
+
+## Managing Multiple Projects
+
+```bash
+# List all projects
+uvup list
+
+# Create project-specific environments
+uvup new client-a-api --template web-template
+uvup new client-b-api --template web-template
+uvup new data-pipeline --template ds-template
+
+# Switch between projects
+cd ~/projects/client-a-api
+uvup activate client-a-api
+# ... work ...
+uvup deactivate
+```
+
+## Experimenting Safely
+
+### Clone Before Experimenting
+
+```bash
+# Clone production environment for testing
+uvup clone production-env experiment-env
+
+# Activate and test new packages
+uvup activate experiment-env
+uvup add experimental-package
+python -m pytest
+uvup deactivate
+
+# If successful, update production
+uvup activate production-env
+uvup add experimental-package
+uvup deactivate
+
+# If failed, just remove experiment
+uvup delete experiment-env
+```
+
+## Upgrading Dependencies
+
+### Safe Upgrade Strategy
+
+```bash
+# 1. Create backup before upgrade
+uvup clone my-project my-project-backup
+
+# 2. Upgrade in original
+uvup activate my-project
+uvup lock --upgrade
+uv sync
+python -m pytest
+uvup deactivate
+
+# 3. If successful, clean up backup
+uvup delete my-project-backup
+
+# 4. If failed, restore from backup
+uvup delete my-project
+uvup clone my-project-backup my-project
+uvup delete my-project-backup
+```
+
+## Best Practices
+
+### Template Naming Conventions
+
+```bash
+# Use descriptive names
+uvup create web-api-template      # Good
+uvup create template1             # Bad
+
+# Use versioning for templates
+uvup create web-api-v1-template
+uvup create web-api-v2-template
+
+# Use prefixes for categories
+uvup create ml-pytorch-template
+uvup create ml-tensorflow-template
+uvup create web-fastapi-template
+uvup create web-flask-template
+```
+
+### Regular Updates
+
+Keep your templates fresh:
+
+```bash
+# Monthly template maintenance
+uvup activate web-template
+uvup lock --upgrade
+uv sync
+# Test template...
+uvup deactivate
+```
diff --git a/book/src/use-cases/getting-started.md b/book/src/use-cases/getting-started.md
new file mode 100644
index 0000000..623b132
--- /dev/null
+++ b/book/src/use-cases/getting-started.md
@@ -0,0 +1,156 @@
+# Getting Started
+
+First steps with uvup.
+
+## First Time Setup
+
+Complete setup from scratch:
+
+```bash
+# 1. Install uvup
+curl -fsSL https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.sh | sh
+
+# 2. Initialize shell integration
+uvup init
+
+# 3. Restart your shell or source config
+source ~/.bashrc  # or ~/.zshrc, etc.
+
+# 4. Create your first environment
+uvup create my-first-project --python 3.12
+
+# 5. Activate and use it
+uvup activate my-first-project
+uvup add requests numpy
+python -c "import requests; print(requests.__version__)"
+uvup deactivate
+```
+
+## Quick Project Creation
+
+### Data Science Project
+
+```bash
+# Create a simple data science project
+uvup create ds-project
+uvup activate ds-project
+uvup add numpy pandas matplotlib jupyter
+jupyter notebook
+```
+
+### Web API Project
+
+```bash
+# Create a web API project
+uvup create web-api
+uvup activate web-api
+uvup add fastapi uvicorn pydantic
+uvup add --group dev pytest black
+
+# Start development server
+uvicorn main:app --reload
+```
+
+### CLI Tool Project
+
+```bash
+# Create a CLI tool project
+uvup create cli-tool
+uvup activate cli-tool
+uvup add click rich typer
+uvup add --group dev pytest
+
+# Run your CLI
+python cli.py --help
+```
+
+## Understanding the Basics
+
+### Directory Structure
+
+After creating an environment, uvup organizes files like this:
+
+```
+~/.uvup/my-project/
+├── .venv/              # Python virtual environment
+├── pyproject.toml      # Project configuration
+└── uv.lock             # Lock file for reproducibility
+```
+
+### Activation Workflow
+
+```bash
+# Before activation - commands fail
+$ uvup add requests
+Error: No active environment
+
+# After activation - commands work
+$ uvup activate myproject
+(myproject) $ uvup add requests
+Added: requests
+
+# Deactivate when done
+(myproject) $ uvup deactivate
+$
+```
+
+### Location Independence
+
+One of uvup's key features:
+
+```bash
+$ uvup activate myproject
+(myproject) $ cd ~/anywhere/on/your/system
+(myproject) $ uvup add numpy  # Still works!
+```
+
+This works because uvup uses `uv --project ~/.uvup/myproject` internally.
+
+## Common First-Time Questions
+
+### Where are my environments?
+
+All environments are stored in `~/.uvup/`:
+
+```bash
+ls ~/.uvup/
+# Output: my-first-project/ ds-project/ web-api/
+```
+
+### How do I see what's installed?
+
+```bash
+uvup activate myproject
+uv pip list
+```
+
+### How do I remove an environment?
+
+```bash
+uvup delete myproject
+```
+
+### Can I use multiple environments?
+
+Yes! Create as many as you need:
+
+```bash
+uvup create project-a
+uvup create project-b
+uvup create project-c
+
+# Switch between them
+uvup activate project-a
+# ... work ...
+uvup deactivate
+
+uvup activate project-b
+# ... work ...
+uvup deactivate
+```
+
+## Next Steps
+
+Continue to:
+- [Development Workflows](./development.md) - Learn advanced patterns
+- [Commands Reference](../commands/README.md) - Complete command documentation
diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md
deleted file mode 100644
index 942ac48..0000000
--- a/docs/COMMANDS.md
+++ /dev/null
@@ -1,434 +0,0 @@
-# Command Reference
-
-Complete reference for all uvup commands.
-
-## Table of Contents
-
-- [Environment Management](#environment-management)
-  - [create](#create)
-  - [list](#list)
-  - [remove](#remove)
-- [Environment Operations](#environment-operations)
-  - [clone](#clone)
-  - [new](#new)
-  - [sync](#sync)
-- [System](#system)
-  - [init](#init)
-  - [update](#update)
-
-## Environment Management
-
-### create
-
-Create a new empty virtual environment.
-
-**Usage:**
-```bash
-uvup create <name> [OPTIONS]
-```
-
-**Arguments:**
-- `<name>` - Name of the environment to create
-
-**Options:**
-- `-p, --python <version>` - Python version (default: 3.12)
-
-**Examples:**
-```bash
-# Create environment with default Python
-uvup create myproject
-
-# Create with specific Python version
-uvup create myproject --python 3.11
-uvup create --python 3.11 myproject
-```
-
-**Notes:**
-- Creates an empty pyproject.toml with minimal configuration
-- Initializes a virtual environment with uv
-- Environment is created in `~/.uvup/<name>/`
-
----
-
-### list
-
-List all available environments.
-
-**Usage:**
-```bash
-uvup list
-```
-
-**Output:**
-- Lists all environments in `~/.uvup/`
-- Shows "No environments found." if empty
-
-**Examples:**
-```bash
-uvup list
-```
-
----
-
-### remove
-
-Remove an existing environment.
-
-**Usage:**
-```bash
-uvup remove <name>
-```
-
-**Arguments:**
-- `<name>` - Name of the environment to remove
-
-**Examples:**
-```bash
-uvup remove myproject
-```
-
-**Notes:**
-- Permanently deletes the environment directory
-- Cannot be undone
-- Fails if environment doesn't exist
-- Only one environment can be removed at a time
-
----
-
-## Environment Operations
-
-### clone
-
-Clone an existing environment to create an exact 1:1 copy.
-
-**Usage:**
-```bash
-uvup clone <source> <target>
-```
-
-**Arguments:**
-- `<source>` - Source environment name
-- `<target>` - Target environment name
-
-**Examples:**
-```bash
-# Create exact backup
-uvup clone myproject myproject-backup
-
-# Clone for testing
-uvup clone production testing
-```
-
-**What Gets Cloned:**
-- ✅ `pyproject.toml` - Project configuration
-- ✅ `hello.py` - Demo file (if exists)
-- ✅ `uv.lock` - Lock file (if exists)
-- ✅ Virtual environment - Fresh venv with same packages
-
-**What Doesn't Get Cloned:**
-- ❌ `.venv/` directory (recreated fresh)
-- ❌ Custom files (only standard files)
-
-**Notes:**
-- Pure 1:1 copy with **no modification options**
-- Use `new` if you need to modify during copy
-- Automatically syncs packages from lock file
-
----
-
-### new
-
-Create a new project from a template environment with modification support.
-
-**Usage:**
-```bash
-uvup new <name> --template <template> [OPTIONS]
-```
-
-**Arguments:**
-- `<name>` - Project name
-- `--template <template>` - Template environment name
-
-**Options:**
-- `-p, --python <version>` - Override Python version
-- `--exclude <packages>` - Exclude packages (comma-separated)
-- `--include <packages>` - Include only these packages (comma-separated)
-- `--path <directory>` - Create in custom directory (default: current dir)
-- `--dry-run` - Preview changes without creating
-
-**Examples:**
-```bash
-# Basic project creation
-uvup new myapp --template web-template
-
-# Custom Python version
-uvup new myapp --template web-template --python 3.11
-
-# Exclude development tools
-uvup new myapp --template web-template --exclude pytest,black,mypy
-
-# Include only specific packages
-uvup new myapp --template web-template --include numpy,pandas,requests
-
-# Create in specific directory
-uvup new myapp --template web-template --path ~/projects
-
-# Preview without creating
-uvup new myapp --template web-template --exclude pytest --dry-run
-```
-
-**Modification Behavior:**
-
-1. **Project Name**: Automatically updated in pyproject.toml
-2. **Python Version**: Overridden if `--python` specified
-3. **Dependencies**: Filtered by `--exclude` or `--include`
-4. **Optional Dependencies**: Also filtered, empty groups removed
-
-**Filtering Rules:**
-
-- `--exclude`: Removes specified packages from both main and optional dependencies
-- `--include`: Keeps ONLY specified packages (removes all others)
-- Cannot use both `--exclude` and `--include` together
-- Package names are case-insensitive
-- Handles PEP 508 specifiers (e.g., `requests[http3]>=2.0`)
-
-**Dry-run Output:**
-```
--- Dry Run Mode --
-
-Template: 'web-template' (Python 3.12)
-Project:  'myapp' (Python 3.11)
-Location: /Users/you/myapp
-
-Python version change:
-  3.12 → 3.11
-
-Filters applied:
-  Exclude: pytest, black
-
-Dependency changes:
-  Removed (2):
-    - pytest>=7.0.0
-    - black>=23.0.0
-  Kept (5):
-
-Optional dependencies:
-  [dev]: Removed (group is empty after filtering)
-  [viz]: No changes
-
-To create this project, run the same command without --dry-run
-```
-
-**Notes:**
-- Creates project in `<path>/<name>/` (default: `./<name>/`)
-- Fails if target directory already exists
-- Automatically runs `uv lock` and `uv sync`
-- Project is ready to use immediately
-
----
-
-### sync
-
-Sync current project with a template environment.
-
-**Usage:**
-```bash
-uvup sync --template <template> [OPTIONS]
-```
-
-**Arguments:**
-- `--template <template>` - Template environment name
-
-**Options:**
-- `-p, --python <version>` - Override Python version
-- `--exclude <packages>` - Exclude packages (comma-separated)
-- `--include <packages>` - Include only these packages (comma-separated)
-- `--dry-run` - Preview changes without syncing
-
-**Examples:**
-```bash
-# Sync with template
-cd myproject
-uvup sync --template web-template
-
-# Sync with Python version change
-uvup sync --template web-template --python 3.11
-
-# Sync without dev dependencies
-uvup sync --template web-template --exclude pytest,black,mypy
-
-# Sync only core packages
-uvup sync --template web-template --include numpy,pandas,requests
-
-# Preview changes
-uvup sync --template web-template --dry-run
-```
-
-**Sync Behavior:**
-
-1. **Dependencies**: Replaced with template's dependencies (filtered)
-2. **Optional Dependencies**: Replaced with template's optional-dependencies (filtered)
-3. **Python Version**: Updated if `--python` specified
-4. **Project Name**: Preserved (NOT changed)
-
-**Safety Features:**
-
-- ✅ Automatic backup: `pyproject.toml.backup` created before changes
-- ✅ Rollback on error: Backup restored if `uv lock` or `uv sync` fails
-- ✅ Backup cleanup: Removed on successful completion
-
-**Dry-run Output:**
-```
--- Dry Run Mode --
-
-Template: 'web-template' (Python 3.12)
-Current:  /Users/you/myproject (Python 3.12)
-
-Dependency changes:
-  Added (2):
-    + fastapi>=0.100.0
-    + uvicorn>=0.23.0
-  Removed (1):
-    - flask>=2.3.0
-  Kept (3):
-
-Optional dependencies:
-  [dev]: Modified (5 packages)
-  [viz]: No changes
-
-To sync this project, run the same command without --dry-run
-```
-
-**Notes:**
-- Must be run from project directory containing `pyproject.toml`
-- Fails if no `pyproject.toml` found
-- Changes take effect immediately (except in dry-run mode)
-- Backup file is left if user interrupts (Ctrl+C)
-
----
-
-## System
-
-### init
-
-Initialize shell integration for uvup.
-
-**Usage:**
-```bash
-uvup init
-```
-
-**Supported Shells:**
-- Bash
-- Zsh
-- Fish
-- PowerShell
-
-**What It Does:**
-- Detects your current shell
-- Adds uvup initialization to shell config
-- Enables `uvup activate` and `uvup deactivate` commands
-
-**Examples:**
-```bash
-# Initialize for current shell
-uvup init
-```
-
-**Shell Config Files:**
-- Bash: `~/.bashrc`
-- Zsh: `~/.zshrc`
-- Fish: `~/.config/fish/config.fish`
-- PowerShell: `$PROFILE`
-
-**Notes:**
-- Run this once after installation
-- Restart shell or source config file to apply
-- Safe to run multiple times (idempotent)
-
----
-
-### update
-
-Update uvup to the latest version.
-
-**Usage:**
-```bash
-uvup update [OPTIONS]
-```
-
-**Options:**
-- `-c, --check` - Only check for updates without installing
-
-**Examples:**
-```bash
-# Update to latest version
-uvup update
-
-# Check if update available
-uvup update --check
-```
-
-**Notes:**
-- Downloads latest release from GitHub
-- Replaces current binary in-place
-- Preserves all environments and configuration
-
----
-
-## Shell-only Commands
-
-These commands are available only after running `uvup init`:
-
-### activate
-
-Activate a virtual environment.
-
-**Usage:**
-```bash
-uvup activate <name>
-```
-
-**Arguments:**
-- `<name>` - Environment name to activate
-
-**Examples:**
-```bash
-uvup activate myproject
-```
-
-### deactivate
-
-Deactivate the current virtual environment.
-
-**Usage:**
-```bash
-uvup deactivate
-```
-
-**Examples:**
-```bash
-uvup deactivate
-```
-
----
-
-## Command Decision Tree
-
-**Need to create something?**
-- Empty environment → `create`
-- Exact copy → `clone`
-- New project from template → `new`
-
-**Need to update?**
-- Current project from template → `sync`
-- uvup itself → `update`
-
-**Need to manage?**
-- See all environments → `list`
-- Delete environment → `remove`
-
-**Need to use?**
-- Enable activation → `init`
-- Enter environment → `activate`
-- Exit environment → `deactivate`
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
deleted file mode 100644
index 688f889..0000000
--- a/docs/INSTALL.md
+++ /dev/null
@@ -1,189 +0,0 @@
-# Installation Guide
-
-This guide provides detailed installation instructions for uvup across different platforms.
-
-## Quick Install (Recommended)
-
-### Linux and macOS
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.sh | sh
-```
-
-The installation script will automatically configure shell integration for you. Restart your terminal or run:
-
-```bash
-source ~/.zshrc  # or ~/.bashrc for bash
-```
-
-### Windows (PowerShell)
-
-```powershell
-Invoke-RestMethod https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.ps1 | Invoke-Expression
-```
-
-Restart your terminal or run:
-
-```powershell
-. $PROFILE
-```
-
-## Manual Installation
-
-Download the latest release for your platform from [GitHub Releases](https://github.com/KercyDing/uvup/releases).
-
-### Linux
-
-```bash
-# Download and install
-wget https://github.com/KercyDing/uvup/releases/latest/download/uvup-linux-x86_64
-chmod +x uvup-linux-x86_64
-sudo mv uvup-linux-x86_64 /usr/local/bin/uvup
-
-# Initialize shell integration
-echo 'eval "$(uvup init)"' >> ~/.bashrc  # or ~/.zshrc for zsh
-source ~/.bashrc
-```
-
-### macOS
-
-**Apple Silicon:**
-```bash
-# Download and install
-wget https://github.com/KercyDing/uvup/releases/latest/download/uvup-macos-arm64
-chmod +x uvup-macos-arm64
-sudo mv uvup-macos-arm64 /usr/local/bin/uvup
-
-# Initialize shell integration
-echo 'eval "$(uvup init)"' >> ~/.zshrc
-source ~/.zshrc
-```
-
-**Intel Macs:**
-```bash
-# Download and install
-wget https://github.com/KercyDing/uvup/releases/latest/download/uvup-macos-x86_64
-chmod +x uvup-macos-x86_64
-sudo mv uvup-macos-x86_64 /usr/local/bin/uvup
-
-# Initialize shell integration
-echo 'eval "$(uvup init)"' >> ~/.zshrc
-source ~/.zshrc
-```
-
-### Windows
-
-1. Download [uvup-windows-x86_64.exe](https://github.com/KercyDing/uvup/releases/latest/download/uvup-windows-x86_64.exe)
-
-2. Create directory and move the binary:
-   ```powershell
-   New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\Programs\uvup"
-   Move-Item uvup-windows-x86_64.exe "$env:LOCALAPPDATA\Programs\uvup\uvup.exe"
-   ```
-
-3. Add to PATH:
-   - Press `Win + R`, type `sysdm.cpl`, press Enter
-   - Go to "Advanced" tab → "Environment Variables"
-   - Under "User variables", select "Path" and click "Edit"
-   - Click "New" and add: `%LOCALAPPDATA%\Programs\uvup`
-   - Click OK to save
-
-4. Initialize shell integration (restart terminal first):
-   ```powershell
-   # Add to profile for all PowerShell hosts
-   Add-Content -Path $PROFILE.CurrentUserAllHosts -Value "`nInvoke-Expression ((uvup init) -join `"``n`")"
-
-   # Load in current session
-   Invoke-Expression ((uvup init) -join "`n")
-   ```
-
-## For Developers
-
-### Installing from Source
-
-1. Clone the repository:
-```bash
-git clone https://github.com/KercyDing/uvup.git
-cd uvup
-```
-
-2. Install from source:
-```bash
-cargo install --path .
-```
-
-3. Initialize shell integration:
-
-**Linux/macOS:**
-```bash
-# Add to your shell configuration
-echo 'eval "$(uvup init)"' >> ~/.zshrc  # or ~/.bashrc for bash
-source ~/.zshrc
-```
-
-**Windows (PowerShell):**
-```powershell
-# Add to profile for all PowerShell hosts
-Add-Content -Path $PROFILE.CurrentUserAllHosts -Value "`nInvoke-Expression ((uvup init) -join `"``n`")"
-
-# Load in current session
-Invoke-Expression ((uvup init) -join "`n")
-```
-
-### Development Workflow
-
-During development, you have several options:
-
-**Option 1: Reinstall after changes (Recommended)**
-```bash
-# After modifying code
-cargo install --path .
-```
-
-**Option 2: Use cargo run for quick testing**
-```bash
-cargo run -- --help
-cargo run -- create test-env
-cargo run -- list
-```
-
-**Option 3: Build and test manually**
-```bash
-cargo build
-./target/debug/uvup --help
-```
-
-## Verification
-
-After installation, verify that uvup is working:
-
-```bash
-uvup --version
-```
-
-You should see the version number displayed.
-
-## Troubleshooting
-
-### Command not found
-
-If you get "command not found" after installation:
-
-1. Make sure you've restarted your terminal or sourced your shell configuration
-2. Verify that uvup is in your PATH:
-   ```bash
-   # Linux/macOS
-   which uvup
-
-   # Windows
-   where.exe uvup
-   ```
-
-### Shell integration not working
-
-If `uvup activate` doesn't work:
-
-1. Check that the init line is in your shell config file
-2. Restart your terminal or source the config file
-
-For more help, please visit [GitHub Issues](https://github.com/KercyDing/uvup/issues).
diff --git a/docs/UNINSTALL.md b/docs/UNINSTALL.md
deleted file mode 100644
index a04f731..0000000
--- a/docs/UNINSTALL.md
+++ /dev/null
@@ -1,157 +0,0 @@
-# Uninstallation Guide
-
-This guide provides detailed instructions for uninstalling uvup from your system.
-
-## Quick Uninstall (Recommended)
-
-### Linux and macOS
-
-```bash
-curl -fsSL -O https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/uninstall.sh
-chmod +x uninstall.sh
-./uninstall.sh
-```
-
-### Windows (PowerShell)
-
-```powershell
-Invoke-WebRequest -Uri https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/uninstall.ps1 -OutFile uninstall.ps1
-.\uninstall.ps1
-```
-
-### What the uninstall script does:
-
-- Remove the uvup binary
-- Ask if you want to delete all virtual environments in `~/.uvup`
-- Remove uvup from PATH (Windows only, if installed via install.ps1)
-- Remove shell integration from your profile
-
-## Manual Uninstall
-
-If you prefer to uninstall manually or if the script doesn't work:
-
-### Linux/macOS
-
-1. Remove binary:
-```bash
-# If installed to /usr/local/bin
-sudo rm /usr/local/bin/uvup
-
-# OR if installed to ~/.local/bin
-rm ~/.local/bin/uvup
-
-# OR if installed via cargo
-rm ~/.cargo/bin/uvup
-```
-
-2. Remove data directory (optional):
-```bash
-rm -rf ~/.uvup
-```
-
-3. Remove from shell config:
-
-Edit your shell configuration file and remove lines containing `eval "$(uvup init)"`:
-
-```bash
-# For bash users
-nano ~/.bashrc
-
-# For zsh users
-nano ~/.zshrc
-
-# For fish users
-nano ~/.config/fish/config.fish
-```
-
-4. Reload your shell:
-```bash
-source ~/.bashrc  # or ~/.zshrc
-```
-
-### Windows
-
-1. Remove binary:
-```powershell
-# If installed to Programs
-Remove-Item "$env:LOCALAPPDATA\Programs\uvup\uvup.exe"
-
-# OR if installed via cargo
-Remove-Item "$env:USERPROFILE\.cargo\bin\uvup.exe"
-```
-
-2. Remove data directory (optional):
-```powershell
-Remove-Item -Recurse "$env:USERPROFILE\.uvup"
-```
-
-3. Remove from PATH (if added manually):
-   - Press `Win + R`, type `sysdm.cpl`, press Enter
-   - Go to "Advanced" tab → "Environment Variables"
-   - Under "User variables", select "Path" and click "Edit"
-   - Find and remove: `%LOCALAPPDATA%\Programs\uvup`
-   - Click OK to save
-
-4. Remove from PowerShell profile:
-
-Find your profile file:
-```powershell
-echo $PROFILE.CurrentUserAllHosts
-```
-
-Edit the file and remove lines containing `uvup init`.
-
-5. Restart your PowerShell terminal.
-
-## Removing Virtual Environments
-
-The uninstall scripts will ask if you want to remove all virtual environments. If you chose not to remove them during uninstall, or if you want to remove them later:
-
-### Linux/macOS
-```bash
-rm -rf ~/.uvup
-```
-
-### Windows
-```powershell
-Remove-Item -Recurse "$env:USERPROFILE\.uvup"
-```
-
-**Warning:** This will permanently delete all Python virtual environments managed by uvup.
-
-## Verification
-
-After uninstallation, verify that uvup is removed:
-
-```bash
-# This should return "command not found"
-uvup --version
-```
-
-## Reinstallation
-
-If you want to reinstall uvup later, please refer to the [Installation Guide](INSTALL.md).
-
-## Troubleshooting
-
-### uvup command still works after uninstall
-
-This might happen if:
-
-1. You have multiple installations (e.g., both in `/usr/local/bin` and `~/.cargo/bin`)
-   - Check with: `which uvup` (Linux/macOS) or `where.exe uvup` (Windows)
-   - Remove all instances
-
-2. Your PATH cache hasn't been refreshed
-   - Restart your terminal
-   - Or run: `hash -r` (bash/zsh)
-
-### Shell integration still active
-
-If you still see uvup functions after uninstall:
-
-1. Make sure you've removed the init line from your shell config
-2. Restart your terminal or source the config file
-3. Check for init lines in multiple config files (e.g., both `.bashrc` and `.bash_profile`)
-
-For more help, please visit [GitHub Issues](https://github.com/KercyDing/uvup/issues).
diff --git a/docs/USE_CASES.md b/docs/USE_CASES.md
deleted file mode 100644
index 9735ee9..0000000
--- a/docs/USE_CASES.md
+++ /dev/null
@@ -1,474 +0,0 @@
-# Use Cases
-
-Real-world scenarios and workflows with uvup.
-
-## Table of Contents
-
-- [Getting Started](#getting-started)
-- [Development Workflows](#development-workflows)
-- [Team Collaboration](#team-collaboration)
-- [Project Management](#project-management)
-- [Advanced Patterns](#advanced-patterns)
-
-## Getting Started
-
-### First Time Setup
-
-```bash
-# 1. Install uvup
-curl -fsSL https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.sh | sh
-
-# 2. Initialize shell integration
-uvup init
-
-# 3. Restart your shell or source config
-source ~/.bashrc  # or ~/.zshrc, etc.
-
-# 4. Create your first environment
-uvup create my-first-project --python 3.12
-
-# 5. Activate and use it
-uvup activate my-first-project
-uv add requests numpy
-python -c "import requests; print(requests.__version__)"
-uvup deactivate
-```
-
-### Quick Project Creation
-
-```bash
-# Create a simple data science project
-uvup create ds-project
-uvup activate ds-project
-uv add numpy pandas matplotlib jupyter
-jupyter notebook
-```
-
-## Development Workflows
-
-### Creating Template Environments
-
-Create reusable templates for different project types:
-
-```bash
-# 1. Create base web template
-uvup create web-template
-uvup activate web-template
-uv add fastapi uvicorn pydantic
-uv add --group dev pytest black mypy ruff
-uvup deactivate
-
-# 2. Create data science template
-uvup create ds-template
-uvup activate ds-template
-uv add numpy pandas matplotlib seaborn scikit-learn
-uv add --group dev jupyter ipykernel pytest
-uvup deactivate
-
-# 3. Create CLI tool template
-uvup create cli-template
-uvup activate cli-template
-uv add click rich typer
-uv add --group dev pytest pytest-cov
-uvup deactivate
-```
-
-### Starting New Projects from Templates
-
-```bash
-# Start a new web API project
-uvup new my-api --template web-template
-
-# Start without dev tools (for production containers)
-uvup new my-api --template web-template --exclude pytest,black,mypy,ruff
-
-# Start with only core dependencies
-uvup new minimal-api --template web-template --include fastapi,uvicorn,pydantic
-```
-
-### Syncing Existing Projects
-
-```bash
-# Update project with latest template changes
-cd my-existing-project
-uvup sync --template web-template --dry-run
-# Review changes...
-uvup sync --template web-template
-
-# Sync but keep dev tools separate
-uvup sync --template web-template --exclude pytest,black,mypy
-```
-
-## Team Collaboration
-
-### Sharing Environment Definitions
-
-**Scenario**: Team wants consistent development environments.
-
-```bash
-# Team lead creates template
-uvup create team-base-template --python 3.11
-uvup activate team-base-template
-uv add requests httpx pydantic sqlalchemy
-uv add --group dev pytest black mypy ruff pre-commit
-uv add --group docs sphinx sphinx-rtd-theme
-uvup deactivate
-
-# Team lead shares the pyproject.toml
-cp ~/.uvup/team-base-template/pyproject.toml ./templates/
-
-# Team members create from template
-uvup create team-base-template
-uvup activate team-base-template
-# Copy pyproject.toml to environment
-cp ./templates/pyproject.toml ~/.uvup/team-base-template/
-cd ~/.uvup/team-base-template
-uv lock
-uv sync
-uvup deactivate
-
-# Now everyone can create consistent projects
-uvup new my-feature --template team-base-template
-```
-
-### Onboarding New Developers
-
-```bash
-# New developer setup script
-#!/bin/bash
-
-# Install uvup
-curl -fsSL https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.sh | sh
-uvup init
-
-# Create standard templates
-uvup create backend-template
-cp templates/backend.toml ~/.uvup/backend-template/pyproject.toml
-cd ~/.uvup/backend-template && uv sync && cd -
-
-uvup create frontend-template
-cp templates/frontend.toml ~/.uvup/frontend-template/pyproject.toml
-cd ~/.uvup/frontend-template && uv sync && cd -
-
-# Clone current project
-git clone https://github.com/company/project
-cd project
-uvup sync --template backend-template
-```
-
-## Project Management
-
-### Managing Multiple Projects
-
-```bash
-# List all projects
-uvup list
-
-# Create project-specific environments
-uvup new client-a-api --template web-template
-uvup new client-b-api --template web-template
-uvup new data-pipeline --template ds-template
-
-# Switch between projects
-cd ~/projects/client-a-api && uvup activate client-a-api
-# ... work on client A ...
-uvup deactivate
-
-cd ~/projects/client-b-api && uvup activate client-b-api
-# ... work on client B ...
-uvup deactivate
-```
-
-### Experimenting Safely
-
-```bash
-# Clone production environment for testing
-uvup clone production-env experiment-env
-
-# Activate and test new packages
-uvup activate experiment-env
-uv add experimental-package
-python -m pytest
-# ... experiment ...
-uvup deactivate
-
-# If successful, update template
-uvup sync --template production-template --dry-run
-# Review and apply
-uvup sync --template production-template
-
-# If failed, just remove experiment
-uvup remove experiment-env
-```
-
-### Upgrading Dependencies
-
-```bash
-# Create backup before upgrade
-uvup clone my-project my-project-backup
-
-# Upgrade in original
-uvup activate my-project
-uv add numpy@latest pandas@latest
-python -m pytest
-# ... verify everything works ...
-uvup deactivate
-
-# If successful, update template
-cd ~/.uvup/my-project-template
-uv add numpy@latest pandas@latest
-uv lock
-
-# If failed, restore from backup
-uvup remove my-project
-uvup clone my-project-backup my-project
-uvup remove my-project-backup
-```
-
-## Advanced Patterns
-
-### Multi-Stage Project Setup
-
-**Scenario**: Different dependency sets for dev/test/prod.
-
-```bash
-# Base template with core dependencies
-uvup create base-template
-uvup activate base-template
-uv add fastapi uvicorn pydantic sqlalchemy
-uvup deactivate
-
-# Development environment (full stack)
-uvup new my-project-dev --template base-template
-cd my-project-dev
-uv add --group dev pytest black mypy ruff ipython
-uv add --group dev pytest-cov pytest-asyncio
-
-# Testing environment (dev + test tools only)
-uvup new my-project-test --template base-template
-cd ../my-project-test
-uv add --group dev pytest pytest-cov pytest-asyncio
-
-# Production environment (minimal)
-uvup new my-project-prod --template base-template \
-  --exclude pytest,black,mypy,ruff,ipython
-```
-
-### Microservices Development
-
-**Scenario**: Multiple services with shared base, different extras.
-
-```bash
-# Create shared base template
-uvup create microservice-base
-uvup activate microservice-base
-uv add fastapi uvicorn pydantic httpx
-uv add --group dev pytest pytest-asyncio
-uvup deactivate
-
-# Create service-specific projects
-uvup new auth-service --template microservice-base
-cd auth-service
-uv add pyjwt passlib[bcrypt] python-multipart
-
-uvup new user-service --template microservice-base
-cd ../user-service
-uv add sqlalchemy asyncpg alembic
-
-uvup new notification-service --template microservice-base
-cd ../notification-service
-uv add aiosmtplib jinja2 celery
-```
-
-### Educational Environments
-
-**Scenario**: Teaching Python with consistent student environments.
-
-```bash
-# Instructor creates course template
-uvup create course-python-basics
-uvup activate course-python-basics
-uv add ipython jupyter notebook pytest
-uvup deactivate
-
-# Students clone for each module
-uvup new module-01-basics --template course-python-basics
-uvup new module-02-functions --template course-python-basics
-uvup new module-03-classes --template course-python-basics
-
-# Each module can have specific packages
-cd module-02-functions
-uv add hypothesis  # for property-based testing
-
-cd ../module-03-classes
-uv add attrs pydantic  # for class examples
-```
-
-### CI/CD Integration
-
-**Scenario**: Reproducible CI environments.
-
-```bash
-# Local development
-uvup create ci-template
-uvup activate ci-template
-uv add pytest pytest-cov black mypy ruff
-uvup deactivate
-
-# Export for CI (Dockerfile)
-cat > Dockerfile << 'DOCKERFILE'
-FROM python:3.12-slim
-
-# Install uv
-RUN pip install uv
-
-# Copy project
-COPY . /app
-WORKDIR /app
-
-# Install dependencies
-RUN uv sync
-
-# Run tests
-CMD ["uv", "run", "pytest"]
-DOCKERFILE
-
-# Or use template in CI script
-# .github/workflows/test.yml
-cat > .github/workflows/test.yml << 'YAML'
-name: Test
-on: [push, pull_request]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: '3.12'
-      - name: Install uvup
-        run: curl -fsSL https://raw.githubusercontent.com/KercyDing/uvup/main/scripts/install.sh | sh
-      - name: Create from template
-        run: |
-          uvup create ci-env --python 3.12
-          cp pyproject.toml ~/.uvup/ci-env/
-          cd ~/.uvup/ci-env && uv sync
-      - name: Run tests
-        run: cd ~/.uvup/ci-env && uv run pytest
-YAML
-```
-
-### Dependency Isolation Testing
-
-**Scenario**: Test with different dependency versions.
-
-```bash
-# Base template
-uvup create app-template
-uvup activate app-template
-uv add requests flask numpy
-uvup deactivate
-
-# Test with minimum versions
-uvup new app-min-versions --template app-template
-cd app-min-versions
-# Manually set minimum versions in pyproject.toml
-uv lock
-uv sync
-uv run pytest
-
-# Test with latest versions
-uvup new app-latest-versions --template app-template
-cd ../app-latest-versions
-uv add requests@latest flask@latest numpy@latest
-uv run pytest
-
-# Test without optional dependencies
-uvup new app-no-optional --template app-template \
-  --exclude dev-package-1,dev-package-2
-cd ../app-no-optional
-uv run pytest
-```
-
-## Tips and Best Practices
-
-### Template Naming Conventions
-
-```bash
-# Use descriptive names
-uvup create web-api-template      # Good
-uvup create template1             # Bad
-
-# Use versioning for templates
-uvup create web-api-v1-template
-uvup create web-api-v2-template
-
-# Use prefixes for categories
-uvup create ml-pytorch-template
-uvup create ml-tensorflow-template
-uvup create web-fastapi-template
-uvup create web-flask-template
-```
-
-### Regular Maintenance
-
-```bash
-#!/bin/bash
-# monthly-maintenance.sh
-
-# Update uvup itself
-uvup update
-
-# List all environments
-echo "Current environments:"
-uvup list
-
-# Update templates with latest packages
-for template in web-template ds-template cli-template; do
-  if uvup list | grep -q "$template"; then
-    echo "Updating $template..."
-    cd ~/.uvup/$template
-    uv add --upgrade $(uv pip list --format=freeze | cut -d= -f1)
-    uv lock
-  fi
-done
-```
-
-### Backup Strategy
-
-```bash
-#!/bin/bash
-# backup-environments.sh
-
-BACKUP_DIR=~/uvup-backups/$(date +%Y%m%d)
-mkdir -p "$BACKUP_DIR"
-
-# Backup all pyproject.toml files
-for env in ~/.uvup/*/; do
-  name=$(basename "$env")
-  cp "$env/pyproject.toml" "$BACKUP_DIR/$name.toml"
-done
-
-echo "Backed up to $BACKUP_DIR"
-```
-
-### Cleanup Unused Environments
-
-```bash
-#!/bin/bash
-# cleanup-old-environments.sh
-
-# List all environments with creation time
-for env in ~/.uvup/*/; do
-  name=$(basename "$env")
-  age=$(find "$env" -maxdepth 0 -mtime +30)
-  if [ -n "$age" ]; then
-    echo "Old environment: $name (> 30 days)"
-    read -p "Remove? (y/n) " -n 1 -r
-    echo
-    if [[ $REPLY =~ ^[Yy]$ ]]; then
-      uvup remove "$name"
-    fi
-  fi
-done
-```
diff --git a/src/cli.rs b/src/cli.rs
index 25a7762..9509341 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -26,9 +26,9 @@ pub(crate) enum Commands {
     #[command(about = "List all environments")]
     List,
 
-    #[command(about = "Remove an environment")]
-    Remove {
-        #[arg(help = "Name of the environment to remove")]
+    #[command(about = "Delete an environment")]
+    Delete {
+        #[arg(help = "Name of the environment to delete")]
         name: String,
     },
 
@@ -104,4 +104,34 @@ pub(crate) enum Commands {
         #[arg(short, long, help = "Only check for updates without installing")]
         check: bool,
     },
+
+    #[command(about = "Add packages to the active environment")]
+    Add {
+        #[arg(help = "Packages to add", required = true)]
+        packages: Vec<String>,
+
+        #[arg(long, help = "Add to optional dependency group")]
+        group: Option<String>,
+    },
+
+    #[command(about = "Remove packages from the active environment")]
+    Remove {
+        #[arg(help = "Packages to remove", required = true)]
+        packages: Vec<String>,
+
+        #[arg(long, help = "Remove from optional dependency group")]
+        group: Option<String>,
+    },
+
+    #[command(about = "Update the lockfile of the active environment")]
+    Lock {
+        #[arg(long, help = "Update all packages to their latest versions")]
+        upgrade: bool,
+    },
+
+    #[command(about = "Display the dependency tree of the active environment")]
+    Tree {
+        #[arg(long, help = "Maximum depth to display")]
+        depth: Option<usize>,
+    },
 }
diff --git a/src/commands/add.rs b/src/commands/add.rs
new file mode 100644
index 0000000..7b90d80
--- /dev/null
+++ b/src/commands/add.rs
@@ -0,0 +1,35 @@
+use crate::env::paths::get_env_path;
+use crate::error::{Result, UvupError};
+use std::env;
+use std::process::Command;
+
+pub(crate) fn run(packages: &[String], group: Option<String>) -> Result<()> {
+    let active_env = env::var("UVUP_ACTIVE_ENV").map_err(|_| UvupError::NoActiveEnvironment)?;
+
+    let env_path = get_env_path(&active_env)?;
+
+    if !env_path.exists() {
+        return Err(UvupError::EnvNotFound(active_env));
+    }
+
+    let mut cmd = Command::new("uv");
+    cmd.arg("--project").arg(&env_path).arg("add");
+
+    if let Some(g) = group {
+        cmd.arg("--group").arg(g);
+    }
+
+    cmd.args(packages);
+
+    let status = cmd
+        .status()
+        .map_err(|e| UvupError::CommandExecutionFailed(format!("Failed to execute uv add: {e}")))?;
+
+    if status.success() {
+        Ok(())
+    } else {
+        Err(UvupError::CommandExecutionFailed(
+            "uv add command failed".to_string(),
+        ))
+    }
+}
diff --git a/src/commands/delete.rs b/src/commands/delete.rs
new file mode 100644
index 0000000..a03d2c4
--- /dev/null
+++ b/src/commands/delete.rs
@@ -0,0 +1,19 @@
+use crate::env::paths::{get_env_path, validate_env_name};
+use crate::error::{Result, UvupError};
+use crate::utils::print_success;
+use std::fs;
+
+pub(crate) fn run(name: String) -> Result<()> {
+    validate_env_name(&name)?;
+
+    let env_path = get_env_path(&name)?;
+
+    if !env_path.exists() {
+        return Err(UvupError::EnvNotFound(name));
+    }
+
+    fs::remove_dir_all(&env_path)?;
+
+    print_success(&format!("Environment '{name}' removed"));
+    Ok(())
+}
diff --git a/src/commands/lock.rs b/src/commands/lock.rs
new file mode 100644
index 0000000..210a255
--- /dev/null
+++ b/src/commands/lock.rs
@@ -0,0 +1,33 @@
+use crate::env::paths::get_env_path;
+use crate::error::{Result, UvupError};
+use std::env;
+use std::process::Command;
+
+pub(crate) fn run(upgrade: bool) -> Result<()> {
+    let active_env = env::var("UVUP_ACTIVE_ENV").map_err(|_| UvupError::NoActiveEnvironment)?;
+
+    let env_path = get_env_path(&active_env)?;
+
+    if !env_path.exists() {
+        return Err(UvupError::EnvNotFound(active_env));
+    }
+
+    let mut cmd = Command::new("uv");
+    cmd.arg("--project").arg(&env_path).arg("lock");
+
+    if upgrade {
+        cmd.arg("--upgrade");
+    }
+
+    let status = cmd.status().map_err(|e| {
+        UvupError::CommandExecutionFailed(format!("Failed to execute uv lock: {e}"))
+    })?;
+
+    if status.success() {
+        Ok(())
+    } else {
+        Err(UvupError::CommandExecutionFailed(
+            "uv lock command failed".to_string(),
+        ))
+    }
+}
diff --git a/src/commands/mod.rs b/src/commands/mod.rs
index ba7b32a..ea1ff43 100644
--- a/src/commands/mod.rs
+++ b/src/commands/mod.rs
@@ -1,8 +1,12 @@
+pub(crate) mod add;
 pub(crate) mod clone;
 pub(crate) mod create;
+pub(crate) mod delete;
 pub(crate) mod init;
 pub(crate) mod list;
+pub(crate) mod lock;
 pub(crate) mod new;
 pub(crate) mod remove;
 pub(crate) mod sync;
+pub(crate) mod tree;
 pub(crate) mod update;
diff --git a/src/commands/remove.rs b/src/commands/remove.rs
index a03d2c4..37089fb 100644
--- a/src/commands/remove.rs
+++ b/src/commands/remove.rs
@@ -1,19 +1,35 @@
-use crate::env::paths::{get_env_path, validate_env_name};
+use crate::env::paths::get_env_path;
 use crate::error::{Result, UvupError};
-use crate::utils::print_success;
-use std::fs;
+use std::env;
+use std::process::Command;
 
-pub(crate) fn run(name: String) -> Result<()> {
-    validate_env_name(&name)?;
+pub(crate) fn run(packages: &[String], group: Option<String>) -> Result<()> {
+    let active_env = env::var("UVUP_ACTIVE_ENV").map_err(|_| UvupError::NoActiveEnvironment)?;
 
-    let env_path = get_env_path(&name)?;
+    let env_path = get_env_path(&active_env)?;
 
     if !env_path.exists() {
-        return Err(UvupError::EnvNotFound(name));
+        return Err(UvupError::EnvNotFound(active_env));
     }
 
-    fs::remove_dir_all(&env_path)?;
+    let mut cmd = Command::new("uv");
+    cmd.arg("--project").arg(&env_path).arg("remove");
 
-    print_success(&format!("Environment '{name}' removed"));
-    Ok(())
+    if let Some(g) = group {
+        cmd.arg("--group").arg(g);
+    }
+
+    cmd.args(packages);
+
+    let status = cmd.status().map_err(|e| {
+        UvupError::CommandExecutionFailed(format!("Failed to execute uv remove: {e}"))
+    })?;
+
+    if status.success() {
+        Ok(())
+    } else {
+        Err(UvupError::CommandExecutionFailed(
+            "uv remove command failed".to_string(),
+        ))
+    }
 }
diff --git a/src/commands/tree.rs b/src/commands/tree.rs
new file mode 100644
index 0000000..8179d6f
--- /dev/null
+++ b/src/commands/tree.rs
@@ -0,0 +1,33 @@
+use crate::env::paths::get_env_path;
+use crate::error::{Result, UvupError};
+use std::env;
+use std::process::Command;
+
+pub(crate) fn run(depth: Option<usize>) -> Result<()> {
+    let active_env = env::var("UVUP_ACTIVE_ENV").map_err(|_| UvupError::NoActiveEnvironment)?;
+
+    let env_path = get_env_path(&active_env)?;
+
+    if !env_path.exists() {
+        return Err(UvupError::EnvNotFound(active_env));
+    }
+
+    let mut cmd = Command::new("uv");
+    cmd.arg("--project").arg(&env_path).arg("tree");
+
+    if let Some(d) = depth {
+        cmd.arg("--depth").arg(d.to_string());
+    }
+
+    let status = cmd.status().map_err(|e| {
+        UvupError::CommandExecutionFailed(format!("Failed to execute uv tree: {e}"))
+    })?;
+
+    if status.success() {
+        Ok(())
+    } else {
+        Err(UvupError::CommandExecutionFailed(
+            "uv tree command failed".to_string(),
+        ))
+    }
+}
diff --git a/src/error.rs b/src/error.rs
index 984c5ae..e3dd35c 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -12,6 +12,7 @@ pub(crate) enum UvupError {
     PathError(String),
     CommandExecutionFailed(String),
     UpdateFailed(String),
+    NoActiveEnvironment,
 }
 
 impl fmt::Display for UvupError {
@@ -54,6 +55,13 @@ impl fmt::Display for UvupError {
             UvupError::UpdateFailed(msg) => {
                 write!(f, "Update failed: {msg}")
             }
+            UvupError::NoActiveEnvironment => {
+                writeln!(f, "Error: No active environment")?;
+                write!(
+                    f,
+                    "Tip: Use 'uvup activate <name>' to activate an environment first"
+                )
+            }
         }
     }
 }
diff --git a/src/main.rs b/src/main.rs
index 862fc79..aefca06 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -26,7 +26,7 @@ fn run() -> Result<()> {
             commands::create::run(name, python.as_deref())?;
         }
         Commands::List => commands::list::run()?,
-        Commands::Remove { name } => commands::remove::run(name)?,
+        Commands::Delete { name } => commands::delete::run(name)?,
         Commands::Clone { source, target } => commands::clone::run(source, target)?,
         Commands::New {
             name,
@@ -59,6 +59,10 @@ fn run() -> Result<()> {
             dry_run,
         )?,
         Commands::Update { check } => commands::update::run(check)?,
+        Commands::Add { packages, group } => commands::add::run(&packages, group)?,
+        Commands::Remove { packages, group } => commands::remove::run(&packages, group)?,
+        Commands::Lock { upgrade } => commands::lock::run(upgrade)?,
+        Commands::Tree { depth } => commands::tree::run(depth)?,
     }
 
     Ok(())
diff --git a/tests/integration_test.rs b/tests/integration_test.rs
index ec2de8e..186c537 100644
--- a/tests/integration_test.rs
+++ b/tests/integration_test.rs
@@ -43,7 +43,7 @@ fn test_init_command() {
 }
 
 #[test]
-fn test_create_list_remove_workflow() {
+fn test_create_list_delete_workflow() {
     let test_env = "test-integration-env";
 
     cleanup_test_env(test_env);
@@ -69,14 +69,14 @@ fn test_create_list_remove_workflow() {
     let list_stdout = String::from_utf8_lossy(&list_output.stdout);
     assert!(list_stdout.contains(test_env));
 
-    let remove_output = Command::new("cargo")
-        .args(["run", "--", "remove", test_env])
+    let delete_output = Command::new("cargo")
+        .args(["run", "--", "delete", test_env])
         .output()
-        .expect("Failed to execute uvup remove");
+        .expect("Failed to execute uvup delete");
 
-    assert!(remove_output.status.success());
-    let remove_stdout = String::from_utf8_lossy(&remove_output.stdout);
-    assert!(remove_stdout.contains(&format!("Environment '{test_env}' removed")));
+    assert!(delete_output.status.success());
+    let delete_stdout = String::from_utf8_lossy(&delete_output.stdout);
+    assert!(delete_stdout.contains(&format!("Environment '{test_env}' removed")));
 
     assert!(!env_path.exists());
 }
@@ -124,18 +124,18 @@ fn test_create_duplicate_environment() {
 }
 
 #[test]
-fn test_remove_nonexistent_environment() {
+fn test_delete_nonexistent_environment() {
     let test_env = "nonexistent-env";
 
     cleanup_test_env(test_env);
 
-    let remove_output = Command::new("cargo")
-        .args(["run", "--", "remove", test_env])
+    let delete_output = Command::new("cargo")
+        .args(["run", "--", "delete", test_env])
         .output()
-        .expect("Failed to execute uvup remove");
+        .expect("Failed to execute uvup delete");
 
-    assert!(!remove_output.status.success());
-    let stderr = String::from_utf8_lossy(&remove_output.stderr);
+    assert!(!delete_output.status.success());
+    let stderr = String::from_utf8_lossy(&delete_output.stderr);
     assert!(stderr.contains("not found"));
 }
 
@@ -181,3 +181,112 @@ fn test_list_empty_environments() {
         }
     }
 }
+
+// Package management tests
+// Note: These tests require UVUP_ACTIVE_ENV to be set, which requires shell integration.
+// They are marked as ignored by default and can be run with: cargo test -- --ignored
+
+#[test]
+#[ignore = "requires shell integration to set UVUP_ACTIVE_ENV"]
+fn test_add_package_without_activation() {
+    let add_output = Command::new("cargo")
+        .args(["run", "--", "add", "requests"])
+        .output()
+        .expect("Failed to execute uvup add");
+
+    assert!(!add_output.status.success());
+    let stderr = String::from_utf8_lossy(&add_output.stderr);
+    assert!(stderr.contains("No active environment"));
+}
+
+#[test]
+#[ignore = "requires shell integration to set UVUP_ACTIVE_ENV"]
+fn test_remove_package_without_activation() {
+    let remove_output = Command::new("cargo")
+        .args(["run", "--", "remove", "requests"])
+        .output()
+        .expect("Failed to execute uvup remove");
+
+    assert!(!remove_output.status.success());
+    let stderr = String::from_utf8_lossy(&remove_output.stderr);
+    assert!(stderr.contains("No active environment"));
+}
+
+#[test]
+#[ignore = "requires shell integration to set UVUP_ACTIVE_ENV"]
+fn test_lock_without_activation() {
+    let lock_output = Command::new("cargo")
+        .args(["run", "--", "lock"])
+        .output()
+        .expect("Failed to execute uvup lock");
+
+    assert!(!lock_output.status.success());
+    let stderr = String::from_utf8_lossy(&lock_output.stderr);
+    assert!(stderr.contains("No active environment"));
+}
+
+#[test]
+#[ignore = "requires shell integration to set UVUP_ACTIVE_ENV"]
+fn test_tree_without_activation() {
+    let tree_output = Command::new("cargo")
+        .args(["run", "--", "tree"])
+        .output()
+        .expect("Failed to execute uvup tree");
+
+    assert!(!tree_output.status.success());
+    let stderr = String::from_utf8_lossy(&tree_output.stderr);
+    assert!(stderr.contains("No active environment"));
+}
+
+#[test]
+fn test_clone_environment() {
+    let source_env = "test-clone-source";
+    let target_env = "test-clone-target";
+
+    cleanup_test_env(source_env);
+    cleanup_test_env(target_env);
+
+    // Create source environment
+    Command::new("cargo")
+        .args(["run", "--", "create", source_env])
+        .output()
+        .expect("Failed to create source environment");
+
+    // Clone it
+    let clone_output = Command::new("cargo")
+        .args(["run", "--", "clone", source_env, target_env])
+        .output()
+        .expect("Failed to execute uvup clone");
+
+    assert!(clone_output.status.success());
+
+    // Verify target exists
+    let target_path = get_test_env_dir().join(target_env);
+    assert!(target_path.exists());
+    assert!(target_path.join("pyproject.toml").exists());
+    assert!(target_path.join(".venv").exists());
+
+    // Cleanup
+    cleanup_test_env(source_env);
+    cleanup_test_env(target_env);
+}
+
+#[test]
+fn test_clone_nonexistent_environment() {
+    let source_env = "nonexistent-source";
+    let target_env = "test-clone-target-2";
+
+    cleanup_test_env(source_env);
+    cleanup_test_env(target_env);
+
+    let clone_output = Command::new("cargo")
+        .args(["run", "--", "clone", source_env, target_env])
+        .output()
+        .expect("Failed to execute uvup clone");
+
+    assert!(!clone_output.status.success());
+    let stderr = String::from_utf8_lossy(&clone_output.stderr);
+    assert!(stderr.contains("not found") || stderr.contains("does not exist"));
+
+    cleanup_test_env(target_env);
+}