@chidchanun/bcp 0.1.28 → 0.2.0

package/docs/README.md

@@ -1,34 +1,80 @@
 # BCP Framework Documentation Source
 
-The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized for the **`bcp-docs-web`** website.
+The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.1.28`
+> **Documentation target:** BCP Framework `0.2.0`
 >
-> **Release state:** unreleased development target. Do not label `0.1.28` as published until RC validation and npm publication complete.
+> **Release state:** unreleased development target. Do not label `0.2.0` as published until RC validation, tagging and npm publication complete.
 
-## Documentation flow
+## Documentation architecture
+
+BCP `0.2.0` uses two machine-readable manifests:
+
+```text
+docs/docs-web-manifest.json
+  -> website navigation, routes, Markdown sources and release pages
+
+docs/platform-manifest.json
+  -> framework version, runtime target, public entrypoints and capability metadata
+```
+
+Markdown files under `docs/` remain the authored content source.
+
+Recommended flow:
 
 ```text
-BCP Framework source/tests
+framework source/tests
         ↓
       docs/
+        ├─ Markdown content
+        ├─ docs-web-manifest.json
+        └─ platform-manifest.json
         ↓
-   bcp-docs-web
+    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 remain authoritative for runtime behavior.
+
+## 0.2.0 Framework Platform baseline
+
+`0.2.0` establishes an explicit compatibility/platform contract rather than introducing a new runtime architecture.
+
+New platform documents:
+
+| Source | Purpose |
+| --- | --- |
+| `platform-manifest.json` | Machine-readable platform/version/public-entrypoint metadata |
+| `platform-contract.md` | Human-readable public platform contract |
+| `migration-0.2.md` | Upgrade guide from the `0.1.x` baseline |
+| `releases/0.2.0.md` | Release notes for the milestone |
+
+Compatibility intent from `0.1.29`:
+
+```text
+intentional public-entrypoint removals: none
+standalone runtime model change: none
+supported production build target: standalone-node
+```
+
+BCP remains pre-1.0, so application upgrades should still be validated before production deployment.
 
 ## Update rule
 
-When framework behavior changes:
+When framework behavior or public surface 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 guide.
+4. Update `platform-manifest.json` when public entrypoints/runtime/capability metadata changes.
+5. Update `docs-web-manifest.json` when website navigation/routes change.
+6. Update `docs/releases/<version>.md`.
+7. Change release state to published only after npm publication succeeds.
+
+## Current docs-web navigation
+
+`docs/docs-web-manifest.json` is the authoritative ordered navigation contract.
 
-## Recommended `bcp-docs-web` navigation
+Current sections:
 
 ```text
 Getting Started
@@ -37,89 +83,131 @@ Authentication
 Database
 Runtime & Infrastructure
 Storage & Uploads
-API Reference
+Developer Experience
+Platform & Compatibility
 Releases
 ```
 
 ### Getting Started
 
-| Website route | Markdown source | Purpose |
-| --- | --- | --- |
-| `/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/deployment` | `deployment.md` | Standalone production deployment |
-| `/docs/updating` | `updating.md` | Framework upgrades |
+| Website route | Markdown source |
+| --- | --- |
+| `/docs/getting-started` | `getting-started.md` |
+| `/docs/configuration` | `configuration.md` |
+| `/docs/application-modules` | `application-modules.md` |
+| `/docs/project-metadata` | `project-metadata.md` |
+| `/docs/deployment` | `deployment.md` |
+| `/docs/updating` | `updating.md` |
 
 ### Routing & Data
 
-| Website route | Markdown source | Purpose |
-| --- | --- | --- |
-| `/docs/routing` | `routing.md` | File-based page/API routing |
-| `/docs/server-data-loaders` | `server-data-loaders.md` | Server-side page data |
-| `/docs/route-guards` | `route-guards.md` | Scoped route authorization |
-| `/docs/form-actions` | `form-actions.md` | Server mutations/forms |
-| `/docs/server-request-apis` | `server-request-apis.md` | Request/cookie/response APIs |
-| `/docs/validation` | `validation.md` | Typed validation |
-| `/docs/error-handling` | `error-handling.md` | Structured HTTP errors |
+| Website route | Markdown source |
+| --- | --- |
+| `/docs/routing` | `routing.md` |
+| `/docs/server-data-loaders` | `server-data-loaders.md` |
+| `/docs/route-guards` | `route-guards.md` |
+| `/docs/form-actions` | `form-actions.md` |
+| `/docs/server-request-apis` | `server-request-apis.md` |
+| `/docs/validation` | `validation.md` |
+| `/docs/error-handling` | `error-handling.md` |
 
 ### Authentication
 
