docs: Add Flash documentation

.cursor/rules/rp-styleguide.mdc

@@ -5,7 +5,7 @@ alwaysApply: true
 ---
 
 Always use sentence case for headings and titles.
-These are proper nouns: Runpod, Pods, Serverless, Hub, Instant Clusters, Secure Cloud, Community Cloud, Tetra.
+These are proper nouns: Runpod, Pods, Serverless, Hub, Instant Clusters, Secure Cloud, Community Cloud, Flash.
 These are generic terms: endpoint, worker, cluster, template, handler, fine-tune, network volume.
 
 Prefer using paragraphs to bullet points unless directly asked.

CLAUDE.md

@@ -98,7 +98,7 @@ Follow the Runpod style guide (`.cursor/rules/rp-styleguide.mdc`) and Google Dev
 ### Capitalization and Terminology
 
 - **Always use sentence case** for headings and titles
-- **Proper nouns**: Runpod, Pods, Serverless, Hub, Instant Clusters, Secure Cloud, Community Cloud, Tetra
+- **Proper nouns**: Runpod, Pods, Serverless, Hub, Instant Clusters, Secure Cloud, Community Cloud, Flash
 - **Generic terms** (lowercase): endpoint, worker, cluster, template, handler, fine-tune, network volume
 
 ### Writing Style

docs.json

@@ -118,6 +118,42 @@
               }
             ]
           },
+          {
+            "group": "Flash",
+            "pages": [
+              "flash/overview",
+              "flash/quickstart",
+              "flash/pricing",
+              "flash/remote-functions",
+              "flash/resource-configuration",
+              "flash/monitoring",
+              "flash/custom-docker-images",
+              {
+                "group": "Build apps",
+                "pages": [
+                  "flash/apps/overview",
+                  "flash/apps/build-app",
+                  "flash/apps/initialize-project",
+                  "flash/apps/local-testing",
+                  "flash/apps/apps-and-environments",
+                  "flash/apps/deploy-apps"
+                ]
+              },
+              {
+                "group": "CLI reference",
+                "pages": [
+                  "flash/cli/overview",
+                  "flash/cli/init",
+                  "flash/cli/run",
+                  "flash/cli/build",
+                  "flash/cli/deploy",
+                  "flash/cli/env",
+                  "flash/cli/app",
+                  "flash/cli/undeploy"
+                ]
+              }
+            ]
+          },
           {
             "group": "Pods",
             "pages": [
@@ -357,6 +393,13 @@
               "tutorials/serverless/run-gemma-7b"
             ]
           },
