@chidchanun/bcp 0.2.0 → 0.2.1

package/docs/README.md

@@ -2,23 +2,26 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.0`
+> **Documentation target:** BCP Framework `0.2.1`
 >
-> **Release state:** unreleased development target. Do not label `0.2.0` 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 architecture
+## Documentation architecture — 0.2.1
 
-BCP `0.2.0` uses two machine-readable manifests:
+BCP uses three machine-readable documentation contracts:
 
 ```text
 docs/docs-web-manifest.json
-  -> website navigation, routes, Markdown sources and release pages
+  -> website navigation, routes, Markdown sources and release routes
 
 docs/platform-manifest.json
-  -> framework version, runtime target, public entrypoints and capability metadata
+  -> framework version, runtime target, public entrypoints and capabilities
+
+docs/api-manifest.json
+  -> public package entrypoints, source ownership and guide mapping
 ```
 
-Markdown files under `docs/` remain the authored content source.
+Markdown files under `docs/` remain the authored documentation content.
 
 Recommended flow:
 
@@ -28,35 +31,30 @@ framework source/tests
       docs/
         ├─ Markdown content
         ├─ docs-web-manifest.json
-        └─ platform-manifest.json
+        ├─ platform-manifest.json
+        └─ api-manifest.json
+        ↓
+manifest-driven sync
         ↓
     bcp-docs-web
 ```
 
 Framework source and tests remain authoritative for runtime behavior.
 
-## 0.2.0 Framework Platform baseline
+## Documentation Platform
 
-`0.2.0` establishes an explicit compatibility/platform contract rather than introducing a new runtime architecture.
+`0.2.1` adds a versioned contract between the framework repository and the documentation website.
 
-New platform documents:
+New sources:
 
 | 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 |
+| `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 |
 
-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.
+The website should not maintain a second hard-coded list of framework pages when those pages exist in `docs-web-manifest.json`.
 
 ## Update rule
 
@@ -65,14 +63,15 @@ When framework behavior or public surface changes:
 1. Update framework source.
 2. Add/update regression tests.
 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.
+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.
 
-## Current docs-web navigation
+## Docs-web navigation
 
-`docs/docs-web-manifest.json` is the authoritative ordered navigation contract.
+`docs/docs-web-manifest.json` is the ordered navigation contract.
 
 Current sections:
 
@@ -85,105 +84,52 @@ Runtime & Infrastructure
 Storage & Uploads
 Developer Experience
 Platform & Compatibility
+API Reference
 Releases
 ```
 
-### Getting Started
-
-| 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 |
-| --- | --- |
-| `/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 |
-| --- | --- |
-| `/docs/authentication` | `authentication.md` |
-| `/docs/auth-route-guards` | `auth-route-guards.md` |
-| `/docs/session-auth` | `session-auth.md` |
-
-### Database
-
-| Website route | Markdown source |
-| --- | --- |
-| `/docs/database` | `database.md` |
-| `/docs/database-migrations` | `database-migrations.md` |
-
-### Runtime & Infrastructure
-
-| 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 |
-| --- | --- |
-| `/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 |
-| --- | --- |
-| `/docs/generators` | `generators.md` |
-| `/docs/developer-tools` | `developer-tools.md` |
-
-### Platform & Compatibility
+Important `0.2.1` routes:
 
 | 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` |
 
-## Platform manifest
+Every route/source pair is validated by unit tests.
 
-`docs/platform-manifest.json` is intended for tooling and `bcp-docs-web` metadata displays.
+## Platform manifest
 
-It records:
+`docs/platform-manifest.json` describes the supported framework baseline:
 
 ```text
 schema version
-framework/version/release state
+framework version/release state
 Node/React/runtime baseline
 production build target
 public package entrypoints
 CLI command families
-capability groups
+capabilities
 storage-provider families
