@chidchanun/bcp 0.1.27 → 0.1.29

package/docs/README.md

@@ -1,10 +1,10 @@
 # BCP Framework Documentation Source
 
-The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized for the future **`bcp-docs-web`** website.
+The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.1.27`
+> **Documentation target:** BCP Framework `0.1.29`
 >
-> **Release state:** unreleased development target. Do not label `0.1.27` as published until RC validation and npm publication complete.
+> **Release state:** unreleased development target. Do not label `0.1.29` as published until RC validation, tagging and npm publication complete.
 
 ## Documentation flow
 
@@ -13,10 +13,45 @@ BCP Framework source/tests
         ↓
       docs/
         ↓
+Markdown content + docs-web manifest
+        ↓
    bcp-docs-web
 ```
 
-Framework source and tests are authoritative for behavior. Markdown under `docs/` is the authored documentation layer. `bcp-docs-web` should render, organize and search these sources instead of becoming a competing source of truth.
+Framework source and tests are authoritative for behavior. Markdown under `docs/` is the authored documentation layer. `bcp-docs-web` should render, organize and search these sources rather than becoming a competing source of truth.
+
+## Docs-web navigation contract — 0.1.29
+
+`docs/docs-web-manifest.json` is the explicit navigation and route contract for the docs website.
+
+It defines:
+
+```text
+schema version
+framework/version target
+release state
+section IDs/titles
+website routes
+Markdown source files
+page titles
+release routes
+```
+
+Recommended docs-web workflow:
+
+```text
+read docs/docs-web-manifest.json
+          ↓
+generate sidebar + route map
+          ↓
+load referenced Markdown file
+          ↓
+render content/search/prev-next
+```
+
+Do not duplicate this mapping in a second hard-coded sidebar unless the website needs a temporary bootstrap fallback.
+
+Markdown remains the content source; the manifest contains navigation metadata only.
 
 ## Update rule
 
@@ -24,12 +59,15 @@ When framework behavior changes:
 
 1. Update framework source.
 2. Add/update regression tests.
-3. Update the matching file under `docs/`.
-4. Update `docs/releases/<version>.md`.
-5. Change release state to published only after npm publication succeeds.
+3. Update the matching Markdown file under `docs/`.
+4. Update `docs/docs-web-manifest.json` when routes/navigation change.
+5. Update `docs/releases/<version>.md`.
+6. Change release state to published only after npm publication succeeds.
 
 ## Recommended `bcp-docs-web` navigation
 
+The current manifest groups documentation into:
+
 ```text
 Getting Started
 Routing & Data
@@ -37,7 +75,7 @@ Authentication
 Database
 Runtime & Infrastructure
 Storage & Uploads
-API Reference
+Developer Experience
 Releases
 ```
 
@@ -48,6 +86,7 @@ Releases
 | `/docs/getting-started` | `getting-started.md` | Create and run a BCP application |
 | `/docs/configuration` | `configuration.md` | Framework configuration/environment |
 | `/docs/application-modules` | `application-modules.md` | Client/server boundaries |
+| `/docs/project-metadata` | `project-metadata.md` | `bcp.project.json` schema and security boundary |
 | `/docs/deployment` | `deployment.md` | Standalone production deployment |
 | `/docs/updating` | `updating.md` | Framework upgrades |
 
@@ -84,10 +123,10 @@ Releases
 | --- | --- | --- |
 | `/docs/middleware` | `middleware.md` | Middleware System v2 |
 | `/docs/hydration` | `hydration.md` | SSR/client hydration parity |
-| `/docs/developer-tools` | `developer-tools.md` | `doctor` / `inspect` |
 | `/docs/development-logging` | `development-logging.md` | Logging/observability |
 | `/docs/caching` | `caching.md` | Cache/revalidation |
 | `/docs/security` | `security.md` | Security/body limits |
+| `/docs/production-hardening` | `production-hardening.md` | Graceful shutdown, trusted proxy and timeouts |
 
 ### Storage & Uploads
 
@@ -98,6 +137,13 @@ Releases
 | `/docs/storage-ecosystem` | `storage-ecosystem.md` | Listing, copy/move, metadata, bulk delete, signed URLs |
 | `/docs/s3-storage` | `s3-storage.md` | S3/R2/MinIO adapter and direct object access |
 
+### Developer Experience
+
+| Website route | Markdown source | Purpose |
+| --- | --- | --- |
+| `/docs/generators` | `generators.md` | Page/API/middleware/migration generators |
+| `/docs/developer-tools` | `developer-tools.md` | Doctor/Inspect v2 and diagnostics |
+
 ## API Reference ownership
 
 Recommended entrypoint groups:
@@ -117,7 +163,7 @@ bcp/middleware
 | Entrypoint | Primary guide |
 | --- | --- |
 | `bcp` | `routing.md`, `server-data-loaders.md`, `form-actions.md` |
-| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `storage-ecosystem.md`, `s3-storage.md`, `development-logging.md` |
+| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `storage-ecosystem.md`, `s3-storage.md`, `development-logging.md`, `production-hardening.md` |
 | `bcp/auth` | `authentication.md`, `auth-route-guards.md` |
 | `bcp/database` | `database.md`, `database-migrations.md` |
 | `bcp/validation` | `validation.md` |
