@chidchanun/bcp 0.1.29 → 0.2.0

package/docs/README.md

@@ -1,72 +1,80 @@
 # BCP Framework Documentation Source
 
-The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized for **`bcp-docs-web`**.
+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.29`
+> **Documentation target:** BCP Framework `0.2.0`
 >
-> **Release state:** unreleased development target. Do not label `0.1.29` as published until RC validation, tagging 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
         ↓
-Markdown content + docs-web manifest
-        ↓
-   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 rather than becoming a competing source of truth.
+Framework source and tests remain authoritative for runtime behavior.
 
-## Docs-web navigation contract — 0.1.29
+## 0.2.0 Framework Platform baseline
 
-`docs/docs-web-manifest.json` is the explicit navigation and route contract for the docs website.
+`0.2.0` establishes an explicit compatibility/platform contract rather than introducing a new runtime architecture.
 
-It defines:
+New platform documents:
 
-```text
-schema version
-framework/version target
-release state
-section IDs/titles
-website routes
-Markdown source files
-page titles
-release routes
-```
+| 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 |
 
-Recommended docs-web workflow:
+Compatibility intent from `0.1.29`:
 
 ```text
-read docs/docs-web-manifest.json
-          ↓
-generate sidebar + route map
-          ↓
-load referenced Markdown file
-          ↓
-render content/search/prev-next
+intentional public-entrypoint removals: none
+standalone runtime model change: none
+supported production build target: standalone-node
 ```
 
-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.
+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 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.
+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
 
-## Recommended `bcp-docs-web` navigation
+`docs/docs-web-manifest.json` is the authoritative ordered navigation contract.
 
-The current manifest groups documentation into:
+Current sections:
 
 ```text
 Getting Started
@@ -76,95 +84,130 @@ Database
 Runtime & Infrastructure
 Storage & Uploads
 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/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 |
+| 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/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 |
+| 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` |
 
 ### 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 |
+| Website route | Markdown source |
+| --- | --- |
+| `/docs/generators` | `generators.md` |
+| `/docs/developer-tools` | `developer-tools.md` |
 
-## API Reference ownership
+### Platform & Compatibility
+
+| Website route | Markdown source |
+| --- | --- |
+| `/docs/platform-contract` | `platform-contract.md` |
+| `/docs/migration-0.2` | `migration-0.2.md` |
 
-Recommended entrypoint groups:
+## 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
+```
+
+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` |
@@ -178,164 +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 upload APIs
-- production streaming multipart upload (`storeMultipartFile()`)
-- backward-compatible `StorageAdapter` contract
-- local filesystem 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
-- 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
 
-### Developer Experience — 0.1.29
+### 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`
+- Local / Amazon S3 / Cloudflare R2 storage presets
 - non-secret `bcp.project.json`
-- `bcp generate page`
-- `bcp generate api`
-- `bcp generate middleware`
-- `bcp generate migration`
-- `bcp update`
+- page/API/middleware/migration generators
 - Doctor/Inspect v2
-- lockfile/package-manager diagnostics
-- duplicate framework declaration checks
-- storage/provider diagnostics
-- production-build/Docker/hardening diagnostics
+- framework updater
 - Windows-safe `bcp-framework` alias
-- `docs/docs-web-manifest.json`
-
-## BCP 0.1.29 documentation focus
-
-### Project generators
 
-```bash
-bcp generate page dashboard/users
-bcp generate api users
-bcp generate middleware
-bcp generate migration create_users
-```
-
-Page/API/middleware generation requires `--force` before replacing existing target files.
-
-See `generators.md`.
-
-### Doctor / Inspect v2
-
-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.
+## Build/runtime baseline
 
-See `developer-tools.md`.
-
-### Project metadata
-
-New `create-bcp-app` projects receive:
+Supported `0.2.0` production target:
 
 ```text
-bcp.project.json
-```
-
-The file records scaffold choices only and must never contain credentials/secrets.
-
-See `project-metadata.md`.
-
-### Docs-web contract
-
-`docs/docs-web-manifest.json` is intended to be consumed directly by `bcp-docs-web` for navigation and route generation.
-
-The website should still read the Markdown source referenced by each manifest page entry.
-
-## CLI commands
-
-```bash
-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
-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 generate page dashboard/users
-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/
 ```
 
-The docs-web manifest currently maps:
+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
@@ -343,122 +314,83 @@ release candidate
 unreleased development target
 ```
 
-The existence of a release note alone does not mean the npm version is published.
-
-## Suggested docs-web implementation
-
-A simple implementation can model the manifest like:
-
-```ts
-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;
-    }>;
-}
-```
-
-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.
+The presence of a release note does not mean the npm version is published.
 
-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 bcp-docs-web implementation
 
-## Suggested website features
+At build/startup:
 
-1. Sidebar from `docs-web-manifest.json`.
-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.29`, validation should cover project generators, Doctor/Inspect v2, create-app project metadata, the existing production hardening runtime and package preparation.
+`0.2.0` adds a platform-contract package smoke check that verifies:
+
+- 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.
 
-The release lockfile must be synchronized to `0.1.29` before the final tag.
+The final release tag must point to the commit that passed the complete RC sequence.
 
 ## Documentation QA checklist
 
 - 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,
-- release notes match the framework version,
-- S3 credentials are never shown as public browser variables,
-- 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.29
-
-Planned **`0.2.0 — Framework Platform`** focus:
-
-- 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 goals until their source/tests land.
+- 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.
 
 ## Repository authority
 
@@ -470,6 +402,7 @@ public exports
 tests
 Markdown docs
 docs-web manifest
+platform manifest
 release notes
 ```