@chidchanun/bcp 0.1.25 → 0.1.27

package/README.md

@@ -1,52 +1,16 @@
 # BCP Framework
 
-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.
+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 and standalone production deployment.
 
-> **Development target:** `0.1.25`
+> **Development target:** `0.1.27`
 >
-> 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.
-
-## Overview
-
-BCP provides a single application model for React pages and server code:
-
-```text
-Browser
-  ↓
-BCP middleware / security
-  ↓
-Route guard
-  ↓
-Loader / action / API route
-  ↓
-React SSR
-  ↓
-Hydration / SPA navigation
-```
-
-The framework is designed so application code can stay close to the route that owns it:
-
-```text
-app/
-├─ layout.tsx
-├─ page.tsx
-├─ dashboard/
-│  ├─ guard.ts
-│  └─ users/
-│     └─ [id]/
-│        ├─ loader.ts
-│        ├─ actions.ts
-│        └─ page.tsx
-└─ api/
-   └─ upload/
-      └─ route.ts
-```
+> BCP is pre-1.0. The `0.1.27` source adds the Storage Ecosystem and remains an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
 ## Current capabilities
 
 | Area | Capability |
 | --- | --- |
-| Application | React SSR, hydration, layouts, metadata, SPA navigation |
+| Application | React SSR, hydration, layouts, metadata and 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>` |
@@ -57,8 +21,8 @@ app/
 | 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 |
+| Uploads | Buffered multipart helpers and production multipart streaming |
+| Storage | Local + S3-compatible adapters, streaming, listing, copy/move, metadata, bulk delete and signed S3 URLs |
 | Caching | Response cache and revalidation primitives |
 | Developer tools | `doctor`, `inspect`, updater and route inspection |
 | Production | Standalone server build with production middleware pipeline |
@@ -73,106 +37,69 @@ Database features currently target MySQL.
 
 ## Quick start
 
-Create a new application:
-
 ```bash
 npx create-bcp-app@latest my-app
 cd my-app
 npm run dev
 ```
 
-Default development URL:
-
-```text
-http://localhost:3000
-```
-
-A generated project normally exposes scripts such as:
+Generated projects normally use the application dependency key `bcp`:
 
 ```json
 {
+  "dependencies": {
+    "bcp": "npm:@chidchanun/bcp@latest"
+  },
   "scripts": {
     "dev": "bcp dev",
     "build": "bcp build",
     "start": "bcp start",
     "routes": "bcp routes",
-    "update": "bcp update"
+    "update": "bcp update",
+    "typecheck": "tsc --noEmit"
   }
 }
 ```
 
-## Packages
+Keep only one framework dependency named `bcp`. Installing both `bcp` and `@chidchanun/bcp` directly can load duplicate framework/React contexts.
 
-The public framework package is published as:
+## Application model
 
 ```text
-@chidchanun/bcp
-```
-
-Applications normally consume it through the dependency key:
-
-```text
-bcp
-```
-
-This keeps imports concise:
-
-```ts
-import {
-    Form,
-    Link,
-    useLoaderData,
-} from "bcp";
-```
-
-Server-only APIs use dedicated entrypoints such as:
-
-```ts
-import {
-    cookies,
-    logger,
-    requestId,
-} from "bcp/server";
+Browser
+  ↓
+BCP security / middleware / cache
+  ↓
+Route guard
+  ↓
+Loader / action / API route
+  ↓
+React SSR
+  ↓
+Hydration / SPA navigation
 ```
 
-## Project structure
-
-A typical application can grow into this layout:
+A route can keep page, loader, guard and actions together:
 
 ```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
-
-lib/
-public/
-migrations/
-bcp.config.ts
-package.json
-tsconfig.json
 ```
 
-BCP keeps page rendering, route authorization, server data and route mutations close together without requiring one large application router configuration file.
-
 ## Routing
 
-Page routes are discovered from `app/**/page.tsx`.
+Page routes are discovered from `app/**/page.tsx` and API routes from `app/**/route.ts`.
 
 ```text
 app/page.tsx                     /
