@chidchanun/bcp 0.1.24 → 0.1.26

package/README.md

@@ -1,8 +1,75 @@
 # BCP Framework
 
-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.
+BCP Framework is a React full-stack framework focused on file-based routing, SSR, server data loading, guarded application flows, API routes, authentication, database access, validation, logging, uploads, storage adapters and standalone production deployment.
 
-> Current release target: `0.1.24`. BCP is pre-1.0 and each release candidate is validated before the manual npm publish step.
+> **Release candidate target:** `0.1.26`
+>
+> BCP is pre-1.0. The `0.1.26` source is complete for RC validation, but it must not be presented as a published npm release until the full release checks pass and the matching packages are published.
+
+## Overview
+
+BCP keeps React pages and their server behavior close to the route that owns them:
+
+```text
+Browser
+  ↓
+BCP security / middleware / cache
+  ↓
+Route guard
+  ↓
+Loader / action / API route
+  ↓
+React SSR
+  ↓
+Hydration / SPA navigation
+```
+
+A typical route can colocate its page, loader, guard and actions:
+
+```text
+app/
+├─ layout.tsx
+├─ page.tsx
+├─ dashboard/
+│  ├─ guard.ts
+│  └─ users/
+│     └─ [id]/
+│        ├─ loader.ts
+│        ├─ actions.ts
+│        └─ page.tsx
+└─ api/
+   └─ upload/
+      └─ route.ts
+```
+
+## 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 | Buffered multipart helpers and production multipart streaming |
+| Storage | Local + S3-compatible adapters, streaming I/O and ranged delivery |
+| Caching | Response cache and revalidation primitives |
+| Developer tools | `doctor`, `inspect`, updater and route inspection |
+| Production | Standalone server build with production middleware pipeline |
+
+## Requirements
+
+- Node.js `24.11` or newer
+- React `19`
+- npm
+
+Database features currently target MySQL.
 
 ## Quick start
 
@@ -18,36 +85,48 @@ Default development URL:
 http://localhost:3000
 ```
 
-## CLI
+Generated projects normally include:
 
-```bash
-bcp dev
-bcp routes
-bcp build
-bcp start
-bcp doctor
-bcp doctor --json
-bcp inspect
-bcp inspect --json
-bcp update
-bcp version
+```json
+{
+  "scripts": {
+    "dev": "bcp dev",
+    "build": "bcp build",
+    "start": "bcp start",
+    "routes": "bcp routes",
+    "update": "bcp update",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
 
-bcp db create create_users
-bcp db migrate
-bcp db status
-bcp db rollback
+## Packages
+
+The public framework package is published as:
+
+```text
+@chidchanun/bcp
 ```
 
-Microsoft SQL Server also installs a Windows executable named `bcp.exe`. BCP Framework therefore also publishes the collision-free alias:
+Applications normally consume it through the dependency key `bcp`, keeping imports concise:
 
-```powershell
-bcp-framework doctor
-bcp-framework inspect
-bcp-framework dev
-bcp-framework build
+```ts
+import {
+    Form,
+    Link,
+    useLoaderData,
+} from "bcp";
 ```
 
-Normal project npm scripts can continue using `bcp` because npm places `node_modules/.bin` first on the script PATH.
+Server-only APIs use dedicated entrypoints:
+
+```ts
+import {
+    cookies,
+    logger,
+    requestId,
+} from "bcp/server";
+```
 
 ## Project structure
 
@@ -55,21 +134,26 @@ Normal project npm scripts can continue using `bcp` because npm places `node_mod
 app/
 ├─ layout.tsx
 ├─ page.tsx
+├─ login/
+│  └─ page.tsx
 ├─ dashboard/
 │  ├─ guard.ts
+│  ├─ page.tsx
 │  └─ users/
 │     └─ [id]/
 │        ├─ loader.ts
 │        ├─ actions.ts
 │        └─ page.tsx
 └─ api/
-   ├─ hello/
-   │  └─ route.ts
+   ├─ auth/
+   │  └─ login/
+   │     └─ route.ts
    └─ upload/
       └─ route.ts
 
 lib/
 public/
+migrations/
 bcp.config.ts
 package.json
 tsconfig.json
@@ -77,6 +161,8 @@ tsconfig.json
 
 ## Routing
 
+Page routes are discovered from `app/**/page.tsx`:
+
 ```text
 app/page.tsx                     /
 app/about/page.tsx               /about
