docs: add micro run documentation with hot reload and config file guide

- Update main README with micro run quick start
- Expand cmd/micro/README.md with configuration options
- Add detailed guide at internal/website/docs/guides/micro-run.md

Documents:
- Hot reload with file watching
- micro.mu DSL configuration
- micro.json alternative
- Dependency ordering
- Environment management
- Graceful shutdown

Co-authored-by: Shelley <shelley@exe.dev>

README.md

@@ -122,14 +122,53 @@ go install go-micro.dev/v5/cmd/protoc-gen-micro@latest
 
 Docs: [`internal/website/docs/getting-started.md`](internal/website/docs/getting-started.md)
 
-## Command line
+## Command Line
 
-Install the CLI and see usage in the docs:
+Install the CLI:
 
 ```
 go install go-micro.dev/v5/cmd/micro@latest
 ```
 
+### Quick Start
+
+```bash
+micro new helloworld   # Create a new service
+cd helloworld
+micro run              # Run with hot reload
+```
+
+### micro run
+
+Run services with hot reload, dependency ordering, and environment management:
+
+```bash
+micro run                    # Hot reload enabled
+micro run --no-watch         # Disable hot reload
+micro run --env production   # Use production environment
+```
+
+For multi-service projects, create a `micro.mu` configuration file:
+
+```
+service users
+    path ./users
+    port 8081
+
+service api
+    path ./api
+    port 8080
+    depends users
+
+env development
+    DATABASE_URL sqlite://./dev.db
+
+env production
+    DATABASE_URL postgres://...
+```
+
+See [cmd/micro/README.md](cmd/micro/README.md) for full CLI documentation.
+
 Docs: [`internal/website/docs`](internal/website/docs)
 
 Package reference: https://pkg.go.dev/go-micro.dev/v5

cmd/micro/README.md

@@ -27,18 +27,97 @@ This will:
 
 ## Run the service
 
-Run the service
+Run the service with hot reload:
 
 ```
 micro run
 ```
 
-List services to see it's running and registered itself
+This will:
+- Watch for file changes and auto-rebuild/restart
+- Start services in dependency order (if configured)
+- Apply environment-specific settings
+
+Options:
+```
+micro run                    # Hot reload enabled (default)
+micro run --no-watch         # Disable hot reload
+micro run --env production   # Use production environment
+micro run ./path/to/service  # Run specific directory
+micro run github.com/micro/blog  # Clone and run from GitHub
+```
+
+List services to see it's running and registered itself:
 
 ```
 micro services
 ```
 
+## Configuration (micro.mu)
+
+For multi-service projects, create a `micro.mu` file to define services, dependencies, and environments:
+
+```
+service users
+    path ./users
+    port 8081
+
+service posts
+    path ./posts
+    port 8082
+    depends users
+
+service web
+    path ./web
+    port 8089
+    depends users posts
+
+env development
+    STORE_ADDRESS file://./data
+    DEBUG true
+
+env production
+    STORE_ADDRESS postgres://localhost/db
+```
+
+### Configuration Options
+
+| Property | Description |
+|----------|-------------|
+| `path` | Directory containing the service (with main.go) |
+| `port` | Port the service listens on (for health checks) |
+| `depends` | Services that must start first (space-separated) |
+
+### Environment Management
+
+Environment variables are injected based on the `--env` flag:
+
+```
+micro run                    # Uses 'development' env (default)
+micro run --env production   # Uses 'production' env
+MICRO_ENV=staging micro run  # Uses 'staging' env
+```
+
+### JSON Alternative
+
+You can also use `micro.json` if you prefer:
+
+```json
+{
+  "services": {
+    "users": { "path": "./users", "port": 8081 },
+    "posts": { "path": "./posts", "port": 8082, "depends": ["users"] }
+  },
+  "env": {
+    "development": { "STORE_ADDRESS": "file://./data" }
+  }
+}
+```
+
+### Without Configuration
+
+If no `micro.mu` or `micro.json` exists, `micro run` discovers all `main.go` files and runs them (original behavior).
+
 ## Describe the service
 
 Describe the service to see available endpoints

internal/website/docs/guides/micro-run.md

