updated pages based on review

Signed-off-by: bidi <bidi@apidemia.com>

Author: bidi47

docs/book/v7/core-features/authentication.md

@@ -7,7 +7,7 @@ It ensures that the entity making the request has the proper credentials to acce
 If it is present, the application tries to find and assign the identity to the application.
 If it is not presented, Dotkernel API assigns a default `guest` identity, represented by an instance of the class `Mezzio\Authentication\UserInterface`.
 Guests can access public endpoints but cannot access protected resources (those requiring user or admin roles).
-Check out the Authorization page for more details on role-based access.
+Check out the [Authorization page](https://docs.dotkernel.org/api-documentation/v7/core-features/authentication/) for more details on role-based access.
 
 ## Configuration
 

docs/book/v7/installation/composer.md

@@ -1,14 +1,21 @@
 # Composer Installation of Packages
 
-Composer is required to install Dotkernel `api`. You can install Composer from the [official site](https://getcomposer.org/).
+In this step you will:
 
-> First, make sure that you have navigated your command prompt to the folder where you copied the files in the previous step.
+- [Install dependencies](#install-dependencies-using-composer).
+- [Enable development mode](#development-mode).
 
-## Install dependencies
+> Composer is required to install Dotkernel `api`.
+> You can install Composer from the [official site](https://getcomposer.org/).
+
+> Before you begin, make sure that you have navigated your command prompt to the folder where you copied the files in the previous step.
+
+## Install Dependencies Using Composer
 
 Run this command in the command prompt.
 
 > Use the **CLI** to ensure interactivity for proper configuration.
+> In some IDEs, Composer may not be able to prompt for configuration settings.
 
 ```shell
 composer install
@@ -17,13 +24,19 @@ composer install
 The automatic setup script performs these tasks:
 
 - Installs the packages listed in the `composer.json` file and their dependencies into the `vendor` folder.
-- Creates the `composer.lock` file that locks all dependencies to exact versions (you can still run `composer update` to replace them with newer versions, if available).
+- Creates the `composer.lock` file that locks all dependencies to exact versions (you can still run `composer update` to replace them with newer versions, if available and installable without conflicts).
 - Configures PHP CodeSniffer, a utility to detect code style errors in PHP code.
 - Generate and save the OAuth2 keys in the `data/oauth` folder.
-- Creates the initial `config/autoload` configuration files:
-    - config/autoload/local.php
-    - config/autoload/local.test.php
-    - config/autoload/mail.global.php
+    - Performed by this script `./bin/generate-oauth2-keys.php`.
+- Creates the initial `config/autoload` configuration files.
+    - Performed by this script `./bin/composer-post-install-script.php`.
+    - These files are created:
+        - config/autoload/local.php
+        - config/autoload/local.test.php
+        - config/autoload/mail.global.php
+
+> The post install commands are run automatically on every `composer install` and `composer update`.
+> The scripts check if the files exist to prevent overwriting them.
 
 You should see this text below, along with a long list of packages to be installed instead of the `[...]`.
 

docs/book/v7/installation/configuration-files.md

@@ -1,7 +1,9 @@
 # Configuration Files
 
-The installation script from `composer.json` (under the key 'post-update-cmd') should have already created the files mentioned on this page.
-We mention them explicitly because you will need to visit them to fully configure your development environment.
+The post-update scripts from `composer.json` (under the key `post-update-cmd`) should have already created the files mentioned on this page.
+
+> We mention these files explicitly because you will need to visit them to fully configure your development environment.
+> You will need to do the same for the production environment when you deploy your application.
 
 ## Prepare config files
 

docs/book/v7/installation/doctrine-orm.md

@@ -1,17 +1,19 @@
 # Doctrine ORM
 
-This step saves the database connection credentials in an API configuration file.
-We do not cover the creation steps of the database itself.
-
 In this step you will:
 
-- Create a database.
-- Create and run a database migration that creates the main tables.
-- Execute fixtures which populate the database with initial data.
+- [Save the database connection credentials in the API configuration file](#setup-database).
+- [Learn about table names prefixing](#understanding-table-names-prefixing).
+- [Create a migration](#creating-migrations).
+- [Run a migration](#running-migrations).
+- [Executing fixtures to populate your database](#executing-fixtures).
+
+> We do not cover the creation steps of the database itself.
 
 ## Setup database
 
-Create a new **MariaDB**/**PostgreSQL** database and set its collation to `utf8mb4_general_ci`.
+Create a new **MariaDB** or **PostgreSQL** database.
+We recommend using a character set that supports UTF-8.
 
 Make sure you fill out the database credentials in `config/autoload/local.php` under `$databases['mariadb']` or `$databases['postgresql']`.
 Below is the item you need to focus on:
@@ -45,12 +47,23 @@ $databases = [
 > Make sure to use the same database name when you create the database in the next step.
 
 > If needed, you can add more database connections to this array.
-> Only **one active database connection** is allowed at a time.
+> Only **one active database connection** is allowed at a time, decided by the `doctrine.connection.orm_default.params` key in `config/autoload/local.php`.
 
-> By default, the application uses the 'mariadb' connection.
-> You can switch to another connection by updating `doctrine` -> `connection` -> `orm_default` -> `params`.
+By default, the application uses the `mariadb` connection, as seen in the `config/autoload/local.php` file below.
+You can switch to the 'postgresql' connection by commenting `'params' => $databases['mariadb']` and uncommenting `'params' => $databases['postgresql']`.
+ 
+```php
+'doctrine'            => [
+    'connection' => [
+        'orm_default' => [
+            'params' => $databases['mariadb'],
+//                'params' => $databases['postgresql'],
+        ],
+    ],
+],
+```
 
-### Prefixing table names
+### Understanding Table Names Prefixing
 
 The database configuration array contains an optional key called `table_prefix`.
 By default, it is an empty string, which means that all the tables will use the names specified in their respective entities, like below.
@@ -106,7 +119,13 @@ This feature helps organize databases and prevent naming conflicts if you plan o
 
 > `doctrine_migration_versions` is an exception and will remain unchanged, since it's a special table handled only by Doctrine Migrations.
 
-### Creating migrations
+### Creating Migrations
+
+When first installing the application, you will need to create a database migration.
+Migrations are used to create and update the database schema based on the entities defined in the application.
+Later, when you need to update the database schema (e.g., add/remove/edit columns), you will need to create new migrations to reflect the changes.
+
+> Using migration files is recommended compared to manually editing the database schema because they make database changes repeatable, trackable, and safe across environments.
 
 Create a database migration by executing the following command:
 
@@ -124,7 +143,12 @@ You can expect a message like this:
  To revert the migration you can use migrations:execute --down "Core\\App\\Migration\\Version20260327154303"
 ```
 
-### Running migrations
+### Running Migrations
+
+Running migrations is the process of applying the changes defined in the migration files to the database.
+
+> Make sure to double-check changes before running migrations, especially when removing columns as this can result in data loss.
+> The first migration should be safe, since the database is empty.
 
 Run the database migrations by executing the following command:
 
@@ -160,9 +184,29 @@ If everything ran correctly, you will get this confirmation.
 
 > The version number `YYYYMMDDHHMMSS` is the timestamp of the migration.
 
-### Executing fixtures
-
-**Fixtures are used to seed the database with initial values and should be executed after migrating the database.**
+### Executing Fixtures
+
+Fixtures are used to seed the database with initial values.
+This basically creates the first records in the database.
+
+> Fixtures should be executed after migrating the database to ensure the tables are created.
+
+> You can edit the initial records if your application demands it, even after running the fixtures.
+> For example, you can edit the user roles or the initial users.
+
+> **Important**
+> 
+> Edit the names and passwords of the initial users to prevent unauthorized users from logging into your application.
+> Make sure to do so in these files:
+> 
+> - `src/Core/src/App/Fixture/UserLoader.php`.
+> - `src/Core/src/App/Fixture/AdminLoader.php`.
+>
+> Check for these methods and change their default parameters:
+> 
+> - `setIdentity`.
+> - `usePassword`.
+> - And optionally `setFirstName` and `setLastName`.
 
 To execute fixtures, run:
 

docs/book/v7/installation/getting-started.md

@@ -1,10 +1,17 @@
 # Clone the project
 
-## Recommended development environment
+In this step you will:
+
+- [Clone the Dotkernel API project](#clone-the-project).
+- [Set file permissions](#set-file-and-folder-permissions).
 
 > If you are using the Microsoft Windows Operating System on your machine, you can use WSL2 as a development environment.
 > Read more about [installing and using WLS2](https://www.dotkernel.com/how-to/installing-almalinux-10-in-wsl2-php-mariadb-composer-phpmyadmin//).
 
+> Make sure to review the [prerequisites](prerequisites.md) before proceeding.
+
+## Clone the Project
+
 Using your terminal, navigate inside the directory where you want to download the project files.
 
 > Make sure that the directory is empty before running the command below.
@@ -15,9 +22,15 @@ Run this command to clone the project files.
 git clone https://github.com/dotkernel/api.git .
 ```
 
+## Set File and Folder Permissions
+
 To prevent future permission errors, certain folders must have their permissions set to 777.
 This way they assign everyone (owner, group, and other users) permissions to read, write, and execute.
 
+> It is safe to set these permissions as accessing the application files is dictated by the `.htaccess` file.
+> The `public` folder is publicly accessible by design, so those files are served directly.
+> Everything else is routed to the `index.php` file.
+
 ```shell
 chmod -R 777 data
 chmod -R 777 public/uploads

docs/book/v7/installation/test-the-installation.md

@@ -1,8 +1,20 @@
 # Test the installation
 
+In this final step you will:
+
+- [Test the installation of your virtual host](#running-the-application).
+- [Optionally, run a PHP built-in server](#old-way-of-doing-things-using-php-built-in-server).
+
+
 > If you are getting server error 500, make sure to check the folder permissions covered in the [FAQ page](https://docs.dotkernel.org/api-documentation/v7/installation/faq/)
 
-Sending a GET request to the home page for your virtual host should output the following message:
+## Running the application
+
+Send a GET request to the home page.
+You can do so by opening a browser and navigating to your virtual host URL.
+Alternatively, you can use a tool like [Bruno](https://www.usebruno.com/).
+
+The browser should output the following message:
 
 ```json
 {"message": "Dotkernel API version 7"}

docs/book/v7/introduction/architecture-at-a-glance.md

@@ -13,7 +13,6 @@ The **Core** is the backbone of your application—system-level infrastructure t
 
 - Authentication & Authorization: OAuth2-based authentication with RBAC (Role-Based Access Control)
 - Database Setup: Doctrine ORM configuration, entity definitions, and repositories
-- Middleware Pipeline: Request/response processing, error handling, content negotiation
 - Common Services: Mail service, error reporting, caching
 - Shared Entities: Admin/User entities, roles, permissions
 
@@ -38,7 +37,8 @@ You spend most development time here, implementing your API's features and busin
 
 ## Headless CMS Architecture
 
-Dotkernel API is built toward a Headless CMS architecture:
+Dotkernel API is built toward a Headless Platform architecture.
+Out of the box, it is a modular monolith that can be split into modules and microservices. 
 
 ```quote
 ┌──────────────────────────────────────────────────────────┐
@@ -251,11 +251,22 @@ Services are automatically resolved and injected by AttributedServiceFactory.
 ## Standards & PSRs
 
 Dotkernel API adheres to PHP standards for interoperability:
+Core PSRs
 
 - **PSR-7**: HTTP Message Interfaces (Requests/Responses)
 - **PSR-11**: Container Interface (Dependency Injection)
 - **PSR-15**: HTTP Handlers and Middleware (Request processing)
+
+Supporting PSRs, installed by dependencies:
+
+- **PSR-3**: Logger Interface (Requests/Responses)
 - **PSR-4**: Autoloading (File organization)
+- **PSR-6**: Caching Interface
+- **PSR-13**: Link Definition Interfaces
+- **PSR-14**: Event Dispatcher
+- **PSR-17**: HTTP Factories
+- **PSR-18**: HTTP Client
+- **PSR-20**: Clock
 
 This ensures your code can integrate with other PSR-compliant libraries.
 

docs/book/v7/introduction/introduction.md

@@ -3,7 +3,7 @@
 ## What is Dotkernel API?
 
 Dotkernel API is a modern, PSR-15 middleware-based REST API framework built on PHP 8.2+.
-It provides a headless CMS architecture with built-in OAuth2 authentication, RBAC authorization, and content negotiation out of the box.
+It is a Headless Platform with built-in OAuth2 authentication, RBAC authorization, and content negotiation.
 
 ## When to Use Dotkernel API
 
@@ -130,4 +130,4 @@ vendor/bin/phpunit --testsuite=FunctionalTests --testdox --colors=always
 ## Next Steps
 
 Ready to get started?
-Jump to the Installation Guide from the menu to set up your first Dotkernel API application.
+Jump to the [Installation Guide](https://docs.dotkernel.org/api-documentation/v7/installation/getting-started/) to set up your first Dotkernel API application.

docs/book/v7/introduction/psr.md

@@ -154,9 +154,3 @@ Provides a standard interface for reading the system clock.
 │ (Loads services automatically)            │
 └───────────────────────────────────────────┘
 ```
-
-## Next Steps
-
-- Review PSR-7 and PSR-15 in detail—these are essential for understanding Dotkernel API.
-- Check individual PSR pages for implementation examples.
-- Consider how PSRs apply to your custom code and modules.

docs/book/v7/introduction/server-requirements.md

@@ -1,23 +1,24 @@
 # Server Requirements
 
-For production environments, we highly recommend a nix-based system (Linux, BSD, macOS).
+For production environments, we highly recommend a Linux-based system.
 Windows is supported for development via WSL2.
 
 ## Operating System
 
 ### Production
 
-- Linux (CentOS, Ubuntu, Debian, AlmaLinux)
+- Linux (AlmaLinux, Debian)
 - BSD (FreeBSD)
 - macOS (Intel or Apple Silicon)
 
 ### Development
 
-- Windows 10/11 (via WSL2 - see WSL2 Setup Guide)
+- Windows 10/11 (via WSL2 - see our [WSL2 Setup Guide](https://docs.dotkernel.org/development/v2/setup/installation/))
 - macOS
 - Linux
 
-> We recommend a nix-based environment for production because of its improved performance, stability, and security hardening options compared to Windows Server.
+> We recommend a Linux-based environment for production because of its improved performance, stability, and security hardening options compared to Windows Server.
+> It should also work on Microsoft's IIS server with minimal modifications, but we have not tested this setup in our projects.
 
 ## Webserver
 
@@ -39,7 +40,6 @@ Earlier PHP versions are not supported.
 
 ### Supported PHP Configurations
 
-- mod_php (Apache module) - Simpler setup, good for shared hosting
 - FPM (FastCGI Process Manager) - Recommended for production, better performance and security isolation
 - CLI SAPI (Command Line Interface) - Required for Cron jobs, migrations, and fixtures
 
@@ -83,8 +83,6 @@ Tested with:
 Tested with:
 
 - PostgreSQL 13 and above
-- PostgreSQL 14 (current stable)
-- PostgreSQL 15 (latest)
 
 ### Database Collation