@chidchanun/bcp 0.1.23 → 0.1.25

package/README.md

@@ -1,863 +1,943 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, validation, structured errors, authentication, database primitives, security defaults and standalone production builds.
+BCP Framework is a React full-stack framework focused on file-based routing, server rendering, server-side data loading, guarded application flows, API routes, authentication, database access, validation, logging, file uploads, storage adapters and standalone production deployment.
 
-> Current release target: `0.1.22`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
+> **Development target:** `0.1.25`
+>
+> BCP is still pre-1.0. Features documented for the current development target should not be presented as published npm behavior until the release candidate has passed and the matching version has been published.
 
-## Quick start
-
-After the packages are published:
-
-```bash
-npx create-bcp-app my-app
-cd my-app
-npm run dev
-```
+## Overview
 
-Open `http://localhost:3000`.
+BCP provides a single application model for React pages and server code:
 
-For local package testing from this repository:
-
-```bash
-npm run package:check
+```text
+Browser
+  ↓
+BCP middleware / security
+  ↓
+Route guard
+  ↓
+Loader / action / API route
+  ↓
+React SSR
+  ↓
+Hydration / SPA navigation
 ```
 
-This creates package tarballs under `.package/artifacts` and verifies that `create-bcp-app` can generate a project from the packed BCP Framework artifact.
-
-## Project structure
+The framework is designed so application code can stay close to the route that owns it:
 
 ```text
 app/
 ├─ layout.tsx
 ├─ page.tsx
-├─ loading.tsx
-├─ error.tsx
-├─ not-found.tsx
 ├─ dashboard/
 │  ├─ guard.ts
-│  ├─ page.tsx
 │  └─ users/
 │     └─ [id]/
 │        ├─ loader.ts
 │        ├─ actions.ts
 │        └─ page.tsx
 └─ api/
-   └─ hello/
+   └─ upload/
       └─ route.ts
-
-lib/
-public/
-bcp.config.ts
-package.json
-tsconfig.json
 ```
 
-## Application imports and boundaries
+## Current capabilities
+
+| Area | Capability |
+| --- | --- |
+| Application | React SSR, hydration, layouts, metadata, SPA navigation |
+| Routing | Static, dynamic, catch-all, optional catch-all and route groups |
+| Server data | `loader.ts`, request-scoped server APIs |
+| Mutations | Route-owned `actions.ts` and `<Form>` |
+| Authorization | `guard.ts`, `requireAuth()`, `requireRole()` |
+| Authentication | JWT cookie sessions and auth helpers |
+| Middleware | Middleware System v2 with onion execution |
+| Validation | Typed validation helpers and structured validation errors |
+| Error handling | HTTP error helpers and consistent error responses |
+| Database | MySQL pool/query helpers, transactions and migrations |
+| Logging | Structured logger, request logger and request IDs |
+| Uploads | Multipart parsing, file validation and safe local persistence |
+| Storage | `StorageAdapter`, local storage adapter and file delivery |
+| Caching | Response cache and revalidation primitives |
+| Developer tools | `doctor`, `inspect`, updater and route inspection |
+| Production | Standalone server build with production middleware pipeline |
 
-Generated applications include the project-root `@/` alias:
+## Requirements
 
-```ts
-import {
-    db,
-} from "@/lib/database";
-```
+- Node.js `24.11` or newer
+- React `19`
+- npm
 
-Modules that use React client hooks must declare `"use client"`:
+Database features currently target MySQL.
 
-```tsx
-"use client";
+## Quick start
 
-import {
-    useState,
-} from "react";
+Create a new application:
+
+```bash
+npx create-bcp-app@latest my-app
+cd my-app
+npm run dev
 ```
 
-Server-only modules can declare:
+Default development URL:
 
-```ts
-import "bcp/server-only";
+```text
+http://localhost:3000
 ```
 
-Database helpers generated by `create-bcp-app` include the server-only marker automatically. A server-only helper must not be imported from a hydrated page/client graph. Use an API route or a server-only route primitive such as `loader.ts`, `guard.ts` or `actions.ts`.
-
-See [Application Modules](docs/application-modules.md) for the complete boundary model and examples.
+A generated project normally exposes scripts such as:
 
-## Tailwind and critical CSS
+```json
+{
+  "scripts": {
+    "dev": "bcp dev",
+    "build": "bcp build",
+    "start": "bcp start",
+    "routes": "bcp routes",
+    "update": "bcp update"
+  }
+}
+```
 
-Generated Tailwind projects compile to `public/bcp.css`. BCP 0.1.6 inlines that stylesheet into SSR HTML when it is 8 KiB or smaller, removing the stylesheet request from the initial render-critical path. Larger stylesheets remain external so the browser can cache them normally. If the application's Content Security Policy does not allow inline styles, BCP automatically keeps the external stylesheet link.
+## Packages
 
-## Development hydration parity
+The public framework package is published as:
 
-BCP 0.1.21 fixes a development-only hydration mismatch where the SSR transform and the React Refresh client transform could assign different semantic values to the same multiline JSX attribute.
+```text
+@chidchanun/bcp
+```
 
-For example, this is supported application code:
+Applications normally consume it through the dependency key:
 
-```tsx
-<div
-    className="
-        min-h-screen
-        bg-white
-        text-slate-950
-    "
-/>
+```text
+bcp
 ```
 