@@ -0,0 +1,191 @@
+---
+layout: default
+---
+
+# micro run - Local Development
+
+`micro run` provides a Rails/Spring-like development experience for Go microservices.
+
+## Quick Start
+
+```bash
+# Run services in current directory with hot reload
+micro run
+
+# Run from a specific directory
+micro run ./myapp
+
+# Clone and run from GitHub
+micro run github.com/micro/blog
+```
+
+## Features
+
+### Hot Reload
+
+By default, `micro run` watches for `.go` file changes and automatically rebuilds and restarts affected services.
+
+```bash
+micro run              # Hot reload enabled (default)
+micro run --no-watch   # Disable hot reload
+```
+
+Changes are debounced (300ms) to handle rapid saves from editors.
+
+### Configuration File
+
+For multi-service projects, create a `micro.mu` file to define services, dependencies, and environments.
+
+#### micro.mu (Recommended)
+
+```
+# Service definitions
+service users
+    path ./users
+    port 8081
+
+service posts
+    path ./posts
+    port 8082
+    depends users
+
+service web
+    path ./web
+    port 8089
+    depends users posts
+
+# Environment configurations
+env development
+    STORE_ADDRESS file://./data
+    DEBUG true
+
+env production
+    STORE_ADDRESS postgres://localhost/db
+    DEBUG false
+```
+
+#### micro.json (Alternative)
+
+```json
+{
+  "services": {
+    "users": {
+      "path": "./users",
+      "port": 8081
+    },
+    "posts": {
+      "path": "./posts",
+      "port": 8082,
+      "depends": ["users"]
+    }
+  },
+  "env": {
+    "development": {
+      "STORE_ADDRESS": "file://./data"
+    }
+  }
+}
+```
+
+### Service Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `path` | Yes | Directory containing the service (with main.go) |
+| `port` | No | Port the service listens on (enables health check waiting) |
+| `depends` | No | Services that must start first (space-separated in .mu, array in .json) |
+
+### Dependency Ordering
+
+When `depends` is specified, services start in topological order:
+
+1. Services with no dependencies start first
+2. Each service waits for its dependencies to be ready
+3. If a service has a `port`, we wait for `/health` to return 200
+4. Circular dependencies are detected and reported as errors
+
+### Environment Management
+
+```bash
+micro run                    # Uses 'development' (default)
+micro run --env production   # Uses 'production'
+micro run --env staging      # Uses 'staging'
+MICRO_ENV=test micro run     # Environment variable override
+```
+
+Environment variables from the config are injected into each service's environment.
+
+### Graceful Shutdown
+
+On SIGINT (Ctrl+C) or SIGTERM:
+
+1. Services stop in reverse dependency order
+2. SIGTERM is sent first (graceful)
+3. After 5 seconds, SIGKILL if still running
+4. PID files are cleaned up
+
+## Without Configuration
+
+If no `micro.mu` or `micro.json` exists:
+
+1. All `main.go` files are discovered recursively
+2. Each is built and run
+3. No dependency ordering
+4. Hot reload still works
+
+## Logs
+
+Service logs are written to:
+- Terminal: Colorized with service name prefix
+- File: `~/micro/logs/{service}-{hash}.log`
+
+View logs:
+```bash
+micro logs          # List available logs
+micro logs users    # Show logs for 'users' service
+```
+
+## Process Management
+
+```bash
+micro status        # Show running services
+micro stop users    # Stop a specific service
+```
+
+## Example: micro/blog
+
+The [micro/blog](https://github.com/micro/blog) project demonstrates a multi-service setup:
+
+```
+# micro.mu
+service users
+    path ./users
+    port 8081
+
+service posts
+    path ./posts
+    port 8082
+    depends users
+
+service comments
+    path ./comments
+    port 8083
+    depends users posts
+
+service web
+    path ./web
+    port 8089
+    depends users posts comments
+```
+
+Run it:
+```bash
+micro run github.com/micro/blog
+```
+
+## Tips
+
+1. **Port Configuration**: Set `port` for services that expose HTTP to enable health check waiting
+2. **Health Endpoint**: Implement `/health` returning 200 for reliable startup sequencing
+3. **Environment Separation**: Keep secrets in production env, use file:// paths for development
+4. **Hot Reload Scope**: Only `.go` files trigger rebuilds; static assets don't