@chidchanun/bcp 0.2.0 → 0.2.1

package/README.md

@@ -2,37 +2,35 @@
 
 BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, database access, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.2.0 — Framework Platform`
+> **Development target:** `0.2.1 — Documentation Platform`
 >
-> `0.2.0` establishes the first explicit platform baseline for BCP. It remains an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.1` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
-## Platform baseline — 0.2.0
+## 0.2 platform
 
-BCP `0.2.0` consolidates the capabilities built across the `0.1.x` series into a documented and testable platform contract.
+`0.2.0` established the Framework Platform baseline. `0.2.1` builds a machine-readable Documentation Platform on top of that baseline without intentionally removing application runtime public entrypoints.
 
-New platform sources:
+The authoritative platform/documentation contracts are:
 
 ```text
 docs/platform-manifest.json
-  -> version, runtime target, public entrypoints and capability metadata
+  -> runtime target, public entrypoints, capabilities and compatibility
 
 docs/docs-web-manifest.json
-  -> docs-web sections, routes, Markdown sources and releases
+  -> docs sections, routes, Markdown sources and releases
 
-docs/platform-contract.md
-  -> public platform/compatibility contract
-
-docs/migration-0.2.md
-  -> application upgrade guide
+docs/api-manifest.json
+  -> public package entrypoints, source ownership and guide routes
 ```
 
-The package release pipeline now verifies the platform contract against the prepared npm artifact so accidental public-export/version drift fails package validation.
+Authored documentation remains under `docs/*.md`.
 
 Read more:
 
 - [Framework Platform Contract](docs/platform-contract.md)
-- [Migrating to 0.2.0](docs/migration-0.2.md)
-- [Platform Manifest](docs/platform-manifest.json)
+- [Documentation Platform](docs/documentation-platform.md)
+- [API Reference](docs/api-reference.md)
+- [Migrating to 0.2.x](docs/migration-0.2.md)
 
 ## Current capabilities
 
@@ -45,7 +43,7 @@ Read more:
 | 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 |
+| Validation | Typed validators and structured validation errors |
 | Error handling | HTTP error helpers and consistent error responses |
 | Database | MySQL helpers, transactions and migrations |
 | Logging | Structured logger, request logger and request IDs |
@@ -54,7 +52,7 @@ Read more:
 | Caching | Response cache and revalidation primitives |
 | Developer tools | Generators, Doctor/Inspect v2, updater, route inspection and project metadata |
 | Production | Standalone Node.js build, hardening gateway, graceful shutdown, trusted proxy controls and HTTP timeouts |
-| Documentation | Markdown source + machine-readable docs-web/platform manifests |
+| Documentation | Manifest-driven docs navigation, platform metadata and public API entrypoint reference |
 
 ## Requirements
 
@@ -120,7 +118,7 @@ app/
 
 ## Public entrypoints
 
-The `0.2.0` platform contract recognizes these application entrypoints:
+The `0.2.x` platform contract recognizes:
 
 ```text
 bcp
@@ -136,9 +134,14 @@ bcp/server-only
 bcp/middleware
 ```
 
-Application code should use public entrypoints rather than importing internal framework files under `packages/`.
+Application code should use these public package entrypoints rather than importing internal framework files under `packages/`.
 
-The authoritative machine-readable list is in [docs/platform-manifest.json](docs/platform-manifest.json).
+The public list is validated in both:
+
+- [Platform Manifest](docs/platform-manifest.json)
+- [API Manifest](docs/api-manifest.json)
+
+See [API Reference](docs/api-reference.md) for ownership and related guides.
 
 ## CLI
 
@@ -175,7 +178,7 @@ bcp generate migration create_users
 
 Page/API/middleware generators require `--force` before replacing an existing scaffold target.
 
-On Windows, Microsoft SQL Server may provide another `bcp.exe`. For direct PowerShell usage prefer the collision-free project-local alias:
+On Windows, Microsoft SQL Server may provide another `bcp.exe`. For direct PowerShell usage prefer the project-local collision-free alias:
 
 ```powershell
 npm exec -- bcp-framework doctor
@@ -184,8 +187,6 @@ npm exec -- bcp-framework routes
 npm exec -- bcp-framework generate page dashboard/users
 ```
 
-Inside npm scripts, `bcp` remains safe because npm prepends the project `node_modules/.bin` directory to `PATH`.
-
 ## Routing, loaders, guards and actions
 
 BCP discovers pages from `app/**/page.tsx` and API handlers from `app/**/route.ts`.
@@ -265,17 +266,7 @@ Amazon S3
 Cloudflare R2
 ```
 
-BCP's storage API supports local and S3-compatible storage, streaming reads/writes, ranges, object listing, copy/move, portable metadata, bulk deletion and S3 signed URLs.
-
-Local Server projects keep a visible scaffold:
-
-```text
-storage/
-├─ .gitkeep
-└─ README.md
-```
-
-Runtime objects remain ignored by Git.
+BCP storage supports local and S3-compatible adapters, streaming reads/writes, ranges, object listing, copy/move, portable metadata, bulk deletion and S3 signed URLs.
 
 Guides:
 
@@ -308,93 +299,75 @@ Run:
 npm run start
 ```
 
-The `0.2.0` platform build target is explicitly:
+The `0.2.x` production target remains:
 
 ```text
 standalone-node
 ```
 
-Native `.exe`, desktop and mobile compilation are not part of the `0.2.0` platform contract.
-
-Production hardening supports:
+Native `.exe`, desktop and mobile compilation are future roadmap work and are not part of the current platform contract.
 