-BCP 0.1.20 already normalized Windows `CRLF` and standalone `CR` source line endings to `LF`, but Babel's JSX transform could still collapse the multiline quoted attribute to a single-space-separated string while SSR preserved the original line breaks and indentation.
+This keeps imports concise:
 
-In 0.1.21, Babel remains responsible for TypeScript stripping and React Refresh registration, but JSX is preserved until esbuild compiles it with the development JSX runtime. This keeps static JSX attribute semantics aligned between SSR and the development client bundle.
+```ts
+import {
+    Form,
+    Link,
+    useLoaderData,
+} from "bcp";
+```
 
-Applications should not need to rewrite multiline classes to one line or use `suppressHydrationWarning` to work around framework transform differences. Genuine runtime mismatches caused by values such as `Date.now()`, `Math.random()`, browser-only initial state, locale differences or changing external data still need to be fixed in application code.
+Server-only APIs use dedicated entrypoints such as:
 
-See [Hydration and deterministic rendering](docs/hydration.md) for the transform pipeline and troubleshooting guidance.
+```ts
+import {
+    cookies,
+    logger,
+    requestId,
+} from "bcp/server";
+```
 
-## Developer diagnostics
+## Project structure
 
-BCP 0.1.22 adds dedicated developer tooling for diagnosing application setup without starting the development server.
+A typical application can grow into this layout:
 
-Run a project health check:
+```text
+app/
+├─ layout.tsx
+├─ page.tsx
+├─ login/
+│  └─ page.tsx
+├─ dashboard/
+│  ├─ guard.ts
+│  ├─ page.tsx
+│  └─ users/
+│     └─ [id]/
+│        ├─ loader.ts
+│        ├─ actions.ts
+│        └─ page.tsx
+└─ api/
+   ├─ auth/
+   │  └─ login/
+   │     └─ route.ts
+   └─ upload/
+      └─ route.ts
 
-```bash
-bcp doctor
+lib/
+public/
+migrations/
+bcp.config.ts
+package.json
+tsconfig.json
 ```
 
-The doctor checks the Node.js runtime, project structure, installed BCP/React packages, React and React DOM version parity, duplicate React package roots, environment/config loading, route conflicts and client/server boundaries. Blocking failures produce a non-zero process exit code.
+BCP keeps page rendering, route authorization, server data and route mutations close together without requiring one large application router configuration file.
+
+## Routing
 
-Inspect the resolved project inputs BCP sees:
+Page routes are discovered from `app/**/page.tsx`.
 
-```bash
-bcp inspect
+```text
+app/page.tsx                     /
+app/about/page.tsx               /about
+app/users/[id]/page.tsx          /users/:id
+app/docs/[...slug]/page.tsx      /docs/*
+app/catalog/[[...slug]]/page.tsx /catalog and /catalog/*
+app/(admin)/settings/page.tsx    /settings
 ```
 
-This prints development env filenames, public environment variable names, resolved BCP configuration, dependency versions and discovered page/API routes.
+Static routes have priority over dynamic and catch-all routes.
 
-Both commands support JSON output:
+API routes use `route.ts`:
 
-```bash
-bcp doctor --json
-bcp inspect --json
+```text
+app/api/users/route.ts       /api/users
+app/api/users/[id]/route.ts  /api/users/:id
 ```
 
-The duplicate React checks are especially useful when verifying local framework builds. Install packed `.tgz` artifacts for release testing instead of linking `.package/bcp` directly into another project, because a linked staging directory can make the application and SSR renderer resolve different React instances.
+Read more: [Routing](docs/routing.md)
 
-See [Developer Tools](docs/developer-tools.md) for the complete command reference.
+## Layouts and metadata
 
-## Commands
+Routes can inherit layouts from parent directories. The framework resolves the layout chain while rendering both development and standalone production requests.
 
-```bash
-bcp dev
-bcp routes
-bcp build
-bcp start
-bcp doctor
-bcp doctor --json
-bcp inspect
-bcp inspect --json
-bcp update
-bcp version
-```
+Document metadata is route-aware and can be generated alongside the page tree.
 
-CLI server overrides are available with `--port` and `--hostname`.
+Read more: [Routing](docs/routing.md)
 
-## Updating an existing project
+## Server data loaders
 
-Once a project is on a BCP version that contains the updater, update to the current npm `latest` release with:
+Place `loader.ts` next to a page when the route needs server-side data.
 
-```bash
-bcp update
+```ts
+// app/users/[id]/loader.ts
+export async function loader({
+    params,
+}) {
+    return {
+        id:
+            params.id,
+    };
+}
 ```
 
-Preview an update without changing files:
+Consume the serializable result in a client page:
 
