@chidchanun/bcp 0.1.26 → 0.1.28

package/README.md

@@ -1,52 +1,16 @@
 # BCP Framework
 
-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.
+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.
 
-> **Release candidate target:** `0.1.26`
+> **Development target:** `0.1.28`
 >
-> 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
-```
+> BCP is pre-1.0. The `0.1.28` source adds Production Hardening 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>` |
@@ -58,10 +22,10 @@ app/
 | 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 |
+| 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 |
+| Production | Standalone build, hardening gateway, graceful shutdown, trusted-proxy controls and HTTP timeouts |
 
 ## Requirements
 
@@ -79,16 +43,13 @@ cd my-app
 npm run dev
 ```
 
-Default development URL:
-
-```text
-http://localhost:3000
-```
-
-Generated projects normally include:
+Generated projects normally use the application dependency key `bcp`:
 
 ```json
 {
+  "dependencies": {
+    "bcp": "npm:@chidchanun/bcp@latest"
+  },
   "scripts": {
     "dev": "bcp dev",
     "build": "bcp build",
@@ -100,68 +61,45 @@ Generated projects normally include:
 }
 ```
 
-## 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 `bcp`, keeping imports concise:
-
-```ts
-import {
-    Form,
-    Link,
-    useLoaderData,
-} from "bcp";
-```
-
-Server-only APIs use dedicated entrypoints:
-
-```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 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
 ```
 
 ## 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                     /
@@ -170,65 +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 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
-export async function loader({
-    params,
-}) {
-    return {
-        id:
-            params.id,
-    };
-}
-```
-
-Consume serializable loader data from 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)
+## Server data, guards and actions
 