-| Website route | Markdown source | Purpose |
-| --- | --- | --- |
-| `/docs/authentication` | `authentication.md` | Authentication Core |
-| `/docs/auth-route-guards` | `auth-route-guards.md` | Auth-aware route guards |
-| `/docs/session-auth` | `session-auth.md` | JWT cookie sessions |
+| Website route | Markdown source |
+| --- | --- |
+| `/docs/authentication` | `authentication.md` |
+| `/docs/auth-route-guards` | `auth-route-guards.md` |
+| `/docs/session-auth` | `session-auth.md` |
 
 ### Database
 
-| Website route | Markdown source | Purpose |
-| --- | --- | --- |
-| `/docs/database` | `database.md` | MySQL database primitives |
-| `/docs/database-migrations` | `database-migrations.md` | Migration CLI/files |
+| Website route | Markdown source |
+| --- | --- |
+| `/docs/database` | `database.md` |
+| `/docs/database-migrations` | `database-migrations.md` |
 
 ### Runtime & Infrastructure
 
-| Website route | Markdown source | Purpose |
-| --- | --- | --- |
-| `/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 production timeouts |
+| Website route | Markdown source |
+| --- | --- |
+| `/docs/middleware` | `middleware.md` |
+| `/docs/hydration` | `hydration.md` |
+| `/docs/development-logging` | `development-logging.md` |
+| `/docs/caching` | `caching.md` |
+| `/docs/security` | `security.md` |
+| `/docs/production-hardening` | `production-hardening.md` |
 
 ### Storage & Uploads
 
-| Website route | Markdown source | Purpose |
-| --- | --- | --- |
-| `/docs/file-upload` | `file-upload.md` | Buffered + streaming multipart uploads |
-| `/docs/storage` | `storage.md` | StorageAdapter, streaming and file delivery |
-| `/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 |
+| Website route | Markdown source |
+| --- | --- |
+| `/docs/file-upload` | `file-upload.md` |
+| `/docs/storage` | `storage.md` |
+| `/docs/storage-ecosystem` | `storage-ecosystem.md` |
+| `/docs/s3-storage` | `s3-storage.md` |
 
-## API Reference ownership
+### Developer Experience
+
+| Website route | Markdown source |
+| --- | --- |
+| `/docs/generators` | `generators.md` |
+| `/docs/developer-tools` | `developer-tools.md` |
+
+### Platform & Compatibility
+
+| Website route | Markdown source |
+| --- | --- |
+| `/docs/platform-contract` | `platform-contract.md` |
+| `/docs/migration-0.2` | `migration-0.2.md` |
+
+## Platform manifest
+
+`docs/platform-manifest.json` is intended for tooling and `bcp-docs-web` metadata displays.
+
+It records:
+
+```text
+schema version
+framework/version/release state
+Node/React/runtime baseline
+production build target
+public package entrypoints
+CLI command families
+capability groups
+storage-provider families
+previous-baseline compatibility intent
+documentation contract files
+```
 
-Recommended entrypoint groups:
+Do not treat the manifest as executable runtime configuration. It describes the supported platform surface; framework source/tests remain authoritative.
+
+## Public entrypoint baseline
+
+The `0.2.0` platform recognizes:
 
 ```text
 bcp
-bcp/server
-bcp/auth
-bcp/database
-bcp/validation
-bcp/error
+bcp/island
 bcp/cache
 bcp/config
+bcp/validation
+bcp/error
+bcp/database
+bcp/auth
+bcp/server
+bcp/server-only
 bcp/middleware
 ```
 
-| Entrypoint | Primary guide |
+`bcp-docs-web` can use this list to build an API-reference index without hard-coding a second entrypoint list.
+
+## API guide ownership
+
+| Entrypoint | Primary guides |
 | --- | --- |
 | `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`, `production-hardening.md` |
-| `bcp/auth` | `authentication.md`, `auth-route-guards.md` |
+| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `storage-ecosystem.md`, `production-hardening.md` |
+| `bcp/auth` | `authentication.md`, `auth-route-guards.md`, `session-auth.md` |
 | `bcp/database` | `database.md`, `database-migrations.md` |
 | `bcp/validation` | `validation.md` |
 | `bcp/error` | `error-handling.md` |
@@ -133,163 +221,92 @@ bcp/middleware
 
 - React SSR/hydration
 - file-based page/API routing
