@chidchanun/bcp 0.1.29 → 0.2.1

package/docs/README.md

@@ -1,72 +1,79 @@
 # 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.1`
 >
-> **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.1` as published until RC validation, tagging and npm publication complete.
 
-## Documentation flow
+## Documentation architecture — 0.2.1
+
+BCP uses three machine-readable documentation contracts:
 
 ```text
-BCP Framework source/tests
-        ↓
-      docs/
-        ↓
-Markdown content + docs-web manifest
-        ↓
-   bcp-docs-web
-```
+docs/docs-web-manifest.json
+  -> website navigation, routes, Markdown sources and release routes
 
-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/platform-manifest.json
+  -> framework version, runtime target, public entrypoints and capabilities
 
-## Docs-web navigation contract — 0.1.29
+docs/api-manifest.json
+  -> public package entrypoints, source ownership and guide mapping
+```
 
-`docs/docs-web-manifest.json` is the explicit navigation and route contract for the docs website.
+Markdown files under `docs/` remain the authored documentation content.
 
-It defines:
+Recommended flow:
 
 ```text
-schema version
-framework/version target
-release state
-section IDs/titles
-website routes
-Markdown source files
-page titles
-release routes
+framework source/tests
+        ↓
+      docs/
+        ├─ Markdown content
+        ├─ docs-web-manifest.json
+        ├─ platform-manifest.json
+        └─ api-manifest.json
+        ↓
+manifest-driven sync
+        ↓
+    bcp-docs-web
 ```
 
-Recommended docs-web workflow:
+Framework source and tests remain authoritative for runtime behavior.
 
-```text
-read docs/docs-web-manifest.json
-          ↓
-generate sidebar + route map
-          ↓
-load referenced Markdown file
-          ↓
-render content/search/prev-next
-```
+## Documentation Platform
 
-Do not duplicate this mapping in a second hard-coded sidebar unless the website needs a temporary bootstrap fallback.
+`0.2.1` adds a versioned contract between the framework repository and the documentation website.
 
-Markdown remains the content source; the manifest contains navigation metadata only.
+New sources:
+
+| Source | Purpose |
+| --- | --- |
+| `api-manifest.json` | Public API entrypoint metadata |
+| `api-reference.md` | Human-readable public package entrypoint reference |
+| `documentation-platform.md` | Docs-web synchronization/versioning contract |
+| `releases/0.2.1.md` | Documentation Platform release notes |
+
+The website should not maintain a second hard-coded list of framework pages when those pages exist in `docs-web-manifest.json`.
 
 ## 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 runtime/public-entrypoint/capability metadata changes.
+5. Update `api-manifest.json` when public API entrypoint ownership changes.
+6. Update `docs-web-manifest.json` when website routes/navigation change.
+7. Update `docs/releases/<version>.md`.
+8. Change release state only after the release workflow reaches that state.
+
+## Docs-web navigation
 
-## Recommended `bcp-docs-web` navigation
+`docs/docs-web-manifest.json` is the ordered navigation contract.
 
-The current manifest groups documentation into:
+Current sections:
 
 ```text
 Getting Started
@@ -76,389 +83,172 @@ Database
 Runtime & Infrastructure
 Storage & Uploads
 Developer Experience
+Platform & Compatibility
+API Reference
 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 |
-
-### 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 |
+Important `0.2.1` routes:
 
-### 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/platform-contract` | `platform-contract.md` |
+| `/docs/documentation-platform` | `documentation-platform.md` |
+| `/docs/migration-0.2` | `migration-0.2.md` |
+| `/docs/api-reference` | `api-reference.md` |
+| `/releases/0.2.1` | `releases/0.2.1.md` |
 
-### Database
+Every route/source pair is validated by unit tests.
 
-| Website route | Markdown source | Purpose |
-| --- | --- | --- |
-| `/docs/database` | `database.md` | MySQL database primitives |
-| `/docs/database-migrations` | `database-migrations.md` | Migration CLI/files |
+## Platform manifest
 
-### Runtime & Infrastructure
+`docs/platform-manifest.json` describes the supported framework baseline:
 
-| 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 |
+```text
+schema version
+framework version/release state
+Node/React/runtime baseline
+production build target
+public package entrypoints
+CLI command families
+capabilities
+storage-provider families
+previous baseline compatibility intent
+documentation contract files
+```
 
-### Storage & Uploads
+Supported production target remains:
 
-| 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 |
+```text
+standalone-node
+```
 
-### Developer Experience
+Native executable, desktop and mobile compilation remain future roadmap work.
 
-| 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 manifest
 
-## API Reference ownership
+`docs/api-manifest.json` describes the public package entrypoints that documentation tooling may present as supported API surfaces.
 
-Recommended entrypoint groups:
+Current entrypoints:
 
 ```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` | `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/database` | `database.md`, `database-migrations.md` |
