docs: Group Concepts into eight sections and rename the section to Concepts

docs/04-get-started/02-quickstart.md

@@ -70,7 +70,7 @@ If you are using Cursor, you will need to **enable the Serverpod and Dart MCP se
 
 ## Start the server and the app
 
-Start the server and the Flutter app by opening up a terminal window and running the [`serverpod start`](../06-concepts/00-start-command.md) command:
+Start the server and the Flutter app by opening up a terminal window and running the [`serverpod start`](./concepts/server-fundamentals/running-your-server) command:
 
 ```bash
 $ serverpod start

docs/04-get-started/03-how-it-works.md

@@ -15,7 +15,7 @@ Serverpod is a full backend. It manages your database, authentication, file uplo
 
 A Serverpod project starts with the `serverpod create` command, which walks you through a few choices that shape what it generates:
 
-- **Project type:** A full server, or a reusable [module](../concepts/modules) shared across servers.
+- **Project type:** A full server, or a reusable [module](./concepts/server-fundamentals/modules) shared across servers.
 - **Database and caching:** Add a Postgres database and Redis (for pub/sub and caching).
 - **Authentication:** Built-in email and social sign-ins.
 - **Web server:** Optionally serve web pages and your Flutter web app alongside your API.
@@ -50,7 +50,7 @@ Start your project before you begin building. With `serverpod start` already run
 
 ## Write an endpoint
 
-In Serverpod, endpoints are the entry points your app calls to run code on the server. You define one as a class that extends `Endpoint`, with async methods that each take a [`Session`](../concepts/sessions) as their first argument and return a typed `Future`:
+In Serverpod, endpoints are the entry points your app calls to run code on the server. You define one as a class that extends `Endpoint`, with async methods that each take a [`Session`](./concepts/endpoints-and-apis/sessions) as their first argument and return a typed `Future`:
 
 ```dart
 class ExampleEndpoint extends Endpoint {
@@ -60,7 +60,7 @@ class ExampleEndpoint extends Endpoint {
 }
 ```
 
-The `Session` is the context for that one call, with access to the database, cache, signed-in user, and logging. Parameters and return types can be the built-in types (`bool`, `int`, `double`, `String`, `DateTime`, `Duration`, `Uri`, `UuidValue`, `BigInt`, `ByteData`), a `List`, `Map`, `Set`, or `Record` of those, or any data model you define. See [Working with endpoints](../concepts/working-with-endpoints) for more information.
+The `Session` is the context for that one call, with access to the database, cache, signed-in user, and logging. Parameters and return types can be the built-in types (`bool`, `int`, `double`, `String`, `DateTime`, `Duration`, `Uri`, `UuidValue`, `BigInt`, `ByteData`), a `List`, `Map`, `Set`, or `Record` of those, or any data model you define. See [Working with endpoints](./concepts/endpoints-and-apis) for more information.
 
 ## Call it from your app
 
@@ -70,7 +70,7 @@ On the app side, the generated client turns each endpoint method into what looks
 final greeting = await client.example.hello('World');
 ```
 
-The client handles the request, the response, and the JSON in between. Most calls follow this request-and-response shape. For live updates, Serverpod also has [streaming endpoints](../concepts/streams) that keep a connection open so the server and app can push data to each other.
+The client handles the request, the response, and the JSON in between. Most calls follow this request-and-response shape. For live updates, Serverpod also has [streaming endpoints](./concepts/endpoints-and-apis/streaming) that keep a connection open so the server and app can push data to each other.
 
 ## Define your data models
 
@@ -83,7 +83,7 @@ fields:
   foundedDate: DateTime?
 ```
 
-When you generate code, this becomes a `Company` Dart class shared by the server and your app, so the same type flows from your endpoints into your Flutter widgets. Fields support the same types as endpoint methods, plus enums and nested models, and can be nullable. See [Working with models](../concepts/models) for the details.
+When you generate code, this becomes a `Company` Dart class shared by the server and your app, so the same type flows from your endpoints into your Flutter widgets. Fields support the same types as endpoint methods, plus enums and nested models, and can be nullable. See [Working with models](./concepts/data-and-the-database/models) for the details.
 
 Add a `table` key to also store the model in a database table:
 
@@ -106,7 +106,7 @@ These run on the same `session` your endpoint method receives. When you change a
 
 That database runs without setup on your part: Serverpod manages an embedded Postgres for you, with no Docker to configure. If you would rather manage Postgres yourself, you can change the configuration in the server's `config` directory.
 
-See [Working with the database](../concepts/database/crud) for building queries, relations, and transactions.
+See [Working with the database](./concepts/data-and-the-database/database/crud) for building queries, relations, and transactions.
 
 ## Build with an AI agent
 

docs/05-build-your-first-app/01-creating-endpoints.md

@@ -112,7 +112,7 @@ class RecipeEndpoint extends Endpoint {
 The endpoint reads your Gemini key from `session.passwords`, which Serverpod populates from the `passwords.yaml` file you edited earlier.
 
 :::info
-Endpoint methods take a `Session` as their first parameter and return a typed `Future` or `Stream`. You can pass and return primitive types or any [model defined in a `.spy.yaml` file](../06-concepts/02-models/01-models.md). The class name's `Endpoint` suffix is dropped on the client, so `RecipeEndpoint` is called via `client.recipe`. See [How it works](../04-get-started/03-how-it-works.md) for how that call reaches the server.
+Endpoint methods take a `Session` as their first parameter and return a typed `Future` or `Stream`. You can pass and return primitive types or any [model defined in a `.spy.yaml` file](../concepts/data-and-the-database/models). The class name's `Endpoint` suffix is dropped on the client, so `RecipeEndpoint` is called via `client.recipe`. See [How it works](../04-get-started/03-how-it-works.md) for how that call reaches the server.
 :::
 
 Save the file. Because `serverpod start` is watching, it regenerates the client bindings for `generateRecipe` automatically. You'll see it run in the terminal.

docs/05-build-your-first-app/02-models-and-data.md

@@ -34,7 +34,7 @@ fields:
 Save the file. `serverpod start` regenerates the `Recipe` class for both the server and the client.
 
 :::info
-Fields can be primitive types, other models, or a typed `List`, `Map`, or `Set`. See [Working with models](../06-concepts/02-models/01-models.md) for the full set of options.
+Fields can be primitive types, other models, or a typed `List`, `Map`, or `Set`. See [Working with models](../concepts/data-and-the-database/models) for the full set of options.
 :::
 
 ## Return the model from your endpoint

docs/05-build-your-first-app/03-working-with-the-database.md

@@ -36,12 +36,12 @@ fields:
 Save the file. The regenerated `Recipe` class now exposes database methods through `Recipe.db`.
 
 :::info
-See the [database models](../06-concepts/02-models/01-models.md#keywords-1) reference for all the keywords you can use in a table.
+See the [database models](../concepts/data-and-the-database/models#keywords-1) reference for all the keywords you can use in a table.
 :::
 
 ## Create and apply the migration
 
-Changing the schema requires a [migration](../06-concepts/06-database/11-migrations.md): a set of SQL steps that bring the database up to date with your models. The `serverpod start` terminal has shortcuts for this, listed along the bottom. With that terminal focused:
+Changing the schema requires a [migration](../concepts/data-and-the-database/database/migrations): a set of SQL steps that bring the database up to date with your models. The `serverpod start` terminal has shortcuts for this, listed along the bottom. With that terminal focused:
 
 ![serverpod start tui](/img/getting-started/tui-logs.png)
 
@@ -77,7 +77,7 @@ Add a second method to the endpoint that returns every saved recipe, newest firs
 ```
 
 :::info
-`insertRow` and `find` are Serverpod's typed database methods. See [CRUD](../06-concepts/06-database/05-crud.md) for the full set of operations.
+`insertRow` and `find` are Serverpod's typed database methods. See [CRUD](../concepts/data-and-the-database/database/crud) for the full set of operations.
 :::
 
 ## Show the saved recipes in your app

docs/05-build-your-first-app/04-deployment.md

@@ -54,4 +54,4 @@ You've built and deployed a full-stack app with Flutter and Serverpod:
 - Persistent storage with the database.
 - A Flutter app that talks to your server through the generated client.
 
-We're excited to see what you'll build next. If you need help, join the [Discord community](https://serverpod.dev/discord) or ask in our [community on GitHub](https://github.com/serverpod/serverpod/discussions). To go deeper into any topic, browse the [Concepts](../06-concepts/01-working-with-endpoints/01-working-with-endpoints.md) section.
+We're excited to see what you'll build next. If you need help, join the [Discord community](https://serverpod.dev/discord) or ask in our [community on GitHub](https://github.com/serverpod/serverpod/discussions). To go deeper into any topic, browse the [Concepts](../concepts/endpoints-and-apis) section.

docs/06-concepts/00-start-command.md → docs/06-concepts/01-server-fundamentals/01-running-your-server.md

@@ -12,7 +12,7 @@ Run it from anywhere inside your project folder:
 serverpod start
 ```
 
-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).
+Use `serverpod start` for local development only. To run your server in production, deploy it instead. See [Deploy to Serverpod Cloud](../../deployments/deploy-to-serverpod-cloud) or [Custom hosting](../../deployments/custom-hosting/choosing-a-strategy).
 
 ## Save a file to hot-reload
 
@@ -28,7 +28,7 @@ On boot, `serverpod start` applies any pending migrations. While it runs, you ha
 - **A** applies pending migrations to the database.
 - **P** creates a repair migration to reconcile a database that has drifted from your migrations.
 
-For how migrations work, see [Migrations](database/migrations).
+For how migrations work, see [Migrations](../data-and-the-database/database/migrations).
 
 ## Choose a run mode
 
@@ -52,6 +52,6 @@ You can still launch an app on demand from the terminal afterwards. To run witho
 
 ## Related
 
-- [`serverpod start` reference](cli/commands/start): every command-line option.
+- [`serverpod start` reference](../cli/commands/start): every command-line option.
 - [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.
+- [Deploy to Serverpod Cloud](../../deployments/deploy-to-serverpod-cloud): run your server in production instead of locally.

docs/06-concepts/07-configuration.md → docs/06-concepts/01-server-fundamentals/02-configuration.md

@@ -16,7 +16,7 @@ The three sources apply in order of precedence. The YAML files are the baseline,
 - **Environment variables**: override matching YAML values, useful for per-deployment settings and secrets.
 - **Dart configuration object**: a `ServerpodConfig` passed to the `Serverpod` constructor, overriding everything else.
 
-For every available option, its environment variable, config-file key, and default, see the [Configuration reference](lookups/configuration-reference).
+For every available option, its environment variable, config-file key, and default, see the [Configuration reference](../lookups/configuration-reference).
 
 ## Configuration files
 
@@ -166,8 +166,8 @@ The following table shows the built-in secrets that Serverpod uses for its core
 
 For secrets related to first-party Serverpod packages, see their respective documentation:
 
-- **Cloud storage**: see [Uploading files](file-uploads) for Google Cloud Storage, AWS S3, and Cloudflare R2 secrets.
-- **Authentication**: see [Storing Secrets](authentication/setup#storing-secrets) on the Authentication setup page.
+- **Cloud storage**: see [Uploading files](../endpoints-and-apis/file-uploads) for Google Cloud Storage, AWS S3, and Cloudflare R2 secrets.
+- **Authentication**: see [Storing Secrets](../authentication/setup#storing-secrets) on the Authentication setup page.
 
 ### Custom secrets
 
@@ -213,7 +213,7 @@ export SERVERPOD_PASSWORD_stripeApiKey=sk_test_123...
 
 Secrets are only available on the server. They are never sent to or accessible from your Flutter app.
 
-Inside an endpoint, read a secret from the [`Session`](sessions) through the `passwords` map:
+Inside an endpoint, read a secret from the [`Session`](../endpoints-and-apis/sessions) through the `passwords` map:
 
 ```dart
 Future<void> processPayment(Session session, PaymentData data) async {
@@ -253,7 +253,7 @@ Use `--from-file` for long or multi-line values such as a service account JSON.
 
 Serverpod uses a `generator.yaml` file to configure code generation. Place this file in the `config` directory of your server project.
 
-For every `generator.yaml` option, its type and default, see the [Configuration reference](lookups/configuration-reference#code-generation). The sections below explain the options you set most often.
+For every `generator.yaml` option, its type and default, see the [Configuration reference](../lookups/configuration-reference#code-generation). The sections below explain the options you set most often.
 
 ### Package types
 
@@ -287,7 +287,7 @@ Test tools for integration testing are generated by default at `test/integration
 # server_test_tools_path: test/integration/test_tools
 ```
 
-See the [testing documentation](testing/get-started) for more details.
+See the [testing documentation](../testing/get-started) for more details.
 
 ### Module dependencies
 
@@ -313,7 +313,7 @@ shared_packages:
   - ../another_shared_package
 ```
 
-Models and the protocol file are generated in each shared package's own directory when you run `serverpod generate` from your server project. See the [shared packages documentation](shared-packages) for setup, usage, and restrictions.
+Models and the protocol file are generated in each shared package's own directory when you run `serverpod generate` from your server project. See the [shared packages documentation](../data-and-the-database/models/shared-packages) for setup, usage, and restrictions.
 
 ### Custom serializable classes
 
@@ -325,7 +325,7 @@ extraClasses:
   - package:my_shared_package/my_shared_package.dart:AnotherCustomClass
 ```
 
-See the [serialization documentation](serialization) for implementing custom serializable classes.
+See the [serialization documentation](../data-and-the-database/models/custom-serialization) for implementing custom serializable classes.
 
 ### Features
 
@@ -345,7 +345,7 @@ experimental_features:
   all: true # Enables all available experimental features
 ```
 
-The `all` key opts into every available experimental feature. No experimental features are available in the current version. See the [experimental features documentation](experimental) for details.
+The `all` key opts into every available experimental feature. No experimental features are available in the current version. See the [experimental features documentation](../operations/experimental-features) for details.
 
 :::warning
 Experimental features may change or be removed in future versions.

docs/06-concepts/01-server-fundamentals/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Server fundamentals",
+  "collapsed": true
+}

docs/06-concepts/01-working-with-endpoints/01-working-with-endpoints.md → docs/06-concepts/02-endpoints-and-apis/01-working-with-endpoints.md

@@ -1,5 +1,5 @@
 ---
-slug: /concepts/working-with-endpoints
+slug: /concepts/endpoints-and-apis
 sidebar_label: Working with endpoints
 description: Endpoints expose server methods to a generated, typed client your Flutter app calls, with one client setup pointed at each environment.
 ---
@@ -70,7 +70,7 @@ apiServer:
   publicScheme: http
 ```
 
-To enable browser credentials for CORS or use platform-native HTTP clients, see [Configure HTTP calls](./working-with-endpoints/configure-http-calls).
+To enable browser credentials for CORS or use platform-native HTTP clients, see [Configure HTTP calls](./endpoints-and-apis/configure-http-calls).
 
 ## Point the client at each environment
 
@@ -102,7 +102,7 @@ You can also pass `List`, `Map`, `Record`, and `Set` as parameters, but they nee
 
 :::warning
 
-While it's possible to pass binary data through a method call and `ByteData`, it is not the most efficient way to transfer large files. See our [file upload](./file-uploads) interface. The size of a call is by default limited to 524288 bytes (512 KiB). It's possible to change by adding the `maxRequestSize` to your config files. E.g., this will double the request size to 1 MiB:
+While it's possible to pass binary data through a method call and `ByteData`, it is not the most efficient way to transfer large files. See our [file upload](./endpoints-and-apis/file-uploads) interface. The size of a call is by default limited to 524288 bytes (512 KiB). It's possible to change by adding the `maxRequestSize` to your config files. E.g., this will double the request size to 1 MiB:
 
 ```yaml
 maxRequestSize: 1048576

docs/06-concepts/05-sessions.md → docs/06-concepts/02-endpoints-and-apis/02-sessions.md

@@ -8,20 +8,20 @@ Every endpoint method receives a `Session` object. It is the entry point for the
 
 :::note
 
-A Serverpod Session should not be confused with the concept of "web sessions" or "user sessions" which persist over multiple API calls. See the [Authentication documentation](./authentication/setup) for managing persistent authentication.
+A Serverpod Session should not be confused with the concept of "web sessions" or "user sessions" which persist over multiple API calls. See the [Authentication documentation](../authentication/setup) for managing persistent authentication.
 
 :::
 
 ## Quick reference
 
 ### Essential properties
 
-- **`db`** - Database access. [See database docs](./database/connection)
-- **`caches`** - Local and distributed caching. [See caching docs](./caching)
+- **`db`** - Database access. [See database docs](../data-and-the-database/database/connection)
+- **`caches`** - Local and distributed caching. [See caching docs](../operations/caching)
 - **`storage`** - File storage operations. [See file uploads](./file-uploads)
 - **`messages`** - Server events for real-time communication within and across servers. [See server events docs](./server-events)
-- **`passwords`** - Credentials from config and environment. [See configuration](./configuration)
-- **`authenticated`** - Current user authentication info. [See authentication docs](./authentication/basics)
+- **`passwords`** - Credentials from config and environment. [See configuration](../server-fundamentals/configuration)
+- **`authenticated`** - Current user authentication info. [See authentication docs](../authentication/basics)
 
 ### Key methods
 
@@ -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](scheduling/setup):
+Instead of managing sessions for async work, use Serverpod's [future call system](../scheduling/setup):
 
 ```dart
 // ✅ Good - Let Serverpod manage the session
@@ -300,4 +300,4 @@ withServerpod('test group', (sessionBuilder, endpoints) {
 });
 ```
 
-For detailed testing strategies, see the [testing documentation](./testing/get-started).
+For detailed testing strategies, see the [testing documentation](../testing/get-started).

docs/06-concepts/01-working-with-endpoints/04-middleware.md → docs/06-concepts/02-endpoints-and-apis/05-endpoint-middleware.md

@@ -5,7 +5,7 @@ description: Middleware on the API server intercepts endpoint requests and respo
 
 # Endpoint middleware
 
-Middleware runs before and after your endpoints, making it suitable for logging, caching, and rate limiting. Serverpod middleware follows the [Relic middleware](https://docs.dartrelic.dev/reference/middleware) interface. To add middleware to web server routes instead, scoped to path prefixes, see [Web server middleware](../webserver/middleware).
+Middleware runs before and after your endpoints, making it suitable for logging, caching, and rate limiting. Serverpod middleware follows the [Relic middleware](https://docs.dartrelic.dev/reference/middleware) interface. To add middleware to web server routes instead, scoped to path prefixes, see [Web server middleware](../web-server/web-server-middleware).
 
 ## Adding middleware to your server