-- static/dynamic/catch-all/optional-catch-all routes
-- route groups/layouts/metadata
+- dynamic/catch-all/optional catch-all routes
+- layouts/metadata/route groups
 - SPA navigation
 - loaders/guards/form actions
 - client islands / partial hydration
-- Fast Refresh
 
-### Server and production runtime
+### Server/runtime
 
-- request-scoped APIs/cookies/redirects/request IDs
-- JWT sessions/authentication
+- request-scoped server APIs
+- JWT cookie sessions
 - Middleware System v2
-- 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
-- production streaming multipart upload (`storeMultipartFile()`)
-- backward-compatible `StorageAdapter` contract
-- local filesystem storage
-- S3/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
-- portable user metadata
-- bulk deletion
-- S3 presigned read/write URLs
-- create-app Local Server / Amazon S3 / Cloudflare R2 presets
+- validation and structured HTTP errors
+- structured logging/request IDs
+- response caching/revalidation
+- production hardening/timeouts
+- graceful shutdown and shutdown hooks
+- trusted-proxy controls
 
 ### Database
 
-- `bcp/database`
-- lazy MySQL pool
-- prepared execution/query helpers
+- MySQL framework primitives
+- prepared query/execute helpers
 - transactions
 - migrations/status/rollback
 
+### Storage & uploads
+
+- buffered multipart APIs
+- streaming multipart upload
+- local filesystem storage
+- Amazon S3 / Cloudflare R2 / S3-compatible storage
+- streaming reads/writes and byte ranges
+- list/copy/move
+- portable metadata
+- bulk delete
+- S3 signed read/write URLs
+
 ### Developer Experience
 
 - `create-bcp-app`
-- `bcp update`
-- `bcp doctor`
-- `bcp inspect`
+- Local / Amazon S3 / Cloudflare R2 storage presets
+- non-secret `bcp.project.json`
+- page/API/middleware/migration generators
+- Doctor/Inspect v2
+- framework updater
 - Windows-safe `bcp-framework` alias
-- standalone production build
-- unit/integration/E2E/package/RC checks
-
-## BCP 0.1.28 documentation focus
 
-### Production hardening
+## Build/runtime baseline
 
-Public cleanup API:
-
-```ts
-import {
-    getProductionHardeningConfig,
-    registerShutdownHook,
-} from "bcp/server";
-```
-
-Production environment controls:
-
-```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
-```
-
-Document these boundaries clearly:
-
-- trusted proxy mode is off by default,
-- forwarding headers are sanitized when trust is disabled,
-- enable trust only behind a trusted reverse proxy/load balancer,
-- Docker/process-manager `SIGTERM` triggers graceful shutdown,
-- shutdown hooks are process-lifetime resource cleanup, not request cleanup,
-- shutdown force-closes remaining public connections after the configured timeout.
-
-See `production-hardening.md`.
-
-### Local Server generator fix
-
-`create-bcp-app --storage local` now generates:
+Supported `0.2.0` production target:
 
 ```text
-lib/storage.ts
-storage/
-├─ .gitkeep
-└─ README.md
-```
-
-Runtime objects remain ignored while the scaffold stays visible/tracked.
-
-### 0.1.27 storage ecosystem remains supported
-
-The storage ecosystem continues to include listing, copy/move, portable metadata, bulk deletion and S3 signed URLs. `0.1.28` hardens deployment/runtime behavior rather than replacing those APIs.
-
-## CLI commands
-
-```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
+standalone-node
 ```
 
-On Windows, direct project-local commands should prefer:
+Build output:
 
-```powershell
-npm exec -- bcp-framework doctor
-npm exec -- bcp-framework inspect
-npm exec -- bcp-framework dev
-npm exec -- bcp-framework build
+```text
+.bcp-framework/build/
+├─ client/
+├─ public/
+└─ server/
+   └─ server.mjs
 ```
 
-Inside npm scripts, `bcp` is safe because npm prepends `node_modules/.bin` to `PATH`.
+Native executable, desktop and mobile compilation are not part of the `0.2.0` platform contract.
 
 ## Releases
 
-Release notes live under:
+Release notes live in:
 
 ```text
 docs/releases/
 ```
 
-Recommended routes:
+Current manifest routes begin with:
 
 ```text
+/releases/0.2.0
+/releases/0.1.29
 /releases/0.1.28
 /releases/0.1.27
 /releases/0.1.26
-/releases/0.1.25
-/releases/0.1.24
 ```
 
-Use one of these release states:
+Use release states consistently:
 
 ```text
 published
