@chidchanun/bcp 0.1.23 → 0.1.24

package/README.md

@@ -1,28 +1,53 @@
 # 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 with file-based routing, SSR, SPA navigation, API routes, middleware, loaders, guards, form actions, authentication, MySQL primitives, validation, structured errors, logging, file uploads and standalone production builds.
 
-> Current release target: `0.1.22`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
+> Current release target: `0.1.24`. BCP is pre-1.0 and each release candidate is validated before the manual npm publish step.
 
 ## Quick start
 
-After the packages are published:
-
 ```bash
-npx create-bcp-app my-app
+npx create-bcp-app@latest my-app
 cd my-app
 npm run dev
 ```
 
-Open `http://localhost:3000`.
+Default development URL:
 
-For local package testing from this repository:
+```text
+http://localhost:3000
+```
+
+## CLI
 
 ```bash
-npm run package:check
+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
 ```
 
-This creates package tarballs under `.package/artifacts` and verifies that `create-bcp-app` can generate a project from the packed BCP Framework artifact.
+Microsoft SQL Server also installs a Windows executable named `bcp.exe`. BCP Framework therefore also publishes the collision-free alias:
+
+```powershell
+bcp-framework doctor
+bcp-framework inspect
+bcp-framework dev
+bcp-framework build
+```
+
+Normal project npm scripts can continue using `bcp` because npm places `node_modules/.bin` first on the script PATH.
 
 ## Project structure
 
@@ -30,19 +55,17 @@ This creates package tarballs under `.package/artifacts` and verifies that `crea
 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/
+   ├─ hello/
+   │  └─ route.ts
+   └─ upload/
       └─ route.ts
 
 lib/
@@ -52,146 +75,8 @@ package.json
 tsconfig.json
 ```
 
-## Application imports and boundaries
-
-Generated applications include the project-root `@/` alias:
-
-```ts
-import {
-    db,
-} from "@/lib/database";
-```
-
-Modules that use React client hooks must declare `"use client"`:
-
-```tsx
-"use client";
-
-import {
-    useState,
-} from "react";
-```
-
-Server-only modules can declare:
-
-```ts
-import "bcp/server-only";
-```
-
-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.
-
-## Tailwind and critical CSS
-
-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.
-
-## Development hydration parity
-
-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.
-
-For example, this is supported application code:
-
-```tsx
-<div
-    className="
-        min-h-screen
-        bg-white
-        text-slate-950
-    "
-/>
-```
-
-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.
-
-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.
-
-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.
-
-See [Hydration and deterministic rendering](docs/hydration.md) for the transform pipeline and troubleshooting guidance.
-
-## Developer diagnostics
-
-BCP 0.1.22 adds dedicated developer tooling for diagnosing application setup without starting the development server.
-
-Run a project health check:
-
-```bash
-bcp doctor
-```
-
-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.
-
-Inspect the resolved project inputs BCP sees:
-
-```bash
-bcp inspect
-```
-
-This prints development env filenames, public environment variable names, resolved BCP configuration, dependency versions and discovered page/API routes.
-
-Both commands support JSON output:
-
-```bash
-bcp doctor --json
-bcp inspect --json
-```
-
-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.
-
-See [Developer Tools](docs/developer-tools.md) for the complete command reference.
-
-## Commands
-
-```bash
-bcp dev
-bcp routes
-bcp build
-bcp start
-bcp doctor
-bcp doctor --json
-bcp inspect
-bcp inspect --json
-bcp update
-bcp version
-```
-
-CLI server overrides are available with `--port` and `--hostname`.
-
-## Updating an existing project
-
-Once a project is on a BCP version that contains the updater, update to the current npm `latest` release with:
-
-```bash
-bcp update
-```
-
-Preview an update without changing files:
-
-```bash
-bcp update --check
-bcp update --dry-run
-```
-
-Or select a published version/dist-tag explicitly:
-
-```bash
-bcp update 0.1.22
-bcp update next
-```
-
-Versions published before the updater do not recognize `bcp update`. Bootstrap the newest CLI once from those projects:
-
-```bash
-npx @chidchanun/bcp@latest update
-```
-
-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.
-
 ## Routing
 