@@ -88,9 +174,24 @@ app/(admin)/settings/page.tsx    /settings
 
 Static routes have priority over dynamic and catch-all routes.
 
-## Server data
+API routes use `route.ts`:
 
-A route can load server-only data with `loader.ts`:
+```text
+app/api/users/route.ts       /api/users
+app/api/users/[id]/route.ts  /api/users/:id
+```
+
+Read more: [Routing](docs/routing.md)
+
+## Layouts and metadata
+
+Routes inherit layouts from parent directories. BCP resolves the layout chain in development and standalone production. Document metadata is route-aware and can be generated alongside the page tree.
+
+Read more: [Routing](docs/routing.md)
+
+## Server data loaders
+
+Place `loader.ts` next to a page when the route needs server-side data:
 
 ```ts
 // app/users/[id]/loader.ts
@@ -104,7 +205,7 @@ export async function loader({
 }
 ```
 
-The page consumes the serializable value with:
+Consume serializable loader data from a client page:
 
 ```tsx
 "use client";
@@ -119,11 +220,37 @@ export default function UserPage() {
             id: string;
         }>();
 
-    return <main>{data.id}</main>;
+    return <main>User {data.id}</main>;
 }
 ```
 
-Protected route trees can use `guard.ts`, and route-owned mutations can use `actions.ts` with the public `<Form>` client API.
+Read more: [Server Data Loaders](docs/server-data-loaders.md)
+
+## Route guards
+
+A route tree can define `guard.ts` to authorize access before rendering:
+
+```ts
+import {
+    requireRole,
+} from "bcp/auth";
+
+export const guard =
+    requireRole("admin");
+```
+
+The standalone production pipeline preserves the same active request context used by authentication and server request APIs.
+
+Read more:
+
+- [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. BCP supports progressive form submission and SPA action transport while keeping mutation code server-only.
+
+Read more: [Form Actions](docs/form-actions.md)
 
 ## Server request APIs
 
@@ -139,11 +266,127 @@ import {
 } from "bcp/server";
 ```
 
-`requestId()` accepts a valid incoming `X-Request-Id` or generates a stable UUID for the request.
+`requestId()` accepts a valid incoming `X-Request-Id` or generates a stable UUID for the active request.
+
+Read more: [Server Request APIs](docs/server-request-apis.md)
+
+## Authentication and sessions
+
+High-level authentication helpers:
+
+```ts
+import {
+    auth,
+    requireAuth,
+    requireRole,
+} from "bcp/auth";
+```
+
+Lower-level JWT cookie session primitives:
+
+```ts
+import {
+    createSession,
+    createSessionToken,
+    destroySession,
+    getSession,
+    verifySessionToken,
+} from "bcp/server";
+```
+
+Authentication is separated from application-specific credential lookup so projects can connect their own user table or identity provider.
+
+Read more:
+
+- [Authentication](docs/authentication.md)
+- [JWT Cookie Sessions](docs/session-auth.md)
+
+## 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;
+}
+```
+
+Existing middleware v1 behavior remains supported for compatibility.
 
-## Logging & Observability
+Read more: [Middleware](docs/middleware.md)
 
-BCP 0.1.23 introduced structured server logging:
+## Validation
+
+```ts
+import {
+    v,
+    validateFormData,
+} from "bcp/validation";
+```
+
+Read more: [Validation](docs/validation.md)
+
+## Error handling
+
+```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"
+  }
+}
+```
+
+Read more: [Error Handling](docs/error-handling.md)
+
+## Database
+
+```ts
+import {
+    db,
+} from "bcp/database";
+```
+
+The database layer provides a lazy MySQL pool, prepared execution, query helpers, transactions and migrations.
+
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
+```
+
+Read more:
+
+- [Database](docs/database.md)
+- [Database Migrations](docs/database-migrations.md)
+
+## Logging and observability
 
 ```ts
 import {
@@ -158,25 +401,9 @@ logger.info(
             "catalog",
     }
 );
-
-export async function loader() {
-    const log =
-        await requestLogger({
-            feature:
-                "categories",
-        });
-
-    log.info(
-        "Loading categories"
-    );
-
-    return {
-        items: [],
-    };
-}
 ```
 
-Configure output with:
+Environment controls:
 
 ```env
 BCP_LOG_LEVEL=debug
@@ -185,9 +412,11 @@ BCP_LOG_FORMAT=json
 
 Supported levels are `debug`, `info`, `warn`, `error` and `silent`. Formats are `pretty` and `json`.
 
-## File Upload
+Read more: [Logging and Observability](docs/development-logging.md)
+
+## File uploads
 
-BCP 0.1.24 adds server-only multipart/file helpers through `bcp/server`:
+BCP keeps the buffered multipart API for small forms:
 
 ```ts
 import {
@@ -196,202 +425,296 @@ import {
     saveUploadedFile,
 } from "bcp/server";
 
-export async function POST(
-    request: Request
-) {
-    const formData =
-        await parseMultipartFormData(
-            request,
-            {
-                maxBytes:
-                    8 * 1024 * 1024,
-            }
-        );
-
-    const file =
-        requireUploadedFile(
-            formData,
-            "file",
-            {
+const formData =
+    await parseMultipartFormData(
+        request,
+        {
+            maxBytes:
+                8 * 1024 * 1024,
+        }
+    );
+
+const file =
+    requireUploadedFile(
+        formData,
+        "file",
+        {
+            maxBytes:
+                5 * 1024 * 1024,
+            allowedTypes: [
+                "image/png",
+                "image/jpeg",
+                "image/webp",
+            ],
+        }
+    );
+```
+
+BCP `0.1.26` adds direct multipart-to-storage streaming for larger production uploads:
+
+```ts
+import {
+    storeMultipartFile,
+} from "bcp/server";
+
+const stored =
+    await storeMultipartFile(
+        request,
+        {
+            storage,
+            fieldName:
+                "file",
+            key:
+                "documents/report.pdf",
+            maxBytes:
+                100 * 1024 * 1024,
+            constraints: {
                 maxBytes:
-                    5 * 1024 * 1024,
+                    80 * 1024 * 1024,
                 allowedTypes: [
-                    "image/png",
-                    "image/jpeg",
-                    "image/webp",
+                    "application/pdf",
                 ],
                 allowedExtensions: [
-                    ".png",
-                    ".jpg",
-                    ".jpeg",
-                    ".webp",
+                    ".pdf",
                 ],
-            }
-        );
-
-    const saved =
-        await saveUploadedFile(
-            file,
-            {
-                directory:
-                    "./uploads",
-            }
-        );
-
-    return Response.json({
-        fileName:
-            saved.fileName,
-        size:
-            saved.size,
-        checksumSha256:
-            saved.checksumSha256,
-    });
-}
+            },
+        }
+    );
 ```
 
-Upload helpers provide:
+`storeMultipartFile()` parses `Request.body` incrementally and streams the selected file directly into the configured `StorageAdapter`. It does not call `request.formData()` for the target file.
+
+The security gateway still applies `server.bodyLimit` / `BCP_BODY_LIMIT` as the outer request limit. Streaming controls memory use; it does not bypass proxy/platform/body limits.
 
-- 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.
+MIME type and extension validation are metadata checks, not content-signature verification.
 
-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.
+Read more: [File Upload](docs/file-upload.md)
+
+## Storage adapters
+
+### Local filesystem
 
 ```ts
 import {
-    defineConfig,
-} from "bcp/config";
+    createLocalStorage,
+} from "bcp/server";
 
-export default defineConfig({
-    server: {
-        bodyLimit:
-            10 * 1024 * 1024,
-    },
-});
+const storage =
+    createLocalStorage({
+        directory:
+            "./uploads",
+    });
 ```
 
-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.
-
-See [File Upload](docs/file-upload.md).
+### S3-compatible storage
 
-## Development route graph recovery
+BCP `0.1.26` adds an S3-compatible backend:
 
-BCP 0.1.24 fixes a development route/client-bundle synchronization issue that could produce:
+```ts
+import {
+    createS3Storage,
+} from "bcp/server";
 
-```text
-Client bundle was not found for route "/docs/[...slug]".
+const storage =
+    createS3Storage({
+        bucket:
+            process.env.S3_BUCKET!,
+        region:
+            process.env.S3_REGION!,
+        endpoint:
+            process.env.S3_ENDPOINT,
+        accessKeyId:
+            process.env.S3_ACCESS_KEY_ID,
+        secretAccessKey:
+            process.env.S3_SECRET_ACCESS_KEY,
+    });
 ```
 
-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.
+Custom endpoints and `forcePathStyle` allow use with S3-compatible services such as MinIO. Explicit credentials are optional; when omitted, the AWS SDK can use its normal server-side credential provider chain.
 
-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.
+Keep cloud credentials server-only. Never expose them through `BCP_PUBLIC_*` variables.
 
-## Developer diagnostics
+Read more: [S3-Compatible Storage](docs/s3-storage.md)
 
-```bash
-bcp doctor
-bcp inspect
+### Streaming storage
+
+The `StorageAdapter` contract keeps its original buffered methods and adds optional streaming capabilities:
+
+```text
+put
+putStream?     ← 0.1.26
+stat
+read
+readStream?    ← 0.1.26
+exists
+delete
+```
+
+Use generic helpers so legacy and native-streaming adapters can share application code:
+
+```ts
+import {
+    getStorageCapabilities,
+    putStorageStream,
+    readStorageStream,
+} from "bcp/server";
 ```
 
-`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.
+Both built-in `0.1.26` adapters support native streaming reads, streaming writes and byte ranges.
 
-`bcp inspect` prints resolved configuration, development env filenames, public variable names, dependency versions and discovered routes.
+Streaming writes support `maxBytes` and `AbortSignal`. Local incomplete objects are removed on failure; S3 multipart uploads are configured to clean up parts on failed completion.
 
-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.
+Read more: [Storage and File Delivery](docs/storage.md)
 
-## Validation and errors
+## Production file delivery
 
 ```ts
 import {
-    v,
-    validateFormData,
-} from "bcp/validation";
+    createStorageResponse,
+} from "bcp/server";
 
