docs(cloud): Reframe PAT and deployment hooks as concepts, non-Dart files as a guide

cloud_docs/01-getting-started/02-launch.md

@@ -28,7 +28,7 @@ It creates a Cloud project and ships its first version. The CLI walks you throug
 - **Project ID.** scloud suggests a default from your pubspec name (for example, `my-app`). Press Enter to accept, or type a different ID. The project ID becomes part of your default URL (`<project-id>.serverpod.space`).
 - **Plan.** Type `starter` or `growth` (see [Cloud plans](https://serverpod.dev/cloud) for details). Pick `starter` for a first deploy. Starter includes a 1-month free trial; no credit card required.
 - **Database.** Press Enter for yes if you want Cloud to provision and manage a Postgres database for your server. Type `n` if your app doesn't need a database, or if you plan to connect to your own.
-- **Pre-deploy hooks.** Hooks run scripts before each deploy. scloud may offer to add `serverpod generate` and a Flutter build hook (if your project defines one). Accept the ones that match your project. See [Deployment hooks](/cloud/reference/deployment/deployment-hooks) for details.
+- **Pre-deploy hooks.** Hooks run scripts before each deploy. scloud may offer to add `serverpod generate` and a Flutter build hook (if your project defines one). Accept the ones that match your project. See [Deployment hooks](/cloud/concepts/deployment-hooks) for details.
 
 After the final confirmation, scloud creates the Cloud project, writes a `scloud.yaml` linking subsequent commands to it, uploads your code, and starts the deploy.
 

cloud_docs/02-concepts/01-deployments.md

@@ -33,7 +33,7 @@ Other flags:
 - `--dart-version`: override the Dart SDK used at build time.
 - `--concurrency=<N>`: how many files are zipped in parallel during packaging (default `5`).
 
-To regenerate code or run other tasks before each deploy, configure a pre-deploy hook. See [Deployment hooks](/cloud/reference/deployment/deployment-hooks).
+To regenerate code or run other tasks before each deploy, configure a pre-deploy hook. See [Deployment hooks](/cloud/concepts/deployment-hooks).
 
 ## Check deployment status
 
@@ -157,7 +157,7 @@ Common causes are missing dependencies in `pubspec.yaml` or compile errors in yo
 
 ## Related
 
-- [Deployment hooks](/cloud/reference/deployment/deployment-hooks) for pre- and post-deploy automation.
+- [Deployment hooks](/cloud/concepts/deployment-hooks) for pre- and post-deploy automation.
 - [Handling private dependencies](/cloud/reference/deployment/handling-private-dependencies) for private package access during the build.
-- [Including non-Dart files](/cloud/reference/deployment/assets) for static assets.
+- [Ship non-Dart files with your server](/cloud/guides/ship-non-dart-files) for shipping static assets like configuration and templates.
 - [Automate deployment with GitHub Actions](/cloud/reference/deployment/github-automation) for CI/CD setups.

cloud_docs/02-concepts/06-personal-access-tokens.md

@@ -0,0 +1,139 @@
+---
+sidebar_label: Personal access tokens
+description: Create personal access tokens to authenticate scloud in CI pipelines, scripts, and headless environments without interactive login.
+---
+
+# Personal access tokens
+
+Personal access tokens let you authenticate the Serverpod Cloud CLI without interactive login. Use them in CI pipelines, scripts, or headless environments where you cannot run `scloud auth login`.
+
+## When to use tokens
+
+Use a personal access token when:
+
+- Running `scloud` in a CI/CD pipeline (GitHub Actions, GitLab CI, and so on).
+- Automating deploys or other `scloud` commands from a script or cron job.
+- Using `scloud` on a server or container with no browser for interactive login.
+
+For everyday development on your machine, `scloud auth login` is simpler; it stores credentials locally and you don't need to handle tokens.
+
+## Create a token
+
+Sign in first, then run:
+
+```bash
+scloud auth create-token
+```
+
+Example output:
+
+```text
+✅ Successfully created an API token.
+
+Use the --token option or the SERVERPOD_CLOUD_TOKEN environment variable to
+authenticate with this token in scloud commands.
+
+The token is only visible once:
+c2FzAZxXRnzFeN2xTo6xVInh3k3bNanACBRM7ux5AYOLQDgzK82PZvdRn0N_f2WqLPCZ
+```
+
+:::warning
+
+The CLI prints the token once. Store it somewhere secure (a secret in your CI system, a password manager). It can't be retrieved again.
+
+:::
+
+### Token expiration
+
+By default, tokens expire after 30 days of non-use. Adjust this when creating the token:
+
+```bash
+# Expire after 7 days of non-use
+scloud auth create-token --idle-ttl 7d
+
+# Never expire from non-use (still valid until revoked or until --expire-at)
+scloud auth create-token --no-idle-ttl
+
+# Expire at a fixed ISO 8601 time
+scloud auth create-token --expire-at 2026-12-31T23:59:59Z
+```
+
+Durations accept `s`, `m`, `h`, and `d` units.
+
+## List authentication sessions
+
+To see your active sessions and tokens with their IDs, creation, last-used, and expiry times:
+
+```bash
+scloud auth list
+```
+
+Use the Token Id column to identify a token before revoking it.
+
+## Revoke a token
+
+Revoke a specific token by its ID from `scloud auth list`:
+
+```bash
+scloud auth logout --token-id <token-id>
+```
+
+Log out the current session instead:
+
+```bash
+scloud auth logout
+```
+
+Revoke every session and token at once:
+
+```bash
+scloud auth logout --all
+```
+
+A revoked token can no longer authenticate.
+
+## Use a token with scloud
+
+The CLI accepts a token two ways. For CI pipelines and shell sessions, prefer the `SERVERPOD_CLOUD_TOKEN` environment variable. The `--token` flag is a per-command override.
+
+### Environment variable
+
+Set the variable once so every subsequent `scloud` call in that shell uses the token:
+
+```bash
+export SERVERPOD_CLOUD_TOKEN="your-token-here"
+scloud deploy
+scloud log
+```
+
+Best for CI pipelines and shell sessions where you set the secret once and run multiple commands.
+
+### Command-line flag
+
+Pass the token directly to any command:
+
+```bash
+scloud --token="your-token-here" deploy
+scloud --token="your-token-here" log
+```
+
+The flag applies only to that command. Useful when the token lives in a script variable or a short-lived secret.
+
+If both `--token` and `SERVERPOD_CLOUD_TOKEN` are set, `--token` takes precedence.
+
+## Use a token in GitHub Actions
+
+Store the token as a repository secret, then pass it to the official action:
+
+```yaml
+- uses: serverpod/serverpod_cloud_deploy@v1
+  with:
+    token: ${{ secrets.SERVERPOD_CLOUD_TOKEN }}
+```
+
+A full setup walkthrough lives in the [serverpod_cloud_deploy action README](https://github.com/serverpod/serverpod_cloud_deploy).
+
+## Related
+
+- [`scloud auth`](/cloud/reference/cli/commands/auth) for the full reference on `auth login`, `create-token`, `list`, and `logout`.
+- [CLI environment variables](/cloud/reference/cli/env_vars) for all `scloud` environment variables.

cloud_docs/02-concepts/07-deployment-hooks.md

@@ -0,0 +1,66 @@
+---
+title: Deployment hooks
+description: Run custom scripts at fixed points in a Serverpod Cloud deploy. Pre-deploy hooks handle setup like code generation; post-deploy hooks send notifications.
+---
+
+# Deployment hooks
+
+Deployment hooks let you run your own scripts at fixed points during a deploy. Use them to build a Flutter web client, regenerate Serverpod code, run database migrations, send a Slack notification on release, or any other custom step that has to happen before or after Cloud receives your project. Without hooks, those steps live in a separate command you remember to run yourself.
+
+## When to use hooks
+
+Hooks come in two shapes:
+
+- **`pre_deploy`** for anything that has to run *before* Cloud receives your project (regenerate Serverpod code, build a Flutter web client, compile non-Dart assets, run database migration scripts, run a test suite as a deploy gate).
+- **`post_deploy`** for anything that should fire *after* the upload completes (Slack notification, kick a downstream pipeline, mark a release in your tracker).
+
+If your deploy doesn't depend on either, don't add hooks. Deploys work without them.
+
+## Configure hooks
+
+Hooks live in `scloud.yaml` under `project.scripts`. Each hook accepts either a single command (string) or a list of commands (array).
+
+Single command:
+
+```yaml
+project:
+  projectId: my-project
+  scripts:
+    pre_deploy: serverpod generate
+    post_deploy: echo "Deployment complete"
+```
+
+Multiple commands run sequentially:
+
+```yaml
+project:
+  projectId: my-project
+  scripts:
+    pre_deploy:
+      - serverpod generate
+      - serverpod run flutter_build
+    post_deploy:
+      - curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK -d '{"text":"Deployed"}'
+```
+
+## How scripts run
+
+Each command runs in your project directory (the one containing `scloud.yaml`) through the system shell (`bash -c` on macOS and Linux, `cmd /c` on Windows). Scripts inherit the environment variables of the shell that invoked `scloud deploy`, so CI-set secrets and your local `PATH` are available. Commands in an array run sequentially; output streams to your terminal in real time as each one executes.
+
+A non-zero exit code halts further commands in that hook.
+
+:::warning
+
+`pre_deploy` and `post_deploy` failures are not symmetric:
+
+- A failing `pre_deploy` script aborts the deploy *before* Cloud receives your code.
+- A failing `post_deploy` script runs *after* the upload, so the deploy has already happened. The `scloud deploy` command exits with an error, but the new version is live.
+
+Plan your scripts accordingly: put anything that must succeed before your code ships in `pre_deploy`.
+
+:::
+
+## Related
+
+- [Deployments](/cloud/concepts/deployments) for the deploy lifecycle around hooks.
+- [`scloud deploy`](/cloud/reference/cli/commands/deploy) for the deploy command and its flags.

cloud_docs/02-guides/06-ship-non-dart-files.md

@@ -0,0 +1,132 @@
+---
+sidebar_label: Ship non-Dart files with your server
+description: Include configuration files, templates, data, or other non-Dart assets alongside your Serverpod Cloud server and read them at runtime.
+---
+
+# Ship non-Dart files with your server
+
+Bundle non-Dart files (configuration, templates, CSV data, binary blobs) with your server code on Cloud. Place them in an `assets/` folder at the project root and read them with `./assets/<path>` at runtime.
+
+## Before you start
+
+- A Serverpod server project on disk (alongside `lib/` and `bin/`).
+- The `scloud` CLI installed and authenticated. See [Install scloud](/cloud/getting-started/installation).
+
+## Add files to your project
+
+Place files in an `assets/` folder at the root of your server project, alongside `lib/` and `bin/`:
+
+```text
+my_server/
+├── assets/
+│   ├── config/
+│   │   └── settings.json
+│   ├── templates/
+│   │   └── email_template.html
+│   └── data/
+│       └── initial_data.csv
+├── lib/
+├── bin/
+└── pubspec.yaml
+```
+
+Then deploy:
+
+```bash
+scloud deploy
+```
+
+Cloud zips your project directory and includes every file that isn't excluded from the deploy package (see [Control what gets uploaded](#control-what-gets-uploaded) below). `assets/` is the Serverpod naming convention for this folder. You can call it anything, but the rest of this guide assumes `assets/`.
+
+To preview which files Cloud will upload before deploying:
+
+```bash
+scloud deploy --dry-run --show-files
+```
+
+## Read an asset at runtime
+
+Use Dart's `dart:io` library and a path relative to the server's working directory:
+
+```dart
+import 'dart:io';
+
+Future<String> readSettings() async {
+  final file = File('./assets/config/settings.json');
+  return file.readAsString();
+}
+```
+
+The path is relative to the directory the server runs from, not to the source file. Use `./assets/<path>` everywhere; absolute paths break across local and deployed environments.
+
+For binary data (images, PDFs, archives), use `readAsBytes()` instead of `readAsString()`.
+
+## Read common file types
+
+### Load JSON configuration
+
+Parse a JSON file into a `Map` on startup or per request:
+
+```dart
+import 'dart:io';
+import 'dart:convert';
+
+Future<Map<String, dynamic>> loadConfig() async {
+  final file = File('./assets/config/app_config.json');
+  final contents = await file.readAsString();
+  return jsonDecode(contents) as Map<String, dynamic>;
+}
+```
+
+### Render a template
+
+Read an HTML or text template, then interpolate values:
+
+```dart
+import 'dart:io';
+
+Future<String> loadWelcomeEmail({required final String name}) async {
+  final template = await File('./assets/templates/welcome_email.html').readAsString();
+  return template.replaceAll('{{name}}', name);
+}
+```
+
+### Read CSV data
+
+For tabular data, read line by line:
+
+```dart
+import 'dart:io';
+
+Future<List<String>> readCsv() async {
+  return File('./assets/data/initial_data.csv').readAsLines();
+}
+```
+
+For more complex parsing, the [`csv` package](https://pub.dev/packages/csv) handles quoting and escaping.
+
+## Control what gets uploaded
+
+Two files affect what's in the deployment:
+
+- **`.gitignore`.** Anything excluded here is also excluded from the deploy.
+- **`.scloudignore`.** Cloud-specific exclusions. Same syntax as `.gitignore`. Use the `!` prefix to opt files back in that `.gitignore` excluded.
+
+Hidden files (those starting with `.`) are excluded by default. If you need them shipped, opt back in via `.scloudignore`. See [Deployments](/cloud/concepts/deployments) for the full picture of the deployment package.
+
+:::tip
+
+Asset files count toward your deployment package size. Large folders slow uploads and the Cloud build step. For files larger than a few megabytes that don't need to live in version control, consider an external object store and reading them from the network instead.
+
+:::
+
+## Troubleshooting
+
+**File not found at runtime.** The path is relative to the server's working directory, not to the source file. Use `./assets/<path>`. Verify the file is in the deployment with `scloud deploy --dry-run --show-files` before debugging at runtime.
+
+**Asset missing from the deployment.** Check `.gitignore` and `.scloudignore`. Patterns like `*.json` exclude every `.json` file unless you opt them back in with `!assets/**`.
+
+## Related
+
+- [Deployments](/cloud/concepts/deployments) for what's in the deployment package and how `.scloudignore` works.
+- [`scloud deploy`](/cloud/reference/cli/commands/deploy) for the deploy command and its flags.