-BCP supports:
-
 ```text
 app/page.tsx                     /
 app/about/page.tsx               /about
@@ -201,143 +86,25 @@ app/catalog/[[...slug]]/page.tsx /catalog and /catalog/*
 app/(admin)/settings/page.tsx    /settings
 ```
 
-Static routes have priority over dynamic routes, which have priority over catch-all routes.
-
-## API routes
-
-```ts
-// app/api/hello/route.ts
-export function GET() {
-    return Response.json({
-        message: "Hello",
-    });
-}
-```
-
-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.
+Static routes have priority over dynamic and catch-all routes.
 
-## 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.
-
-```ts
-import {
-    bearerToken,
-    clientIp,
-    cookies,
-    json,
-    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.
-
-Response cookies and redirects can be composed for login-style flows:
-
-```ts
-import {
-    cookies,
-    redirect,
-} from "bcp/server";
-
-export async function POST() {
-    const cookieStore =
-        await cookies();
-
-    cookieStore.set(
-        "session",
-        "session-token",
-        {
-            httpOnly: true,
-            secure: true,
-            sameSite: "lax",
-            path: "/",
-            maxAge: 60 * 60 * 12,
-        }
-    );
-
-    return redirect(
-        "/dashboard",
-        303
-    );
-}
-```
-
-`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.
+## Server data
 
-## Server data loaders
-
-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.
-
-```text
-app/users/[id]/
-├─ loader.ts
-└─ page.tsx
-```
+A route can load server-only data with `loader.ts`:
 
 ```ts
 // app/users/[id]/loader.ts
-import {
-    getSession,
-    redirect,
-} from "bcp/server";
-
 export async function loader({
     params,
-    searchParams,
-}: {
-    params: {
-        id: string;
-    };
-    searchParams: URLSearchParams;
 }) {
-    const session =
-        await getSession();
-
-    if (!session) {
-        return redirect(
-            "/login",
-            303
-        );
-    }
-
     return {
         id:
             params.id,
-        query:
-            searchParams.get("q"),
-        session,
     };
 }
 ```
 
-Pages consume the serializable result with `useLoaderData<T>()`:
+The page consumes the serializable value with:
 
 ```tsx
 "use client";
@@ -350,434 +117,272 @@ export default function UserPage() {
     const data =
         useLoaderData<{
             id: string;
-            query: string | null;
         }>();
 
-    return (
-        <main>
-            User {data.id}
-        </main>
-    );
+    return <main>{data.id}</main>;
 }
 ```
 
-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.
+Protected route trees can use `guard.ts`, and route-owned mutations can use `actions.ts` with the public `<Form>` client API.
 
-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.
+## Server request APIs
 
-See [Server Data Loaders](docs/server-data-loaders.md) for serialization rules, authentication patterns, redirect behavior, SPA navigation, cache safety and request-context semantics.
+```ts
+import {
+    bearerToken,
+    clientIp,
+    cookies,
+    headers,
+    requestId,
+    requestMethod,
+    requestUrl,
+} from "bcp/server";
+```
 
-## Protected routes and auth guards
+`requestId()` accepts a valid incoming `X-Request-Id` or generates a stable UUID for the request.
 
-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 & Observability
 
