From 61c3e0cf9ac8a89ec5bc69f6e3cd2d043814b7fd Mon Sep 17 00:00:00 2001
From: Romain Lanz <2793951+RomainLanz@users.noreply.github.com>
Date: Tue, 7 May 2024 14:45:00 +0200
Subject: [PATCH] refactor: new structure (#86)

* docs: first draft of new structure

* chore: move back to sentence casing

* chore: remove .DS_Store file

* chore: update casing of HTTP

* chore: update GH discussions link

* chore: remove bunch of redirects

* chore: correct bunch of link, tables, images and code examples

* chore: write lucid & edge page

* chore: write deployment guide

* fix(deployment): correct heading

* chore(deployment): add Dockerfile

* chore(deployment): remove not needed cache view directive

* chore(deployment): remove ignore ts errors flag in dockerfile

* chore: rename rc file to adonisrc file

* chore: rename securing ssr apps

* chore: rename api references to references

* chore: correct redirect for rc file

* chore: improve the content of quick lucid doc

* fix: correct broken links
---
 README.md                                     |    2 +-
 content/docs/ace/creating_commands.md         |    4 +-
 content/docs/ace/prompts.md                   |    2 +-
 content/docs/ace/tui.md                       |    2 +-
 .../access_tokens_guard.md                    |   10 +-
 .../basic_auth_guard.md                       |    6 +-
 .../custom_auth_guard.md}                     |    2 +-
 .../{auth => authentication}/introduction.md  |   14 +-
 .../{auth => authentication}/session_guard.md |   10 +-
 .../social_authentication.md}                 |    4 +-
 .../verifying_user_credentials.md             |   10 +-
 .../body_parser.md}                           |   12 +-
 content/docs/{http => basics}/controllers.md  |   16 +-
 content/docs/{http => basics}/cookies.md      |    2 +-
 .../{http => basics}/exception_handling.md    |   20 +-
 content/docs/{http => basics}/file_uploads.md |   42 +-
 content/docs/{http => basics}/middleware.md   |    8 +-
 .../{http => basics}/middleware_flow 2.jpeg   |  Bin
 .../{http => basics}/middleware_flow.jpeg     |  Bin
 .../post_comments_resource_routes_list.png    |  Bin
 ...comments_resource_routes_list_original.png |  Bin
 .../post_resource_routes_list.png             |  Bin
 .../post_resource_routes_list_original.png    |  Bin
 content/docs/{http => basics}/request.md      |   10 +-
 content/docs/{http => basics}/response.md     |    8 +-
 content/docs/{http => basics}/routing.md      |  223 ++-
 content/docs/{http => basics}/session.md      |   16 +-
 .../{http => basics}/shallow_routes_list.png  |  Bin
 .../shallow_routes_list_original.jpg          |  Bin
 .../{http => basics}/static_file_server.md    |    4 +-
 content/docs/{http => basics}/validation.md   |    8 +-
 .../vite-dev-server-original.png              |  Bin
 .../docs/{http => basics}/vite-dev-server.png |  Bin
 .../assets_bundling.md => basics/vite.md}     |    4 +-
 .../{http => basics}/vscode_routes_list.png   |  Bin
 .../vscode_routes_list_original.png           |  Bin
 .../adonisrc_file.md                          |    2 +-
 .../{fundamentals => concepts}/application.md |   16 +-
 .../application_lifecycle.md                  |    2 +-
 .../async_local_storage.md                    |    4 +-
 .../boot_phase_flow_chart.png                 |  Bin
 .../boot_phase_flow_chart_original.png        |  Bin
 .../config_providers.md                       |    6 +-
 .../container_services.md                     |    2 +-
 .../dependency_injection.md}                  |    4 +-
 .../extending_the_framework.md                |   34 +-
 .../docs/{fundamentals => concepts}/hmr.md    |    0
 .../docs/{http => concepts}/http_context.md   |   44 +-
 .../http_overview.md}                         |   26 +-
 .../{fundamentals => concepts}/scaffolding.md |   20 +-
 .../scaffolding_workflow.png                  |  Bin
 .../scaffolding_workflow_original.png         |  Bin
 .../server_boot_lifecycle.png                 |  Bin
 .../server_boot_lifecycle_original.png        |  Bin
 .../service_providers.md                      |   10 +-
 .../start_phase_flow_chart.png                |  Bin
 .../start_phase_flow_chart_original.png       |  Bin
 .../termination_phase_flow_chart.png          |  Bin
 .../termination_phase_flow_chart_original.png |  Bin
 .../tooling_config.md                         |    0
 .../typescript_build_process.md               |   12 +-
 content/docs/database/introduction.md         |   16 +
 content/docs/database/lucid.md                |  212 +++
 content/docs/database/sql.md                  |   32 -
 content/docs/db.json                          |  621 ++++---
 content/docs/digging_deeper/emitter.md        |   14 +-
 content/docs/digging_deeper/i18n.md           |   80 +-
 content/docs/digging_deeper/locks.md          |    8 +-
 content/docs/digging_deeper/logger.md         |    4 +-
 content/docs/digging_deeper/mail.md           | 1426 +++++++++++++++++
 content/docs/{ace => digging_deeper}/repl.md  |    6 +-
 content/docs/digging_deeper/transmit.md       |    2 +-
 content/docs/experimental/assembler_hooks.md  |    4 +-
 content/docs/experimental/inertia.md          |   14 +-
 content/docs/experimental/vite.md             |    4 +-
 content/docs/fundamentals/.DS_Store           |  Bin 6148 -> 0 bytes
 content/docs/fundamentals/deployments.md      |  105 --
 .../configuration.md}                         |    4 +-
 content/docs/getting_started/deployment.md    |  231 +++
 .../env_intellisense.jpeg                     |  Bin
 .../env_intellisense_original.png             |  Bin
 .../environment_variables.md}                 |    4 +-
 .../folder_structure.md                       |   10 +-
 .../installation.md                           |   10 +-
 content/docs/guides/.DS_Store                 |  Bin 6148 -> 0 bytes
 content/docs/http/.DS_Store                   |  Bin 6148 -> 0 bytes
 content/docs/http/url_builder.md              |  186 ---
 content/docs/mail/class_based_mails.md        |  190 ---
 content/docs/mail/custom_transports.md        |  110 --
 content/docs/mail/fake_mailer.md              |  192 ---
 content/docs/mail/introduction.md             |  509 ------
 content/docs/mail/message.md                  |  422 -----
 .../forms_and_validation/custom_messages.md   |    0
 .../pika-1675149043774-1x.jpeg                |  Bin
 .../forms_and_validation/schema_101.md        |    0
 .../validating_api_requests.md                |    0
 .../validating_server_rendered_forms.md       |    0
 .../forms_and_validation/validation.md        |    6 +-
 .../validator-static-types.webp               |  Bin
 .../fundamentals/package_development.md       |   14 +-
 .../{ => old}/http/assets_bundling_encore.md  |    0
 .../{ => old}/pages/adonisjs-at-a-glance.md   |    0
 content/docs/{ => old}/resources/updates.md   |    0
 .../tutorial/creating-new-application.md      |    0
 .../docs/{ => old}/tutorial/introduction.md   |    0
 .../{ => old}/validator/custom_messages.md    |    0
 .../docs/{ => old}/validator/custom_rules.md  |    0
 .../{ => old}/validator/error_reporters.md    |    2 +-
 .../docs/{ => old}/validator/introduction.md  |    0
 .../{ => old}/validator/schema_caching.md     |    0
 .../docs/{ => old}/validator/schema_types.md  |    0
 .../{ => old}/validator/validation_rules.md   |    0
 content/docs/preface/contribution_guide.md    |  113 ++
 content/docs/{guides => preface}/faqs.md      |    4 +-
 content/docs/preface/governance.md            |  104 ++
 .../docs/{guides => preface}/introduction.md  |   10 +-
 content/docs/{guides => preface}/releases.md  |    0
 .../{reference => references}/commands.md     |   20 +-
 .../docs/{reference => references}/edge.md    |   20 +-
 .../docs/{reference => references}/events.md  |    2 +-
 .../{reference => references}/exceptions.md   |   25 +-
 .../docs/{reference => references}/helpers.md |    2 +-
 .../authorization.md                          |   14 +-
 content/docs/security/encryption.md           |    2 +-
 content/docs/security/{hash.md => hashing.md} |    4 +-
 .../{rate-limiter.md => rate_limiting.md}     |   12 +-
 ...curity.md => securing_ssr_applications.md} |   21 +-
 content/docs/testing/browser_tests.md         |    7 +-
 ...{commandline_tests.md => console_tests.md} |    4 +-
 .../{database_tests.md => database.md}        |    0
 content/docs/testing/http_tests.md            |   10 +-
 content/docs/testing/introduction.md          |   16 +-
 content/docs/testing/mocks_and_fakes.md       |   10 +-
 .../edgejs.md}                                |   37 +-
 .../docs/views-and-templates/introduction.md  |   21 +
 public/_redirects                             |  139 +-
 templates/partials/introduction_cards.edge    |    2 +-
 137 files changed, 3131 insertions(+), 2527 deletions(-)
 rename content/docs/{auth => authentication}/access_tokens_guard.md (95%)
 rename content/docs/{auth => authentication}/basic_auth_guard.md (95%)
 rename content/docs/{auth/custom_auth_guards.md => authentication/custom_auth_guard.md} (98%)
 rename content/docs/{auth => authentication}/introduction.md (91%)
 rename content/docs/{auth => authentication}/session_guard.md (94%)
 rename content/docs/{digging_deeper/social_auth.md => authentication/social_authentication.md} (98%)
 rename content/docs/{auth => authentication}/verifying_user_credentials.md (94%)
 rename content/docs/{http/bodyparser_middleware.md => basics/body_parser.md} (95%)
 rename content/docs/{http => basics}/controllers.md (93%)
 rename content/docs/{http => basics}/cookies.md (97%)
 rename content/docs/{http => basics}/exception_handling.md (92%)
 rename content/docs/{http => basics}/file_uploads.md (78%)
 rename content/docs/{http => basics}/middleware.md (97%)
 rename content/docs/{http => basics}/middleware_flow 2.jpeg (100%)
 rename content/docs/{http => basics}/middleware_flow.jpeg (100%)
 rename content/docs/{http => basics}/post_comments_resource_routes_list.png (100%)
 rename content/docs/{http => basics}/post_comments_resource_routes_list_original.png (100%)
 rename content/docs/{http => basics}/post_resource_routes_list.png (100%)
 rename content/docs/{http => basics}/post_resource_routes_list_original.png (100%)
 rename content/docs/{http => basics}/request.md (96%)
 rename content/docs/{http => basics}/response.md (96%)
 rename content/docs/{http => basics}/routing.md (75%)
 rename content/docs/{http => basics}/session.md (94%)
 rename content/docs/{http => basics}/shallow_routes_list.png (100%)
 rename content/docs/{http => basics}/shallow_routes_list_original.jpg (100%)
 rename content/docs/{http => basics}/static_file_server.md (96%)
 rename content/docs/{http => basics}/validation.md (94%)
 rename content/docs/{http => basics}/vite-dev-server-original.png (100%)
 rename content/docs/{http => basics}/vite-dev-server.png (100%)
 rename content/docs/{http/assets_bundling.md => basics/vite.md} (98%)
 rename content/docs/{http => basics}/vscode_routes_list.png (100%)
 rename content/docs/{http => basics}/vscode_routes_list_original.png (100%)
 rename content/docs/{fundamentals => concepts}/adonisrc_file.md (99%)
 rename content/docs/{fundamentals => concepts}/application.md (96%)
 rename content/docs/{fundamentals => concepts}/application_lifecycle.md (99%)
 rename content/docs/{fundamentals => concepts}/async_local_storage.md (97%)
 rename content/docs/{fundamentals => concepts}/boot_phase_flow_chart.png (100%)
 rename content/docs/{fundamentals => concepts}/boot_phase_flow_chart_original.png (100%)
 rename content/docs/{fundamentals => concepts}/config_providers.md (93%)
 rename content/docs/{fundamentals => concepts}/container_services.md (97%)
 rename content/docs/{fundamentals/ioc_container.md => concepts/dependency_injection.md} (99%)
 rename content/docs/{fundamentals => concepts}/extending_the_framework.md (75%)
 rename content/docs/{fundamentals => concepts}/hmr.md (100%)
 rename content/docs/{http => concepts}/http_context.md (83%)
 rename content/docs/{http/introduction.md => concepts/http_overview.md} (79%)
 rename content/docs/{fundamentals => concepts}/scaffolding.md (94%)
 rename content/docs/{fundamentals => concepts}/scaffolding_workflow.png (100%)
 rename content/docs/{fundamentals => concepts}/scaffolding_workflow_original.png (100%)
 rename content/docs/{http => concepts}/server_boot_lifecycle.png (100%)
 rename content/docs/{http => concepts}/server_boot_lifecycle_original.png (100%)
 rename content/docs/{fundamentals => concepts}/service_providers.md (90%)
 rename content/docs/{fundamentals => concepts}/start_phase_flow_chart.png (100%)
 rename content/docs/{fundamentals => concepts}/start_phase_flow_chart_original.png (100%)
 rename content/docs/{fundamentals => concepts}/termination_phase_flow_chart.png (100%)
 rename content/docs/{fundamentals => concepts}/termination_phase_flow_chart_original.png (100%)
 rename content/docs/{fundamentals => concepts}/tooling_config.md (100%)
 rename content/docs/{fundamentals => concepts}/typescript_build_process.md (94%)
 create mode 100644 content/docs/database/introduction.md
 create mode 100644 content/docs/database/lucid.md
 delete mode 100644 content/docs/database/sql.md
 create mode 100644 content/docs/digging_deeper/mail.md
 rename content/docs/{ace => digging_deeper}/repl.md (94%)
 delete mode 100644 content/docs/fundamentals/.DS_Store
 delete mode 100644 content/docs/fundamentals/deployments.md
 rename content/docs/{guides/config.md => getting_started/configuration.md} (96%)
 create mode 100644 content/docs/getting_started/deployment.md
 rename content/docs/{guides => getting_started}/env_intellisense.jpeg (100%)
 rename content/docs/{guides => getting_started}/env_intellisense_original.png (100%)
 rename content/docs/{guides/env.md => getting_started/environment_variables.md} (98%)
 rename content/docs/{guides => getting_started}/folder_structure.md (93%)
 rename content/docs/{guides => getting_started}/installation.md (95%)
 delete mode 100644 content/docs/guides/.DS_Store
 delete mode 100644 content/docs/http/.DS_Store
 delete mode 100644 content/docs/http/url_builder.md
 delete mode 100644 content/docs/mail/class_based_mails.md
 delete mode 100644 content/docs/mail/custom_transports.md
 delete mode 100644 content/docs/mail/fake_mailer.md
 delete mode 100644 content/docs/mail/introduction.md
 delete mode 100644 content/docs/mail/message.md
 rename content/docs/{ => old}/forms_and_validation/custom_messages.md (100%)
 rename content/docs/{ => old}/forms_and_validation/pika-1675149043774-1x.jpeg (100%)
 rename content/docs/{ => old}/forms_and_validation/schema_101.md (100%)
 rename content/docs/{ => old}/forms_and_validation/validating_api_requests.md (100%)
 rename content/docs/{ => old}/forms_and_validation/validating_server_rendered_forms.md (100%)
 rename content/docs/{ => old}/forms_and_validation/validation.md (92%)
 rename content/docs/{ => old}/forms_and_validation/validator-static-types.webp (100%)
 rename content/docs/{ => old}/fundamentals/package_development.md (87%)
 rename content/docs/{ => old}/http/assets_bundling_encore.md (100%)
 rename content/docs/{ => old}/pages/adonisjs-at-a-glance.md (100%)
 rename content/docs/{ => old}/resources/updates.md (100%)
 rename content/docs/{ => old}/tutorial/creating-new-application.md (100%)
 rename content/docs/{ => old}/tutorial/introduction.md (100%)
 rename content/docs/{ => old}/validator/custom_messages.md (100%)
 rename content/docs/{ => old}/validator/custom_rules.md (100%)
 rename content/docs/{ => old}/validator/error_reporters.md (98%)
 rename content/docs/{ => old}/validator/introduction.md (100%)
 rename content/docs/{ => old}/validator/schema_caching.md (100%)
 rename content/docs/{ => old}/validator/schema_types.md (100%)
 rename content/docs/{ => old}/validator/validation_rules.md (100%)
 create mode 100644 content/docs/preface/contribution_guide.md
 rename content/docs/{guides => preface}/faqs.md (93%)
 create mode 100644 content/docs/preface/governance.md
 rename content/docs/{guides => preface}/introduction.md (83%)
 rename content/docs/{guides => preface}/releases.md (100%)
 rename content/docs/{reference => references}/commands.md (93%)
 rename content/docs/{reference => references}/edge.md (80%)
 rename content/docs/{reference => references}/events.md (98%)
 rename content/docs/{reference => references}/exceptions.md (86%)
 rename content/docs/{reference => references}/helpers.md (99%)
 rename content/docs/{digging_deeper => security}/authorization.md (95%)
 rename content/docs/security/{hash.md => hashing.md} (98%)
 rename content/docs/security/{rate-limiter.md => rate_limiting.md} (97%)
 rename content/docs/security/{web-security.md => securing_ssr_applications.md} (94%)
 rename content/docs/testing/{commandline_tests.md => console_tests.md} (98%)
 rename content/docs/testing/{database_tests.md => database.md} (100%)
 rename content/docs/{http/views_and_templates.md => views-and-templates/edgejs.md} (52%)
 create mode 100644 content/docs/views-and-templates/introduction.md

diff --git a/README.md b/README.md
index d3391a10..1b20ac03 100644
--- a/README.md
+++ b/README.md
@@ -120,7 +120,7 @@ A typical database entry has the following properties.
 {
   "permalink": "introduction",
   "title": "Introduction",
-  "contentPath": "./introduction.md",
+  "contentPath": "./http_overview.md",
   "category": "Guides"
 }
 ```
diff --git a/content/docs/ace/creating_commands.md b/content/docs/ace/creating_commands.md
index cbe67d40..e515527d 100644
--- a/content/docs/ace/creating_commands.md
+++ b/content/docs/ace/creating_commands.md
@@ -2,7 +2,7 @@
 
 Alongside using Ace commands, you may also create custom commands as part of your application codebase. The commands are stored inside the `commands` directory (at the root level). You may create a command by running the following command.
 
-See also: [Make command](../reference/commands.md#makecommand)
+See also: [Make command](../references/commands.md#makecommand)
 
 ```sh
 node ace make:command greet
@@ -229,7 +229,7 @@ export default class GreetCommand extends BaseCommand {
 
 ## Dependency injection
 
-Ace commands are constructed and executed using the [IoC container](../fundamentals/ioc_container.md). Therefore, you can type-hint dependencies on command lifecycle methods and use the `@inject` decorator to resolve them.
+Ace commands are constructed and executed using the [IoC container](../../concepts/dependency_injection). Therefore, you can type-hint dependencies on command lifecycle methods and use the `@inject` decorator to resolve them.
 
 For demonstration, let's inject the `UserService` class in all the lifecycle methods.
 
diff --git a/content/docs/ace/prompts.md b/content/docs/ace/prompts.md
index 4a546b0c..fa5d7c3e 100644
--- a/content/docs/ace/prompts.md
+++ b/content/docs/ace/prompts.md
@@ -13,7 +13,7 @@ Prompts are interactive terminal widgets you can use to accept user input. Ace p
 
 Ace prompts are built with testing in mind. When writing tests, you may trap prompts and respond to them programmatically.
 
-See also: [Testing ace commands](../testing/commandline_tests.md)
+See also: [Testing ace commands](../../testing/console_tests)
 
 ## Displaying a prompt
 
diff --git a/content/docs/ace/tui.md b/content/docs/ace/tui.md
index 7268919f..5aacd7bd 100644
--- a/content/docs/ace/tui.md
+++ b/content/docs/ace/tui.md
@@ -4,7 +4,7 @@ Ace terminal UI is powered by the [@poppinss/cliui](https://github.com/poppinss/
 
 The terminal UI primitives are built with testing in mind. When writing tests, you may turn on the `raw` mode to disable colors and formatting and collect all logs in memory to write assertions against them.
 
-See also: [Testing Ace commands](../testing/commandline_tests.md)
+See also: [Testing Ace commands](../../testing/console_tests)
 
 ## Displaying log messages
 
diff --git a/content/docs/auth/access_tokens_guard.md b/content/docs/authentication/access_tokens_guard.md
similarity index 95%
rename from content/docs/auth/access_tokens_guard.md
rename to content/docs/authentication/access_tokens_guard.md
index 4966c442..21e2019d 100644
--- a/content/docs/auth/access_tokens_guard.md
+++ b/content/docs/authentication/access_tokens_guard.md
@@ -178,7 +178,7 @@ In the following example, we **find a user by id** and **issue them an access to
 
 The `.create` method accepts an instance of the User model and returns an instance of the [AccessToken](https://github.com/adonisjs/auth/blob/main/modules/access_tokens_guard/access_token.ts) class. 
 
-The `token.value` property contains the value (wrapped as a [Secret](../reference/helpers.md#secret)) that must be shared with the user. The value is only available when generating the token, and the user will not be able to see it again.
+The `token.value` property contains the value (wrapped as a [Secret](../references/helpers.md#secret)) that must be shared with the user. The value is only available when generating the token, and the user will not be able to see it again.
 
 ```ts
 import router from '@adonisjs/core/services/router'
@@ -235,7 +235,7 @@ await User.accessTokens.create(user, ['server:create', 'server:read'])
 
 ### Token abilities vs. Bouncer abilities
 
-You should not confuse token abilities with [bouncer authorization checks](../digging_deeper/authorization.md#defining-abilities). Let's try to understand the difference with a practical example.
+You should not confuse token abilities with [bouncer authorization checks](../security/authorization.md#defining-abilities). Let's try to understand the difference with a practical example.
 
 - Let's say you define a **bouncer ability that allows admin users to create new projects**.
 
@@ -341,7 +341,7 @@ The `tokensUserProvider` method accepts the following options and returns an ins
 ## Authenticating requests
 Once the guard has been configured, you can start authenticating requests using the `auth` middleware or manually calling the `auth.authenticate` method.
 
-The `auth.authenticate` method returns an instance of the User model for the authenticated user, or it throws an [E_UNAUTHORIZED_ACCESS](../reference/exceptions.md#e_unauthorized_access) exception when unable to authenticate the request.
+The `auth.authenticate` method returns an instance of the User model for the authenticated user, or it throws an [E_UNAUTHORIZED_ACCESS](../references/exceptions.md#e_unauthorized_access) exception when unable to authenticate the request.
 
 ```ts
 import router from '@adonisjs/core/services/router'
@@ -393,7 +393,7 @@ class PostsController {
 
 ### Get authenticated user or fail
 
-If you do not like using the [non-null assertion operator](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#non-null-assertion-operator-postfix-) on the `auth.user` property, you may use the `auth.getUserOrFail` method. This method will return the user object or throw [E_UNAUTHORIZED_ACCESS](../reference/exceptions.md#e_unauthorized_access) exception.
+If you do not like using the [non-null assertion operator](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#non-null-assertion-operator-postfix-) on the `auth.user` property, you may use the `auth.getUserOrFail` method. This method will return the user object or throw [E_UNAUTHORIZED_ACCESS](../references/exceptions.md#e_unauthorized_access) exception.
 
 ```ts
 import { HttpContext } from '@adonisjs/core/http'
@@ -483,4 +483,4 @@ await User.accessTokens.delete(user, token.identifier)
 ```
 
 ## Events
-Please check the [events reference guide](../reference/events.md#access_tokens_authauthentication_attempted) to view the list of available events emitted by the access tokens guard.
+Please check the [events reference guide](../references/events.md#access_tokens_authauthentication_attempted) to view the list of available events emitted by the access tokens guard.
diff --git a/content/docs/auth/basic_auth_guard.md b/content/docs/authentication/basic_auth_guard.md
similarity index 95%
rename from content/docs/auth/basic_auth_guard.md
rename to content/docs/authentication/basic_auth_guard.md
index 231fb0ff..a0d3f332 100644
--- a/content/docs/auth/basic_auth_guard.md
+++ b/content/docs/authentication/basic_auth_guard.md
@@ -1,4 +1,4 @@
-# Basic authentication
+# Basic authentication guard
 
 The basic auth guard is an implementation of the [HTTP authentication framework](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication), in which the client must pass the user credentials as a base64 encoded string via the `Authorization` header. The server allows the request if the credentials are valid. Otherwise, a web-native prompt is displayed to re-enter the credentials.
 
@@ -33,7 +33,7 @@ The `basicAuthUserProvider` method creates an instance of the [BasicAuthLucidUse
 
 
 ## Preparing the User model
-The model (`User` model in this example) configured with the `basicAuthUserProvider` must use the [AuthFinder](./verifying_user_credentials.md#using-the-auth-finder-mixin) mixin to verify the user credentials during authentication.
+The model (`User` model in this example) configured with the `basicAuthUserProvider` must use the [AuthFinder](verifying_user_credentials.md#using-the-auth-finder-mixin) mixin to verify the user credentials during authentication.
 
 ```ts
 import { DateTime } from 'luxon'
@@ -123,7 +123,7 @@ router
 ```
 
 ### Get authenticated user or fail
-If you do not like using the [non-null assertion operator](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#non-null-assertion-operator-postfix-) on the `auth.user` property, you may use the `auth.getUserOrFail` method. This method will return the user object or throw [E_UNAUTHORIZED_ACCESS](../reference/exceptions.md#e_unauthorized_access) exception.
+If you do not like using the [non-null assertion operator](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#non-null-assertion-operator-postfix-) on the `auth.user` property, you may use the `auth.getUserOrFail` method. This method will return the user object or throw [E_UNAUTHORIZED_ACCESS](../references/exceptions.md#e_unauthorized_access) exception.
 
 ```ts
 import { middleware } from '#start/kernel'
diff --git a/content/docs/auth/custom_auth_guards.md b/content/docs/authentication/custom_auth_guard.md
similarity index 98%
rename from content/docs/auth/custom_auth_guards.md
rename to content/docs/authentication/custom_auth_guard.md
index 44fa6a83..e0fa920c 100644
--- a/content/docs/auth/custom_auth_guards.md
+++ b/content/docs/authentication/custom_auth_guard.md
@@ -247,7 +247,7 @@ Authenticating a request includes:
 - Verifying its authenticity.
 - Fetching the user for whom the token was generated.
 
-Our guard will need access to the [HttpContext](../http/http_context.md) to read request headers and cookies, so let's update the class `constructor` and accept it as an argument.
+Our guard will need access to the [HttpContext](../concepts/http_context.md) to read request headers and cookies, so let's update the class `constructor` and accept it as an argument.
 
 ```ts
 // insert-start
diff --git a/content/docs/auth/introduction.md b/content/docs/authentication/introduction.md
similarity index 91%
rename from content/docs/auth/introduction.md
rename to content/docs/authentication/introduction.md
index c4e8eb90..75bba793 100644
--- a/content/docs/auth/introduction.md
+++ b/content/docs/authentication/introduction.md
@@ -22,7 +22,7 @@ The auth package narrowly focuses on authenticating HTTP requests, and the follo
 
 - User registration features like **registration forms**, **email verification**, and **account activation**.
 - Account management features like **password recovery** or **email update**.
-- Assigning roles or verifying permissions. Instead, [use bouncer](../digging_deeper/authorization.md) to implement authorization checks in your application.
+- Assigning roles or verifying permissions. Instead, [use bouncer](../security/authorization.md) to implement authorization checks in your application.
 
 
 <!-- :::note
@@ -38,11 +38,11 @@ It provides ready-to-use actions for user registration, email management, sessio
 
 ## Choosing an auth guard
 
-The following inbuilt authentication guards provide you with the most straightforward workflow for authenticating users without compromising the security of your applications. Also, you can [build your authentication guards](./custom_auth_guards.md) for custom requirements.
+The following inbuilt authentication guards provide you with the most straightforward workflow for authenticating users without compromising the security of your applications. Also, you can [build your authentication guards](custom_auth_guard) for custom requirements.
 
 ### Session
 
-The session guard uses the [@adonisjs/session](../http/session.md) package to track the logged-in user state inside the session store. 
+The session guard uses the [@adonisjs/session](../basics/session.md) package to track the logged-in user state inside the session store. 
 
 Sessions and cookies have been on the internet for a long time and work great for most applications. We recommend using the session guard:
 
@@ -127,7 +127,7 @@ node ace add @adonisjs/auth --guard=basic_auth
 ## The Initialize auth middleware
 During setup, we register the `@adonisjs/auth/initialize_auth_middleware` within your application. The middleware is responsible for creating an instance of the [Authenticator](https://github.com/adonisjs/auth/blob/main/src/authenticator.ts) class and shares it via the `ctx.auth` property with the rest of the request.
 
-Note that the initialize auth middleware does not authenticate the request or protect the routes. It's used only for initializing the authenticator and sharing it with the rest of the request. You must use the [auth](./session_guard.md#protecting-routes) middleware for protecting routes.
+Note that the initialize auth middleware does not authenticate the request or protect the routes. It's used only for initializing the authenticator and sharing it with the rest of the request. You must use the [auth](session_guard.md#protecting-routes) middleware for protecting routes.
 
 Also, the same authenticator instance is shared with Edge templates (if your app is using Edge), and you can access it using the `auth` property. For example:
 
@@ -170,6 +170,6 @@ Also, update the `User` model if you define, rename, or remove columns from the
 
 ## Next steps
 
-- Learn how to [verify user credentials](./verifying_user_credentials.md) without compromising the security of your application.
-- Use [session guard](./session_guard.md) for stateful authentication.
-- Use [access tokens guard](./access_tokens_guard.md) for tokens based authentication.
+- Learn how to [verify user credentials](verifying_user_credentials.md) without compromising the security of your application.
+- Use [session guard](session_guard.md) for stateful authentication.
+- Use [access tokens guard](access_tokens_guard.md) for tokens based authentication.
diff --git a/content/docs/auth/session_guard.md b/content/docs/authentication/session_guard.md
similarity index 94%
rename from content/docs/auth/session_guard.md
rename to content/docs/authentication/session_guard.md
index d3a3801e..facb81fe 100644
--- a/content/docs/auth/session_guard.md
+++ b/content/docs/authentication/session_guard.md
@@ -1,5 +1,5 @@
 # Session guard
-The session guard uses the [@adonisjs/session](../http/session.md) package to login and authenticate users during an HTTP request.
+The session guard uses the [@adonisjs/session](../basics/session.md) package to login and authenticate users during an HTTP request.
 
 Sessions and cookies have been on the internet for a long time and work great for most applications. Therefore, we recommend using the session guard for server-rendered applications or an SPA web client on the same top-level domain.
 
@@ -39,7 +39,7 @@ You can login a user using the `guard.login` method. The method accepts an insta
 
 In the following example:
 
-- We use the `verifyCredentials` from the [AuthFinder mixin](./verifying_user_credentials.md#using-the-auth-finder-mixin) to find a user by email and password.
+- We use the `verifyCredentials` from the [AuthFinder mixin](verifying_user_credentials.md#using-the-auth-finder-mixin) to find a user by email and password.
 
 - The `auth.use('web')` returns an instance of the [SessionGuard](https://github.com/adonisjs/auth/blob/main/modules/session_guard/guard.ts) configured inside the `config/auth.ts` file.
 
@@ -193,7 +193,7 @@ router
 
 ### Get authenticated user or fail
 
-If you do not like using the [non-null assertion operator](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#non-null-assertion-operator-postfix-) on the `auth.user` property, you may use the `auth.getUserOrFail` method. This method will return the user object or throw [E_UNAUTHORIZED_ACCESS](../reference/exceptions.md#e_unauthorized_access) exception.
+If you do not like using the [non-null assertion operator](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#non-null-assertion-operator-postfix-) on the `auth.user` property, you may use the `auth.getUserOrFail` method. This method will return the user object or throw [E_UNAUTHORIZED_ACCESS](../references/exceptions.md#e_unauthorized_access) exception.
 
 ```ts
 import { middleware } from '#start/kernel'
@@ -210,7 +210,7 @@ router
 ```
 
 ### Access user within Edge templates
-The [InitializeAuthMiddleware](./introduction.md#the-initialize-auth-middleware) also shares the `ctx.auth` property with Edge templates. Therefore, you can access the currently logged-in user via the `auth.user` property.
+The [InitializeAuthMiddleware](introduction.md#the-initialize-auth-middleware) also shares the `ctx.auth` property with Edge templates. Therefore, you can access the currently logged-in user via the `auth.user` property.
 
 ```edge
 @if(auth.isAuthenticated)
@@ -394,4 +394,4 @@ router
 Finally, you can configure the redirect route for the logged-in users inside the `./app/middleware/guest_middleware.ts` file.
 
 ## Events
-Please check the [events reference guide](../reference/events.md#session_authcredentials_verified) to view the list of available events emitted by the Auth package.
+Please check the [events reference guide](../references/events.md#session_authcredentials_verified) to view the list of available events emitted by the Auth package.
diff --git a/content/docs/digging_deeper/social_auth.md b/content/docs/authentication/social_authentication.md
similarity index 98%
rename from content/docs/digging_deeper/social_auth.md
rename to content/docs/authentication/social_authentication.md
index b54448dc..f7b80382 100644
--- a/content/docs/digging_deeper/social_auth.md
+++ b/content/docs/authentication/social_authentication.md
@@ -11,7 +11,7 @@ Ally comes with the following inbuilt drivers, alongside an extensible API to [r
 - Discord
 - LinkedIn
 
-Ally does not store any users or access tokens on your behalf. It implements the OAuth2 and OAuth1 protocols, authenticates a user with social service, and provides user details. You can store that information inside a database and use the [auth](../auth/introduction.md) package to login the user within your application.
+Ally does not store any users or access tokens on your behalf. It implements the OAuth2 and OAuth1 protocols, authenticates a user with social service, and provides user details. You can store that information inside a database and use the [auth](introduction.md) package to login the user within your application.
 
 ## Installation
 
@@ -235,7 +235,7 @@ The scopes can be defined within the `config/ally.ts` file, or you can define th
 
 Thanks to TypeScript, you will get autocomplete suggestions for all the available scopes.
 
-![](./ally_autocomplete.png)
+![](../digging_deeper/ally_autocomplete.png)
 
 ```ts
 // title: config/ally.ts
diff --git a/content/docs/auth/verifying_user_credentials.md b/content/docs/authentication/verifying_user_credentials.md
similarity index 94%
rename from content/docs/auth/verifying_user_credentials.md
rename to content/docs/authentication/verifying_user_credentials.md
index 525954f9..c598dacf 100644
--- a/content/docs/auth/verifying_user_credentials.md
+++ b/content/docs/authentication/verifying_user_credentials.md
@@ -7,7 +7,7 @@ By default, we provide secure APIs to find users and verify their passwords. How
 In this guide, we will cover the process of finding a user by a UID and verifying their password before marking them as logged in.
 
 ## Basic example
-You can use the User model directly to find a user and verify their password. In the following example, we find a user by email and use the [hash](../security/hash.md) service to verify the password hash.
+You can use the User model directly to find a user and verify their password. In the following example, we find a user by email and use the [hash](../security/hashing) service to verify the password hash.
 
 ```ts
 import { HttpContext } from '@adonisjs/core/http'
@@ -117,7 +117,7 @@ export default class User extends compose(BaseModel, AuthFinder) {
   - `uids`: An array of model properties that can be used to identify a user uniquely. If you assign a user a username or phone number, you can also use them as a UID.
   - `passwordColumnName`: The model property name that holds the user password.
 
-- Finally, you can use the return value of the `withAuthFinder` method as a [mixin](../reference/helpers.md#compose) on the User model.
+- Finally, you can use the return value of the `withAuthFinder` method as a [mixin](../references/helpers.md#compose) on the User model.
 
 ### Verifying credentials
 Once you have applied the Auth finder mixin, you can replace all the code from the `SessionController.store` method with the following code snippet.
@@ -160,7 +160,7 @@ export default class SessionController {
 ```
 
 ### Handling exceptions
-In case of invalid credentials, the `verifyCredentials` method will throw [E_INVALID_CREDENTIALS](../reference/exceptions.md#e_invalid_credentials) exception.
+In case of invalid credentials, the `verifyCredentials` method will throw [E_INVALID_CREDENTIALS](../references/exceptions.md#e_invalid_credentials) exception.
 
 The exception is self-handled and will be converted to a response using the following content negotiation rules.
 
@@ -168,11 +168,11 @@ The exception is self-handled and will be converted to a response using the foll
 
 - HTTP requests with the `Accept=application/vnd.api+json` header will receive an array of error messages formatted per the JSON API spec.
 
-- If you use sessions, the user will be redirected to the form and receive the errors via [session flash messages](../http/session.md#flash-messages).
+- If you use sessions, the user will be redirected to the form and receive the errors via [session flash messages](../basics/session.md#flash-messages).
 
 - All other requests will receive errors back as plain text.
 
-However, if needed, you can handle the exception inside the [global exception handler](../http/exception_handling.md) as follows.
+However, if needed, you can handle the exception inside the [global exception handler](../basics/exception_handling.md) as follows.
 
 ```ts
 // highlight-start
diff --git a/content/docs/http/bodyparser_middleware.md b/content/docs/basics/body_parser.md
similarity index 95%
rename from content/docs/http/bodyparser_middleware.md
rename to content/docs/basics/body_parser.md
index 8184c865..6836d9e2 100644
--- a/content/docs/http/bodyparser_middleware.md
+++ b/content/docs/basics/body_parser.md
@@ -1,11 +1,11 @@
-# BodyParser middleware
+# Body parser middleware
 
 The request data is parsed using the `BodyParser` middleware registered inside the `start/kernel.ts` file.
 
 The configuration for the middleware is stored inside the `config/bodyparser.ts` file. In this file, you may configure parsers for parsing **JSON payloads**, **multipart forms with file uploads**, and **URL-encoded forms**.
 
-See also: [Reading request body](./request.md#request-body)\
-See also: [File uploads](./file_uploads.md)
+See also: [Reading request body](request.md#request-body)\
+See also: [File uploads](file_uploads.md)
 
 ```ts
 import { defineConfig } from '@adonisjs/core/bodyparser'
@@ -208,7 +208,7 @@ The URL-encoded request body is parsed using the [qs package](https://www.npmjs.
 
 The `multipart` parser is used for parsing HTML form requests with file uploads.
 
-See also: [File uploads](./file_uploads.md)
+See also: [File uploads](file_uploads.md)
 
 ```ts
 multipart: {
@@ -236,7 +236,7 @@ Enabling `autoProcess` will move all the user-uploaded files to the `tmp` direct
 
 Later, inside the controllers, you can validate the files and move them to a persistent location or a cloud service.
 
-If you disable the `autoProcess` flag, then you will have to manually process the stream and read files/fields from the request body. See also: [Self-processing multipart stream](./file_uploads.md#self-processing-multipart-stream).
+If you disable the `autoProcess` flag, then you will have to manually process the stream and read files/fields from the request body. See also: [Self-processing multipart stream](file_uploads.md#self-processing-multipart-stream).
 
 You may define an array of routes for which to auto process the files. The values **must be a route pattern** and not the URL.
 
@@ -293,7 +293,7 @@ limit
 
 <dd>
 
-The maximum limit of bytes to allow when processing all files. You can define the individual file size limit using the [request.file](./file_uploads.md) method.
+The maximum limit of bytes to allow when processing all files. You can define the individual file size limit using the [request.file](file_uploads.md) method.
 
 </dd>
 
diff --git a/content/docs/http/controllers.md b/content/docs/basics/controllers.md
similarity index 93%
rename from content/docs/http/controllers.md
rename to content/docs/basics/controllers.md
index c690b044..d6c24336 100644
--- a/content/docs/http/controllers.md
+++ b/content/docs/basics/controllers.md
@@ -4,7 +4,7 @@ HTTP controllers offer an abstraction layer to organize the route handlers insid
 
 The controllers are stored within the `./app/controllers` directory, representing each controller as a plain JavaScript class. You may create a new controller by running the following command.
 
-See also: [Make controller command](../reference/commands.md#makecontroller)
+See also: [Make controller command](../references/commands.md#makecontroller)
 
 ```sh
 node ace make:controller users
@@ -31,7 +31,7 @@ export default class UsersController {
 }
 ```
 
-Finally, let's bind this controller to a route. We will import the controller using the `#controllers` alias. The aliases are defined using [subpath imports feature of Node.js](../guides/folder_structure.md#the-sub-path-imports).
+Finally, let's bind this controller to a route. We will import the controller using the `#controllers` alias. The aliases are defined using [subpath imports feature of Node.js](../getting_started/folder_structure.md#the-sub-path-imports).
 
 ```ts
 // title: start/routes.ts
@@ -44,7 +44,7 @@ router.get('users', [UsersController, 'index'])
 As you might have noticed, we do not create an instance of the controller class and instead pass it directly to the route. Doing so allows AdonisJS to:
 
 - Create a fresh instance of the controller for each request.
-- And also construct the class using the [IoC container](../fundamentals/ioc_container.md), which allows you to leverage automatic dependency injection.
+- And also construct the class using the [IoC container](../concepts/dependency_injection.md), which allows you to leverage automatic dependency injection.
 
 :::caption{for="error"}
 
@@ -127,7 +127,7 @@ Using magic strings is subjective, and you can decide if you want to use them pe
 
 ## Dependency injection
 
-The controller classes are instantiated using the [IoC container](../fundamentals/ioc_container.md); therefore, you can type-hint dependencies inside the controller constructor or a controller method.
+The controller classes are instantiated using the [IoC container](../concepts/dependency_injection.md); therefore, you can type-hint dependencies inside the controller constructor or a controller method.
 
 Given you have a `UserService` class, you can inject an instance of it inside the controller as follows.
 
@@ -157,7 +157,7 @@ export default class UsersController {
 
 ### Method injection
 
-You can inject an instance of `UserService` directly inside the controller method using [method injection](../fundamentals/ioc_container.md#using-method-injection). In this case, you must apply the `@inject` decorator on the method name.
+You can inject an instance of `UserService` directly inside the controller method using [method injection](../concepts/dependency_injection.md#using-method-injection). In this case, you must apply the `@inject` decorator on the method name.
 
 The first parameter passed to the controller method is always the HttpContext. Therefore, you must type-hint the `UserService` as the second parameter.
 
@@ -179,7 +179,7 @@ export default class UsersController {
 
 Automatic resolution of dependencies is not only limited to the controller. Any class injected inside the controller can also type-hint dependencies, and the IoC container will construct the tree of dependencies for you.
 
-For example, let's modify the `UserService` class to accept an instance of the [HttpContext](./http_context.md) as a constructor dependency.
+For example, let's modify the `UserService` class to accept an instance of the [HttpContext](../concepts/http_context.md) as a constructor dependency.
 
 ```ts
 import { inject } from '@adonisjs/core'
@@ -303,7 +303,7 @@ router.shallowResource('posts.comments', CommentsController)
 The routes created using the `router.resource` method are named after the resource name and the controller action. First, we convert the resource name to snake case and concatenate the action name using the dot `.` separator.
 
 | Resource         | Action name | Route name               |
-| ---------------- | ----------- | ------------------------ |
+|------------------|-------------|--------------------------|
 | posts            | index       | `posts.index`            |
 | userPhotos       | index       | `user_photos.index`      |
 | group-attributes | show        | `group_attributes.index` |
@@ -365,7 +365,7 @@ router.resource('posts', PostsController).params({
 The above change will generate the following routes _(showing partial list)_.
 
 | HTTP method | Route               | Controller method |
-| ----------- | ------------------- | ----------------- |
+|-------------|---------------------|-------------------|
 | GET         | `/posts/:post`      | show              |
 | GET         | `/posts/:post/edit` | edit              |
 | PUT         | `/posts/:post`      | update            |
diff --git a/content/docs/http/cookies.md b/content/docs/basics/cookies.md
similarity index 97%
rename from content/docs/http/cookies.md
rename to content/docs/basics/cookies.md
index 3539120a..f6b005f4 100644
--- a/content/docs/http/cookies.md
+++ b/content/docs/basics/cookies.md
@@ -1,6 +1,6 @@
 # Cookies
 
-The request cookies are parsed automatically during an HTTP request. You can read cookies using the [request](./request.md) object and set/clear cookies using the [response](./response.md) object.
+The request cookies are parsed automatically during an HTTP request. You can read cookies using the [request](request.md) object and set/clear cookies using the [response](response.md) object.
 
 ```ts
 // title: Read cookies
diff --git a/content/docs/http/exception_handling.md b/content/docs/basics/exception_handling.md
similarity index 92%
rename from content/docs/http/exception_handling.md
rename to content/docs/basics/exception_handling.md
index 68c2004a..0cc49fd9 100644
--- a/content/docs/http/exception_handling.md
+++ b/content/docs/basics/exception_handling.md
@@ -43,13 +43,15 @@ If you want to handle a specific exception differently, you can do that inside t
 ```ts
 import { errors } from '@vinejs/vine'
 
-async handle(error: unknown, ctx: HttpContext) {
-  if (error instanceof errors.E_VALIDATION_EXCEPTION) {
-    ctx.response.status(422).send(error.messages)
-    return
+export default class HttpExceptionHandler extends ExceptionHandler {
+  async handle(error: unknown, ctx: HttpContext) {
+    if (error instanceof errors.E_VALIDATION_EXCEPTION) {
+      ctx.response.status(422).send(error.messages)
+      return
+    }
+
+    return super.handle(error, ctx)
   }
-  
-  return super.handle(error, ctx)
 }
 ```
 
@@ -90,7 +92,7 @@ export default class HttpExceptionHandler extends ExceptionHandler {
 
 The `report` method on the exceptions handler class handles reporting of exceptions. 
 
-The method receives the error as the first argument and the [HTTP context](./http_context.md) as the second argument. You should not write a response from the `report` method and use the context only to read the request information.
+The method receives the error as the first argument and the [HTTP context](../concepts/http_context.md) as the second argument. You should not write a response from the `report` method and use the context only to read the request information.
 
 ### Logging exceptions
 
@@ -177,7 +179,7 @@ export default class HttpExceptionHandler extends ExceptionHandler {
 
 You can create an exception class using the `make:exception` ace command. An exception extends the `Exception` class from the `@adonisjs/core` package.
 
-See also: [Make exception command](../reference/commands.md#makeexception)
+See also: [Make exception command](../references/commands.md#makeexception)
 
 ```sh
 node ace make:exception UnAuthorized
@@ -258,4 +260,4 @@ try {
 ```
 
 ## Known errors
-Please check the [exceptions reference guide](../reference/exceptions.md) to view the list of known errors.
+Please check the [exceptions reference guide](../references/exceptions.md) to view the list of known errors.
diff --git a/content/docs/http/file_uploads.md b/content/docs/basics/file_uploads.md
similarity index 78%
rename from content/docs/http/file_uploads.md
rename to content/docs/basics/file_uploads.md
index c1074b19..3434f76c 100644
--- a/content/docs/http/file_uploads.md
+++ b/content/docs/basics/file_uploads.md
@@ -1,6 +1,6 @@
 # File uploads
 
-AdonisJS has first-class support for processing user-uploaded files sent using the `multipart/form-data` content type. The files are auto-processed using the [bodyparser middleware](./bodyparser_middleware.md#multipart-parser) and saved inside your operating system's `tmp` directory.
+AdonisJS has first-class support for processing user-uploaded files sent using the `multipart/form-data` content type. The files are auto-processed using the [bodyparser middleware](../basics/body_parser.md#multipart-parser) and saved inside your operating system's `tmp` directory.
 
 Later, inside your controllers, you may access the files, validate them and move them to a persistent location or a cloud storage service like S3.
 
@@ -90,7 +90,7 @@ if (invalidDocuments.length) {
 
 ### Using validator
 
-Instead of validating files manually (as seen in the previous section), you may use the [validator](./validation.md) to validate files as part of the validation pipeline. You do not have to manually check for errors when using the validator; the validation pipeline takes care of that.
+Instead of validating files manually (as seen in the previous section), you may use the [validator](validation.md) to validate files as part of the validation pipeline. You do not have to manually check for errors when using the validator; the validation pipeline takes care of that.
 
 ```ts
 // app/validators/user_validator.ts
@@ -113,7 +113,7 @@ import { HttpContext } from '@adonisjs/core/http'
 import { updateAvatarValidator } from '#validators/user_validator'
 
 export default class UserAvatarsController {
-  update({ request }: HttpContext) {
+  async update({ request }: HttpContext) {
     // highlight-start
     const { avatar } = await request.validateUsing(
       updateAvatarValidator
@@ -184,26 +184,26 @@ await auth.user.save()
 
 Following is the list of properties you may access on the [MultipartFile](https://github.com/adonisjs/bodyparser/blob/main/src/multipart/file.ts) instance.
 
-| Property | Description |
-|---------|------------|
-| `fieldName` | The name of the HTML input field. |
-| `clientName` | The file name on the user's computer. |
-| `size` | The size of the file in bytes.  |
-| `extname` | The file extname |
-| `errors` | An array of errors associated with a given file. |
-| `type` | The [mime type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the file |
-| `subtype` | The [mime subtype](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the file. |
-| `filePath` | The absolute path to the file after the `move` operation. |
-| `fileName` | The file name after the `move` operation. |
-| `tmpPath` | The absolute path to the file inside the `tmp` directory. |
-| `meta` | Metadata associated with the file as a key-value pair. The object is empty by default. |
-| `validated` | A boolean to know if the file has been validated. |
-| `isValid` | A boolean to know if the file has passed the validation rules. |
-| `hasErrors` | A boolean to know if one or more errors are associated with a given file. |
+| Property     | Description                                                                                                  |
+|--------------|--------------------------------------------------------------------------------------------------------------|
+| `fieldName`  | The name of the HTML input field.                                                                            |
+| `clientName` | The file name on the user's computer.                                                                        |
+| `size`       | The size of the file in bytes.                                                                               |
+| `extname`    | The file extname                                                                                             |
+| `errors`     | An array of errors associated with a given file.                                                             |
+| `type`       | The [mime type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the file     |
+| `subtype`    | The [mime subtype](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the file. |
+| `filePath`   | The absolute path to the file after the `move` operation.                                                    |
+| `fileName`   | The file name after the `move` operation.                                                                    |
+| `tmpPath`    | The absolute path to the file inside the `tmp` directory.                                                    |
+| `meta`       | Metadata associated with the file as a key-value pair. The object is empty by default.                       |
+| `validated`  | A boolean to know if the file has been validated.                                                            |
+| `isValid`    | A boolean to know if the file has passed the validation rules.                                               |
+| `hasErrors`  | A boolean to know if one or more errors are associated with a given file.                                    |
 
 ## Serving files
 
-If you have persisted user-uploaded files in the same filesystem as your application code, you may serve files by creating a route and using the [`response.download`](./response.md#downloading-files) method. 
+If you have persisted user-uploaded files in the same filesystem as your application code, you may serve files by creating a route and using the [`response.download`](response.md#downloading-files) method. 
 
 ```ts
 import { sep, normalize } from 'node:path'
@@ -225,7 +225,7 @@ router.get('/uploads/*', ({ request, response }) => {
 })
 ```
 
-- We get the file path using the [wildcard route param](./routing.md#wildcard-params) and convert the array into a string.
+- We get the file path using the [wildcard route param](routing.md#wildcard-params) and convert the array into a string.
 - Next, we normalize the path using the Node.js path module.
 - Using the `PATH_TRAVERSAL_REGEX` we protect this route against [path traversal](https://owasp.org/www-community/attacks/Path_Traversal).
 - Finally, we convert the `normalizedPath` to an absolute path inside the `uploads` directory and serve the file using the `response.download` method.
diff --git a/content/docs/http/middleware.md b/content/docs/basics/middleware.md
similarity index 97%
rename from content/docs/http/middleware.md
rename to content/docs/basics/middleware.md
index 3673c5ad..292e0d98 100644
--- a/content/docs/http/middleware.md
+++ b/content/docs/basics/middleware.md
@@ -66,7 +66,7 @@ router.named({
 
 Middleware are stored inside the `./app/middleware` directory, and you can create a new middleware file by running the `make:middleware` ace command.
 
-See also: [Make middleware command](../reference/commands.md#makemiddleware)
+See also: [Make middleware command](../references/commands.md#makemiddleware)
 
 ```sh
 node ace make:middleware user_location
@@ -74,7 +74,7 @@ node ace make:middleware user_location
 
 The above command will create the `user_location_middleware.ts` file under the middleware directory. 
 
-A middleware is represented as a class with the `handle` method. During execution, AdonisJS will automatically call this method and give it the [HttpContext](./http_context.md) as the first argument.
+A middleware is represented as a class with the `handle` method. During execution, AdonisJS will automatically call this method and give it the [HttpContext](../concepts/http_context.md) as the first argument.
 
 ```ts
 // title: app/middleware/user_location_middleware.ts
@@ -200,7 +200,7 @@ router.get('payments', () => {}).use(
 
 ## Dependency injection 
 
-Middleware classes are instantiated using the [IoC container](../fundamentals/ioc_container.md); therefore, you can type-hint dependencies inside the middleware constructor, and the container will inject them for you.
+Middleware classes are instantiated using the [IoC container](../concepts/dependency_injection.md); therefore, you can type-hint dependencies inside the middleware constructor, and the container will inject them for you.
 
 Given you have a `GeoIpService` class to look up user location from the request IP, you can inject it into the middleware using the `@inject` decorator.
 
@@ -243,7 +243,7 @@ The middleware layer of AdonisJS is built on top of [Chain of Responsibility](ht
 
 ## Middleware and exception handling
 
-AdonisJS automatically captures the exception raised by the middleware pipeline or the route handler and converts it into an HTTP response using the [global exception handler](./exception_handling.md).
+AdonisJS automatically captures the exception raised by the middleware pipeline or the route handler and converts it into an HTTP response using the [global exception handler](exception_handling.md).
 
 As a result, you do not have to wrap the `next` function calls inside a `try/catch` statement. Also, the automatic exception handling ensures that the upstream logic of middleware is always executed after the `next` function call.
 
diff --git a/content/docs/http/middleware_flow 2.jpeg b/content/docs/basics/middleware_flow 2.jpeg
similarity index 100%
rename from content/docs/http/middleware_flow 2.jpeg
rename to content/docs/basics/middleware_flow 2.jpeg
diff --git a/content/docs/http/middleware_flow.jpeg b/content/docs/basics/middleware_flow.jpeg
similarity index 100%
rename from content/docs/http/middleware_flow.jpeg
rename to content/docs/basics/middleware_flow.jpeg
diff --git a/content/docs/http/post_comments_resource_routes_list.png b/content/docs/basics/post_comments_resource_routes_list.png
similarity index 100%
rename from content/docs/http/post_comments_resource_routes_list.png
rename to content/docs/basics/post_comments_resource_routes_list.png
diff --git a/content/docs/http/post_comments_resource_routes_list_original.png b/content/docs/basics/post_comments_resource_routes_list_original.png
similarity index 100%
rename from content/docs/http/post_comments_resource_routes_list_original.png
rename to content/docs/basics/post_comments_resource_routes_list_original.png
diff --git a/content/docs/http/post_resource_routes_list.png b/content/docs/basics/post_resource_routes_list.png
similarity index 100%
rename from content/docs/http/post_resource_routes_list.png
rename to content/docs/basics/post_resource_routes_list.png
diff --git a/content/docs/http/post_resource_routes_list_original.png b/content/docs/basics/post_resource_routes_list_original.png
similarity index 100%
rename from content/docs/http/post_resource_routes_list_original.png
rename to content/docs/basics/post_resource_routes_list_original.png
diff --git a/content/docs/http/request.md b/content/docs/basics/request.md
similarity index 96%
rename from content/docs/http/request.md
rename to content/docs/basics/request.md
index d09066d1..9173ff0c 100644
--- a/content/docs/http/request.md
+++ b/content/docs/basics/request.md
@@ -18,7 +18,7 @@ router.get('posts', async ({ request }) => {
 })
 ```
 
-The `request.params` method returns an object of [Route params](./routing.md#route-params).
+The `request.params` method returns an object of [Route params](routing.md#route-params).
 
 ```ts
 import router from '@adonisjs/core/services/router'
@@ -45,7 +45,7 @@ router.get('posts/:slug/comments/:id', async ({ request }) => {
 
 ## Request body
 
-AdonisJS parses the request body using the [bodyparser middleware](./bodyparser_middleware.md) registered inside the `start/kernel.ts` file.
+AdonisJS parses the request body using the [body-parser middleware](../basics/body_parser.md) registered inside the `start/kernel.ts` file.
 
 You can access the request body using the `request.body()` method. It returns the parsed request body as an object.
 
@@ -110,7 +110,7 @@ router.post('comments', async ({ request }) => {
 
 The `request.all`, `request.body`, or the cherry-picking methods are not type-safe because there is no direct way for AdonisJS to know the expected data types of the request body.
 
-However, you may use the [validator](./validation.md) to validate the request body and have static type-safety.
+However, you may use the [validator](validation.md) to validate the request body and have static type-safety.
 
 ## Request URL
 
@@ -254,7 +254,7 @@ router.get('/', async ({ request }) => {
 Following is the complete list of content negotiation methods.
 
 | Method    | HTTP header in use                                                                           |
-| --------- | -------------------------------------------------------------------------------------------- |
+|-----------|----------------------------------------------------------------------------------------------|
 | types     | [Accept](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept)                   |
 | languages | [Accept-language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) |
 | encodings | [Accept-encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) |
@@ -435,7 +435,7 @@ Once enabled, you can spoof the form method as follows.
 
 ## Extending Request class
 
-You can add custom properties to the Request class using macros or getters. Make sure to read the [extending AdonisJS guide](../fundamentals/extending_the_framework.md) first if you are new to the concept of macros.
+You can add custom properties to the Request class using macros or getters. Make sure to read the [extending AdonisJS guide](../concepts/extending_the_framework.md) first if you are new to the concept of macros.
 
 ```ts
 import { Request } from '@adonisjs/core/http'
diff --git a/content/docs/http/response.md b/content/docs/basics/response.md
similarity index 96%
rename from content/docs/http/response.md
rename to content/docs/basics/response.md
index c326df01..e1307d80 100644
--- a/content/docs/http/response.md
+++ b/content/docs/basics/response.md
@@ -205,7 +205,7 @@ router.get('/posts', async ({ response }) => {
 })
 ```
 
-The redirect class also allows constructing a URL from a pre-registered route. The `redirect.toRoute` method accepts the [route identifier](./routing.md#route-identifier) as the first parameter and the route params as the second parameter.
+The redirect class also allows constructing a URL from a pre-registered route. The `redirect.toRoute` method accepts the [route identifier](routing.md#route-identifier) as the first parameter and the route params as the second parameter.
 
 ```ts
 import router from '@adonisjs/core/services/router'
@@ -257,10 +257,10 @@ response.redirect().withQs().back()
 
 ## Aborting request with an error
 
-You may use the `response.abort` method to end the request by raising an exception. The method will throw an `E_HTTP_REQUEST_ABORTED` exception and trigger the [exception handling](./exception_handling.md) flow.
+You may use the `response.abort` method to end the request by raising an exception. The method will throw an `E_HTTP_REQUEST_ABORTED` exception and trigger the [exception handling](exception_handling.md) flow.
 
 ```ts
-router.get('posts/:id/edit', ({ response, auth, params }) => {
+router.get('posts/:id/edit', async ({ response, auth, params }) => {
   const post = await Post.findByOrFail(params.id)
 
   if (!auth.user.can('editPost', post)) {
@@ -324,7 +324,7 @@ Following is the list of rules we follow to set the `content-type` header.
 
 ## Extending Response class
 
-You can add custom properties to the Response class using macros or getters. Make sure to read the [extending AdonisJS guide](../fundamentals/extending_the_framework.md) first if you are new to the concept of macros.
+You can add custom properties to the Response class using macros or getters. Make sure to read the [extending AdonisJS guide](../concepts/extending_the_framework.md) first if you are new to the concept of macros.
 
 ```ts
 import { Response } from '@adonisjs/core/http'
diff --git a/content/docs/http/routing.md b/content/docs/basics/routing.md
similarity index 75%
rename from content/docs/http/routing.md
rename to content/docs/basics/routing.md
index e0464331..347a5081 100644
--- a/content/docs/http/routing.md
+++ b/content/docs/basics/routing.md
@@ -47,11 +47,11 @@ router.get('/posts/:id', ({ params }) => {
 })
 ```
 
-| URL               | Id        |
-| ----------------- | --------- |
-| `‌/posts/1`       | `1`       |
-| `‌/posts/100`     | `100`     |
-| `‌/posts/foo-bar` | `foo-bar` |
+| URL              | Id        |
+|------------------|-----------|
+| `/posts/1`       | `1`       |
+| `/posts/100`     | `100`     |
+| `/posts/foo-bar` | `foo-bar` |
 
 A URI can also accept multiple params. Each param should have a unique name.
 
@@ -64,10 +64,10 @@ router.get('/posts/:id/comments/:commentId', ({ params }) => {
 })
 ```
 
-| URL                           | Id        | Comment Id |
-| ----------------------------- | --------- | ---------- |
-| `‌/posts/1/comments/4`        | `1`       | `4`        |
-| `‌/posts/foo-bar/comments/22` | `foo-bar` | `22`       |
+| URL                          | Id        | Comment Id |
+|------------------------------|-----------|------------|
+| `/posts/1/comments/4`        | `1`       | `4`        |
+| `/posts/foo-bar/comments/22` | `foo-bar` | `22`       |
 
 ### Optional params
 
@@ -99,7 +99,7 @@ router.get('/docs/:category/*', ({ params }) => {
 ```
 
 | URL                  | Category | Wildcard param   |
-| -------------------- | -------- | ---------------- |
+|----------------------|----------|------------------|
 | `/docs/http/context` | `http`   | `['context']`    |
 | `/docs/api/sql/orm`  | `api`    | `['sql', 'orm']` |
 
@@ -215,7 +215,7 @@ router.post('users', async () => {
 
 In the following example, we import the `UsersController` class and bind it to the route. During an HTTP request, AdonisJS will create an instance of the controller class using the IoC container and execute the `store` method.
 
-See also: Dedicated guide on [controllers](./controllers.md).
+See also: Dedicated guide on [controllers](controllers.md).
 
 
 ```ts
@@ -228,7 +228,7 @@ router.post('users', [UsersController, 'store'])
 
 You can define a middleware on a route by calling the `route.use` method. The method accepts an inline callback or a reference to a named middleware.
 
-Following is a minimal example of defining a route middleware. We recommend reading the [dedicated guide on middleware](./middleware.md) to explore all the available options and the execution flow of middleware.
+Following is a minimal example of defining a route middleware. We recommend reading the [dedicated guide on middleware](middleware.md) to explore all the available options and the execution flow of middleware.
 
 ```ts
 router
@@ -245,7 +245,7 @@ router
 
 ## Route identifier
 
-Every route has a unique identifier you can use to reference the route elsewhere in your application. For example, you can generate a URL to a route using the [URL builder](./url_builder.md) or redirect to a route using the [response.redirect](./response.md#redirects) method.
+Every route has a unique identifier you can use to reference the route elsewhere in your application. For example, you can generate a URL to a route using the [URL builder](#url-builder) or redirect to a route using the [response.redirect](response.md#redirects) method.
 
 By default, the route pattern is the route identifier. However, you can assign a unique, memorable name to the route using the `route.as` method.
 
@@ -375,7 +375,7 @@ You can assign middleware to routes inside a group using the `group.use` method.
 
 In the case of nested groups, the middleware from the outermost group will run first. In other words, a group prepends middleware to the route middleware stack.
 
-See also: [Middleware guide](./middleware.md)
+See also: [Middleware guide](middleware.md)
 
 ```ts
 router
@@ -440,7 +440,7 @@ The render method accepts the name of the edge template to render. Optionally, y
 
 :::warning
 
-The `route.on.render` method only exists when you have configured the [Edge service provider](./views_and_templates.md#using-edge)
+The `route.on.render` method only exists when you have configured the [Edge service provider](../views-and-templates/introduction#using-edge)
 
 :::
 
@@ -508,7 +508,7 @@ router.on('/posts').redirect('/articles', {
 
 ## Current request route
 
-The route of the current request can be accessed using the [`HttpContext.route`](./http_context.md#http-context-properties) property. It includes the **route pattern**, **name**, **reference to its middleware store**, and **reference to the route handler**.
+The route of the current request can be accessed using the [`HttpContext.route`](../concepts/http_context.md#http-context-properties) property. It includes the **route pattern**, **name**, **reference to its middleware store**, and **reference to the route handler**.
 
 ```ts
 router.get('payments', ({ route }) => {
@@ -569,7 +569,7 @@ router.get('posts/:id', () => {})
 
 AdonisJS raises a 404 exception when no matching route is found for the current request's URL.
 
-To display a 404 page to the user, you can catch the `E_ROUTE_NOT_FOUND` exception inside the [global exception handler](./exception_handling.md) and render a template.
+To display a 404 page to the user, you can catch the `E_ROUTE_NOT_FOUND` exception inside the [global exception handler](exception_handling.md) and render a template.
 
 ```ts
 import { errors } from '@adonisjs/core'
@@ -586,9 +586,196 @@ export default class HttpExceptionHandler extends ExceptionHandler {
 }
 ```
 
+## URL builder
+
+You may use the URL builder to create URLs for pre-defined routes in your application. For example, create a form action URL inside Edge templates, or make the URL to redirect the request to another route.
+
+The `router.builder` method creates an instance of the [URL builder](https://github.com/adonisjs/http-server/blob/main/src/router/lookup_store/url_builder.ts) class, and you can use the builder's fluent API to lookup a route and create a URL for it.
+
+```ts
+import router from '@adonisjs/core/services/router'
+const PostsController = () => import('#controllers/posts_controller')
+
+router
+  .get('posts/:id', [PostsController, 'show'])
+  .as('posts.show')
+```
+
+You may generate the URL for the `posts.show` route as follows.
+
+```ts
+import router from '@adonisjs/core/services/router'
+
+router
+  .builder()
+  .params([1])
+  .make('posts.show') // /posts/1
+
+router
+ .builder()
+ .params([20])
+ .make('posts.show') // /posts/20
+```
+
+The params can be specified as an array of positional arguments. Or you can define them as a key-value pair.
+
+```ts
+router
+ .builder()
+ .params({ id: 1 })
+ .make('posts.show') // /posts/1
+```
+
+### Defining query parameters
+
+The query parameters can be defined using the `builder.qs` method. The method accepts an object of key-value pair and serializes it to a query string.
+
+```ts
+router
+  .builder()
+  .qs({ page: 1, sort: 'asc' })
+  .make('posts.index') // /posts?page=1&sort=asc
+```
+
+The query string is serialized using the [qs](https://www.npmjs.com/package/qs) npm package. You can [configure its settings](https://github.com/adonisjs/http-server/blob/main/src/define_config.ts#L49-L54) inside the `config/app.ts` file under the `http` object.
+
+```ts
+// config/app.js
+http: defineConfig({
+  qs: {
+    stringify: {
+      // 
+    }
+  }
+})
+```
+
+### Prefixing URL
+
+You may prefix a base URL to the output using the `builder.prefixUrl` method.
+
+```ts
+router
+  .builder()
+  .prefixUrl('https://blog.adonisjs.com')
+  .params({ id: 1 })
+  .make('posts.show')
+```
+
+### Generating signed URLs
+
+Signed URLs are URLs with a signature query string appended to them. The signature is used to verify if the URL has been tampered after it was generated.
+
+For example, you have a URL to unsubscribe users from your newsletter. The URL contains the `userId` and might look as follows.
+
+```
+/unsubscribe/231
+```
+
+To prevent someone from changing the user id from `231` to something else, you can sign this URL and verify the signature when handling requests for this route.
+
+```ts
+router.get('unsubscribe/:id', ({ request, response }) => {
+  if (!request.hasValidSignature()) {
+    return response.badRequest('Invalid or expired URL')
+  }
+  
+  // Remove subscription
+}).as('unsubscribe')
+```
+
+You may use the `makeSigned` method to create a signed URL.
+
+```ts
+router
+  .builder()
+  .prefixUrl('https://blog.adonisjs.com')
+  .params({ id: 231 })
+  // highlight-start
+  .makeSigned('unsubscribe')
+  // highlight-end
+```
+
+#### Signed URL expiration
+
+You may generate signed URLs that expire after a given duration using the `expiresIn` option. The value can be a number in milliseconds or a time expression string.
+
+```ts
+router
+  .builder()
+  .prefixUrl('https://blog.adonisjs.com')
+  .params({ id: 231 })
+  // highlight-start
+  .makeSigned('unsubscribe', {
+    expiresIn: '3 days'
+  })
+  // highlight-end
+```
+
+### Disabling route lookup
+
+The URL builder performs a route lookup with the route identifier given to the `make` and the `makeSigned` methods.
+
+If you want to create a URL for routes defined outside of your AdonisJS application, you may disable the route lookup and give the route pattern to the `make` and the `makeSigned` methods.
+
+```ts
+router
+  .builder()
+  .prefixUrl('https://your-app.com')
+  .disableRouteLookup()
+  .params({ token: 'foobar' })
+  .make('/email/verify/:token') // /email/verify/foobar
+```
+
+### Making URL for routes under a domain
+You can make URLs for routes registered under a specific domain using the `router.builderForDomain` method. The method accepts the route pattern you used at the time of defining the routes.
+
+```ts
+import router from '@adonisjs/core/services/router'
+const PostsController = () => import('#controllers/posts_controller')
+
+router.group(() => {
+  router
+    .get('/posts/:id', [PostsController, 'show'])
+    .as('posts.show')
+}).domain('blog.adonisjs.com')
+```
+
+You can create URL for the `posts.show` route under `blog.adonisjs.com` domain as follows.
+
+```ts
+router
+  .builderForDomain('blog.adonisjs.com')
+  .params({ id: 1 })
+  .make('posts.show')
+```
+
+### Generating URLs inside templates
+
+You may use the `route` and the `signedRoute` methods inside templates to generate a URL using the URL builder.
+
+See also: [Edge helpers reference](../references/edge.md#routesignedroute)
+
+```edge
+<a href="{{ route('posts.show', [post.id]) }}">
+  View post
+</a>
+```
+
+```edge
+<a href="{{
+  signedRoute('unsubscribe', [user.id], {
+    expiresIn: '3 days',
+    prefixUrl: 'https://blog.adonisjs.com'    
+  })
+}}">
+  Unsubscribe
+</a>
+```
+
 ## Extending router
 
-You can add custom properties to different router classes using macros and getters. Make sure to read the [extending AdonisJS guide](../fundamentals/extending_the_framework.md) first if you are new to the concept of macros.
+You can add custom properties to different router classes using macros and getters. Make sure to read the [extending AdonisJS guide](../concepts/extending_the_framework.md) first if you are new to the concept of macros.
 
 Following is the list of classes you can extend.
 
diff --git a/content/docs/http/session.md b/content/docs/basics/session.md
similarity index 94%
rename from content/docs/http/session.md
rename to content/docs/basics/session.md
index 2814bbab..c38a2c06 100644
--- a/content/docs/http/session.md
+++ b/content/docs/basics/session.md
@@ -144,7 +144,7 @@ The `age` property controls the validity of session data without any user activi
 
 <dd>
 
-Control session ID cookie attributes. See also [cookie configuration](./cookies.md#configuration).
+Control session ID cookie attributes. See also [cookie configuration](cookies.md#configuration).
 
 </dd>
 
@@ -280,7 +280,7 @@ export default defineConfig({
 ```
 
 ## Basic example
-Once the session package has been registered, you can access the `session` property from the [HTTP Context](./http_context.md). The session property exposes the API for reading and writing data to the session store.
+Once the session package has been registered, you can access the `session` property from the [HTTP Context](../concepts/http_context.md). The session property exposes the API for reading and writing data to the session store.
 
 ```ts
 import router from '@adonisjs/core/services/router'
@@ -500,12 +500,12 @@ router.get('/contact', ({ view, session }) => {
 ```
 
 ### Validation errors and flash messages
-The Session middleware automatically captures the [validation exceptions](./validation.md#error-handling) and redirects the user back to the form. The validation errors and form input data are kept within flash messages, and you can access them inside Edge templates.
+The Session middleware automatically captures the [validation exceptions](validation.md#error-handling) and redirects the user back to the form. The validation errors and form input data are kept within flash messages, and you can access them inside Edge templates.
 
 In the following example:
 
-- We access the value of the `title` input field using the [`old` method](../reference/edge.md#old).
-- And access the error message using the [`@inputError` tag](../reference/edge.md#inputerror).
+- We access the value of the `title` input field using the [`old` method](../references/edge.md#old).
+- And access the error message using the [`@inputError` tag](../references/edge.md#inputerror).
 
 ```edge
 <form method="POST" action="/posts">
@@ -600,7 +600,7 @@ console.log(session.flashMessages.has('key'))
 
 The same `flashMessages` property is also shared with Edge templates, and you can access it as follows.
 
-See also: [Edge helpers reference](../reference/edge.md#flashmessages)
+See also: [Edge helpers reference](../references/edge.md#flashmessages)
 
 ```edge
 {{ flashMessages.all() }}
@@ -628,7 +628,7 @@ Finally, you can access a specific flash message or a validation error using the
 ```
 
 ## Events
-Please check the [events reference guide](../reference/events.md#sessioninitiated) to view the list of events dispatched by the `@adonisjs/session` package.
+Please check the [events reference guide](../references/events.md#sessioninitiated) to view the list of events dispatched by the `@adonisjs/session` package.
 
 ## Creating a custom session store
 Session stores must implement the [SessionStoreContract](https://github.com/adonisjs/session/blob/main/src/types.ts#L23C18-L23C38) interface and define the following methods.
@@ -717,4 +717,4 @@ export default defineConfig({
 
 ### A note on serializing data
 
-The `write` method receives the session data as an object, and you might have to convert it to a string before saving it. You can use any serialization package for the same or the [MessageBuilder](../reference/helpers.md#message-builder) helper provided by the AdonisJS helpers module. For inspiration, please consult the official [session stores](https://github.com/adonisjs/session/blob/main/src/stores/redis.ts#L59).
+The `write` method receives the session data as an object, and you might have to convert it to a string before saving it. You can use any serialization package for the same or the [MessageBuilder](../references/helpers.md#message-builder) helper provided by the AdonisJS helpers module. For inspiration, please consult the official [session stores](https://github.com/adonisjs/session/blob/main/src/stores/redis.ts#L59).
diff --git a/content/docs/http/shallow_routes_list.png b/content/docs/basics/shallow_routes_list.png
similarity index 100%
rename from content/docs/http/shallow_routes_list.png
rename to content/docs/basics/shallow_routes_list.png
diff --git a/content/docs/http/shallow_routes_list_original.jpg b/content/docs/basics/shallow_routes_list_original.jpg
similarity index 100%
rename from content/docs/http/shallow_routes_list_original.jpg
rename to content/docs/basics/shallow_routes_list_original.jpg
diff --git a/content/docs/http/static_file_server.md b/content/docs/basics/static_file_server.md
similarity index 96%
rename from content/docs/http/static_file_server.md
rename to content/docs/basics/static_file_server.md
index 70e9810f..ecd94f5a 100644
--- a/content/docs/http/static_file_server.md
+++ b/content/docs/basics/static_file_server.md
@@ -1,6 +1,6 @@
 # Static files server
 
-You can serve static files from a given directory using the `@adonisjs/static` package. The package ships with a middleware that you must register in the [server middleware stack](./middleware.md#server-middleware-stack) to intercept the HTTP requests and serve files.
+You can serve static files from a given directory using the `@adonisjs/static` package. The package ships with a middleware that you must register in the [server middleware stack](middleware.md#server-middleware-stack) to intercept the HTTP requests and serve files.
 
 ## Installation
 
@@ -236,7 +236,7 @@ A function that returns an object of headers to set on the response. The functio
 
 Once the middleware is registered, you may create files inside the `public` directory and access them in the browser using the file path. For example, the `./public/css/style.css` file can be accessed using the `http://localhost:3333/css/style.css` URL.
 
-The files in the `public` directory are not compiled or built using an assets bundler. If you want to compile frontend assets, you must place them inside the `resources` directory and use the [assets bundler](./assets_bundling.md).
+The files in the `public` directory are not compiled or built using an assets bundler. If you want to compile frontend assets, you must place them inside the `resources` directory and use the [assets bundler](../basics/vite.md).
 
 ## Copying static files to production build
 The static files stored inside the `/public` directory are automatically copied to the `build` folder when you run `node ace build` command.
diff --git a/content/docs/http/validation.md b/content/docs/basics/validation.md
similarity index 94%
rename from content/docs/http/validation.md
rename to content/docs/basics/validation.md
index 7df0ddd4..2709d2bb 100644
--- a/content/docs/http/validation.md
+++ b/content/docs/basics/validation.md
@@ -78,7 +78,7 @@ export default class PostsController {
 
 Once you have created the `PostsController` and defined the routes, you may use the following ace command to create a validator.
 
-See also: [Make validator command](../reference/commands.md#makevalidator)
+See also: [Make validator command](../references/commands.md#makevalidator)
 
 ```sh
 node ace make:validator post
@@ -156,7 +156,7 @@ That is all! Validating the user input is two lines of code inside your controll
 Also, you do not have to wrap the `validate` method call inside a `try/catch`. Because in the case of an error, AdonisJS will automatically convert the error to an HTTP response.
 
 ## Error handling
-The [HttpExceptionHandler](./exception_handling.md) will convert the validation errors to an HTTP response automatically. The exception handler uses content negotiation and returns a response based upon the [Accept](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept) header value.
+The [HttpExceptionHandler](exception_handling.md) will convert the validation errors to an HTTP response automatically. The exception handler uses content negotiation and returns a response based upon the [Accept](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept) header value.
 
 :::tip
 
@@ -170,7 +170,7 @@ Also, the session middleware [overwrites the `renderValidationErrorAsHTML` metho
 
 - HTTP requests with `Accept=application/vnd.api+json` header will receive an array of error messages formatted as per the [JSON API](https://jsonapi.org/format/#errors) spec.
 
-- Server rendered forms using the [session package](./session.md) will receive the errors via [session flash messages](./session.md#validation-errors-and-flash-messages).
+- Server rendered forms using the [session package](session.md) will receive the errors via [session flash messages](session.md#validation-errors-and-flash-messages).
 
 - All other requests will receive errors back as plain text.
 
@@ -307,7 +307,7 @@ vine.withMetaData<{ userId: number }>((meta) => {
 ```
 
 ## Configuring VineJS
-You may create a [preload file](../fundamentals/adonisrc_file.md#preloads) inside the `start` directory to configure VineJS with custom error messages or use a custom error reporter.
+You may create a [preload file](../concepts/adonisrc_file#preloads) inside the `start` directory to configure VineJS with custom error messages or use a custom error reporter.
 
 ```sh
 node ace make:preload validator
diff --git a/content/docs/http/vite-dev-server-original.png b/content/docs/basics/vite-dev-server-original.png
similarity index 100%
rename from content/docs/http/vite-dev-server-original.png
rename to content/docs/basics/vite-dev-server-original.png
diff --git a/content/docs/http/vite-dev-server.png b/content/docs/basics/vite-dev-server.png
similarity index 100%
rename from content/docs/http/vite-dev-server.png
rename to content/docs/basics/vite-dev-server.png
diff --git a/content/docs/http/assets_bundling.md b/content/docs/basics/vite.md
similarity index 98%
rename from content/docs/http/assets_bundling.md
rename to content/docs/basics/vite.md
index 765584af..b1a0430f 100644
--- a/content/docs/http/assets_bundling.md
+++ b/content/docs/basics/vite.md
@@ -1,4 +1,4 @@
-# Assets bundling
+# Vite
 
 AdonisJS uses [Vite](https://vitejs.dev/) to bundle the frontend assets of your applications. We provide an official integration that performs all the heavy lifting required to integrate Vite with a backend framework like AdonisJS. It includes:
 
@@ -7,7 +7,7 @@ AdonisJS uses [Vite](https://vitejs.dev/) to bundle the frontend assets of your
 - Edge helpers and tags to generate URLs for assets processed by Vite.
 
 ## Installation
-Vite comes pre-configured with the [web starter kit](../guides/installation.md#web-starter-kit-spannot-ready-yetclassbadge). However, you can follow the below instructions to configure it inside an existing AdonisJS project.
+Vite comes pre-configured with the [web starter kit](../getting_started/installation.md#web-starter-kit). However, you can follow the below instructions to configure it inside an existing AdonisJS project.
 
 Install and configure the package using the following command :
 
diff --git a/content/docs/http/vscode_routes_list.png b/content/docs/basics/vscode_routes_list.png
similarity index 100%
rename from content/docs/http/vscode_routes_list.png
rename to content/docs/basics/vscode_routes_list.png
diff --git a/content/docs/http/vscode_routes_list_original.png b/content/docs/basics/vscode_routes_list_original.png
similarity index 100%
rename from content/docs/http/vscode_routes_list_original.png
rename to content/docs/basics/vscode_routes_list_original.png
diff --git a/content/docs/fundamentals/adonisrc_file.md b/content/docs/concepts/adonisrc_file.md
similarity index 99%
rename from content/docs/fundamentals/adonisrc_file.md
rename to content/docs/concepts/adonisrc_file.md
index a14f3b2c..1253f0d8 100644
--- a/content/docs/fundamentals/adonisrc_file.md
+++ b/content/docs/concepts/adonisrc_file.md
@@ -209,7 +209,7 @@ By default, the providers are loaded in all the environments. However, you can a
 Providers are loaded in the same order as registered inside the `providers` array.
 :::
 
-See also: [Service providers](../fundamentals/service_providers.md)
+See also: [Service providers](service_providers.md)
 
 ```ts
 {
diff --git a/content/docs/fundamentals/application.md b/content/docs/concepts/application.md
similarity index 96%
rename from content/docs/fundamentals/application.md
rename to content/docs/concepts/application.md
index c76bf4f7..45c07696 100644
--- a/content/docs/fundamentals/application.md
+++ b/content/docs/concepts/application.md
@@ -2,7 +2,7 @@
 
 The [Application](https://github.com/adonisjs/application/blob/main/src/application.ts) class does all the heavy lifting of wiring together an AdonisJS application. You can use this class to know about the environment in which your app is running, get the current state of the application, or make paths to specific directories.
 
-See also: [Application lifecycle](./application_lifecycle.md)
+See also: [Application lifecycle](application_lifecycle.md)
 
 ## Environment 
 
@@ -45,12 +45,12 @@ console.log(app.nodeEnvironment)
 ```
 
 | NODE_ENV | Normalized to |
-|------------|----------------|
-| dev | development |
-| develop | development |
-| stage | staging |
-| prod | production |
-| testing | test |
+|----------|---------------|
+| dev      | development   |
+| develop  | development   |
+| stage    | staging       |
+| prod     | production    |
+| testing  | test          |
 
 Also, you can use the following properties as a shorthand to know the current environment.
 
@@ -76,7 +76,7 @@ app.nodeEnvironment === 'test'
 
 ## State
 
-The state refers to the current state of the application. The framework features you can access significantly depend upon the current state of the application. For example, you cannot access the [container bindings](./ioc_container.md#container-bindings) or [container services](./container_services.md) until the app is in a `booted` state.
+The state refers to the current state of the application. The framework features you can access significantly depend upon the current state of the application. For example, you cannot access the [container bindings](dependency_injection#container-bindings) or [container services](container_services.md) until the app is in a `booted` state.
 
 The application is always in one of the following known states.
 
diff --git a/content/docs/fundamentals/application_lifecycle.md b/content/docs/concepts/application_lifecycle.md
similarity index 99%
rename from content/docs/fundamentals/application_lifecycle.md
rename to content/docs/concepts/application_lifecycle.md
index c7868f00..fbba8799 100644
--- a/content/docs/fundamentals/application_lifecycle.md
+++ b/content/docs/concepts/application_lifecycle.md
@@ -1,4 +1,4 @@
-# Application Lifecycle
+# Application lifecycle
 
 In this guide, we will learn how AdonisJS boots your application and what lifecycle hooks you can use to change the application state before it is considered ready.
 
diff --git a/content/docs/fundamentals/async_local_storage.md b/content/docs/concepts/async_local_storage.md
similarity index 97%
rename from content/docs/fundamentals/async_local_storage.md
rename to content/docs/concepts/async_local_storage.md
index 2d6811a6..80e410d7 100644
--- a/content/docs/fundamentals/async_local_storage.md
+++ b/content/docs/concepts/async_local_storage.md
@@ -1,4 +1,4 @@
-# Async Local Storage
+# Async local storage
 
 As per the [Node.js official documentation](https://nodejs.org/docs/latest-v21.x/api/async_context.html#class-asynclocalstorage): “AsyncLocalStorage is used to create asynchronous state within callbacks and promise chains. **It allows storing data throughout the lifetime of a web request or any other asynchronous duration. It is similar to thread-local storage in other languages**.”
 
@@ -106,7 +106,7 @@ Passing data by reference has no technical downsides. But, it does make the code
 
 ## Usage
 
-AdonisJS uses `AsyncLocalStorage` during HTTP requests and shares the [HTTP context](../http/http_context.md) as the state. As a result, you can access the HTTP context in your application globally.
+AdonisJS uses `AsyncLocalStorage` during HTTP requests and shares the [HTTP context](http_context.md) as the state. As a result, you can access the HTTP context in your application globally.
 
 First, you must enable the `useAsyncLocalStorage` flag inside the `config/app.ts` file.
 
diff --git a/content/docs/fundamentals/boot_phase_flow_chart.png b/content/docs/concepts/boot_phase_flow_chart.png
similarity index 100%
rename from content/docs/fundamentals/boot_phase_flow_chart.png
rename to content/docs/concepts/boot_phase_flow_chart.png
diff --git a/content/docs/fundamentals/boot_phase_flow_chart_original.png b/content/docs/concepts/boot_phase_flow_chart_original.png
similarity index 100%
rename from content/docs/fundamentals/boot_phase_flow_chart_original.png
rename to content/docs/concepts/boot_phase_flow_chart_original.png
diff --git a/content/docs/fundamentals/config_providers.md b/content/docs/concepts/config_providers.md
similarity index 93%
rename from content/docs/fundamentals/config_providers.md
rename to content/docs/concepts/config_providers.md
index bd1f45ef..616e7d4d 100644
--- a/content/docs/fundamentals/config_providers.md
+++ b/content/docs/concepts/config_providers.md
@@ -47,7 +47,7 @@ export default {
 }
 ```
 
-**🚨 The above example will fail** because the AdonisJS [container services](./container_services.md) are unavailable until the application has been booted and the config files are imported before the application boot phase.
+**🚨 The above example will fail** because the AdonisJS [container services](container_services.md) are unavailable until the application has been booted and the config files are imported before the application boot phase.
 
 ### Well, that's a problem with AdonisJS architecture 🤷🏻‍♂️
 Not really. Let's not use the container service and create an instance of the Emitter class directly within the config file.
@@ -119,7 +119,7 @@ The above code will work fine. However, you are manually constructing the depend
 With AdonisJS, we strive to write minimal boilerplate code and use the IoC container for lookup dependencies.
 
 ## With config provider
-Now, let's re-write the `config/hash.ts` file and use a config provider this time. Config provider is a fancy name for a function that accepts an [instance of the Application class](./application.md) and resolves its dependencies using the container.
+Now, let's re-write the `config/hash.ts` file and use a config provider this time. Config provider is a fancy name for a function that accepts an [instance of the Application class](application.md) and resolves its dependencies using the container.
 
 ```ts
 // highlight-start
@@ -146,7 +146,7 @@ export default {
 }
 ```
 
-Once you use the [hash](../security/hash.md) service, the config provider for the `scrypt` driver will be executed to resolve its dependencies. As a result, we do not attempt to look up the `emitter` until we use the hash service elsewhere inside our code.
+Once you use the [hash](../security/hashing) service, the config provider for the `scrypt` driver will be executed to resolve its dependencies. As a result, we do not attempt to look up the `emitter` until we use the hash service elsewhere inside our code.
 
 Since config providers are async, you might want to import the `Scrypt` driver lazily via dynamic import.
 
diff --git a/content/docs/fundamentals/container_services.md b/content/docs/concepts/container_services.md
similarity index 97%
rename from content/docs/fundamentals/container_services.md
rename to content/docs/concepts/container_services.md
index 3ebc405e..0bf5fd11 100644
--- a/content/docs/fundamentals/container_services.md
+++ b/content/docs/concepts/container_services.md
@@ -1,6 +1,6 @@
 # Container services
 
-As we discussed in the [IoC container guide](./ioc_container.md#container-bindings), the container bindings are one of the primary reasons for the IoC container to exists in AdonisJS.
+As we discussed in the [IoC container guide](dependency_injection#container-bindings), the container bindings are one of the primary reasons for the IoC container to exists in AdonisJS.
 
 Container bindings keep your codebase clean from boilerplate code required to construct objects before they can be used.
 
diff --git a/content/docs/fundamentals/ioc_container.md b/content/docs/concepts/dependency_injection.md
similarity index 99%
rename from content/docs/fundamentals/ioc_container.md
rename to content/docs/concepts/dependency_injection.md
index a8985f5b..8bfa1c95 100644
--- a/content/docs/fundamentals/ioc_container.md
+++ b/content/docs/concepts/dependency_injection.md
@@ -1,4 +1,4 @@
-# IoC container
+# Dependency injection
 
 At the heart of every AdonisJS application is an IoC container that can construct classes and resolve dependencies with almost zero config.
 
@@ -344,7 +344,7 @@ import { inject } from '@adonisjs/core'
 
 export default class UsersController {
   @inject()
-  index(, service: UserService) {}
+  index(service: UserService) {}
 }
 ```
 
diff --git a/content/docs/fundamentals/extending_the_framework.md b/content/docs/concepts/extending_the_framework.md
similarity index 75%
rename from content/docs/fundamentals/extending_the_framework.md
rename to content/docs/concepts/extending_the_framework.md
index 789f6db8..ae637d6c 100644
--- a/content/docs/fundamentals/extending_the_framework.md
+++ b/content/docs/concepts/extending_the_framework.md
@@ -21,7 +21,7 @@ export default class AppProvider {
 }
 ```
 
-In the following example, we add the `wantsJSON` method to the [Request](../http/request.md) class and define its types simultaneously.
+In the following example, we add the `wantsJSON` method to the [Request](../basics/request.md) class and define its types simultaneously.
 
 ```ts
 // title: src/extensions.ts
@@ -81,26 +81,26 @@ Request.getter('hasRequestId', function (this: Request) {
 
 Following is the list of classes that can be extended using Macros and getters.
 
-| Class | Import path |
-|------|------------|
-| [Application](https://github.com/adonisjs/application/blob/main/src/application.ts) | `@adonisjs/core/app` |
-| [Request](https://github.com/adonisjs/http-server/blob/main/src/request.ts) | `@adonisjs/core/http` |
-| [Response](https://github.com/adonisjs/http-server/blob/main/src/response.ts) | `@adonisjs/core/http` |
-| [HttpContext](https://github.com/adonisjs/http-server/blob/main/src/http_context/main.ts) | `@adonisjs/core/http` |
-| [Route](https://github.com/adonisjs/http-server/blob/main/src/router/route.ts) | `@adonisjs/core/http` |
-| [RouteGroup](https://github.com/adonisjs/http-server/blob/main/src/router/group.ts) | `@adonisjs/core/http` |
-| [RouteResource](https://github.com/adonisjs/http-server/blob/main/src/router/resource.ts) | `@adonisjs/core/http` |
-| [BriskRoute](https://github.com/adonisjs/http-server/blob/main/src/router/brisk.ts) | `@adonisjs/core/http` |
-| [ExceptionHandler](https://github.com/adonisjs/http-server/blob/main/src/exception_handler.ts) | `@adonisjs/core/http` |
-| [MultipartFile](https://github.com/adonisjs/bodyparser/blob/main/src/multipart/file.ts) | `@adonisjs/core/bodyparser` |
+| Class                                                                                          | Import path                 |
+|------------------------------------------------------------------------------------------------|-----------------------------|
+| [Application](https://github.com/adonisjs/application/blob/main/src/application.ts)            | `@adonisjs/core/app`        |
+| [Request](https://github.com/adonisjs/http-server/blob/main/src/request.ts)                    | `@adonisjs/core/http`       |
+| [Response](https://github.com/adonisjs/http-server/blob/main/src/response.ts)                  | `@adonisjs/core/http`       |
+| [HttpContext](https://github.com/adonisjs/http-server/blob/main/src/http_context/main.ts)      | `@adonisjs/core/http`       |
+| [Route](https://github.com/adonisjs/http-server/blob/main/src/router/route.ts)                 | `@adonisjs/core/http`       |
+| [RouteGroup](https://github.com/adonisjs/http-server/blob/main/src/router/group.ts)            | `@adonisjs/core/http`       |
+| [RouteResource](https://github.com/adonisjs/http-server/blob/main/src/router/resource.ts)      | `@adonisjs/core/http`       |
+| [BriskRoute](https://github.com/adonisjs/http-server/blob/main/src/router/brisk.ts)            | `@adonisjs/core/http`       |
+| [ExceptionHandler](https://github.com/adonisjs/http-server/blob/main/src/exception_handler.ts) | `@adonisjs/core/http`       |
+| [MultipartFile](https://github.com/adonisjs/bodyparser/blob/main/src/multipart/file.ts)        | `@adonisjs/core/bodyparser` |
 
 
 ## Extending modules
 Most of the AdonisJS modules provide extensible APIs to register custom implementations. Following is an aggregated list of the same.
 
-- [Creating Hash driver](../security/hash.md#creating-a-custom-hash-driver)
-- [Creating Session driver](../http/session.md#creating-a-custom-session-driver)
-- [Creating Social auth driver](../digging_deeper/social_auth.md#creating-a-custom-social-driver)
-- [Extending REPL](../ace/repl.md#adding-custom-methods-to-repl)
+- [Creating Hash driver](../security/hashing#creating-a-custom-hash-driver)
+- [Creating Session driver](../basics/session.md#creating-a-custom-session-store)
+- [Creating Social auth driver](../authentication/social_authentication#creating-a-custom-social-driver)
+- [Extending REPL](../digging_deeper/repl.md#adding-custom-methods-to-repl)
 - [Creating i18n translations loader](../digging_deeper/i18n.md#creating-a-custom-translation-loader)
 - [Creating i18n translations formatter](../digging_deeper/i18n.md#creating-a-custom-translation-formatter)
diff --git a/content/docs/fundamentals/hmr.md b/content/docs/concepts/hmr.md
similarity index 100%
rename from content/docs/fundamentals/hmr.md
rename to content/docs/concepts/hmr.md
diff --git a/content/docs/http/http_context.md b/content/docs/concepts/http_context.md
similarity index 83%
rename from content/docs/http/http_context.md
rename to content/docs/concepts/http_context.md
index 6880b7e7..e8570fc6 100644
--- a/content/docs/http/http_context.md
+++ b/content/docs/concepts/http_context.md
@@ -4,10 +4,10 @@ A new instance of [HTTP Context class](https://github.com/adonisjs/http-server/b
 
 HTTP Context holds all the information you may need related to an HTTP request. For example:
 
-- You can access the request body, headers, and query params using the [ctx.request](./request.md) property.
-- You can respond to the HTTP request using the [ctx.response](./response.md) property.
-- Access the logged-in user using the [ctx.auth](../auth/introduction.md) property.
-- Authorize user actions using the [ctx.bouncer](../digging_deeper/authorization.md) property.
+- You can access the request body, headers, and query params using the [ctx.request](../basics/request.md) property.
+- You can respond to the HTTP request using the [ctx.response](../basics/response.md) property.
+- Access the logged-in user using the [ctx.auth](../authentication/introduction.md) property.
+- Authorize user actions using the [ctx.bouncer](../security/authorization.md) property.
 - And so on.
 
 In a nutshell, the context is a request-specific store holding all the information for the ongoing request.
@@ -18,7 +18,7 @@ The HTTP context is passed by reference to the route handler, middleware, and ex
 
 ### Route handler
 
-The [router handler](./routing.md) receives the HTTP context as the first parameter.
+The [router handler](../basics/routing.md) receives the HTTP context as the first parameter.
 
 ```ts
 import router from '@adonisjs/core/services/router'
@@ -45,7 +45,7 @@ router.get('/', ({ request, response }) => {
 
 ### Controller method
 
-The [controller method](./controllers.md) (similar to the router handler) receives the HTTP context as the first parameter.
+The [controller method](../basics/controllers.md) (similar to the router handler) receives the HTTP context as the first parameter.
 
 ```ts
 import { HttpContext } from '@adonisjs/core/http'
@@ -58,7 +58,7 @@ export default class HomeController {
 
 ### Middleware class
 
-The `handle` method of the [middleware class](./middleware.md) receives HTTP context as the first parameter. 
+The `handle` method of the [middleware class](../basics/middleware.md) receives HTTP context as the first parameter. 
 
 ```ts
 import { HttpContext } from '@adonisjs/core/http'
@@ -71,7 +71,7 @@ export default class AuthMiddleware {
 
 ### Exception handler class
 
-The `handle` and the `report` methods of the [global exception handler](./exception_handling.md) class receive HTTP context as the second parameter. The first parameter is the `error` property.
+The `handle` and the `report` methods of the [global exception handler](../basics/exception_handling.md) class receive HTTP context as the second parameter. The first parameter is the `error` property.
 
 ```ts
 import {
@@ -90,7 +90,7 @@ export default class ExceptionHandler extends HttpExceptionHandler {
 }
 ```
 
-## Injecting Http Context using Dependency Injection
+## Injecting HTTP Context using Dependency Injection
 
 If you use Dependency injection throughout your application, you can inject the HTTP context to a class or a method by type hinting the `HttpContext` class.
 
@@ -101,7 +101,7 @@ Ensure the `#middleware/container_bindings_middleware` middleware is registered
 
 :::
 
-See also: [IoC container guide](../fundamentals/ioc_container.md)
+See also: [IoC container guide](../concepts/dependency_injection.md)
 
 ```ts
 // title: app/services/user_service.ts
@@ -141,7 +141,7 @@ Dependency injection is one way to accept the HTTP context as a class constructo
 
 However, it is not a hard requirement to restructure your application and use Dependency injection everywhere. You can also access the HTTP context from anywhere inside your application using the [Async local storage](https://nodejs.org/dist/latest-v21.x/docs/api/async_context.html#class-asynclocalstorage) provided by Node.js. 
 
-We have a [dedicated guide](../fundamentals/async_local_storage.md) on how Async local storage works and how AdonisJS uses it to provide global access to the HTTP context.
+We have a [dedicated guide](async_local_storage.md) on how Async local storage works and how AdonisJS uses it to provide global access to the HTTP context.
 
 In the following example, the `UserService` class uses the `HttpContext.getOrFail` method to get the HTTP context instance for the ongoing request.
 
@@ -184,7 +184,7 @@ ctx.request
 
 <dd>
 
-Reference to an instance of the [HTTP Request class](./request.md).
+Reference to an instance of the [HTTP Request class](../basics/request.md).
 
 </dd>
 
@@ -196,7 +196,7 @@ ctx.response
 
 <dd>
 
-Reference to an instance of the [HTTP Response class](./response.md).
+Reference to an instance of the [HTTP Response class](../basics/response.md).
 
 </dd>
 
@@ -256,7 +256,7 @@ ctx.session
 
 <dd>
 
-Reference to an instance of [Session](./session.md) created for the current HTTP request.
+Reference to an instance of [Session](../basics/session.md) created for the current HTTP request.
 
 </dd>
 
@@ -268,7 +268,7 @@ ctx.auth
 
 <dd>
 
-Reference to an instance of the [Authenticator class](https://github.com/adonisjs/auth/blob/main/src/authenticator.ts). Learn more about [authentication](../auth/introduction.md).
+Reference to an instance of the [Authenticator class](https://github.com/adonisjs/auth/blob/main/src/authenticator.ts). Learn more about [authentication](../authentication/introduction.md).
 
 </dd>
 
@@ -280,7 +280,7 @@ ctx.view
 
 <dd>
 
-Reference to an instance of Edge renderer. Learn more about Edge in [View and templates guide](./views_and_templates.md#using-edge)
+Reference to an instance of Edge renderer. Learn more about Edge in [View and templates guide](../views-and-templates/introduction#using-edge)
 
 </dd>
 
@@ -292,7 +292,7 @@ ctx\.ally
 
 <dd>
 
-Reference to an instance of the [Ally Manager class](https://github.com/adonisjs/ally/blob/main/src/ally_manager.ts) to implement social login in your apps. Learn more about [Ally](../digging_deeper/social_auth.md)
+Reference to an instance of the [Ally Manager class](https://github.com/adonisjs/ally/blob/main/src/ally_manager.ts) to implement social login in your apps. Learn more about [Ally](../authentication/social_authentication)
 
 </dd>
 
@@ -304,7 +304,7 @@ ctx.bouncer
 
 <dd>
 
-Reference to an instance of the [Bouncer class](https://github.com/adonisjs/bouncer/blob/main/src/bouncer.ts). Learn more about [Authorization](../digging_deeper/authorization.md).
+Reference to an instance of the [Bouncer class](https://github.com/adonisjs/bouncer/blob/main/src/bouncer.ts). Learn more about [Authorization](../security/authorization.md).
 
 </dd>
 
@@ -325,14 +325,15 @@ Reference to an instance of the [I18n class](https://github.com/adonisjs/i18n/bl
 
 ## Extending HTTP context
 
-You may add custom properties to the HTTP context class using macros or getters. Make sure to read the [extending AdonisJS guide](../fundamentals/extending_the_framework.md) first if you are new to the concept of macros.
+You may add custom properties to the HTTP context class using macros or getters. Make sure to read the [extending AdonisJS guide](extending_the_framework.md) first if you are new to the concept of macros.
 
 ```ts
 import { HttpContext } from '@adonisjs/core/http'
 
 HttpContext.macro('aMethod', function (this: HttpContext) {
   return value
-}
+})
+
 HttpContext.getter('aProperty', function (this: HttpContext) {
   return value
 })
@@ -354,7 +355,8 @@ declare module '@adonisjs/core/http' {
 
 HttpContext.macro('aMethod', function (this: HttpContext) {
   return value
-}
+})
+
 HttpContext.getter('aProperty', function (this: HttpContext) {
   return value
 })
diff --git a/content/docs/http/introduction.md b/content/docs/concepts/http_overview.md
similarity index 79%
rename from content/docs/http/introduction.md
rename to content/docs/concepts/http_overview.md
index 7bd49436..a72383c2 100644
--- a/content/docs/http/introduction.md
+++ b/content/docs/concepts/http_overview.md
@@ -10,7 +10,7 @@ The HTTP layer inside an AdonisJS application consists of the following modules.
 
 <dt>
 
-[Router](./routing.md)
+[Router](../basics/routing.md)
 
 </dt>
 
@@ -22,7 +22,7 @@ The [router module](https://github.com/adonisjs/http-server/blob/main/src/router
 
 <dt>
 
-[Controllers](./controllers.md)
+[Controllers](../basics/controllers.md)
 
 </dt>
 
@@ -34,7 +34,7 @@ Controllers are JavaScript classes that you bind to a route to handle the HTTP r
 
 <dt>
 
-[HttpContext](./http_context.md)
+[HttpContext](http_context.md)
 
 </dt>
 
@@ -47,7 +47,7 @@ AdonisJS creates an instance of the [HttpContext](https://github.com/adonisjs/ht
 
 <dt>
 
-[Middleware](./middleware.md)
+[Middleware](../basics/middleware.md)
 
 </dt>
 
@@ -59,7 +59,7 @@ The middleware pipeline in AdonisJS is an implementation of [Chain of Responsibi
 
 <dt>
 
-[Global Exception handler](./exception_handling.md)
+[Global Exception handler](../basics/exception_handling.md)
 
 </dt>
 
@@ -92,7 +92,7 @@ The HTTP server is booted once you call [the `boot` method](https://github.com/a
 
 In a typical AdonisJS application, the `boot` method is called by the [Ignitor](https://github.com/adonisjs/core/blob/main/src/ignitor/http.ts) module within the `bin/server.ts` file.
 
-Also, it is essential to define the routes, middleware, and the global exception handler before the `boot` method is called, and AdonisJS achieves that using the `start/routes.ts` and `start/kernel.ts` [preload files](../fundamentals/adonisrc_file.md#preloads).
+Also, it is essential to define the routes, middleware, and the global exception handler before the `boot` method is called, and AdonisJS achieves that using the `start/routes.ts` and `start/kernel.ts` [preload files](adonisrc_file#preloads).
 
 ![](./server_boot_lifecycle.png)
 
@@ -102,8 +102,8 @@ Now that we have an HTTP server listening for incoming requests. Let's see how A
 :::note
 
 **See also:**\
-[Middleware execution flow](./middleware.md#middleware-execution-flow)\
-[Middleware and exception handling](./middleware.md#middleware-and-exception-handling)
+[Middleware execution flow](../basics/middleware.md#middleware-execution-flow)\
+[Middleware and exception handling](../basics/middleware.md#middleware-and-exception-handling)
 
 :::
 
@@ -115,9 +115,9 @@ Now that we have an HTTP server listening for incoming requests. Let's see how A
 
 <dd>
 
-As the first step, the server module creates an instance of the [HttpContext](./http_context.md) class and passes it as a reference to the middleware, route handlers, and the global exception handler.
+As the first step, the server module creates an instance of the [HttpContext](http_context.md) class and passes it as a reference to the middleware, route handlers, and the global exception handler.
 
-If you have enabled the [AsyncLocalStorage](../fundamentals/async_local_storage.md#usage), then the same instance is 
+If you have enabled the [AsyncLocalStorage](async_local_storage.md#usage), then the same instance is 
 shared as the local storage state.
 
 </dd>
@@ -126,7 +126,7 @@ shared as the local storage state.
 
 <dd>
 
-Next, the middleware from the [server middleware stack](./middleware.md#server-middleware-stack) are executed. These middleware can intercept and respond to the request before it reaches the route handler.
+Next, the middleware from the [server middleware stack](../basics/middleware.md#server-middleware-stack) are executed. These middleware can intercept and respond to the request before it reaches the route handler.
 
 Also, every HTTP request goes through the server middleware stack, even if you have not defined any router for the given endpoint. This allows server middleware to add functionality to an app without relying on the routing system.
 
@@ -144,7 +144,7 @@ If a server middleware does not end the request, we look for a matching route fo
 
 <dd>
 
-Once there is a matching route, we execute the [router global middleware](./middleware.md#router-middleware-stack) and the [named middleware stack](./middleware.md#named-middleware-collection). Again, middleware can intercept the request before it reaches the route handler.
+Once there is a matching route, we execute the [router global middleware](../basics/middleware.md#router-middleware-stack) and the [named middleware stack](../basics/middleware.md#named-middleware-collection). Again, middleware can intercept the request before it reaches the route handler.
 
 </dd>
 
@@ -164,7 +164,7 @@ Suppose an exception is raised during any step in the process. In that case, the
 
 Once you define the response body using the `response.send` method or by returning a value from the route handler, we begin the response serialization process and set the appropriate headers.
 
-Learn more about [response body serialization](./response.md#response-body-serialization)
+Learn more about [response body serialization](../basics/response.md#response-body-serialization)
 
 </dd>
 
diff --git a/content/docs/fundamentals/scaffolding.md b/content/docs/concepts/scaffolding.md
similarity index 94%
rename from content/docs/fundamentals/scaffolding.md
rename to content/docs/concepts/scaffolding.md
index d150c252..20cb7aff 100644
--- a/content/docs/fundamentals/scaffolding.md
+++ b/content/docs/concepts/scaffolding.md
@@ -1,4 +1,4 @@
-# Scaffolding and Codemods
+# Scaffolding and codemods
 
 Scaffolding refers to the process of generating source files from static templates (aka stubs), and codemods refer to updating the TypeScript source code by parsing the AST.
 
@@ -166,13 +166,13 @@ export default class {{ modelName }}Resource {
 ### Global variables
 The following global variables are always shared with a stub.
 
-| Variable       | Description                                                                                                                                         |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `app`          | Reference to an instance of the [application class](../fundamentals/application.md).                                                                |
-| `generators`   | Reference to the [generators module](https://github.com/adonisjs/application/blob/main/src/generators.ts).                                          |
-| `randomString` | Reference to the [randomString](../reference/helpers.md#random) helper function.                                                                               |
-| `string`       | A function to create a [string builder](../reference/helpers.md#string-builder) instance. You can use the string builder to apply transformations on a string. |
-| `flags`        | The command-line flags are defined when running the ace command.                                                                              |
+| Variable       | Description                                                                                                                                                         |
+|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `app`          | Reference to an instance of the [application class](application.md).                                                                                                |
+| `generators`   | Reference to the [generators module](https://github.com/adonisjs/application/blob/main/src/generators.ts).                                                          |
+| `randomString` | Reference to the [randomString](../references/helpers.md#random) helper function.                                                                               |
+| `string`       | A function to create a [string builder](../references/helpers.md#string-builder) instance. You can use the string builder to apply transformations on a string. |
+| `flags`        | The command-line flags are defined when running the ace command.                                                                                                    |
 
 
 ## Ejecting stubs
@@ -201,7 +201,7 @@ export default class {{ controllerName }} {
 ```
 
 - In the first two lines, we use the [generators module](https://github.com/adonisjs/application/blob/main/src/generators.ts) to generate the controller class name and the controller file name.
-- From lines 3-7, we [define the destination path](#customizing-the-destination-path) for the controller file using the `exports` function.
+- From lines 3-7, we [define the destination path](#using-cli-flags-to-customize-stub-output-destination)customizing-the-destination-path) for the controller file using the `exports` function.
 - Finally, we define the contents of the scaffolded controller.
 
 Feel free to modify the stub. Next time, the changes will be picked when you run the `make:controller` command.
@@ -272,7 +272,7 @@ The codemods API is powered by [ts-morph](https://github.com/dsherret/ts-morph)
 ```ts
 import type Configure from '@adonisjs/core/commands/configure'
 
-export function configure(command: ConfigureCommand) {
+export async function configure(command: ConfigureCommand) {
   const codemods = await command.createCodemods()
 }
 ```
diff --git a/content/docs/fundamentals/scaffolding_workflow.png b/content/docs/concepts/scaffolding_workflow.png
similarity index 100%
rename from content/docs/fundamentals/scaffolding_workflow.png
rename to content/docs/concepts/scaffolding_workflow.png
diff --git a/content/docs/fundamentals/scaffolding_workflow_original.png b/content/docs/concepts/scaffolding_workflow_original.png
similarity index 100%
rename from content/docs/fundamentals/scaffolding_workflow_original.png
rename to content/docs/concepts/scaffolding_workflow_original.png
diff --git a/content/docs/http/server_boot_lifecycle.png b/content/docs/concepts/server_boot_lifecycle.png
similarity index 100%
rename from content/docs/http/server_boot_lifecycle.png
rename to content/docs/concepts/server_boot_lifecycle.png
diff --git a/content/docs/http/server_boot_lifecycle_original.png b/content/docs/concepts/server_boot_lifecycle_original.png
similarity index 100%
rename from content/docs/http/server_boot_lifecycle_original.png
rename to content/docs/concepts/server_boot_lifecycle_original.png
diff --git a/content/docs/fundamentals/service_providers.md b/content/docs/concepts/service_providers.md
similarity index 90%
rename from content/docs/fundamentals/service_providers.md
rename to content/docs/concepts/service_providers.md
index bcfb4b59..029347ae 100644
--- a/content/docs/fundamentals/service_providers.md
+++ b/content/docs/concepts/service_providers.md
@@ -1,8 +1,8 @@
-# Service Providers
+# Service providers
 
 Services providers are plain JavaScript classes with lifecycle methods to perform actions during different phases of the application.
 
-A service provider can register [bindings into the container](./ioc_container.md#container-bindings), [extend existing bindings](./ioc_container.md#container-events), or run actions after the HTTP server starts.
+A service provider can register [bindings into the container](../concepts/dependency_injection.md#container-bindings), [extend existing bindings](../concepts/dependency_injection.md#container-events), or run actions after the HTTP server starts.
 
 Service providers are the entry point to an AdonisJS application with the ability to modify the application state before it is considered ready.
 
@@ -35,9 +35,9 @@ By default, a provider is loaded in all the runtime environments. However, you c
 
 Service providers are stored inside the `providers` directory of your app. Alternatively, you can use the `node ace make:provider app` command.
 
-The provider module must have an `export default` statement returning the provider class. The class constructor receives an instance of the [Application](./application.md) class.
+The provider module must have an `export default` statement returning the provider class. The class constructor receives an instance of the [Application](application.md) class.
 
-See also: [Make provider command](../reference/commands.md#makeprovider)
+See also: [Make provider command](../references/commands.md#makeprovider)
 
 ```ts
 import { ApplicationService } from '@adonisjs/core/types'
@@ -159,7 +159,7 @@ export default class AppProvider {
 
 The `shutdown` method is called when AdonisJS is in the middle of gracefully exiting the application.
 
-The event of exiting the application depends upon the environment in which the app is running and how the application process started. Please read the [application lifecycle guide](./application_lifecycle.md) to know more about it.
+The event of exiting the application depends upon the environment in which the app is running and how the application process started. Please read the [application lifecycle guide](application_lifecycle.md) to know more about it.
 
 ```ts
 export default class AppProvider {
diff --git a/content/docs/fundamentals/start_phase_flow_chart.png b/content/docs/concepts/start_phase_flow_chart.png
similarity index 100%
rename from content/docs/fundamentals/start_phase_flow_chart.png
rename to content/docs/concepts/start_phase_flow_chart.png
diff --git a/content/docs/fundamentals/start_phase_flow_chart_original.png b/content/docs/concepts/start_phase_flow_chart_original.png
similarity index 100%
rename from content/docs/fundamentals/start_phase_flow_chart_original.png
rename to content/docs/concepts/start_phase_flow_chart_original.png
diff --git a/content/docs/fundamentals/termination_phase_flow_chart.png b/content/docs/concepts/termination_phase_flow_chart.png
similarity index 100%
rename from content/docs/fundamentals/termination_phase_flow_chart.png
rename to content/docs/concepts/termination_phase_flow_chart.png
diff --git a/content/docs/fundamentals/termination_phase_flow_chart_original.png b/content/docs/concepts/termination_phase_flow_chart_original.png
similarity index 100%
rename from content/docs/fundamentals/termination_phase_flow_chart_original.png
rename to content/docs/concepts/termination_phase_flow_chart_original.png
diff --git a/content/docs/fundamentals/tooling_config.md b/content/docs/concepts/tooling_config.md
similarity index 100%
rename from content/docs/fundamentals/tooling_config.md
rename to content/docs/concepts/tooling_config.md
diff --git a/content/docs/fundamentals/typescript_build_process.md b/content/docs/concepts/typescript_build_process.md
similarity index 94%
rename from content/docs/fundamentals/typescript_build_process.md
rename to content/docs/concepts/typescript_build_process.md
index abebff05..3e6db481 100644
--- a/content/docs/fundamentals/typescript_build_process.md
+++ b/content/docs/concepts/typescript_build_process.md
@@ -19,11 +19,11 @@ All the below-mentioned tools come pre-installed as development dependencies wit
 
 - **[SWC](https://swc.rs/)** is a TypeScript compiler written in Rust. We use it during development with TS Node to make the JIT process extremely fast.
 
-| Tool | Used for | Type checking |
-|------|---------|------------|
-| `TSC` | Creating production build | Yes |
-| `TS Node` | Development | No |
-| `SWC` | Development | No |
+| Tool      | Used for                  | Type checking |
+|-----------|---------------------------|---------------|
+| `TSC`     | Creating production build | Yes           |
+| `TS Node` | Development               | No            |
+| `SWC`     | Development               | No            |
 
 ## Executing TypeScript files without compilation
 
@@ -100,7 +100,7 @@ The production build of your AdonisJS application is created using the `node ace
 - Rewrite the `ace.js` file **from scratch** to remove the `ts-node/esm` loader. 
 - Compile frontend assets using Vite (if configured).
 - Compile TypeScript source code to JavaScript using [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html).
-- Copy non-TypeScript files registered under the [`metaFiles`](./adonisrc_file.md#metafiles) array to the `./build` folder.
+- Copy non-TypeScript files registered under the [`metaFiles`](../concepts/adonisrc_file#metafiles) array to the `./build` folder.
 - Copy the `package.json` and `package-lock.json/yarn.lock` files to the `./build` folder.
 
 :::warning
diff --git a/content/docs/database/introduction.md b/content/docs/database/introduction.md
new file mode 100644
index 00000000..703555c9
--- /dev/null
+++ b/content/docs/database/introduction.md
@@ -0,0 +1,16 @@
+# SQL and ORMs
+
+SQL databases are popular for storing the application's data in persistent storage. You can use any libraries and ORMs to make SQL queries inside an AdonisJS application.
+
+:::note
+The AdonisJS core team built the [Lucid ORM](./lucid.md) but does not force you to use it. You can use any other SQL libraries and ORMs you would like inside an AdonisJS application.
+:::
+
+## Popular options
+
+Following is the list of other popular SQL libraries and ORMs you can use inside an AdonisJS application (just like any other Node.js application).
+
+- [**Lucid**](./lucid.md) is a SQL query builder and an **Active Record ORM** built on top of [Knex](https://knexjs.org) created and maintained by the AdonisJS core team.
+- [**Kysely**](https://kysely.dev/docs/getting-started) is an end-to-end type safe query builder for Node.js. Kysely is a great fit if you need a lean query builder without any models. We have written an article explaining [how you can integrate Kysely inside an AdonisJS application](https://adonisjs.com/blog/kysely-with-adonisjs).
+- [**Drizzle ORM**](https://orm.drizzle.team/) is used by many AdonisJS developers in our community. We do not have any experience using this ORM, but you want to check it out and see if it's an excellent fit for your use case.
+- [**Mikro ORM**](https://mikro-orm.io/docs/guide/first-entity) is an underrated ORM in the Node.js ecosystem. MikroORM is a little verbose in comparison to Lucid. However, it is actively maintained and also built on top of Knex.
diff --git a/content/docs/database/lucid.md b/content/docs/database/lucid.md
new file mode 100644
index 00000000..fc4b1c4c
--- /dev/null
+++ b/content/docs/database/lucid.md
@@ -0,0 +1,212 @@
+# Lucid ORM
+
+Lucid is a SQL query builder, and an Active Record ORM built on top of [Knex](https://knexjs.org) created and maintained by the AdonisJS core team. Lucid strives to leverage SQL to its full potential and offers clean API for many advanced SQL operations.
+
+:::note
+The documentation for Lucid is available on [https://lucid.adonisjs.com](https://lucid.adonisjs.com)
+:::
+
+## Why Lucid
+
+Following are some of the hand-picked Lucid features.
+
+- A fluent query builder built on top of Knex.
+- Support for read-write replicas and multiple connection management.
+- Class-based models that adhere to the active record pattern (handling relations, serialization and hooks).
+- Migration system to modify database schema using incremental changesets.
+- Model factories to generate fake data for testing.
+- Database seeders to insert initial/dummy data into the database.
+
+Apart from those, the following are additional reasons for using Lucid inside an AdonisJS application.
+
+- We ship first-class integrations for Lucid with the Auth package and validator. Therefore, you do not have to write these integrations yourself.
+
+- Lucid comes pre-configured with the `api` and the `web` starter kits, providing a head start to your applications.
+
+- One of the primary goals of Lucid is to leverage SQL to its full potential and support many advanced SQL operations like **window functions**, **recursive CTEs**, **JSON operations**, **row-based locks**, and much more.
+
+- Both Lucid and Knex have been around for many years. Hence, they are mature and battle-tested compared to many other new ORMs.
+
+With that said, AdonisJS does not force you to use Lucid. Just uninstall the package and install the ORM of your choice.
+
+## Installation
+
+Install and configure Lucid using the following command.
+
+```sh
+node ace add @adonisjs/lucid
+```
+
+:::disclosure{title="See steps performed by the configure command"}
+
+1. Registers the following service provider inside the `adonisrc.ts` file.
+
+   ```ts
+   {
+     providers: [
+       // ...other providers
+       () => import('@adonisjs/lucid/database_provider'),
+     ]
+   }
+   ```
+
+2. Register the following command inside the `adonisrc.ts` file.
+
+   ```ts
+   {
+     commands: [
+       // ...other commands
+       () => import('@adonisjs/lucid/commands'),
+     ]
+   }
+   ```
+
+3. Create the `config/database.ts` file.
+
+4. Define the environment variables and their validations for the selected dialect.
+
+5. Install required peer dependencies.
+
+:::
+
+
+## Creating your first model
+
+Once the configuration is completed, you can create your first model using the following command.
+
+```sh
+node ace make:model User
+```
+
+This command creates a new file inside the `app/models` directory with the following content.
+
+```ts
+import { DateTime } from 'luxon'
+import { BaseModel, column } from '@adonisjs/lucid/orm'
+
+export default class User extends BaseModel {
+  @column({ isPrimary: true })
+  declare id: number
+
+  @column.dateTime({ autoCreate: true })
+  declare createdAt: DateTime
+
+  @column.dateTime({ autoCreate: true, autoUpdate: true })
+  declare updatedAt: DateTime
+}
+```
+
+Learn more about models by visiting the [official documentation](https://lucid.adonisjs.com/docs/models).
+
+## Migrations
+
+Migrations are a way to modify the database schema and data using incremental changesets. You can create a new migration using the following command.
+
+```sh
+node ace make:migration users
+```
+
+This command creates a new file inside the `database/migrations` directory with the following content.
+
+```ts
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+export default class extends BaseSchema {
+  protected tableName = 'users'
+
+  async up() {
+    this.schema.createTable(this.tableName, (table) => {
+      table.increments('id')
+      table.timestamp('created_at')
+      table.timestamp('updated_at')
+    })
+  }
+
+  async down() {
+    this.schema.dropTable(this.tableName)
+  }
+}
+```
+
+You can run all the pending migrations using the following command.
+
+```sh
+node ace migration:run
+```
+
+Learn more about migrations by visiting the [official documentation](https://lucid.adonisjs.com/docs/migrations).
+
+## Query Builder
+
+Lucid ships with a fluent query builder built on top of Knex. You can use the query builder to perform CRUD operations on your database.
+
+```ts
+import db from '@adonisjs/lucid/services/db'
+
+/**
+ * Creates query builder instance
+ */
+const query = db.query()
+
+/**
+ * Creates query builder instance and also selects
+ * the table
+ */
+const queryWithTableSelection = db.from('users')
+```
+
+The query builder can also be scoped to a model instance.
+
+```ts
+import User from '#models/user'
+
+const user = await User.query().where('username', 'rlanz').first()
+```
+
+Learn more about the query builder by visiting the [official documentation](https://lucid.adonisjs.com/docs/select-query-builder).
+
+## CRUD operations
+
+Lucid models have built-in methods to perform CRUD operations on the database.
+
+```ts
+import User from '#models/user'
+
+/**
+ * Create a new user
+ */
+const user = await User.create({
+  username: 'rlanz',
+  email: 'romain@adonisjs.com',
+})
+
+/**
+ * Find a user by primary key
+ */
+const user = await User.find(1)
+
+/**
+ * Update a user
+ */
+
+const user = await User.find(1)
+user.username = 'romain'
+await user.save()
+
+/**
+ * Delete a user
+ */
+const user = await User.find(1)
+await user.delete()
+```
+
+Learn more about CRUD operations by visiting the [official documentation](https://lucid.adonisjs.com/docs/crud-operations).
+
+## Learn more
+
+- [Lucid documentation](https://lucid.adonisjs.com)
+- [Installation & Usage](https://lucid.adonisjs.com/docs/installation)
+- [CRUD Operations](https://lucid.adonisjs.com/docs/crud-operations)
+- [Model Hooks](https://lucid.adonisjs.com/docs/model-hooks)
+- [Relations](https://lucid.adonisjs.com/docs/relationships)
+- [Adocasts Lucid Series](https://adocasts.com/topics/lucid)
diff --git a/content/docs/database/sql.md b/content/docs/database/sql.md
deleted file mode 100644
index ba69e5e5..00000000
--- a/content/docs/database/sql.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# SQL and ORMs
-
-SQL databases are popular for storing the application's data in persistent storage. You can use any libraries and ORMS to make SQL queries inside an AdonisJS application.
-
-However, the AdonisJS core team [has created/maintains Lucid](https://lucid.adonisjs.com/docs/introduction). Lucid is a SQL query builder and an Active Record ORM built on top of [Knex](https://knexjs.org/). We created Lucid back in 2016 and maintain it to date.
-
-:::note
-
-The documentation for Lucid is available on [https://lucid.adonisjs.com](https://lucid.adonisjs.com)
-
-:::
-
-## Why Lucid
-
-Apart from the features listed on the [Lucid website](https://lucid.adonisjs.com/docs/introduction), the following are additional reasons for using Lucid inside an AdonisJS application.
-
-- We ship first-class integrations for Lucid with the Auth package and validator. Therefore, you do not have to write these integrations yourself.
-
-- Lucid comes pre-configured with the `api` and the `web` starter kits, providing a head start to your applications.
-
-- One of the primary goals of Lucid is to leverage SQL to its full potential and support many advanced SQL operations like **window functions**, **recursive CTEs**, **JSON operations**, **row-based locks**, and much more.
-
-- Both Lucid and Knex have been around for many years. Hence, they are mature and battle-tested compared to many other new ORMs.
-
-With that said, AdonisJS does not force you to use Lucid. Just uninstall the package and install the ORM of your choice.
-
-## Other popular options
-Following is the list of other popular SQL libraries and ORMs you can use inside an AdonisJS application (just like any other Node.js application).
-
-- [**Kysely**](https://kysely.dev/docs/getting-started) is an end-to-end type safe query builder for Node.js. Kysely is a great fit if you need a lean query builder without any models. We have written an article explaining [how you can integrate Kysely inside an AdonisJS application](https://adonisjs.com/blog/kysely-with-adonisjs).
-- [**Drizzle ORM**](https://orm.drizzle.team/) is used by many AdonisJS developers in our community. We do not have any experience using this ORM, but you want to check it out and see if it's an excellent fit for your use case.
-- [**Mikro ORM**](https://mikro-orm.io/docs/guide/first-entity) is an underrated ORM in the Node.js ecosystem. MikroORM is a little verbose in comparison to Lucid. However, it is actively maintained and also built on top of Knex.
diff --git a/content/docs/db.json b/content/docs/db.json
index cab27d79..e43dfdc3 100644
--- a/content/docs/db.json
+++ b/content/docs/db.json
@@ -1,517 +1,494 @@
 [
   {
-    "permalink": "introduction",
+    "permalink": "preface/introduction",
     "title": "Introduction",
-    "contentPath": "./guides/introduction.md",
-    "category": "Getting started"
+    "contentPath": "./preface/introduction.md",
+    "category": "Preface"
   },
   {
-    "permalink": "installation",
-    "title": "Installation",
-    "contentPath": "./guides/installation.md",
-    "category": "Getting started"
+    "permalink": "preface/faqs",
+    "title": "FAQs",
+    "contentPath": "./preface/faqs.md",
+    "category": "Preface"
   },
   {
-    "permalink": "folder-structure",
-    "title": "Folder structure",
-    "contentPath": "./guides/folder_structure.md",
-    "category": "Getting started"
+    "permalink": "preface/governance",
+    "title": "Governance",
+    "contentPath": "./preface/governance.md",
+    "category": "Preface"
   },
   {
-    "permalink": "config",
-    "title": "Config",
-    "contentPath": "./guides/config.md",
-    "category": "Getting started"
+    "permalink": "preface/releases",
+    "title": "Releases",
+    "contentPath": "./preface/releases.md",
+    "category": "Preface"
   },
   {
-    "permalink": "environment-variables",
-    "title": "Environment variables",
-    "contentPath": "./guides/env.md",
-    "category": "Getting started"
+    "permalink": "preface/contribution-guide",
+    "title": "Contribution Guide",
+    "contentPath": "./preface/contribution_guide.md",
+    "category": "Preface"
   },
   {
-    "permalink": "faqs",
-    "title": "FAQs",
-    "contentPath": "./guides/faqs.md",
+    "permalink": "getting-started/installation",
+    "title": "Installation",
+    "contentPath": "./getting_started/installation.md",
     "category": "Getting started"
   },
   {
-    "permalink": "releases",
-    "title": "Releases",
-    "contentPath": "./guides/releases.md",
+    "permalink": "getting-started/configuration",
+    "title": "Configuration",
+    "contentPath": "./getting_started/configuration.md",
     "category": "Getting started"
   },
   {
-    "permalink": "http",
-    "redirects": [],
-    "title": "Introduction",
-    "contentPath": "./http/introduction.md",
-    "category": "HTTP"
+    "permalink": "getting-started/environment-variables",
+    "title": "Environment variables",
+    "contentPath": "./getting_started/environment_variables.md",
+    "category": "Getting started"
   },
   {
-    "permalink": "http-context",
-    "redirects": ["context"],
-    "title": "HTTP context",
-    "contentPath": "./http/http_context.md",
-    "category": "HTTP"
+    "permalink": "getting-started/folder-structure",
+    "title": "Folder structure",
+    "contentPath": "./getting_started/folder_structure.md",
+    "category": "Getting started"
   },
   {
-    "permalink": "routing",
-    "title": "Routing",
-    "contentPath": "./http/routing.md",
-    "category": "HTTP"
+    "permalink": "getting-started/deployment",
+    "title": "Deployment",
+    "contentPath": "./getting_started/deployment.md",
+    "category": "Getting started"
   },
   {
-    "permalink": "controllers",
-    "title": "Controllers",
-    "contentPath": "./http/controllers.md",
-    "category": "HTTP"
+    "permalink": "concepts/adonisrc-file",
+    "title": "AdonisRC file",
+    "contentPath": "./concepts/adonisrc_file.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "request",
-    "title": "Request",
-    "contentPath": "./http/request.md",
-    "category": "HTTP"
+    "permalink": "concepts/async-local-storage",
+    "title": "Async local storage",
+    "contentPath": "./concepts/async_local_storage.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "response",
-    "title": "Response",
-    "contentPath": "./http/response.md",
-    "category": "HTTP"
+    "permalink": "concepts/application",
+    "title": "Application",
+    "contentPath": "./concepts/application.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "middleware",
-    "title": "Middleware",
-    "contentPath": "./http/middleware.md",
-    "category": "HTTP"
+    "permalink": "concepts/application-lifecycle",
+    "title": "Application lifecycle",
+    "contentPath": "./concepts/application_lifecycle.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "cookies",
-    "title": "Cookies",
-    "contentPath": "./http/cookies.md",
-    "category": "HTTP"
+    "permalink": "concepts/config-providers",
+    "title": "Config providers",
+    "contentPath": "./concepts/config_providers.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "bodyparser-middleware",
-    "title": "Bodyparser middleware",
-    "contentPath": "./http/bodyparser_middleware.md",
-    "category": "HTTP"
+    "permalink": "concepts/container-services",
+    "title": "Container services",
+    "contentPath": "./concepts/container_services.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "file-uploads",
-    "title": "File uploads",
-    "contentPath": "./http/file_uploads.md",
-    "category": "HTTP"
+    "permalink": "concepts/dependency-injection",
+    "title": "Dependency injection (DI)",
+    "contentPath": "./concepts/dependency_injection.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "validation",
-    "title": "Validation",
-    "contentPath": "./http/validation.md",
-    "category": "HTTP"
+    "permalink": "concepts/extending-adonisjs",
+    "title": "Extending the framework",
+    "contentPath": "./concepts/extending_the_framework.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "session",
-    "title": "Session",
-    "contentPath": "./http/session.md",
-    "category": "HTTP"
+    "permalink": "concepts/hot-module-replacement",
+    "title": "Hot module replacement (HMR)",
+    "contentPath": "./concepts/hmr.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "url-builder",
-    "redirects": ["guides/security/signed-urls"],
-    "title": "URL builder",
-    "contentPath": "./http/url_builder.md",
-    "category": "HTTP"
+    "permalink": "concepts/http-overview",
+    "title": "HTTP overview",
+    "contentPath": "./concepts/http_overview.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "exception-handling",
-    "title": "Exception handling",
-    "contentPath": "./http/exception_handling.md",
-    "category": "HTTP"
+    "permalink": "concepts/http-context",
+    "title": "HTTP context",
+    "contentPath": "./concepts/http_context.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "views-and-templates",
-    "title": "Views and Templates",
-    "contentPath": "./http/views_and_templates.md",
-    "category": "HTTP"
+    "permalink": "concepts/service-providers",
+    "title": "Service providers",
+    "contentPath": "./concepts/service_providers.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "static-file-server",
-    "redirects": ["guides/static-assets"],
-    "title": "Static file server",
-    "contentPath": "./http/static_file_server.md",
-    "category": "HTTP"
+    "permalink": "concepts/scaffolding",
+    "title": "Scaffolding",
+    "contentPath": "./concepts/scaffolding.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "assets-bundling",
-    "title": "Assets bundling",
-    "contentPath": "./http/assets_bundling.md",
-    "category": "HTTP"
+    "permalink": "concepts/tooling-config",
+    "title": "Tooling config",
+    "contentPath": "./concepts/tooling_config.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "assets-bundling-encore",
-    "title": "Assets Bundling (Encore)",
-    "draft": true,
-    "contentPath": "./http/assets_bundling_encore.md",
-    "category": "HTTP"
+    "permalink": "concepts/typescript-build-process",
+    "title": "TypeScript build process",
+    "contentPath": "./concepts/typescript_build_process.md",
+    "category": "Concepts"
   },
   {
-    "permalink": "sql",
-    "title": "SQL & ORMs",
-    "contentPath": "./database/sql.md",
-    "category": "Database"
+    "permalink": "basics/routing",
+    "title": "Routing",
+    "contentPath": "./basics/routing.md",
+    "category": "Basics"
   },
   {
-    "permalink": "redis",
-    "title": "Redis",
-    "contentPath": "./database/redis.md",
-    "category": "Database"
+    "permalink": "basics/controllers",
+    "title": "Controllers",
+    "contentPath": "./basics/controllers.md",
+    "category": "Basics"
   },
   {
-    "permalink": "hashing",
-    "title": "Hash",
-    "contentPath": "./security/hash.md",
-    "category": "Security"
+    "permalink": "basics/middleware",
+    "title": "Middleware",
+    "contentPath": "./basics/middleware.md",
+    "category": "Basics"
   },
   {
-    "permalink": "encryption",
-    "title": "Encryption",
-    "contentPath": "./security/encryption.md",
-    "category": "Security"
+    "permalink": "basics/body-parser",
+    "title": "Body parser",
+    "contentPath": "./basics/body_parser.md",
+    "category": "Basics"
   },
   {
-    "permalink": "web-security",
-    "title": "Securing SSR apps",
-    "contentPath": "./security/web-security.md",
-    "category": "Security"
+    "permalink": "basics/request",
+    "title": "Request",
+    "contentPath": "./basics/request.md",
+    "category": "Basics"
   },
   {
-    "permalink": "rate-limiter",
-    "title": "Rate limiter",
-    "contentPath": "./security/rate-limiter.md",
-    "category": "Security"
+    "permalink": "basics/response",
+    "title": "Response",
+    "contentPath": "./basics/response.md",
+    "category": "Basics"
   },
   {
-    "permalink": "cors",
-    "title": "CORS",
-    "contentPath": "./security/cors.md",
-    "category": "Security"
+    "permalink": "basics/validation",
+    "title": "Validation",
+    "contentPath": "./basics/validation.md",
+    "category": "Basics"
   },
   {
-    "permalink": "auth",
-    "title": "Introduction",
-    "contentPath": "./auth/introduction.md",
-    "category": "Auth"
+    "permalink": "basics/file-uploads",
+    "title": "File uploads",
+    "contentPath": "./basics/file_uploads.md",
+    "category": "Basics"
   },
   {
-    "permalink": "verifying_user_credentials",
-    "title": "Verifying user credentials",
-    "contentPath": "./auth/verifying_user_credentials.md",
-    "category": "Auth"
+    "permalink": "basics/session",
+    "title": "Session",
+    "contentPath": "./basics/session.md",
+    "category": "Basics"
   },
   {
-    "permalink": "auth-session-guard",
-    "title": "Session guard",
-    "contentPath": "./auth/session_guard.md",
-    "category": "Auth"
+    "permalink": "basics/cookies",
+    "title": "Cookies",
+    "contentPath": "./basics/cookies.md",
+    "category": "Basics"
   },
   {
-    "permalink": "auth-access-tokens-guard",
-    "title": "Access tokens guard",
-    "contentPath": "./auth/access_tokens_guard.md",
-    "category": "Auth"
+    "permalink": "basics/exception-handling",
+    "title": "Exception handling",
+    "contentPath": "./basics/exception_handling.md",
+    "category": "Basics"
   },
   {
-    "permalink": "basic-auth-guard",
-    "title": "Basic auth guard",
-    "contentPath": "./auth/basic_auth_guard.md",
-    "category": "Auth"
+    "permalink": "basics/vite",
+    "title": "Vite",
+    "contentPath": "./basics/vite.md",
+    "category": "Basics"
   },
   {
-    "permalink": "auth-custom-guards",
-    "title": "Custom auth guards",
-    "contentPath": "./auth/custom_auth_guards.md",
-    "category": "Auth"
+    "permalink": "basics/static-file-server",
+    "title": "Static file server",
+    "contentPath": "./basics/static_file_server.md",
+    "category": "Basics"
   },
   {
-    "permalink": "mail",
+    "permalink": "database/introduction",
     "title": "Introduction",
-    "contentPath": "./mail/introduction.md",
-    "category": "Mail"
-  },
-  {
-    "permalink": "mail-message",
-    "title": "Configuring message",
-    "contentPath": "./mail/message.md",
-    "category": "Mail"
+    "contentPath": "./database/introduction.md",
+    "category": "Database"
   },
   {
-    "permalink": "mail-classes",
-    "title": "Class-based mails",
-    "contentPath": "./mail/class_based_mails.md",
-    "category": "Mail"
+    "permalink": "database/lucid",
+    "title": "Lucid",
+    "contentPath": "./database/lucid.md",
+    "category": "Database"
   },
   {
-    "permalink": "fake-mailer",
-    "title": "Fake mailer",
-    "contentPath": "./mail/fake_mailer.md",
-    "category": "Mail"
+    "permalink": "database/redis",
+    "title": "Redis",
+    "contentPath": "./database/redis.md",
+    "category": "Database"
   },
   {
-    "permalink": "mail-custom-transports",
-    "title": "Creating custom transports",
-    "contentPath": "./mail/custom_transports.md",
-    "category": "Mail"
+    "permalink": "authentication/introduction",
+    "title": "Introduction",
+    "contentPath": "./authentication/introduction.md",
+    "category": "Authentication"
   },
   {
-    "permalink": "application",
-    "redirects": ["guides/application"],
-    "title": "Application",
-    "contentPath": "./fundamentals/application.md",
-    "category": "Fundamentals"
+    "permalink": "authentication/verifying-user-credentials",
+    "title": "Verifying user credentials",
+    "contentPath": "./authentication/verifying_user_credentials.md",
+    "category": "Authentication"
   },
   {
-    "permalink": "application-lifecycle",
-    "title": "Application lifecycle",
-    "contentPath": "./fundamentals/application_lifecycle.md",
-    "category": "Fundamentals"
+    "permalink": "authentication/session-guard",
+    "title": "Session guard",
+    "contentPath": "./authentication/session_guard.md",
+    "category": "Authentication"
   },
   {
-    "permalink": "adonisrc-file",
-    "redirects": ["guides/adonis-rcfile"],
-    "title": "AdonisRC file",
-    "contentPath": "./fundamentals/adonisrc_file.md",
-    "category": "Fundamentals"
+    "permalink": "authentication/access-tokens-guard",
+    "title": "Access tokens guard",
+    "contentPath": "./authentication/access_tokens_guard.md",
+    "category": "Authentication"
   },
   {
-    "permalink": "ioc-container",
-    "title": "IoC container",
-    "contentPath": "./fundamentals/ioc_container.md",
-    "category": "Fundamentals"
+    "permalink": "authentication/basic-auth-guard",
+    "title": "Basic auth guard",
+    "contentPath": "./authentication/basic_auth_guard.md",
+    "category": "Authentication"
   },
   {
-    "permalink": "container-services",
-    "title": "Container services",
-    "contentPath": "./fundamentals/container_services.md",
-    "category": "Fundamentals"
+    "permalink": "authentication/custom-auth-guard",
+    "title": "Custom auth guard",
+    "contentPath": "./authentication/custom_auth_guard.md",
+    "category": "Authentication"
   },
   {
-    "permalink": "service-providers",
-    "title": "Service providers",
-    "contentPath": "./fundamentals/service_providers.md",
-    "category": "Fundamentals"
+    "permalink": "authentication/social-authentication",
+    "title": "Social authentication",
+    "contentPath": "./authentication/social_authentication.md",
+    "category": "Authentication"
   },
   {
-    "permalink": "config-providers",
-    "title": "Config providers",
-    "contentPath": "./fundamentals/config_providers.md",
-    "category": "Fundamentals"
+    "permalink": "security/authorization",
+    "title": "Authorization",
+    "contentPath": "./security/authorization.md",
+    "category": "Security"
   },
   {
-    "permalink": "async-local-storage",
-    "title": "Async Local Storage",
-    "contentPath": "./fundamentals/async_local_storage.md",
-    "category": "Fundamentals"
+    "permalink": "security/encryption",
+    "title": "Encryption",
+    "contentPath": "./security/encryption.md",
+    "category": "Security"
   },
   {
-    "permalink": "typescript-build-process",
-    "redirects": ["guides/typescript-build-process"],
-    "title": "TypeScript build process",
-    "contentPath": "./fundamentals/typescript_build_process.md",
-    "category": "Fundamentals"
+    "permalink": "security/hashing",
+    "title": "Hashing",
+    "contentPath": "./security/hashing.md",
+    "category": "Security"
   },
   {
-    "permalink": "hmr",
-    "title": "Hot module replacement (HMR)",
-    "contentPath": "./fundamentals/hmr.md",
-    "category": "Fundamentals"
+    "permalink": "security/cors",
+    "title": "CORS",
+    "contentPath": "./security/cors.md",
+    "category": "Security"
   },
   {
-    "permalink": "extend-adonisjs",
-    "title": "Extending the framework",
-    "contentPath": "./fundamentals/extending_the_framework.md",
-    "category": "Fundamentals"
+    "permalink": "security/securing-ssr-applications",
+    "title": "Securing SSR apps",
+    "contentPath": "./security/securing_ssr_applications.md",
+    "category": "Security"
   },
   {
-    "permalink": "scaffolding",
-    "title": "Scaffolding",
-    "contentPath": "./fundamentals/scaffolding.md",
-    "category": "Fundamentals"
+    "permalink": "security/rate-limiting",
+    "title": "Rate limiting",
+    "contentPath": "./security/rate_limiting.md",
+    "category": "Security"
   },
   {
-    "permalink": "package-development",
-    "draft": true,
-    "title": "Package development",
-    "contentPath": "./fundamentals/package_development.md",
-    "category": "Fundamentals"
+    "permalink": "views-and-templates/introduction",
+    "title": "Introduction",
+    "contentPath": "./views-and-templates/introduction.md",
+    "category": "Views & Templates"
   },
   {
-    "permalink": "tooling-config",
-    "title": "Tooling config",
-    "contentPath": "./fundamentals/tooling_config.md",
-    "category": "Fundamentals"
+    "permalink": "views-and-templates/edgejs",
+    "title": "EdgeJS",
+    "contentPath": "./views-and-templates/edgejs.md",
+    "category": "Views & Templates"
   },
   {
-    "permalink": "authorization",
-    "title": "Authorization",
-    "contentPath": "./digging_deeper/authorization.md",
-    "category": "Digging Deeper"
+    "permalink": "testing/introduction",
+    "title": "Introduction",
+    "contentPath": "./testing/introduction.md",
+    "category": "Testing"
   },
   {
-    "permalink": "emitter",
-    "redirects": ["guides/events"],
-    "title": "Emitter",
-    "contentPath": "./digging_deeper/emitter.md",
-    "category": "Digging Deeper"
+    "permalink": "testing/http-tests",
+    "title": "HTTP tests",
+    "contentPath": "./testing/http_tests.md",
+    "category": "Testing"
   },
   {
-    "permalink": "logger",
-    "title": "Logger",
-    "contentPath": "./digging_deeper/logger.md",
-    "category": "Digging Deeper"
+    "permalink": "testing/browser-tests",
+    "title": "Browser tests",
+    "contentPath": "./testing/browser_tests.md",
+    "category": "Testing"
   },
   {
-    "permalink": "social-auth",
-    "title": "Social authentication",
-    "contentPath": "./digging_deeper/social_auth.md",
-    "category": "Digging Deeper"
+    "permalink": "testing/console-tests",
+    "title": "Console tests",
+    "contentPath": "./testing/console_tests.md",
+    "category": "Testing"
   },
   {
-    "permalink": "i18n",
-    "title": "Internationalization",
-    "contentPath": "./digging_deeper/i18n.md",
-    "category": "Digging Deeper"
+    "permalink": "testing/database",
+    "title": "Database",
+    "contentPath": "./testing/database.md",
+    "category": "Testing"
   },
   {
-    "permalink": "locks",
-    "title": "Atomic Locks",
-    "contentPath": "./digging_deeper/locks.md",
-    "category": "Digging Deeper"
+    "permalink": "testing/mocks-and-fakes",
+    "title": "Mocks & Fakes",
+    "contentPath": "./testing/mocks_and_fakes.md",
+    "category": "Testing"
   },
   {
-    "permalink": "transmit",
-    "title": "Transmit",
-    "contentPath": "./digging_deeper/transmit.md",
-    "category": "Digging Deeper"
+    "permalink": "digging-deeper/emitter",
+    "title": "Emitter",
+    "contentPath": "./digging_deeper/emitter.md",
+    "category": "Digging deeper"
   },
   {
-    "permalink": "testing",
-    "title": "Introduction",
-    "contentPath": "./testing/introduction.md",
-    "category": "Testing"
+    "permalink": "digging-deeper/i18n",
+    "title": "I18n",
+    "contentPath": "./digging_deeper/i18n.md",
+    "category": "Digging deeper"
   },
   {
-    "permalink": "http-tests",
-    "title": "HTTP tests",
-    "contentPath": "./testing/http_tests.md",
-    "category": "Testing"
+    "permalink": "digging-deeper/locks",
+    "title": "Locks",
+    "contentPath": "./digging_deeper/locks.md",
+    "category": "Digging deeper"
   },
   {
-    "permalink": "database-tests",
-    "title": "Database tests",
-    "contentPath": "./testing/database_tests.md",
-    "category": "Testing"
+    "permalink": "digging-deeper/logger",
+    "title": "Logger",
+    "contentPath": "./digging_deeper/logger.md",
+    "category": "Digging deeper"
   },
   {
-    "permalink": "browser-tests",
-    "title": "Browser tests",
-    "contentPath": "./testing/browser_tests.md",
-    "category": "Testing"
+    "permalink": "digging-deeper/mail",
+    "title": "Mail",
+    "contentPath": "./digging_deeper/mail.md",
+    "category": "Digging deeper"
   },
   {
-    "permalink": "command-line-tests",
-    "title": "Command-line tests",
-    "contentPath": "./testing/commandline_tests.md",
-    "category": "Testing"
+    "permalink": "digging-deeper/transmit",
+    "title": "Transmit",
+    "contentPath": "./digging_deeper/transmit.md",
+    "category": "Digging deeper"
   },
   {
-    "permalink": "mocks-and-fakes",
-    "redirects": ["guides/testing/fakes"],
-    "title": "Mocks and fakes",
-    "contentPath": "./testing/mocks_and_fakes.md",
-    "category": "Testing"
+    "permalink": "digging-deeper/repl",
+    "title": "Repl",
+    "contentPath": "./digging_deeper/repl.md",
+    "category": "Digging deeper"
   },
   {
     "permalink": "ace",
     "title": "Introduction",
     "contentPath": "./ace/introduction.md",
-    "category": "Ace command line"
+    "category": "Ace commands"
   },
   {
     "permalink": "ace-creating-commands",
     "title": "Creating commands",
     "contentPath": "./ace/creating_commands.md",
-    "category": "Ace command line"
+    "category": "Ace commands"
   },
   {
     "permalink": "ace-arguments",
     "title": "Command arguments",
     "contentPath": "./ace/args.md",
-    "category": "Ace command line"
+    "category": "Ace commands"
   },
   {
     "permalink": "ace-flags",
     "title": "Command flags",
     "contentPath": "./ace/flags.md",
-    "category": "Ace command line"
+    "category": "Ace commands"
   },
   {
     "permalink": "ace-prompts",
     "title": "Prompts",
     "contentPath": "./ace/prompts.md",
-    "category": "Ace command line"
+    "category": "Ace commands"
   },
   {
     "permalink": "ace-terminal-ui",
     "title": "Terminal UI",
     "contentPath": "./ace/tui.md",
-    "category": "Ace command line"
+    "category": "Ace commands"
   },
   {
-    "permalink": "repl",
-    "title": "REPL",
-    "contentPath": "./ace/repl.md",
-    "category": "Ace command line"
-  },
-  {
-    "permalink": "commands-reference",
+    "permalink": "references/commands",
     "title": "Commands",
-    "contentPath": "./reference/commands.md",
-    "category": "Reference"
+    "contentPath": "./references/commands.md",
+    "category": "References"
   },
   {
-    "permalink": "edge-reference",
+    "permalink": "references/edge",
     "title": "Edge helpers and tags",
-    "contentPath": "./reference/edge.md",
-    "category": "Reference"
+    "contentPath": "./references/edge.md",
+    "category": "References"
   },
   {
-    "permalink": "events-reference",
+    "permalink": "references/events",
     "title": "Events",
-    "contentPath": "./reference/events.md",
-    "category": "Reference"
+    "contentPath": "./references/events.md",
+    "category": "References"
   },
   {
-    "permalink": "exceptions-reference",
+    "permalink": "references/exceptions",
     "title": "Exceptions",
-    "contentPath": "./reference/exceptions.md",
-    "category": "Reference"
+    "contentPath": "./references/exceptions.md",
+    "category": "References"
   },
   {
-    "permalink": "helpers-reference",
+    "permalink": "references/helpers",
     "title": "Helpers",
-    "contentPath": "./reference/helpers.md",
-    "category": "Reference"
+    "contentPath": "./references/helpers.md",
+    "category": "References"
   },
   {
-    "permalink": "experimental-vite",
-    "title": "New Vite Integration",
-    "contentPath": "./experimental/vite.md",
+    "permalink": "experimental-assembler-hooks",
+    "title": "Assembler hooks",
+    "contentPath": "./experimental/assembler_hooks.md",
     "category": "Experimental"
   },
   {
-    "permalink": "experimental-assembler-hooks",
-    "title": "Assembler Hooks",
-    "contentPath": "./experimental/assembler_hooks.md",
+    "permalink": "experimental-vite",
+    "title": "New Vite integration",
+    "contentPath": "./experimental/vite.md",
     "category": "Experimental"
   },
   {
diff --git a/content/docs/digging_deeper/emitter.md b/content/docs/digging_deeper/emitter.md
index 42964434..a18769ae 100644
--- a/content/docs/digging_deeper/emitter.md
+++ b/content/docs/digging_deeper/emitter.md
@@ -33,7 +33,7 @@ Once you have defined the event listener, you can emit the `user:registered` eve
 import emitter from '@adonisjs/core/services/emitter'
 
 export default class UsersController {
-  store() {
+  async store() {
     const user = await User.create(data)
     emitter.emit('user:registered', user)
   }
@@ -77,7 +77,7 @@ declare module '@adonisjs/core/types' {
 
 Like HTTP controllers, listener classes offer an abstraction layer to move inline event listeners inside dedicated files. Listener classes are stored inside the `app/listeners` directory and you may create a new listener using the `make:listener` command.
 
-See also: [Make listener command](../reference/commands.md#makelistener)
+See also: [Make listener command](../references/commands.md#makelistener)
 
 ```sh
 node ace make:listener sendVerificationEmail
@@ -95,7 +95,7 @@ export default class SendVerificationEmail {
 }
 ```
 
-As the final step, you must bind the listener class to an event within the `start/events.ts` file. You may import the listener using the `#listeners` alias. The aliases are defined using the [subpath imports feature of Node.js](../guides/folder_structure.md#the-sub-path-imports).
+As the final step, you must bind the listener class to an event within the `start/events.ts` file. You may import the listener using the `#listeners` alias. The aliases are defined using the [subpath imports feature of Node.js](../getting_started/folder_structure.md#the-sub-path-imports).
 
 ```ts
 // title: start/events.ts
@@ -130,7 +130,7 @@ You cannot inject the `HttpContext` inside a listener class. Because events are
 
 :::
 
-The listener classes are instantiated using the [IoC container](../fundamentals/ioc_container.md); therefore, you can type-hint dependencies inside the class constructor or the method which handles the event.
+The listener classes are instantiated using the [IoC container](../concepts/dependency_injection.md); therefore, you can type-hint dependencies inside the class constructor or the method which handles the event.
 
 In the following example, we type-hint the `TokensService` as a constructor argument. When invoking this listener, the IoC container will inject an instance of the `TokensService` class.
 
@@ -175,7 +175,7 @@ Class-based events encapsulate the event identifier and the event data within th
 
 You may create an event class using the `make:event` command.
 
-See also: [Make event command](../reference/commands.md#makeevent)
+See also: [Make event command](../references/commands.md#makeevent)
 
 ```sh
 node ace make:event UserRegistered
@@ -226,7 +226,7 @@ import User from '#models/user'
 import UserRegistered from '#events/user_registered'
 
 export default class UsersController {
-  store() {
+  async store() {
     const user = await User.create(data)
     
     /**
@@ -335,7 +335,7 @@ emitter.clearAllListeners()
 ```
 
 ## List of available events
-Please check the [events reference guide](../reference/events.md) to view the list of available events.
+Please check the [events reference guide](../references/events.md) to view the list of available events.
 
 ## Faking events during tests
 
diff --git a/content/docs/digging_deeper/i18n.md b/content/docs/digging_deeper/i18n.md
index e7a86109..bbf0e861 100644
--- a/content/docs/digging_deeper/i18n.md
+++ b/content/docs/digging_deeper/i18n.md
@@ -144,8 +144,6 @@ If you do not define this value, we will infer the `supportedLocales` from trans
 
 </dd>
 
-</dd>
-
 <dt>
 
   loaders
@@ -301,11 +299,11 @@ During the initial setup, we create a `detect_user_locale_middleware.ts` file in
 
 - Detect the locale of the request using the [`Accept-language` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).
 
-- Create an instance of the `I18n` class for the request locale and share it with the rest of the request pipeline using the [HTTP Context](../http/http_context.md).
+- Create an instance of the `I18n` class for the request locale and share it with the rest of the request pipeline using the [HTTP Context](../concepts/http_context.md).
 
 - Share the same instance with Edge templates as a global `i18n` property.
 
-- Finally, hook into the [Request validator](../http/validation.md#the-requestvalidateusing-method) and provide validation messages using translation files.
+- Finally, hook into the [Request validator](../basics/validation.md#the-requestvalidateusing-method) and provide validation messages using translation files.
 
 If this middleware is active, you can translate messages inside your controllers and Edge templates as follows.
 
@@ -329,7 +327,7 @@ export default class PostsController {
 Since the `detect_user_locale_middleware` is part of your application codebase, you may modify the `getRequestLocale` method and use custom logic to find the user language.
 
 ## Translating validation messages
-The `detect_user_locale_middleware` hooks into the [Request validator](../http/validation.md#the-requestvalidateusing-method) and provides validation messages using the translation files.
+The `detect_user_locale_middleware` hooks into the [Request validator](../basics/validation.md#the-requestvalidateusing-method) and provides validation messages using the translation files.
 
 ```ts
 export default class DetectUserLocaleMiddleware {
@@ -500,24 +498,24 @@ You have an appointment today at 2:48 PM
 
 ICU provides a [wide array of patterns](https://unicode-org.github.io/icu/userguide/format_parse/datetime/#date-field-symbol-table) to customize the date-time format. However, not all of them are available via ECMA402's Intl API. Therefore, we only support the following patterns.
 
-| Symbol |  Description |
-|------|------------------|
-| `G` | Era designator   |
-| `y` | year   |
-| `M` | month in year  |
-| `L` | stand-alone month in year  |
-| `d` | day in month   |
-| `E` | day of week  |
-| `e` | local day of week e..eee is not supported |
-| `c` | stand-alone local day of week c..ccc is not supported |
-| `a` | AM/PM marker   |
-| `h` | Hour [1-12]  |
-| `H` | Hour [0-23]  |
-| `K` | Hour [0-11]  |
-| `k` | Hour [1-24]  |
-| `m` | Minute   |
-| `s` | Second   |
-| `z` | Time Zone |
+| Symbol | Description                                           |
+|--------|-------------------------------------------------------|
+| `G`    | Era designator                                        |
+| `y`    | year                                                  |
+| `M`    | month in year                                         |
+| `L`    | stand-alone month in year                             |
+| `d`    | day in month                                          |
+| `E`    | day of week                                           |
+| `e`    | local day of week e..eee is not supported             |
+| `c`    | stand-alone local day of week c..ccc is not supported |
+| `a`    | AM/PM marker                                          |
+| `h`    | Hour [1-12]                                           |
+| `H`    | Hour [0-23]                                           |
+| `K`    | Hour [0-11]                                           |
+| `k`    | Hour [1-24]                                           |
+| `m`    | Minute                                                |
+| `s`    | Second                                                |
+| `z`    | Time Zone                                             |
 
 ### Plural rules
 ICU message syntax has first-class support for defining the plural rules within your messages. For example:
@@ -556,15 +554,15 @@ The `#` is a special token to be used as a placeholder for the numeric value. It
 
 The plural rule uses the `{key, plural, matches}` syntax. The `matches` is a literal value matched to one of the following plural categories.
 
-| Category | Description |
-|-----------|------------|
-| `zero` | This category is used for languages with grammar specialized specifically for zero number of items. (Examples are Arabic and Latvian) |
-| `one` | This category is used for languages with grammar explicitly specialized for one item. Many languages, but not all, use this plural category. (Many popular Asian languages, such as Chinese and Japanese, do not use this category.) |
-| `two` | This category is used for languages that have grammar explicitly specialized for two items. (Examples are Arabic and Welsh.) |
-| `few` | This category is used for languages with grammar explicitly specialized for a small number of items. For some languages, this is used for 2-4 items, for some 3-10 items, and other languages have even more complex rules. |
-| `many` | This category is used for languages with specialized grammar for a more significant number of items. (Examples are Arabic, Polish, and Russian.) |
-| `other` | This category is used if the value doesn't match one of the other plural categories. Note that this is used for "plural" for languages (such as English) that have a simple "singular" versus "plural" dichotomy. |
-| `=value` | This is used to match a specific value regardless of the plural categories of the current locale. |
+| Category | Description                                                                                                                                                                                                                          |
+|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `zero`   | This category is used for languages with grammar specialized specifically for zero number of items. (Examples are Arabic and Latvian)                                                                                                |
+| `one`    | This category is used for languages with grammar explicitly specialized for one item. Many languages, but not all, use this plural category. (Many popular Asian languages, such as Chinese and Japanese, do not use this category.) |
+| `two`    | This category is used for languages that have grammar explicitly specialized for two items. (Examples are Arabic and Welsh.)                                                                                                         |
+| `few`    | This category is used for languages with grammar explicitly specialized for a small number of items. For some languages, this is used for 2-4 items, for some 3-10 items, and other languages have even more complex rules.          |
+| `many`   | This category is used for languages with specialized grammar for a more significant number of items. (Examples are Arabic, Polish, and Russian.)                                                                                     |
+| `other`  | This category is used if the value doesn't match one of the other plural categories. Note that this is used for "plural" for languages (such as English) that have a simple "singular" versus "plural" dichotomy.                    |
+| `=value` | This is used to match a specific value regardless of the plural categories of the current locale.                                                                                                                                    |
 
 > *The table's content is referenced from [formatjs.io](https://formatjs.io/docs/core-concepts/icu-syntax/#plural-format)*
 
@@ -612,15 +610,15 @@ It's my 2nd anniversary
 
 The select ordinal format uses the `{key, selectordinal, matches}` syntax. The match is a literal value and is matched to one of the following plural categories.
 
-| Category | Description |
-|------------|------------|
-| `zero` | This category is used for languages with grammar specialized specifically for zero number of items. (Examples are Arabic and Latvian.) |
-| `one` | This category is used for languages with grammar explicitly specialized for one item. Many languages, but not all, use this plural category. (Many popular Asian languages, such as Chinese and Japanese, do not use this category.) |
-| `two` | This category is used for languages that have grammar explicitly specialized for two items. (Examples are Arabic and Welsh.) |
-| `few` | This category is used for languages with grammar explicitly specialized for a small number of items. For some languages, this is used for 2-4 items, for some 3-10 items, and other languages have even more complex rules. |
-| `many` | This category is used for languages with specialized grammar for a larger number of items. (Examples are Arabic, Polish, and Russian.) |
-| `other` | This category is used if the value doesn't match one of the other plural categories. Note that this is used for "plural" for languages (such as English) that have a simple "singular" versus "plural" dichotomy. |
-| `=value` | This is used to match a specific value regardless of the plural categories of the current locale. |
+| Category | Description                                                                                                                                                                                                                          |
+|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `zero`   | This category is used for languages with grammar specialized specifically for zero number of items. (Examples are Arabic and Latvian.)                                                                                               |
+| `one`    | This category is used for languages with grammar explicitly specialized for one item. Many languages, but not all, use this plural category. (Many popular Asian languages, such as Chinese and Japanese, do not use this category.) |
+| `two`    | This category is used for languages that have grammar explicitly specialized for two items. (Examples are Arabic and Welsh.)                                                                                                         |
+| `few`    | This category is used for languages with grammar explicitly specialized for a small number of items. For some languages, this is used for 2-4 items, for some 3-10 items, and other languages have even more complex rules.          |
+| `many`   | This category is used for languages with specialized grammar for a larger number of items. (Examples are Arabic, Polish, and Russian.)                                                                                               |
+| `other`  | This category is used if the value doesn't match one of the other plural categories. Note that this is used for "plural" for languages (such as English) that have a simple "singular" versus "plural" dichotomy.                    |
+| `=value` | This is used to match a specific value regardless of the plural categories of the current locale.                                                                                                                                    |
 
 > *The table's content is referenced from [formatjs.io](https://formatjs.io/docs/core-concepts/icu-syntax/#selectordinal-format)*
 
diff --git a/content/docs/digging_deeper/locks.md b/content/docs/digging_deeper/locks.md
index 58521dcf..68379ddc 100644
--- a/content/docs/digging_deeper/locks.md
+++ b/content/docs/digging_deeper/locks.md
@@ -26,7 +26,7 @@ node ace add @adonisjs/lock
     }
     ```
 
-2. Create the `config/lock.ts` file.
+3. Create the `config/lock.ts` file.
 
 4. Define the following environment variable alongside its validation inside the `start/env.ts` file.
    ```ts
@@ -154,6 +154,8 @@ connectionName
 
 </dt>
 
+<dd>
+
 Reference to the database connection defined within the `config/database.ts` file. If not defined, we will use the default database connection.
 
 </dd>
@@ -328,7 +330,7 @@ export class ProcessOrder {
     /**
      * We are restoring the lock from the serialized version
      */
-    const lock = locks.restoreLock(lock)
+    const handle = locks.restoreLock(lock)
 
     /**
      * Process the order
@@ -338,7 +340,7 @@ export class ProcessOrder {
     /**
      * Release the lock
      */
-    await lock.release()
+    await handle.release()
   }
 }
 ```
diff --git a/content/docs/digging_deeper/logger.md b/content/docs/digging_deeper/logger.md
index a0ca5654..bb21d1ce 100644
--- a/content/docs/digging_deeper/logger.md
+++ b/content/docs/digging_deeper/logger.md
@@ -19,7 +19,7 @@ It is recommended to use the `ctx.logger` property during HTTP requests. The HTT
 import router from '@adonisjs/core/services/router'
 import User from '#models/user'
 
-router.get('/users/:id', ({ logger, params }) => {
+router.get('/users/:id', async ({ logger, params }) => {
   logger.info('Fetching user by id %s', params.id)
   const user = await User.find(params.id)
 })
@@ -465,7 +465,7 @@ redact: {
 ### Using the Secret data type
 An alternative to redaction is to wrap sensitive values inside the Secret class. For example:
 
-See also: [Secret class usage docs](../reference/helpers.md#secret)
+See also: [Secret class usage docs](../references/helpers.md#secret)
 
 ```ts
 import { Secret } from '@adonisjs/core/helpers'
diff --git a/content/docs/digging_deeper/mail.md b/content/docs/digging_deeper/mail.md
new file mode 100644
index 00000000..0da62b8b
--- /dev/null
+++ b/content/docs/digging_deeper/mail.md
@@ -0,0 +1,1426 @@
+# Mail
+
+You can send emails from your AdonisJS application using the `@adonisjs/mail` package. The mail package is built on top of [Nodemailer](https://nodemailer.com/), bringing the following quality of life improvements over Nodemailer.
+
+- Fluent API to configure mail messages.
+- Ability to define emails as classes for better organization and easier testing.
+- An extensive suite of officially maintained transports. It includes `smtp`, `ses`, `mailgun`, `sparkpost`, `resend`, and `brevo`.
+- Improved testing experience using the Fakes API.
+- Mail messenger to queue emails.
+- Functional APIs to generate calendar events.
+
+## Installation
+
+Install and configure the package using the following command :
+
+```sh
+node ace add @adonisjs/mail
+
+# Pre-define transports to use via CLI flag
+node ace add @adonisjs/mail --transports=resend --transports=smtp
+```
+
+:::disclosure{title="See steps performed by the add command"}
+
+1. Installs the `@adonisjs/mail` package using the detected package manager.
+
+2. Registers the following service provider and command inside the `adonisrc.ts` file.
+
+    ```ts
+    {
+      commands: [
+        // ...other commands
+        () => import('@adonisjs/mail/commands')
+      ],
+      providers: [
+        // ...other providers
+        () => import('@adonisjs/mail/mail_provider')
+      ]
+    }
+    ```
+3. Create the `config/mail.ts` file.
+
+4. Defines the environment variables and their validations for the selected mail services
+
+:::
+
+
+## Configuration
+
+The configuration for the mail package is stored inside the `config/mail.ts` file. Inside this file, you may configure multiple email services as `mailers` to use them within your application.
+
+See also: [Config stub](https://github.com/adonisjs/mail/blob/main/stubs/config/mail.stub)
+
+```ts
+import env from '#start/env'
+import { defineConfig, transports } from '@adonisjs/mail'
+
+const mailConfig = defineConfig({
+  default: 'smtp',
+  
+  /**
+   * A static address for the "from" property. It will be
+   * used unless an explicit from address is set on the
+   * Email
+   */
+  from: {
+    address: '',
+    name: '',
+  },
+  
+  /**
+   * A static address for the "reply-to" property. It will be
+   * used unless an explicit replyTo address is set on the
+   * Email
+   */
+  replyTo: {
+    address: '',
+    name: '',
+  },
+
+  /**
+   * The mailers object can be used to configure multiple mailers
+   * each using a different transport or the same transport with a different
+   * options.
+   */
+  mailers: {
+    smtp: transports.smtp({
+      host: env.get('SMTP_HOST'),
+      port: env.get('SMTP_PORT'),
+    }),
+
+    resend: transports.resend({
+      key: env.get('RESEND_API_KEY'),
+      baseUrl: 'https://api.resend.com',
+    }),
+  },
+})
+```
+
+<dl>
+
+<dt>
+
+default
+
+</dt>
+
+<dd>
+
+The name of the mailer to use by default for sending emails.
+
+</dd>
+
+<dt>
+
+from
+
+</dt>
+
+<dd>
+
+A static global address to use for the `from` property. The global address will be used unless an explicit `from` address is defined on the email.
+
+</dd>
+
+<dt>
+
+replyTo
+
+</dt>
+
+<dd>
+
+A static global address to use for the `reply-to` property. The global address will be used unless an explicit `replyTo` address is defined on the email.
+
+</dd>
+
+<dt>
+
+mailers
+
+</dt>
+
+<dd>
+
+The `mailers` object is used to configure one or more mailers you want to use for sending emails. You can switch between the mailers at runtime using the `mail.use` method.
+
+</dd>
+
+</dl>
+
+## Transports config
+Following is a complete reference of configuration options accepted by the officially supported transports.
+
+See also: [TypeScript types for config object](https://github.com/adonisjs/mail/blob/main/src/types.ts#L261)
+
+<div class="disclosure_wrapper">
+
+:::disclosure{title="Mailgun config"}
+<br />
+
+The following configuration options are sent to the Mailgun's [`/messages.mime`](https://documentation.mailgun.com/en/latest/api-sending.html#sending) API endpoint.
+
+```ts
+{
+  mailers: {
+    mailgun: transports.mailgun({
+      baseUrl: 'https://api.mailgun.net/v3',
+      key: env.get('MAILGUN_API_KEY'),
+      domain: env.get('MAILGUN_DOMAIN'),
+
+      /**
+       * The following options can be overridden at
+       * runtime when calling the `mail.send` method.
+       */
+      oDkim: true,
+      oTags: ['transactional', 'adonisjs_app'],
+      oDeliverytime: new Date(2024, 8, 18),
+      oTestMode: false,
+      oTracking: false,
+      oTrackingClick: false,
+      oTrackingOpens: false,
+      headers: {
+        // h:prefixed headers
+      },
+      variables: {
+        appId: '',
+        userId: '',
+        // v:prefixed variables
+      }
+    })
+  }
+}
+```
+
+:::
+
+:::disclosure{title="SMTP config"}
+<br />
+
+The following configuration options are forwarded to Nodemailer as it is. So please check the [Nodemailer documentation](https://nodemailer.com/smtp/) as well.
+
+```ts
+{
+  mailers: {
+    smtp: transports.smtp({
+      host: env.get('SMTP_HOST'),
+      port: env.get('SMTP_PORT'),
+      secure: false,
+
+      auth: {
+        type: 'login',
+        user: env.get('SMTP_USERNAME'),
+        pass: env.get('SMTP_PASSWORD')
+      },
+
+      tls: {},
+
+      ignoreTLS: false,
+      requireTLS: false,
+
+      pool: false,
+      maxConnections: 5,
+      maxMessages: 100,
+    })
+  }
+}
+```
+
+:::
+
+:::disclosure{title="SES config"}
+<br />
+
+The following configuration options are forwarded to Nodemailer as it is. So please check the [Nodemailer documentation](https://nodemailer.com/transports/ses/) as well.
+
+Make sure to install the `@aws-sdk/client-ses` package to use the SES transport.
+
+```ts
+{
+  mailers: {
+    ses: transports.ses({
+      /**
+       * Forwarded to aws sdk
+       */
+      apiVersion: '2010-12-01',
+      region: 'us-east-1',
+      credentials: {
+        accessKeyId: env.get('AWS_ACCESS_KEY_ID'),
+        secretAccessKey: env.get('AWS_SECRET_ACCESS_KEY'),
+      },
+
+      /**
+       * Nodemailer specific
+       */
+      sendingRate: 10,
+      maxConnections: 5,
+    })
+  }
+}
+```
+
+:::
+
+:::disclosure{title="SparkPost config"}
+
+<br />
+
+The following configuration options are sent to the SparkPost's [`/transmissions`](https://developers.sparkpost.com/api/transmissions/#header-request-body) API endpoint.
+
+```ts
+{
+  mailers: {
+    sparkpost: transports.sparkpost({
+      baseUrl: 'https://api.sparkpost.com/api/v1',
+      key: env.get('SPARKPOST_API_KEY'),
+
+      /**
+       * The following options can be overridden at
+       * runtime when calling the `mail.send` method.
+       */
+      startTime: new Date(),
+      openTracking: false,
+      clickTracking: false,
+      initialOpen: false,
+      transactional: true,
+      sandbox: false,
+      skipSuppression: false,
+      ipPool: '',
+    })
+  }
+}
+```
+
+:::
+
+:::disclosure{title="Resend config"}
+<br />
+
+The following configuration options are sent to the Resend's [`/emails`](https://resend.com/docs/api-reference/emails/send-email) API endpoint.
+
+```ts
+{
+  mailers: {
+    resend: transports.resend({
+      baseUrl: 'https://api.resend.com',
+      key: env.get('RESEND_API_KEY'),
+
+      /**
+       * The following options can be overridden at
+       * runtime when calling the `mail.send` method.
+       */
+      tags: [
+        {
+          name: 'category',
+          value: 'confirm_email'
+        }
+      ]
+    })
+  }
+}
+```
+:::
+
+</div>
+
+## Basic example
+
+Once the initial configuration is completed, you may send emails using the `mail.send` method. The mail service is a singleton instance of the [MailManager](https://github.com/adonisjs/mail/blob/main/src/mail_manager.ts) class created using the config file.
+
+The `mail.send` method passes an instance of the [Message](https://github.com/adonisjs/mail/blob/main/src/message.ts) class to the callback and delivers the email using the `default` mailer configured inside the config file.
+
+In the following example, we trigger an email from the controller after creating a new user account.
+
+```ts
+import User from '#models/user'
+import { HttpContext } from '@adonisjs/core/http'
+// highlight-start
+import mail from '@adonisjs/mail/services/main'
+// highlight-end
+
+export default class UsersController {
+  async store({ request }: HttpContext) {
+    /**
+     * For demonstration only. You should validate the data
+     * before storing it inside the database.
+     */
+    const user = await User.create(request.all())
+
+    // highlight-start
+    await mail.send((message) => {
+      message
+        .to(user.email)
+        .from('info@example.org')
+        .subject('Verify your email address')
+        .htmlView('emails/verify_email', { user })
+    })
+    // highlight-end
+  }
+}
+```
+
+## Queueing emails
+Since sending emails can be time-consuming, you might want to push them to a queue and send emails in the background. You can do the same using the `mail.sendLater` method.
+
+The `sendLater` method accepts the same parameters as the `send` method. However, instead of sending the email immediately, it will use the **Mail messenger** to queue it.
+
+```ts
+// delete-start
+await mail.send((message) => {
+// delete-end
+// insert-start
+await mail.sendLater((message) => {
+// insert-end
+  message
+    .to(user.email)
+    .from('info@example.org')
+    .subject('Verify your email address')
+    .htmlView('emails/verify_email', { user })
+})
+```
+
+By default, the **mail messenger uses an in-memory queue**, meaning the queue will drop the jobs if your process dies with pending jobs. This might not be a huge deal if your application UI allows re-sending emails with manual actions. However, you can always configure a custom messenger and use a database-backed queue.
+
+### Using bullmq for queueing emails
+
+```sh
+npm i bullmq
+```
+
+In the following example, we use the `mail.setMessenger` method to configure a custom queue that uses `bullmq` under the hood for storing jobs.
+
+We store the compiled email, runtime configuration, and the mailer name inside the job. Later, we will use this data to send emails inside a worker process.
+
+```ts
+import { Queue } from 'bullmq'
+import mail from '@adonisjs/mail/services/main'
+
+// highlight-start
+const emailsQueue = new Queue('emails')
+// highlight-end
+
+// highlight-start
+mail.setMessenger((mailer) => {
+  return {
+    async queue(mailMessage, config) {
+      await emailsQueue.add('send_email', {
+        mailMessage,
+        config,
+        mailerName: mailer.name,
+      })
+    }
+  }
+})
+// highlight-end
+```
+
+Finally, let's write the code for the queue Worker. Depending on your application workflow, you may have to start another process for the workers to process the jobs.
+
+In the following example:
+
+- We process jobs named `send_email` from the `emails` queue.
+- Access compiled mail message, runtime config, and the mailer name from the job data.
+- And send the email using the `mailer.sendCompiled` method.
+
+```ts
+import { Worker } from 'bullmq'
+import mail from '@adonisjs/mail/services/main'
+
+new Worker('emails', async (job) => {
+  if (job.name === 'send_email') {
+    const {
+      mailMessage,
+      config,
+      mailerName
+    } = job.data
+
+    await mail
+      .use(mailerName)
+      .sendCompiled(mailMessage, config)
+  }
+})
+```
+
+That's all! You may continue using the `mail.sendLater` method. However, the emails will be queued inside a redis database this time.
+
+## Switching between mailers
+You may switch between the configured mailers using the `mail.use` method. The `mail.use` method accepts the name of the mailer (as defined inside the config file) and returns an instance of the [Mailer](https://github.com/adonisjs/mail/blob/main/src/mailer.ts) class.
+
+```ts
+import mail from '@adonisjs/mail/services/main'
+
+mail.use() // Instance of default mailer
+mail.use('mailgun') // Mailgun mailer instance
+```
+
+You may call the `mailer.send` or `mailer.sendLater` methods to send email using a mailer instance. For example:
+
+```ts
+await mail
+  .use('mailgun')
+  .send((message) => {
+  })
+```
+
+```ts
+await mail
+  .use('mailgun')
+  .sendLater((message) => {
+  })
+```
+
+The mailer instances are cached for the lifecycle of the process. You may use the `mail.close` method to destroy an existing instance and re-create a new instance from scratch.
+
+```ts
+import mail from '@adonisjs/mail/services/main'
+
+/**
+ * Close transport and remove instance from
+ * cache
+ */
+await mail.close('mailgun')
+
+/**
+ * Create a fresh instance
+ */
+mail.use('mailgun')
+```
+
+## Configuring the template engine
+By default, the mail package is configured to use the [Edge template engine](../views-and-templates/introduction.md#configuring-edge) for defining the email **HTML** and **Plain text** contents.§
+
+However, as shown in the following example, you may also register a custom template engine by overriding the `Message.templateEngine` property.
+
+See also: [Defining email contents](#defining-email-contents)
+
+```ts
+import { Message } from '@adonisjs/mail'
+
+Message.templateEngine = {
+  async render(templatePath, data) {
+    return someTemplateEngine.render(templatePath, data)
+  }
+}
+```
+
+## Events
+Please check the [events reference guide](../references/events.md#mailsending) to view the list of events dispatched by the `@adonisjs/mail` package.
+
+## Configuring message
+
+The properties of an email are defined using the [Message](https://github.com/adonisjs/mail/blob/main/src/message.ts) class. An instance of this class is provided to the callback function created using the `mail.send`, or `mail.sendLater` methods.
+
+```ts
+import { Message } from '@adonisjs/mail'
+import mail from '@adonisjs/mail/services/main'
+
+await mail.send((message) => {
+  // highlight-start
+  console.log(message instanceof Message) // true
+  // highlight-end
+})
+
+await mail.sendLater((message) => {
+  // highlight-start
+  console.log(message instanceof Message) // true
+  // highlight-end
+})
+```
+
+### Defining subject and sender
+You may define the email subject using the `message.subject` method and the email's sender using the `message.from` method.
+
+```ts
+await mail.send((message) => {
+  message
+  // highlight-start
+    .subject('Verify your email address')
+    .from('info@example.org')
+  // highlight-end
+})
+```
+
+The `from` method accepts the email address as a string or an object with the sender name and the email address.
+
+```ts
+message
+  .from({
+    address: 'info@example.com',
+    name: 'AdonisJS'
+  })
+```
+
+The sender can also be defined globally within the config file. The global sender will be used if no explicit sender is defined for an individual message.
+
+```ts
+const mailConfig = defineConfig({
+  from: {
+    address: 'info@example.com',
+    name: 'AdonisJS'
+  }
+})
+```
+
+### Defining recipients
+You may define the email recipients using the `message.to`, `message.cc`, and the `message.bcc` methods. These methods accept the email address as a string or an object with the recipient name and the email address.
+
+```ts
+await mail.send((message) => {
+  message
+    .to(user.email)
+    .cc(user.team.email)
+    .bcc(user.team.admin.email)
+})
+```
+
+```ts
+await mail.send((message) => {
+  message
+    .to({
+      address: user.email,
+      name: user.fullName,
+    })
+    .cc({
+      address: user.team.email,
+      name: user.team.name,
+    })
+    .bcc({
+      address: user.team.admin.email,
+      name: user.team.admin.fullName,
+    })
+})
+```
+
+You can define multiple `cc` and `bcc` recipients as an array of email addresses or an object with email addresses and the recipient name.
+
+```ts
+await mail.send((message) => {
+  message
+    .cc(['first@example.com', 'second@example.com'])
+    .bcc([
+      {
+        name: 'First recipient',
+        address: 'first@example.com'
+      },
+      {
+        name: 'Second recipient',
+        address: 'second@example.com'
+      }
+    ])
+})
+```
+
+You may also define the `replyTo` email address using the `message.replyTo` method.
+
+```ts
+await mail.send((message) => {
+  message
+    .from('info@example.org')
+    // highlight-start
+    .replyTo('noreply@example.org')
+    // highlight-end
+})
+```
+
+### Defining email contents
+You may define the **HTML** and **Plain text** contents for an email using `message.html` or `message.text` methods.
+
+```ts
+await mail.send((message) => {
+  /**
+   * HTML contents
+   */
+  message.html(`
+    <h1> Verify email address </h1>
+    <p> <a href="https://myapp.com">Click here</a> to verify your email address </a>
+  `)
+
+  /**
+   * Plain text contents
+   */
+  message.text(`
+    Verify email address
+    Please visit https://myapp.com to verify your email address
+  `)
+})
+```
+
+#### Using Edge templates
+
+Since writing inline content could be cumbersome, you may use Edge templates instead. If you have already [configured Edge](../views-and-templates/introduction.md#configuring-edge), you may use the `message.htmlView` and `message.textView` methods to render templates.
+
+```sh
+// title: Create templates
+node ace make:view emails/verify_email_html
+node ace make:view emails/verify_email_text
+```
+
+```ts
+// title: Use them for defining contents
+await mail.send((message) => {
+  message.htmlView('emails/verify_email_html', stateToShare)
+  message.textView('emails/verify_email_text', stateToShare)
+})
+```
+
+#### Using MJML for email markup
+MJML is a markup language for creating emails without writing all the complex HTML to make your emails look good in every email client.
+
+The first step is to install the [mjml](https://npmjs.com/mjml) package from npm.
+
+```sh
+npm i mjml
+```
+
+Once done, you can write MJML markup inside your Edge templates by wrapping it inside the `@mjml` tag.
+
+:::note
+
+Since the output of MJML contains the `html`, `head`, and `body` tags, it is unnecessary to define them within your Edge templates.
+
+:::
+
+```edge
+@mjml()
+  <mjml>
+    <mj-body>
+      <mj-section>
+        <mj-column>
+          <mj-text>
+            Hello World!
+          </mj-text>
+        </mj-column>
+      </mj-section>
+    </mj-body>
+  </mjml>
+@end
+```
+
+You may pass the [MJML configuration options](https://documentation.mjml.io/#inside-node-js) as props to the `@mjml` tag.
+
+```edge
+@mjml({
+  keepComments: false,
+  fonts: {
+    Lato: 'https://fonts.googleapis.com/css?family=Lato:400,500,700'
+  }
+})
+```
+
+### Attaching files
+You may use the `message.attach` method to send attachments in an email. The `attach` method accepts an absolute path or a file system URL of a file you want to send as an attachment.
+
+```ts
+import app from '@adonisjs/core/services/app'
+
+await mail.send((message) => {
+  message.attach(app.makePath('uploads/invoice.pdf'))
+})
+```
+
+You may define the filename for the attachment using the `options.filename` property.
+
+```ts
+message.attach(app.makePath('uploads/invoice.pdf'), {
+  filename: 'invoice_october_2023.pdf'
+})
+```
+
+The complete list of options accepted by the `message.attach` method follows.
+
+<table>
+<thead>
+<tr>
+<th>Option</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>filename</code></td>
+<td>The display name for the attachment. Defaults to the basename of the attachment path.</td>
+</tr>
+<tr>
+<td><code>contentType</code></td>
+<td>The content type for the attachment. If not set, the <code>contentType</code> will be inferred from the file extension.</td>
+</tr>
+<tr>
+<td><code>contentDisposition</code></td>
+<td>Content disposition type for the attachment. Defaults to <code>attachment</code></td>
+</tr>
+<tr>
+<td><code>headers</code></td>
+<td>
+<p>Custom headers for the attachment node. The headers property is a key-value pair</p>
+</td>
+</tr>
+</tbody></table>
+
+#### Attaching files from streams and buffers
+You may create email attachments from streams and buffers using the `message.attachData` method. The method accepts a readable stream or the buffer as the first argument and the options object as the second argument.
+
+:::note
+
+The `message.attachData` method should not be used when queueing emails using the `mail.sendLater` method. Since queued jobs are serialized and persisted inside a database, attaching raw data will increase the storage size.
+
+Moreover, queueing an email will fail if you attach a stream using the `message.attachData` method.
+:::
+
+```ts
+message.attach(fs.createReadStream('./invoice.pdf'), {
+  filename: 'invoice_october_2023.pdf'
+})
+```
+
+```ts
+message.attach(Buffer.from('aGVsbG8gd29ybGQh'), {
+  encoding: 'base64',
+  filename: 'greeting.txt',
+})
+```
+
+### Embedding images
+You may embed images within the contents of your email using the `embedImage` view helper. The `embedImage` method under the hood uses [CID](https://sendgrid.com/en-us/blog/embedding-images-emails-facts#1-cid-embedded-images-inline-images) to mark the image as an attachment and uses its content id as the source of the image.
+
+```edge
+<img src="{{
+  embedImage(app.makePath('assets/hero.jpg'))
+}}" />
+```
+
+Following will be the output HTML
+
+```html
+<img src="cid:a-random-content-id" />
+```
+
+The following attachment will be defined automatically on the email payload.
+
+```ts
+{
+  attachments: [{
+    path: '/root/app/assets/hero.jpg',
+    filename: 'hero.jpg',
+    cid: 'a-random-content-id'
+  }]
+}
+```
+
+#### Embedding images from buffers
+
+Like the `embedImage` method, you may use the `embedImageData` method to embed an image from raw data.
+
+```edge
+<img src="{{
+  embedImageData(rawBuffer, { filename: 'hero.jpg' })
+}}" />
+```
+
+### Attaching calendar events
+You may attach calendar events to an email using the `message.icalEvent` method. The `icalEvent` method accepts the event contents as the first parameter and the `options` object as the second parameter.
+
+```ts
+const contents = 'BEGIN:VCALENDAR\r\nPRODID:-//ACME/DesktopCalendar//EN\r\nMETHOD:REQUEST\r\n...'
+
+await mail.send((message) => {
+  message.icalEvent(contents, {
+    method: 'PUBLISH',
+    filename: 'invite.ics',
+  })
+})
+```
+
+Since defining the event file contents manually can be cumbersome, you may pass a callback function to the `icalEvent` method and generate the invite contents using JavaScript API.
+
+The `calendar` object provided to the callback function is a reference of the [ical-generator](https://www.npmjs.com/package/ical-generator) npm package, so make sure to go through the package's README file as well.
+
+```ts
+message.icalEvent((calendar) => {
+  // highlight-start
+  calendar
+    .createEvent({
+      summary: 'Adding support for ALS',
+      start: DateTime.local().plus({ minutes: 30 }),
+      end: DateTime.local().plus({ minutes: 60 }),
+    })
+  // highlight-end
+}, {
+  method: 'PUBLISH',
+  filename: 'invite.ics',
+})
+```
+
+#### Reading invite contents from a file or a URL
+You may define the invite contents from a file or an HTTP URL using the `icalEventFromFile` or `icalEventFromUrl` methods.
+
+```ts
+message.icalEventFromFile(
+  app.resourcesPath('calendar-invites/invite.ics'),
+  {
+    filename: 'invite.ics',
+    method: 'PUBLISH'
+  }
+)
+```
+
+```ts
+message.icalEventFromFile(
+  'https://myapp.com/users/1/invite.ics',
+  {
+    filename: 'invite.ics',
+    method: 'PUBLISH'
+  }
+)
+```
+
+### Defining email headers
+You may define additional email headers using the `message.header` method. The method accepts the header key as the first parameter and the value as the second parameter.
+
+```ts
+message.header('x-my-key', 'header value')
+
+/**
+ * Define an array of values
+ */
+message.header('x-my-key', ['header value', 'another value'])
+```
+
+By default, the email headers are encoded and folded to meet the requirement of having plain ASCII messages with lines no longer than 78 bytes. However, if you want to bypass the encoding rules, you may set a header using the `message.preparedHeader` method.
+
+```ts
+message.preparedHeader(
+  'x-unprocessed',
+  'a really long header or value with non-ascii characters 👮',
+)
+```
+
+### Defining `List` headers
+The message class includes helper methods to define complex headers like [List-Unsubscribe](https://sendgrid.com/en-us/blog/list-unsubscribe) or [List-Help](https://support.optimizely.com/hc/en-us/articles/4413200569997-Setting-up-the-List-Help-header#heading-2) with ease. You can learn about the encoding rules for `List` headers on the [nodemailer website](https://nodemailer.com/message/list-headers/).
+
+```ts
+message.listHelp('admin@example.com?subject=help')
+// List-Help: <mailto:admin@example.com?subject=help>
+```
+
+```ts
+message.listUnsubscribe({
+  url: 'http://example.com',
+  comment: 'Comment'
+})
+// List-Unsubscribe: <http://example.com> (Comment)
+```
+
+```ts
+/**
+ * Repeating header multiple times
+ */
+message.listSubscribe('admin@example.com?subject=subscribe')
+message.listSubscribe({
+  url: 'http://example.com',
+  comment: 'Subscribe'
+})
+// List-Subscribe: <mailto:admin@example.com?subject=subscribe>
+// List-Subscribe: <http://example.com> (Subscribe)
+```
+
+For all other arbitrary `List` headers, you may use the `addListHeader` method.
+
+```ts
+message.addListHeader('post', 'http://example.com/post')
+// List-Post: <http://example.com/post>
+```
+
+## Class-based emails
+
+Instead of writing emails inside the `mail.send` method closure, you may move them to dedicated mail classes for better organization and [easier testing](#testing-mail-classes).
+
+The mail classes are stored inside the `./app/mails` directory, and each file represents a single email. You may create a mail class by running the `make:mail` ace command.
+
+See also: [Make mail command](../references/commands.md#makemail)
+
+```sh
+node ace make:mail verify_email
+```
+
+The mail class extends the [BaseMail](https://github.com/adonisjs/mail/blob/main/src/base_mail.ts) class and is scaffolded with following properties and methods. You may configure the mail message inside the `prepare` method using the `this.message` property.
+
+```ts
+import User from '#models/user'
+import { BaseMail } from '@adonisjs/mail'
+
+export default class VerifyEmailNotification extends BaseMail {
+  from = 'sender_email@example.org'
+  subject = 'Verify email'
+
+  prepare() {
+    this.message.to('user_email@example.org')
+  }
+}
+```
+
+<dl>
+
+<dt>
+
+from
+
+</dt>
+
+<dd>
+
+Configure the sender's email address. If you omit this property, you must call the `message.from` method to define the sender.
+
+</dd>
+
+<dt>
+
+subject
+
+</dt>
+
+<dd>
+
+Configure the email subject. If you omit this property, you must use the `message.subject` method to define the email subject.
+
+</dd>
+
+<dt>
+
+replyTo
+
+</dt>
+
+<dd>
+
+Configure the `replyTo` email address.
+
+</dd>
+
+<dt>
+
+prepare
+
+</dt>
+
+<dd>
+
+The `prepare` method is called automatically by the `build` method to prepare the mail message for sending.
+
+You must define the email contents, attachments, recipients, etc, within this method.
+
+</dd>
+
+<dt>
+
+build :span[Inherited]{class="badge"}
+
+</dt>
+
+<dd>
+
+The `build` method is inherited from the `BaseMail` class. The method is called automatically at the time of sending the email.
+
+Make sure to reference the [original implementation](https://github.com/adonisjs/mail/blob/main/src/base_mail.ts#L81) if you decide to override this method.
+
+</dd>
+
+</dl>
+
+### Sending email using the mail class
+You may call the `mail.send` method and pass it an instance of the mail class to send the email. For example:
+
+```ts
+// title: Send mail
+import mail from '@adonisjs/mail/services/main'
+import VerifyEmailNotification from '#mails/verify_email'
+
+await mail.send(new VerifyEmailNotification())
+```
+
+```ts
+// title: Queue mail
+import mail from '@adonisjs/mail/services/main'
+import VerifyEmailNotification from '#mails/verify_email'
+
+await mail.sendLater(new VerifyEmailNotification())
+```
+
+You may share data with the mail class using constructor arguments. For example:
+
+```ts
+/**
+ * Creating a user
+ */
+const user = await User.create(payload)
+
+await mail.send(
+  /**
+   * Passing user to the mail class
+   */
+  new VerifyEmailNotification(user)
+)
+```
+
+### Testing mail classes
+
+One of the primary benefits of using [Mail classes](#class-based-emails) is a better testing experience. You can build mail classes without sending them and write assertions for the message properties.
+
+```ts
+import { test } from '@japa/runner'
+import VerifyEmailNotification from '#mails/verify_email'
+
+test.group('Verify email notification', () => {
+  test('prepare email for sending', async () => {
+    const email = new VerifyEmailNotification()
+
+    /**
+     * Build email message and render templates to
+     * compute the email HTML and plain text
+     * contents
+     */
+    await email.buildWithContents()
+    
+    /**
+     * Write assertions to ensure the message is built
+     * as expected
+     */
+    email.message.assertTo('user@example.org')
+    email.message.assertFrom('info@example.org')
+    email.message.assertSubject('Verify email address')
+    email.message.assertReplyTo('no-reply@example.org')
+  })
+})
+```
+
+You may write assertions for the message contents as follows.
+
+```ts
+const email = new VerifyEmailNotification()
+await email.buildWithContents()
+
+// highlight-start
+email.message.assertHtmlIncludes(
+  `<a href="/emails/1/verify"> Verify email address </a>`
+)
+email.message.assertTextIncludes('Verify email address')
+// highlight-end
+```
+
+Also, you may write assertions for the attachments. The assertions only work with file-based attachments and not for streams or raw content.
+
+```ts
+const email = new VerifyEmailNotification()
+await email.buildWithContents()
+
+// highlight-start
+email.message.assertAttachment(
+  app.makePath('uploads/invoice.pdf')
+)
+// highlight-end
+```
+
+Feel free to look at the [Message](https://github.com/adonisjs/mail/blob/main/src/message.ts) class source code for all the available assertion methods.
+
+## Fake mailer
+You may want to use the Fake mailer during testing to prevent your application from sending emails. The Fake mailer collects all outgoing emails within memory and offers an easy-to-use API for writing assertions against them.
+
+In the following example:
+
+- We start by creating an instance of the [FakeMailer](https://github.com/adonisjs/mail/blob/main/src/fake_mailer.ts) using the `mail.fake` method.
+- Next, we call the `/register` endpoint API.
+- Finally, we use the `mails` property from the fake mailer to assert the `VerifyEmailNotification` was sent.
+
+```ts
+import { test } from '@japa/runner'
+import mail from '@adonisjs/mail/services/main'
+import VerifyEmailNotification from '#mails/verify_email'
+
+test.group('Users | register', () => {
+  test('create a new user account', async ({ client, route }) => {
+    // highlight-start
+    /**
+     * Turn on the fake mode
+     */
+    const { mails } = mail.fake()
+    // highlight-end
+    
+    /**
+     * Make an API call
+     */
+    await client
+      .post(route('users.store'))
+      .send(userData)
+      
+    // highlight-start
+    /**
+     * Assert the controller indeed sent the
+     * VerifyEmailNotification mail
+     */
+    mails.assertSent(VerifyEmailNotification, ({ message }) => {
+      return message
+        .hasTo(userData.email)
+        .hasSubject('Verify email address')
+    })
+    // highlight-end
+  })
+})
+```
+
+Once you are done writing the test, you must restore the fake using the `mail.restore` method.
+
+```ts
+test('create a new user account', async ({ client, route, cleanup }) => {
+  const { mails } = mail.fake()
+  
+  /**
+   * The cleanup hooks are executed after the test
+   * finishes successfully or with an error.
+   */
+  cleanup(() => {
+    mail.restore()
+  })
+})
+```
+
+### Writing assertions
+
+The `mails.assertSent` method accepts the mail class constructor as the first argument and throws an exception when unable to find any emails for the expected class.
+
+```ts
+const { mails } = mail.fake()
+
+/**
+ * Asser the email was sent
+ */
+mails.assertSent(VerifyEmailNotification)
+```
+
+You may pass a callback function to the `assertSent` method to further check if the email was sent to the expected recipient or has correct subject.
+
+The callback function receives an instance of the mail class and you can use the `.message` property to get access to the [message](#configuring-message) object.
+
+```ts
+mails.assertSent(VerifyEmailNotification, (email) => {
+  return email.message
+    .hasTo(userData.email)
+    .hasFrom('info@example.org')
+    .hasSubject('Verify your email address')
+})
+```
+
+You may run assertions on the `message` object within the callback. For example:
+
+```ts
+mails.assertSent(VerifyEmailNotification, (email) => {
+  email.message.assertHasTo(userData.email)
+  email.message.assertHasFrom('info@example.org')
+  email.message.assertHasSubject('Verify your email address')
+
+  /**
+   * All assertions passed, so return true to consider the
+   * email as sent.
+   */
+  return true
+})
+```
+
+#### Assert email was not sent
+
+You may use the `mails.assertNotSent` method to assert an email was not sent during the test. This method is the opposite of the `assertSent` method and accepts the same arguments.
+
+```ts
+const { mails } = mail.fake()
+
+mails.assertNotSent(PasswordResetNotification)
+```
+
+#### Assert emails count
+
+Finally, you can assert the count of sent emails using the `assertSentCount` and `assertNoneSent` methods.
+
+```ts
+const { mails } = mail.fake()
+
+// Assert 2 emails were sent in total
+mails.assertSentCount(2)
+
+// Assert only one VerifyEmailNotification was sent
+mails.assertSentCount(VerifyEmailNotification, 1)
+```
+
+```ts
+const { mails } = mail.fake()
+
+// Assert zero emails were sent
+mails.assertNoneSent()
+```
+
+### Writing assertions for queued emails
+
+If you have queued emails using the `mail.sendLater` method, you may use the following methods to write assertions for them.
+
+```ts
+const { mails } = mail.fake()
+
+/**
+ * Assert "VerifyEmailNotification" email was queued
+ * Optionally, you may pass the finder function to
+ * narrow down the email
+ */
+mails.assertQueued(VerifyEmailNotification)
+
+/**
+ * Assert "VerifyEmailNotification" email was not queued
+ * Optionally, you may pass the finder function to
+ * narrow down the email
+ */
+mails.assertNotQueued(PasswordResetNotification)
+
+/**
+ * Assert two emails were queued in total.
+ */
+mails.assertQueuedCount(2)
+
+/**
+ * Assert "VerifyEmailNotification" email was queued
+ * only once
+ */
+mails.assertQueuedCount(VerifyEmailNotification , 1)
+
+/**
+ * Assert nothing was queued
+ */
+mails.assertNoneQueued()
+```
+
+### Getting a list of sent or queued emails
+
+You may use the `mails.sent` or `mails.queued` methods to get an array of emails sent/queued during tests.
+
+```ts
+const { mails } = mail.fake()
+
+const sentEmails = mails.sent()
+const queuedEmails = mails.queued()
+
+const email = sentEmails.find((email) => {
+  return email instanceof VerifyEmailNotification
+})
+
+if (email) {
+  email.message.assertTo(userData.email)
+  email.message.assertFrom(userData.email)
+  email.message.assertHtmlIncludes('<a href="/verify/email"> Verify your email address</a>')
+}
+```
+
+## Creating custom transports
+
+AdonisJS Mail transports are built on top of [Nodemailer transports](https://nodemailer.com/plugins/create/#transports); therefore, you must create/use a nodemailer transport before you can register it with the Mail package.
+
+In this guide, we will wrap the [nodemailer-postmark-transport](https://www.npmjs.com/package/nodemailer-postmark-transport) to an AdonisJS Mail transport.
+
+```sh
+npm i nodemailer nodemailer-postmark-transport
+```
+
+As you can see in the following example, the heavy lifting of sending an email is done by the `nodemailer`. The AdonisJS transport acts as an adapter forwarding the message to nodemailer and normalizing its response to an instance of [MailResponse](https://github.com/adonisjs/mail/blob/main/src/mail_response.ts).
+
+```ts
+import nodemailer from 'nodemailer'
+import nodemailerTransport from 'nodemailer-postmark-transport'
+
+import { MailResponse } from '@adonisjs/mail'
+import type {
+  NodeMailerMessage,
+  MailTransportContract
+} from '@adonisjs/mail/types'
+
+/**
+ * Configuration accepted by the transport
+ */
+export type PostMarkConfig = {
+  auth: {
+    apiKey: string
+  }
+}
+
+/**
+ * Transport implementation
+ */
+export class PostMarkTransport implements MailTransportContract {
+  #config: PostMarkConfig
+  constructor(config: PostMarkConfig) {
+    this.#config = config
+  }
+
+  #createNodemailerTransport(config: PostMarkConfig) {
+    return nodemailer.createTransport(nodemailerTransport(config))
+  }
+
+  async send(
+    message: NodeMailerMessage,
+    config?: PostMarkConfig
+  ): Promise<MailResponse> {
+    /**
+     * Create nodemailer transport
+     */
+    const transporter = this.#createNodemailerTransport({
+      ...this.#config,
+      ...config,
+    })
+
+    /**
+     * Send email
+     */
+    const response = await transporter.sendMail(message)
+
+    /**
+     * Normalize response to an instance of the "MailResponse" class
+     */
+    return new MailResponse(response.messageId, response.envelope, response)
+  }
+}
+```
+
+### Creating the config factory function
+To reference the above transport inside the `config/mail.ts` file, you must create a factory function that returns an instance of the transport.
+
+You may write the following code within the same file as your transport's implementation.
+
+```ts
+import type {
+  NodeMailerMessage,
+  MailTransportContract,
+  // insert-start
+  MailManagerTransportFactory
+  // insert-end
+} from '@adonisjs/mail/types'
+
+export function postMarkTransport(
+  config: PostMarkConfig
+): MailManagerTransportFactory {
+  return () => {
+    return new PostMarkTransport(config)
+  }
+}
+```
+
+### Using the transport
+Finally, you can reference the transport inside your config file using the `postMarkTransport` helper.
+
+```ts
+import env from '#start/env'
+import { defineConfig } from '@adonisjs/mail'
+import { postMarkTransport } from 'my-custom-package'
+
+const mailConfig = defineConfig({
+  mailers: {
+    postmark: postMarkTransport({
+      auth: {
+        apiKey: env.get('POSTMARK_API_KEY'),
+      },
+    }),
+  },
+})
+```
diff --git a/content/docs/ace/repl.md b/content/docs/digging_deeper/repl.md
similarity index 94%
rename from content/docs/ace/repl.md
rename to content/docs/digging_deeper/repl.md
index 723c368f..027c3e39 100644
--- a/content/docs/ace/repl.md
+++ b/content/docs/digging_deeper/repl.md
@@ -5,13 +5,13 @@ Like the [Node.js REPL](https://nodejs.org/api/repl.html), AdonisJS offers an ap
 node ace repl
 ```
 
-![](./ace_repl.png)
+![](../ace/ace_repl.png)
 
 On top of a standard Node.js REPL, AdonisJS provides the following features.
 
 - Import and execute TypeScript files.
 - Shorthand methods to import container services like the `router`, `helpers`, `hash` service, and so on.
-- Shorthand method to make class instances using the [IoC container](../fundamentals/ioc_container.md#constructing-a-tree-of-dependencies).
+- Shorthand method to make class instances using the [IoC container](../concepts/dependency_injection.md#constructing-a-tree-of-dependencies).
 - Extensible API to add custom methods and REPL commands.
 
 ## Interacting with REPL
@@ -92,7 +92,7 @@ p                     Promisify a function. Similar to Node.js "util.promisify"
 ## Adding custom methods to REPL
 You can add custom methods to the REPL using `repl.addMethod`. The method accepts the name as the first argument and the implementation callback as the second argument.
 
-For demonstration, let's create a [preload file](../fundamentals/adonisrc_file.md#preloads) file and define a method to import all models from the `./app/models` directory.
+For demonstration, let's create a [preload file](../concepts/adonisrc_file#preloads) file and define a method to import all models from the `./app/models` directory.
 
 ```sh
 node ace make:preload repl --env=repl
diff --git a/content/docs/digging_deeper/transmit.md b/content/docs/digging_deeper/transmit.md
index 11fa163b..2d3838df 100644
--- a/content/docs/digging_deeper/transmit.md
+++ b/content/docs/digging_deeper/transmit.md
@@ -102,7 +102,7 @@ routeHandlerModifier
 
 A function that is called before registering transmit routes. It receives the route instance. Use this function to add custom middleware or modify the route handler.
 
-For example, you can use the [`Rate Limiter`](../security/rate-limiter.md) and auth middleware to avoid abuse of some transmit route.
+For example, you can use the [`Rate Limiter`](../security/rate_limiting.md) and auth middleware to avoid abuse of some transmit route.
 
 ```ts
 import { defineConfig } from '@adonisjs/transmit'
diff --git a/content/docs/experimental/assembler_hooks.md b/content/docs/experimental/assembler_hooks.md
index 1578f76c..753579b5 100644
--- a/content/docs/experimental/assembler_hooks.md
+++ b/content/docs/experimental/assembler_hooks.md
@@ -1,10 +1,10 @@
-# Assembler Hooks
+# Assembler hooks
 
 Assembler hooks are a way of executing code at specific points in the assembler lifecycle. As a reminder, the Assembler is a part of AdonisJS that enables you to launch your dev server, build your application, and run your tests. 
 
 These hooks can be helpful for tasks such as file generation, code compilation, or injecting custom build steps.
 
-Assembler hooks were initially introduced for our [new experimental version of Vite](./vite.md). These hooks enable the `adonisjs/vite` package to customize the build process and inject a step where front-end assets are built, and also, if necessary, generate an SSR build.
+Assembler hooks were initially introduced for our [new experimental version of Vite](vite.md). These hooks enable the `adonisjs/vite` package to customize the build process and inject a step where front-end assets are built, and also, if necessary, generate an SSR build.
 
 ## Adding a hook
 
diff --git a/content/docs/experimental/inertia.md b/content/docs/experimental/inertia.md
index d7c658f9..a2109992 100644
--- a/content/docs/experimental/inertia.md
+++ b/content/docs/experimental/inertia.md
@@ -159,7 +159,7 @@ createInertiaApp({
 })
 ```
 
-```ts
+```tsx
 // title: React
 import { createRoot } from 'react-dom/client';
 import { createInertiaApp } from '@inertiajs/react';
@@ -242,7 +242,7 @@ The role of this file is to create an Inertia app and to resolve the page compon
 
 ## Rendering pages
 
-While configuring your package, a `inertia_middleware` has been registered inside the `start/kernel.ts` file. This middleware is responsible for setting up the `inertia` object on the [`HttpContext`](../http/http_context.md).
+While configuring your package, a `inertia_middleware` has been registered inside the `start/kernel.ts` file. This middleware is responsible for setting up the `inertia` object on the [`HttpContext`](../concepts/http_context.md).
 
 To render a view using Inertia, use the `inertia.render` method. The method accepts the view name and the data to be passed to the component as props.
 
@@ -549,7 +549,7 @@ export class UsersController {
   index() {
     return inertia.render('users/index', {
       users: [
-        { id: 1, name: 'julien' }
+        { id: 1, name: 'julien' },
         { id: 2, name: 'virk' },
         { id: 3, name: 'romain' },
       ]
@@ -604,7 +604,7 @@ defineProps<{
 
 ## CSRF 
 
-If you enabled [CSRF protection](../security/web-security.md#csrf-protection) for your application, enable the `enableXsrfCookie` option in the `config/shield.ts` file.
+If you enabled [CSRF protection](../../security/securing_ssr_applications#csrf-protection) for your application, enable the `enableXsrfCookie` option in the `config/shield.ts` file.
 
 Enabling this option will ensure that the `XSRF-TOKEN` cookie is set on the client side and sent back to the server with every request.
 
@@ -632,7 +632,7 @@ Read the [official documentation](https://inertiajs.com/asset-versioning) for mo
 
 ### Enabling SSR
 
-[Inertia Starter Kit](../guides/installation.md#starter-kits) comes with server-side rendering (SSR) support out of the box. So make sure to use it if you want to enable SSR for your application. 
+[Inertia Starter Kit](../getting_started/installation.md#starter-kits) comes with server-side rendering (SSR) support out of the box. So make sure to use it if you want to enable SSR for your application. 
 
 If you started your application without enabling SSR, you can always enable it later by following the following steps : 
 
@@ -666,7 +666,7 @@ export default function render(page) {
 }
 ```
 
-```ts
+```tsx
 // title: React
 import ReactDOMServer from 'react-dom/server'
 import { createInertiaApp } from '@inertiajs/react'
@@ -700,7 +700,7 @@ export default function render(page) {
 }
 ```
 
-```ts
+```tsx
 // title: Solid
 import { hydrate } from 'solid-js/web'
 import { createInertiaApp } from 'inertia-adapter-solid'
diff --git a/content/docs/experimental/vite.md b/content/docs/experimental/vite.md
index f8968f7b..16c03e06 100644
--- a/content/docs/experimental/vite.md
+++ b/content/docs/experimental/vite.md
@@ -2,7 +2,7 @@
 
 :::warning
 
-This documentation targets the new experimental version of our Vite integration ( 3.x.x ). If you use an older version, please refer to the [Vite 2.x.x documentation](../http/assets_bundling.md). 
+This documentation targets the new experimental version of our Vite integration ( 3.x.x ). If you use an older version, please refer to the [Vite 2.x.x documentation](../basics/vite.md). 
 
 :::
 
@@ -82,7 +82,7 @@ export default defineConfig({
 
 The `assetsBundler` property is set to `false` to turn off the assets bundler management done by the AdonisJS Assembler.
 
-The `unstable_assembler` property registers the `@adonisjs/vite/build_hook` to execute the Vite build process. See [Assembler hooks](./assembler_hooks.md) for more information.
+The `unstable_assembler` property registers the `@adonisjs/vite/build_hook` to execute the Vite build process. See [Assembler hooks](assembler_hooks.md) for more information.
 
 
 ## Configuration
diff --git a/content/docs/fundamentals/.DS_Store b/content/docs/fundamentals/.DS_Store
deleted file mode 100644
index 5008ddfcf53c02e82d7eee2e57c38e5672ef89f6..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 6148
zcmeH~Jr2S!425mzP>H1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3
zem<@ulZcFPQ@L2!n>{z**<q8>++&mCkOWA81W14cNZ<zv;LbK1Poaz?KmsK2CSc!(
z0ynLxE!0092;Krf2c+FF_Fe*7ECH>lEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ
zLs35+`xjp>T0<F0fCPF1$Cyrb|F7^5{eNG?83~ZUUlGt@xh*qZDeu<Z%US-OSsOPv
j)R!Z4KLME7ReXlK;d!wEw5GODWMKRea10D2@KpjYNUI8I

diff --git a/content/docs/fundamentals/deployments.md b/content/docs/fundamentals/deployments.md
deleted file mode 100644
index d0dee057..00000000
--- a/content/docs/fundamentals/deployments.md
+++ /dev/null
@@ -1,105 +0,0 @@
-# Deployment
-
-Deploying an AdonisJS application is no different than deploying a standard Node.js application. You need a server running `Node.js >= 18.x` along with `npm` to install production dependencies.
-
-This guide will cover the generic guidelines to deploy and run an AdonisJS application in production. In addition, you can read the following articles covering step by step deployment process for a specific platform.
-
-## Creating production build
-
-As a first step, you must create the production build of your AdonisJS application by running the `build` command.
-
-See also: [TypeScript build process](./typescript_build_process.md)
-
-```sh
-node ace build --production
-```
-
-The compiled output is written inside the `./build` directory. If you use Vite, its output will be written inside the `./build/public` directory.
-
-Once you have created the production build, you may copy the `./build` folder to your production server. **From now on, the build folder will be the root of your application**.
-
-## Configuring a reverse proxy
-
-Node.js applications are usually [deployed behind a reverse proxy](https://medium.com/intrinsic-blog/why-should-i-use-a-reverse-proxy-if-node-js-is-production-ready-5a079408b2ca) server like Nginx. So the incoming traffic on ports `80` and `443` will be handled by Nginx first and then forwarded to your Node.js application.
-
-Following is an example Nginx config file you may use as the starting point.
-
-:::warning
-
-Make sure to replace the values inside the angle brackets `<>`.
-
-:::
-
-```nginx
-server {
-  listen 80;
-
-  server_name <APP_DOMAIN.COM>;
-
-  location / {
-    proxy_pass http://localhost:<ADONIS_PORT>;
-    proxy_http_version 1.1;
-    proxy_set_header Upgrade $http_upgrade;
-    proxy_set_header Connection 'upgrade';
-    proxy_set_header Host $host;
-    proxy_set_header X-Real-IP $remote_addr;
-    proxy_set_header X-Forwarded-Proto $scheme;
-    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_cache_bypass $http_upgrade;
-  }
-}
-```
-
-## Defining environment variables
-
-If you are using a deployment platform like Heroku or Cleavr, you may use their control panel to define the environment variables. 
-
-However, if you are deploying your application on a bare-bone server like a Digital Ocean droplet or EC2, you may first create a `.env` file on the server. Ensure the file is stored securely and only authorized users can access it.
-
-Assuming you have created the `.env` file in the `/etc/secrets` directory, you must start your production server as follows.
-
-The `ENV_PATH` environment variable instructs AdonisJS to look for the `.env` file inside the mentioned directory.
-
-```sh
-ENV_PATH=/etc/secrets node server.js
-```
-
-## Starting the production server
-
-You may start the production server by running the `node server.js` file. However, it is recommended to use a process manager like [pm2](https://pm2.keymetrics.io/docs/usage/quick-start/).
-
-- PM2 will run your application in background without blocking the current terminal session.
-- It will restart the application, if your app crashes while serving requests.
-- Also, PM2 makes it super simple to run your application in [cluster mode](https://nodejs.org/api/cluster.html#cluster)
-
-Following is an example [pm2 ecosystem file](https://pm2.keymetrics.io/docs/usage/application-declaration/) you may use as the starting point.
-
-```js
-// title: ecosystem.config.js
-module.exports = {
-  apps: [
-    {
-      name: 'web-app',
-      script: './server.js',
-      instances: 'max',
-      exec_mode: 'cluster',
-      autorestart: true,
-    },
-  ],
-}
-```
-
-```sh
-// title: Start server
-pm2 start ecosystem.config.js
-```
-
-## Migrating database
-
-## Writing logs
-
-## Persistent storage for file uploads
-
-## Caching templates
-
-## Serving static assets
\ No newline at end of file
diff --git a/content/docs/guides/config.md b/content/docs/getting_started/configuration.md
similarity index 96%
rename from content/docs/guides/config.md
rename to content/docs/getting_started/configuration.md
index 6d5c745d..4e4fc87b 100644
--- a/content/docs/guides/config.md
+++ b/content/docs/getting_started/configuration.md
@@ -1,4 +1,4 @@
-# Config
+# Configuration
 
 The configuration files of your AdonisJS application are stored inside the `config` directory. A brand new AdonisJS application comes with a handful of pre-existing files used by the framework core and installed packages.
 
@@ -7,7 +7,7 @@ Feel free to create additional files your application requires inside the `confi
 
 :::note
 
-We recommend using [environment variables](./env.md) for storing secrets and environment-specific configuration.
+We recommend using [environment variables](environment_variables) for storing secrets and environment-specific configuration.
 
 
 :::
diff --git a/content/docs/getting_started/deployment.md b/content/docs/getting_started/deployment.md
new file mode 100644
index 00000000..77d0d2aa
--- /dev/null
+++ b/content/docs/getting_started/deployment.md
@@ -0,0 +1,231 @@
+# Deployment
+
+Deploying an AdonisJS application is no different than deploying a standard Node.js application. You need a server running `Node.js >= 20.6` along with `npm` to install production dependencies.
+
+This guide will cover the generic guidelines to deploy and run an AdonisJS application in production. 
+
+## Creating production build
+
+As a first step, you must create the production build of your AdonisJS application by running the `build` command.
+
+See also: [TypeScript build process](../concepts/typescript_build_process.md)
+
+```sh
+node ace build
+```
+
+The compiled output is written inside the `./build` directory. If you use Vite, its output will be written inside the `./build/public` directory.
+
+Once you have created the production build, you may copy the `./build` folder to your production server. **From now on, the build folder will be the root of your application**.
+
+### Creating a Docker image
+
+If you are using Docker to deploy your application, you may create a Docker image using the following `Dockerfile`.
+
+```dockerfile
+FROM node:20.12.2-alpine3.18 as base
+
+# All deps stage
+FROM base as deps
+WORKDIR /app
+ADD package.json package-lock.json ./
+RUN npm ci
+
+# Production only deps stage
+FROM base as production-deps
+WORKDIR /app
+ADD package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+# Build stage
+FROM base as build
+WORKDIR /app
+COPY --from=deps /app/node_modules /app/node_modules
+ADD . .
+RUN node ace build
+
+# Production stage
+FROM base
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --from=production-deps /app/node_modules /app/node_modules
+COPY --from=build /app/build /app
+EXPOSE 8080
+CMD ["node", "./bin/server.js"]
+```
+
+Feel free to modify the Dockerfile to suit your needs.
+
+## Configuring a reverse proxy
+
+Node.js applications are usually [deployed behind a reverse proxy](https://medium.com/intrinsic-blog/why-should-i-use-a-reverse-proxy-if-node-js-is-production-ready-5a079408b2ca) server like Nginx. So the incoming traffic on ports `80` and `443` will be handled by Nginx first and then forwarded to your Node.js application.
+
+Following is an example Nginx config file you may use as the starting point.
+
+:::warning
+Make sure to replace the values inside the angle brackets `<>`.
+:::
+
+```nginx
+server {
+  listen 80;
+  listen [::]:80;
+
+  server_name <APP_DOMAIN.COM>;
+
+  location / {
+    proxy_pass http://localhost:<ADONIS_PORT>;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection 'upgrade';
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_cache_bypass $http_upgrade;
+  }
+}
+```
+
+## Defining environment variables
+
+If you are deploying your application on a bare-bone server, like a DigitalOcean Droplet or an EC2 instance, you may use an `.env` file to define the environment variables. Ensure the file is stored securely and only authorized users can access it.
+
+:::note
+If you are using a deployment platform like Heroku or Cleavr, you may use their control panel to define the environment variables.
+:::
+
+Assuming you have created the `.env` file in an `/etc/secrets` directory, you must start your production server as follows.
+
+```sh
+ENV_PATH=/etc/secrets node build/server.js
+```
+
+The `ENV_PATH` environment variable instructs AdonisJS to look for the `.env` file inside the mentioned directory.
+
+## Starting the production server
+
+You may start the production server by running the `node server.js` file. However, it is recommended to use a process manager like [pm2](https://pm2.keymetrics.io/docs/usage/quick-start).
+
+- PM2 will run your application in background without blocking the current terminal session.
+- It will restart the application, if your app crashes while serving requests.
+- Also, PM2 makes it super simple to run your application in [cluster mode](https://nodejs.org/api/cluster.html#cluster)
+
+Following is an example [pm2 ecosystem file](https://pm2.keymetrics.io/docs/usage/application-declaration) you may use as the starting point.
+
+```js
+// title: ecosystem.config.js
+module.exports = {
+  apps: [
+    {
+      name: 'web-app',
+      script: './server.js',
+      instances: 'max',
+      exec_mode: 'cluster',
+      autorestart: true,
+    },
+  ],
+}
+```
+
+```sh
+// title: Start server
+pm2 start ecosystem.config.js
+```
+
+## Migrating database
+
+If you are using a SQL database, you must run the database migrations on the production server to create the required tables.
+
+If you are using Lucid, you may run the following command.
+
+```sh
+node ace migration:run --force
+```
+
+The `--force` flag is required when running migrations in the production environment.
+
+### When to run migrations
+
+Also, it would be best if you always run the migrations before restarting the server. Then, if the migration fails, do not restart the server.
+
+Using a managed service like Cleavr or Heroku, they can automatically handle this use case. Otherwise, you will have to run the migration script inside a CI/CD pipeline or run it manually through SSH.
+
+### Do not rollback in production
+
+Rolling back migrations in production is a risky operation. The `down` method in your migration files usually contains destructive actions like **drop the table**, or **remove a column**, and so on.
+
+It is recommended to turn off rollbacks in production inside the config/database.ts file and instead, create a new migration to fix the issue and run it on the production server.
+
+Disabling rollbacks in production will ensure that the `node ace migration:rollback` command results in an error.
+
+```js
+{
+  pg: {
+    client: 'pg',
+    migrations: {
+      disableRollbacksInProduction: true,
+    }
+  }
+}
+```
+
+### Concurrent migrations
+
+If you are running migrations on a server with multiple instances, you must ensure that only one instance runs the migrations.
+
+For MySQL and PostgreSQL, Lucid will obtain advisory locks to ensure that concurrent migration is not allowed. However, it is better to avoid running migrations from multiple servers in the first place.
+
+## Persistent storage for file uploads
+
+Environments like Amazon EKS, Google Kubernetes, Heroku, DigitalOcean Apps, and so on, run your application code inside [an ephemeral filesystem](https://devcenter.heroku.com/articles/dynos#ephemeral-filesystem), which means that each deployment, by default, will nuke the existing filesystem and creates a fresh one.
+
+If your application allows users to upload files, you must use a persistent storage service like Amazon S3, Google Cloud Storage, or DigitalOcean Spaces instead of relying on the local filesystem.
+
+## Writing logs
+
+AdonisJS uses the [`pino` logger](../digging_deeper/logger.md) by default, which writes logs to the console in JSON format. You can either set up an external logging service to read the logs from stdout/stderr, or forward them to a local file on the same server.
+
+## Serving static assets
+
+Serving static assets effectively is essential for the performance of your application. Regardless of how fast your AdonisJS applications are, the delivery of static assets plays a massive role to a better user experience.
+
+### Using a CDN
+
+The best approach is to use a CDN (Content Delivery Network) for delivering the static assets from your AdonisJS application.
+
+The frontend assets compiled using [Vite](../basics/vite.md) are fingerprinted by default, which means that the file names are hashed based on their content. This allows you to cache the assets forever and serve them from a CDN.
+
+Depending upon the CDN service you are using and your deployment technique, you may have to add a step to your deployment process to move the static files to the CDN server. This is how it should work in a nutshell.
+
+1. Update the `vite.config.js` and `config/vite.ts` configuration to [use the CDN URL](../basics/vite.md#deploying-assets-to-a-cdn).
+
+2. Run the `build` command to compile the application and the assets.
+
+3. Copy the output of `public/assets` to your CDN server. For example, [here is a command](https://github.com/adonisjs-community/polls-app/blob/main/commands/PublishAssets.ts) we use to publish the assets to an Amazon S3 bucket.
+
+### Using Nginx to deliver static assets
+
+Another option is to offload the task of serving assets to Nginx. If you use Vite to compile the front-end assets, you must aggressively cache all the static files since they are fingerprinted.
+
+Add the following block to your Nginx config file. **Make sure to replace the values inside the angle brackets `<>`**.
+
+```nginx
+location ~ \.(jpg|png|css|js|gif|ico|woff|woff2) {
+  root <PATH_TO_ADONISJS_APP_PUBLIC_DIRECTORY>;
+  sendfile on;
+  sendfile_max_chunk 2m;
+  add_header Cache-Control "public";
+  expires 365d;
+}
+```
+
+### Using AdonisJS static file server
+
+You can also rely on the [AdonisJS inbuilt static file server](../basics/static_file_server.md) to serve the static assets from the `public` directory to keep things simple.
+
+No additional configuration is required. Just deploy your AdonisJS application as usual, and the request for static assets will be served automatically.
+
+:::warn
+The static file server is not recommended for production use. It is best to use a CDN or Nginx to serve static assets.
+:::
diff --git a/content/docs/guides/env_intellisense.jpeg b/content/docs/getting_started/env_intellisense.jpeg
similarity index 100%
rename from content/docs/guides/env_intellisense.jpeg
rename to content/docs/getting_started/env_intellisense.jpeg
diff --git a/content/docs/guides/env_intellisense_original.png b/content/docs/getting_started/env_intellisense_original.png
similarity index 100%
rename from content/docs/guides/env_intellisense_original.png
rename to content/docs/getting_started/env_intellisense_original.png
diff --git a/content/docs/guides/env.md b/content/docs/getting_started/environment_variables.md
similarity index 98%
rename from content/docs/guides/env.md
rename to content/docs/getting_started/environment_variables.md
index f8749eda..cbc8585f 100644
--- a/content/docs/guides/env.md
+++ b/content/docs/getting_started/environment_variables.md
@@ -42,7 +42,7 @@ env.get('PORT', 3333)
 ### Sharing env module with Edge templates
 If you want to access environment variables within edge templates, then you must share the `env` module as a global variable with edge templates. 
 
-You can [create `view.ts` as a preload file](../fundamentals/adonisrc_file.md#preloads) inside the `start` directory and write the following lines of code inside it.
+You can [create `view.ts` as a preload file](../concepts/adonisrc_file#preloads) inside the `start` directory and write the following lines of code inside it.
 
 ```ts
 // title: start/view.ts
@@ -196,7 +196,7 @@ The `schema.enum` method validates the environment variable against one of the p
 }
 
 // Using native enums
-enum NODE_ENV = {
+enum NODE_ENV {
   development = 'development',
   production = 'production'
 }
diff --git a/content/docs/guides/folder_structure.md b/content/docs/getting_started/folder_structure.md
similarity index 93%
rename from content/docs/guides/folder_structure.md
rename to content/docs/getting_started/folder_structure.md
index 6ae8e1fe..2027c6bd 100644
--- a/content/docs/guides/folder_structure.md
+++ b/content/docs/getting_started/folder_structure.md
@@ -10,7 +10,7 @@ The `adonisrc.ts` file is used to configure the workspace and some of the runtim
 
 In this file, you can register providers, define command aliases, or specify the files to copy to the production build.
 
-See also: [AdonisRC file reference guide](../fundamentals/adonisrc_file.md)
+See also: [AdonisRC file reference guide](../concepts/adonisrc_file)
 
 ## The `tsconfig.json` file
 
@@ -149,7 +149,7 @@ The `start` directory contains the files you want to import during the boot life
 
 AdonisJS does not auto-import files from the `start` directory. It is merely used as a convention to group similar files.
 
-We recommend reading about [preload files](../fundamentals/adonisrc_file.md#preloads) and the [application boot lifecycle](../fundamentals/application_lifecycle.md) to have a better understanding of which files to keep under the `start` directory.
+We recommend reading about [preload files](../concepts/adonisrc_file#preloads) and the [application boot lifecycle](../concepts/application_lifecycle.md) to have a better understanding of which files to keep under the `start` directory.
 
 ## The `public` directory
 
@@ -183,7 +183,7 @@ The `config` directory contains the runtime configuration files for your applica
 
 The framework's core and other installed packages read configuration files from this directory. You can also store config local to your application inside this directory.
 
-Learn more about [configuration management](./config.md).
+Learn more about [configuration management](./configuration.md).
 
 ```
 ├── config
@@ -213,9 +213,9 @@ The directory is empty by default, however, you can create files and folders wit
 
 ## The `providers` directory
 
-The `providers` directory is used to store the [service providers](../fundamentals/service_providers.md) used by your application. You can create new providers using the `node ace make:provider` command.
+The `providers` directory is used to store the [service providers](../concepts/service_providers.md) used by your application. You can create new providers using the `node ace make:provider` command.
 
-Learn more about [service providers](../fundamentals/service_providers.md)
+Learn more about [service providers](../concepts/service_providers.md)
 
 ```
 ├── providers
diff --git a/content/docs/guides/installation.md b/content/docs/getting_started/installation.md
similarity index 95%
rename from content/docs/guides/installation.md
rename to content/docs/getting_started/installation.md
index a1814a9b..ada4694d 100644
--- a/content/docs/guides/installation.md
+++ b/content/docs/getting_started/installation.md
@@ -50,7 +50,7 @@ npm init adonisjs@latest hello-world -- --kit=api --auth-guard=access_tokens
 
 ## Starter kits
 
-Starter kits serve as a starting point for creating applications using AdonisJS. They come with an [opinionated folder structure](./folder_structure.md), pre-configured AdonisJS packages, and the necessary tooling you need during development.
+Starter kits serve as a starting point for creating applications using AdonisJS. They come with an [opinionated folder structure](folder_structure.md), pre-configured AdonisJS packages, and the necessary tooling you need during development.
 
 
 :::note
@@ -139,7 +139,7 @@ In this starter kit:
 
 The API starter kit is configured with session-based authentication. However, if you wish to use tokens-based authentication, you can use the `--auth-guard` flag.
 
-See also: [Which authentication guard should I use?](../auth/introduction.md#choosing-an-auth-guard)
+See also: [Which authentication guard should I use?](../authentication/introduction.md#choosing-an-auth-guard)
 
 ```sh
 npm init adonisjs@latest -- -K=api --auth-guard=access_tokens
@@ -216,7 +216,7 @@ npm init adonisjs@latest -- -K="user/repo#v2.1.0"
 ## Starting the development server
 Once you have created an AdonisJS application, you may start the development server by running the `node ace serve` command.
 
-Ace is a command line framework bundled inside the framework's core. The `--hmr` flag monitors the file system and performs [hot module replacement (HMR)](../fundamentals/hmr.md) for certain sections of your codebase.
+Ace is a command line framework bundled inside the framework's core. The `--hmr` flag monitors the file system and performs [hot module replacement (HMR)](../concepts/hmr.md) for certain sections of your codebase.
 
 ```sh
 node ace serve --hmr
@@ -232,7 +232,7 @@ You may create the JavaScript output using the `node ace build` command. The Jav
 
 When Vite is configured, this command also compiles the frontend assets using Vite and writes the output to the `build/public` folder.
 
-See also: [TypeScript build process](../fundamentals/typescript_build_process.md).
+See also: [TypeScript build process](../concepts/typescript_build_process.md).
 
 ```sh
 node ace build
@@ -244,7 +244,7 @@ While AdonisJS takes care of building the end-user applications, you may need ad
 
 We strongly recommend you use **[ESLint](https://eslint.org/)** to lint your code and use **[Prettier](https://prettier.io)** to re-format your code for consistency.
 
-The official starter kits come pre-configured with both ESLint and Prettier and use the opinionated presets from the AdonisJS core team. You can learn more about them in the [Tooling config](../fundamentals/tooling_config.md) section of the docs.
+The official starter kits come pre-configured with both ESLint and Prettier and use the opinionated presets from the AdonisJS core team. You can learn more about them in the [Tooling config](../concepts/tooling_config.md) section of the docs.
 
 Finally, we recommend you install ESLint and Prettier plugins for your code editor so that you have a tighter feedback loop during the application development. Also, you can use the following commands to `lint` and `format` your code from the command line.
 
diff --git a/content/docs/guides/.DS_Store b/content/docs/guides/.DS_Store
deleted file mode 100644
index 5008ddfcf53c02e82d7eee2e57c38e5672ef89f6..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 6148
zcmeH~Jr2S!425mzP>H1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3
zem<@ulZcFPQ@L2!n>{z**<q8>++&mCkOWA81W14cNZ<zv;LbK1Poaz?KmsK2CSc!(
z0ynLxE!0092;Krf2c+FF_Fe*7ECH>lEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ
zLs35+`xjp>T0<F0fCPF1$Cyrb|F7^5{eNG?83~ZUUlGt@xh*qZDeu<Z%US-OSsOPv
j)R!Z4KLME7ReXlK;d!wEw5GODWMKRea10D2@KpjYNUI8I

diff --git a/content/docs/http/.DS_Store b/content/docs/http/.DS_Store
deleted file mode 100644
index 5008ddfcf53c02e82d7eee2e57c38e5672ef89f6..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 6148
zcmeH~Jr2S!425mzP>H1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3
zem<@ulZcFPQ@L2!n>{z**<q8>++&mCkOWA81W14cNZ<zv;LbK1Poaz?KmsK2CSc!(
z0ynLxE!0092;Krf2c+FF_Fe*7ECH>lEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ
zLs35+`xjp>T0<F0fCPF1$Cyrb|F7^5{eNG?83~ZUUlGt@xh*qZDeu<Z%US-OSsOPv
j)R!Z4KLME7ReXlK;d!wEw5GODWMKRea10D2@KpjYNUI8I

diff --git a/content/docs/http/url_builder.md b/content/docs/http/url_builder.md
deleted file mode 100644
index ba76d0ab..00000000
--- a/content/docs/http/url_builder.md
+++ /dev/null
@@ -1,186 +0,0 @@
-# URL builder
-
-You may use the URL builder to create URLs for pre-defined routes in your application. For example, create a form action URL inside Edge templates, or make the URL to redirect the request to another route.
-
-The `router.builder` method creates an instance of the [URL builder](https://github.com/adonisjs/http-server/blob/main/src/router/lookup_store/url_builder.ts) class, and you can use the builder's fluent API to lookup a route and create a URL for it.
-
-```ts
-import router from '@adonisjs/core/services/router'
-const PostsController = () => import('#controllers/posts_controller')
-
-router
-  .get('posts/:id', [PostsController, 'show'])
-  .as('posts.show')
-```
-
-You may generate the URL for the `posts.show` route as follows.
-
-```ts
-import router from '@adonisjs/core/services/router'
-
-router
-  .builder()
-  .params([1])
-  .make('posts.show') // /posts/1
-
-router
- .builder()
- .params([20])
- .make('posts.show') // /posts/20
-```
-
-The params can be specified as an array of positional arguments. Or you can define them as a key-value pair.
-
-```ts
-router
- .builder()
- .params({ id: 1 })
- .make('posts.show') // /posts/1
-```
-
-## Defining query parameters
-
-The query parameters can be defined using the `builder.qs` method. The method accepts an object of key-value pair and serializes it to a query string.
-
-```ts
-router
-  .builder()
-  .qs({ page: 1, sort: 'asc' })
-  .make('posts.index') // /posts?page=1&sort=asc
-```
-
-The query string is serialized using the [qs](https://www.npmjs.com/package/qs) npm package. You can [configure its settings](https://github.com/adonisjs/http-server/blob/main/src/define_config.ts#L49-L54) inside the `config/app.ts` file under the `http` object.
-
-```ts
-// config/app.js
-http: defineConfig({
-  qs: {
-    stringify: {
-      // 
-    }
-  }
-})
-```
-
-## Prefixing URL
-
-You may prefix a base URL to the output using the `builder.prefixUrl` method.
-
-```ts
-router
-  .builder()
-  .prefixUrl('https://blog.adonisjs.com')
-  .params({ id: 1 })
-  .make('posts.show')
-```
-
-## Generating signed URLs
-
-Signed URLs are URLs with a signature query string appended to them. The signature is used to verify if the URL has been tampered after it was generated.
-
-For example, you have a URL to unsubscribe users from your newsletter. The URL contains the `userId` and might look as follows.
-
-```
-/unsubscribe/231
-```
-
-To prevent someone from changing the user id from `231` to something else, you can sign this URL and verify the signature when handling requests for this route.
-
-```ts
-router.get('unsubscribe/:id', ({ request, response }) => {
-  if (!request.hasValidSignature()) {
-    return response.badRequest('Invalid or expired URL')
-  }
-  
-  // Remove subscription
-}).as('unsubscribe')
-```
-
-You may use the `makeSigned` method to create a signed URL.
-
-```ts
-router
-  .builder()
-  .prefixUrl('https://blog.adonisjs.com')
-  .params({ id: 231 })
-  // highlight-start
-  .makeSigned('unsubscribe')
-  // highlight-end
-```
-
-### Signed URL expiration
-
-You may generate signed URLs that expire after a given duration using the `expiresIn` option. The value can be a number in milliseconds or a time expression string.
-
-```ts
-router
-  .builder()
-  .prefixUrl('https://blog.adonisjs.com')
-  .params({ id: 231 })
-  // highlight-start
-  .makeSigned('unsubscribe', {
-    expiresIn: '3 days'
-  })
-  // highlight-end
-```
-
-## Disabling route lookup
-
-The URL builder performs a route lookup with the route identifier given to the `make` and the `makeSigned` methods.
-
-If you want to create a URL for routes defined outside of your AdonisJS application, you may disable the route lookup and give the route pattern to the `make` and the `makeSigned` methods.
-
-```ts
-router
-  .builder()
-  .prefixUrl('https://your-app.com')
-  .disableRouteLookup()
-  .params({ token: 'foobar' })
-  .make('/email/verify/:token') // /email/verify/foobar
-```
-
-## Making URL for routes under a domain
-You can make URLs for routes registered under a specific domain using the `router.builderForDomain` method. The method accepts the route pattern you used at the time of defining the routes.
-
-```ts
-import router from '@adonisjs/core/services/router'
-const PostsController = () => import('#controllers/posts_controller')
-
-router.group(() => {
-  router
-    .get('/posts/:id', [PostsController, 'show'])
-    .as('posts.show')
-}).domain('blog.adonisjs.com')
-```
-
-You can create URL for the `posts.show` route under `blog.adonisjs.com` domain as follows.
-
-```ts
-router
-  .builderForDomain('blog.adonisjs.com')
-  .params({ id: 1 })
-  .make('posts.show')
-```
-
-## Generating URLs inside templates
-
-You may use the `route` and the `signedRoute` methods inside templates to generate a URL using the URL builder.
-
-See also: [Edge helpers reference](../reference/edge.md#routesignedroute)
-
-```edge
-<a href="{{ route('posts.show', [post.id]) }}">
-  View post
-</a>
-```
-
-```edge
-<a href="{{
-  signedRoute('unsubscribe', [user.id], {
-    expiresIn: '3 days',
-    prefixUrl: 'https://blog.adonisjs.com'    
-  })
-}}">
-  Unsubscribe
-</a>
-```
diff --git a/content/docs/mail/class_based_mails.md b/content/docs/mail/class_based_mails.md
deleted file mode 100644
index 50ca803f..00000000
--- a/content/docs/mail/class_based_mails.md
+++ /dev/null
@@ -1,190 +0,0 @@
-# Class-based emails
-
-Instead of writing emails inside the `mail.send` method closure, you may move them to dedicated mail classes for better organization and [easier testing](#testing-mail-classes).
-
-The mail classes are stored inside the `./app/mails` directory, and each file represents a single email. You may create a mail class by running the `make:mail` ace command.
-
-See also: [Make mail command](../reference/commands.md#makemail)
-
-```sh
-node ace make:mail verify_email
-```
-
-The mail class extends the [BaseMail](https://github.com/adonisjs/mail/blob/main/src/base_mail.ts) class and is scaffolded with following properties and methods. You may configure the mail message inside the `prepare` method using the `this.message` property.
-
-```ts
-import User from '#models/user'
-import { BaseMail } from '@adonisjs/mail'
-
-export default class VerifyEmailNotification extends BaseMail {
-  from = 'sender_email@example.org'
-  subject = 'Verify email'
-
-  prepare() {
-    this.message.to('user_email@example.org')
-  }
-}
-```
-
-<dl>
-
-<dt>
-
-from
-
-</dt>
-
-<dd>
-
-Configure the sender's email address. If you omit this property, you must call the `message.from` method to define the sender.
-
-</dd>
-
-<dt>
-
-subject
-
-</dt>
-
-<dd>
-
-Configure the email subject. If you omit this property, you must use the `message.subject` method to define the email subject.
-
-</dd>
-
-<dt>
-
-replyTo
-
-</dt>
-
-<dd>
-
-Configure the `replyTo` email address.
-
-</dd>
-
-<dt>
-
-prepare
-
-</dt>
-
-<dd>
-
-The `prepare` method is called automatically by the `build` method to prepare the mail message for sending. 
-
-You must define the email contents, attachments, recipients, etc, within this method.
-
-</dd>
-
-<dt>
-
-build :span[Inherited]{class="badge"}
-
-</dt>
-
-<dd>
-
-The `build` method is inherited from the `BaseMail` class. The method is called automatically at the time of sending the email.
-
-Make sure to reference the [original implementation](https://github.com/adonisjs/mail/blob/main/src/base_mail.ts#L81) if you decide to override this method.
-
-</dd>
-
-</dl>
-
-## Sending email using the mail class
-You may call the `mail.send` method and pass it an instance of the mail class to send the email. For example:
-
-```ts
-// title: Send mail
-import mail from '@adonisjs/mail/services/main'
-import VerifyEmailNotification from '#mails/verify_email'
-
-await mail.send(new VerifyEmailNotification())
-```
-
-```ts
-// title: Queue mail
-import mail from '@adonisjs/mail/services/main'
-import VerifyEmailNotification from '#mails/verify_email'
-
-await mail.sendLater(new VerifyEmailNotification())
-```
-
-You may share data with the mail class using constructor arguments. For example:
-
-```ts
-/**
- * Creating a user
- */
-const user = await User.create(payload)
-
-await mail.send(
-  /**
-   * Passing user to the mail class
-   */
-  new VerifyEmailNotification(user)
-)
-```
-
-## Testing mail classes
-
-One of the primary benefits of using [Mail classes](#class-based-emails) is a better testing experience. You can build mail classes without sending them and write assertions for the message properties.
-
-```ts
-import { test } from '@japa/runner'
-import VerifyEmailNotification from '#mails/verify_email'
-
-test.group('Verify email notification', () => {
-  test('prepare email for sending', async () => {
-    const email = new VerifyEmailNotification()
-
-    /**
-     * Build email message and render templates to
-     * compute the email HTML and plain text
-     * contents
-     */
-    await email.buildWithContents()
-    
-    /**
-     * Write assertions to ensure the message is built
-     * as expected
-     */
-    email.message.assertTo('user@example.org')
-    email.message.assertFrom('info@example.org')
-    email.message.assertSubject('Verify email address')
-    email.message.assertReplyTo('no-reply@example.org')
-  })
-})
-```
-
-You may write assertions for the message contents as follows.
-
-```ts
-const email = new VerifyEmailNotification()
-await email.buildWithContents()
-
-// highlight-start
-email.message.assertHtmlIncludes(
-  `<a href="/emails/1/verify"> Verify email address </a>`
-)
-email.message.assertTextIncludes('Verify email address')
-// highlight-end
-```
-
-Also, you may write assertions for the attachments. The assertions only work with file-based attachments and not for streams or raw content.
-
-```ts
-const email = new VerifyEmailNotification()
-await email.buildWithContents()
-
-// highlight-start
-email.message.assertAttachment(
-  app.makePath('uploads/invoice.pdf')
-)
-// highlight-end
-```
-
-Feel free to look at the [Message](https://github.com/adonisjs/mail/blob/main/src/message.ts) class source code for all the available assertion methods.
diff --git a/content/docs/mail/custom_transports.md b/content/docs/mail/custom_transports.md
deleted file mode 100644
index 6ed685fd..00000000
--- a/content/docs/mail/custom_transports.md
+++ /dev/null
@@ -1,110 +0,0 @@
-# Creating custom transports
-
-AdonisJS Mail transports are built on top of [Nodemailer transports](https://nodemailer.com/plugins/create/#transports); therefore, you must create/use a nodemailer transport before you can register it with the Mail package.
-
-In this guide, we will wrap the [nodemailer-postmark-transport](https://www.npmjs.com/package/nodemailer-postmark-transport) to an AdonisJS Mail transport. 
-
-```sh
-npm i nodemailer nodemailer-postmark-transport
-```
-
-As you can see in the following example, the heavy lifting of sending an email is done by the `nodemailer`. The AdonisJS transport acts as an adapter forwarding the message to nodemailer and normalizing its response to an instance of [MailResponse](https://github.com/adonisjs/mail/blob/main/src/mail_response.ts).
-
-```ts
-import nodemailer from 'nodemailer'
-import nodemailerTransport from 'nodemailer-postmark-transport'
-
-import { MailResponse } from '@adonisjs/mail'
-import type {
-  NodeMailerMessage,
-  MailTransportContract
-} from '@adonisjs/mail/types'
-
-/**
- * Configuration accepted by the transport
- */
-export type PostMarkConfig = {
-  auth: {
-    apiKey: string
-  }
-}
-
-/**
- * Transport implementation
- */
-export class PostMarkTransport implements MailTransportContract {
-  #config: PostMarkConfig
-  constructor(config: PostMarkConfig) {
-    this.#config = config
-  }
-
-  #createNodemailerTransport(config: PostMarkConfig) {
-    return nodemailer.createTransport(nodemailerTransport(config))
-  }
-
-  async send(
-    message: NodeMailerMessage,
-    config?: PostMarkConfig
-  ): Promise<MailResponse> {
-    /**
-     * Create nodemailer transport
-     */
-    const transporter = this.#createNodemailerTransport({
-      ...this.#config,
-      ...config,
-    })
-
-    /**
-     * Send email
-     */
-    const response = await transporter.sendMail(message)
-
-    /**
-     * Normalize response to an instance of the "MailResponse" class
-     */
-    return new MailResponse(response.messageId, response.envelope, response)
-  }
-}
-```
-
-## Creating the config factory function
-To reference the above transport inside the `config/mail.ts` file, you must create a factory function that returns an instance of the transport.
-
-You may write the following code within the same file as your transport's implementation.
-
-```ts
-import type {
-  NodeMailerMessage,
-  MailTransportContract,
-  // insert-start
-  MailManagerTransportFactory
-  // insert-end
-} from '@adonisjs/mail/types'
-
-export function postMarkTransport(
-  config: PostMarkConfig
-): MailManagerTransportFactory {
-  return () => {
-    return new PostMarkTransport(config)
-  }
-}
-```
-
-## Using the transport
-Finally, you can reference the transport inside your config file using the `postMarkTransport` helper.
-
-```ts
-import env from '#start/env'
-import { defineConfig } from '@adonisjs/mail'
-import { postMarkTransport } from 'my-custom-package'
-
-const mailConfig = defineConfig({
-  mailers: {
-    postmark: postMarkTransport({
-      auth: {
-        apiKey: env.get('POSTMARK_API_KEY'),
-      },
-    }),
-  },
-})
-```
diff --git a/content/docs/mail/fake_mailer.md b/content/docs/mail/fake_mailer.md
deleted file mode 100644
index 18b67d3c..00000000
--- a/content/docs/mail/fake_mailer.md
+++ /dev/null
@@ -1,192 +0,0 @@
-# Fake mailer
-You may want to use the Fake mailer during testing to prevent your application from sending emails. The Fake mailer collects all outgoing emails within memory and offers an easy-to-use API for writing assertions against them.
-
-In the following example:
-
-- We start by creating an instance of the [FakeMailer](https://github.com/adonisjs/mail/blob/main/src/fake_mailer.ts) using the `mail.fake` method. 
-- Next, we call the `/register` endpoint API.
-- Finally, we use the `mails` property from the fake mailer to assert the `VerifyEmailNotification` was sent.
-
-```ts
-import { test } from '@japa/runner'
-import mail from '@adonisjs/mail/services/main'
-import VerifyEmailNotification from '#mails/verify_email'
-
-test.group('Users | register', () => {
-  test('create a new user account', async ({ client, route }) => {
-    // highlight-start
-    /**
-     * Turn on the fake mode
-     */
-    const { mails } = mail.fake()
-    // highlight-end
-    
-    /**
-     * Make an API call
-     */
-    await client
-      .post(route('users.store'))
-      .send(userData)
-      
-    // highlight-start
-    /**
-     * Assert the controller indeed sent the
-     * VerifyEmailNotification mail
-     */
-    mails.assertSent(VerifyEmailNotification, ({ message }) => {
-      return message
-        .hasTo(userData.email)
-        .hasSubject('Verify email address')
-    })
-    // highlight-end
-  })
-})
-```
-
-Once you are done writing the test, you must restore the fake using the `mail.restore` method.
-
-```ts
-test('create a new user account', async ({ client, route, cleanup }) => {
-  const { mails } = mail.fake()
-  
-  /**
-   * The cleanup hooks are executed after the test
-   * finishes successfully or with an error.
-   */
-  cleanup(() => {
-    mail.restore()
-  })
-})
-```
-
-## Writing assertions
-
-The `mails.assertSent` method accepts the mail class constructor as the first argument and throws an exception when unable to find any emails for the expected class.
-
-```ts
-const { mails } = mail.fake()
-
-/**
- * Asser the email was sent
- */
-mails.assertSent(VerifyEmailNotification)
-```
-
-You may pass a callback function to the `assertSent` method to further check if the email was sent to the expected recipient or has correct subject.
-
-The callback function receives an instance of the mail class and you can use the `.message` property to get access to the [message](./message.md) object.
-
-```ts
-mails.assertSent(VerifyEmailNotification, (email) => {
-  return email.message
-    .hasTo(userData.email)
-    .hasFrom('info@example.org')
-    .hasSubject('Verify your email address')
-})
-```
-
-You may run assertions on the `message` object within the callback. For example:
-
-```ts
-mails.assertSent(VerifyEmailNotification, (email) => {
-  email.message.assertHasTo(userData.email)
-  email.message.assertHasFrom('info@example.org')
-  email.message.assertHasSubject('Verify your email address')
-
-  /**
-   * All assertions passed, so return true to consider the
-   * email as sent.
-   */
-  return true
-})
-```
-
-### Assert email was not sent
-
-You may use the `mails.assertNotSent` method to assert an email was not sent during the test. This method is the opposite of the `assertSent` method and accepts the same arguments.
-
-```ts
-const { mails } = mail.fake()
-
-mails.assertNotSent(PasswordResetNotification)
-```
-
-### Assert emails count
-
-Finally, you can assert the count of sent emails using the `assertSentCount` and `assertNoneSent` methods.
-
-```ts
-const { mails } = mail.fake()
-
-// Assert 2 emails were sent in total
-mails.assertSentCount(2)
-
-// Assert only one VerifyEmailNotification was sent
-mails.assertSentCount(VerifyEmailNotification, 1)
-```
-
-```ts
-const { mails } = mail.fake()
-
-// Assert zero emails were sent
-mails.assertNoneSent()
-```
-
-## Writing assertions for queued emails
-
-If you have queued emails using the `mail.sendLater` method, you may use the following methods to write assertions for them.
-
-```ts
-const { mails } = mail.fake()
-
-/**
- * Assert "VerifyEmailNotification" email was queued
- * Optionally, you may pass the finder function to
- * narrow down the email
- */
-mails.assertQueued(VerifyEmailNotification)
-
-/**
- * Assert "VerifyEmailNotification" email was not queued
- * Optionally, you may pass the finder function to
- * narrow down the email
- */
-mails.assertNotQueued(PasswordResetNotification)
-
-/**
- * Assert two emails were queued in total.
- */
-mails.assertQueuedCount(2)
-
-/**
- * Assert "VerifyEmailNotification" email was queued
- * only once
- */
-mails.assertQueuedCount(VerifyEmailNotification , 1)
-
-/**
- * Assert nothing was queued
- */
-mails.assertNoneQueued()
-```
-
-## Getting a list of sent or queued emails
-
-You may use the `mails.sent` or `mails.queued` methods to get an array of emails sent/queued during tests.
-
-```ts
-const { mails } = mail.fake()
-
-const sentEmails = mails.sent()
-const queuedEmails = mails.queued()
-
-const email = sentEmails.find((email) => {
-  return email instanceof VerifyEmailNotification
-})
-
-if (email) {
-  email.message.assertTo(userData.email)
-  email.message.assertFrom(userData.email)
-  email.message.assertHtmlIncludes('<a href="/verify/email"> Verify your email address</a>')
-}
-```
diff --git a/content/docs/mail/introduction.md b/content/docs/mail/introduction.md
deleted file mode 100644
index 54e10ac1..00000000
--- a/content/docs/mail/introduction.md
+++ /dev/null
@@ -1,509 +0,0 @@
-# Mail
-
-You can send emails from your AdonisJS application using the `@adonisjs/mail` package. The mail package is built on top of [Nodemailer](https://nodemailer.com/), bringing the following quality of life improvements over Nodemailer.
-
-- Fluent API to configure mail messages.
-- Ability to define emails as classes for better organization and easier testing.
-- An extensive suite of officially maintained transports. It includes `smtp`, `ses`, `mailgun`, `sparkpost`, `resend`, and `brevo`.
-- Improved testing experience using the Fakes API.
-- Mail messenger to queue emails.
-- Functional APIs to generate calendar events.
-
-## Installation
-
-Install and configure the package using the following command :
-
-```sh
-node ace add @adonisjs/mail
-
-# Pre-define transports to use via CLI flag
-node ace add @adonisjs/mail --transports=resend --transports=smtp
-```
-
-:::disclosure{title="See steps performed by the add command"}
-
-1. Installs the `@adonisjs/mail` package using the detected package manager.
-
-2. Registers the following service provider and command inside the `adonisrc.ts` file.
-
-    ```ts
-    {
-      commands: [
-        // ...other commands
-        () => import('@adonisjs/mail/commands')
-      ],
-      providers: [
-        // ...other providers
-        () => import('@adonisjs/mail/mail_provider')
-      ]
-    }
-    ```
-
-3. Create the `config/mail.ts` file.
-
-4. Defines the environment variables and their validations for the selected mail services
-
-:::
-
-
-## Configuration
-
-The configuration for the mail package is stored inside the `config/mail.ts` file. Inside this file, you may configure multiple email services as `mailers` to use them within your application.
-
-See also: [Config stub](https://github.com/adonisjs/mail/blob/main/stubs/config/mail.stub)
-
-```ts
-import env from '#start/env'
-import { defineConfig, transports } from '@adonisjs/mail'
-
-const mailConfig = defineConfig({
-  default: 'smtp',
-  
-  /**
-   * A static address for the "from" property. It will be
-   * used unless an explicit from address is set on the
-   * Email
-   */
-  from: {
-    address: '',
-    name: '',
-  },
-  
-  /**
-   * A static address for the "reply-to" property. It will be
-   * used unless an explicit replyTo address is set on the
-   * Email
-   */
-  replyTo: {
-    address: '',
-    name: '',
-  },
-
-  /**
-   * The mailers object can be used to configure multiple mailers
-   * each using a different transport or the same transport with a different
-   * options.
-   */
-  mailers: {
-    smtp: transports.smtp({
-      host: env.get('SMTP_HOST'),
-      port: env.get('SMTP_PORT'),
-    }),
-
-    resend: transports.resend({
-      key: env.get('RESEND_API_KEY'),
-      baseUrl: 'https://api.resend.com',
-    }),
-  },
-})
-```
-
-<dl>
-
-<dt>
-
-default
-
-</dt>
-
-<dd>
-
-The name of the mailer to use by default for sending emails.
-
-</dd>
-
-<dt>
-
-from
-
-</dt>
-
-<dd>
-
-A static global address to use for the `from` property. The global address will be used unless an explicit `from` address is defined on the email.
-
-</dd>
-
-<dt>
-
-replyTo
-
-</dt>
-
-<dd>
-
-A static global address to use for the `reply-to` property. The global address will be used unless an explicit `replyTo` address is defined on the email.
-
-</dd>
-
-<dt>
-
-mailers
-
-</dt>
-
-<dd>
-
-The `mailers` object is used to configure one or more mailers you want to use for sending emails. You can switch between the mailers at runtime using the `mail.use` method.
-
-</dd>
-
-</dl>
-
-## Transports config
-Following is a complete reference of configuration options accepted by the officially supported transports. 
-
-See also: [TypeScript types for config object](https://github.com/adonisjs/mail/blob/main/src/types.ts#L261)
-
-<div class="disclosure_wrapper">
-
-:::disclosure{title="Mailgun config"}
-<br />
-
-The following configuration options are sent to the Mailgun's [`/messages.mime`](https://documentation.mailgun.com/en/latest/api-sending.html#sending) API endpoint.
-
-```ts
-{
-  mailers: {
-    mailgun: transports.mailgun({
-      baseUrl: 'https://api.mailgun.net/v3',
-      key: env.get('MAILGUN_API_KEY'),
-      domain: env.get('MAILGUN_DOMAIN'),
-
-      /**
-       * The following options can be overridden at
-       * runtime when calling the `mail.send` method.
-       */
-      oDkim: true,
-      oTags: ['transactional', 'adonisjs_app'],
-      oDeliverytime: new Date(2024, 8, 18),
-      oTestMode: false,
-      oTracking: false,
-      oTrackingClick: false,
-      oTrackingOpens: false,
-      headers: {
-        // h:prefixed headers
-      },
-      variables: {
-        appId: '',
-        userId: '',
-        // v:prefixed variables
-      }
-    })
-  }
-}
-```
-
-:::
-
-:::disclosure{title="SMTP config"}
-<br />
-
-The following configuration options are forwarded to Nodemailer as it is. So please check the [Nodemailer documentation](https://nodemailer.com/smtp/) as well.
-
-```ts
-{
-  mailers: {
-    smtp: transports.smtp({
-      host: env.get('SMTP_HOST'),
-      port: env.get('SMTP_PORT'),
-      secure: false,
-
-      auth: {
-        type: 'login',
-        user: env.get('SMTP_USERNAME'),
-        pass: env.get('SMTP_PASSWORD')
-      },
-
-      tls: {},
-
-      ignoreTLS: false,
-      requireTLS: false,
-
-      pool: false,
-      maxConnections: 5,
-      maxMessages: 100,
-    })
-  }
-}
-```
-
-:::
-
-:::disclosure{title="SES config"}
-<br />
-
-The following configuration options are forwarded to Nodemailer as it is. So please check the [Nodemailer documentation](https://nodemailer.com/transports/ses/) as well.
-
-Make sure to install the `@aws-sdk/client-ses` package to use the SES transport.
-
-```ts
-{
-  mailers: {
-    ses: transports.ses({
-      /**
-       * Forwarded to aws sdk
-       */
-      apiVersion: '2010-12-01',
-      region: 'us-east-1',
-      credentials: {
-        accessKeyId: env.get('AWS_ACCESS_KEY_ID'),
-        secretAccessKey: env.get('AWS_SECRET_ACCESS_KEY'),
-      },
-
-      /**
-       * Nodemailer specific
-       */
-      sendingRate: 10,
-      maxConnections: 5,
-    })
-  }
-}
-```
-
-:::
-
-:::disclosure{title="SparkPost config"}
-
-<br />
-
-The following configuration options are sent to the SparkPost's [`/transmissions`](https://developers.sparkpost.com/api/transmissions/#header-request-body) API endpoint.
-
-```ts
-{
-  mailers: {
-    sparkpost: transports.sparkpost({
-      baseUrl: 'https://api.sparkpost.com/api/v1',
-      key: env.get('SPARKPOST_API_KEY'),
-
-      /**
-       * The following options can be overridden at
-       * runtime when calling the `mail.send` method.
-       */
-      startTime: new Date(),
-      openTracking: false,
-      clickTracking: false,
-      initialOpen: false,
-      transactional: true,
-      sandbox: false,
-      skipSuppression: false,
-      ipPool: '',
-    })
-  }
-}
-```
-
-:::
-
-:::disclosure{title="Resend config"}
-<br />
-
-The following configuration options are sent to the Resend's [`/emails`](https://resend.com/docs/api-reference/emails/send-email) API endpoint.
-
-```ts
-{
-  mailers: {
-    resend: transports.resend({
-      baseUrl: 'https://api.resend.com',
-      key: env.get('RESEND_API_KEY'),
-
-      /**
-       * The following options can be overridden at
-       * runtime when calling the `mail.send` method.
-       */
-      tags: [
-        {
-          name: 'category',
-          value: 'confirm_email'
-        }
-      ]
-    })
-  }
-}
-```
-:::
-
-</div>
-
-## Basic example
-
-Once the initial configuration is completed, you may send emails using the `mail.send` method. The mail service is a singleton instance of the [MailManager](https://github.com/adonisjs/mail/blob/main/src/mail_manager.ts) class created using the config file.
-
-The `mail.send` method passes an instance of the [Message](https://github.com/adonisjs/mail/blob/main/src/message.ts) class to the callback and delivers the email using the `default` mailer configured inside the config file.
-
-In the following example, we trigger an email from the controller after creating a new user account.
-
-```ts
-import User from '#models/user'
-import { HttpContext } from '@adonisjs/core/http'
-// highlight-start
-import mail from '@adonisjs/mail/services/main'
-// highlight-end
-
-export default class UsersController {
-  async store({ request }: HttpContext) {
-    /**
-     * For demonstration only. You should validate the data
-     * before storing it inside the database.
-     */
-    const user = await User.create(request.all())
-
-    // highlight-start
-    await mail.send((message) => {
-      message
-        .to(user.email)
-        .from('info@example.org')
-        .subject('Verify your email address')
-        .htmlView('emails/verify_email', { user })
-    })
-    // highlight-end
-  }
-}
-```
-
-## Queueing emails
-Since sending emails can be time-consuming, you might want to push them to a queue and send emails in the background. You can do the same using the `mail.sendLater` method.
-
-The `sendLater` method accepts the same parameters as the `send` method. However, instead of sending the email immediately, it will use the **Mail messenger** to queue it.
-
-```ts
-// delete-start
-await mail.send((message) => {
-// delete-end
-// insert-start
-await mail.sendLater((message) => {
-// insert-end
-  message
-    .to(user.email)
-    .from('info@example.org')
-    .subject('Verify your email address')
-    .htmlView('emails/verify_email', { user })
-})
-```
-
-By default, the **mail messenger uses an in-memory queue**, meaning the queue will drop the jobs if your process dies with pending jobs. This might not be a huge deal if your application UI allows re-sending emails with manual actions. However, you can always configure a custom messenger and use a database-backed queue.
-
-### Using bullmq for queueing emails
-
-```sh
-npm i bullmq
-```
-
-In the following example, we use the `mail.setMessenger` method to configure a custom queue that uses `bullmq` under the hood for storing jobs.
-
-We store the compiled email, runtime configuration, and the mailer name inside the job. Later, we will use this data to send emails inside a worker process.
-
-```ts
-import { Queue } from 'bullmq'
-import mail from '@adonisjs/mail/services/main'
-
-// highlight-start
-const emailsQueue = new Queue('emails')
-// highlight-end
-
-// highlight-start
-mail.setMessenger((mailer) => {
-  return {
-    async queue(mailMessage, config) {
-      await emailsQueue.add('send_email', {
-        mailMessage,
-        config,
-        mailerName: mailer.name,
-      })
-    }
-  }
-})
-// highlight-end
-```
-
-Finally, let's write the code for the queue Worker. Depending on your application workflow, you may have to start another process for the workers to process the jobs.
-
-In the following example:
-
-- We process jobs named `send_email` from the `emails` queue.
-- Access compiled mail message, runtime config, and the mailer name from the job data.
-- And send the email using the `mailer.sendCompiled` method.
-
-```ts
-import { Worker } from 'bullmq'
-import mail from '@adonisjs/mail/services/main'
-
-new Worker('emails', async (job) => {
-  if (job.name === 'send_email') {
-    const {
-      mailMessage,
-      config,
-      mailerName
-    } = job.data
-
-    await mail
-      .use(mailerName)
-      .sendCompiled(mailMessage, config)
-  }
-})
-```
-
-That's all! You may continue using the `mail.sendLater` method. However, the emails will be queued inside a redis database this time.
-
-## Switching between mailers
-You may switch between the configured mailers using the `mail.use` method. The `mail.use` method accepts the name of the mailer (as defined inside the config file) and returns an instance of the [Mailer](https://github.com/adonisjs/mail/blob/main/src/mailer.ts) class.
-
-```ts
-import mail from '@adonisjs/mail/services/main'
-
-mail.use() // Instance of default mailer
-mail.use('mailgun') // Mailgun mailer instance
-```
-
-You may call the `mailer.send` or `mailer.sendLater` methods to send email using a mailer instance. For example:
-
-```ts
-await mail
-  .use('mailgun')
-  .send((message) => {
-  })
-```
-
-```ts
-await mail
-  .use('mailgun')
-  .sendLater((message) => {
-  })
-```
-
-The mailer instances are cached for the lifecycle of the process. You may use the `mail.close` method to destroy an existing instance and re-create a new instance from scratch.
-
-```ts
-import mail from '@adonisjs/mail/services/main'
-
-/**
- * Close transport and remove instance from
- * cache
- */
-await mail.close('mailgun')
-
-/**
- * Create a fresh instance
- */
-mail.use('mailgun')
-```
-
-## Configuring the template engine
-By default, the mail package is configured to use the [Edge template engine](../http/views_and_templates.md#configuring-edge) for defining the email **HTML** and **Plain text** contents.
-
-However, as shown in the following example, you may also register a custom template engine by overriding the `Message.templateEngine` property.
-
-See also: [Defining email contents](./message.md#defining-email-contents)
-
-```ts
-import { Message } from '@adonisjs/mail'
-
-Message.templateEngine = {
-  async render(templatePath, data) {
-    return someTemplateEngine.render(templatePath, data)
-  }
-}
-```
-
-## Events
-Please check the [events reference guide](../reference/events.md#mailsending) to view the list of events dispatched by the `@adonisjs/mail` package.
diff --git a/content/docs/mail/message.md b/content/docs/mail/message.md
deleted file mode 100644
index 849fd8ff..00000000
--- a/content/docs/mail/message.md
+++ /dev/null
@@ -1,422 +0,0 @@
-# Configuring message
-
-The properties of an email are defined using the [Message](https://github.com/adonisjs/mail/blob/main/src/message.ts) class. An instance of this class is provided to the callback function created using the `mail.send`, or `mail.sendLater` methods.
-
-```ts
-import { Message } from '@adonisjs/mail'
-import mail from '@adonisjs/mail/services/main'
-
-await mail.send((message) => {
-  // highlight-start
-  console.log(message instanceof Message) // true
-  // highlight-end
-})
-
-await mail.sendLater((message) => {
-  // highlight-start
-  console.log(message instanceof Message) // true
-  // highlight-end
-})
-```
-
-## Defining subject and sender
-You may define the email subject using the `message.subject` method and the email's sender using the `message.from` method.
-
-```ts
-await mail.send((message) => {
-  message
-  // highlight-start
-    .subject('Verify your email address')
-    .from('info@example.org')
-  // highlight-end
-})
-```
-
-The `from` method accepts the email address as a string or an object with the sender name and the email address.
-
-```ts
-message
-  .from({
-    address: 'info@example.com',
-    name: 'AdonisJS'
-  })
-```
-
-The sender can also be defined globally within the config file. The global sender will be used if no explicit sender is defined for an individual message.
-
-```ts
-const mailConfig = defineConfig({
-  from: {
-    address: 'info@example.com',
-    name: 'AdonisJS'
-  }
-})
-```
-
-## Defining recipients
-You may define the email recipients using the `message.to`, `message.cc`, and the `message.bcc` methods. These methods accept the email address as a string or an object with the recipient name and the email address.
-
-```ts
-await mail.send((message) => {
-  message
-    .to(user.email)
-    .cc(user.team.email)
-    .bcc(user.team.admin.email)
-})
-```
-
-```ts
-await mail.send((message) => {
-  message
-    .to({
-      address: user.email,
-      name: user.fullName,
-    })
-    .cc({
-      address: user.team.email,
-      name: user.team.name,
-    })
-    .bcc({
-      address: user.team.admin.email,
-      name: user.team.admin.fullName,
-    })
-})
-```
-
-You can define multiple `cc` and `bcc` recipients as an array of email addresses or an object with email addresses and the recipient name.
-
-```ts
-await mail.send((message) => {
-  message
-    .cc(['first@example.com', 'second@example.com'])
-    .bcc([
-      {
-        name: 'First recipient',
-        address: 'first@example.com'
-      },
-      {
-        name: 'Second recipient',
-        address: 'second@example.com'
-      }
-    ])
-})
-```
-
-You may also define the `replyTo` email address using the `message.replyTo` method.
-
-```ts
-await mail.send((message) => {
-  message
-    .from('info@example.org')
-    // highlight-start
-    .replyTo('noreply@example.org')
-    // highlight-end
-})
-```
-
-## Defining email contents
-You may define the **HTML** and **Plain text** contents for an email using `message.html` or `message.text` methods.
-
-```ts
-await mail.send((message) => {
-  /**
-   * HTML contents
-   */
-  message.html(`
-    <h1> Verify email address </h1>
-    <p> <a href="https://myapp.com">Click here</a> to verify your email address </a>
-  `)
-
-  /**
-   * Plain text contents
-   */
-  message.text(`
-    Verify email address
-    Please visit https://myapp.com to verify your email address
-  `)
-})
-```
-
-### Using Edge templates
-
-Since writing inline content could be cumbersome, you may use Edge templates instead. If you have already [configured Edge](../http/views_and_templates.md#configuring-edge), you may use the `message.htmlView` and `message.textView` methods to render templates.
-
-```sh
-// title: Create templates
-node ace make:view emails/verify_email_html
-node ace make:view emails/verify_email_text
-```
-
-```ts
-// title: Use them for defining contents
-await mail.send((message) => {
-  message.htmlView('emails/verify_email_html', stateToShare)
-  message.textView('emails/verify_email_text', stateToShare)
-})
-```
-
-### Using MJML for email markup
-MJML is a markup language for creating emails without writing all the complex HTML to make your emails look good in every email client.
-
-The first step is to install the [mjml](https://npmjs.com/mjml) package from npm.
-
-```sh
-npm i mjml
-```
-
-Once done, you can write MJML markup inside your Edge templates by wrapping it inside the `@mjml` tag.
-
-:::note
-
-Since the output of MJML contains the `html`, `head`, and `body` tags, it is unnecessary to define them within your Edge templates.
-
-:::
-
-```edge
-@mjml()
-  <mjml>
-    <mj-body>
-      <mj-section>
-        <mj-column>
-          <mj-text>
-            Hello World!
-          </mj-text>
-        </mj-column>
-      </mj-section>
-    </mj-body>
-  </mjml>
-@end
-```
-
-You may pass the [MJML configuration options](https://documentation.mjml.io/#inside-node-js) as props to the `@mjml` tag.
-
-```edge
-@mjml({
-  keepComments: false,
-  fonts: {
-    Lato: 'https://fonts.googleapis.com/css?family=Lato:400,500,700'
-  }
-})
-```
-
-## Attaching files
-You may use the `message.attach` method to send attachments in an email. The `attach` method accepts an absolute path or a file system URL of a file you want to send as an attachment.
-
-```ts
-import app from '@adonisjs/core/services/app'
-
-await mail.send((message) => {
-  message.attach(app.makePath('uploads/invoice.pdf'))
-})
-```
-
-You may define the filename for the attachment using the `options.filename` property.
-
-```ts
-message.attach(app.makePath('uploads/invoice.pdf'), {
-  filename: 'invoice_october_2023.pdf'
-})
-```
-
-The complete list of options accepted by the `message.attach` method follows.
-
-<table>
-<thead>
-<tr>
-<th>Option</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody><tr>
-<td><code>filename</code></td>
-<td>The display name for the attachment. Defaults to the basename of the attachment path.</td>
-</tr>
-<tr>
-<td><code>contentType</code></td>
-<td>The content type for the attachment. If not set, the <code>contentType</code> will be inferred from the file extension.</td>
-</tr>
-<tr>
-<td><code>contentDisposition</code></td>
-<td>Content disposition type for the attachment. Defaults to <code>attachment</code></td>
-</tr>
-<tr>
-<td><code>headers</code></td>
-<td>
-<p>Custom headers for the attachment node. The headers property is a key-value pair</p>
-</td>
-</tr>
-</tbody></table>
-
-### Attaching files from streams and buffers
-You may create email attachments from streams and buffers using the `message.attachData` method. The method accepts a readable stream or the buffer as the first argument and the options object as the second argument.
-
-:::note
-
-The `message.attachData` method should not be used when queueing emails using the `mail.sendLater` method. Since queued jobs are serialized and persisted inside a database, attaching raw data will increase the storage size.
-
-Moreover, queueing an email will fail if you attach a stream using the `message.attachData` method.
-:::
-
-```ts
-message.attach(fs.createReadStream('./invoice.pdf'), {
-  filename: 'invoice_october_2023.pdf'
-})
-```
-
-```ts
-message.attach(Buffer.from('aGVsbG8gd29ybGQh'), {
-  encoding: 'base64',
-  filename: 'greeting.txt',
-})
-```
-
-## Embedding images
-You may embed images within the contents of your email using the `embedImage` view helper. The `embedImage` method under the hood uses [CID](https://sendgrid.com/en-us/blog/embedding-images-emails-facts#1-cid-embedded-images-inline-images) to mark the image as an attachment and uses its content id as the source of the image.
-
-```edge
-<img src="{{
-  embedImage(app.makePath('assets/hero.jpg'))
-}}" />
-```
-
-Following will be the output HTML
-
-```html
-<img src="cid:a-random-content-id" />
-```
-
-The following attachment will be defined automatically on the email payload.
-
-```ts
-{
-  attachments: [{
-    path: '/root/app/assets/hero.jpg',
-    filename: 'hero.jpg',
-    cid: 'a-random-content-id'
-  }]
-}
-```
-
-### Embedding images from buffers
-
-Like the `embedImage` method, you may use the `embedImageData` method to embed an image from raw data.
-
-```edge
-<img src="{{
-  embedImageData(rawBuffer, { filename: 'hero.jpg' })
-}}" />
-```
-
-## Attaching calendar events
-You may attach calendar events to an email using the `message.icalEvent` method. The `icalEvent` method accepts the event contents as the first parameter and the `options` object as the second parameter.
-
-```ts
-const contents = 'BEGIN:VCALENDAR\r\nPRODID:-//ACME/DesktopCalendar//EN\r\nMETHOD:REQUEST\r\n...'
-
-await mail.send((message) => {
-  message.icalEvent(contents, {
-    method: 'PUBLISH',
-    filename: 'invite.ics',
-  })
-})
-```
-
-Since defining the event file contents manually can be cumbersome, you may pass a callback function to the `icalEvent` method and generate the invite contents using JavaScript API.
-
-The `calendar` object provided to the callback function is a reference of the [ical-generator](https://www.npmjs.com/package/ical-generator) npm package, so make sure to go through the package's README file as well.
-
-```ts
-message.icalEvent((calendar) => {
-  // highlight-start
-  calendar
-    .createEvent({
-      summary: 'Adding support for ALS',
-      start: DateTime.local().plus({ minutes: 30 }),
-      end: DateTime.local().plus({ minutes: 60 }),
-    })
-  // highlight-end
-}, {
-  method: 'PUBLISH',
-  filename: 'invite.ics',
-})
-```
-
-### Reading invite contents from a file or a URL
-You may define the invite contents from a file or an HTTP URL using the `icalEventFromFile` or `icalEventFromUrl` methods.
-
-```ts
-message.icalEventFromFile(
-  app.resourcesPath('calendar-invites/invite.ics'),
-  {
-    filename: 'invite.ics',
-    method: 'PUBLISH'
-  }
-)
-```
-
-```ts
-message.icalEventFromFile(
-  'https://myapp.com/users/1/invite.ics',
-  {
-    filename: 'invite.ics',
-    method: 'PUBLISH'
-  }
-)
-```
-
-## Defining email headers
-You may define additional email headers using the `message.header` method. The method accepts the header key as the first parameter and the value as the second parameter.
-
-```ts
-message.header('x-my-key', 'header value')
-
-/**
- * Define an array of values
- */
-message.header('x-my-key', ['header value', 'another value'])
-```
-
-By default, the email headers are encoded and folded to meet the requirement of having plain ASCII messages with lines no longer than 78 bytes. However, if you want to bypass the encoding rules, you may set a header using the `message.preparedHeader` method.
-
-```ts
-message.preparedHeader(
-  'x-unprocessed',
-  'a really long header or value with non-ascii characters 👮',
-)
-```
-
-## Defining `List` headers
-The message class includes helper methods to define complex headers like [List-Unsubscribe](https://sendgrid.com/en-us/blog/list-unsubscribe) or [List-Help](https://support.optimizely.com/hc/en-us/articles/4413200569997-Setting-up-the-List-Help-header#heading-2) with ease. You can learn about the encoding rules for `List` headers on the [nodemailer website](https://nodemailer.com/message/list-headers/).
-
-```ts
-message.listHelp('admin@example.com?subject=help')
-// List-Help: <mailto:admin@example.com?subject=help>
-```
-
-```ts
-message.listUnsubscribe({
-  url: 'http://example.com',
-  comment: 'Comment'
-})
-// List-Unsubscribe: <http://example.com> (Comment)
-```
-
-```ts
-/**
- * Repeating header multiple times
- */
-message.listSubscribe('admin@example.com?subject=subscribe')
-message.listSubscribe({
-  url: 'http://example.com',
-  comment: 'Subscribe'
-})
-// List-Subscribe: <mailto:admin@example.com?subject=subscribe>
-// List-Subscribe: <http://example.com> (Subscribe)
-```
-
-For all other arbitrary `List` headers, you may use the `addListHeader` method.
-
-```ts
-message.addListHeader('post', 'http://example.com/post')
-// List-Post: <http://example.com/post>
-```
diff --git a/content/docs/forms_and_validation/custom_messages.md b/content/docs/old/forms_and_validation/custom_messages.md
similarity index 100%
rename from content/docs/forms_and_validation/custom_messages.md
rename to content/docs/old/forms_and_validation/custom_messages.md
diff --git a/content/docs/forms_and_validation/pika-1675149043774-1x.jpeg b/content/docs/old/forms_and_validation/pika-1675149043774-1x.jpeg
similarity index 100%
rename from content/docs/forms_and_validation/pika-1675149043774-1x.jpeg
rename to content/docs/old/forms_and_validation/pika-1675149043774-1x.jpeg
diff --git a/content/docs/forms_and_validation/schema_101.md b/content/docs/old/forms_and_validation/schema_101.md
similarity index 100%
rename from content/docs/forms_and_validation/schema_101.md
rename to content/docs/old/forms_and_validation/schema_101.md
diff --git a/content/docs/forms_and_validation/validating_api_requests.md b/content/docs/old/forms_and_validation/validating_api_requests.md
similarity index 100%
rename from content/docs/forms_and_validation/validating_api_requests.md
rename to content/docs/old/forms_and_validation/validating_api_requests.md
diff --git a/content/docs/forms_and_validation/validating_server_rendered_forms.md b/content/docs/old/forms_and_validation/validating_server_rendered_forms.md
similarity index 100%
rename from content/docs/forms_and_validation/validating_server_rendered_forms.md
rename to content/docs/old/forms_and_validation/validating_server_rendered_forms.md
diff --git a/content/docs/forms_and_validation/validation.md b/content/docs/old/forms_and_validation/validation.md
similarity index 92%
rename from content/docs/forms_and_validation/validation.md
rename to content/docs/old/forms_and_validation/validation.md
index f8a54cee..f6a447f1 100644
--- a/content/docs/forms_and_validation/validation.md
+++ b/content/docs/old/forms_and_validation/validation.md
@@ -14,7 +14,7 @@ The data validation layer in AdonisJS is framework agnostic, and you can use any
 
 ## Basic example
 
-Following is a basic example of creating a validation schema and using the `request.validate` method to perform the validation. Make sure to read our dedicated guides on [validating server-rendered forms](./validating_server_rendered_forms.md) and [validating API requests](./validating_api_requests.md).
+Following is a basic example of creating a validation schema and using the `request.validate` method to perform the validation. Make sure to read our dedicated guides on [validating server-rendered forms](validating_server_rendered_forms.md) and [validating API requests](validating_api_requests.md).
 
 ```ts
 import router from '@adonisjs/core/services/router'
@@ -95,5 +95,5 @@ The schema methods like `schema.number`, or `schema.boolean` perform validations
 
 ## Next steps
 
-- Read guides on [validating server-rendered forms](./validating_server_rendered_forms.md) and [validating API requests](./validating_api_requests.md).
-- Learn everything about the [creating validation schemas](./schema_101.md).
+- Read guides on [validating server-rendered forms](validating_server_rendered_forms.md) and [validating API requests](validating_api_requests.md).
+- Learn everything about the [creating validation schemas](schema_101.md).
diff --git a/content/docs/forms_and_validation/validator-static-types.webp b/content/docs/old/forms_and_validation/validator-static-types.webp
similarity index 100%
rename from content/docs/forms_and_validation/validator-static-types.webp
rename to content/docs/old/forms_and_validation/validator-static-types.webp
diff --git a/content/docs/fundamentals/package_development.md b/content/docs/old/fundamentals/package_development.md
similarity index 87%
rename from content/docs/fundamentals/package_development.md
rename to content/docs/old/fundamentals/package_development.md
index 7e49d0fa..07cdb721 100644
--- a/content/docs/fundamentals/package_development.md
+++ b/content/docs/old/fundamentals/package_development.md
@@ -16,9 +16,9 @@ We assume you know how to create and publish a package on npm and have basic kno
 
 When creating a package, ensure your package's source code is not tightly coupled with the AdonisJS application runtime. For example:
 
-- Inside an AdonisJS application, you can import the router using the `@adonisjs/core/services/router` service. Whereas your package should accept the same router via Dependency injection. **In fact, packages should never import [container services](./container_services.md)**.
+- Inside an AdonisJS application, you can import the router using the `@adonisjs/core/services/router` service. Whereas your package should accept the same router via Dependency injection. **In fact, packages should never import [container services](../../concepts/container_services.md)**.
 
-- Similarly, inside an AdonisJS application, you can import config files from the `config` directory. Whereas your package should read the config using the [Config provider](../guides/config.md#reading-config-inside-service-providers).
+- Similarly, inside an AdonisJS application, you can import config files from the `config` directory. Whereas your package should read the config using the [Config provider](../../getting_started/configuration#reading-config-inside-service-providers).
 
 - You should not use the `@inject` decorator inside your packages. There is an alternative API to inject dependencies inside a class automatically.
 
@@ -53,7 +53,7 @@ Refer to the [README file of the starter kit](https://github.com/adonisjs/pkg-st
 ## Using service providers
 Service providers acts as a bridge between your package and an AdonisJS application. You can use service providers to provide dependencies to your package source code, register bindings to the container, or extend the framework using the `boot` method lifecycle hook.
 
-See also: [Service providers](./service_providers.md) and [Extending the framework](./extending_the_framework.md).
+See also: [Service providers](../../concepts/service_providers.md) and [Extending the framework](../../concepts/extending_the_framework.md).
 
 ### Automatically injecting dependencies
 Inside an AdonisJS application you can use the `@inject` decorator to inject dependencies to a class constructor. Whereas, when creating a package, we recommend not using the decorator and instead use the `container.bind` method to customize the construction of a class.
@@ -99,7 +99,7 @@ export default class MyPackageProvider {
 You can repeat this process for any class that is constructed using the container. Be it the middleware, controllers, event listeners and so on.
 
 ### Registering singleton services
-If your package has certain classes that should have only one instance throughout the lifecycle of the application, you can bind them to the container and export them as [container services](./container_services.md).
+If your package has certain classes that should have only one instance throughout the lifecycle of the application, you can bind them to the container and export them as [container services](../../concepts/container_services.md).
 
 A great example of the same is the HTTP router shipped with the framework core. Since, a typical AdonisJS application needs a single instance of the [Router class](https://github.com/adonisjs/http-server/blob/main/src/router/main.ts), we [register it as a singleton](https://github.com/adonisjs/core/blob/main/providers/http_provider.ts#L39-L44) inside the container.
 
@@ -152,7 +152,7 @@ import cache from 'my-package/services/cache'
 ```
 
 ## Exporting middleware
-You must export [HTTP middleware](../http/middleware.md) classes using `export default`. This will allow the package consumers to drop the import path inside the middleware collection array.
+You must export [HTTP middleware](../../basics/middleware.md) classes using `export default`. This will allow the package consumers to drop the import path inside the middleware collection array.
 
 In the following example, we export a `LogRequests` middleware from the `./middleware/log_requests.ts` file. Also, we define the public import path using [Node.js subpath exports](https://nodejs.org/api/packages.html#subpath-exports).
 
@@ -186,7 +186,7 @@ router.use([
 ```
 
 ## Exporting controllers
-You must export [HTTP controller](../http/controllers.md) classes using `export default`. This will allow the package consumers to drop the import path inside the route definition.
+You must export [HTTP controller](../../basics/controllers.md) classes using `export default`. This will allow the package consumers to drop the import path inside the route definition.
 
 In the following example, we export an `InvoicesController` class from the `./controllers/invoices_controller.ts` file. Also, we define the public import path using Node.js subpath exports.
 
@@ -224,7 +224,7 @@ router.post('invoices', [InvoicesController, 'store'])
 ```
 
 ## Exporting commands
-You may ship [Ace commands](../ace/introduction.md) as part of your package by creating them inside the `commands` directory. If you are using the [package starter kit](https://github.com/adonisjs/pkg-starter-kit), we will create a manifest file (containing commands meta-data) for your commands automatically during the build process. The manifest file is used to improve the initial load time of Ace.
+You may ship [Ace commands](../../ace/introduction.md) as part of your package by creating them inside the `commands` directory. If you are using the [package starter kit](https://github.com/adonisjs/pkg-starter-kit), we will create a manifest file (containing commands meta-data) for your commands automatically during the build process. The manifest file is used to improve the initial load time of Ace.
 
 ## Defining routes
 
diff --git a/content/docs/http/assets_bundling_encore.md b/content/docs/old/http/assets_bundling_encore.md
similarity index 100%
rename from content/docs/http/assets_bundling_encore.md
rename to content/docs/old/http/assets_bundling_encore.md
diff --git a/content/docs/pages/adonisjs-at-a-glance.md b/content/docs/old/pages/adonisjs-at-a-glance.md
similarity index 100%
rename from content/docs/pages/adonisjs-at-a-glance.md
rename to content/docs/old/pages/adonisjs-at-a-glance.md
diff --git a/content/docs/resources/updates.md b/content/docs/old/resources/updates.md
similarity index 100%
rename from content/docs/resources/updates.md
rename to content/docs/old/resources/updates.md
diff --git a/content/docs/tutorial/creating-new-application.md b/content/docs/old/tutorial/creating-new-application.md
similarity index 100%
rename from content/docs/tutorial/creating-new-application.md
rename to content/docs/old/tutorial/creating-new-application.md
diff --git a/content/docs/tutorial/introduction.md b/content/docs/old/tutorial/introduction.md
similarity index 100%
rename from content/docs/tutorial/introduction.md
rename to content/docs/old/tutorial/introduction.md
diff --git a/content/docs/validator/custom_messages.md b/content/docs/old/validator/custom_messages.md
similarity index 100%
rename from content/docs/validator/custom_messages.md
rename to content/docs/old/validator/custom_messages.md
diff --git a/content/docs/validator/custom_rules.md b/content/docs/old/validator/custom_rules.md
similarity index 100%
rename from content/docs/validator/custom_rules.md
rename to content/docs/old/validator/custom_rules.md
diff --git a/content/docs/validator/error_reporters.md b/content/docs/old/validator/error_reporters.md
similarity index 98%
rename from content/docs/validator/error_reporters.md
rename to content/docs/old/validator/error_reporters.md
index 0949d37c..f408ca12 100644
--- a/content/docs/validator/error_reporters.md
+++ b/content/docs/old/validator/error_reporters.md
@@ -6,7 +6,7 @@ Error formatters are helpful when you are writing an API server following a pre-
 Without error formatters, you have to manually loop over the error messages and re-shape them as per the spec followed by your API team. At the same time, error formatters expose an API to collect and structure error messages within the validation lifecycle (without any extra performance overhead).
 
 ## Using error reporters
-The validations performed using the `request.validate` method uses content negotiation to [find the best possible error reporter](./introduction.md#server-rendered-app) for a given HTTP request.
+The validations performed using the `request.validate` method uses content negotiation to [find the best possible error reporter](introduction.md#server-rendered-app) for a given HTTP request.
 
 However, you can also define the error reporter explicitly, which will turn off the content negotiation checks.
 
diff --git a/content/docs/validator/introduction.md b/content/docs/old/validator/introduction.md
similarity index 100%
rename from content/docs/validator/introduction.md
rename to content/docs/old/validator/introduction.md
diff --git a/content/docs/validator/schema_caching.md b/content/docs/old/validator/schema_caching.md
similarity index 100%
rename from content/docs/validator/schema_caching.md
rename to content/docs/old/validator/schema_caching.md
diff --git a/content/docs/validator/schema_types.md b/content/docs/old/validator/schema_types.md
similarity index 100%
rename from content/docs/validator/schema_types.md
rename to content/docs/old/validator/schema_types.md
diff --git a/content/docs/validator/validation_rules.md b/content/docs/old/validator/validation_rules.md
similarity index 100%
rename from content/docs/validator/validation_rules.md
rename to content/docs/old/validator/validation_rules.md
diff --git a/content/docs/preface/contribution_guide.md b/content/docs/preface/contribution_guide.md
new file mode 100644
index 00000000..a9470460
--- /dev/null
+++ b/content/docs/preface/contribution_guide.md
@@ -0,0 +1,113 @@
+# Contributing
+This is a general contribution guide for all of the [AdonisJS](https://github.com/adonisjs) repos. Please read this guide thoroughly before contributing to any of the repos 🙏
+
+Code is not the only way to contribute. Following are also some ways to contribute and become part of the community.
+
+- Fixing typos in the documentation
+- Improving existing docs
+- Writing cookbooks or blog posts to educate others in the community
+- Triaging issues
+- Sharing your opinion on existing issues
+- Help the community in discord and the discussions forum
+
+## Reporting bugs
+Many issues reported on open source projects are usually questions or misconfiguration at the reporter's end. Therefore, we highly recommend you properly troubleshoot your issues before reporting them.
+
+If you're reporting a bug, include as much information as possible with the code samples you have written. The scale of good to bad issues looks as follows.
+
+- **PERFECT ISSUE**: You isolate the underlying bug. Create a failing test in the repo and open a Github issue around it.
+- **GOOD ISSUE**: You isolate the underlying bug and provide a minimal reproduction of it as a Github repo. Antfu has written a great article on [Why Reproductions are Required](https://antfu.me/posts/why-reproductions-are-required).
+- **DECENT ISSUE**: You correctly state your issue. Share the code that produces the issue in the first place. Also, include the related configuration files and the package version you use.
+
+  Last but not least is to format every code block properly by following the [Github markdown syntax guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax).
+
+- **POOR ISSUE**: You dump the question you have with the hope that the other person will ask the relevant questions and help you. These kinds of issues are closed automatically without any explanation.
+
+## Having a discussion
+You often want to discuss a topic or maybe share some ideas. In that case, create a discussion in the discussions forum under the **💡Ideas** category.
+
+## Educating others
+Educating others is one of the best ways to contribute to any community and earn recognition.
+
+You can use the **📚 Cookbooks** category on our discussion forum to share an article with others. The cookbooks section is NOT strictly moderated, except the shared knowledge should be relevant to the project.
+
+## Creating pull requests
+It is never a good experience to have your pull request declined after investing a lot of time and effort in writing the code. Therefore, we highly recommend you to [kick off a discussion](https://github.com/orgs/adonisjs/discussions) before starting any new work on your side.
+
+Just start a discussion and explain what are you planning to contribute?
+
+- **Are you trying to create a PR to fix a bug**: PRs for bugs are mostly accepted once the bug has been confirmed.
+- **Are you planning to add a new feature**: Please thoroughly explain why this feature is required and share links to the learning material we can read to educate ourselves.
+
+  For example: If you are adding support for snapshot testing to Japa or AdonisJS. Then share the links I can use to learn more about snapshot testing in general.
+
+> Note: You should also be available to open additional PRs for documenting the contributed feature or improvement.
+
+## Repository setup
+
+1. Start by cloning the repo on your local machine.
+
+    ```sh
+    git clone <REPO_URL>
+    ```
+
+2. Install dependencies on your local. Please do not update any dependencies along with a feature request. If you find stale dependencies, create a separate PR to update them.
+
+   We use `npm` for managing dependencies, therefore do not use `yarn` or any other tool.
+
+    ```sh
+    npm install
+    ```
+
+3. Run tests by executing the following command.
+
+    ```sh
+    npm test
+    ```
+
+## Tools in use
+Following is the list of tools in use.
+
+| Tool                   | Usage                                                                                                                                                                                                                                                                  |
+|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| TypeScript             | All of the repos are authored in TypeScript. The compiled JavaScript and Type-definitions are published on npm.                                                                                                                                                        |
+| TS Node                | We use [ts-node](https://typestrong.org/ts-node/) to run tests or scripts without compiling TypeScript. The main goal of ts-node is to have a faster feedback loop during development                                                                                  |
+| SWC                    | [SWC](https://swc.rs/) is a Rust based TypeScript compiler. TS Node ships with first-class support for using SWC over the TypeScript official compiler. The main reason for using SWC is the speed gain.                                                               |
+| Release-It             | We use [release-it](https://github.com/release-it/release-it) to publish our packages on npm. It does all the heavy lifting of creating a release and publishes it on npm and Github. Its config is defined within the `package.json` file.                            |
+| ESLint                 | ESLint helps us enforce a consistent coding style across all the repos with multiple contributors. All our ESLint rules are published under the [eslint-plugin-adonis](https://github.com/adonisjs-community/eslint-plugin-adonis) package.                            |
+| Prettier               | We use prettier to format the codebase for consistent visual output. If you are confused about why we are using ESLint and Prettier both, then please read [Prettier vs. Linters](https://prettier.io/docs/en/comparison.html) doc on the Prettier website.            |
+| EditorConfig           | The `.editorconfig` file in the root of every project configures your Code editor to use a set of rules for indentation and whitespace management. Again, Prettier is used for post formatting your code, and Editorconfig is used to configure the editor in advance. |
+| Conventional Changelog | All of the commits across all the repos uses [commitlint](https://github.com/conventional-changelog/commitlint/#what-is-commitlint) to enforce consistent commit messages.                                                                                             |
+| Husky                  | We use [husky](https://typicode.github.io/husky/#/) to enforce commit conventions when committing the code. Husky is a git hooks system written in Node                                                                                                                |
+
+## Commands
+
+| Command | Description |
+|-------|--------|
+| `npm run test` | Run project tests using `ts-node` |
+| `npm run compile` | Compile the TypeScript project to JavaScript. The compiled output is written inside the `build` directory |
+| `npm run release` | Start the release process using `np` |
+| `npm run lint` | Lint the codebase using ESlint |
+| `npm run format` | Format the codebase using Prettier | 
+| `npm run sync-labels` | Sync the labels defined inside the `.github/labels.json` file with Github. This command is for the project admin only. |
+
+## Coding style
+All of our projects are written in TypeScript and are moving to pure ESM.
+
+- You can learn more about [my coding style here](https://github.com/thetutlage/meta/discussions/3)
+- Check out the setup I follow for [ESM and TypeScript here](https://github.com/thetutlage/meta/discussions/2)
+
+Also, make sure to run the following commands before pushing the code.
+
+```sh
+# Formats using prettier
+npm run format
+
+# Lints using Eslint
+npm run lint
+```
+
+## Getting recognized as a contributor
+We rely on GitHub to list all the repo contributors in the right-side panel of the repo. Following is an example of the same.
+
+Also, we use the [auto generate release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#about-automatically-generated-release-notes) feature of Github, which adds a reference to the contributor profile within the release notes.
diff --git a/content/docs/guides/faqs.md b/content/docs/preface/faqs.md
similarity index 93%
rename from content/docs/guides/faqs.md
rename to content/docs/preface/faqs.md
index 7f9be3e6..5e6bc0e2 100644
--- a/content/docs/guides/faqs.md
+++ b/content/docs/preface/faqs.md
@@ -14,7 +14,7 @@ AdonisJS (the framework) and the official packages are distributed under the [MI
 
 ## Is AdonisJS reliable and well-maintained?
 
-AdonisJS is used in production by [Marie Claire](https://www.marieclaire.com/), [Cleavr](https://cleavr.io), [Ledger](https://www.ledger.com/), [Cavai](https://cavai.com), [Kayako](https://kayako.com), [Renault Group](https://www.renaultgroup.com/en/), [Zakodium](https://www.zakodium.com/), [FIVB](https://www.fivb.com/en), and many more companies in varying capacities.
+AdonisJS is used in production by [Marie Claire](https://www.marieclaire.com/), [Cleavr](https://cleavr.io), [Ledger](https://www.ledger.com/), [Cavai](https://cavai.com), [Kayako](https://kayako.com), [Renault Group](https://www.renaultgroup.com/en/), [Zakodium](https://www.zakodium.com/), [FIVB](https://www.fivb.com), and many more companies in varying capacities.
 
 The framework creator works full-time on AdonisJS and ensures the framework is actively improved and maintained.
 
@@ -39,6 +39,6 @@ Check out the following links to stay connected and up-to-date.
 
 - [Discord server](https://discord.gg/vDcEjq6)
 - [X (Formerly Twitter)](https://twitter.com/adonisframework)
-- [GitHub discussions](https://github.com/adonisjs/core/discussions)
+- [GitHub discussions](https://github.com/orgs/adonisjs/discussions)
 - [Blog and Newsletter](https://adonisjs.com/blog?referrer=adonisjs_docs_faq)
 - [Adocasts](https://adocasts.com/?referrer=adonisjs_docs_faq)
diff --git a/content/docs/preface/governance.md b/content/docs/preface/governance.md
new file mode 100644
index 00000000..5d9c9d2c
--- /dev/null
+++ b/content/docs/preface/governance.md
@@ -0,0 +1,104 @@
+# Governance
+
+## Roles and responsibilities
+
+### Authors
+
+Harminder Virk (the creator of AdonisJS) serves as the Project Author. The project author is responsible for the project's governance, standards, and direction. To summarize:
+
+- The project author decides which new projects should live under the AdonisJS umbrella.
+- The project author is responsible for assigning leads to projects and transferring projects to a new lead when an existing lead steps down.
+- It is the author's responsibility to share/document the framework's vision and keep project leads in sync with the same.
+
+### Project Leads
+
+AdonisJS is a combination of several packages created and managed by the core team. All of these packages are led by a project lead selected by the project Author.
+
+In almost every case, the creator of the package serves as the project lead since they are the ones who have put the initial efforts into bringing the idea to life.
+
+The project lead has the final say in all aspects of decision-making within the project. However, because the community always has the ability to fork, this person is fully answerable to the community. It is the project lead's responsibility to set the strategic objectives of the project and communicate these clearly to the community. They also have to understand the community as a whole and strive to satisfy as many conflicting needs as possible while ensuring that the project survives in the long term.
+
+In many ways, the role of the project lead is about diplomacy. The key is to ensure that, as the project expands, the right people are given influence over it, and the community rallies behind the vision of the project lead. The lead's job is then to ensure that the core team members (see below) make the right decisions on behalf of the project. Generally speaking, as long as the core team members are aligned with the project's strategy, the project lead will allow them to proceed as desired.
+
+:::note
+A project lead cannot archive or decide to remove the project from the AdonisJS umbrella. They can decide to stop working on the project, and in that case, we will find a new project lead.
+:::
+
+### Core team
+
+Members of the core team are contributors who have made multiple valuable contributions to the project and are now relied upon to both write code directly to the repository and screen the contributions of others. In many cases, they are programmers, but it is also possible that they contribute in a different role, for example, community engagement. Typically, a core team member will focus on a specific aspect of the project and will bring a level of expertise and understanding that earns them the respect of the community and the project lead. The role of core team member is not an official one, it is simply a position that influential members of the community will find themselves in as the project lead looks to them for guidance and support.
+
+Core team members have no authority over the overall direction of the project. However, they do have the ear of the project lead. It is a core team member's job to ensure that the lead is aware of the community's needs and collective objectives, and to help develop or elicit appropriate contributions to the project. Often, core team members are given informal control over their specific areas of responsibility, and are assigned rights to directly modify certain areas of the source code. That is, although core team members do not have explicit decision-making authority, they will often find that their actions are synonymous with the decisions made by the lead.
+
+#### Active Core Team Members
+
+Active Core Team Members contribute to the project on a regular basis. An active core team member usually has or more focus areas - in the most common cases, they will be responsible for the regular issue triaging, bug fixing, documentation improvements or feature development in a subproject repository.
+
+#### Core Team Emeriti
+
+Some core team members who have made valuable contributions in the past may no longer be able to commit to the same level of participation today due to various reasons. That is perfectly normal, and any past contributions to the project are still highly appreciated. These core team members are honored for their contributions as Core Team Emeriti, and are welcome to resume active participation at any time.
+
+### Contributors
+
+Contributors are community members who either have no desire to become core team members, or have not yet been given the opportunity by the project lead. They make valuable contributions, such as those outlined in the list below, but generally do not have the authority to make direct changes to the project code. Contributors engage with the project through communication tools, such as the RFC discussions, GitHub issues and pull requests, Discord chatroom, and the forum.
+
+Anyone can become a contributor. There is no expectation of commitment to the project, no specific skill requirements and no selection process. To become a contributor, a community member simply has to perform one or more actions that are beneficial to the project.
+
+Some contributors will already be engaging with the project as users, but will also find themselves doing one or more of the following:
+
+- Supporting new users (current users often provide the most effective new user support)
+- Reporting bugs
+- Identifying requirements
+- Programming
+- Assisting with project infrastructure
+- Fixing bugs
+- Adding features
+
+As contributors gain experience and familiarity with the project, they may find that the project lead starts relying on them more and more. When this begins to happen, they gradually adopt the role of core team member, as described above.
+
+### Users
+
+Users are community members who have a need for the project. They are the most important members of the community: without them, the project would have no purpose. Anyone can be a user; there are no specific requirements.
+
+Users should be encouraged to participate in the life of the project and the community as much as possible. User contributions enable the project team to ensure that they are satisfying the needs of those users. Common user activities include (but are not limited to):
+
+- Evangelizing about the project.
+- Informing developers of project strengths and weaknesses from a new user's perspective.
+- Providing moral support (a 'thank you' goes a long way).
+- Providing financial support through GitHub Sponsors.
+
+Users who continue to engage with the project and its community will often find themselves becoming more and more involved. Such users may then go on to become contributors, as described above.
+
+## Support
+
+All participants in the community are encouraged to provide support for new users within the project management infrastructure. This support is provided as a way of growing the community. Those seeking support should recognize that all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring guaranteed response times or results should therefore seek to purchase a support contract. However, for those willing to engage with the project on its terms, and willing to help support other users, the community support channels are ideal.
+
+### Monetary Donations
+
+For an open development project, money is less important than active contribution. However, some people or organizations are cash-rich and time-poor and would prefer to make their contribution in the form of cash. If you want to make a significant donation, you may be able to sponsor us to implement a new feature or fix some bugs. The project website provides clear guidance on how to go about donating.
+
+If you run a business using the project as a revenue-generating product, it makes business sense to sponsor its development. It ensures the project that your product relies on stays healthy and actively maintained. It can also improve exposure in our community and make it easier to attract new developers.
+
+## Branding and Ownership
+
+AdonisJS (spelled with "JS" at the end) is a registered trademark of Harminder Virk.
+
+Only the projects under the `@adonisjs` npm scope and the AdonisJS GitHub organization are managed and officially supported by the core team.
+
+Also, you must not use the AdonisJS name or logos in a way that could mistakenly imply any official connection with or endorsement of AdonisJS. Any use of the AdonisJS name or logos in a manner that could cause customer confusion is not permitted.
+
+This includes naming a product or service in a way that emphasizes the AdonisJS brand, like "AdonisJS UIKit" or "AdonisJS Studio", as well as in domain names like "adonisjs-studio.com".
+
+Instead, you must use your own brand name in a way that clearly distinguishes it from AdonisJS.
+
+Additionally, you may not use our trademarks for t-shirts, stickers, or other merchandise without explicit written consent.
+
+## Projects under AdonisJS umbrella
+
+Projects under the AdonisJS umbrella are the intellectual property of the Project Author. Once a project created by a project lead becomes part of the "AdonisJS GitHub organization," or if it is published under the `@adonisjs` npm scope, the project leads cannot delete or abandon the project.
+
+---
+
+:::note
+This governance document is based upon the [Benevolent Dictator Governance Model](http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel) by Ross Gardler and Gabriel Hanganu, licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/). This document itself is also licensed under the same license.
+:::
diff --git a/content/docs/guides/introduction.md b/content/docs/preface/introduction.md
similarity index 83%
rename from content/docs/guides/introduction.md
rename to content/docs/preface/introduction.md
index e4e62841..bd69c1e3 100644
--- a/content/docs/guides/introduction.md
+++ b/content/docs/preface/introduction.md
@@ -6,7 +6,7 @@
 
 AdonisJS is a TypeScript-first web framework for Node.js. You can use it to create a full-stack web application or a JSON API server.
 
-At the fundamental level, AdonisJS [provides structure to your applications](./folder_structure.md), configures a [seamless TypeScript development environment](../fundamentals/typescript_build_process.md), configures [HMR](../fundamentals/hmr.md) for your backend code, and offers a vast collection of well-maintained and extensively documented packages.
+At the fundamental level, AdonisJS [provides structure to your applications](../getting_started/folder_structure.md), configures a [seamless TypeScript development environment](../concepts/typescript_build_process.md), configures [HMR](../concepts/hmr.md) for your backend code, and offers a vast collection of well-maintained and extensively documented packages.
 
 We envision teams using AdonisJS **spending less time** on trivial decisions like cherry-picking npm packages for every minor feature, writing glue code, debating for the perfect folder structure, and **spending more time** delivering real-world features critical for the business needs.
 
@@ -14,7 +14,7 @@ We envision teams using AdonisJS **spending less time** on trivial decisions lik
 
 AdonisJS focuses on the backend and lets you choose the frontend stack of your choice.
 
-If you like to keep things simple, pair AdonisJS with a [traditional template engine](../http/views_and_templates.md) to generate static HTML on the server. Or create a JSON API for your frontend Vue/React application.
+If you like to keep things simple, pair AdonisJS with a [traditional template engine](../views-and-templates/introduction) to generate static HTML on the server. Or create a JSON API for your frontend Vue/React application.
 
 AdonisJS aims to provide you with batteries to create a robust backend application from scratch. Be it sending emails, validating user input, performing CRUD operations, or authenticating users. We take care of it all.
 
@@ -26,8 +26,8 @@ AdonisJS is built on top of modern JavaScript primitives. We use ES modules, Nod
 Also, TypeScript plays a considerable role when designing the framework's APIs. For example, AdonisJS has:
 
 - [Type-safe event emitter](../digging_deeper/emitter.md#making-events-type-safe)
-- [Type-safe environment variables](./env.md)
-- [Type-safe validation library](../http/validation.md)
+- [Type-safe environment variables](../getting_started/environment_variables)
+- [Type-safe validation library](../basics/validation.md)
 
 ### Embracing MVC
 
@@ -86,7 +86,7 @@ The AdonisJS documentation is written as a reference guide, covering the usage a
 With that said, the documentation extensively covers the usage of available modules and the inner workings of the framework.
 
 ## Recent releases
-Following is the list of recent releases. [Click here](./releases.md) to view all the releases.
+Following is the list of recent releases. [Click here](releases.md) to view all the releases.
 
 ::include{template="partials/recent_releases"}
 
diff --git a/content/docs/guides/releases.md b/content/docs/preface/releases.md
similarity index 100%
rename from content/docs/guides/releases.md
rename to content/docs/preface/releases.md
diff --git a/content/docs/reference/commands.md b/content/docs/references/commands.md
similarity index 93%
rename from content/docs/reference/commands.md
rename to content/docs/references/commands.md
index 98beb26b..de2e299e 100644
--- a/content/docs/reference/commands.md
+++ b/content/docs/references/commands.md
@@ -112,7 +112,7 @@ node ace serve --hmr --assets-args="--cors --open"
 ## build
 The `build` command uses the [@adonisjs/assembler](https://github.com/adonisjs/assembler?tab=readme-ov-file#bundler) package to create the production build of your AdonisJS application. The following steps are performed to generate the build.
 
-See also: [TypeScript build process](../fundamentals/typescript_build_process.md).
+See also: [TypeScript build process](../concepts/typescript_build_process.md).
 
 ```sh
 node ace build
@@ -289,7 +289,7 @@ However, you can force overwrite files using the `--force` flag.
 
 Eject stubs from a given package to your application `stubs` directory. In the following example, we copy the `make/controller` stubs to our application for modification.
 
-See also: [Customizing stubs](../fundamentals/scaffolding.md#ejecting-stubs)
+See also: [Customizing stubs](../concepts/scaffolding.md#ejecting-stubs)
 
 ```sh
 # Copy stub from @adonisjs/core package
@@ -418,7 +418,7 @@ node ace make:middleware bodyparser
 
 <dd>
 
-Skip the [middleware stack](../http/middleware.md#middleware-stacks) selection prompt by defining the stack explicitly. The value must be `server`, `named`, or `router`.
+Skip the [middleware stack](../basics/middleware.md#middleware-stacks) selection prompt by defining the stack explicitly. The value must be `server`, `named`, or `router`.
 
 ```sh
 node ace make:middleware bodyparser --stack=router
@@ -532,7 +532,7 @@ node ace make:service invoice
 
 ## make\:exception
 
-Create a new [custom exception class](../http/exception_handling.md#custom-exceptions). Exceptions are stored inside the `app/exceptions` directory.
+Create a new [custom exception class](../basics/exception_handling.md#custom-exceptions). Exceptions are stored inside the `app/exceptions` directory.
 
 - Form: `NA`
 - Suffix: `exception`
@@ -574,7 +574,7 @@ node ace make:view posts/list
 
 ## make\:provider
 
-Create a [service provider file](../fundamentals/service_providers.md). Providers are stored inside the `providers` directory at the root of your application and use the following naming conventions.
+Create a [service provider file](../concepts/service_providers.md). Providers are stored inside the `providers` directory at the root of your application and use the following naming conventions.
 
 - Form: `singular`
 - Suffix: `provider`
@@ -596,7 +596,7 @@ node ace make:provider app
 
 <dd>
 
-Define environments in which the provider should get imported. [Learn more about app environments](../fundamentals/application.md#environment)
+Define environments in which the provider should get imported. [Learn more about app environments](../concepts/application.md#environment)
 
 ```sh
 node ace make:provider app -e=web -e=console
@@ -608,7 +608,7 @@ node ace make:provider app -e=web -e=console
 
 ## make\:preload
 
-Create a new [preload file](../fundamentals/adonisrc_file.md#preloads). Preload files are stored inside the `start` directory.
+Create a new [preload file](../../concepts/rc_file#preloads). Preload files are stored inside the `start` directory.
 
 ```sh
 node ace make:preload view
@@ -624,7 +624,7 @@ node ace make:preload view
 
 <dd>
 
-Define environments in which the preload file should get imported. [Learn more about app environments](../fundamentals/application.md#environment)
+Define environments in which the preload file should get imported. [Learn more about app environments](../concepts/application.md#environment)
 
 ```sh
 node ace make:preload view app -e=web -e=console
@@ -716,7 +716,7 @@ node ace make:policy post
 ## inspect\:rcfile
 View the contents of the `adonisrc.ts` file after merging the defaults. You may use this command to inspect the available configuration options and override them per your application requirements.
 
-See also: [AdonisRC file](../fundamentals/adonisrc_file.md)
+See also: [AdonisRC file](../../concepts/rc_file)
 
 ```sh
 node ace inspect:rcfile
@@ -731,7 +731,7 @@ node ace list:routes
 
 Also, you can see the routes list from the VSCode activity bar if you are using our [official VSCode extension](https://marketplace.visualstudio.com/items?itemName=jripouteau.adonis-vscode-extension).
 
-![](../http/vscode_routes_list.png)
+![](../basics/vscode_routes_list.png)
 
 <dl>
 
diff --git a/content/docs/reference/edge.md b/content/docs/references/edge.md
similarity index 80%
rename from content/docs/reference/edge.md
rename to content/docs/references/edge.md
index 343ba01e..a9e6b7a3 100644
--- a/content/docs/reference/edge.md
+++ b/content/docs/references/edge.md
@@ -3,7 +3,7 @@
 In this guide, we will learn about the **helpers and the tags** contributed to Edge by the AdonisJS official packages. The helpers shipped with Edge are not covered in this guide and must reference [Edge](https://edgejs.dev/docs/helpers) documentation for the same.
 
 ## request
-Reference to the instance of ongoing [HTTP request](../http/request.md). The property is only available when a template is rendered using the `ctx.view.render` method.
+Reference to the instance of ongoing [HTTP request](../basics/request.md). The property is only available when a template is rendered using the `ctx.view.render` method.
 
 ```edge
 {{ request.url() }}
@@ -11,7 +11,7 @@ Reference to the instance of ongoing [HTTP request](../http/request.md). The pro
 ```
 
 ## route/signedRoute
-Helper functions to create URL for a route using the [URL builder](../http/url_builder.md#generating-urls-inside-templates). Unlike the URL builder, the view helpers do not have a fluent API and accept the following parameters.
+Helper functions to create URL for a route using the [URL builder](../basics/routing.md#url-builder). Unlike the URL builder, the view helpers do not have a fluent API and accept the following parameters.
 
 <table>
     <tr>
@@ -58,14 +58,14 @@ Helper functions to create URL for a route using the [URL builder](../http/url_b
 ```
 
 ## app
-Reference to the [Application instance](../fundamentals/application.md).
+Reference to the [Application instance](../concepts/application.md).
 
 ```edge
 {{ app.getEnvironment() }}
 ```
 
 ## config
-A [helper function](../guides/config.md#reading-config-inside-edge-templates) to reference configuration values inside Edge templates. You may use the `config.has` method to check if the value for a key exists.
+A [helper function](../getting_started/configuration.md#reading-config-inside-edge-templates) to reference configuration values inside Edge templates. You may use the `config.has` method to check if the value for a key exists.
 
 ```edge
 @if(config.has('app.appUrl'))
@@ -76,14 +76,14 @@ A [helper function](../guides/config.md#reading-config-inside-edge-templates) to
 ```
 
 ## session
-A read-only copy of the [session object](../http/session.md#reading-and-writing-data). You cannot mutate session data within Edge templates. The `session` property is only available when the template is rendered using the `ctx.view.render` method.
+A read-only copy of the [session object](../basics/session.md#reading-and-writing-data). You cannot mutate session data within Edge templates. The `session` property is only available when the template is rendered using the `ctx.view.render` method.
 
 ```edge
 Post views: {{ session.get(`post.${post.id}.visits`) }}
 ```
 
 ## flashMessages
-A read-only copy of [session flash messages](../http/session.md#flash-messages). The `flashMessages` property is only available when the template is rendered using the `ctx.view.render` method.
+A read-only copy of [session flash messages](../basics/session.md#flash-messages). The `flashMessages` property is only available when the template is rendered using the `ctx.view.render` method.
 
 ```edge
 @if(flashMessages.has('inputErrorsBag.title'))
@@ -123,7 +123,7 @@ Reference to an instance of the I18n class configured using the application's de
 ```
 
 ## auth
-Reference to the [ctx.auth](../http/http_context.md#http-context-properties) property shared by the [InitializeAuthMiddleware](https://github.com/adonisjs/auth/blob/main/src/auth/middleware/initialize_auth_middleware.ts#L14). You may use this property to access information about the logged-in user.
+Reference to the [ctx.auth](../concepts/http_context.md#http-context-properties) property shared by the [InitializeAuthMiddleware](https://github.com/adonisjs/auth/blob/main/src/auth/middleware/initialize_auth_middleware.ts#L14). You may use this property to access information about the logged-in user.
 
 ```edge
 @if(auth.isAuthenticated)
@@ -143,14 +143,14 @@ If you are displaying the logged-in user info on a public page (not protected by
 ```
 
 ## asset
-Resolve the URL of an asset processed by Vite. Learn more about [referencing assets inside Edge templates](../http/assets_bundling.md#referencing-assets-inside-edge-templates).
+Resolve the URL of an asset processed by Vite. Learn more about [referencing assets inside Edge templates](../basics/vite.md#referencing-assets-inside-edge-templates).
 
 ```edge
 <img src="{{ asset('resources/images/hero.jpg') }}" />
 ```
 
 ## embedImage / embedImageData
-The `embedImage` and the `embedImageData` helpers are added by the [mail](../mail/message.md#embedding-images) package and are only available when rendering a template to send an email.
+The `embedImage` and the `embedImageData` helpers are added by the [mail](../digging_deeper/mail.md#embedding-images) package and are only available when rendering a template to send an email.
 
 ```edge
 <img src="{{
@@ -286,7 +286,7 @@ The `@can` and `@cannot` tags allows you write authorization checks in Edge temp
 
 The first argument is the ability or the policy reference followed by the arguments accepted by the check.
 
-See also: [Pre-registering abilities and policies](../digging_deeper/authorization.md#pre-registering-abilities-and-policies)
+See also: [Pre-registering abilities and policies](../security/authorization.md#pre-registering-abilities-and-policies)
 
 ```edge
 @can('editPost', post)
diff --git a/content/docs/reference/events.md b/content/docs/references/events.md
similarity index 98%
rename from content/docs/reference/events.md
rename to content/docs/references/events.md
index c9c7c4f7..86a8542d 100644
--- a/content/docs/reference/events.md
+++ b/content/docs/references/events.md
@@ -4,7 +4,7 @@ In this guide, we look at the list of events dispatched by the framework core an
 
 ## http\:request_completed
 
-The [`http:request_completed`](https://github.com/adonisjs/http-server/blob/main/src/types/server.ts#L65) event is dispatched after an HTTP request is completed. The event contains an instance of the [HttpContext](../http/http_context.md) and the request duration. The `duration` value is the output of the `process.hrtime` method.
+The [`http:request_completed`](https://github.com/adonisjs/http-server/blob/main/src/types/server.ts#L65) event is dispatched after an HTTP request is completed. The event contains an instance of the [HttpContext](../concepts/http_context.md) and the request duration. The `duration` value is the output of the `process.hrtime` method.
 
 ```ts
 import emitter from '@adonisjs/core/services/emitter'
diff --git a/content/docs/reference/exceptions.md b/content/docs/references/exceptions.md
similarity index 86%
rename from content/docs/reference/exceptions.md
rename to content/docs/references/exceptions.md
index dc598519..f8cafea8 100644
--- a/content/docs/reference/exceptions.md
+++ b/content/docs/references/exceptions.md
@@ -1,11 +1,11 @@
 # Exceptions reference
 
-In this guide we will go through the list of known exceptions raised by the framework core and the official packages. Some of the exceptions are marked as **self-handled**. [Self-handled exceptions](../http/exception_handling.md#defining-the-handle-method) can convert themselves to an HTTP response.
+In this guide we will go through the list of known exceptions raised by the framework core and the official packages. Some of the exceptions are marked as **self-handled**. [Self-handled exceptions](../basics/exception_handling.md#defining-the-handle-method) can convert themselves to an HTTP response.
 
 <div style="--prose-h2-font-size: 22px;">
 
 ## E_ROUTE_NOT_FOUND
-The exception is raised when the HTTP server receives a request for a non-existing route. By default, the client will get a 404 response, and optionally, you may render an HTML page using [status pages](../http/exception_handling.md#status-pages).
+The exception is raised when the HTTP server receives a request for a non-existing route. By default, the client will get a 404 response, and optionally, you may render an HTML page using [status pages](../basics/exception_handling.md#status-pages).
 
 - **Status code**: 404
 - **Self handled**: No
@@ -18,7 +18,7 @@ if (error instanceof errors.E_ROUTE_NOT_FOUND) {
 ```
 
 ## E_AUTHORIZATION_FAILURE
-The exception is raised when a bouncer authorization check fails. The exception is self-handled and [uses content-negotiation](../digging_deeper/authorization.md#throwing-authorizationexception) to return an appropriate error response to the client.
+The exception is raised when a bouncer authorization check fails. The exception is self-handled and [uses content-negotiation](../security/authorization.md#throwing-authorizationexception) to return an appropriate error response to the client.
 
 - **Status code**: 403
 - **Self handled**: Yes
@@ -31,7 +31,7 @@ if (error instanceof bouncerErrors.E_AUTHORIZATION_FAILURE) {
 ```
 
 ## E_TOO_MANY_REQUESTS
-The exception is raised by the [@adonisjs/rate-limiter](../security/rate-limiter.md) package when a request exhausts all the requests allowed during a given duration. The exception is self-handled and [uses content-negotiation](../security/rate-limiter.md#handling-throttleexception) to return an appropriate error response to the client.
+The exception is raised by the [@adonisjs/rate-limiter](../security/rate_limiting.md) package when a request exhausts all the requests allowed during a given duration. The exception is self-handled and [uses content-negotiation](../security/rate_limiting.md#handling-throttleexception) to return an appropriate error response to the client.
 
 - **Status code**: 429
 - **Self handled**: Yes
@@ -44,7 +44,7 @@ if (error instanceof limiterErrors.E_TOO_MANY_REQUESTS) {
 ```
 
 ## E_BAD_CSRF_TOKEN
-The exception is raised when a form using [CSRF protection](../security/web-security.md#csrf-protection) is submitted without the CSRF token, or the CSRF token is invalid.
+The exception is raised when a form using [CSRF protection](../security/securing_ssr_applications.md#csrf-protection) is submitted without the CSRF token, or the CSRF token is invalid.
 
 - **Status code**: 403
 - **Self handled**: Yes
@@ -67,7 +67,7 @@ The `E_BAD_CSRF_TOKEN` exception is [self-handled](https://github.com/adonisjs/s
 ## E_OAUTH_MISSING_CODE
 The `@adonisjs/ally` package raises the exception when the OAuth service does not provide the OAuth code during the redirect.
 
-You can avoid this exception if you [handle the errors](../digging_deeper/social_auth.md#handling-callback-response) before calling the `.accessToken` or `.user` methods.
+You can avoid this exception if you [handle the errors](../authentication/social_authentication.md#handling-callback-response) before calling the `.accessToken` or `.user` methods.
 
 - **Status code**: 500
 - **Self handled**: No
@@ -81,7 +81,7 @@ if (error instanceof allyErrors.E_OAUTH_MISSING_CODE) {
 ## E_OAUTH_STATE_MISMATCH
 The `@adonisjs/ally` package raises the exception when the CSRF state defined during the redirect is missing.
 
-You can avoid this exception if you [handle the errors](../digging_deeper/social_auth.md#handling-callback-response) before calling the `.accessToken` or `.user` methods.
+You can avoid this exception if you [handle the errors](../authentication/social_authentication.md#handling-callback-response) before calling the `.accessToken` or `.user` methods.
 
 - **Status code**: 400
 - **Self handled**: No
@@ -93,7 +93,7 @@ if (error instanceof allyErrors.E_OAUTH_STATE_MISMATCH) {
 ```
 
 ## E_UNAUTHORIZED_ACCESS
-The exception is raised when one of the authentication guards is not able to authenticate the request. The exception is self-handled and uses [content-negotiation](../auth/session_guard.md#handling-authentication-exception) to return an appropriate error response to the client.
+The exception is raised when one of the authentication guards is not able to authenticate the request. The exception is self-handled and uses [content-negotiation](../authentication/session_guard.md#handling-authentication-exception) to return an appropriate error response to the client.
 
 - **Status code**: 401
 - **Self handled**: Yes
@@ -106,7 +106,7 @@ if (error instanceof authErrors.E_UNAUTHORIZED_ACCESS) {
 ```
 
 ## E_INVALID_CREDENTIALS
-The exception is raised when the auth finder is not able to verify the user credentials. The exception is handled and use [content-negotiation](../auth/verifying_user_credentials.md#handling-exceptions)  to return an appropriate error response to the client.
+The exception is raised when the auth finder is not able to verify the user credentials. The exception is handled and use [content-negotiation](../authentication/verifying_user_credentials.md#handling-exceptions)  to return an appropriate error response to the client.
 
 - **Status code**: 400
 - **Self handled**: Yes
@@ -119,7 +119,7 @@ if (error instanceof authErrors.E_INVALID_CREDENTIALS) {
 ```
 
 ## E_CANNOT_LOOKUP_ROUTE
-The exception is raised when you attempt to create a URL for a route using the [URL builder](../http/url_builder.md).
+The exception is raised when you attempt to create a URL for a route using the [URL builder](../basics/routing.md#url-builder).
 
 - **Status code**: 500
 - **Self handled**: No
@@ -158,7 +158,7 @@ if (error instanceof errors.E_HTTP_EXCEPTION) {
 ```
 
 ## E_HTTP_REQUEST_ABORTED
-The `E_HTTP_REQUEST_ABORTED` is a sub-class of the `E_HTTP_EXCEPTION` exception. This exception is raised by the [response.abort](../http/response.md#aborting-request-with-an-error) method.
+The `E_HTTP_REQUEST_ABORTED` is a sub-class of the `E_HTTP_EXCEPTION` exception. This exception is raised by the [response.abort](../basics/response.md#aborting-request-with-an-error) method.
 
 ```ts
 import { errors } from '@adonisjs/core'
@@ -168,7 +168,7 @@ if (error instanceof errors.E_HTTP_REQUEST_ABORTED) {
 ```
 
 ## E_INSECURE_APP_KEY
-The exception is raised when the length of `appKey` is smaller than 16 characters. You can use the [generate:key](./commands.md#generatekey) ace command to generate a secure app key.
+The exception is raised when the length of `appKey` is smaller than 16 characters. You can use the [generate:key](commands.md#generatekey) ace command to generate a secure app key.
 
 - **Status code**: 500
 - **Self handled**: No
@@ -389,4 +389,3 @@ if (error instanceof sessionErrors.E_SESSION_NOT_READY) {
 ```
 
 </div>
-
diff --git a/content/docs/reference/helpers.md b/content/docs/references/helpers.md
similarity index 99%
rename from content/docs/reference/helpers.md
rename to content/docs/references/helpers.md
index 1a773833..a7ff5e9d 100644
--- a/content/docs/reference/helpers.md
+++ b/content/docs/references/helpers.md
@@ -390,7 +390,7 @@ Convert a value to a sentence.
 ```ts
 import string from '@adonisjs/core/helpers/string'
 
-string.sentenceCase('getting-started-with-adonisjs')
+string.sentenceCase('getting_started-with-adonisjs')
 // Getting started with adonisjs
 ```
 
diff --git a/content/docs/digging_deeper/authorization.md b/content/docs/security/authorization.md
similarity index 95%
rename from content/docs/digging_deeper/authorization.md
rename to content/docs/security/authorization.md
index 1c7d266b..8227df60 100644
--- a/content/docs/digging_deeper/authorization.md
+++ b/content/docs/security/authorization.md
@@ -210,7 +210,7 @@ Policies offer an abstraction layer to organize the authorization checks as clas
 
 The policies are stored inside the `./app/policies` directory, and each file represents a single policy. You may create a new policy by running the following command.
 
-See also: [Make policy command](../reference/commands.md#makepolicy)
+See also: [Make policy command](../references/commands.md#makepolicy)
 
 ```sh
 node ace make:policy post
@@ -387,7 +387,7 @@ export default class PostPolicy extends BasePolicy {
 ```
 
 ### Dependency injection
-The policy classes are created using the [IoC container](../fundamentals/ioc_container.md); therefore, you can type-hint and inject dependencies inside the policy constructor using the `@inject` decorator.
+The policy classes are created using the [IoC container](../concepts/dependency_injection.md); therefore, you can type-hint and inject dependencies inside the policy constructor using the `@inject` decorator.
 
 ```ts
 import { inject } from '@adonisjs/core'
@@ -407,7 +407,7 @@ export class PostPolicy extends BasePolicy {
 }
 ```
 
-If a Policy class is created during an HTTP request, you may also inject an instance of [HttpContext](../http/http_context.md) inside it.
+If a Policy class is created during an HTTP request, you may also inject an instance of [HttpContext](../concepts/http_context.md) inside it.
 
 ```ts
 // highlight-start
@@ -448,9 +448,9 @@ AdonisJS will convert the `AuthorizationException` to a `403 - Forbidden` HTTP r
 
 - HTTP requests with `Accept=application/vnd.api+json` header will receive an array of error messages formatted as per the [JSON API](https://jsonapi.org/format/#errors) spec.
 
-- All other requests will receive a plain text response message. However, you may use [status pages](../http/exception_handling.md#status-pages) to show a custom error page for authorization errors.
+- All other requests will receive a plain text response message. However, you may use [status pages](../basics/exception_handling.md#status-pages) to show a custom error page for authorization errors.
 
-You may also self-handle `AuthorizationException` errors within the [global exception handler](../http/exception_handling.md).
+You may also self-handle `AuthorizationException` errors within the [global exception handler](../basics/exception_handling.md).
 
 ```ts
 import { errors } from '@adonisjs/bouncer'
@@ -496,7 +496,7 @@ export const editPost = Bouncer.ability((user: User, post: Post) => {
 })
 ```
 
-If you are using the [@adonisjs/i18n](./i18n.md) package, you may return a localized response using the `.t` method. The translation message will be used over the default message during an HTTP request based on the user's language.
+If you are using the [@adonisjs/i18n](../digging_deeper/i18n.md) package, you may return a localized response using the `.t` method. The translation message will be used over the default message during an HTTP request based on the user's language.
 
 ```ts
 export const editPost = Bouncer.ability((user: User, post: Post) => {
@@ -675,4 +675,4 @@ These tags accept the `ability` name or the `policy.method` name as the first pa
 ```
 
 ## Events
-Please check the [events reference guide](../reference/events.md#authorizationfinished) to view the list of events dispatched by the `@adonisjs/bouncer` package.
+Please check the [events reference guide](../references/events.md#authorizationfinished) to view the list of events dispatched by the `@adonisjs/bouncer` package.
diff --git a/content/docs/security/encryption.md b/content/docs/security/encryption.md
index b0522d75..c38d7752 100644
--- a/content/docs/security/encryption.md
+++ b/content/docs/security/encryption.md
@@ -4,7 +4,7 @@ Using the encryption service, you may encrypt and decrypt values in your applica
 
 The `encryption` service uses the `appKey` stored inside the `config/app.ts` file as the secret to encrypt the values.
 
-- It is recommended to keep the `appKey` secure and inject it into your application using [environment variables](../guides/env.md). Anyone with access to this key can decrypt values.
+- It is recommended to keep the `appKey` secure and inject it into your application using [environment variables](../getting_started/environment_variables.md). Anyone with access to this key can decrypt values.
 
 - The key should be at least 16 characters long and have a cryptographically secure random value. You may generate the key using the `node ace generate:key` command.
 
diff --git a/content/docs/security/hash.md b/content/docs/security/hashing.md
similarity index 98%
rename from content/docs/security/hash.md
rename to content/docs/security/hashing.md
index 66c680ac..4652e134 100644
--- a/content/docs/security/hash.md
+++ b/content/docs/security/hashing.md
@@ -1,6 +1,6 @@
 # Hashing
 
-You may hash user passwords in your application using the `hash` service. AdonisJS has first-class support for `bcrypt`, `scrypt`, and `argon2` hashing algorithms and the ability to [add custom drivers](../fundamentals/extending_the_framework.md#creating-a-hash-driver).
+You may hash user passwords in your application using the `hash` service. AdonisJS has first-class support for `bcrypt`, `scrypt`, and `argon2` hashing algorithms and the ability to [add custom drivers](#creating-a-custom-hash-driver).
 
 The hashed values are stored in [PHC string format](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md). PHC is a deterministic encoding specification for formatting hashes.
 
@@ -289,7 +289,7 @@ Since you will be using the `hash` service to hash user passwords, you may find
 
 :::note
 
-If you are using the `@adonisjs/auth` module, hashing passwords within your model is unnecessary. The `AuthFinder` automatically handles password hashing, ensuring your user credentials are securely processed. Learn more about this process [here](../auth/verifying_user_credentials.md#hashing-user-password).
+If you are using the `@adonisjs/auth` module, hashing passwords within your model is unnecessary. The `AuthFinder` automatically handles password hashing, ensuring your user credentials are securely processed. Learn more about this process [here](../authentication/verifying_user_credentials.md#hashing-user-password).
 
 :::
 
diff --git a/content/docs/security/rate-limiter.md b/content/docs/security/rate_limiting.md
similarity index 97%
rename from content/docs/security/rate-limiter.md
rename to content/docs/security/rate_limiting.md
index 41fe9d93..30cc6eab 100644
--- a/content/docs/security/rate-limiter.md
+++ b/content/docs/security/rate_limiting.md
@@ -1,4 +1,4 @@
-# Rate limiter
+# Rate limiting
 
 AdonisJS provides a first-party package for implementing rate limits in your web application or the API server. The rate limiter provides `redis`, `mysql`, `postgresql` and `memory` as the storage options, with the ability to [create custom storage providers](#creating-a-custom-storage-provider).
 
@@ -437,15 +437,15 @@ limiter
 ```
 
 ## Handling ThrottleException
-The throttle middleware throws the [E_TOO_MANY_REQUESTS](../reference/exceptions.md#e_too_many_requests) exception when the user has exhausted all the requests within the specified timeframe. The exception will be automatically converted to an HTTP response using the following content negotiation rules.
+The throttle middleware throws the [E_TOO_MANY_REQUESTS](../references/exceptions.md#e_too_many_requests) exception when the user has exhausted all the requests within the specified timeframe. The exception will be automatically converted to an HTTP response using the following content negotiation rules.
 
 - HTTP requests with the `Accept=application/json` header will receive an array of error messages. Each array element will be an object with the message property.
 
 - HTTP requests with the `Accept=application/vnd.api+json` header will receive an array of error messages formatted per the JSON API spec.
 
-- All other requests will receive a plain text response message. However, you may use [status pages](../http/exception_handling.md#status-pages) to show a custom error page for limiter errors.
+- All other requests will receive a plain text response message. However, you may use [status pages](../basics/exception_handling.md#status-pages) to show a custom error page for limiter errors.
 
-You may also self-handle the error within the [global exception handler](../http/exception_handling.md#handling-exceptions).
+You may also self-handle the error within the [global exception handler](../basics/exception_handling.md#handling-exceptions).
 
 ```ts
 import { errors } from '@adonisjs/limiter'
@@ -523,7 +523,7 @@ Alongside throttling HTTP requests, you may also use the limiter to apply rate l
 Before you can apply rate limiting on an action, you must get an instance of the [Limiter](https://github.com/adonisjs/limiter/blob/main/src/limiter.ts) class using the `limiter.use` method. The `use` method accepts the name of the backend store and the following rate-limiting options.
 
 - `requests`: The number of requests to allow for a given duration.
-- `duration`: The duration in seconds or a [time expression](../reference/helpers.md#seconds) string.
+- `duration`: The duration in seconds or a [time expression](../references/helpers.md#seconds) string.
 - `block (optional)`: The duration for which to block the key after all the requests have been exhausted.
 - `inMemoryBlockOnConsumed (optional)`: See [shared options](#shared-options)
 - `inMemoryBlockDuration (optional)`: See [shared options](#shared-options)
@@ -598,7 +598,7 @@ import { HttpContext } from '@adonisjs/core/http'
 import limiter from '@adonisjs/limiter/services/main'
 
 export default class SessionController {
-  store({ request, response, session }: HttpContext) {
+  async store({ request, response, session }: HttpContext) {
     const { email, password } = request.only(['email', 'passwords'])
 
     /**
diff --git a/content/docs/security/web-security.md b/content/docs/security/securing_ssr_applications.md
similarity index 94%
rename from content/docs/security/web-security.md
rename to content/docs/security/securing_ssr_applications.md
index 9981a9d4..6992712b 100644
--- a/content/docs/security/web-security.md
+++ b/content/docs/security/securing_ssr_applications.md
@@ -1,11 +1,11 @@
-# Securing server-rendered apps
+# Securing server-rendered applications
 
 If you are creating a server-rendered application using AdonisJS, then you must use the `@adonisjs/shield` package to protect your applications from common web attacks like **CSRF**, **XSS**, **Content sniffing**, and so on.
 
 The package comes pre-configured with the **web starter kit**. However, you can manually install and configure the package as follows.
 
 :::note
-The `@adonisjs/shield` package has a peer dependency on the `@adonisjs/session` package, so make sure to [configure the session package](../http/session.md) first.
+The `@adonisjs/shield` package has a peer dependency on the `@adonisjs/session` package, so make sure to [configure the session package](../basics/session.md) first.
 :::
 
 ```sh
@@ -66,12 +66,13 @@ Once you configure the `@adonisjs/shield` package, all form submissions without
 :::
 
 ```html
+
 <form method="POST" action="/">
-  // highlight-start
-  <input type="hidden" name="_csrf" value="Q9ghWSf0-3FD9eCiu5YxvKaxLEZ6F_K4DL8o" />
-  // highlight-end
-  <input type="name" name="name" placeholder="Enter your name" />
-  <button type="submit">Submit</button>
+    // highlight-start
+    <input type="hidden" name="_csrf" value="Q9ghWSf0-3FD9eCiu5YxvKaxLEZ6F_K4DL8o"/>
+    // highlight-end
+    <input type="name" name="name" placeholder="Enter your name"/>
+    <button type="submit">Submit</button>
 </form>
 ```
 
@@ -97,7 +98,7 @@ You can access the flash message as follows inside an edge template.
 </form>
 ```
 
-You can also self-handle the `E_BAD_CSRF_TOKEN` exception inside the [global exception handler](../http/exception_handling.md#handling-exceptions) as follows.
+You can also self-handle the `E_BAD_CSRF_TOKEN` exception inside the [global exception handler](../basics/exception_handling.md#handling-exceptions) as follows.
 
 ```ts
 import app from '@adonisjs/core/services/app'
@@ -210,7 +211,7 @@ cookieOptions
 
 <dd>
 
-Configuration for the `XSRF-TOKEN` cookie. [See cookies configuration](../http/cookies.md#configuration) for available options.
+Configuration for the `XSRF-TOKEN` cookie. [See cookies configuration](../basics/cookies.md#configuration) for available options.
 
 </dd>
 
@@ -344,7 +345,7 @@ const shieldConfig = defineConfig({
 ```
 
 ### Loading assets from the Vite Dev server
-If you are using the [Vite integration](../http/assets_bundling.md), you can use the following CSP keywords to allow assets served by the Vite Dev server.
+If you are using the [Vite integration](../basics/vite.md), you can use the following CSP keywords to allow assets served by the Vite Dev server.
 
 - The `@viteDevUrl` adds the Vite dev server URL to the allowed list.
 - The `@viteHmrUrl` adds the Vite HMR websocket server URL to the allowed list.
diff --git a/content/docs/testing/browser_tests.md b/content/docs/testing/browser_tests.md
index d7eb6bfd..a8f4c9a1 100644
--- a/content/docs/testing/browser_tests.md
+++ b/content/docs/testing/browser_tests.md
@@ -1,4 +1,5 @@
 # Browser tests
+
 Browser tests are executed inside real browsers like Chrome, Firefox, or Safari. We make use of [Playwright](https://playwright.dev/) (a browser automation tool) for interacting with webpages programmatically.
 
 Playwright is both a testing framework and a library that exposes JavaScript APIs to interact with the browser. We **do not use the Playwright testing framework** because we are already using Japa, and using multiple testing frameworks inside a single project will only lead to confusion and config bloat.
@@ -145,7 +146,7 @@ await browserContext.getPlainCookie('cartTotal')
 ```
 
 ## Populating session store
-If you are using the [`@adonisjs/session`](../http/session.md) package to read/write session data in your application, you may also want to use the `sessionBrowserClient` plugin to populate the session store when writing tests.
+If you are using the [`@adonisjs/session`](../basics/session.md) package to read/write session data in your application, you may also want to use the `sessionBrowserClient` plugin to populate the session store when writing tests.
 
 ### Setup
 The first step is registering the plugin inside the `tests/bootstrap.ts` file.
@@ -284,10 +285,10 @@ await browserContext
 ## The route helper
 You may use the `route` helper from the TestContext to create a URL for a route. Using the route helper ensures that whenever you update your routes, you do not have to come back and fix all the URLs inside your tests.
 
-The `route` helper accepts the same set of arguments accepted by the global template method [route](../http/url_builder.md#route).
+The `route` helper accepts the same set of arguments accepted by the global template method [route](../basics/routing.md#url-builder).
 
 ```ts
-test('see list of users', ({ visit, route }) => {
+test('see list of users', async ({ visit, route }) => {
   const page = await visit(
     // highlight-start
     route('users.list')
diff --git a/content/docs/testing/commandline_tests.md b/content/docs/testing/console_tests.md
similarity index 98%
rename from content/docs/testing/commandline_tests.md
rename to content/docs/testing/console_tests.md
index 5b0ccf3a..791c2cb7 100644
--- a/content/docs/testing/commandline_tests.md
+++ b/content/docs/testing/console_tests.md
@@ -1,4 +1,4 @@
-# Command-line tests
+# Console tests
 
 Command-line tests refer to testing custom Ace commands that are part of your application or the package codebase.
 
@@ -28,7 +28,7 @@ export default class Greet extends BaseCommand {
 }
 ```
 
-Let's create a **unit** test inside the `tests/unit` directory. Feel free to [define the unit test suite](./introduction.md#suites) if it is not already defined.
+Let's create a **unit** test inside the `tests/unit` directory. Feel free to [define the unit test suite](introduction.md#suites) if it is not already defined.
 
 ```sh
 node ace make:test commands/greet --suite=unit
diff --git a/content/docs/testing/database_tests.md b/content/docs/testing/database.md
similarity index 100%
rename from content/docs/testing/database_tests.md
rename to content/docs/testing/database.md
diff --git a/content/docs/testing/http_tests.md b/content/docs/testing/http_tests.md
index eba4f3ee..4c905e5f 100644
--- a/content/docs/testing/http_tests.md
+++ b/content/docs/testing/http_tests.md
@@ -4,7 +4,7 @@ HTTP tests refer to testing your application endpoints by making an actual HTTP
 
 HTTP tests are performed using the [API client plugin](https://japa.dev/docs/plugins/api-client) of Japa. The API client plugin is a stateless request library similar to `Axios` or `fetch` but more suited for testing.
 
-If you want to test your web apps inside a real browser and interact with them programmatically, we recommend using the [Browser client](./browser_tests.md) that uses Playwright for testing.
+If you want to test your web apps inside a real browser and interact with them programmatically, we recommend using the [Browser client](browser_tests.md) that uses Playwright for testing.
 
 ## Setup
 The first step is to install the following packages from the npm packages registry.
@@ -141,7 +141,7 @@ await client
   .withCookie('user_preferences', { limit: 10 })
 ```
 
-The `withCookie` method defines a [singed cookie](../http/cookies.md#signed-cookies). In addition, you may use the `withEncryptedCookie` or `withPlainCookie` methods to send other types of cookies to the server.
+The `withCookie` method defines a [singed cookie](../basics/cookies.md#signed-cookies). In addition, you may use the `withEncryptedCookie` or `withPlainCookie` methods to send other types of cookies to the server.
 
 ```ts
 await client
@@ -174,7 +174,7 @@ response.assertCookie('user_preferences')
 ```
 
 ## Populating session store
-If you are using the [`@adonisjs/session`](../http/session.md) package to read/write session data in your application, you may also want to use the `sessionApiClient` plugin to populate the session store when writing tests.
+If you are using the [`@adonisjs/session`](../basics/session.md) package to read/write session data in your application, you may also want to use the `sessionApiClient` plugin to populate the session store when writing tests.
 
 ### Setup
 The first step is registering the plugin inside the `tests/bootstrap.ts` file.
@@ -367,7 +367,7 @@ await client
 ```
 
 ## Making a request with a CSRF token
-If forms in your application use [CSRF protection](../security/web-security.md), you may use the `withCsrfToken` method to generate a CSRF token and pass it as a header during the request.
+If forms in your application use [CSRF protection](../security/securing_ssr_applications.md), you may use the `withCsrfToken` method to generate a CSRF token and pass it as a header during the request.
 
 Before using the `withCsrfToken` method, register the following Japa plugins inside the `tests/bootstrap.ts` file and also make sure to [switch the `SESSION_DRIVER` env variable](#setup-1) to `memory`.
 
@@ -400,7 +400,7 @@ test('create a post', async ({ client }) => {
 ## The route helper
 You may use the `route` helper from the TestContext to create a URL for a route. Using the route helper ensures that whenever you update your routes, you do not have to come back and fix all the URLs inside your tests.
 
-The `route` helper accepts the same set of arguments accepted by the global template method [route](../http/url_builder.md#generating-urls-inside-templates).
+The `route` helper accepts the same set of arguments accepted by the global template method [route](../basics/routing.md#url-builder).
 
 ```ts
 test('get a list of users', async ({ client, route }) => {
diff --git a/content/docs/testing/introduction.md b/content/docs/testing/introduction.md
index ff4d8ca5..3eb7b4ac 100644
--- a/content/docs/testing/introduction.md
+++ b/content/docs/testing/introduction.md
@@ -100,7 +100,7 @@ export const reporters: Config['reporters'] = {
 
 You may create a new test using the `make:test` command. The command needs the suite's name to create the test file.
 
-See also: [Make test command](../reference/commands.md#maketest)
+See also: [Make test command](../references/commands.md#maketest)
 
 ```sh
 node ace make:test posts/create --suite=functional
@@ -241,13 +241,13 @@ See also: [Japa filtering tests guide](https://japa.dev/docs/filtering-tests)
 
 :::
 
-| Flag | Description |
-|------|-----------|
-| `--tests` | Filter test by the test title. This filter matches against the exact test title. |
-| `--files` | Filter tests by subset of test file name. The match is performed against the end of the filename without `.spec.ts`. You can run tests for a complete folder using the wildcard expression. `folder/*` |
-| `--groups` | Filter test by group name. This filter matches against the exact group name. |
-| `--tags` | Filter tests by tags. You can prefix the tag name with tilde `~` to ignore tests with the given tag |
-| `--matchAll` | By default, Japa will run tests that matches any of the mentioned tags. If you want all tags to match, then use the `--matchAll` flag |
+| Flag         | Description                                                                                                                                                                                            |
+|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--tests`    | Filter test by the test title. This filter matches against the exact test title.                                                                                                                       |
+| `--files`    | Filter tests by subset of test file name. The match is performed against the end of the filename without `.spec.ts`. You can run tests for a complete folder using the wildcard expression. `folder/*` |
+| `--groups`   | Filter test by group name. This filter matches against the exact group name.                                                                                                                           |
+| `--tags`     | Filter tests by tags. You can prefix the tag name with tilde `~` to ignore tests with the given tag                                                                                                    |
+| `--matchAll` | By default, Japa will run tests that matches any of the mentioned tags. If you want all tags to match, then use the `--matchAll` flag                                                                  |
 
 ### Force exiting tests
 
diff --git a/content/docs/testing/mocks_and_fakes.md b/content/docs/testing/mocks_and_fakes.md
index 03bd02be..e6356850 100644
--- a/content/docs/testing/mocks_and_fakes.md
+++ b/content/docs/testing/mocks_and_fakes.md
@@ -1,4 +1,4 @@
-# Mocks and fakes
+# Mocks and Fakes
 
 When testing your applications, you might want to mock or fake specific dependencies to prevent actual implementations from running. For example, you wish to refrain from emailing your customers when running tests and neither call third-party services like a payment gateway.
 
@@ -11,12 +11,12 @@ Fakes are objects with working implementations explicitly created for testing. F
 We provide fake implementations for the following container services. The fakes API is documented alongside the module documentation.
 
 - [Emitter fake](../digging_deeper/emitter.md#faking-events-during-tests)
-- [Hash fake](../security/hash.md#faking-hash-service-during-tests)
-- [Fake mailer](../mail/fake_mailer.md)
+- [Hash fake](../security/hashing.md#faking-hash-service-during-tests)
+- [Fake mailer](../digging_deeper/mail.md#fake-mailer)
 
 ## Dependency injection and fakes
 
-If you use dependency injection in your application or use the [container to create class instances](../fundamentals/ioc_container.md), you can provide a fake implementation for a class using the `container.swap` method.
+If you use dependency injection in your application or use the [container to create class instances](../concepts/dependency_injection.md), you can provide a fake implementation for a class using the `container.swap` method.
 
 In the following example, we inject `UserService` to the `UsersController`.
 
@@ -26,7 +26,7 @@ import { inject } from '@adonisjs/core'
 
 export default class UsersController {
   @inject()
-  index(, service: UserService) {}
+  index(service: UserService) {}
 }
 ```
 
diff --git a/content/docs/http/views_and_templates.md b/content/docs/views-and-templates/edgejs.md
similarity index 52%
rename from content/docs/http/views_and_templates.md
rename to content/docs/views-and-templates/edgejs.md
index 0a74ab4c..559b960d 100644
--- a/content/docs/http/views_and_templates.md
+++ b/content/docs/views-and-templates/edgejs.md
@@ -1,27 +1,15 @@
-# Views and Templates
+# EdgeJS
 
-AdonisJS is an excellent fit for creating traditional server-rendered applications in Node.js. If you enjoy the simplicity of using a backend template engine that outputs HTML without any overhead of Virtual DOM and build tools, then this guide is for you.
+Edge is a **simple**, **Modern**, and **batteries included** template engine created and maintained by the AdonisJS core team for Node.js. Edge is similar to writing JavaScript. If you know JavaScript, you know Edge.
 
-The typical workflow of a server-rendered application in AdonisJS looks as follows.
-
-- Choose a template engine to render HTML dynamically.
-- Use [Vite](./assets_bundling.md) for bundling CSS and frontend JavaScript.
-- Optionally, you can opt for libraries like [HTMX](https://htmx.org/) or [Unpoly](https://unpoly.com/) to progressively enhance your application and navigate like an SPA.
-
-## Choosing a template engine
-The AdonisJS core team has created a framework-agnostic template engine called [Edge.js](https://edgejs.dev). Following are some of the reasons for using Edge.
-
-- Edge is simple, modern, and a batteries-included template engine in the Node.js ecosystem.
-- It has support for Components with features like slots and context API.
-- Integration with Iconify to render SVG icons.
+:::note
+The documentation for Edge is available on [https://edgejs.dev](https://edgejs.dev)
+:::
 
-AdonisJS does not force you to use Edge, and you can pick any other template engine of your choice, be it Pug, Nunjucks, and so on.
+## Installation
 
-## Using Edge
 Install and configure Edge using the following command.
 
-See also: [Edge documentation](https://edgejs.dev)
-
 ```sh
 node ace add edge
 ```
@@ -44,6 +32,7 @@ node ace add edge
 :::
 
 ## Rendering your first template
+
 Once the configuration is completed, you can use Edge to render templates. Let's create a `welcome.edge` file inside the `resources/views` directory.
 
 ```sh
@@ -83,7 +72,7 @@ router.on('/').render('welcome')
 ```
 
 ## Configuring Edge
-You can use Edge plugins or add global helpers to Edge by creating a [preload file](../fundamentals/adonisrc_file.md#preloads) inside the `start` directory.
+You can use Edge plugins or add global helpers to Edge by creating a [preload file](../concepts/adonisrc_file#preloads) inside the `start` directory.
 
 ```sh
 node ace make:preload view
@@ -107,4 +96,12 @@ edge.global('appUrl', env.get('APP_URL'))
 ```
 
 ## Global helpers
-Please check the [Edge helpers reference guide](../reference/edge.md) to view the list of helpers contributed by AdonisJS.
+
+Please check the [Edge helpers reference guide](../references/edge.md) to view the list of helpers contributed by AdonisJS.
+
+## Learn more
+
+- [Edge.js documentation](https://edgejs.dev)
+- [Components](https://edgejs.dev/docs/components)
+- [SVG icons](https://edgejs.dev/docs/edge-iconify)
+- [Adocasts Edge Series](https://adocasts.com/topics/edge)
diff --git a/content/docs/views-and-templates/introduction.md b/content/docs/views-and-templates/introduction.md
new file mode 100644
index 00000000..85c590fe
--- /dev/null
+++ b/content/docs/views-and-templates/introduction.md
@@ -0,0 +1,21 @@
+# Views and Templates
+
+AdonisJS is an excellent fit for creating traditional server-rendered applications in Node.js. If you enjoy the simplicity of using a backend template engine that outputs HTML without any overhead of Virtual DOM and build tools, then this guide is for you.
+
+The typical workflow of a server-rendered application in AdonisJS looks as follows.
+
+- Choose a template engine to render HTML dynamically.
+- Use [Vite](../basics/vite.md) for bundling CSS and frontend JavaScript.
+- Optionally, you can opt for libraries like [HTMX](https://htmx.org/) or [Unpoly](https://unpoly.com/) to progressively enhance your application and navigate like an SPA.
+
+:::note
+The AdonisJS core team has created a framework-agnostic template engine called [Edge.js](https://edgejs.dev) but does not force you to use it. You can use any other template engine you would like inside an AdonisJS application.
+:::
+
+## Popular options
+
+Following is the list of popular template engines you can use inside an AdonisJS application (just like any other Node.js application).
+
+- [**EdgeJS**](https://edgejs.dev) is a simple, modern, and batteries included template engine created and maintained by the AdonisJS core team for Node.js.
+- [**Pug**](https://pugjs.org) is a template engine heavily influenced by Haml.
+- [**Nunjucks**](https://mozilla.github.io/nunjucks) is a rich feature template engine inspired by Jinja2.
diff --git a/public/_redirects b/public/_redirects
index 182f9515..393589ef 100644
--- a/public/_redirects
+++ b/public/_redirects
@@ -1,43 +1,4 @@
 / /guides/introduction
-/guides /guides/introduction
-/guides/release-process /guides/releases
-/guides/context /guides/http-context
-/guides/direct-file-uploads /guides/file-uploads
-/guides/static-assets /guides/static-file-server
-/guides/assets-manager /guides/assets-bundling
-/guides/views/* /guides/views-and-templates
-/guides/validator/* /guides/validation
-/guides/database/introduction /guides/database/sql
-/guides/database/query-builder /guides/database/sql
-/guides/database/transactions /guides/database/sql
-/guides/database/pagination /guides/database/sql
-/guides/database/migrations /guides/database/sql
-/guides/database/seeders /guides/database/sql
-/guides/database/debugging /guides/database/sql
-/guides/models/* /guides/database/sql
-/guides/auth/introduction /guides/auth
-/guides/auth/web-guard /guides/auth-session-guard
-/guides/auth/api-tokens-guard /guides/auth-access-tokens-guard
-/guides/auth/basic-auth-guard /guides/basic-auth-guard
-/guides/auth/middleware /guides/auth
-/guides/auth/social /guides/social-auth
-/guides/security/web-security /guides/web-security
-/guides/security/cors /guides/cors
-/guides/security/encryption /guides/encryption
-/guides/security/hashing /guides/hashing
-/guides/security/signed-urls /guides/url-builder
-/guides/testing/introduction /guides/testing
-/guides/testing/http-tests /guides/http-tests
-/guides/testing/fakes /guides/mocks-and-fakes
-/guides/ace-commandline /guides/ace
-/guides/events /guides/emitter
-/guides/helpers /guides/helpers-reference
-/guides/mailer /guides/mail
-/reference/validator/* /guides/validation
-/reference/views/* /guides/edge-reference
-/reference/i18n/* /guides/i18n
-/releases/* /guides/releases
-/guides/hot-module-reloading /guides/hmr
 
 /cookbooks/validating-server-rendered-forms https://v5-docs.adonisjs.com/cookbooks/validating-server-rendered-forms 308
 /cookbooks/using-ally-with-api-guard https://v5-docs.adonisjs.com/cookbooks/using-ally-with-api-guard 308
@@ -46,3 +7,103 @@
 /cookbooks/using-knex-postgis-with-lucid https://v5-docs.adonisjs.com/cookbooks/using-knex-postgis-with-lucid 308
 /cookbooks/dockerizing-adonis https://v5-docs.adonisjs.com/cookbooks/dockerizing-adonis 308
 /cookbooks/socketio-with-adonisjs https://v5-docs.adonisjs.com/cookbooks/socketio-with-adonisjs 308
+
+# Old Redirects
+/guides/testing/fakes /guides/testing/mocks-and-fakes
+/guides/events /guides/digging-deeper/emitter
+
+# New Structure
+/guides /guides/preface/introduction
+/guides/preface /guides/preface/introduction
+/guides/introduction /guides/preface/introduction
+/guides/faqs /guides/preface/faqs
+/guides/releases /guides/preface/releases
+
+/guides/getting-started /guides/getting-started/installation
+/guides/installation /guides/getting-started/installation
+/guides/config /guides/getting-started/configuration
+/guides/environment-variables /guides/getting-started/environment-variables
+/guides/folder-structure /guides/getting-started/folder-structure
+
+/guides/concepts /guides/concepts/async-local-storage
+/guides/async-local-storage /guides/concepts/async-local-storage
+/guides/application /guides/concepts/application
+/guides/application-lifecycle /guides/concepts/application-lifecycle
+/guides/config-providers /guides/concepts/config-providers
+/guides/container-services /guides/concepts/container-services
+/guides/ioc-container /guides/concepts/dependency-injection
+/guides/extend-adonisjs /guides/concepts/extending-adonisjs
+/guides/hmr /guides/concepts/hot-module-replacement
+/guides/http /guides/concepts/http-overview
+/guides/http-context /guides/concepts/http-context
+/guides/adonisrc-file /guides/concepts/adonisrcrc-file
+/guides/service-providers /guides/concepts/service-providers
+/guides/scaffolding /guides/concepts/scaffolding
+/guides/tooling-config /guides/concepts/tooling-config
+/guides/typescript-build-process /guides/concepts/typescript-build-process
+
+/guides/basics /guides/basics/routing
+/guides/routing /guides/basics/routing
+/guides/controllers /guides/basics/controllers
+/guides/middleware /guides/basics/middleware
+/guides/bodyparser-middleware /guides/basics/body-parser
+/guides/request /guides/basics/request
+/guides/response /guides/basics/response
+/guides/validation /guides/basics/validation
+/guides/file-uploads /guides/basics/file-uploads
+/guides/session /guides/basics/session
+/guides/cookies /guides/basics/cookies
+/guides/exception-handling /guides/basics/exception-handling
+/guides/assets-bundling /guides/basics/vite
+/guides/static-file-server /guides/basics/static-file-server
+/guides/url-builder /guides/basics/routing#url-builder
+
+/guides/database /guides/database/introduction
+/guides/sql /guides/database/introduction
+/guides/redis /guides/database/redis
+
+/guides/authentication /guides/authentication/introduction
+/guides/auth /guides/authentication/introduction
+/guides/verifying_user_credentials /guides/authentication/verifying-user-credentials
+/guides/auth-session-guard /guides/authentication/session-guard
+/guides/auth-access-tokens-guard /guides/authentication/access-tokens-guard
+/guides/basic-auth-guard /guides/authentication/basic-auth-guard
+/guides/auth-custom-guards /guides/authentication/custom-auth-guard
+/guides/social-auth /guides/authentication/social-authentication
+
+/guides/security /guides/security/authorization
+/guides/authorization /guides/security/authorization
+/guides/encryption /guides/security/encryption
+/guides/hash /guides/security/hashing
+/guides/cors /guides/security/cors
+/guides/web-security /guides/security/securing-ssr-applications
+/guides/rate-limiter /guides/security/rate-limiting
+
+/guides/views-and-templates /guides/views-and-templates/introduction
+
+/guides/testing /guides/testing/introduction
+/guides/http-tests /guides/testing/http-tests
+/guides/browser-tests /guides/testing/browser-tests
+/guides/command-line-tests /guides/testing/console-tests
+/guides/database-tests /guides/testing/database
+/guides/mocks-and-fakes /guides/testing/mocks-and-fakes
+
+/guides/digging-deeper /guides/digging-deeper/emitter
+/guides/emitter /guides/digging-deeper/emitter
+/guides/i18n /guides/digging-deeper/i18n
+/guides/locks /guides/digging-deeper/locks
+/guides/logger /guides/digging-deeper/logger
+/guides/transmit /guides/digging-deeper/transmit
+/guides/repl /guides/digging-deeper/repl
+
+/guides/commands-reference /guides/references/commands
+/guides/edge-reference /guides/references/edge
+/guides/events-reference /guides/references/events
+/guides/exceptions-reference /guides/references/exceptions
+/guides/helpers-reference /guides/references/helpers
+
+/guides/mail /guides/digging-deeper/mail
+/guides/mail-message /guides/digging-deeper/mail#configuring-message
+/guides/mail-classes /guides/digging-deeper/mail#class-based-emails
+/guides/fake-mailer /guides/digging-deeper/mail#fake-mailer
+/guides/mail-custom-transports /guides/digging-deeper/mail#creating-custom-transports
diff --git a/templates/partials/introduction_cards.edge b/templates/partials/introduction_cards.edge
index 4ac8a864..06415c59 100644
--- a/templates/partials/introduction_cards.edge
+++ b/templates/partials/introduction_cards.edge
@@ -57,7 +57,7 @@
         </a>
       </li>
       <li>
-        <a href="https://github.com/adonisjs/core/discussions" target="_blank">
+        <a href="https://github.com/orgs/adonisjs/discussions" target="_blank">
           GitHub discussions
         </a>
       </li>