@@ -181,73 +108,16 @@ 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
-```
-
-Static routes have priority over dynamic and catch-all routes.
 
-API routes use `route.ts`:
-
-```text
-app/api/users/route.ts       /api/users
-app/api/users/[id]/route.ts  /api/users/:id
+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 can inherit layouts from parent directories. The framework resolves the layout chain while rendering both development and standalone production requests.
-
-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
-export async function loader({
-    params,
-}) {
-    return {
-        id:
-            params.id,
-    };
-}
-```
-
-Consume the serializable result in a client page:
-
-```tsx
-"use client";
-
-import {
-    useLoaderData,
-} from "bcp";
-
-export default function UserPage() {
-    const data =
-        useLoaderData<{
-            id: string;
-        }>();
-
-    return (
-        <main>
-            User {data.id}
-        </main>
-    );
-}
-```
-
-Read more: [Server Data Loaders](docs/server-data-loaders.md)
-
-## Route guards
+## Server data, guards and actions
 
-A route tree can define `guard.ts` to authorize access before the protected route is rendered.
-
-Authentication-aware guards are available through `bcp/auth`:
+Server loaders live next to their route in `loader.ts`. Route authorization can be defined in `guard.ts`, while route-owned mutations live in `actions.ts`.
 
 ```ts
 import {
@@ -258,44 +128,14 @@ export const guard =
     requireRole("admin");
 ```
 
-The standalone production pipeline preserves the same active request context used by authentication and server request APIs.
-
 Read more:
 
+- [Server Data Loaders](docs/server-data-loaders.md)
 - [Route Guards](docs/route-guards.md)
 - [Auth Route Guards](docs/auth-route-guards.md)
+- [Form Actions](docs/form-actions.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.
-
-Read more: [Form Actions](docs/form-actions.md)
-
-## Server request APIs
-
-Request-scoped APIs are exposed through `bcp/server`:
-
-```ts
-import {
-    bearerToken,
-    clientIp,
-    cookies,
-    headers,
-    requestId,
-    requestMethod,
-    requestUrl,
-} from "bcp/server";
-```
-
-`requestId()` uses a valid incoming `X-Request-Id` when available 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 are available through:
+## Authentication and server APIs
 
 ```ts
 import {
@@ -303,117 +143,33 @@ import {
     requireAuth,
     requireRole,
 } from "bcp/auth";
-```
-
-Lower-level JWT cookie session primitives are available through `bcp/server`:
 
-```ts
 import {
-    createSession,
-    createSessionToken,
-    destroySession,
-    getSession,
-    verifySessionToken,
+    cookies,
+    headers,
+    requestId,
+    requestMethod,
+    requestUrl,
 } from "bcp/server";
 ```
 
-Authentication is intentionally separated from application-specific credential lookup so projects can connect their own user table or identity provider.
+BCP also exposes lower-level JWT cookie session primitives through `bcp/server`.
 
 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;
-}
-```
-
-This allows middleware to run logic both before and after downstream route execution.
-
-Existing middleware v1 behavior remains supported for compatibility.
-
-Read more: [Middleware](docs/middleware.md)
-
-## Validation
-
-BCP includes typed validation primitives:
-
-```ts
-import {
-    v,
-    validateFormData,
-} from "bcp/validation";
-```
-
-Validation can be shared by API routes and form actions without coupling application schemas to the rendering layer.
-
-Read more: [Validation](docs/validation.md)
-
-## 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"
-  }
-}
-```
-
-Read more: [Error Handling](docs/error-handling.md)
+- [JWT Sessions](docs/session-auth.md)
+- [Server Request APIs](docs/server-request-apis.md)
 
 ## Database
 
-Database helpers are exposed through:
-
 ```ts
 import {
     db,
 } from "bcp/database";
 ```
 
-The database layer provides:
-
-- lazy MySQL pool creation,
-- prepared execution,
-- query helpers,
-- transactions,
-- migration status and rollback support.
-
-Migration commands:
+The database layer provides lazy MySQL pool creation, prepared execution, query helpers, transactions and migrations.
 
 ```bash
 bcp db create create_users
@@ -427,396 +183,244 @@ Read more:
 - [Database](docs/database.md)
 - [Database Migrations](docs/database-migrations.md)
 
-## Logging and observability
+## Uploads and streaming
 