-previous-baseline compatibility intent
+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.
+Supported production target remains:
+
+```text
+standalone-node
+```
+
+Native executable, desktop and mobile compilation remain future roadmap work.
+
+## API manifest
 
-## Public entrypoint baseline
+`docs/api-manifest.json` describes the public package entrypoints that documentation tooling may present as supported API surfaces.
 
-The `0.2.0` platform recognizes:
+Current entrypoints:
 
 ```text
 bcp
@@ -199,151 +145,68 @@ bcp/server-only
 bcp/middleware
 ```
 
-`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`, `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` |
-| `bcp/cache` | `caching.md` |
-| `bcp/config` | `configuration.md` |
-| `bcp/middleware` | `middleware.md` |
-
-## Current capability groups
-
-### Application
-
-- React SSR/hydration
-- file-based page/API routing
-- dynamic/catch-all/optional catch-all routes
-- layouts/metadata/route groups
-- SPA navigation
-- loaders/guards/form actions
-- client islands / partial hydration
-
-### Server/runtime
-
-- request-scoped server APIs
-- JWT cookie sessions
-- Middleware System v2
-- validation and structured HTTP errors
-- structured logging/request IDs
-- response caching/revalidation
-- production hardening/timeouts
-- graceful shutdown and shutdown hooks
-- trusted-proxy controls
-
-### Database
-
-- 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`
-- 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
-
-## Build/runtime baseline
-
-Supported `0.2.0` production target:
-
-```text
-standalone-node
-```
-
-Build output:
-
-```text
-.bcp-framework/build/
-├─ client/
-├─ public/
-└─ server/
-   └─ server.mjs
-```
-
-Native executable, desktop and mobile compilation are not part of the `0.2.0` platform contract.
-
-## Releases
-
-Release notes live in:
-
-```text
-docs/releases/
-```
-
-Current manifest routes begin with:
+Each API entry records:
 
 ```text
-/releases/0.2.0
-/releases/0.1.29
-/releases/0.1.28
-/releases/0.1.27
-/releases/0.1.26
+package
+source file
+environment boundary
+reference route
+summary
+related guide routes
 ```
 
-Use release states consistently:
-
-```text
-published
-release candidate
-unreleased development target
-```
+The API-manifest entrypoint set must match the public-entrypoint set in `platform-manifest.json` exactly.
 
-The presence of a release note does not mean the npm version is published.
+See [API Reference](api-reference.md).
 
-## Suggested bcp-docs-web implementation
+## bcp-docs-web synchronization
 
-At build/startup:
+The `bcp-docs-web` sync should load all three manifests first.
 
 ```text
-load docs-web-manifest.json
-load platform-manifest.json
+selected framework ref
         ↓
-validate schema/version relationship
+docs-web-manifest.json
+platform-manifest.json
+api-manifest.json
         ↓
-build sidebar + route map + release map
+validate version/release/API parity
         ↓
-load referenced Markdown
+load only referenced Markdown
         ↓
-render content + prev/next + search index
+rewrite internal Markdown links to website routes
         ↓
-show version/release/platform metadata
+synchronize CMS/search/navigation
 ```
 
-Recommended website behavior:
+The matching docs-web implementation supports local framework source or a selected Git ref.
+
+Examples:
+
+```powershell
+npm run docs:sync -- --dry-run
+npm run docs:sync -- --publish-new
+npm run docs:sync -- --ref=v0.2.0
+```
 
-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.
+Using a tag/ref is the foundation for historical/versioned documentation without manually copying current Markdown into another source tree.
+
+## Public API guide ownership
+
+| 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
 
@@ -354,11 +217,18 @@ Recommended website behavior:
 - exact public API names,
 - clear stable/RC/roadmap labels,
 - security limitations next to affected APIs,
-- no framework-internal module 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 `0.2.0`:
+Before publishing `0.2.1`:
 
 ```bash
 npm run typecheck
