Overhaul

docs/book/v1/admin/introduction.md

@@ -1,5 +1,11 @@
 # Introduction
 
+## Summary
+
+An overview of Dotkernel Admin, a skeleton application for quickly building a database-backed administration site with reports, graphs, and a PSR-compliant middleware stack.
+
+## Details
+
 Dotkernel Admin is an application (skeleton) intended for quickly setting up an administration site for your platform.
 
 Dotkernel Admin:
@@ -9,3 +15,19 @@ Dotkernel Admin:
 - Contains many graphical components to ensure an intuitive user experience.
 - Has a PSR-Compliant Middleware Stack to promote a lean, modular architecture and create a common ground between components from various sources.
 - Implements [PSR-7](https://www.php-fig.org/psr/psr-7/) (HTTP message interfaces) and [PSR-15](https://www.php-fig.org/psr/psr-15/) (HTTP Server Request Handlers) as defined by the [PHP Framework Interop Group](https://www.php-fig.org/).
+
+## FAQ
+
+**Q: What is Dotkernel Admin?**
+A: It's a skeleton application for quickly setting up an administration site to manage records in your database.
+
+**Q: Does Dotkernel Admin include reporting features?**
+A: Yes, it has built-in reports and graphs to help you monitor your platform.
+
+**Q: What standards does Dotkernel Admin implement?**
+A: PSR-7 and PSR-15, as defined by the PHP Framework Interop Group (PHP-FIG).
+
+## See also
+
+- [Usage](usage.md) — how Admin fits alongside API and Queue.
+- [Architecture Overview](../architecture.md) — how all the platform pieces fit together.

docs/book/v1/admin/usage.md

@@ -1,11 +1,13 @@
 # Usage
 
-Dotkernel Admin can be installed independently or together with other applications in the Dotkernel suite, based on your business requirements.
-These components are designed to complement each other (out-of-box they are separate codebases):
+## Summary
+
+Explains how Dotkernel Admin fits alongside Dotkernel API and Dotkernel Queue, and how you can start with Admin alone and add the other components later.
 
-- **Dotkernel API** exposes the content to 3rd-party frontends or backends.
-- **Dotkernel Admin** (optional) manages the data (create, edit, delete).
-- **Dotkernel Queue** (optional) queue management microservice.
+## Details
+
+Dotkernel Admin can be installed independently or together with other applications in the Dotkernel suite, based on your business requirements.
+Out of the box, Admin, API, and Queue are separate codebases designed to complement each other — see the [Architecture Overview](../architecture.md) for how they fit together.
 
 You can start with Dotkernel Admin and integrate it into your existing platform.
 The Admin has built-in reports and graphs that can be configured and customized based on your needs.
@@ -14,3 +16,20 @@ Later on you can add:
 
 - Dotkernel API to handle all data manipulation.
 - Dotkernel Queue for its asynchronous task processing.
+
+## FAQ
+
+**Q: Can Dotkernel Admin be used on its own?**
+A: Yes, it can be installed independently and integrated into your existing platform.
+
+**Q: Are Dotkernel Admin, API, and Queue part of the same codebase?**
+A: No, out of the box they are separate codebases designed to complement each other.
+
+**Q: What do Dotkernel API and Dotkernel Queue add to Admin?**
+A: The API handles data manipulation for the platform, and Queue handles asynchronous task processing.
+
+## See also
+
+- [Dotkernel API: Usage](../api/usage.md)
+- [Dotkernel Queue: Usage](../queue/usage.md)
+- [Architecture Overview](../architecture.md)

docs/book/v1/api/introduction.md

@@ -1,10 +1,32 @@
 # Introduction
 
+## Summary
+
+An overview of Dotkernel API, the Mezzio-based REST API at the root of the Dotkernel Headless Platform, and its PSR-compliant, standards-based architecture.
+
+## Details
+
 Dotkernel API is a REST API based on the Mezzio skeleton.
-The API is the root or the Dotkernel Headless Platform.
+The API is the root of the Dotkernel Headless Platform.
 
 Dotkernel API:
 
 - Ensures that you build a cohesive system that contains an API-first backend with the same architecture and standards support as other Dotkernel tools and applications.
 - Has a PSR-Compliant Middleware Stack to promote a lean, modular architecture and create a common ground between components from various sources.
 - Implements [PSR-7](https://www.php-fig.org/psr/psr-7/) (HTTP message interfaces) and [PSR-15](https://www.php-fig.org/psr/psr-15/) (HTTP Server Request Handlers) as defined by the [PHP Framework Interop Group](https://www.php-fig.org/).
+
+## FAQ
+
+**Q: What is Dotkernel API built on?**
+A: It's a REST API based on the Mezzio skeleton.
+
+**Q: What role does Dotkernel API play in the Headless Platform?**
+A: It is the root of the Dotkernel Headless Platform.
+
+**Q: What standards does Dotkernel API implement?**
+A: PSR-7 and PSR-15, as defined by the PHP Framework Interop Group (PHP-FIG).
+
+## See also
+
+- [Usage](usage.md) — how API fits alongside Admin and Queue.
+- [Architecture Overview](../architecture.md) — how all the platform pieces fit together.

docs/book/v1/api/usage.md

@@ -1,11 +1,13 @@
 # Usage
 
-Dotkernel API can be installed independently or together with other applications in the Dotkernel suite, based on your business requirements.
-These components are designed to complement each other (out-of-box they are separate codebases):
+## Summary
+
+Explains how Dotkernel API fits alongside Dotkernel Admin and Dotkernel Queue, and how to start with API alone and add the other components later.
 
-- **Dotkernel API** exposes the content to 3rd-party frontends or backends.
-- **Dotkernel Admin** (optional) manages the data (create, edit, delete).
-- **Dotkernel Queue** (optional) queue management microservice.
+## Details
+
+Dotkernel API can be installed independently or together with other applications in the Dotkernel suite, based on your business requirements.
+Out of the box, API, Admin, and Queue are separate codebases designed to complement each other — see the [Architecture Overview](../architecture.md) for how they fit together.
 
 A safe bet is to start with Dotkernel API and integrate it into your existing platform.
 The API can manage the access permissions to keep your data secure:
@@ -17,3 +19,20 @@ Later on you can add:
 
 - Dotkernel Admin for its simple table-based approach, its reports and graphs.
 - Dotkernel Queue for its asynchronous task processing.
+
+## FAQ
+
+**Q: Should I start with Dotkernel API or Admin?**
+A: Starting with Dotkernel API is a safe bet since it can manage access permissions to keep your data secure.
+
+**Q: How does Dotkernel API separate admin and regular users?**
+A: Admin-level users create and edit the data, while regular users read the data for your frontend.
+
+**Q: What can I add to Dotkernel API later?**
+A: Dotkernel Admin for its table-based management, reports and graphs, and Dotkernel Queue for asynchronous task processing.
+
+## See also
+
+- [Dotkernel Admin: Usage](../admin/usage.md)
+- [Dotkernel Queue: Usage](../queue/usage.md)
+- [Architecture Overview](../architecture.md)

docs/book/v1/architecture.md

@@ -0,0 +1,32 @@
+# Architecture Overview
+
+## Summary
+
+Ties together the four building blocks of the Dotkernel Headless Platform — API, Admin, Queue, and the Core submodule — and shows how they combine into a single platform.
+
+## Details
+
+The [Headless Platform](introduction.md) principle is to decouple the frontend from the backend services, so any number of outside systems can consume the same backend.
+Dotkernel implements this with four building blocks, each its own Git repository, which you combine based on your needs:
+
+- **[Dotkernel API](api/introduction.md)** exposes your data to 3rd-party frontends or backends.
+- **[Dotkernel Admin](admin/introduction.md)** (optional) manages the data through a simple table-based UI, with built-in reports and graphs.
+- **[Dotkernel Queue](queue/introduction.md)** (optional) handles asynchronous task processing as its own microservice.
+- **[Core submodule](core/introduction.md)** is the shared codebase that any of the above applications can include, so they all manage database entities and services the same way.
+
+You don't need every piece from the start.
+You can begin with [just Admin](admin/usage.md) or [just API](api/usage.md) and add the others later as requirements grow.
+Once you're running more than one application, pull the shared logic out into a [Core submodule](core/creation.md) and include it in each one — a typical setup looks like API + Core, Admin + Core, and Queue + Core, each in its own repository, all reading from the same shared entities and services (see [Using the Core Submodule](core/usage.md)).
+
+Regardless of which pieces you use, every Dotkernel application and package boots the same way: through a [ConfigProvider](config-provider/introduction.md) that declares its dependencies, handlers, and configuration, merged together by the framework at [bootstrap time](config-provider/functionality.md).
+
+## FAQ
+
+**Q: What are the building blocks of the Dotkernel Headless Platform?**
+A: Dotkernel API, Dotkernel Admin, Dotkernel Queue, and the Core submodule.
+
+**Q: Do I need all four components to get started?**
+A: No, you can start with just Admin or just API and add the others as your requirements grow.
+
+**Q: How do multiple applications stay consistent with each other?**
+A: By sharing a Core submodule for entities and services, and by each bootstrapping through its own ConfigProvider.

docs/book/v1/config-provider/benefits.md

@@ -1,10 +1,32 @@
 # Benefits
 
+## Summary
+
+Lists the benefits of using a ConfigProvider, including centralized, modular, container-friendly, and testable configuration.
+
+## Details
+
 - **Centralized setup** – Instead of hardcoding bootstrap code, you declare it in a config provider so it's easy to read, change, or extend.
 - **Modular** – Each package can ship with its own config without interfering with others.
 - **Container-friendly** – It works well with frameworks using DI containers like Laminas ServiceManager, PHP-DI, or Pimple.
-- **Standardized service definitions** - It has consistent rules for object creation that are separate from business logic.
-- **Environment-agnostic** - It returns an array that defines dev, test, or prod environments.
-- **Testability** - The consistent, central configuration promotes isolated (e.g. per-module) testing, easier swapping of dependencies and the assertion of pipeline setup (e.g. check if a config key is present).
+- **Standardized service definitions** – It has consistent rules for object creation that are separate from business logic.
+- **Environment-agnostic** – It returns an array that defines dev, test, or prod environments.
+- **Testability** – The consistent, central configuration promotes isolated (e.g. per-module) testing, easier swapping of dependencies and the assertion of pipeline setup (e.g. check if a config key is present).
 
 > **Dotkernel ConfigProviders** have to be **added manually** in `config/config.php`, because all the initial ConfigProviders required to install the applications are already injected.
+
+## FAQ
+
+**Q: Why use a ConfigProvider instead of hardcoding bootstrap code?**
+A: It centralizes configuration so it's easy to read, change, or extend.
+
+**Q: Does a ConfigProvider work with dependency injection containers?**
+A: Yes, it's container-friendly and works with DI containers like Laminas ServiceManager, PHP-DI, or Pimple.
+
+**Q: Do I need to register Dotkernel ConfigProviders manually?**
+A: Yes, Dotkernel ConfigProviders must be added manually in `config/config.php`.
+
+## See also
+
+- [Introduction](introduction.md)
+- [How the ConfigProvider works](functionality.md)

docs/book/v1/config-provider/functionality.md

@@ -1,5 +1,11 @@
 # How the ConfigProvider works
 
+## Summary
+
+Walks through how the ConfigProvider is picked up during bootstrap, merged, resolved, and executed within the Mezzio middleware pipeline.
+
+## Details
+
 The ConfigProvider is automatically picked up by the framework during application bootstrap.
 Let's look at it step by step:
 
@@ -20,4 +26,20 @@ $config = $container->get('config')['key'] ?? [];
 
 Below you can see how Mezzio and Dotkernel merge and use ConfigProviders to build the middleware pipeline and dependencies.
 
-![Headless Platform with Core Submodule](https://docs.dotkernel.org/img/headless-platform/ConfigProvider.png)
+![Diagram of Mezzio and Dotkernel merging ConfigProviders into the middleware pipeline](https://docs.dotkernel.org/img/headless-platform/ConfigProvider.png)
+
+## FAQ
+
+**Q: When is the ConfigProvider picked up?**
+A: Automatically, by the framework during application bootstrap.
+
+**Q: What happens during the "Resolve item" step?**
+A: `$app->pipe()` resolves a service name from the container, wraps a middleware array, or calls a closure/invokable object.
+
+**Q: Why does the error-handling middleware run last in the pipeline?**
+A: So it can catch any exceptions raised by the preceding middleware.
+
+## See also
+
+- [Introduction](introduction.md)
+- [Benefits](benefits.md)

docs/book/v1/config-provider/introduction.md

@@ -1,5 +1,11 @@
 # Introduction
 
+## Summary
+
+Introduces the `ConfigProvider` class, what it returns, and how it's used across Dotkernel applications and packages, with a code example.
+
+## Details
+
 In PHP, the `ConfigProvider` is a class that is part of an application's bootstrap process.
 It returns an array of configuration, settings, or anything else your application needs.
 In Dotkernel, each application module and package contains a `ConfigProvider` that normally returns:
@@ -51,3 +57,20 @@ All Dotkernel applications and packages use ConfigProviders:
 - [Dotkernel Frontend](https://docs.dotkernel.org/frontend-documentation/)
 - [Dotkernel Light](https://docs.dotkernel.org/light-documentation/)
 - [Dotkernel Packages](https://docs.dotkernel.org/packages/)
+
+## FAQ
+
+**Q: What does a ConfigProvider return in Dotkernel?**
+A: Dependency injection mappings, request handlers, and template file paths.
+
+**Q: Which Dotkernel applications use ConfigProviders?**
+A: Dotkernel API, Admin, Frontend, Light, and Packages all use ConfigProviders.
+
+**Q: Is the Dotkernel ConfigProvider approach specific to Dotkernel?**
+A: No, it follows an approach similar to Laminas/Mezzio.
+
+## See also
+
+- [How the ConfigProvider works](functionality.md)
+- [Benefits](benefits.md)
+- [Glossary](../glossary.md)

docs/book/v1/core/benefits.md

@@ -1,5 +1,11 @@
 # Benefits of the Core Submodule
 
+## Summary
+
+Lists the benefits the Core submodule pattern provides as your platform grows, such as scalability and easier onboarding.
+
+## Details
+
 This design pattern ensures:
 
 - Design flexibility.
@@ -10,3 +16,19 @@ This design pattern ensures:
 
 As your platform expands, each new application connects to the Dotkernel Headless Platform via the central API which services everything the other applications require.
 This ensures consistency throughout your platform, while allowing any number of outside connections as requirements arise.
+
+## FAQ
+
+**Q: How does the Core submodule pattern help as a platform grows?**
+A: It provides design flexibility and scalability suited for both enterprise and smaller applications.
+
+**Q: Can multiple developers work on the platform using this pattern?**
+A: Yes, it allows splitting the work across multiple developers.
+
+**Q: How do new applications connect to the platform?**
+A: Each new application connects via the central API, which services everything the other applications require.
+
+## See also
+
+- [Introduction](introduction.md)
+- [Using the Core Submodule](usage.md)

docs/book/v1/core/creation.md

@@ -1,11 +1,29 @@
 # Creating a Core Submodule
 
+## Summary
+
+A step-by-step guide to turning the Core module into a Git submodule, including adding, committing, and initializing/updating it.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- Git installed locally.
+- An existing Core module in your application to convert (see the note below).
+- Push access to a new, empty Git repository that will hold the extracted Core code.
+
+## Instructions
+
 The full steps for creating a submodule are described in [Git Tools – Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
 
 > There is already a Core module in some of the Dotkernel applications, but it works like any other module (App, Page, or User).
 > The Core modules are designed to be a starting point for the module’s transformation into a Git submodule.
 
 First create a new Git repository that will contain the Core code.
+
+> If the existing Core folder already has commit history you want to keep, extract it with a history-preserving tool such as `git subtree split` before pushing to the new repository.
+> Simply creating an empty repository and adding it as a submodule does not carry over the folder's original history.
+
 To create the submodule in an application, you need to have Git create the `.gitmodules` file in the root of the main repository by running the command below.
 Use the url from the new repository you just created instead of `<url>`:
 
@@ -21,7 +39,7 @@ This allows Git to manage the submodule correctly, from cloning, to updating, to
 > None of the Dotkernel applications have the .gitmodules file out of the box.
 > Only after isolating the Core into a Git submodule and pushing it to a separate Git repository does it become available to be included into any Dotkernel application.
 
-From now on, any changes to the Core submodule must be commited from within the Core folder, like for any other Git repository, using these commands (simplified version, provided as an example):
+From now on, any changes to the Core submodule must be committed from within the Core folder, like for any other Git repository, using these commands (simplified version, provided as an example):
 
 ```shell
 cd <path/to/submodule>
@@ -38,3 +56,25 @@ git submodule update
 ```
 
 > Do not forget to delete the existing Core module before adding the submodule to other applications.
+
+## FAQ
+
+**Q: Where can I find the full steps for creating a Git submodule?**
+A: In the official Git documentation, [Git Tools – Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
+
+**Q: What command creates a submodule in an application?**
+A: `git submodule add <url>`, using the URL of the new Core repository.
+
+**Q: How do I get the submodule after cloning the project?**
+A: Run `git submodule init` followed by `git submodule update`.
+
+**Q: Should I keep the existing Core module after adding the submodule?**
+A: No, delete the existing Core module before adding the submodule to other applications.
+
+**Q: Will I lose the Core folder's Git history when I create the submodule?**
+A: Yes, unless you extract it first with a history-preserving tool such as `git subtree split` — simply creating an empty repository and adding it as a submodule does not carry over the folder's original history.
+
+## See also
+
+- [Introduction](introduction.md)
+- [Using the Core Submodule](usage.md)