-```bash
-bcp update --check
-bcp update --dry-run
-```
+```tsx
+"use client";
+
+import {
+    useLoaderData,
+} from "bcp";
 
-Or select a published version/dist-tag explicitly:
+export default function UserPage() {
+    const data =
+        useLoaderData<{
+            id: string;
+        }>();
 
-```bash
-bcp update 0.1.22
-bcp update next
+    return (
+        <main>
+            User {data.id}
+        </main>
+    );
+}
 ```
 
-Versions published before the updater do not recognize `bcp update`. Bootstrap the newest CLI once from those projects:
+Read more: [Server Data Loaders](docs/server-data-loaders.md)
 
-```bash
-npx @chidchanun/bcp@latest update
-```
+## Route guards
 
-The updater changes the framework dependency and package-manager lockfile, detects npm/pnpm/Yarn/Bun from the project lockfile, and restores package metadata if installation fails. It does not overwrite application source files, database schemas or authentication code. See [Updating BCP Framework](docs/updating.md) for the complete behavior and migration notes.
+A route tree can define `guard.ts` to authorize access before the protected route is rendered.
 
-## Routing
+Authentication-aware guards are available through `bcp/auth`:
 
-BCP supports:
+```ts
+import {
+    requireRole,
+} from "bcp/auth";
 
-```text
-app/page.tsx                     /
-app/about/page.tsx               /about
-app/users/[id]/page.tsx          /users/:id
-app/docs/[...slug]/page.tsx      /docs/*
-app/catalog/[[...slug]]/page.tsx /catalog and /catalog/*
-app/(admin)/settings/page.tsx    /settings
+export const guard =
+    requireRole("admin");
 ```
 
-Static routes have priority over dynamic routes, which have priority over catch-all routes.
+The standalone production pipeline preserves the same active request context used by authentication and server request APIs.
 
-## API routes
+Read more:
 
-```ts
-// app/api/hello/route.ts
-export function GET() {
-    return Response.json({
-        message: "Hello",
-    });
-}
-```
+- [Route Guards](docs/route-guards.md)
+- [Auth Route Guards](docs/auth-route-guards.md)
+
+## Form actions
+
+Route-owned mutations live in `actions.ts` and can be invoked through the public `<Form>` API.
+
+This supports both progressive form submission and SPA action transport while keeping mutation logic server-only.
 
-Supported methods include GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS. HEAD falls back to GET when no explicit HEAD handler exists, and OPTIONS is generated automatically when appropriate.
+Read more: [Form Actions](docs/form-actions.md)
 
 ## Server request APIs
 
-BCP 0.1.7 adds request-scoped server helpers through `bcp/server`. These helpers are server-only and are available from API handlers, server data loaders, route guards and form actions.
+Request-scoped APIs are exposed through `bcp/server`:
 
 ```ts
 import {
     bearerToken,
     clientIp,
     cookies,
-    json,
+    headers,
     requestId,
     requestMethod,
     requestUrl,
 } from "bcp/server";
-
-export async function GET() {
-    const url =
-        await requestUrl();
-
-    return json({
-        pathname:
-            url.pathname,
-        method:
-            await requestMethod(),
-        requestId:
-            await requestId(),
-        bearerToken:
-            await bearerToken(),
-        clientIp:
-            await clientIp(),
-        session:
-            (
-                await cookies()
-            ).get(
-                "session"
-            )?.value ?? null,
-    });
-}
 ```
 
-`requestId()` reuses a valid incoming `X-Request-Id` or generates one stable UUID for the request. `bearerToken()` extracts a Bearer credential without decoding or verifying it. `clientIp()` uses the direct socket address by default; applications behind a trusted reverse proxy can explicitly use `clientIp({ trustProxy: true })` to read validated `Forwarded`, `X-Forwarded-For` or `X-Real-IP` values.
+`requestId()` uses a valid incoming `X-Request-Id` when available or generates a stable UUID for the active request.
 
-Response cookies and redirects can be composed for login-style flows:
+Read more: [Server Request APIs](docs/server-request-apis.md)
+
+## Authentication and sessions
+
+High-level authentication helpers are available through:
 
 ```ts
 import {
-    cookies,
-    redirect,
+    auth,
+    requireAuth,
+    requireRole,
+} from "bcp/auth";
+```
+
+Lower-level JWT cookie session primitives are available through `bcp/server`:
+
+```ts
+import {
+    createSession,
+    createSessionToken,
+    destroySession,
+    getSession,
+    verifySessionToken,
 } from "bcp/server";
+```
 