-```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
-```
-
-Enable trusted proxy mode only when untrusted clients cannot bypass the trusted reverse proxy/load balancer.
+Production hardening supports configurable request/header/keep-alive/shutdown timeouts, trusted-proxy handling and `SIGTERM` / `SIGINT` graceful shutdown.
 
 Read more: [Production Hardening](docs/production-hardening.md)
 
-## Doctor / Inspect / project metadata
-
-Project diagnostics:
-
-```powershell
-npm exec -- bcp-framework doctor
-npm exec -- bcp-framework inspect --json
-```
+## Documentation Platform — 0.2.1
 
-Doctor/Inspect v2 can report lockfile/package-manager state, duplicate framework declarations, standalone build presence, Docker/project diagnostics, storage provider and production-hardening configuration.
+`0.2.1` makes the framework repository directly consumable by `bcp-docs-web`.
 
-Projects created by recent `create-bcp-app` versions include non-secret scaffold metadata:
+Recommended website flow:
 
 ```text
-bcp.project.json
+selected framework ref
+        ↓
+docs/docs-web-manifest.json
+docs/platform-manifest.json
+docs/api-manifest.json
+        ↓
+validate version + release state + public entrypoints
+        ↓
+load referenced Markdown
+        ↓
+sync CMS/search/navigation
+        ↓
+render bcp-docs-web
 ```
 
-Credentials, database passwords, access keys, JWT/session secrets and tokens must never be stored in that file.
-
-Guides:
-
-- [Developer Tools](docs/developer-tools.md)
-- [Project Metadata](docs/project-metadata.md)
+`bcp-docs-web` should not maintain a second hard-coded framework page list.
 
-## Updating from 0.1.x
+The manifests provide:
 
-`0.2.0` does not intentionally remove public entrypoints from the `0.1.29` baseline.
+```text
+sidebar/category order
+website routes
+Markdown sources
+version + release state
+release routes
+public package entrypoints
+API guide ownership
+```
 
-Recommended upgrade flow after publication:
+The docs sync may target a release ref for historical content:
 
 ```powershell
-npm exec -- bcp-framework doctor
-npm exec -- bcp-framework update --check
-npm exec -- bcp-framework update 0.2.0
-npm run typecheck
-npm run build
+npm run docs:sync -- --ref=v0.2.0
 ```
 
-Do not reuse a standalone `.bcp-framework/build` produced by an older framework version; rebuild after upgrading.
-
-Read more: [Migrating to 0.2.0](docs/migration-0.2.md)
-
-## Documentation source and bcp-docs-web
-
-The framework repository is the documentation source of truth.
-
-`bcp-docs-web` should consume:
+Read more:
 
-```text
-docs/docs-web-manifest.json
-  -> navigation, routes, Markdown sources and release routes
+- [Documentation Platform](docs/documentation-platform.md)
+- [Documentation Source Map](docs/README.md)
+- [Docs-Web Manifest](docs/docs-web-manifest.json)
+- [Platform Manifest](docs/platform-manifest.json)
+- [API Manifest](docs/api-manifest.json)
 
-docs/platform-manifest.json
-  -> version, runtime target, public entrypoints and capabilities
-```
+## Updating from 0.1.x / 0.2.x
 
-Markdown under `docs/` remains the authored content source.
+`0.2.1` does not intentionally remove application public entrypoints from the `0.2.0` baseline.
 
-Start here:
+After upgrading, always rebuild the standalone artifact instead of reusing `.bcp-framework/build` from another framework version.
 
-- [Documentation Source Map](docs/README.md)
-- [Docs-Web Manifest](docs/docs-web-manifest.json)
-- [Platform Manifest](docs/platform-manifest.json)
-- [Framework Platform Contract](docs/platform-contract.md)
-- [Migration Guide](docs/migration-0.2.md)
+Read more: [Migrating to 0.2.x](docs/migration-0.2.md)
 
 ## Release validation
 
@@ -410,7 +383,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.0` adds a platform-contract package smoke check that verifies the prepared npm artifact's public exports, executable aliases, Node baseline, docs metadata and framework/create-app version parity.
+`0.2.1` adds Documentation Platform unit/package checks that validate manifest version parity, docs source existence, API/public-entrypoint parity and prepared npm documentation artifacts.
 
 Do not tag or publish a release until the final release commit passes the complete RC sequence.
 
@@ -418,23 +391,31 @@ Do not tag or publish a release until the final release commit passes the comple
 
 | 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 |
 | `0.1.27` | Storage Ecosystem |
 | `0.1.28` | Production Hardening |
 | `0.1.29` | Developer Experience |
-| `0.2.0` | Framework Platform baseline |
+| `0.2.0` | Framework Platform |
+| `0.2.1` | Documentation Platform |
+
+## Roadmap
+
+Next planned milestone:
+
+```text
+0.2.2 — Configuration & Environment v2
+```
 
-## Next direction
+Focus:
 
-After the `0.2.0` platform baseline is validated and released, later `0.2.x` work can add broader build/deployment targets and higher-level platform features without changing the existing standalone Node.js contract by accident.
+- typed production configuration improvements,
+- environment validation,
+- startup configuration diagnostics,
+- configuration schema/inspection tooling.
 
-Native executable/desktop/mobile packaging remains future roadmap work, not a `0.2.0` guarantee.
+Application packaging (`bcp package`, native executable experiments) remains later `0.2.x` roadmap work.
 
 ## License