# Interactive Guides and Quick Reference (v3.3.0)

## 🚀 Guide System Added (2025-09-30)

A comprehensive interactive guide system providing copy-paste ready commands and step-by-step walkthroughs.

## Available Guides

**Quick Reference:**

- `provisioning sc` - Quick command reference (fastest, no pager)
- `provisioning guide quickstart` - Full command reference with examples

**Step-by-Step Guides:**

- `provisioning guide from-scratch` - Complete deployment from zero to production
- `provisioning guide update` - Update existing infrastructure safely
- `provisioning guide customize` - Customize with layers and templates

**List All Guides:**

- `provisioning guide list` - Show all available guides
- `provisioning howto` - Same as guide list (shortcut)

## Guide Features

- **Copy-Paste Ready**: All commands include placeholders you can adjust
- **Complete Examples**: Full workflows from start to finish
- **Best Practices**: Production-ready patterns and recommendations
- **Troubleshooting**: Common issues and solutions included
- **Shortcuts Reference**: Comprehensive shortcuts for fast operations
- **Beautiful Rendering**: Uses `glow`, `bat`, or `less` for formatted display

## Recommended Setup

For best viewing experience, install `glow` (markdown terminal renderer):

```bash
# macOS
brew install glow

# Ubuntu/Debian
apt install glow

# Fedora
dnf install glow

# Using Go
go install github.com/charmbracelet/glow@latest
```

**Without glow**: Guides fallback to `bat` (syntax highlighting) or `less` (pagination).
**All systems**: Basic pagination always works, even without external tools.

## Quick Start with Guides

```bash
# Show quick reference (fastest)
provisioning sc

# Show full command reference
provisioning guide quickstart

# Step-by-step deployment
provisioning guide from-scratch

# Update infrastructure
provisioning guide update

# Customize with layers
provisioning guide customize

# List all guides
provisioning guide list
```

## Guide Content

**Quick Reference** (`provisioning sc`)

- Condensed command reference (fastest access)
- Essential shortcuts and commands
- Common flags and operations
- No pager, instant display

**Quickstart Guide** (`docs/guides/quickstart-cheatsheet.md`)

- Complete shortcuts reference (80+ mappings)
- Copy-paste command examples
- Common workflows (deploy, update, customize)
- Debug and check mode examples
- Output format options

**From Scratch Guide** (`docs/guides/from-scratch.md`)

- Prerequisites and setup
- Workspace initialization
- Module discovery and configuration
- Server deployment
- Task service installation
- Cluster creation
- Verification steps

**Update Guide** (`docs/guides/update-infrastructure.md`)

- Check for updates
- Update strategies (in-place, rolling, blue-green)
- Task service updates
- Database migrations
- Rollback procedures
- Post-update verification

**Customize Guide** (`docs/guides/customize-infrastructure.md`)

- Layer system explained (Core → Workspace → Infrastructure)
- Using templates
- Creating custom modules
- Configuration inheritance
- Advanced customization patterns

## Access from Help System

The guide system is integrated into the help system:

```bash
# Show guide help
provisioning help guides

# Help topic access
provisioning help guide
provisioning help howto
```

## Guide Shortcuts

| Full Command | Shortcuts |
|--------------|-----------|
| `sc` | - (quick reference, fastest) |
| `guide` | `guides` |
| `guide quickstart` | `shortcuts`, `quick` |
| `guide from-scratch` | `scratch`, `start`, `deploy` |
| `guide update` | `upgrade` |
| `guide customize` | `custom`, `layers`, `templates` |
| `guide list` | `howto` |

## Documentation Location

All guide markdown files are in `guides/`:

- `quickstart-cheatsheet.md` - Quick reference
- `from-scratch.md` - Complete deployment
- `update-infrastructure.md` - Update procedures
- `customize-infrastructure.md` - Customization patterns