-| `bcp/validation` | `validation.md` |
-| `bcp/error` | `error-handling.md` |
-| `bcp/cache` | `caching.md` |
-| `bcp/config` | `configuration.md` |
-| `bcp/middleware` | `middleware.md` |
-
-## Current capability groups
-
-### Application
-
-- React SSR/hydration
-- file-based page/API routing
-- static/dynamic/catch-all/optional-catch-all routes
-- route groups/layouts/metadata
-- SPA navigation
-- loaders/guards/form actions
-- client islands / partial hydration
-- Fast Refresh
-
-### Server and production runtime
-
-- request-scoped APIs/cookies/redirects/request IDs
-- JWT sessions/authentication
-- 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
-
-### Database
-
-- `bcp/database`
-- lazy MySQL pool
-- prepared execution/query helpers
-- transactions
-- migrations/status/rollback
-
-### 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`
-- Doctor/Inspect v2
-- lockfile/package-manager diagnostics
-- duplicate framework declaration checks
-- storage/provider diagnostics
-- production-build/Docker/hardening diagnostics
-- 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.
-
-See `developer-tools.md`.
-
-### Project metadata
-
-New `create-bcp-app` projects receive:
+Each API entry records:
 
 ```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
+package
+source file
+environment boundary
+reference route
+summary
+related guide routes
 ```
 
-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
-```
+The API-manifest entrypoint set must match the public-entrypoint set in `platform-manifest.json` exactly.
 
-Inside npm scripts, `bcp` is safe because npm prepends `node_modules/.bin` to `PATH`.
+See [API Reference](api-reference.md).
 
-## Releases
+## bcp-docs-web synchronization
 
-Release notes live under:
+The `bcp-docs-web` sync should load all three manifests first.
 
 ```text
-docs/releases/
-```
-
-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
+selected framework ref
+        ↓
+docs-web-manifest.json
+platform-manifest.json
+api-manifest.json
+        ↓
+validate version/release/API parity
+        ↓
+load only referenced Markdown
+        ↓
+rewrite internal Markdown links to website routes
+        ↓
+synchronize CMS/search/navigation
 ```
 
-Use one of these release states:
+The matching docs-web implementation supports local framework source or a selected Git ref.
 
-```text
-published
-release candidate
-unreleased development target
-```
+Examples:
 
-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;
-    }>;
-}
+```powershell
+npm run docs:sync -- --dry-run
+npm run docs:sync -- --publish-new
+npm run docs:sync -- --ref=v0.2.0
 ```
 
-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.
+Using a tag/ref is the foundation for historical/versioned documentation without manually copying current Markdown into another source tree.
 
-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.
+## Public API guide ownership
 
-## Suggested website features
-
-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.
-
-Later:
-
-- generated symbol reference,
-- versioned snapshots,
-- interactive examples/playgrounds,
-- release comparison pages.
+| Entrypoint | Primary guides |
+| --- | --- |
+| `bcp` | `routing.md`, `server-data-loaders.md`, `route-guards.md`, `form-actions.md` |
+| `bcp/island` | `hydration.md` |
+| `bcp/cache` | `caching.md` |
+| `bcp/config` | `configuration.md` |
+| `bcp/validation` | `validation.md` |
+| `bcp/error` | `error-handling.md` |
+| `bcp/database` | `database.md`, `database-migrations.md` |
+| `bcp/auth` | `authentication.md`, `auth-route-guards.md`, `session-auth.md` |
+| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `storage-ecosystem.md`, `production-hardening.md` |
+| `bcp/server-only` | `application-modules.md` |
+| `bcp/middleware` | `middleware.md` |
 
 ## 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,
+- no secrets/runtime `.env` values in public documentation metadata.
+
+## Search and previous/next
+
+Search should index Markdown content and headings. Manifest titles/categories/API summaries may be used as metadata.
+
+Sidebar and previous/next ordering should follow `docs-web-manifest.json` order so navigation surfaces cannot drift from each other.
 
 ## Release validation
 
-Before publishing:
+Before publishing `0.2.1`:
 
 ```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.
-
-The release lockfile must be synchronized to `0.1.29` before the final tag.
-
-## 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.
+Documentation Platform validation covers:
 
-## Next direction after 0.1.29
+- every Markdown source exists,
+- every docs/release route is unique,
+- package/platform/docs/API versions match,
+- API entrypoints match the platform public-entrypoint set,
+- API guide routes exist,
+- prepared npm packages contain the three manifests, API reference and Documentation Platform guide.
 
-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.
+The final release tag must point to the exact commit that passed the complete RC sequence.
 
 ## Repository authority
 
@@ -470,7 +260,24 @@ public exports
 tests
 Markdown docs
 docs-web manifest
+platform manifest
+API manifest
 release notes
 ```
 
-`bcp-docs-web` is the presentation/search/navigation layer for this content.
+`bcp-docs-web` remains the presentation/search/navigation layer for this content.
+
+## Next direction
+
+Planned next milestone:
+
+```text
+0.2.2 — Configuration & Environment v2
+```
+
+Focus:
+
+- typed production configuration improvements,
+- environment validation,
+- startup configuration diagnostics,
+- configuration schema/inspection tooling.