@@ -139,7 +185,7 @@ bcp/middleware
 - client islands / partial hydration
 - Fast Refresh
 
-### Server
+### Server and production runtime
 
 - request-scoped APIs/cookies/redirects/request IDs
 - JWT sessions/authentication
@@ -147,22 +193,28 @@ bcp/middleware
 - validation/structured errors
 - structured logging
 - response caching/security gateway
+- production hardening gateway
+- configurable request/header/keep-alive/shutdown timeouts
+- `SIGTERM` / `SIGINT` graceful shutdown
+- application shutdown hooks
+- trusted-proxy forwarding-header controls
 
 ### Storage & Uploads
 
-- buffered multipart `FormData` upload APIs
+- buffered multipart upload APIs
 - production streaming multipart upload (`storeMultipartFile()`)
 - backward-compatible `StorageAdapter` contract
 - local filesystem storage
-- S3/R2/MinIO-compatible storage
+- Amazon S3 / Cloudflare R2 / MinIO-compatible storage
 - streaming reads/writes and byte ranges
 - ETag/Last-Modified file delivery
 - upload/storage limits and abort cleanup
 - object listing with cursors
-- native/fallback copy and move
+- copy and move
 - portable user metadata
 - bulk deletion
 - S3 presigned read/write URLs
+- create-app Local Server / Amazon S3 / Cloudflare R2 presets
 
 ### Database
 
@@ -172,76 +224,61 @@ bcp/middleware
 - transactions
 - migrations/status/rollback
 
-### Developer Experience
+### Developer Experience — 0.1.29
 
 - `create-bcp-app`
+- non-secret `bcp.project.json`
+- `bcp generate page`
+- `bcp generate api`
+- `bcp generate middleware`
+- `bcp generate migration`
 - `bcp update`
-- `bcp doctor`
-- `bcp inspect`
+- Doctor/Inspect v2
+- lockfile/package-manager diagnostics
+- duplicate framework declaration checks
+- storage/provider diagnostics
+- production-build/Docker/hardening diagnostics
 - Windows-safe `bcp-framework` alias
-- standalone production build
-- unit/integration/E2E/package/RC checks
-
-## BCP 0.1.27 documentation focus
+- `docs/docs-web-manifest.json`
 
-### Storage ecosystem
+## BCP 0.1.29 documentation focus
 
-New generic helpers include:
+### Project generators
 
-```ts
-import {
-    copyStorageObject,
-    createStorageSignedReadUrl,
-    createStorageSignedWriteUrl,
-    deleteStorageObjects,
-    getStorageEcosystemCapabilities,
-    getStorageMetadata,
-    listStorageObjects,
-    moveStorageObject,
-    setStorageMetadata,
-} from "bcp/server";
+```bash
+bcp generate page dashboard/users
+bcp generate api users
+bcp generate middleware
+bcp generate migration create_users
 ```
 
-Document these boundaries clearly:
+Page/API/middleware generation requires `--force` before replacing existing target files.
+
+See `generators.md`.
+
+### Doctor / Inspect v2
 
-- ecosystem methods are additive and do not invalidate older `StorageAdapter` implementations,
-- listing cursors are opaque,
-- overwrite remains opt-in,
-- move is copy + delete rather than an atomic distributed transaction,
-- application metadata is portable string metadata and not authorization/business state,
-- `bcp_sha256` is reserved for framework checksum metadata,
-- local storage does not emulate signed URLs,
-- S3 direct-transfer URLs are temporary credentials and require application authorization before issuance.
+Doctor adds deployment/project-health checks without removing previous checks. Inspect keeps its previous JSON fields and adds a `project` object containing lockfile, package manager, project metadata/presets, build presence, Dockerfile, framework declarations, storage provider and hardening status.
 
-See `storage-ecosystem.md`.
+See `developer-tools.md`.
 
-### S3 ecosystem
+### Project metadata
 
-`createS3Storage()` keeps the same public constructor and now adds:
+New `create-bcp-app` projects receive:
 
 ```text
-ListObjectsV2
-CopyObject
-DeleteObjects
-presigned GetObject
-presigned PutObject
-application metadata
+bcp.project.json
 ```
 
-See `s3-storage.md`.
+The file records scaffold choices only and must never contain credentials/secrets.
 
-### 0.1.26 foundations remain supported
+See `project-metadata.md`.
 
-The following remain part of the storage stack:
+### Docs-web contract
 
-```text
-putStorageStream()
-readStorageStream()
-storeMultipartFile()
-createStorageResponse()
-```
+`docs/docs-web-manifest.json` is intended to be consumed directly by `bcp-docs-web` for navigation and route generation.
 
-`0.1.27` builds on these rather than replacing them.
+The website should still read the Markdown source referenced by each manifest page entry.
 
 ## CLI commands
 
@@ -250,6 +287,10 @@ bcp dev
 bcp routes
 bcp build
 bcp start
+bcp generate page dashboard/users
+bcp generate api users
+bcp generate middleware
+bcp generate migration create_users
 bcp doctor
 bcp doctor --json
 bcp inspect
@@ -268,6 +309,7 @@ On Windows, direct project-local commands should prefer:
 ```powershell
 npm exec -- bcp-framework doctor
 npm exec -- bcp-framework inspect