-import {
-    badRequest,
-    unauthorized,
-    toErrorResponse,
-} from "bcp/error";
+export function GET(
+    request: Request
+) {
+    return createStorageResponse(
+        request,
+        storage,
+        "documents/report.pdf",
+        {
+            disposition:
+                "attachment",
+            downloadName:
+                "report.pdf",
+        }
+    );
+}
 ```
 
-Structured error responses use the common envelope:
+`createStorageResponse()` uses storage streaming and supports:
 
-```json
-{
-  "error": {
-    "status": 400,
-    "code": "BAD_REQUEST",
-    "message": "Invalid request"
-  }
-}
+- `GET` / `HEAD`,
+- ETag / Last-Modified validators,
+- `If-Range`,
+- single byte ranges with `206 Partial Content`,
+- `304 Not Modified`,
+- `416 Range Not Satisfiable`,
+- safe `Content-Disposition` filenames,
+- configurable cache control.
+
+The default cache policy remains:
+
+```text
+private, max-age=0, must-revalidate
 ```
 
-## Database
+Multiple byte ranges remain intentionally unsupported in `0.1.26`.
 
-```ts
-import {
-    db,
-} from "bcp/database";
+Read more: [Storage and File Delivery](docs/storage.md)
+
+## Caching
+
+BCP includes 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 remains 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
+```
+
+Public environment variables use:
+
+```text
+BCP_PUBLIC_
 ```
 