+          {
+            "group": "Flash",
+            "pages": [
+              "tutorials/flash/text-generation-with-transformers",
+              "tutorials/flash/image-generation-with-sdxl"
+            ]
+          },
           {
             "group": "Pods",
             "pages": [

flash/apps/apps-and-environments.mdx

@@ -0,0 +1,207 @@
+---
+title: "Manage apps and environments"
+sidebarTitle: "Manage apps and environments"
+description: "Manage Flash apps and environments with the flash app and flash env commands."
+tag: "BETA"
+---
+
+This page covers practical commands and workflows for managing Flash apps and environments. For a conceptual overview of the deployment hierarchy, see the [development lifecycle guide](/flash/apps/overview).
+
+## Flash apps
+
+A **Flash app** is a namespace registered on Runpod's backend that groups all resources for a single project, including environments, builds, and configuration. The app itself is just metadata—actual cloud resources (endpoints, volumes) are created when you deploy to an environment.
+
+### App hierarchy
+
+```text
+Flash App (my-project)
+│
+├── Environments
+│   ├── dev
+│   │   ├── Endpoints (gpu-worker, cpu-worker)
+│   │   └── Volumes (model-cache)
+│   ├── staging
+│   │   ├── Endpoints (gpu-worker, cpu-worker)
+│   │   └── Volumes (model-cache)
+│   └── production
+│       ├── Endpoints (gpu-worker, cpu-worker)
+│       └── Volumes (model-cache)
+│
+└── Builds
+    ├── build_v1 (2024-01-15)
+    ├── build_v2 (2024-01-18)
+    └── build_v3 (2024-01-20)
+```
+
+### Creating apps
+
+Apps are created automatically when you first run `flash deploy`. You can also register them explicitly:
+
+```bash
+flash app create APP_NAME
+```
+
+This registers the app namespace on Runpod's backend but doesn't create any cloud resources or local files.
+
+### Managing apps
+
+Use `flash app` commands to manage your apps:
+
+```bash
+# List all apps
+flash app list
+
+# Get app details
+flash app get APP_NAME
+
+# Delete an app and all its resources
+flash app delete --app APP_NAME
+```
+
+<Warning>
+
+Deleting an app removes all environments, builds, endpoints, and volumes associated with it. This operation is irreversible.
+
+</Warning>
+
+## Understanding builds and deployments
+
+When you run `flash deploy`, three things happen on Runpod:
+
+### 1. Build artifact is uploaded
+
+Flash creates a **tarball** (`.flash/artifact.tar.gz`) containing:
+
+- Your Python code (`main.py`, `workers/`, etc.).
+- Pre-installed dependencies (bundled during build).
+- Deployment manifest (`flash_manifest.json`).
+- Auto-generated handler code.
+
+This tarball is uploaded to Runpod's storage and associated with your app as a "build."
+
+### 2. Serverless endpoints are provisioned
+
+For each resource in the manifest, Flash creates a Serverless endpoint:
+
+**Mothership endpoint** (Load-Balanced):
+
+- Runs your FastAPI app from `main.py`.
+- Provides the public HTTPS URL for users.
+- Orchestrates calls to worker endpoints.
+- Uses pre-built image: `runpod/flash-lb-cpu:latest`
+
+**Worker endpoints** (Queue-Based):
+
+- Execute your `@remote` functions.
+- Scale automatically based on load.
+- Run on GPUs or CPUs based on configuration.
+- Uses pre-built images: `runpod/flash:latest` (GPU) or `runpod/flash-cpu:latest` (CPU).
+
+### 3. Environment is activated
+
+The environment is linked to:
+
+- The uploaded build (specific version of your code).
+- The provisioned endpoints (running infrastructure).
+- Deployment state (health, status, metrics).
+
+**Key insight:** You're **not** building custom Docker images. The Flash images are pre-built and generic—they extract your tarball and run your code. This is why deployments are fast (no image build step) and limited to 500 MB (only code and dependencies, not full Docker images).
+
+## Environments
+
+An **environment** is an isolated deployment stage within a Flash app (e.g., `dev`, `staging`, `production`). Each environment has its own endpoints, build version, volumes, and deployment state. Environments are completely independent.
+
+### Creating environments
+
+Environments are created automatically when you deploy with `--env`:
+
+```bash
+# Creates 'staging' environment if it doesn't exist
+flash deploy --env staging
+```
+
+You can also create them explicitly:
+
+```bash
+flash env create staging
+```
+
+### Managing environments
+
+Use `flash env` commands to manage environments:
+
+```bash
+# List all environments
+flash env list
+
+# Get environment details
+flash env get production
+
+# Delete an environment
+flash env delete dev
+```
+
+### Environment states
+
+| State | Description |
+|-------|-------------|
+| PENDING | Environment created but not deployed |
+| DEPLOYING | Deployment in progress |
+| DEPLOYED | Successfully deployed and running |
+| FAILED | Deployment or health check failed |
+| DELETING | Deletion in progress |
+
+## Best practices
+
+### Naming conventions
+
+Use clear, descriptive names:
+
+```bash
+# Good
+flash env create dev
+flash env create staging
+flash env create production
+
+# Avoid
+flash env create env1
+flash env create test123
+```
+
+### Environment strategy
+
+**Three-tier approach** (recommended for teams):
+
+| Environment | Purpose |
+|-------------|---------|
+| `dev` | Active development, frequent deploys |
+| `staging` | Pre-production testing, QA validation |
+| `production` | Live user-facing deployment |
+
+**Simple approach** (small projects):
+
+| Environment | Purpose |
+|-------------|---------|
+| `dev` | Development and testing |
+| `production` | Live deployment |
+
+### Workflow recommendations
+
+1. **Develop locally**: Test with `flash run` before deploying.
+2. **Deploy to dev**: `flash deploy --env dev` for initial testing.
+3. **Deploy to staging**: `flash deploy --env staging` for QA.
+4. **Deploy to production**: `flash deploy --env production` after approval.
+
+### Resource management
+
+- Monitor environments regularly with `flash env list`
+- Clean up unused environments to avoid resource accumulation.
+- Check resource usage with `flash env get <name>`
+- Delete environments carefully as deletion is irreversible.
+
+## Next steps
+
+- [Deploy your first app](/flash/apps/deploy-apps) with `flash deploy`
+- [Learn about the CLI](/flash/cli/overview) for all available commands.
+- [View the env command reference](/flash/cli/env) for detailed options.
+- [View the app command reference](/flash/cli/app) for detailed options.