feat: add Middleware Guide and update documentation links

Author: 3m1n3nc3

docs/.vitepress/config.ts

@@ -37,6 +37,7 @@ export default defineConfig({
         items: [
           { text: 'Getting Started', link: '/guide/getting-started' },
           { text: 'CLI', link: '/guide/cli' },
+          { text: 'Middleware', link: '/guide/middleware' },
           { text: 'Database & Modeling', link: '/guide/database-modeling' },
           { text: 'API Reference', link: '/api' },
         ]

docs/guide/express-runtime.md

@@ -1,6 +1,6 @@
 # Express Runtime Interaction
 
-This page documents every supported way to interact directly with Arkstack's Express runtime.
+Arkstack's Express runtime integration provides multiple ways to interact with the underlying Express instance, allowing for flexible middleware application, route handling, and lifecycle control.
 
 ## Bootstrap Exports
 
@@ -91,5 +91,6 @@ await app.shutdown();
 ## Notes
 
 - `app.boot(port)` mounts public assets, binds router, applies middleware, registers error handling, starts the server, and attaches graceful shutdown.
+- For middleware layering and recommended usage, see [Middleware Guide](/guide/middleware).
 - Use the router contract (`getRouter`) for framework-agnostic behavior where possible.
 - Prefer `expressApp` only when you specifically need native Express APIs.

docs/guide/h3-runtime.md

@@ -1,6 +1,6 @@
 # H3 Runtime Interaction
 
-This page documents every supported way to interact directly with Arkstack's H3 runtime.
+Arkstack's H3 runtime integration provides multiple ways to interact with the underlying H3 instance, allowing for flexible middleware application, route handling, and lifecycle control.
 
 ## Bootstrap Exports
 
@@ -93,5 +93,6 @@ await app.shutdown();
 ## Notes
 
 - `app.boot(port)` mounts public assets, binds router, applies middleware, starts the server, and attaches graceful shutdown.
+- For middleware layering and recommended usage, see [Middleware Guide](/guide/middleware).
 - Use the router contract (`getRouter`) for framework-agnostic behavior where possible.
 - Prefer `h3App` only when you specifically need native H3 APIs.

docs/guide/middleware.md

@@ -0,0 +1,112 @@
+# Middleware Guide
+
+Arkstack provides a structured approach to middleware configuration and execution. This guide covers where to define middleware, the execution order, and best practices for layering.
+
+## Where middleware is configured
+
+Define middleware in your kit's `src/config/middleware.ts` file.
+
+Each config returns the same shape:
+
+```ts
+{
+  global: [],
+  before: [],
+  after: [],
+}
+```
+
+## Middleware execution order
+
+Arkstack applies middleware in this order during `app.boot(port)`:
+
+1. Public assets are mounted.
+2. `global` middleware runs.
+3. `before` middleware runs.
+4. Routes are bound.
+5. `after` middleware runs.
+6. Runtime-specific startup continues (Express error handler registration, then server start).
+
+Use each group with this intent:
+
+- `global`: middleware that should always run for every request (body parsing, CORS, method override, baseline security headers).
+- `before`: middleware that should run before route handlers are bound/executed (request context setup, auth gates, request-level tracing).
+- `after`: middleware that should run after routes are bound (post-route transforms, tail processing).
+
+## Express example
+
+`express/src/config/middleware.ts`:
+
+```ts
+import express, { Express } from 'express';
+import cors from 'cors';
+import methodOverride from 'method-override';
+import { MiddlewareConfig } from 'src/types/config';
+
+const config = (_app: Express): MiddlewareConfig => {
+  return {
+    global: [
+      express.json(),
+      express.urlencoded({ extended: true }),
+      methodOverride('X-HTTP-Method'),
+      cors(),
+    ],
+    before: [],
+    after: [],
+  };
+};
+
+export default config;
+```
+
+## H3 example
+
+`h3/src/config/middleware.ts`:
+
+```ts
+import { H3 } from 'h3';
+import { MiddlewareConfig } from 'src/types/config';
+import { cors } from '@app/http/middlewares/cors';
+
+const config = (_app: H3): MiddlewareConfig => {
+  return {
+    global: [cors()],
+    before: [],
+    after: [],
+  };
+};
+
+export default config;
+```
+
+## Route-level middleware
+
+Use config middleware for app-wide concerns. For route-specific behavior, attach middleware at route declaration time.
+
+Example from Express route registration:
+
+```ts
+import { Router } from 'src/core/router';
+
+Router.get(
+  '/',
+  ({ res }) => {
+    res
+      .setHeader('Content-Type', 'text/html')
+      .send('Welcome to the Express application!');
+  },
+  [
+    () => {
+      console.log('Middleware for root route');
+    },
+  ],
+);
+```
+
+## Team expectation
+
+- Prefer `src/config/middleware.ts` for cross-cutting concerns.
+- Keep `global` minimal and predictable.
+- Put request gating/initialization in `before`.
+- Reserve `after` for true post-route concerns.
+- Keep route-level middleware close to the route when the concern is route-specific.