docs: Promote cloud guides into a Concepts section

cloud_docs/02-concepts/01-deployments.md

@@ -15,18 +15,13 @@ Deploy your project to Cloud:
 scloud deploy
 ```
 
-The CLI packages your project, uploads it, kicks off the build, and prints URLs you can access once the deployment is live:
+The CLI packages your project, uploads it, and tails the build through four lifecycle stages until the new version is serving traffic. Once the deployment is live, your project is reachable at its default URLs:
 
-```text
-✓ Project uploaded successfully! 🚀
-
-When the server has started, you can access it at:
-  Web:      https://my-app.serverpod.space/
-  API:      https://my-app.api.serverpod.space/
-  Insights: https://my-app.insights.serverpod.space/
+- Web: `https://<project-id>.serverpod.space/`
+- API: `https://<project-id>.api.serverpod.space/`
+- Insights: `https://<project-id>.insights.serverpod.space/`
 
-See `scloud domain --help` to set up a custom domain.
-```
+Set up your own URL with the [`scloud domain`](/cloud/reference/cli/commands/domain) command. See [Custom domains](/cloud/concepts/custom-domains).
 
 Other flags:
 
@@ -44,18 +39,19 @@ Watch the latest deployment as it runs:
 scloud deployment show
 ```
 
-The command prints a real-time lifecycle update:
+The command tracks the deployment through four stages and updates each line as it progresses:
 
 ```text
-Tracking status of my-app deploy 4583d0a1-3d0a-400e-a9a5-9880da6abc94, started at 2026-06-03 13:41:21:
+Tracking my-app deployment 4583d0a1-3d0a-400e-a9a5-9880da6abc94
+(Press Ctrl+C to exit)
 
-✓ Booster liftoff:      Upload successful!
-✓ Orbit acceleration:   Build successful!
-✓ Orbital insertion:    Deploy successful!
-✓ Pod commissioning:    Service successful! 🚀
+Upload successful.
+Cloud build successful.
+Infra deploy successful.
+Service rollout successful. 🚀
 ```
 
-The output marks each of the four lifecycle stages: **Booster liftoff** (upload), **Orbit acceleration** (build), **Orbital insertion** (deploy), and **Pod commissioning** (service ready).
+The stages: **Upload** (your project package reaches Cloud), **Cloud build** (Cloud builds the container), **Infra deploy** (the new version rolls out), and **Service rollout** (the new version takes traffic).
 
 List recent deployments:
 

cloud_docs/02-concepts/02-logs.md