-```text
-app/dashboard/
-├─ guard.ts
-├─ page.tsx
-└─ users/
-   └─ [id]/
-      ├─ loader.ts
-      └─ page.tsx
-```
+BCP 0.1.23 introduced structured server logging:
 
 ```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,
-    };
-}
-```
+export async function loader() {
+    const log =
+        await requestLogger({
+            feature:
+                "categories",
+        });
 
-Descendant loaders receive the merged result as `guardData`, so they do not need to repeat `getSession()`:
+    log.info(
+        "Loading categories"
+    );
 
-```ts
-export async function loader({
-    params,
-    guardData,
-}) {
     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";
-
-import {
-    useGuardData,
-} from "bcp";
-
-export default function DashboardPage() {
-    const guard =
-        useGuardData<{
-            session: {
-                email: string;
-            };
-            role: string;
-        }>();
+Configure output with:
 
-    return (
-        <main>
-            {guard.session.email}
-        </main>
-    );
-}
+```env
+BCP_LOG_LEVEL=debug
+BCP_LOG_FORMAT=json
 ```
 
-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.
-
-See [Protected Route Guards](docs/route-guards.md) for nested role policies, serialization rules, middleware ordering, cookie behavior and production hardening.
-
-## Form actions and server mutations
+Supported levels are `debug`, `info`, `warn`, `error` and `silent`. Formats are `pretty` and `json`.
 
-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 adds server-only multipart/file helpers through `bcp/server`:
 
 ```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();
-
-    // await db.execute(...)
-
-    revalidatePath("/users");
-
-    if (!name) {
-        return {
-            ok: false,
-            message: "Name is required",
-        };
-    }
-
-    if (
-        context.searchParams.get("done") === "1"
-    ) {
-        return redirect(
-            "/users",
-            303
+    const formData =
+        await parseMultipartFormData(
+            request,
+            {
+                maxBytes:
+                    8 * 1024 * 1024,
+            }
         );
-    }
-
-    return {
-        ok: true,
-        id: context.params.id,
-        name,
-        method: context.method,
-    };
-}
-```
-
-Client forms reference the named server action without importing it into the browser graph:
-
-```tsx
-"use client";
 
-import {
-    Form,
-    useActionData,
-    useActionError,
-    useFormStatus,
-} from "bcp";
+    const file =
+        requireUploadedFile(
+            formData,
+            "file",
+            {
+                maxBytes:
+                    5 * 1024 * 1024,
+                allowedTypes: [
+                    "image/png",
+                    "image/jpeg",
+                    "image/webp",
+                ],
+                allowedExtensions: [
+                    ".png",
+                    ".jpg",
+                    ".jpeg",
+                    ".webp",
+                ],
+            }
+        );
 
-function SubmitButton() {
-    const status =
-        useFormStatus();
-
-    return (
-        <button
-            type="submit"
-            disabled={status.pending}
-        >
-            {status.pending
-                ? "Saving..."
-                : "Save"}
-        </button>
-    );
-}
+    const saved =
+        await saveUploadedFile(
+            file,
+            {
+                directory:
+                    "./uploads",
+            }
+        );
 
-export default function UserForm() {
-    const result =
-        useActionData<{
-            ok: boolean;
-            message?: string;
-        }>();
-    const error =
-        useActionError();
-
-    return (
-        <Form
-            action="saveUser"
-            method="patch"
-            refresh
-        >
-            <input name="name" />
-            <SubmitButton />
-            {result?.message}
-            {error?.message}
-        </Form>
-    );
+    return Response.json({
+        fileName:
+            saved.fileName,
+        size:
+            saved.size,
+        checksumSha256:
+            saved.checksumSha256,
+    });
 }
 ```
 
-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.
-
-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.
-
-## JWT cookie sessions
+Upload helpers provide:
 
-BCP 0.1.8 adds HS256 JWT cookie sessions directly to `bcp/server`. Configure a server-only secret of at least 32 bytes:
-
-```env
-BCP_SESSION_SECRET=replace-this-with-a-long-random-secret-at-least-32-bytes
-```
+- multipart validation,
+- total and per-file size limits,
+- MIME/extension allowlists,
+- optional or required file fields,
+- safe UUID-based storage names,
+- filename sanitization,
+- path traversal protection,
+- no-overwrite-by-default storage,
+- SHA-256 checksum metadata.
 
-Login-style APIs can create an HttpOnly session cookie without manually signing or serializing the JWT:
+The security gateway enforces `server.bodyLimit` / `BCP_BODY_LIMIT` before request data reaches application handlers. The default is 1 MiB, so applications accepting larger files must raise it explicitly.
 
 ```ts
 import {
-    createSession,
-    json,
-} from "bcp/server";
-
-export async function POST() {
-    await createSession(
-        {
-            userId: 42,
-            email: "user@example.com",
-            role: "admin",
-        },
-        {
-            issuer: "my-app",
-            audience: "my-app-users",
-        }
-    );
+    defineConfig,
+} from "bcp/config";
 
-    return json({
-        success: true,
-    });
-}
+export default defineConfig({
+    server: {
+        bodyLimit:
+            10 * 1024 * 1024,
+    },
+});
 ```
 
-Protected API routes can verify and read the session:
+MIME type and extension are metadata checks, not content-signature verification. Security-sensitive applications should additionally inspect file content and use malware scanning where appropriate.
 
-```ts
-import {
-    getSession,
-    json,
-} from "bcp/server";
+See [File Upload](docs/file-upload.md).
 