-Structured server logging is available through `bcp/server`:
+BCP supports the original buffered multipart helpers as well as production multipart-to-storage streaming:
 
 ```ts
 import {
-    logger,
-    requestLogger,
+    storeMultipartFile,
 } from "bcp/server";
 
-logger.info(
-    "Application event",
-    {
-        feature:
-            "catalog",
-    }
-);
-```
-
-Request-scoped logging can automatically include request identity:
-
-```ts
-export async function loader() {
-    const log =
-        await requestLogger({
-            feature:
-                "categories",
-        });
-
-    log.info(
-        "Loading categories"
+const stored =
+    await storeMultipartFile(
+        request,
+        {
+            storage,
+            fieldName: "file",
+            key: "documents/report.pdf",
+            maxBytes: 100 * 1024 * 1024,
+            constraints: {
+                maxBytes: 80 * 1024 * 1024,
+                allowedTypes: [
+                    "application/pdf",
+                ],
+            },
+        }
     );
-
-    return {
-        items: [],
-    };
-}
 ```
 
-Environment controls:
+`storeMultipartFile()` consumes `Request.body` incrementally and streams the selected file directly into storage. Request/body infrastructure limits still apply.
 
-```env
-BCP_LOG_LEVEL=debug
-BCP_LOG_FORMAT=json
-```
+Read more: [File Upload](docs/file-upload.md)
 
-Supported levels:
+## Storage
 
-```text
-debug
-info
-warn
-error
-silent
-```
+### Local filesystem
 
-Supported formats:
+```ts
+import {
+    createLocalStorage,
+} from "bcp/server";
 
-```text
-pretty
-json
+const storage =
+    createLocalStorage({
+        directory: "./uploads",
+    });
 ```
 
-Read more: [Logging and Observability](docs/development-logging.md)
-
-## File upload
-
-BCP `0.1.24` introduced multipart parsing and file validation:
+### S3 / R2 / MinIO
 
 ```ts
 import {
-    parseMultipartFormData,
-    requireUploadedFile,
-    saveUploadedFile,
+    createS3Storage,
 } from "bcp/server";
 
-export async function POST(
-    request: Request
-) {
-    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",
-                ],
-                allowedExtensions: [
-                    ".png",
-                    ".jpg",
-                    ".jpeg",
-                    ".webp",
-                ],
-            }
-        );
-
-    return Response.json(
-        await saveUploadedFile(
-            file,
-            {
-                directory:
-                    "./uploads",
-            }
-        )
-    );
-}
+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,
+    });
 ```
 
-Upload helpers provide:
+Custom endpoints and `forcePathStyle` support common S3-compatible deployments such as MinIO. Keep credentials server-only.
+
+Read more: [S3-Compatible Storage](docs/s3-storage.md)
 
-- 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.
+### Streaming storage
 
-The security gateway applies `server.bodyLimit` / `BCP_BODY_LIMIT` before application upload parsing. Applications accepting larger files must raise that outer limit explicitly.
+The stable minimum `StorageAdapter` retains its buffered API while adapters can expose optional `putStream()` and `readStream()` implementations.
 
 ```ts
 import {
-    defineConfig,
-} from "bcp/config";
-
-export default defineConfig({
-    server: {
-        bodyLimit:
-            10 * 1024 * 1024,
-    },
-});
+    getStorageCapabilities,
+    putStorageStream,
+    readStorageStream,
+} from "bcp/server";
 ```
 
-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.
+Both built-in local and S3 adapters support streaming reads/writes and byte ranges.
 
-Read more: [File Upload](docs/file-upload.md)
+Read more: [Storage and File Delivery](docs/storage.md)
 
-## Storage adapters
+### Storage Ecosystem — 0.1.27
 
-BCP `0.1.25` adds the first application-facing storage abstraction.
+BCP `0.1.27` adds a richer, additive object-storage API without invalidating older `StorageAdapter` implementations:
 
 ```ts
 import {
-    createLocalStorage,
-    storeUploadedFile,
+    copyStorageObject,
+    createStorageSignedReadUrl,
+    createStorageSignedWriteUrl,
+    deleteStorageObjects,
+    getStorageEcosystemCapabilities,
+    getStorageMetadata,
+    listStorageObjects,
+    moveStorageObject,
+    setStorageMetadata,
 } from "bcp/server";