@@ -0,0 +1,142 @@
+---
+title: Logs
+description: How Serverpod Cloud surfaces logs through Insights, the scloud CLI for terminal access and filtering, and session-log configuration.
+---
+
+# Logs
+
+Serverpod Cloud collects logs from your running app and from each deployment's build, and surfaces them in two places: Serverpod Insights, a visual log viewer in the Cloud console; and the `scloud` CLI, which gives terminal access to runtime logs (with rich filtering) and is the only path to build logs from failed deploys.
+
+Insights is usually the right starting point for understanding what your app is doing because logs are grouped by session. The CLI is faster for one-off checks, supports filtering by time, and is the source of truth for build-time output.
+
+## View logs in Insights
+
+Open Insights from the Cloud console once a project is deployed. Sessions appear in a chronological list; selecting one expands into its messages, errors, and (when enabled per project) the database queries the session ran and the stack traces for any caught exceptions. Query logging and stack-trace capture add overhead, so they're off by default.
+
+:::tip
+
+Use Serverpod Insights for root-cause analysis. The session-grouped view makes it straightforward to follow a single request end-to-end, which is harder to do from terminal output.
+
+:::
+
+## View build logs
+
+Build logs are emitted while Cloud builds your deployment package: package installation, compilation, warnings, and errors. They're the first place to look when a deploy fails. Fetch the latest build log:
+
+```bash
+scloud deployment build-log
+```
+
+Pass a sequence number (where `0` is the latest) or a UUID to inspect a specific deployment; `scloud deployment list` shows the IDs:
+
+```bash
+scloud deployment build-log 3
+scloud deployment build-log 550e8400-e29b-41d4-a716-446655440000
+```
+
+For longer build logs, redirect to a file or filter inline:
+
+```bash
+scloud deployment build-log > build-log.txt
+scloud deployment build-log | grep ERROR
+```
+
+## View runtime logs
+
+Runtime logs are the live output of your deployed service. Each entry contains:
+
+- **Timestamp**: local time by default, UTC with `--utc`
+- **Level**: `INFO`, `ERROR`, and so on
+- **Origin service**: `API`, `insights`, or `web`
+- **Message body**
+
+Fetch the most recent records:
+
+```bash
+scloud log
+```
+
+By default this returns 50 records. Use `--limit` to fetch more (or fewer):
+
+```bash
+scloud log --limit 100
+```
+
+Pass `--utc` for UTC timestamps (useful when collaborating across time zones):
+
+```bash
+scloud log --utc
+```
+
+Pipe to standard shell tools for further filtering, or redirect to a file for sharing:
+
+```bash
+scloud log | grep ERROR
+scloud log > project_logs.txt
+```
+
+## Filter logs by time
+
+The `--since` and `--until` options accept either duration strings or ISO 8601 timestamps.
+
+Duration strings cover recent windows:
+
+```bash
+scloud log 120s              # last 120 seconds
+scloud log 5m                # last 5 minutes
+scloud log 12h               # last 12 hours
+scloud log 7d                # last 7 days
+scloud log --since 1h --until 10m
+```
+
+ISO 8601 strings allow specific times:
+
+```bash
+scloud log --since "2026-06-15T14:00:00Z"
+scloud log --since "2026-06-15T14:00:00Z" --until "2026-06-15T16:00:00Z"
+```
+
+Lower-precision ISO forms are also accepted:
+
+```bash
+scloud log --since "2026-06-15T14:00"     # without seconds
+scloud log --since "2026-06-15T14"        # without minutes and seconds
+scloud log --since "2026-06-15"           # just the date (starts at 00:00:00)
+```
+
+Duration and ISO forms can be mixed:
+
+```bash
+scloud log --since "2026-06-15T14:00:00Z" --until 30m
+scloud log --since 1h --until "2026-06-15T16:00:00Z"
+```
+
+## Stream logs
+
+Follow new log records as they arrive:
+
+```bash
+scloud log --tail
+```
+
+Press `Ctrl+C` to stop. `--tail` cannot be combined with `--since` or `--until`.
+
+## Configure session logging
+
+Two environment variables control how each request's session logs are handled. By default:
+
+- `SERVERPOD_SESSION_CONSOLE_LOG_ENABLED` defaults to `true`. Session logs print to the runtime console.
+- `SERVERPOD_SESSION_PERSISTENT_LOG_ENABLED` defaults to `false`. Session logs are not written to the database for later inspection.
+
+To change either default, set the value with `scloud variable set`. See [Passwords, secrets, and environment variables](/cloud/concepts/passwords-secrets-env-vars) for variable management.
+
+## Troubleshooting
+
+**Invalid timestamp format.** Use ISO 8601 form (`YYYY-MM-DDTHH:MM:SSZ`) or a supported duration string (`5m`, `2h`, `1d`).
+
+**No logs appearing.** Check that the time range is correct, that the app is running and generating output, and (for `--tail`) that you haven't also passed `--since` or `--until`.
+
+## Related
+
+- [CLI reference: `log` command](/cloud/reference/cli/commands/log)
+- [CLI reference: `deployment` command](/cloud/reference/cli/commands/deployment)

cloud_docs/02-concepts/03-passwords-secrets-env-vars.md