-export async function GET() {
-    const session =
-        await getSession<{
-            userId: number;
-            email: string;
-            role: string;
-        }>({
-            issuer: "my-app",
-            audience: "my-app-users",
-        });
+## Development route graph recovery
 
-    if (!session) {
-        return json(
-            {
-                error: "Unauthorized",
-            },
-            {
-                status: 401,
-            }
-        );
-    }
+BCP 0.1.24 fixes a development route/client-bundle synchronization issue that could produce:
 
-    return json({
-        userId:
-            session.userId,
-        email:
-            session.email,
-        role:
-            session.role,
-    });
-}
+```text
+Client bundle was not found for route "/docs/[...slug]".
 ```
 
-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.
+The problem happened when the actual page topology changed but Windows/editor filesystem events were classified as `change` instead of `add`/`unlink`. The route scanner could see a new route while the incremental client bundle graph still represented the previous route tree.
 
-## create-bcp-app auth preset
+The dev gateway now compares the actual pathname/page/layout graph and automatically refreshes the internal development server/client bundler when topology changes. Manually deleting `.bcp-framework` should no longer be required to recover this state.
 
-BCP 0.1.8 can scaffold the JWT cookie foundation automatically:
+## Developer diagnostics
 
 ```bash
-npx create-bcp-app my-app --database mysql --auth jwt-cookie
-```
-
-Interactive setup offers `None` and `JWT Cookie`. Selecting JWT Cookie creates:
-
-```text
-lib/auth.ts
-app/api/auth/login/route.ts
-app/api/auth/logout/route.ts
-app/api/auth/me/route.ts
-```
-
-and adds:
-
-```env
-BCP_SESSION_SECRET=
+bcp doctor
+bcp inspect
 ```
 
-to `.env.example`.
+`bcp doctor` checks project structure, BCP/React installations, React renderer parity, duplicate framework copies, environment/config loading, route conflicts and client/server boundaries. Blocking failures return a non-zero exit code.
 
-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.
+`bcp inspect` prints resolved configuration, development env filenames, public variable names, dependency versions and discovered routes.
 
-The generated MySQL preset uses a reusable `db` pool and separate `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` and `DB_NAME` settings.
+For local release verification, install packed `.tgz` artifacts under the existing `bcp` dependency key. Do not install a second `@chidchanun/bcp` copy next to `node_modules/bcp`, because separate framework copies can split React contexts and produce misleading loader/hook errors.
 
-## Metadata
+## Validation and errors
 
 ```ts
-import type {
-    Metadata,
-} from "bcp";
+import {
+    v,
+    validateFormData,
+} from "bcp/validation";
 
-export const metadata: Metadata = {
-    title: "Dashboard",
-    description: "Dashboard page",
-};
+import {
+    badRequest,
+    unauthorized,
+    toErrorResponse,
+} from "bcp/error";
 ```
 