-The database layer provides a lazy MySQL pool, prepared execution, queries and transactions. Database migrations are managed through `bcp db` commands.
+Server-only values remain server-side and are not emitted into browser bundles.
 
-## Authentication
+Read more: [Configuration](docs/configuration.md)
 
-```ts
-import {
-    auth,
-    requireAuth,
-    requireRole,
-} from "bcp/auth";
+## Developer tools
+
+```bash
+bcp doctor
+bcp inspect
 ```
 
-BCP also exposes lower-level JWT cookie session helpers through `bcp/server`.
+`bcp doctor` checks project structure, BCP/React installation parity, duplicate framework copies, environment/config loading, route conflicts and client/server boundaries.
 
-## Middleware
+`bcp inspect` reports resolved configuration, environment sources, dependency versions and discovered routes.
 
-Middleware v2 uses true onion execution:
+Read more: [Developer Tools](docs/developer-tools.md)
 
-```ts
-export async function middleware(
-    request,
-    context,
-    next
-) {
-    const response =
-        await next();
+## Windows CLI
 
-    response.headers.set(
-        "x-app",
-        "example"
-    );
+Microsoft SQL Server can install another executable named `bcp.exe`. BCP therefore publishes the collision-free alias `bcp-framework`.
 
-    return response;
-}
+Inside npm scripts, `bcp` is safe because npm prepends the project's `node_modules/.bin` to `PATH`.
+
+For direct PowerShell usage, use the project-local CLI:
+
+```powershell
+npm exec -- bcp-framework --version
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+npm exec -- bcp-framework routes
+npm exec -- bcp-framework dev
+npm exec -- bcp-framework build
+```
+
+This keeps the CLI version aligned with the framework installed by the application.
+
+## CLI reference
+
+```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
 ```
 
