docs: Reshape Server fundamentals + add Configuration reference

docs/06-concepts/00-start-command.md

@@ -1,70 +1,57 @@
 ---
-description: Reference for the serverpod start command, covering every option, the terminal UI shortcuts for migrations and hot restart, and the server arguments it forwards.
+description: The serverpod start command runs your project in development, with code generation, hot reload, database migrations, and the Flutter app in one terminal.
 ---
 
-# Starting the server
+# Running your server
 
-The `serverpod start` command runs your project in development mode. It generates the latest code, starts the server with hot reload, and launches the companion Flutter app, all in a single interactive terminal.
+As you build, one command keeps your server, generated code, and app in sync, so a change shows up the moment you save. The `serverpod start` command does exactly that: it generates the latest code, runs your server with hot reload, and launches your companion Flutter apps, all inside a single interactive terminal.
+
+Run it from anywhere inside your project folder:
 
 ```bash
 serverpod start
 ```
 
-Run it from anywhere inside your project folder.
+Use `serverpod start` for local development only. To run your server in production, deploy it instead. See [Deploy to Serverpod Cloud](../08-deployments/01-deploy-to-serverpod-cloud.md) or [Custom hosting](../08-deployments/custom-hosting/01-choosing-a-strategy.md).
 
-When it boots the server, `serverpod start` applies any pending migrations. While it runs, you create and apply new migrations from the terminal UI (see [Terminal UI shortcuts](#terminal-ui-shortcuts)).
+## Save a file to hot-reload
 
-## Usage
+While `serverpod start` is watching, which is the default, saving a file recompiles and hot-reloads the affected code without a restart. This covers your endpoints, models, and generated client, so the running server and the generated code stay in step as you work. When a change cannot be hot-reloaded, press **R** in the terminal to hot restart.
 
-```bash
-serverpod start [options] [-- <server-args>]
-```
+To start without watching, pass `--no-watch`. The server then runs through `dart run` with no incremental compilation.
 
-## Options
+## Manage migrations from the terminal
 
-| Option | Default | Description |
-| --- | --- | --- |
-| `-w`, `--watch` / `--no-watch` | `true` | Watch files and hot-reload using the Frontend Server for fast incremental compilation. Pass `--no-watch` to start the server with `dart run` instead. |
-| `-d`, `--directory <path>` | auto-detect | Set the server package directory. Auto-detected from the current directory when omitted. |
-| `--docker` / `--no-docker` | `false` | Start Docker Compose services if a `docker-compose.yaml` exists (typically Redis when running Postgres separately). Off by default; pass `--docker` to opt in. |
-| `--tui` / `--no-tui` | `true` | Show the interactive terminal UI. Pass `--no-tui` to run without it, for example in scripts or non-interactive shells. |
-| `--flutter` / `--no-flutter` | `true` | Launch the companion Flutter app alongside the server. Pass `--no-flutter` to start only the server. |
-| `--flutter-device <name>` | `chrome` | Choose the device passed to `flutter run -d`. Use `web-server` for headless or CI runs. |
-| `--flutter-option <arg>` | none | Forward an extra argument to [`flutter run`](https://docs.flutter.dev/reference/flutter-cli). Repeatable, e.g. `--flutter-option=--web-port=8090`. |
-| `-h`, `--help` | | Print usage information. |
+On boot, `serverpod start` applies any pending migrations. While it runs, you handle further schema changes from the interactive terminal without leaving the session. The terminal lists these shortcuts along the bottom:
 
-## Terminal UI shortcuts
+- **M** creates a migration from your current model changes.
+- **A** applies pending migrations to the database.
+- **P** creates a repair migration to reconcile a database that has drifted from your migrations.
 
-The interactive terminal UI lists its shortcuts along the bottom. With the `serverpod start` terminal focused:
+For how migrations work, see [Migrations](database/migrations).
 
-| Key | Action |
-| --- | --- |
-| **R** | Hot restart the server. |
-| **M** | Create a migration from your current model changes (`Shift+M` to force). |
-| **A** | Apply pending migrations to the database. |
-| **P** | Create a repair migration to reconcile a drifted database (`Shift+P` to force). |
+## Choose a run mode
 
-Saving a file hot-reloads the server automatically while watching is enabled.
+By default, `serverpod start` runs in the `development` run mode. To start in another mode, forward a `--mode` argument to the server after `--`:
 
-## Passing arguments to the server
+```bash
+serverpod start -- --mode staging
+```
+
+The run mode selects which configuration and passwords the server loads. See [Configuration](configuration) for what each mode reads. For every argument `serverpod start` forwards to the server, see the [`serverpod start` reference](cli/commands/start).
 
-Arguments after `--` are forwarded to the running server. For example, to start it in a specific run mode:
+## Run the server on its own
+
+By default, `serverpod start` also launches the companion Flutter apps marked `auto_launch: true` in the server's `pubspec.yaml`. To start only the server, disable that:
 
 ```bash
-serverpod start -- --mode staging
+serverpod start --no-flutter
 ```
 
-The server accepts the following arguments:
+You can still launch an app on demand from the terminal afterwards. To run without the interactive terminal at all, for a script or CI, pass `--no-tui`.
 
-| Argument | Allowed values | Default | Description |
-| --- | --- | --- | --- |
-| `-m`, `--mode` | `development`, `test`, `staging`, `production` | `development` | Set the run mode the server starts in. |
-| `-r`, `--role` | `monolith`, `serverless`, `maintenance` | `monolith` | Set the role the server runs as. |
-| `-l`, `--logging` | `normal`, `verbose` | `normal` | Set the logging level. |
-| `-i`, `--server-id` | any | `default` | Set the id of this server instance. |
-| `-a`, `--apply-migrations` | | `false` | Apply pending database migrations on boot. |
-| `-A`, `--apply-repair-migration` | | `false` | Apply the repair migration on boot. |
+## Related
 
-:::note
-`serverpod start` is intended for local development. For production, deploy the server instead. See [Deploy to Serverpod Cloud](../08-deployments/01-deploy-to-serverpod-cloud.md) or [Custom hosting](../08-deployments/custom-hosting/01-choosing-a-strategy.md).
-:::
+- [`serverpod start` reference](cli/commands/start): every option, terminal shortcut, and forwarded server argument.
+- [Configuration](configuration): the run modes and files the server loads on start.
+- [Deploy to Serverpod Cloud](../08-deployments/01-deploy-to-serverpod-cloud.md): run your server in production instead of locally.

docs/06-concepts/05-sessions.md

@@ -1,5 +1,5 @@
 ---
-description: Understand Serverpod sessions, which provides access to the database, cache, storage, and messaging for every endpoint call.
+description: The Session object gives every endpoint call access to the database, cache, file storage, and messaging, and manages its own lifecycle and logging.
 ---
 
 # Sessions
@@ -233,7 +233,7 @@ Future<List<User>> getActiveUsers(Session session) async {
 
 ### 2. Use FutureCalls for delayed operations
 
-Instead of managing sessions for async work, use Serverpod's future call system:
+Instead of managing sessions for async work, use Serverpod's [future call system](scheduling/setup):
 
 ```dart
 // ✅ Good - Let Serverpod manage the session