@@ -0,0 +1,147 @@
+---
+title: Passwords, secrets, and environment variables
+description: "Serverpod Cloud has three configuration tiers: encrypted passwords via the Serverpod API, encrypted secrets as named env vars, and plaintext variables."
+---
+
+# Passwords, secrets, and environment variables
+
+Serverpod Cloud has three tiers for project configuration. Passwords are encrypted and accessed through Serverpod's `getPassword()` API. Secrets are encrypted and injected as environment variables under a name you choose. Variables are plaintext, for non-sensitive configuration.
+
+|                       | Passwords                                              | Secrets                                                    | Variables                                               |
+| --------------------- | ------------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------- |
+| **CLI**               | `scloud password`                                      | `scloud secret`                                            | `scloud variable`                                       |
+| **Stored as**         | Env var with `SERVERPOD_PASSWORD_` prefix              | Env var (any name)                                         | Env var (any name)                                      |
+| **Encrypted**         | Yes                                                    | Yes                                                        | No (values visible in CLI and dashboard)                |
+| **Access in code**    | `session.serverpod.getPassword('name')`                | `Platform.environment['NAME']`                             | `Platform.environment['NAME']`                          |
+| **Use when**          | Serverpod code reads the value (preferred for secrets) | A dependency reads env vars and cannot use `getPassword()` | Non-sensitive config (URLs, feature flags)              |
+
+All three commands follow the same shape:
+
+- **`--name`** (mandatory): positional or as a flag
+- **Value**: positional, `--value`, or `--from-file`
+- **`-p, --project`**: required only when the project isn't linked
+- **`set` is create-or-update**: running it again with the same name overwrites the value
+
+## Manage passwords
+
+Passwords are the default tier for sensitive values the server reads through the Serverpod API. They are encrypted at rest, never shown after they're set, and accessed in code by the name you gave them. Each password is stored under a `SERVERPOD_PASSWORD_` prefix that the CLI adds on `set` and that `getPassword()` strips on read, so the name in your code stays clean.
+
+Serverpod Cloud also provisions a set of platform-managed passwords automatically: database credentials, Insights tokens, `serverpod_auth_idp_server` keys, and keys for the legacy auth module. `scloud password list` groups them into four categories: **Custom** (passwords you add), **Services** (database, Insights, and related platform passwords), **Auth** (passwords for `serverpod_auth_idp_server`), and **Legacy Auth** (passwords for the legacy authentication module). The Status column marks platform-managed passwords `AUTO (Platform)` and user-set ones `SET (User)`.
+
+Override a platform-managed password by setting a custom value with the same name. Unset it to restore the platform default.
+
+Set a password by name and value:
+
+```bash
+scloud password set myApiKey "your_secret_value"
+```
+
+Read the value in code:
+
+```dart
+final apiKey = await session.serverpod.getPassword('myApiKey');
+```
+
+Pass `--from-file` when the value is long, multi-line, or shouldn't appear in shell history:
+
+```bash
+scloud password set myApiKey --from-file path/to/file.txt
+```
+
+List all configured passwords:
+
+```bash
+scloud password list
+```
+
+Remove a user-added password:
+
+```bash
+scloud password unset myApiKey
+```
+
+## Manage secrets
+
+Secrets are the right tier when a library or dependency reads a value from `Platform.environment['SOMETHING']` and can't use the Serverpod API. They're encrypted at rest and never shown in the CLI after creation.
+
+Set a secret by name and value:
+
+```bash
+scloud secret set API_KEY "your_secret_value"
+```
+
+Read the value in code:
+
+```dart
+final apiKey = Platform.environment['API_KEY'];
+```
+
+Pass `--from-file` for long, multi-line, or sensitive values you don't want in shell history:
+
+```bash
+scloud secret set API_KEY --from-file path/to/file.txt
+```
+
+List configured secrets:
+
+```bash
+scloud secret list
+```
+
+Remove a secret:
+
+```bash
+scloud secret unset API_KEY
+```
+
+## Manage environment variables
+
+Variables are for non-sensitive configuration: URLs, feature flags, region names, or other settings that don't need encryption. Values are stored in plaintext and visible in the CLI and the Cloud console.
+
+Set a variable by name and value:
+
+```bash
+scloud variable set LOG_LEVEL "info"
+```
+
+Read the value in code:
+
+```dart
+final logLevel = Platform.environment['LOG_LEVEL'];
+```
+
+Pass `--from-file` to load the value from a file:
+
+```bash
+scloud variable set LOG_LEVEL --from-file path/to/file.txt
+```
+
+List configured variables:
+
+```bash
+scloud variable list
+```
+
+Remove a variable:
+
+```bash
+scloud variable unset LOG_LEVEL
+```
+
+:::warning
+
+Do not use variables for API keys, tokens, or passwords. Use passwords or secrets for sensitive data.
+
+:::
+
+## Limits
+
+The same naming and size rules apply across all three tiers:
+
+- Names use letters (`a-z`, `A-Z`), digits (`0-9`), and underscores (`_`) only, and must start with a letter or underscore.
+- Maximum name length is 255 characters.
+- Variables and secrets each have a separate per-project storage budget of 64,000 bytes (the total of all names plus values within that tier). Passwords share the secrets budget because they're stored as secrets under the `SERVERPOD_PASSWORD_` prefix.
+
+## Related
+
+- CLI reference: [`password`](/cloud/reference/cli/commands/password), [`secret`](/cloud/reference/cli/commands/secret), [`variable`](/cloud/reference/cli/commands/variable)