add command, instructions

Author: breardon2011

taco/Makefile

@@ -95,7 +95,7 @@ help: ## Show this help
 # Migration name variable (use with: make atlas-diff-all name=add_new_feature)
 NAME ?= $(shell date +%Y%m%d%H%M%S)
 
-.PHONY: atlas-install atlas-diff-all atlas-apply-all atlas-lint-all atlas-hash-all
+.PHONY: atlas-install atlas-diff-all atlas-plan atlas-apply-all atlas-lint-all atlas-hash-all
 
 # Install Atlas CLI and GORM provider
 atlas-install: ## Install Atlas CLI and GORM provider
@@ -104,6 +104,20 @@ atlas-install: ## Install Atlas CLI and GORM provider
 	@go install ariga.io/atlas-provider-gorm@latest
 	@echo "✅ Atlas tools installed successfully"
 
+# Preview migration changes without generating files
+atlas-plan: ## Preview what migrations would be generated (use: make atlas-plan name=my_change)
+	@echo "Previewing migration changes for all databases..."
+	@if [ -z "$(filter-out $(NAME),$(shell date +%Y%m%d%H%M%S))" ]; then \
+		echo "⚠️  Using auto-generated name: $(NAME)"; \
+		echo "💡 Tip: Use 'make atlas-plan name=descriptive_name' for better naming"; \
+	fi
+	@echo "\n🔐 Generating checksums for existing migrations..."
+	@$(MAKE) atlas-hash-all
+	@echo "\n📊 PostgreSQL (dry-run)..." && atlas migrate diff $(NAME) --env postgres --dry-run || true
+	@echo "\n📊 MySQL (dry-run)..." && atlas migrate diff $(NAME) --env mysql --dry-run || true
+	@echo "\n📊 SQLite (dry-run)..." && atlas migrate diff $(NAME) --env sqlite --dry-run || true
+	@echo "\n✅ Preview complete (no files generated)"
+
 # Generate migrations for all database dialects (Postgres, MySQL, SQLite)
 atlas-diff-all: ## Generate migrations for all databases (use: make atlas-diff-all name=my_change)
 	@echo "Generating migrations for all databases..."

taco/migrations/MIGRATIONS.md

@@ -0,0 +1,47 @@
+# Database Migrations
+
+Atlas-based schema migrations for PostgreSQL, MySQL, and SQLite.
+
+## Quick Reference
+
+```bash
+# Preview changes (dry-run)
+make atlas-plan name=my_change
+
+# Generate migrations
+make atlas-diff-all name=my_change
+
+# Validate migrations
+make atlas-lint-all
+
+# Apply migrations locally
+atlas migrate apply --env postgres
+atlas migrate apply --env mysql  
+atlas migrate apply --env sqlite
+```
+
+## Local Development
+
+### First-time setup
+```bash
+# Install Atlas CLI
+make atlas-install
+
+# Ensure Docker is running (required for Postgres/MySQL dev databases)
+docker info
+```
+
+### Modifying schema
+
+1. Edit GORM models in `internal/query/types/models.go`
+2. Preview changes: `make atlas-plan name=add_user_field`
+3. Generate migrations: `make atlas-diff-all name=add_user_field`
+4. Review generated SQL in `migrations/{postgres,mysql,sqlite}/`
+5. Apply locally: `atlas migrate apply --env [postgres|mysql|sqlite]`
+6. Commit: `git add migrations/ && git commit -m "Add user field migration"`
+
+## Docker/Production
+
+Migrations are **automatically applied** via `scripts/entrypoint.sh` before the app starts.
+
+