+npm exec -- bcp-framework generate page dashboard/users
 npm exec -- bcp-framework dev
 npm exec -- bcp-framework build
 ```
@@ -282,15 +324,15 @@ Release notes live under:
 docs/releases/
 ```
 
-Recommended routes:
+The docs-web manifest currently maps:
 
 ```text
+/releases/0.1.29
+/releases/0.1.28
 /releases/0.1.27
 /releases/0.1.26
 /releases/0.1.25
 /releases/0.1.24
-/releases/0.1.23
-/releases/0.1.22
 ```
 
 Use one of these release states:
@@ -303,27 +345,49 @@ unreleased development target
 
 The existence of a release note alone does not mean the npm version is published.
 
-## Suggested website model
+## Suggested docs-web implementation
+
+A simple implementation can model the manifest like:
 
 ```ts
-interface DocPage {
-    title: string;
-    slug: string;
-    section: string;
-    sourceFile: string;
-    versionTarget?: string;
-    releaseState?:
-        | "published"
-        | "rc"
-        | "unreleased";
+interface DocsWebManifest {
+    schemaVersion: number;
+    framework: string;
+    versionTarget: string;
+    releaseState: string;
+    sections: Array<{
+        id: string;
+        title: string;
+        pages: Array<{
+            route: string;
+            source: string;
+            title: string;
+        }>;
+    }>;
+    releases: Array<{
+        route: string;
+        source: string;
+        version: string;
+        state?: string;
+    }>;
 }
 ```
 
-The first `bcp-docs-web` implementation can keep this mapping in a route manifest and consume Markdown directly.
+Recommended website behavior:
+
+1. Load/validate `docs-web-manifest.json` at build/startup.
+2. Build the sidebar in manifest order.
+3. Resolve each route to its referenced Markdown source.
+4. Generate previous/next links from manifest order.
+5. Index rendered Markdown headings/content for search.
+6. Use `versionTarget` / `releaseState` for the site banner.
+7. Use release entries for the release navigation.
+
+Do not expose `bcp.project.json` secrets because the project metadata format is intentionally non-secret; runtime `.env` files should never be ingested into public docs output.
 
 ## Suggested website features
 
-1. Sidebar navigation from this source map.
+1. Sidebar from `docs-web-manifest.json`.
 2. Markdown rendering + syntax highlighting.
 3. Previous/next navigation.
 4. Version/release-state banner.
@@ -365,43 +429,36 @@ npm run test:package
 npm run rc:check
 ```
 
-For `0.1.27`, package validation must also confirm the staged artifact includes:
-
-```text
-@aws-sdk/client-s3
-@aws-sdk/lib-storage
-@aws-sdk/s3-request-presigner
-busboy
-```
+For `0.1.29`, validation should cover project generators, Doctor/Inspect v2, create-app project metadata, the existing production hardening runtime and package preparation.
 
-and the ecosystem runtime/public exports.
+The release lockfile must be synchronized to `0.1.29` before the final tag.
 
 ## Documentation QA checklist
 
-- linked Markdown files exist,
-- examples use public exports,
+- every manifest Markdown source exists,
+- every manifest route is unique,
+- examples use public exports/CLI commands,
 - version/release states are current,
 - Windows direct CLI examples use `npm exec -- bcp-framework`,
 - upload/storage/auth security caveats are present,
-- route names match the current router,
 - release notes match the framework version,
 - S3 credentials are never shown as public browser variables,
-- signed URLs are documented as temporary credentials,
-- roadmap APIs are not presented as published guarantees.
+- project metadata remains non-secret,
+- proxy trust remains documented as opt-in,
+- roadmap APIs are not presented as release guarantees.
 
-## Next direction after 0.1.27
+## Next direction after 0.1.29
 
-Planned `0.1.28 — Production Hardening` focus:
+Planned **`0.2.0 — Framework Platform`** focus:
 
-- graceful HTTP shutdown and active-request draining,
-- database/S3 resource cleanup,
-- trusted proxy and forwarded-header handling,
-- timeout controls,
-- security hardening,
-- Docker/standalone runtime regression coverage,
-- startup/runtime dependency diagnostics.
+- consolidate public API naming/behavior,
+- document compatibility expectations,
+- stabilize supported production deployment paths,
+- complete docs-web integration and documentation coverage,
+- publish migration guidance for pre-`0.2.0` applications,
+- establish a platform baseline before broader feature expansion.
 
-These remain roadmap items until their source/tests land.
+These remain roadmap goals until their source/tests land.
 
 ## Repository authority
 
@@ -411,7 +468,8 @@ The framework repository remains authoritative for:
 source
 public exports
 tests
-docs
+Markdown docs
+docs-web manifest
 release notes
 ```