@@ -297,97 +314,96 @@ release candidate
 unreleased development target
 ```
 
-The existence of a release note alone does not mean the npm version is published.
-
-## Suggested website model
-
-```ts
-interface DocPage {
-    title: string;
-    slug: string;
-    section: string;
-    sourceFile: string;
-    versionTarget?: string;
-    releaseState?:
-        | "published"
-        | "rc"
-        | "unreleased";
-}
-```
+The presence of a release note does not mean the npm version is published.
+
+## Suggested bcp-docs-web implementation
 
-## Suggested website features
+At build/startup:
 
-1. Sidebar navigation from this source map.
-2. Markdown rendering + syntax highlighting.
-3. Previous/next navigation.
-4. Version/release-state banner.
-5. Release pages.
-6. Full-text search.
-7. Copy buttons for code blocks.
-8. Mobile navigation.
-9. GitHub source/edit links.
+```text
+load docs-web-manifest.json
+load platform-manifest.json
+        ↓
+validate schema/version relationship
+        ↓
+build sidebar + route map + release map
+        ↓
+load referenced Markdown
+        ↓
+render content + prev/next + search index
+        ↓
+show version/release/platform metadata
+```
 
-Later:
+Recommended website behavior:
 
-- generated symbol reference,
-- versioned snapshots,
-- interactive examples/playgrounds,
-- release comparison pages.
+1. Build navigation in manifest order.
+2. Resolve every website route to its Markdown source.
+3. Generate previous/next links from manifest ordering.
+4. Use `versionTarget` and `releaseState` for banners.
+5. Use `platform-manifest.json` for runtime/public-entrypoint metadata.
+6. Index Markdown headings/content for search.
+7. Never ingest runtime `.env` files into public documentation output.
 
 ## Source conventions
 
-- one H1 per page,
+- one H1 per Markdown page,
 - stable heading hierarchy,
 - fenced code blocks with language tags,
 - relative links between docs,
 - exact public API names,
 - clear stable/RC/roadmap labels,
 - security limitations next to affected APIs,
-- runnable examples where possible,
-- no private/internal modules presented as public API.
+- no framework-internal module presented as public API.
 
 ## Release validation
 
-Before publishing:
+Before publishing `0.2.0`:
 
 ```bash
 npm run typecheck
 npm run test:unit
 npm run test:integration
-npm run test:e2e
 npm run test:package
+npm run test:e2e
 npm run rc:check
 ```
 
-For `0.1.28`, package validation must confirm the staged artifact includes the production hardening runtime/gateway, shutdown APIs, Local Server generator fix, and the existing S3 runtime dependencies.
-
-A representative Docker app should also be built and stopped with `docker stop` to verify graceful `SIGTERM` shutdown.
+`0.2.0` adds a platform-contract package smoke check that verifies:
 
-## Documentation QA checklist
+- prepared framework/create-app version parity,
+- required public exports,
+- both CLI executable aliases,
+- Node.js engine baseline,
+- inclusion of platform/docs contract files,
+- docs-web target/version consistency.
 
-- linked Markdown files exist,
-- examples use public exports,
-- version/release states are current,
-- Windows direct CLI examples use `npm exec -- bcp-framework`,
-- upload/storage/auth security caveats are present,
-- release notes match the framework version,
-- S3 credentials are never shown as public browser variables,
-- signed URLs are documented as temporary credentials,
-- proxy trust is documented as opt-in,
-- roadmap APIs are not presented as published guarantees.
+The final release tag must point to the commit that passed the complete RC sequence.
 
-## Next direction after 0.1.28
+## Documentation QA checklist
 
-Planned `0.1.29 — Developer Experience` focus:
+- every manifest Markdown source exists,
+- every website route is unique,
+- docs-web target matches platform version,
+- platform public entrypoints match package exports,
+- examples use public APIs/commands,
+- release states are accurate,
+- secrets are never placed in project/docs metadata,
+- proxy trust remains opt-in,
+- roadmap features are not presented as release guarantees.
 
-- generators for common framework files,
-- richer `doctor` and `inspect`,
-- improved build/runtime diagnostics,
-- create-app preset improvements,
-- production configuration diagnostics.
+## Repository authority
 
-These remain roadmap items until their source/tests land.
+The framework repository remains authoritative for:
 
-## Repository authority
+```text
+source
+public exports
+tests
+Markdown docs
+docs-web manifest
+platform manifest
+release notes
+```
 
-The framework repository remains authoritative for source, public exports, tests, docs and release notes. `bcp-docs-web` is the presentation/search/navigation layer for this content.
+`bcp-docs-web` is the presentation/search/navigation layer for this content.