-Existing v1 middleware remains supported.
+## Development behavior
 
-## Hydration parity
+BCP includes Fast Refresh and deterministic development hydration behavior. Recent stabilization work covers:
 
-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.
+- 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.
 
-Multiline quoted JSX attributes are supported without rewriting classes onto a single line or applying `suppressHydrationWarning` as a framework workaround.
+Read more: [Hydration](docs/hydration.md)
 
-## Production
+## Production build
 
 ```bash
 npm run build
-npm start
+npm run start
 ```
 
-Standalone output is generated under:
+Production output:
 
 ```text
 .bcp-framework/build/
@@ -401,44 +724,73 @@ Standalone output is generated under:
    └─ server.mjs
 ```
 
-## Updating
+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.
+
+Read more: [Deployment](docs/deployment.md)
+
+## Updating BCP
 
 ```bash
 bcp update
 bcp update --check
 bcp update --dry-run
-bcp update 0.1.24
+bcp update 0.1.26
 bcp update next
 ```
 
-Projects published before the updater can bootstrap it once with:
+Projects created before the updater was introduced can bootstrap it once with:
 
 ```bash
 npx @chidchanun/bcp@latest update
 ```
 
-## Release validation
+Read more: [Updating](docs/updating.md)
+
+## Framework development and release validation
+
+Inside the BCP Framework repository:
 
 ```bash
+npm install
 npm run typecheck
 npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+```
+
+Full release-candidate validation:
+
+```bash
 npm run rc:check
 ```
 
-After RC passes, releases are tagged and published manually with the guarded release scripts.
+A version must not be tagged or published until RC and packed-package verification pass.
 
-## Documentation
+Read more: [Releasing](docs/releasing.md)
 
+## Documentation source
+
+The `docs/` directory is the source content for the future **`bcp-docs-web`** documentation website.
+
+Start with:
+
+- [Documentation Source Map](docs/README.md)
 - [Getting Started](docs/getting-started.md)
+- [Configuration](docs/configuration.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)
+- [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)
+- [S3-Compatible Storage](docs/s3-storage.md)
 - [Authentication](docs/authentication.md)
 - [Auth Route Guards](docs/auth-route-guards.md)
 - [JWT Sessions](docs/session-auth.md)
@@ -447,17 +799,50 @@ After RC passes, releases are tagged and published manually with the guarded rel
 - [Middleware](docs/middleware.md)
 - [Hydration](docs/hydration.md)
 - [Developer Tools](docs/developer-tools.md)
-- [Development Logging](docs/development-logging.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
+Recommended `bcp-docs-web` top-level navigation:
+
+```text
+Getting Started
+Routing & Data
+Authentication
+Database
+Runtime & Infrastructure
+Storage & Uploads
+API Reference
+Releases
+```
+
+## Release history
+
+Release notes live under `docs/releases/`.
+
+| 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 |
+| `0.1.26` | S3-Compatible Storage and Production Streaming |
+
+## Next direction
+
+After `0.1.26`, the recommended direction is:
+
+1. signed storage URLs where needed,
+2. object listing/copy/move capabilities,
+3. broader production hardening and graceful shutdown,
+4. stronger storage/provider diagnostics.
 
-- Node.js 24.11 or newer
-- React 19
+These are roadmap items, not `0.1.26` API guarantees.
 
 ## License