docs: Open every Cloud concept page with a reason to care

.github/doc-templates/concept.md

@@ -16,10 +16,18 @@ description: <One sentence summary, 120–160 chars. Used for SEO and AI retriev
 
 # <Capability name>
 
-Two to four sentences. What the capability is, in plain language. The reader should leave this
-paragraph knowing what the feature does and roughly when they'd reach for it.
-
-Don't open with marketing. Open with the substance.
+Two to four sentences. The order matters:
+
+1. First sentence: a concrete reason the reader would reach for this capability. Name
+   use cases or stakes they will recognise. ("Cloud collects logs so you can debug a deploy
+   that broke at 3am or trace a request that took two seconds." beats "Cloud has a logging
+   system.") The first sentence is what a scanner reads to decide if the page is relevant.
+2. Second sentence: what the capability is and how it works at a glance. Mechanics live
+   here, not in the opener.
+3. (Optional) third or fourth sentence: scope, roadmap status, or a pointer to a section
+   below.
+
+Don't open with marketing or feature labels. Open with the substance.
 If the capability has a roadmap item (workaround today, native support coming), say so here.
 
 ## When to use <capability>
@@ -90,7 +98,7 @@ If an operation has a primary form and a variant, show both in adjacent code blo
 ## Checklist before publishing
 
 - [ ] `description` frontmatter is present and reads well in isolation (120–160 chars).
-- [ ] Overview opens with what the capability is, in plain language. No marketing.
+- [ ] Overview opens with a concrete reason a reader would care, not the mechanism. Names use cases or stakes by name before describing structure.
 - [ ] Roadmap status stated up front if relevant.
 - [ ] Operations are action-shaped headings, ordered by how often the reader needs them.
 - [ ] Code blocks are language-tagged; `title` attributes used for file content.

cloud_docs/02-concepts/01-deployments.md

@@ -5,7 +5,7 @@ description: Deploy your Serverpod app to Cloud, check deployment status, valida
 
 # Deployments
 
-A deployment is one running version of your Serverpod app on Cloud. Every `scloud deploy` rolls out a new version, and Cloud serves the most recent successful one, so subsequent deploys move your app forward automatically.
+Every code change you ship to Serverpod Cloud goes through a deployment. A deployment is one running version of your Serverpod app; every `scloud deploy` rolls out a new version, and Cloud serves the most recent successful one, so subsequent deploys move your app forward automatically.
 
 ## Deploy your app
 

cloud_docs/02-concepts/02-logs.md

@@ -5,9 +5,9 @@ description: How Serverpod Cloud surfaces logs through Insights, the scloud CLI
 
 # 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.
+When a request fails, a deploy errors out, or you're chasing a slow endpoint, logs are where you go to find out what happened. Serverpod Cloud collects logs from your running app and from each deployment's build, and surfaces them through Serverpod Insights (a visual viewer in the Cloud console) and the `scloud` CLI.
 
-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.
+Insights groups logs by session, so it's the right starting point for tracing a single request end-to-end. The CLI is faster for one-off filtering and is the only path to build logs from failed deploys.
 
 ## View logs in Insights
 

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

@@ -5,7 +5,7 @@ description: "Serverpod Cloud has three configuration tiers: encrypted passwords
 
 # 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.
+Your server needs sensitive values (database passwords, third-party API keys, OAuth client secrets) and runtime configuration without checking them into source. Serverpod Cloud gives you three configuration tiers. 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                                               |
 | --------------------- | ------------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------- |

cloud_docs/02-concepts/04-custom-domains.md

@@ -5,6 +5,8 @@ description: Custom domains attach to the web, API, or Insights surface of a Ser
 
 # Custom domains
 
+When you're ready to ship your project to real users, you'll want it reachable at `yourapp.com` rather than the `*.serverpod.space` defaults. Custom domains attach a domain you own to your project's web, API, or Insights surface, with automatic TLS and DNS-based verification.
+
 Every Serverpod Cloud project gets default domains automatically. A project named `my-app` is reachable at:
 
 | Service  | Default domain                             |
@@ -13,8 +15,6 @@ Every Serverpod Cloud project gets default domains automatically. A project name
 | API      | `https://my-app.api.serverpod.space/`      |
 | Insights | `https://my-app.insights.serverpod.space/` |
 
-Custom domains let you replace any of those with your own URL. Serverpod Cloud provisions and renews TLS certificates automatically; the only setup required is a DNS record and a verification step.
-
 ## Attach a custom domain
 
 A custom domain points at one of the three surfaces:

cloud_docs/02-concepts/05-database.md

@@ -5,9 +5,9 @@ description: How Serverpod Cloud's managed PostgreSQL works, including provision
 
 # Database
 
-Serverpod Cloud can provision and run a managed PostgreSQL database alongside your project. When the database is enabled, Cloud handles provisioning, connection details for your server, migrations on every deploy, and backups. Direct access from tools like `psql` or a GUI client is opt-in and requires a database user that you create yourself.
+Most Serverpod apps need to persist data (user accounts, orders, session state). Serverpod Cloud can provision and run a managed PostgreSQL database alongside your project, so you don't have to set up or maintain Postgres yourself. When the database is enabled, Cloud handles provisioning, connection details for your server, migrations on every deploy, and backups. Direct access from tools like `psql` or a GUI client is opt-in and requires a database user that you create yourself.
 
-The managed database runs on PostgreSQL 17 with TLS required, connection pooling on by default, and autoscaling compute. Cloud manages the infrastructure for you.
+The managed database runs on PostgreSQL 17 with TLS required, connection pooling on by default, and autoscaling compute.
 
 ## Enable the database
 

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

@@ -5,7 +5,7 @@ description: Create personal access tokens to authenticate scloud in CI pipeline
 
 # 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 you need to run `scloud` in a CI pipeline, a script, or a headless environment where the browser-based `scloud auth login` flow isn't possible, you authenticate with a personal access token instead. Tokens are long-lived credentials you generate once, store as a secret, and pass to `scloud` as a flag or environment variable.
 
 ## When to use tokens
 

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

@@ -5,7 +5,7 @@ description: Run custom scripts at fixed points in a Serverpod Cloud deploy. Pre
 
 # 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.
+If every deploy needs you to build a Flutter web client, regenerate Serverpod code, run database migrations, or send a Slack notification on release, deployment hooks let `scloud deploy` do that work for you. Hooks run your own scripts at fixed points around the deploy. Without them, those steps live in a separate command you remember to run yourself.
 
 ## When to use hooks