-Dynamic routes can export `generateMetadata()` and receive route params.
+Structured error responses use the common envelope:
+
+```json
+{
+  "error": {
+    "status": 400,
+    "code": "BAD_REQUEST",
+    "message": "Invalid request"
+  }
+}
+```
 
-## Cache and revalidation
+## Database
 
 ```ts
-export const revalidate = 60;
+import {
+    db,
+} from "bcp/database";
 ```
 
-Server data can use:
+The database layer provides a lazy MySQL pool, prepared execution, queries and transactions. Database migrations are managed through `bcp db` commands.
+
+## Authentication
 
 ```ts
 import {
-    cache,
-    dedupe,
-    revalidatePath,
-    revalidateTag,
-} from "bcp/cache";
+    auth,
+    requireAuth,
+    requireRole,
+} from "bcp/auth";
 ```
 
-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.
+BCP also exposes lower-level JWT cookie session helpers through `bcp/server`.
 
 ## Middleware
 
-```ts
-import {
-    next,
-    redirect,
-    type MiddlewareRequest,
-} from "bcp/middleware";
+Middleware v2 uses true onion execution:
 
-export function middleware(
-    request: MiddlewareRequest
+```ts
+export async function middleware(
+    request,
+    context,
+    next
 ) {
-    if (
-        request.nextUrl.pathname === "/private" &&
-        !request.cookies.has("session")
-    ) {
-        return redirect("/login");
-    }
+    const response =
+        await next();
+
+    response.headers.set(
+        "x-app",
+        "example"
+    );
 
-    return next();
+    return response;
 }
 ```
 
-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.
+Existing v1 middleware remains supported.
 
-## Configuration
-
-```ts
-import {
-    defineConfig,
-} from "bcp/config";
+## Hydration parity
 
-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=()",
-    },
-});
-```
+BCP 0.1.20 normalized Windows CRLF/CR source line endings in development instrumentation. BCP 0.1.21 completed SSR/client JSX semantic parity by preserving JSX through the Babel React Refresh pass and allowing esbuild to perform the development JSX transform.
 
-Development/build precedence is CLI > `BCP_*` environment > `bcp.config.*` > defaults. Standalone start uses CLI > runtime environment > the config frozen into the production build.
+Multiline quoted JSX attributes are supported without rewriting classes onto a single line or applying `suppressHydrationWarning` as a framework workaround.
 
 ## Production
 
@@ -786,78 +391,74 @@ npm run build
 npm start
 ```
 
-The standalone output is generated under:
+Standalone output is generated 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.
+## Updating
 
-## Package preparation
+```bash
+bcp update
+bcp update --check
+bcp update --dry-run
+bcp update 0.1.24
+bcp update next
+```
 
-The development monorepo stays private. Publishable artifacts are produced separately:
+Projects published before the updater can bootstrap it once with:
 
 ```bash
-npm run package:prepare
-npm run package:check
-npm run release:check
+npx @chidchanun/bcp@latest update
 ```
 
-For the final Release Candidate gate:
+## Release validation
 
 ```bash
-npm login
+npm run typecheck
+npm run test:unit
 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.
-
-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.
-
-`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.
-
-No real npm publish command is run automatically by the repository.
+After RC passes, releases are tagged and published manually with the guarded release scripts.
 
 ## Documentation
 
 - [Getting Started](docs/getting-started.md)
 - [Application Modules](docs/application-modules.md)
+- [Routing](docs/routing.md)
 - [Server Request APIs](docs/server-request-apis.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)
+- [Form Actions](docs/form-actions.md)
 - [Validation](docs/validation.md)
 - [Error Handling](docs/error-handling.md)
+- [File Upload](docs/file-upload.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)
+- [Development Logging](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
 
-BCP Framework currently targets Node.js 24.11 or newer and React 19.
+- Node.js 24.11 or newer
+- React 19
 
 ## 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.