+```
 
-const storage =
-    createLocalStorage({
-        directory:
-            "./uploads",
-    });
+Listing supports prefix filtering, limits and opaque cursors:
 
-const stored =
-    await storeUploadedFile(
-        file,
+```ts
+const page =
+    await listStorageObjects(
+        storage,
         {
-            storage,
-            key:
-                "avatars/user-101.webp",
+            prefix: "documents/",
+            limit: 50,
         }
     );
 ```
 
-The `StorageAdapter` contract contains:
-
-```text
-put
-stat
-read
-exists
-delete
-```
+Copy and move use native adapter operations when available, with portable fallback behavior where practical:
 
-Application code can depend on this contract instead of depending directly on filesystem paths.
+```ts
+await copyStorageObject(
+    storage,
+    "incoming/report.pdf",
+    "archive/report.pdf"
+);
 
-The built-in adapter in `0.1.25` is local filesystem storage. Cloud/object-storage adapters are planned for a later milestone.
+await moveStorageObject(
+    storage,
+    "tmp/avatar.webp",
+    "users/42/avatar.webp"
+);
+```
 
-Storage keys are logical relative paths. Absolute paths and traversal segments are rejected.
+Portable user metadata is string-to-string metadata and is distinct from application authorization/business state:
 
-Read more: [Storage and File Delivery](docs/storage.md)
-
-## Production file delivery
+```ts
+await setStorageMetadata(
+    storage,
+    "archive/report.pdf",
+    {
+        owner: "user-42",
+        status: "approved",
+    }
+);
+```
 
-Storage objects can be returned through a hardened HTTP response helper:
+S3-compatible storage also supports short-lived presigned direct-transfer URLs:
 
 ```ts
-import {
-    createStorageResponse,
-} from "bcp/server";
+const downloadUrl =
+    await createStorageSignedReadUrl(
+        storage,
+        "videos/demo.mp4",
+        {
+            expiresIn: 300,
+        }
+    );
 
-export async function GET(
-    request: Request
-) {
-    return createStorageResponse(
-        request,
+const uploadUrl =
+    await createStorageSignedWriteUrl(
         storage,
-        "documents/report.pdf",
+        "uploads/demo.mp4",
         {
-            disposition:
-                "attachment",
-            downloadName:
-                "report.pdf",
+            expiresIn: 300,
+            contentType: "video/mp4",
         }
     );
-}
 ```
 
-`createStorageResponse()` supports:
+Local storage intentionally does not emulate signed URLs. Signed URLs are temporary credentials and should only be generated after application authorization.
 
-- `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.
+Read more: [Storage Ecosystem](docs/storage-ecosystem.md)
 
-The default cache policy is intentionally conservative:
+## File delivery
 
-```text
-private, max-age=0, must-revalidate
-```
+`createStorageResponse()` serves local or cloud-backed objects through the same API with `GET`, `HEAD`, ETag/Last-Modified validators and single byte ranges.
 
-Public immutable caching must be opted into explicitly.
+```ts
+import {
+    createStorageResponse,
+} from "bcp/server";
 
-Multiple byte ranges are intentionally not supported in `0.1.25`.
+return createStorageResponse(
+    request,
+    storage,
+    "documents/report.pdf"
+);
+```
 
 Read more: [Storage and File Delivery](docs/storage.md)
 
-## 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.
+## Middleware, validation, errors and caching
 
-Storage keys, filenames and MIME metadata must not be treated as authorization decisions.
+BCP includes Middleware System v2, typed validation helpers, structured HTTP errors, structured logging and response caching/revalidation.
 
-Read more: [Security](docs/security.md)
+Read more:
 
-## Environment and configuration
+- [Middleware](docs/middleware.md)
+- [Validation](docs/validation.md)
+- [Error Handling](docs/error-handling.md)
+- [Logging and Observability](docs/development-logging.md)
+- [Caching](docs/caching.md)
+- [Security](docs/security.md)
 
-Application configuration lives in:
+## Production build
 
-```text
-bcp.config.ts
+```bash
+npm run build
+npm run start
 ```
 
-Public environment variables use the prefix:
+Standalone output is written under:
 
 ```text
-BCP_PUBLIC_
-```
-
-Server-only environment values remain server-side and are not emitted into browser bundles.
-
-Read more: [Configuration](docs/configuration.md)
-
-## Developer tools
-
-BCP includes project diagnostics:
-
-```bash
-bcp doctor
-bcp inspect
+.bcp-framework/build/
+├─ client/
+├─ public/
+└─ server/
+   └─ server.mjs
 ```
 
-`bcp doctor` checks areas such as:
-
-- project structure,
-- BCP installation,
-- React / ReactDOM compatibility,
-- duplicate framework copies,
-- environment/config loading,
-- route conflicts,
-- client/server boundaries.
-
-`bcp inspect` reports resolved configuration, environment sources, dependencies and discovered routes.
-
-Read more: [Developer Tools](docs/developer-tools.md)
+Read more: [Deployment](docs/deployment.md)
 
 ## Windows CLI
 
-Microsoft SQL Server also installs an executable named `bcp.exe` on Windows.
+Microsoft SQL Server can install another executable named `bcp.exe`. BCP publishes the collision-free alias `bcp-framework`.
 
-BCP therefore publishes the collision-free alias:
-
-```text
-bcp-framework
-```
+Inside project npm scripts, `bcp` is safe because npm prepends `node_modules/.bin` to `PATH`.
 
-Inside project npm scripts, `bcp` remains safe because npm puts `node_modules/.bin` at the front of `PATH`.
-
-For direct PowerShell usage, prefer:
+For direct PowerShell usage:
 
 ```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
 ```
 
-## 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
-```
-
-## Development behavior
-
-BCP includes Fast Refresh and deterministic development hydration behavior.
-
-Recent stabilization work also covers:
-
-- 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.
-
-A development topology change should no longer require manually deleting `.bcp-framework` to recover a missing client route bundle.
-
-Read more: [Hydration](docs/hydration.md)
-
-## Production build
-
-Build an application:
-
-```bash
-npm run build
-```
-
-Start the generated standalone runtime:
-
-```bash
-npm run start
-```
-
-Production output is written under:
-
-```text
-.bcp-framework/build/
-├─ client/
-├─ public/
-└─ server/
-   └─ server.mjs
-```
-
-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)
+Read more: [Developer Tools](docs/developer-tools.md)
 
 ## Updating BCP
 