-## Route guards
-
-A route tree can define `guard.ts` to authorize access before rendering:
+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 {
@@ -239,40 +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. 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
-
-```ts
-import {
-    bearerToken,
-    clientIp,
-    cookies,
-    headers,
-    requestId,
-    requestMethod,
-    requestUrl,
-} from "bcp/server";
-```
-
-`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:
+## Authentication and server APIs
 
 ```ts
 import {
@@ -280,89 +143,23 @@ import {
     requireAuth,
     requireRole,
 } from "bcp/auth";
-```
 
-Lower-level JWT cookie session primitives:
-
-```ts
 import {
-    createSession,
-    createSessionToken,
-    destroySession,
-    getSession,
-    verifySessionToken,
+    cookies,
+    headers,
+    requestId,
+    requestMethod,
+    requestUrl,
 } from "bcp/server";
 ```
 
-Authentication is 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;
-}
-```
-
-Existing middleware v1 behavior remains supported for compatibility.
-
-Read more: [Middleware](docs/middleware.md)
-
-## 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)
+- [JWT Sessions](docs/session-auth.md)
+- [Server Request APIs](docs/server-request-apis.md)
 
 ## Database
 
@@ -372,7 +169,7 @@ import {
 } from "bcp/database";
 ```
 
-The database layer provides a lazy MySQL pool, prepared execution, query helpers, transactions and migrations.
+The database layer provides lazy MySQL pool creation, prepared execution, query helpers, transactions and migrations.
 
 ```bash
 bcp db create create_users
@@ -386,71 +183,9 @@ Read more:
 - [Database](docs/database.md)
 - [Database Migrations](docs/database-migrations.md)
 
-## Logging and observability
-
-```ts
-import {
-    logger,
-    requestLogger,
-} from "bcp/server";
-
-logger.info(
-    "Application event",
-    {
-        feature:
-            "catalog",
-    }
-);
-```
-
-Environment controls:
-
-```env
-BCP_LOG_LEVEL=debug
-BCP_LOG_FORMAT=json
-```
-
-Supported levels are `debug`, `info`, `warn`, `error` and `silent`. Formats are `pretty` and `json`.
-
-Read more: [Logging and Observability](docs/development-logging.md)
-
-## File uploads
-
-BCP keeps the buffered multipart API for small forms:
-
-```ts
-import {
-    parseMultipartFormData,
-    requireUploadedFile,
-    saveUploadedFile,
-} from "bcp/server";
-
-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",
-            ],
-        }
-    );
-```
+## Uploads and streaming
 
-BCP `0.1.26` adds direct multipart-to-storage streaming for larger production uploads:
+BCP supports the original buffered multipart helpers as well as production multipart-to-storage streaming:
 
 ```ts
 import {
@@ -462,35 +197,24 @@ const stored =
         request,
         {
             storage,
-            fieldName:
-                "file",
-            key:
-                "documents/report.pdf",
-            maxBytes:
-                100 * 1024 * 1024,
+            fieldName: "file",
+            key: "documents/report.pdf",
+            maxBytes: 100 * 1024 * 1024,
             constraints: {
-                maxBytes:
-                    80 * 1024 * 1024,
+                maxBytes: 80 * 1024 * 1024,
                 allowedTypes: [
                     "application/pdf",
                 ],
-                allowedExtensions: [
-                    ".pdf",
-                ],
             },
         }
     );
 ```
 
-`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.
-
-MIME type and extension validation are metadata checks, not content-signature verification.
+`storeMultipartFile()` consumes `Request.body` incrementally and streams the selected file directly into storage. Request/body infrastructure limits still apply.
 
 Read more: [File Upload](docs/file-upload.md)
 
-## Storage adapters
+## Storage
 
 ### Local filesystem
 
@@ -501,14 +225,13 @@ import {
 
 const storage =
     createLocalStorage({
-        directory:
-            "./uploads",
+        directory: "./uploads",
     });
 ```
 
-### S3-compatible storage
+`create-bcp-app --storage local` creates `lib/storage.ts` plus a visible `storage/README.md` / `.gitkeep` scaffold. Runtime objects remain ignored by Git.
 
-BCP `0.1.26` adds an S3-compatible backend:
+### S3 / R2 / MinIO
 
 ```ts
 import {
@@ -517,40 +240,21 @@ import {
 
 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,
+        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,
     });
 ```
 
-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.
-
-Keep cloud credentials server-only. Never expose them through `BCP_PUBLIC_*` variables.
+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)
 
 ### 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:
+The stable minimum `StorageAdapter` retains its buffered API while adapters can expose optional `putStream()` and `readStream()` implementations.
 
 ```ts
 import {
@@ -560,109 +264,122 @@ import {
 } from "bcp/server";
 ```
 
-Both built-in `0.1.26` adapters support native streaming reads, streaming writes and byte ranges.
-
-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.
+Both built-in local and S3 adapters support streaming reads/writes and byte ranges.
 
 Read more: [Storage and File Delivery](docs/storage.md)
 
-## Production file delivery
+### Storage Ecosystem — 0.1.27
+
+BCP `0.1.27` adds a richer, additive object-storage API without invalidating older `StorageAdapter` implementations:
 
 ```ts
 import {
-    createStorageResponse,
+    copyStorageObject,
+    createStorageSignedReadUrl,
+    createStorageSignedWriteUrl,
+    deleteStorageObjects,
+    getStorageEcosystemCapabilities,
+    getStorageMetadata,
+    listStorageObjects,
+    moveStorageObject,
+    setStorageMetadata,
 } from "bcp/server";
-
-export function GET(
-    request: Request
-) {
-    return createStorageResponse(
-        request,
-        storage,
-        "documents/report.pdf",
-        {
-            disposition:
-                "attachment",
-            downloadName:
-                "report.pdf",
-        }
-    );
-}
 ```
 
-`createStorageResponse()` uses storage streaming and supports:
+Listing supports prefix filtering, limits and opaque cursors. Copy and move use native adapter operations when available, with portable fallback behavior where practical. Portable user metadata is string-to-string metadata and is distinct from authorization/business state.
 
-- `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.
+S3-compatible storage also supports short-lived presigned direct-transfer URLs. Local storage intentionally does not emulate signed URLs.
 
-The default cache policy remains:
+Read more: [Storage Ecosystem](docs/storage-ecosystem.md)
 
-```text
-private, max-age=0, must-revalidate
-```
+## File delivery
 
-Multiple byte ranges remain intentionally unsupported in `0.1.26`.
+`createStorageResponse()` serves local or cloud-backed objects through the same API with `GET`, `HEAD`, ETag/Last-Modified validators and single byte ranges.
 
-Read more: [Storage and File Delivery](docs/storage.md)
+```ts
+import {
+    createStorageResponse,
+} from "bcp/server";
 
-## Caching
+return createStorageResponse(
+    request,
+    storage,
+    "documents/report.pdf"
+);
+```
 
-BCP includes response caching and revalidation primitives used by development and standalone production runtimes.
+Read more: [Storage and File Delivery](docs/storage.md)
 
-Read more: [Caching](docs/caching.md)
+## Middleware, validation, errors and caching
 
-## Security
+BCP includes Middleware System v2, typed validation helpers, structured HTTP errors, structured logging and response caching/revalidation.
 
-The framework security layer includes request body limits and production request handling defaults. Application authorization remains the responsibility of route guards and application logic.
+Read more:
 
-Storage keys, filenames and MIME metadata must not be treated as authorization decisions.
+- [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)
 
-Read more: [Security](docs/security.md)
+## Production build
 
-## Environment and configuration
+```bash
+npm run build
+npm run start
+```
 
-Application configuration lives in:
+Standalone output is written under:
 
 ```text
-bcp.config.ts
+.bcp-framework/build/
+├─ client/
+├─ public/
+└─ server/
+   └─ server.mjs
 ```
 
-Public environment variables use:
+### Production Hardening — 0.1.28
 
-```text
-BCP_PUBLIC_
-```
+The standalone runtime is wrapped by a public hardening gateway with configurable HTTP and shutdown behavior:
 
-Server-only values remain server-side and are not emitted into browser bundles.
+```dotenv
+BCP_REQUEST_TIMEOUT_MS=120000
+BCP_HEADERS_TIMEOUT_MS=66000
+BCP_KEEP_ALIVE_TIMEOUT_MS=65000
+BCP_SHUTDOWN_TIMEOUT_MS=10000
+BCP_TRUST_PROXY=false
+```
 
-Read more: [Configuration](docs/configuration.md)
+Standalone production handles `SIGTERM` and `SIGINT`, drains the public listener, runs application cleanup hooks and then stops internal runtime layers.
 
-## Developer tools
+```ts
+import {
+    registerShutdownHook,
+} from "bcp/server";
 
-```bash
-bcp doctor
-bcp inspect
+registerShutdownHook(
+    () => {
+        storage.destroy();
+    },
+    {
+        name: "storage",
+    }
+);
 ```
 
-`bcp doctor` checks project structure, BCP/React installation parity, duplicate framework copies, environment/config loading, route conflicts and client/server boundaries.
+Trusted proxy mode is disabled by default. Enable `BCP_TRUST_PROXY=true` only when direct untrusted traffic cannot bypass the trusted reverse proxy/load balancer.
 
-`bcp inspect` reports resolved configuration, environment sources, dependency versions and discovered routes.
-
-Read more: [Developer Tools](docs/developer-tools.md)
+Read more: [Production Hardening](docs/production-hardening.md)
 
 ## Windows CLI
 
-Microsoft SQL Server can install another executable named `bcp.exe`. BCP therefore publishes the collision-free alias `bcp-framework`.
+Microsoft SQL Server can install another executable named `bcp.exe`. BCP publishes the collision-free alias `bcp-framework`.
 
-Inside npm scripts, `bcp` is safe because npm prepends the project's `node_modules/.bin` to `PATH`.
+Inside project npm scripts, `bcp` is safe because npm prepends `node_modules/.bin` to `PATH`.
 
-For direct PowerShell usage, use the project-local CLI:
+For direct PowerShell usage:
 
 ```powershell
 npm exec -- bcp-framework --version
@@ -673,62 +390,7 @@ 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
-```
-
-## Development behavior
-
-BCP includes Fast Refresh and deterministic development hydration behavior. Recent stabilization work 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.
-
-Read more: [Hydration](docs/hydration.md)
-
-## Production build
-
-```bash
-npm run build
-npm run start
-```
-
-Production output:
-
-```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.
-
-Read more: [Deployment](docs/deployment.md)
+Read more: [Developer Tools](docs/developer-tools.md)
 
 ## Updating BCP
 
@@ -736,22 +398,14 @@ Read more: [Deployment](docs/deployment.md)
 bcp update
 bcp update --check
 bcp update --dry-run
-bcp update 0.1.26
+bcp update 0.1.28
 bcp update next
 ```
 
-Projects created before the updater was introduced can bootstrap it once with:
-
-```bash
-npx @chidchanun/bcp@latest update
-```
-
 Read more: [Updating](docs/updating.md)
 
 ## Framework development and release validation
 
-Inside the BCP Framework repository:
-
 ```bash
 npm install
 npm run typecheck
@@ -759,70 +413,41 @@ 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 RC 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 for 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)
+- [Production Hardening](docs/production-hardening.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)
 
-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 |
@@ -832,17 +457,20 @@ Release notes live under `docs/releases/`.
 | `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 |
+| `0.1.28` | Production Hardening |
 
 ## Next direction
 
-After `0.1.26`, the recommended direction is:
+After `0.1.28`, the planned milestone is **`0.1.29 — Developer Experience`**:
 
-1. signed storage URLs where needed,
-2. object listing/copy/move capabilities,
-3. broader production hardening and graceful shutdown,
-4. stronger storage/provider diagnostics.
+1. route/API/middleware/migration generators,
+2. richer `doctor` and `inspect` diagnostics,
+3. clearer build/runtime error messages,
+4. improved create-app presets and automation flags,
+5. production configuration diagnostics.
 
-These are roadmap items, not `0.1.26` API guarantees.
+These are roadmap items, not `0.1.28` guarantees.
 
 ## License