@@ -369,28 +239,16 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`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 final release tag must point to the commit that passed the complete RC sequence.
+Documentation Platform validation covers:
 
-## Documentation QA checklist
+- 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.
 
-- 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.
+The final release tag must point to the exact commit that passed the complete RC sequence.
 
 ## Repository authority
 
@@ -403,7 +261,23 @@ 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.

package/docs/api-manifest.json

@@ -0,0 +1,129 @@
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "version": "0.2.1",
+  "releaseState": "unreleased",
+  "coverage": "public-entrypoints",
+  "entrypoints": [
+    {
+      "package": "bcp",
+      "source": "packages/client/src/index.tsx",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp",
+      "summary": "React application APIs for routing, links, forms, loader/guard data, islands, metadata and route error handling.",
+      "guides": [
+        "/docs/routing",
+        "/docs/server-data-loaders",
+        "/docs/route-guards",
+        "/docs/form-actions"
+      ]
+    },
+    {
+      "package": "bcp/island",
+      "source": "packages/client/src/islands.tsx",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp-island",
+      "summary": "Partial-hydration island creation and island loading strategy types.",
+      "guides": [
+        "/docs/hydration"
+      ]
+    },
+    {
+      "package": "bcp/cache",
+      "source": "packages/client/src/cache.ts",
+      "environment": "server-preferred",
+      "route": "/docs/api-reference#bcp-cache",
+      "summary": "Cache, deduplication, statistics and path/tag revalidation primitives.",
+      "guides": [
+        "/docs/caching"
+      ]
+    },
+    {
+      "package": "bcp/config",
+      "source": "packages/client/src/config.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-config",
+      "summary": "Typed BCP configuration definition, loading and resolution APIs.",
+      "guides": [
+        "/docs/configuration"
+      ]
+    },
+    {
+      "package": "bcp/validation",
+      "source": "packages/client/src/validation.ts",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp-validation",
+      "summary": "Typed validators, parse helpers and structured validation errors.",
+      "guides": [
+        "/docs/validation"
+      ]
+    },
+    {
+      "package": "bcp/error",
+      "source": "packages/client/src/http-error.ts",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp-error",
+      "summary": "Structured HTTP error creation, classification and response helpers.",
+      "guides": [
+        "/docs/error-handling"
+      ]
+    },
+    {
+      "package": "bcp/database",
+      "source": "packages/client/src/database.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-database",
+      "summary": "Database pool, prepared query/execute helpers and transaction primitives.",
+      "guides": [
+        "/docs/database",
+        "/docs/database-migrations"
+      ]
+    },
+    {
+      "package": "bcp/auth",
+      "source": "packages/client/src/auth.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-auth",
+      "summary": "Authentication, login/logout/session rotation and route authorization guards.",
+      "guides": [
+        "/docs/authentication",
+        "/docs/auth-route-guards",
+        "/docs/session-auth"
+      ]
+    },
+    {
+      "package": "bcp/server",
+      "source": "packages/client/src/server.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-server",
+      "summary": "Request context, cookies, logging, production hardening, upload, storage, response and session APIs.",
+      "guides": [
+        "/docs/server-request-apis",
+        "/docs/file-upload",
+        "/docs/storage",
+        "/docs/storage-ecosystem",
+        "/docs/production-hardening"
+      ]
+    },
+    {
+      "package": "bcp/server-only",
+      "source": "packages/client/src/server-only.mjs",
+      "environment": "server-marker",
+      "route": "/docs/api-reference#bcp-server-only",
+      "summary": "Server-only module boundary marker that prevents accidental browser inclusion.",
+      "guides": [
+        "/docs/application-modules"
+      ]
+    },
+    {
+      "package": "bcp/middleware",
+      "source": "packages/server/src/middleware.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-middleware",
+      "summary": "Middleware System v2 request/response pipeline types and helpers.",
+      "guides": [
+        "/docs/middleware"
+      ]
+    }
+  ]
+}