-export async function POST() {
-    const cookieStore =
-        await cookies();
+Authentication is intentionally separated from application-specific credential lookup so projects can connect their own user table or identity provider.
 
-    cookieStore.set(
-        "session",
-        "session-token",
-        {
-            httpOnly: true,
-            secure: true,
-            sameSite: "lax",
-            path: "/",
-            maxAge: 60 * 60 * 12,
-        }
-    );
+Read more:
+
+- [Authentication](docs/authentication.md)
+- [JWT Cookie Sessions](docs/session-auth.md)
 
-    return redirect(
-        "/dashboard",
-        303
+## Middleware
+
+Middleware System v2 uses onion-style execution:
+
+```ts
+export async function middleware(
+    request,
+    context,
+    next
+) {
+    const response =
+        await next();
+
+    response.headers.set(
+        "x-app",
+        "example"
     );
+
+    return response;
 }
 ```
 
-`redirect()` defaults to status `307`; supported statuses are `301`, `302`, `303`, `307` and `308`. Use `cookieStore.delete("session")` to expire a cookie. See [Server Request APIs](docs/server-request-apis.md) for proxy trust, URL handling, response helpers, request isolation, cookie options and boundary details.
+This allows middleware to run logic both before and after downstream route execution.
 
-## Server data loaders
+Existing middleware v1 behavior remains supported for compatibility.
 
-BCP 0.1.9 adds a server-only `loader.ts` convention next to `page.tsx`. The loader runs before SSR, receives route `params` plus `searchParams`, and can use `bcp/server` APIs, sessions and server-only database modules.
+Read more: [Middleware](docs/middleware.md)
 
-```text
-app/users/[id]/
-├─ loader.ts
-└─ page.tsx
-```
+## Validation
+
+BCP includes typed validation primitives:
 
 ```ts
-// app/users/[id]/loader.ts
 import {
-    getSession,
-    redirect,
-} from "bcp/server";
+    v,
+    validateFormData,
+} from "bcp/validation";
+```
 
-export async function loader({
-    params,
-    searchParams,
-}: {
-    params: {
-        id: string;
-    };
-    searchParams: URLSearchParams;
-}) {
-    const session =
-        await getSession();
+Validation can be shared by API routes and form actions without coupling application schemas to the rendering layer.
 
-    if (!session) {
-        return redirect(
-            "/login",
-            303
-        );
-    }
+Read more: [Validation](docs/validation.md)
 
-    return {
-        id:
-            params.id,
-        query:
-            searchParams.get("q"),
-        session,
-    };
+## Error handling
+
+Structured HTTP error helpers are exposed through `bcp/error`:
+
+```ts
+import {
+    badRequest,
+    forbidden,
+    notFoundResponse,
+    toErrorResponse,
+    unauthorized,
+} from "bcp/error";
+```
+
+The common error envelope is:
+
+```json
+{
+  "error": {
+    "status": 400,
+    "code": "BAD_REQUEST",
+    "message": "Invalid request"
+  }
 }
 ```
 
-Pages consume the serializable result with `useLoaderData<T>()`:
+Read more: [Error Handling](docs/error-handling.md)
 
-```tsx
-"use client";
+## Database
+
+Database helpers are exposed through:
 
+```ts
 import {
-    useLoaderData,
-} from "bcp";
+    db,
+} from "bcp/database";
+```
 
-export default function UserPage() {
-    const data =
-        useLoaderData<{
-            id: string;
-            query: string | null;
-        }>();
+The database layer provides:
 
-    return (
-        <main>
-            User {data.id}
-        </main>
-    );
-}
-```
+- lazy MySQL pool creation,
+- prepared execution,
+- query helpers,
+- transactions,
+- migration status and rollback support.
 
-Loader data is validated as JSON-safe before SSR and is serialized into framework data so hydration reads the same value without importing `loader.ts` into the browser graph. A loader may also return a Web `Response`; response cookies are preserved on redirects.
+Migration commands:
 
-Loader-backed pages now use the same SPA navigation model as normal BCP routes. `<Link>`, `navigate()`, `router.push()`, `router.replace()`, history navigation and `router.refresh()` request `/_bcp/navigation`; the server executes the target loader inside a fresh target-page request context and returns current loader data with the route payload. Same-origin loader redirects continue through the router while preserving `Set-Cookie` headers. Superseded navigations are aborted and sequence-checked so stale responses cannot update the active route. Loader pages remain excluded from the production response-cache manifest by default because their output may depend on session, cookie, request identity or user-specific database state.
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
+```
 
-See [Server Data Loaders](docs/server-data-loaders.md) for serialization rules, authentication patterns, redirect behavior, SPA navigation, cache safety and request-context semantics.
+Read more:
 
-## Protected routes and auth guards
+- [Database](docs/database.md)
+- [Database Migrations](docs/database-migrations.md)
 
-BCP 0.1.10 adds scoped `guard.ts` / `guard.tsx` files for page authorization. A guard protects the pages in its directory and descendant route directories, runs before the page loader, and can use the same request/session APIs as a loader.
+## Logging and observability
 
-```text
-app/dashboard/
-├─ guard.ts
-├─ page.tsx
-└─ users/
-   └─ [id]/
-      ├─ loader.ts
-      └─ page.tsx
-```
+Structured server logging is available through `bcp/server`:
 
 ```ts
-// app/dashboard/guard.ts
 import {
-    getSession,
-    redirect,
+    logger,
+    requestLogger,
 } from "bcp/server";
 
-export async function guard() {
-    const session =
-        await getSession<{
-            userId: number;
-            email: string;
-            role: string;
-        }>();
-
-    if (!session) {
-        return redirect(
-            "/login",
-            303
-        );
+logger.info(
+    "Application event",
+    {
+        feature:
+            "catalog",
     }
-
-    return {
-        session,
-        role:
-            session.role,
-    };
-}
+);
 ```
 
-Descendant loaders receive the merged result as `guardData`, so they do not need to repeat `getSession()`:
+Request-scoped logging can automatically include request identity:
 
 ```ts
-export async function loader({
-    params,
-    guardData,
-}) {
+export async function loader() {
+    const log =
+        await requestLogger({
+            feature:
+                "categories",
+        });
+
+    log.info(
+        "Loading categories"
+    );
+
     return {
-        id:
-            params.id,
-        user:
-            guardData.session,
-        role:
-            guardData.role,
+        items: [],
     };
 }
 ```
 
-A page can consume the same authorization data with `useGuardData<T>()`:
-
-```tsx
-"use client";
+Environment controls:
 
-import {
-    useGuardData,
-} from "bcp";
+```env
+BCP_LOG_LEVEL=debug
+BCP_LOG_FORMAT=json
+```
 
-export default function DashboardPage() {
-    const guard =
-        useGuardData<{
-            session: {
-                email: string;
-            };
-            role: string;
-        }>();
+Supported levels:
 
-    return (
-        <main>
-            {guard.session.email}
-        </main>
-    );
-}
+```text
+debug
+info
+warn
+error
+silent
 ```
 
-Nested guards execute from root to child and receive merged ancestor output as `guardData`. Guard redirects and response cookies work for both direct document requests and SPA navigation. Guarded pages are excluded from the automatic production response cache, and standalone production strips user-supplied internal guard transport headers before evaluating authorization.
+Supported formats:
 
-See [Protected Route Guards](docs/route-guards.md) for nested role policies, serialization rules, middleware ordering, cookie behavior and production hardening.
+```text
+pretty
+json
+```
 
-## Form actions and server mutations
+Read more: [Logging and Observability](docs/development-logging.md)
 
-BCP 0.1.11 adds route-owned server mutations with `actions.ts` / `actions.tsx`. Actions stay on the server and let page forms perform create, update and delete operations without creating a dedicated API route for every mutation.
+## File upload
 
-```text
-app/users/[id]/
-├─ guard.ts
-├─ loader.ts
-├─ actions.ts
-└─ page.tsx
-```
+BCP `0.1.24` introduced multipart parsing and file validation:
 
 ```ts
-// app/users/[id]/actions.ts
-import "bcp/server-only";
-
 import {
-    redirect,
-    type PageActionContext,
+    parseMultipartFormData,
+    requireUploadedFile,
+    saveUploadedFile,
 } from "bcp/server";
 
-import {
-    revalidatePath,
-} from "bcp/cache";
-
-export async function saveUser(
-    formData: FormData,
-    context: PageActionContext
+export async function POST(
+    request: Request
 ) {
-    const name =
-        String(
-            formData.get("name") ?? ""
-        ).trim();
+    const formData =
+        await parseMultipartFormData(
+            request,
+            {
+                maxBytes:
+                    8 * 1024 * 1024,
+            }
+        );
 
-    // await db.execute(...)
+    const file =
+        requireUploadedFile(
+            formData,
+            "file",
+            {
+                maxBytes:
+                    5 * 1024 * 1024,
+                allowedTypes: [
+                    "image/png",
+                    "image/jpeg",
+                    "image/webp",
+                ],
+                allowedExtensions: [
+                    ".png",
+                    ".jpg",
+                    ".jpeg",
+                    ".webp",
+                ],
+            }
+        );
 
-    revalidatePath("/users");
+    return Response.json(
+        await saveUploadedFile(
+            file,
+            {
+                directory:
+                    "./uploads",
+            }
+        )
+    );
+}
+```
 
-    if (!name) {
-        return {
-            ok: false,
-            message: "Name is required",
-        };
-    }
+Upload helpers provide:
 
-    if (
-        context.searchParams.get("done") === "1"
-    ) {
-        return redirect(
-            "/users",
-            303
-        );
-    }
+- multipart validation,
+- total request and per-file size limits,
+- MIME and extension allowlists,
+- required/optional file fields,
+- safe UUID-based storage names,
+- filename sanitization,
+- path traversal protection,
+- no-overwrite-by-default persistence,
+- SHA-256 checksum metadata.
 
-    return {
-        ok: true,
-        id: context.params.id,
-        name,
-        method: context.method,
-    };
-}
+The security gateway applies `server.bodyLimit` / `BCP_BODY_LIMIT` before application upload parsing. Applications accepting larger files must raise that outer limit explicitly.
+
+```ts
+import {
+    defineConfig,
+} from "bcp/config";
+
+export default defineConfig({
+    server: {
+        bodyLimit:
+            10 * 1024 * 1024,
+    },
+});
 ```
 
-Client forms reference the named server action without importing it into the browser graph:
+MIME type and extension validation are metadata checks, not content-signature verification. Security-sensitive applications should additionally verify content and use malware scanning where appropriate.
 
-```tsx
-"use client";
+Read more: [File Upload](docs/file-upload.md)
+
+## Storage adapters
 
+BCP `0.1.25` adds the first application-facing storage abstraction.
+
+```ts
 import {
-    Form,
-    useActionData,
-    useActionError,
-    useFormStatus,
-} from "bcp";
+    createLocalStorage,
+    storeUploadedFile,
+} from "bcp/server";
 
-function SubmitButton() {
-    const status =
-        useFormStatus();
+const storage =
+    createLocalStorage({
+        directory:
+            "./uploads",
+    });
 
-    return (
-        <button
-            type="submit"
-            disabled={status.pending}
-        >
-            {status.pending
-                ? "Saving..."
-                : "Save"}
-        </button>
+const stored =
+    await storeUploadedFile(
+        file,
+        {
+            storage,
+            key:
+                "avatars/user-101.webp",
+        }
     );
-}
+```
 
-export default function UserForm() {
-    const result =
-        useActionData<{
-            ok: boolean;
-            message?: string;
-        }>();
-    const error =
-        useActionError();
+The `StorageAdapter` contract contains:
 
-    return (
-        <Form
-            action="saveUser"
-            method="patch"
-            refresh
-        >
-            <input name="name" />
-            <SubmitButton />
-            {result?.message}
-            {error?.message}
-        </Form>
-    );
-}
+```text
+put
+stat
+read
+exists
+delete
 ```
 
-Supported semantic methods are POST, PUT, PATCH and DELETE. Guards execute before actions and pass merged authorization state through `context.guardData`. Actions can use cookies, JWT sessions, `requestMethod()`, redirects and cache revalidation. Enhanced forms submit through the BCP SPA transport; forms without JavaScript fall back to standard HTML POST with POST/Redirect/GET semantics. Action-backed pages are excluded from automatic production response caching.
+Application code can depend on this contract instead of depending directly on filesystem paths.
 
-See [Form Actions and Server Mutations](docs/form-actions.md) for action return values, pending/error state, progressive enhancement, guards, redirects, cookies, cache invalidation and standalone behavior.
+The built-in adapter in `0.1.25` is local filesystem storage. Cloud/object-storage adapters are planned for a later milestone.
 
-## JWT cookie sessions
+Storage keys are logical relative paths. Absolute paths and traversal segments are rejected.
 
-BCP 0.1.8 adds HS256 JWT cookie sessions directly to `bcp/server`. Configure a server-only secret of at least 32 bytes:
+Read more: [Storage and File Delivery](docs/storage.md)
 
-```env
-BCP_SESSION_SECRET=replace-this-with-a-long-random-secret-at-least-32-bytes
-```
+## Production file delivery
 
-Login-style APIs can create an HttpOnly session cookie without manually signing or serializing the JWT:
+Storage objects can be returned through a hardened HTTP response helper:
 
 ```ts
 import {
-    createSession,
-    json,
+    createStorageResponse,
 } from "bcp/server";
 
-export async function POST() {
-    await createSession(
-        {
-            userId: 42,
-            email: "user@example.com",
-            role: "admin",
-        },
+export async function GET(
+    request: Request
+) {
+    return createStorageResponse(
+        request,
+        storage,
+        "documents/report.pdf",
         {
-            issuer: "my-app",
-            audience: "my-app-users",
+            disposition:
+                "attachment",
+            downloadName:
+                "report.pdf",
         }
     );
-
-    return json({
-        success: true,
-    });
 }
 ```
 
-Protected API routes can verify and read the session:
-
-```ts
-import {
-    getSession,
-    json,
-} from "bcp/server";
+`createStorageResponse()` supports:
 
-export async function GET() {
-    const session =
-        await getSession<{
-            userId: number;
-            email: string;
-            role: string;
-        }>({
-            issuer: "my-app",
-            audience: "my-app-users",
-        });
+- `GET`,
+- `HEAD`,
+- `ETag`,
+- `Last-Modified`,
+- `If-None-Match`,
+- `If-Modified-Since`,
+- `If-Range`,
+- single byte ranges with `206 Partial Content`,
+- `304 Not Modified`,
+- `416 Range Not Satisfiable`,
+- safe `Content-Disposition` filenames.
 
-    if (!session) {
-        return json(
-            {
-                error: "Unauthorized",
-            },
-            {
-                status: 401,
-            }
-        );
-    }
+The default cache policy is intentionally conservative:
 
-    return json({
-        userId:
-            session.userId,
-        email:
-            session.email,
-        role:
-            session.role,
-    });
-}
+```text
+private, max-age=0, must-revalidate
 ```
 
-Use `destroySession()` to expire the cookie. Low-level `createSessionToken()` and `verifySessionToken()` helpers are also available when an application needs to manage token storage itself. JWT payloads are signed, not encrypted, so sensitive secrets must not be stored inside them. See [JWT Cookie Sessions](docs/session-auth.md) for options and the security model.
+Public immutable caching must be opted into explicitly.
 
-## create-bcp-app auth preset
+Multiple byte ranges are intentionally not supported in `0.1.25`.
 
-BCP 0.1.8 can scaffold the JWT cookie foundation automatically:
+Read more: [Storage and File Delivery](docs/storage.md)
 
-```bash
-npx create-bcp-app my-app --database mysql --auth jwt-cookie
+## Caching
+
+BCP includes server response caching and revalidation primitives used by development and standalone production runtimes.
+
+Read more: [Caching](docs/caching.md)
+
+## Security
+
+The framework security layer includes request body limits and production request handling defaults. Application authorization is still the responsibility of route guards and application logic.
+
+Storage keys, filenames and MIME metadata must not be treated as authorization decisions.
+
+Read more: [Security](docs/security.md)
+
+## Environment and configuration
+
+Application configuration lives in:
+
+```text
+bcp.config.ts
 ```
 
-Interactive setup offers `None` and `JWT Cookie`. Selecting JWT Cookie creates:
+Public environment variables use the prefix:
 
 ```text
-lib/auth.ts
-app/api/auth/login/route.ts
-app/api/auth/logout/route.ts
-app/api/auth/me/route.ts
+BCP_PUBLIC_
 ```
 
-and adds:
+Server-only environment values remain server-side and are not emitted into browser bundles.
 
-```env
-BCP_SESSION_SECRET=
+Read more: [Configuration](docs/configuration.md)
+
+## Developer tools
+
+BCP includes project diagnostics:
+
+```bash
+bcp doctor
+bcp inspect
 ```
 
-to `.env.example`.
+`bcp doctor` checks areas such as:
 
-The generated `authenticateCredentials(email, password)` returns `null` by default. Applications must connect it to their own database lookup and password-hash verification before login can succeed. This is intentional so a newly generated project does not trust user identity supplied directly by the browser.
+- project structure,
+- BCP installation,
+- React / ReactDOM compatibility,
+- duplicate framework copies,
+- environment/config loading,
+- route conflicts,
+- client/server boundaries.
 
-The generated MySQL preset uses a reusable `db` pool and separate `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` and `DB_NAME` settings.
+`bcp inspect` reports resolved configuration, environment sources, dependencies and discovered routes.
 
-## Metadata
+Read more: [Developer Tools](docs/developer-tools.md)
 
-```ts
-import type {
-    Metadata,
-} from "bcp";
+## Windows CLI
+
+Microsoft SQL Server also installs an executable named `bcp.exe` on Windows.
 
-export const metadata: Metadata = {
-    title: "Dashboard",
-    description: "Dashboard page",
-};
+BCP therefore publishes the collision-free alias:
+
+```text
+bcp-framework
 ```
 
-Dynamic routes can export `generateMetadata()` and receive route params.
+Inside project npm scripts, `bcp` remains safe because npm puts `node_modules/.bin` at the front of `PATH`.
 
-## Cache and revalidation
+For direct PowerShell usage, prefer:
 
-```ts
-export const revalidate = 60;
+```powershell
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+npm exec -- bcp-framework dev
+npm exec -- bcp-framework build
 ```
 
-Server data can use:
+## CLI reference
 
-```ts
-import {
-    cache,
-    dedupe,
-    revalidatePath,
-    revalidateTag,
-} from "bcp/cache";
+```bash
+bcp dev
+bcp routes
+bcp build
+bcp start
+bcp doctor
+bcp doctor --json
+bcp inspect
+bcp inspect --json
+bcp update
+bcp version
+
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
 ```
 
-The current cache implementation is process-local and intentionally does not provide distributed invalidation across multiple Node.js instances. Loader-backed, route-guarded and action-backed pages are excluded from the automatic production response-cache manifest when their output or mutation flow may depend on request/session state. Cache server data explicitly only when the application has a safe user-aware cache key and invalidation strategy.
+## Development behavior
 
-## Middleware
+BCP includes Fast Refresh and deterministic development hydration behavior.
 
-```ts
-import {
-    next,
-    redirect,
-    type MiddlewareRequest,
-} from "bcp/middleware";
+Recent stabilization work also covers:
 
-export function middleware(
-    request: MiddlewareRequest
-) {
-    if (
-        request.nextUrl.pathname === "/private" &&
-        !request.cookies.has("session")
-    ) {
-        return redirect("/login");
-    }
+- Windows line-ending parity,
+- multiline JSX hydration parity,
+- duplicate BCP installation detection,
+- automatic page-route/client-bundle graph resynchronization,
+- standalone authentication guard request-context parity.
 
-    return next();
-}
-```
+A development topology change should no longer require manually deleting `.bcp-framework` to recover a missing client route bundle.
 
-Use middleware for request-wide interception and `guard.ts` for page-subtree authorization that needs to feed identity/role data into loaders, actions and pages. In standalone production, project middleware runs before route guards and form actions.
+Read more: [Hydration](docs/hydration.md)
 
-## Configuration
+## Production build
 
-```ts
-import {
-    defineConfig,
-} from "bcp/config";
+Build an application:
 
-export default defineConfig({
-    server: {
-        port: 3000,
-        hostname: "localhost",
-        bodyLimit: 1024 * 1024,
-    },
-    compression: true,
-    build: {
-        minify: true,
-        sourceMaps: false,
-    },
-    cache: {
-        response: true,
-    },
-    security: {
-        poweredByHeader: false,
-        contentSecurityPolicy: false,
-        frameOptions: "SAMEORIGIN",
-        referrerPolicy:
-            "strict-origin-when-cross-origin",
-        permissionsPolicy:
-            "camera=(), microphone=(), geolocation=()",
-    },
-});
+```bash
+npm run build
 ```
 
-Development/build precedence is CLI > `BCP_*` environment > `bcp.config.*` > defaults. Standalone start uses CLI > runtime environment > the config frozen into the production build.
-
-## Production
+Start the generated standalone runtime:
 
 ```bash
-npm run build
-npm start
+npm run start
 ```
 
-The standalone output is generated under:
+Production output is written under:
 
 ```text
 .bcp-framework/build/
 ├─ client/
 ├─ public/
 └─ server/
-   ├─ server.mjs
-   ├─ middleware.mjs
-   ├─ guards.mjs
-   ├─ actions.mjs
-   ├─ cache-manifest.json
-   └─ config.json
+   └─ server.mjs
 ```
 
-`guards.mjs` is generated only when the application contains protected route guards. `actions.mjs` is generated only when the application contains route form actions.
+The standalone runtime composes production middleware, security, cache, actions, guards, loaders and page rendering into the final HTTP pipeline.
+
+Runtime hostname/port overrides can be supplied to `bcp start` without rebuilding the application.
+
+Read more: [Deployment](docs/deployment.md)
 
-## Package preparation
+## Updating BCP
+
+```bash
+bcp update
+bcp update --check
+bcp update --dry-run
+bcp update 0.1.25
+bcp update next
+```
 
-The development monorepo stays private. Publishable artifacts are produced separately:
+Projects created before the updater was introduced can bootstrap it once using the public package:
 
 ```bash
-npm run package:prepare
-npm run package:check
-npm run release:check
+npx @chidchanun/bcp@latest update
 ```
 
-For the final Release Candidate gate:
+Read more: [Updating](docs/updating.md)
+
+## Framework development
+
+When working inside the BCP Framework repository itself:
+
+```bash
+npm install
+npm run typecheck
+npm run test:unit
+npm run test:e2e
+npm run test:package
+```
+
+Full release-candidate validation:
 
 ```bash
-npm login
 npm run rc:check
 ```
 
-`rc:check` validates tests/release metadata, checks npm package-name availability or ownership, performs `npm publish --dry-run`, and clean-installs both generated tarballs into temporary projects.
+A version must not be tagged or published until its release candidate and packed-package verification pass.
 
-After a real publish, `npm run release:visibility-check` verifies that the exact framework and generator versions are readable from the npm registry before the release is treated as ready for installation.
+Read more: [Releasing](docs/releasing.md)
 
-`package:prepare` stages the framework at `.package/bcp`. The default package name is `bcp`; set `BCP_PACKAGE_NAME` when preparing a scoped or alternate package name.
+## Documentation source
 
-No real npm publish command is run automatically by the repository.
+The `docs/` directory is the source content intended to feed the future **`bcp-docs-web`** documentation website.
 
-## Documentation
+Start with:
 
+- [Documentation Source Map](docs/README.md)
 - [Getting Started](docs/getting-started.md)
+- [Configuration](docs/configuration.md)
 - [Application Modules](docs/application-modules.md)
-- [Server Request APIs](docs/server-request-apis.md)
+- [Routing](docs/routing.md)
 - [Server Data Loaders](docs/server-data-loaders.md)
-- [Protected Route Guards](docs/route-guards.md)
-- [Form Actions and Server Mutations](docs/form-actions.md)
+- [Route Guards](docs/route-guards.md)
+- [Form Actions](docs/form-actions.md)
+- [Server Request APIs](docs/server-request-apis.md)
 - [Validation](docs/validation.md)
 - [Error Handling](docs/error-handling.md)
+- [File Upload](docs/file-upload.md)
+- [Storage and File Delivery](docs/storage.md)
 - [Authentication](docs/authentication.md)
 - [Auth Route Guards](docs/auth-route-guards.md)
-- [JWT Cookie Sessions](docs/session-auth.md)
+- [JWT Sessions](docs/session-auth.md)
 - [Database](docs/database.md)
 - [Database Migrations](docs/database-migrations.md)
 - [Middleware](docs/middleware.md)
-- [Hydration and deterministic rendering](docs/hydration.md)
+- [Hydration](docs/hydration.md)
 - [Developer Tools](docs/developer-tools.md)
-- [Updating BCP Framework](docs/updating.md)
-- [Routing](docs/routing.md)
-- [Configuration](docs/configuration.md)
+- [Logging and Observability](docs/development-logging.md)
 - [Caching](docs/caching.md)
 - [Security](docs/security.md)
 - [Deployment](docs/deployment.md)
+- [Updating](docs/updating.md)
 - [Releasing](docs/releasing.md)
 
-## Requirements
+## Documentation website model
+
+When `bcp-docs-web` is built, the recommended top-level information architecture is:
+
+```text
+Getting Started
+Routing & Data
+Authentication
+Database
+Runtime & Infrastructure
+API Reference
+Releases
+```
+
+`docs/README.md` contains the proposed route-to-source mapping for that website.
+
+## Release history
+
+Release notes are stored under:
+
+```text
+docs/releases/
+```
+
+Recent milestones:
+
+| Version | Milestone |
+| --- | --- |
+| `0.1.20` | Hydration line-ending stabilization |
+| `0.1.21` | Hydration semantic parity |
+| `0.1.22` | Developer tools and diagnostics |
+| `0.1.23` | Logging and observability |
+| `0.1.24` | File Upload Foundation |
+| `0.1.25` | Storage Adapters and File Delivery |
+
+## Roadmap
+
+Current planned direction after `0.1.25`:
+
+1. S3-compatible / cloud storage adapter integration.
+2. Production upload streaming.
+3. Broader storage adapter ecosystem.
+4. Additional production hardening as new workloads expose edge cases.
 
-BCP Framework currently targets Node.js 24.11 or newer and React 19.
+Roadmap items are plans, not published API guarantees.
 
 ## License
 
-BCP Framework and `create-bcp-app` are released under the MIT License. See [LICENSE](LICENSE).
+BCP Framework and `create-bcp-app` are released under the MIT License.