@@ -824,100 +428,55 @@ Read more: [Deployment](docs/deployment.md)
 bcp update
 bcp update --check
 bcp update --dry-run
-bcp update 0.1.25
+bcp update 0.1.27
 bcp update next
 ```
 
-Projects created before the updater was introduced can bootstrap it once using the public package:
-
-```bash
-npx @chidchanun/bcp@latest update
-```
-
 Read more: [Updating](docs/updating.md)
 
-## Framework development
-
-When working inside the BCP Framework repository itself:
+## Framework development and release validation
 
 ```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
 ```
 
-A version must not be tagged or published until its release candidate and packed-package verification pass.
+A version must not be tagged or published until its RC and packed-package verification pass.
 
 Read more: [Releasing](docs/releasing.md)
 
 ## Documentation source
 
-The `docs/` directory is the source content intended to feed the future **`bcp-docs-web`** documentation website.
+The `docs/` directory is the authored source for **`bcp-docs-web`**.
 
-Start with:
+Recommended starting points:
 
 - [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 Data Loaders](docs/server-data-loaders.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)
+- [Storage Ecosystem](docs/storage-ecosystem.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)
 - [Database](docs/database.md)
-- [Database Migrations](docs/database-migrations.md)
 - [Middleware](docs/middleware.md)
-- [Hydration](docs/hydration.md)
 - [Developer Tools](docs/developer-tools.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)
 
-## 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 |
@@ -926,17 +485,22 @@ Recent milestones:
 | `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 |
+| `0.1.27` | Storage Ecosystem |
 
-## Roadmap
+## Next direction
 
-Current planned direction after `0.1.25`:
+After `0.1.27`, the planned milestone is **`0.1.28 — Production Hardening`**:
 
-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.
+1. graceful HTTP shutdown and active-request draining,
+2. database/S3 resource cleanup,
+3. trusted proxy and forwarded-header handling,
+4. request/server timeout controls,
+5. security hardening,
+6. Docker and standalone-runtime regression coverage,
+7. stronger startup/runtime diagnostics.
 
-Roadmap items are plans, not published API guarantees.
+These are roadmap items, not `0.1.27` guarantees.
 
 ## License