fix: Document free model definition placement

docs/01-get-started.md

@@ -122,7 +122,7 @@ These are the most important directories:
 
 - `config`: These are the configuration files for your Serverpod. These include a `password.yaml` file with your passwords and configurations for running your server in development, staging, and production. By default, everything is correctly configured to run your server locally.
 - `lib/src/endpoints`: This is the default location for your server's endpoints. When you add methods to an endpoint, Serverpod will generate the corresponding methods in your client.
-- `lib/src/models`: The model definition files are placed here. The files define the classes you can pass through your API and how they relate to your database. Serverpod generates serializable objects from the model definitions.
+- `lib/src/models`: Default location for your model definition files. The files define the classes you can pass through your API and how they relate to your database. Serverpod generates serializable objects from the model definitions.
 
 Both the `endpoints` and `models` directories contain sample files that give a quick idea of how they work. So this a great place to start learning.
 
@@ -167,9 +167,9 @@ To learn more about endpoints, see the [Working with endpoints](concepts/working
 
 Serverpod makes it easy to generate serializable classes that can be passed between server and client or used to communicate with the database.
 
-The structure for your serialized classes is defined in yaml-files in the `lib/src/models` directory. Run `serverpod generate` in the home directory of the server to build the Dart code for the classes and make them accessible to both the server and client.
+The structure for your serialized classes is defined in `.spy.yaml` files anywhere in the `lib` directory. Run `serverpod generate` in the home directory of the server to build the Dart code for the classes and make them accessible to both the server and client.
 
-Here is a simple example of a yaml-file defining a serializable class:
+Here is a simple example of a `.spy.yaml` file defining a serializable class:
 
 ```yaml
 class: Company

docs/02-get-started-with-mini.md

@@ -36,7 +36,7 @@ If you are using VS Code, install our Serverpod extension. It will help you vali
 :::
 
 ## Creating models
-In Serverpod, you define your models in easy-to-read YAML-files, which you place in your server’s `lib/src/models` directory. Model files will be converted to Dart classes that can be serialized and sent to and from the server to your app. This is an example of a model file:
+In Serverpod, you define your models in easy-to-read YAML-files, which you place anywhere in your server’s `lib` directory with the `.spy.yaml` extension. Model files will be converted to Dart classes that can be serialized and sent to and from the server to your app. This is an example of a model file:
 
 ```yaml
 class: Company
@@ -111,4 +111,4 @@ var result = await client.company.isLegit(company);
 ```
 
 ## Conclusion
-You are now ready to start exploring the exciting world of Serverpod! And even if you start out with Serverpod mini, you can always [upgrade](upgrading/upgrade-from-mini) to the full version later.
+You are now ready to start exploring the exciting world of Serverpod! And even if you start out with Serverpod mini, you can always [upgrade](upgrading/upgrade-from-mini) to the full version later.

docs/06-concepts/01-working-with-endpoints.md

@@ -1,6 +1,6 @@
 # Working with endpoints
 
-Endpoints are the connection points to the server from the client. With Serverpod, you add methods to your endpoint, and your client code will be generated to make the method call. For the code to be generated, you need to place the endpoint file anywhere under the **lib** directory of your server. Your endpoint should extend the `Endpoint` class. For methods to be generated, they need to return a typed `Future`, and its first argument should be a `Session` object. The `Session` object holds information about the call being made and provides access to the database.
+Endpoints are the connection points to the server from the client. With Serverpod, you add methods to your endpoint, and your client code will be generated to make the method call. For the code to be generated, you need to place the endpoint file anywhere under the `lib` directory of your server. Your endpoint should extend the `Endpoint` class. For methods to be generated, they need to return a typed `Future`, and its first argument should be a `Session` object. The `Session` object holds information about the call being made and provides access to the database.
 
 ```dart
 import 'package:serverpod/serverpod.dart';

docs/06-concepts/02-models.md

@@ -1,6 +1,8 @@
 # Working with models
 
-Models are Yaml files used to define serializable classes in Serverpod. They are used to generate Dart code for the server and client, and, if a database table is defined, to generate database code for the server. Using regular `.yaml` files within `lib/src/models` is supported, but it is recommended to use `.spy.yaml` (.spy stands for "Server Pod Yaml") to leverage syntax highlighting provided by the [Serverpod Extension](https://marketplace.visualstudio.com/items?itemName=serverpod.serverpod) for VS Code.
+Models are Yaml files used to define serializable classes in Serverpod. They are used to generate Dart code for the server and client, and, if a database table is defined, to generate database code for the server.
+
+Using regular `.yaml` files within `lib/src/models` is supported, but it is recommended to use `.spy.yaml` (.spy stands for "Serverpod YAML"). Using this file type allows placing the model files anywhere in your servers `lib` directory and enables syntax highlighting provided by the [Serverpod Extension](https://marketplace.visualstudio.com/items?itemName=serverpod.serverpod) for VS Code.
 
 The files are analyzed by the Serverpod CLI when generating the project and creating migrations.
 
@@ -114,7 +116,7 @@ Serverpod generates some convenience methods on the Dart classes.
 
 ### copyWith
 
-The `copyWith` method allows for efficient object copying with selective field updates and is available on all generated `class`es. Here's how it operates:
+The `copyWith` method allows for efficient object copying with selective field updates and is available on all generated classes. Here's how it operates:
 
 ```dart
 var john = User(name: 'John Doe', age: 25);

docs/06-concepts/04-exceptions.md

@@ -12,7 +12,7 @@ Use the Serverpod Insights app to view your logs. It will show any failed or slo
 
 ## Serializable exceptions
 
-Serverpod allows adding data to an exception you throw on the server and extracting that data in the client. This is useful for passing error messages back to the client when a call fails. You use the same yaml-files to define the serializable exceptions as you would with any serializable model (see [serialization](serialization) for details). The only difference is that you use the keyword `exception` instead of `class`.
+Serverpod allows adding data to an exception you throw on the server and extracting that data in the client. This is useful for passing error messages back to the client when a call fails. You use the same YAML-files to define the serializable exceptions as you would with any serializable model (see [serialization](serialization) for details). The only difference is that you use the keyword `exception` instead of `class`.
 
 ```yaml
 exception: MyException

docs/06-concepts/06-database/04-indexing.md

@@ -1,10 +1,10 @@
 # Indexing
 
-For performance reasons, you may want to add indexes to your database tables. These are added in the yaml-files defining the serializable objects.
+For performance reasons, you may want to add indexes to your database tables. These are added in the YAML-files defining the serializable objects.
 
 ### Add an index
 
-To add an index, add an `indexes` section to the yaml-file. The `indexes` section is a map where the key is the name of the index and the value is a map with the index details.
+To add an index, add an `indexes` section to the YAML-file. The `indexes` section is a map where the key is the name of the index and the value is a map with the index details.
 
 ```yaml
 class: Company

docs/06-concepts/10-modules.md

@@ -67,7 +67,7 @@ dependencies:
 
 ## Referencing a module
 
-It can be useful to reference serializable objects in other modules from the yaml-files in your model directory. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the auth package.
+It can be useful to reference serializable objects in other modules from the YAML-files in your models. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the auth package.
 
 ```yaml
 class: MyClass

versioned_docs/version-0.9.10/03-concepts/02-serialization.md

@@ -1,7 +1,7 @@
 # Serialization
-Serverpod makes it easy to generate serializable classes that can be passed between server and client or used to communicate with the database. The structure for the classes is defined in yaml-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
+Serverpod makes it easy to generate serializable classes that can be passed between server and client or used to communicate with the database. The structure for the classes is defined in YAML-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
 
-Here is a simple example of a yaml-file defining a serializable class:
+Here is a simple example of a YAML-file defining a serializable class:
 
 ```yaml
 class: Company

versioned_docs/version-0.9.10/03-concepts/03-database-communication.md

@@ -27,7 +27,7 @@ fields:
 Likewise, if you only want a field to be accessible in the protocol but not stored in the server, you can add the `api` flag. By default, a field is accessible to both the API and the database.
 
 ### Database indexes
-For performance reasons, you may want to add indexes to your database tables. You add these in the yaml-files defining the serializable objects.
+For performance reasons, you may want to add indexes to your database tables. You add these in the YAML-files defining the serializable objects.
 
 ```yaml
 class: Company

versioned_docs/version-0.9.11/03-concepts/02-serialization.md

@@ -1,7 +1,7 @@
 # Serialization
-Serverpod makes it easy to generate serializable classes that can be passed between server and client or used to communicate with the database. The structure for the classes is defined in yaml-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
+Serverpod makes it easy to generate serializable classes that can be passed between server and client or used to communicate with the database. The structure for the classes is defined in YAML-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
 
-Here is a simple example of a yaml-file defining a serializable class:
+Here is a simple example of a YAML-file defining a serializable class:
 
 ```yaml
 class: Company

versioned_docs/version-0.9.11/03-concepts/03-database-communication.md

@@ -33,7 +33,7 @@ If you use the `database` or `api` options the field must be nullable.
 :::
 
 ### Database indexes
-For performance reasons, you may want to add indexes to your database tables. You add these in the yaml-files defining the serializable objects.
+For performance reasons, you may want to add indexes to your database tables. You add these in the YAML-files defining the serializable objects.
 
 ```yaml
 class: Company

versioned_docs/version-0.9.20/04-concepts/02-serialization.md

@@ -2,9 +2,9 @@
 Serverpod makes it easy to generate serializable classes that can be passed between server and client or used to communicate with the database.
 
 ## Serverpod's native serialization
-The structure for your serialized classes is defined in yaml-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
+The structure for your serialized classes is defined in YAML-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
 
-Here is a simple example of a yaml-file defining a serializable class:
+Here is a simple example of a YAML-file defining a serializable class:
 
 ```yaml
 class: Company

versioned_docs/version-0.9.20/04-concepts/03-database-communication.md

@@ -39,7 +39,7 @@ If you use the `database` or `api` options the field must be nullable.
 :::
 
 ### Database indexes
-For performance reasons, you may want to add indexes to your database tables. You add these in the yaml-files defining the serializable objects.
+For performance reasons, you may want to add indexes to your database tables. You add these in the YAML-files defining the serializable objects.
 
 ```yaml
 class: Company

versioned_docs/version-0.9.20/04-concepts/06-modules.md

@@ -57,7 +57,7 @@ dependencies:
 ```
 
 ## Referencing a module
-It can be useful to reference serializable objects in other modules from the yaml-files in your protocol directory. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the auth package.
+It can be useful to reference serializable objects in other modules from the YAML-files in your protocol directory. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the auth package.
 
 ```yaml
 class: MyClass
@@ -84,4 +84,4 @@ In your Flutter package, you most likely want to import the client libraries cre
 
 Most modules will need a set of database tables to function. When naming the tables, you should use the module name as a prefix to the table name to avoid any conflicts. For instance, the Serverpod tables are prefixed with `serverpod_`.
 
-:::
+:::

versioned_docs/version-0.9.21/04-concepts/02-serialization.md

@@ -2,9 +2,9 @@
 Serverpod makes it easy to generate serializable classes that can be passed between server and client or used to communicate with the database.
 
 ## Serverpod's native serialization
-The structure for your serialized classes is defined in yaml-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
+The structure for your serialized classes is defined in YAML-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
 
-Here is a simple example of a yaml-file defining a serializable class:
+Here is a simple example of a YAML-file defining a serializable class:
 
 ```yaml
 class: Company

versioned_docs/version-0.9.21/04-concepts/03-database-communication.md

@@ -39,7 +39,7 @@ If you use the `database` or `api` options the field must be nullable.
 :::
 
 ### Database indexes
-For performance reasons, you may want to add indexes to your database tables. You add these in the yaml-files defining the serializable objects.
+For performance reasons, you may want to add indexes to your database tables. You add these in the YAML-files defining the serializable objects.
 
 ```yaml
 class: Company

versioned_docs/version-0.9.21/04-concepts/06-modules.md

@@ -57,7 +57,7 @@ dependencies:
 ```
 
 ## Referencing a module
-It can be useful to reference serializable objects in other modules from the yaml-files in your protocol directory. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the auth package.
+It can be useful to reference serializable objects in other modules from the YAML-files in your protocol directory. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the auth package.
 
 ```yaml
 class: MyClass
@@ -84,4 +84,4 @@ In your Flutter package, you most likely want to import the client libraries cre
 
 Most modules will need a set of database tables to function. When naming the tables, you should use the module name as a prefix to the table name to avoid any conflicts. For instance, the Serverpod tables are prefixed with `serverpod_`.
 
-:::
+:::

versioned_docs/version-0.9.22/04-concepts/02-serialization.md

@@ -2,9 +2,9 @@
 Serverpod makes it easy to generate serializable classes that can be passed between server and client or used to communicate with the database.
 
 ## Serverpod's native serialization
-The structure for your serialized classes is defined in yaml-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
+The structure for your serialized classes is defined in YAML-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
 
-Here is a simple example of a yaml-file defining a serializable class:
+Here is a simple example of a YAML-file defining a serializable class:
 
 ```yaml
 class: Company

versioned_docs/version-0.9.22/04-concepts/03-database-communication.md

@@ -39,7 +39,7 @@ If you use the `database` or `api` options the field must be nullable.
 :::
 
 ### Database indexes
-For performance reasons, you may want to add indexes to your database tables. You add these in the yaml-files defining the serializable objects.
+For performance reasons, you may want to add indexes to your database tables. You add these in the YAML-files defining the serializable objects.
 
 ```yaml
 class: Company

versioned_docs/version-0.9.22/04-concepts/06-modules.md

@@ -57,7 +57,7 @@ dependencies:
 ```
 
 ## Referencing a module
-It can be useful to reference serializable objects in other modules from the yaml-files in your protocol directory. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the auth package.
+It can be useful to reference serializable objects in other modules from the YAML-files in your protocol directory. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the auth package.
 
 ```yaml
 class: MyClass
@@ -84,4 +84,4 @@ In your Flutter package, you most likely want to import the client libraries cre
 
 Most modules will need a set of database tables to function. When naming the tables, you should use the module name as a prefix to the table name to avoid any conflicts. For instance, the Serverpod tables are prefixed with `serverpod_`.
 
-:::
+:::

versioned_docs/version-0.9.5/02-concepts/02-serialization.md

@@ -1,7 +1,7 @@
 # Serialization
-Serverpod makes it easy to generate serializable classes that can be passed between server and client or used to communicate with the database. The structure for the classes is defined in yaml-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
+Serverpod makes it easy to generate serializable classes that can be passed between server and client or used to communicate with the database. The structure for the classes is defined in YAML-files in the `protocol` directory. Run `serverpod generate` to build the Dart code for the classes and make them accessible to both the server and client.
 
-Here is a simple example of a yaml-file defining a serializable class:
+Here is a simple example of a YAML-file defining a serializable class:
 
 ```yaml
 class: Company

versioned_docs/version-0.9.5/02-concepts/03-database-communication.md

@@ -27,7 +27,7 @@ fields:
 Likewise, if you only want a field to be accessible in the protocol but not stored in the server, you can add the `api` flag. By default, a field is accessible to both the API and the database.
 
 ### Database indexes
-For performance reasons, you may want to add indexes to your database tables. You add these in the yaml-files defining the serializable objects.
+For performance reasons, you may want to add indexes to your database tables. You add these in the YAML-files defining the serializable objects.
 
 ```yaml
 class: Company