@chidchanun/bcp 0.1.23 → 0.1.25

package/docs/README.md

@@ -1,321 +1,292 @@
 # BCP Framework Documentation Source
 
-This directory is the documentation source of truth for the BCP Framework documentation website.
+The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized so it can be consumed later by the **`bcp-docs-web`** documentation website.
 
-The recommended documentation website project name is `bcp-docs`.
+> **Documentation target:** BCP Framework `0.1.25`
+>
+> The documentation target can be newer than the version currently published to npm. Unreleased behavior must be labeled as a development target until release validation and publication are complete.
 
-> Documentation target: BCP Framework `0.1.23`
+## Documentation goals
 
-## Purpose
+The documentation source should make it possible to build `bcp-docs-web` without duplicating framework knowledge into a second repository.
 
-The `bcp-docs` website should turn the Markdown files in this directory into a structured developer documentation experience without duplicating framework behavior in a separate source of truth.
+The expected relationship is:
+
+```text
+BCP Framework source/tests
+        ↓
+      docs/
+        ↓
+   bcp-docs-web
+```
+
+Framework source and tests remain authoritative for behavior. Markdown under `docs/` is the authored documentation layer. The future website should primarily render, organize and search this source instead of becoming a separate source of truth.
+
+## Content update rule
 
 When framework behavior changes:
 
-1. update the framework source and tests,
-2. update the relevant file in `docs/`,
-3. update the release note in `docs/releases/`,
-4. then publish or synchronize the content to `bcp-docs`.
+1. Update framework source.
+2. Add or update regression tests.
+3. Update the matching documentation file under `docs/`.
+4. Update the release note under `docs/releases/` when the change belongs to a release milestone.
+5. Only present the feature as published after release validation and npm publication complete.
 
-The website should not invent API behavior that is not documented or tested in the framework repository.
+## Recommended `bcp-docs-web` navigation
 
-## Recommended website navigation
+The website should use these top-level groups:
+
+```text
+Getting Started
+Routing & Data
+Authentication
+Database
+Runtime & Infrastructure
+API Reference
+Releases
+```
 
 ### Getting Started
 
-| Website route | Source file | Description |
+| Website route | Markdown source | Purpose |
 | --- | --- | --- |
 | `/docs/getting-started` | `getting-started.md` | Create and run a BCP application |
-| `/docs/configuration` | `configuration.md` | Framework configuration |
-| `/docs/application-modules` | `application-modules.md` | Client/server module boundaries |
-| `/docs/deployment` | `deployment.md` | Production and deployment guidance |
-| `/docs/updating` | `updating.md` | Upgrade an existing BCP project |
+| `/docs/configuration` | `configuration.md` | Framework configuration and environment behavior |
+| `/docs/application-modules` | `application-modules.md` | Client/server boundaries and module rules |
+| `/docs/deployment` | `deployment.md` | Standalone production deployment |
+| `/docs/updating` | `updating.md` | Framework upgrade workflow |
 
-### Routing and Data
+### Routing & Data
 
-| Website route | Source file | Description |
+| Website route | Markdown source | Purpose |
 | --- | --- | --- |
-| `/docs/routing` | `routing.md` | File-based routing |
+| `/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 page authorization |
+| `/docs/route-guards` | `route-guards.md` | Scoped route authorization |
 | `/docs/form-actions` | `form-actions.md` | Server mutations and forms |
-| `/docs/server-request-apis` | `server-request-apis.md` | Request, cookie, redirect and response APIs |
-| `/docs/validation` | `validation.md` | Typed form/API validation and field errors |
-| `/docs/error-handling` | `error-handling.md` | Structured HTTP errors and standard error responses |
+| `/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 |
+| `/docs/file-upload` | `file-upload.md` | Multipart parsing and upload validation |
+| `/docs/storage` | `storage.md` | Storage adapters and production file delivery |
 
 ### Authentication
 
-| Website route | Source file | Description |
+| Website route | Markdown source | Purpose |
 | --- | --- | --- |
-| `/docs/authentication` | `authentication.md` | Authentication Core and `bcp/auth` |
-| `/docs/auth-route-guards` | `auth-route-guards.md` | `requireAuth`, `requireRole` and guard integration |
-| `/docs/session-auth` | `session-auth.md` | Low-level JWT cookie sessions |
+| `/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 |
 
 ### Database
 
-| Website route | Source file | Description |
+| Website route | Markdown source | Purpose |
 | --- | --- | --- |
-| `/docs/database` | `database.md` | `bcp/database`, MySQL and transactions |
+| `/docs/database` | `database.md` | MySQL database primitives |
 | `/docs/database-migrations` | `database-migrations.md` | Migration CLI and migration files |
 
-### Runtime and Infrastructure
+### Runtime & Infrastructure
 
-| Website route | Source file | Description |
+| Website route | Markdown source | Purpose |
 | --- | --- | --- |
-| `/docs/middleware` | `middleware.md` | Middleware System v2 and v1 compatibility |
-| `/docs/hydration` | `hydration.md` | SSR/client transform parity, deterministic rendering and Windows line endings |
-| `/docs/developer-tools` | `developer-tools.md` | `bcp doctor`, `bcp inspect` and JSON diagnostics |
-| `/docs/development-logging` | `development-logging.md` | Structured logging, request identity and development observability |
+| `/docs/middleware` | `middleware.md` | Middleware System v2 |
+| `/docs/hydration` | `hydration.md` | SSR/client hydration parity |
+| `/docs/developer-tools` | `developer-tools.md` | `doctor` and `inspect` diagnostics |
+| `/docs/development-logging` | `development-logging.md` | Structured logging and observability |
 | `/docs/caching` | `caching.md` | Cache and revalidation |
-| `/docs/security` | `security.md` | Framework security defaults |
+| `/docs/security` | `security.md` | Security defaults and request body limits |
 
-### Releases
+## API Reference grouping
 
-Use the files under `docs/releases/` for release pages.
+`bcp-docs-web` can derive an API-reference navigation layer from the authored guides.
 
-Recommended route format:
+Recommended entrypoint groups:
 
 ```text
-/releases/0.1.21
-/releases/0.1.22
-/releases/0.1.23
+bcp
+bcp/server
+bcp/auth
+bcp/database
+bcp/validation
+bcp/error
+bcp/cache
+bcp/config
+bcp/middleware
 ```
 
-The newest release should also be available from `/releases`.
+The first version of the website does not need generated TypeDoc-style reference pages. It can begin by linking APIs to the guide that owns them, then add generated symbol-level reference later if useful.
 
-## Homepage content for bcp-docs
+Suggested ownership:
 
-The documentation homepage should describe BCP as a React full-stack framework and highlight the currently implemented capabilities.
+| Entrypoint | Primary guide |
+| --- | --- |
+| `bcp` | `routing.md`, `server-data-loaders.md`, `form-actions.md` |
+| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `development-logging.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` |
 
-Recommended feature groups:
+## Current capability groups
 
 ### Application
 
-- File-based routing
-- React SSR
+- React SSR and hydration
+- file-based page/API routing
+- dynamic routes
+- catch-all and optional catch-all routes
+- route groups
+- layouts and metadata
 - SPA navigation
-- Persistent layouts
-- Loading and error UI
-- API routes
-- Client islands / partial hydration
-- Deterministic development hydration across server/client transform pipelines
-- LF/CRLF-safe development source handling
-
-### Server data and mutations
-
-- Server data loaders
-- Route guards
-- Form actions
-- Request-scoped server APIs
-- Cookies and redirects
-- `bcp/validation`
-- Typed form/API validation
-- Field and form error output
-- `bcp/error`
-- Structured HTTP error responses
-- Safe unknown-error fallback responses
+- server data loaders
+- route guards
+- form actions
+- client islands / partial hydration
+- Fast Refresh
+- deterministic development hydration
+
+### Server
+
+- request-scoped server APIs
+- request IDs
+- cookies and redirects
+- JWT sessions
+- authentication helpers
+- Middleware System v2
+- typed validation
+- structured errors
+- structured logging
+- multipart file uploads
+- upload validation
+- storage adapter contract
+- local filesystem storage adapter
+- production file delivery
+- validators and byte ranges
 
 ### Database
 
 - `bcp/database`
-- Lazy MySQL connection pool
-- Queries and prepared execution
-- Transactions
-- Database migrations
-- Migration status and rollback
-
-### Authentication
+- lazy MySQL pool
+- prepared execution
+- query helpers
+- transactions
+- migrations
+- migration status
+- rollback
 
-- `bcp/auth`
-- JWT cookie sessions
-- Typed users and session data
-- Session rotation
-- `requireAuth()`
-- `requireRole()`
-- Auth-aware route guards
-
-### Middleware
-
-- Middleware System v2
-- Middleware chains
-- Real `await next()` downstream execution
-- Before/after response interception
-- Shared request context state
-- Matchers
-- Rewrite and redirect
-- Backward-compatible Middleware v1 handlers
-
-### Production and DX
+### Developer Experience
 
 - `create-bcp-app`
-- Interactive project setup
-- Tailwind preset
-- Database/auth presets
 - `bcp update`
-- `bcp doctor` project/runtime diagnostics
-- `bcp inspect` environment/config/route inspection
-- JSON developer-tool output for CI/automation
-- Duplicate React and duplicate BCP installation diagnostics
+- `bcp doctor`
+- `bcp inspect`
+- route inspection
 - `bcp-framework` Windows-safe CLI alias
-- Structured server logger
-- Request-scoped loggers with request identity
-- Pretty and JSON log formats
-- Configurable log levels
-- Structured development HTTP/SSR timing events
-- Standalone production builds
-- Critical CSS
-- Cache/revalidation
-- Security defaults
-- Unit/integration/E2E/package smoke testing in the framework repository
-
-## Suggested homepage hero
+- standalone production build
+- unit/integration/E2E/package tests
+- release/package smoke checks
 
-Suggested content, not a required exact copy:
+## BCP 0.1.25 documentation focus
 
-```text
-BCP Framework
-A React full-stack framework for building server-rendered applications with routing,
-data loading, server mutations, authentication, databases, validation, structured errors,
-middleware, observability and production tooling.
-```
+### Storage adapters
 
-Primary actions:
+BCP `0.1.25` introduces the first application-facing storage abstraction through `bcp/server`:
 
-```text
-Get Started
-Read the Docs
-View on GitHub
+```ts
+import {
+    createLocalStorage,
+    createStorageResponse,
+    normalizeStorageKey,
+    StorageError,
+    storeUploadedFile,
+} from "bcp/server";
 ```
 
-The website may display the current release version from project metadata instead of hard-coding it in multiple UI files.
+The documentation must make these boundaries clear:
 
-## Suggested documentation sidebar
+- `StorageAdapter` is the application-facing contract.
+- `createLocalStorage()` is the built-in adapter in this milestone.
+- storage keys are logical relative paths, not operating-system paths.
+- absolute paths and traversal segments are rejected.
+- overwrite is opt-in.
+- local metadata persists content type and SHA-256 identity.
+- `createStorageResponse()` supports `GET` and `HEAD`.
+- validators include ETag and Last-Modified behavior.
+- single byte ranges are supported.
+- multiple ranges are intentionally unsupported in `0.1.25` and return `416`.
+- the default cache policy is private/revalidate.
+- public caching must be explicit.
+- storage keys do not replace authentication or authorization.
 
-```text
-Getting Started
-  Introduction
-  Installation
-  Project Structure
-  Configuration
-  Updating
-
-Core
-  Routing
-  Application Modules
-  Server Request APIs
-  Server Data Loaders
-  Route Guards
-  Form Actions
-  Validation
-  Error Handling
-
-Authentication
-  Authentication Core
-  Auth Route Guards
-  JWT Sessions
-
-Database
-  Database
-  Migrations
-
-Runtime
-  Middleware
-  Hydration
-  Developer Tools
-  Logging & Observability
-  Caching
-  Security
-
-Production
-  Deployment
-
-Releases
-  0.1.23
-  0.1.22
-  0.1.21
-```
+See `storage.md`.
 
-## Suggested documentation page layout
+### File Upload
 
-Each documentation page should support:
+BCP `0.1.24` introduced:
 
-- title
-- short summary
-- previous/next page navigation
-- table of contents generated from headings
-- syntax-highlighted code blocks
-- copy-code button
-- deep links to headings
-- responsive sidebar
-- mobile navigation
-- light/dark appearance
-- framework version label
-- link to the corresponding source Markdown file in GitHub
+- multipart parsing,
+- request/file size limits,
+- MIME allowlists,
+- extension allowlists,
+- required/optional file fields,
+- safe local file names,
+- traversal protection,
+- overwrite protection,
+- SHA-256 metadata.
 
-Optional later additions:
+Those APIs remain supported in `0.1.25`.
 
-- documentation search
-- version selector
-- API symbol index
-- interactive examples
-- edit-on-GitHub links
+`storeUploadedFile()` is the bridge between a validated multipart `File` and a `StorageAdapter`.
 
-## Code examples
+See:
 
-Examples should use the public package entrypoints that application developers actually install.
+- `file-upload.md`
+- `storage.md`
 
-Preferred:
+### Production auth guard stabilization
 
-```ts
-import {
-    auth,
-    requireAuth,
-} from "bcp/auth";
+The `0.1.24` stabilization cycle unified standalone guard/action authentication imports with the active request-context runtime.
 
-import {
-    db,
-} from "bcp/database";
+This prevents production-only failures where APIs such as `cookies()`, `getSession()`, `requireAuth()` or `requireRole()` could see a different request-context instance after bundling.
 
-import {
-    v,
-    validateFormData,
-} from "bcp/validation";
+### Development route graph synchronization
 
-import {
-    badRequest,
-    unauthorized,
-} from "bcp/error";
+The `0.1.24` stabilization cycle also fixed a development graph drift where the route scanner could see a new route while the incremental client bundle graph still represented the previous topology.
 
-import {
-    logger,
-    requestLogger,
-} from "bcp/server";
+The development gateway now compares the actual page route graph and refreshes the internal client bundler when pathname/page/layout topology changes.
 
-import {
-    type MiddlewarePipelineHandler,
-} from "bcp/middleware";
-```
+### Logging and observability
 
-Avoid documenting internal monorepo imports such as:
+BCP `0.1.23` introduced:
 
-```text
-packages/server/src/...
-packages/client/src/...
-```
+- `logger`,
+- `createLogger()`,
+- request-scoped `requestLogger()`,
+- log levels,
+- pretty/JSON formats,
+- request IDs,
+- structured development request logging,
+- SSR/import debug timing.
 
-unless a page is explicitly explaining framework internals.
+See `development-logging.md`.
 
-## Version labels
+### Developer tools
 
-The website should distinguish:
+BCP `0.1.22` introduced:
 
-- current stable npm version
-- documentation target version
-- unreleased/main documentation if it is shown
+- `bcp doctor`,
+- `bcp inspect`,
+- JSON diagnostic output,
+- duplicate React detection,
+- duplicate BCP installation protection,
+- Windows-safe `bcp-framework` CLI alias.
 
-Do not label unreleased `main` behavior as already available from npm until the corresponding package has been published.
+See `developer-tools.md`.
 
-## Framework commands to document
+## CLI commands
 
 ```bash
 bcp dev
@@ -335,135 +306,163 @@ bcp db status
 bcp db rollback
 ```
 
-On Windows systems where Microsoft SQL Server owns the `bcp` executable name, document the equivalent collision-free commands with `bcp-framework`.
-
-Project creation:
+On Windows systems where Microsoft SQL Server owns `bcp.exe`, direct project-local commands should prefer:
 
-```bash
-npx create-bcp-app@latest my-app
+```powershell
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+npm exec -- bcp-framework dev
+npm exec -- bcp-framework build
 ```
 
-## Middleware v2 documentation priority
+Inside npm scripts, `bcp` remains safe because npm prepends `node_modules/.bin` to `PATH`.
 
-BCP 0.1.18 introduced a meaningful middleware architecture change, so the `bcp-docs` website should make the distinction between v1 and v2 clear.
+## Release documentation
 
-The middleware page should prominently explain:
+Release notes live under:
 
 ```text
-v1 next()        = return a pass-through instruction
-v2 await next()  = execute downstream middleware/application and receive Response
+docs/releases/
 ```
 
-Existing v1 code remains supported, so migration documentation should describe v2 as an additive upgrade rather than a mandatory rewrite.
+Recommended website release routes:
 
-See `middleware.md` for the full API and examples.
+```text
+/releases/0.1.25
+/releases/0.1.24
+/releases/0.1.23
+/releases/0.1.22
+/releases/0.1.21
+/releases/0.1.20
+```
 
-## Validation documentation priority
+The website should display a clear release state for each version:
 
-BCP 0.1.19 introduced the public `bcp/validation` entrypoint. The docs website should show validation in both form-action and API-route examples.
+```text
+published
+release candidate
+unreleased development target
+```
 
-Important concepts to surface:
+Do not infer publication state only from the existence of a Markdown release note.
 
-- `v.object`, `v.string`, `v.number`, `v.boolean`, `v.array`
-- FormData coercion with `validateFormData()`
-- `success/data` versus `issues/fieldErrors/formErrors`
-- object fields are stripped unless `allowUnknown: true`
-- `refine()` for custom application rules
-- no external validation dependency is required
+## Suggested `bcp-docs-web` content model
 
-See `validation.md` for the complete API and examples.
+A future website can represent each Markdown page with metadata similar to:
 
-## Error Handling documentation priority
+```ts
+interface DocPage {
+    title: string;
+    slug: string;
+    section: string;
+    sourceFile: string;
+    versionTarget?: string;
+    releaseState?:
+        | "published"
+        | "rc"
+        | "unreleased";
+}
+```
 
-BCP 0.1.20 introduced the public `bcp/error` entrypoint and a standard HTTP error envelope.
+The metadata does not need to live in frontmatter immediately. The first implementation can use a route manifest in the docs website and consume Markdown files directly.
 
-The docs website should clearly distinguish:
+## Suggested website features
 
-```text
-notFound()          = activate page 404 UI behavior
-notFoundResponse()  = return a JSON 404 HTTP response
-```
+The first useful version of `bcp-docs-web` should prioritize:
 
-Important concepts to surface:
+1. Sidebar navigation generated from the route/source map.
+2. Markdown rendering with syntax highlighting.
+3. Previous/next page navigation.
+4. Version/development-target banner.
+5. Release note pages.
+6. Search across Markdown content.
+7. Copy buttons for code blocks.
+8. Mobile navigation.
+9. Direct GitHub source/edit links.
 
-- `HttpError` and `createHttpError()`
-- `errorResponse()` for any 4xx/5xx status
-- `toErrorResponse()` for safe catch boundaries
-- `badRequest()`, `unauthorized()`, `forbidden()`, `conflict()` and other convenience helpers
-- standard `{ error: { status, code, message, details? } }` payload
-- error responses default to `Cache-Control: no-store`
-- unknown exceptions become a generic 500 response without exposing the original exception message
-- normal field validation still belongs to `bcp/validation`
+Later additions can include:
 
-See `error-handling.md` for the complete API and examples.
+- generated API symbol reference,
+- versioned documentation snapshots,
+- interactive examples,
+- framework playgrounds,
+- release comparison pages.
 
-## Hydration documentation priority
+## Source conventions
 
-BCP 0.1.20 added line-ending normalization for the development React Refresh path. That removed the Windows `CRLF` versus `LF` mismatch, but a second issue remained when Babel compiled multiline quoted JSX attributes and collapsed their whitespace differently from SSR.
+For documentation intended for the website:
 
-BCP 0.1.21 completes this fix by keeping Babel responsible for TypeScript removal and React Refresh instrumentation while leaving JSX untransformed. esbuild then performs the development JSX transform with the development JSX runtime enabled.
+- use one H1 per source page,
+- keep heading hierarchy stable,
+- use fenced code blocks with language tags,
+- use relative repository links for other docs,
+- keep API names exactly aligned with public exports,
+- distinguish current behavior from roadmap plans,
+- include security limitations next to the API they affect,
+- prefer runnable examples over pseudo APIs,
+- avoid documenting private/internal modules as public APIs.
 
-The docs website should make these points clear:
+## Stable vs development documentation
 
-- multiline quoted JSX attributes are supported,
-- multiline template-literal JSX expressions are supported,
-- developers should not need to rewrite multiline `className` values as one-line strings to avoid framework hydration warnings,
-- `CRLF` and standalone `CR` source line endings are normalized to `LF` before development instrumentation,
-- React Refresh instrumentation must not change the semantic value of JSX attributes,
-- the framework fix does not suppress genuine hydration mismatches caused by random values, locale differences, browser-only initial branches, changing external data or invalid HTML,
-- `suppressHydrationWarning` is not a general-purpose solution.
+`main` can contain documentation for the next release before npm publication.
 
-See `hydration.md` for the full explanation, transform pipeline and troubleshooting steps.
+Therefore the website must distinguish:
 
-## Developer Tools documentation priority
+```text
+Documentation target != necessarily current npm stable version
+```
 
-BCP 0.1.22 adds `bcp doctor` and `bcp inspect` as the first dedicated developer-diagnostics commands.
+For example, while `0.1.25` is under release validation, `docs/storage.md` can describe the `0.1.25` development target, but the website should not label it as published until the release is actually available.
 
-The docs website should surface:
+## Release validation
 
-- PASS/WARN/FAIL health checks,
-- non-zero exit codes for blocking doctor failures,
-- React / React DOM version and package-root parity,
-- duplicate `bcp` / `@chidchanun/bcp` installation detection,
-- config and development environment inspection,
-- page/API route summaries,
-- `--json` output for CI and automation,
-- the recommendation to verify local releases from packed `.tgz` artifacts installed under the existing `bcp` dependency key rather than linked staging directories.
+Before publishing a framework release:
 
-See `developer-tools.md` for the full command reference.
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
 
-## Logging and observability documentation priority
+Release validation should include packed-package smoke verification and representative production application testing.
 
-BCP 0.1.23 adds the structured logging foundation through `bcp/server`.
+## Documentation QA checklist
 
-The docs website should surface:
+Before a docs release or website sync:
 
-- `logger.debug/info/warn/error`,
-- `createLogger()` and child loggers,
-- `requestLogger()` and its request ID/method/path bindings,
-- `attachRequestId()` for `X-Request-Id` response propagation,
-- `BCP_LOG_LEVEL`,
-- `BCP_LOG_FORMAT=pretty|json`,
-- JSON-safe `Error`, `bigint` and circular value handling,
-- structured `http.request`, `module.import` and `ssr.render` development events,
-- the existing dev noise filter for framework-internal requests.
+- all linked Markdown files exist,
+- examples use public exports,
+- version numbers are current,
+- unreleased features are labeled correctly,
+- Windows CLI instructions use the safe alias where needed,
+- security caveats are present for uploads/storage/authentication,
+- route names match the current router,
+- release notes match the framework version,
+- no generated `.bcp-framework` paths are presented as user-authored source files.
 
-See `development-logging.md` for the complete API and examples.
+## Roadmap
 
-## Release roadmap
+After `0.1.25`, the current planned framework direction is:
 
-`0.1.23` is the Logging & Observability milestone. The next planned milestone is `0.1.24` — File Upload foundation, followed by Background Jobs, Testing Utilities, Production Build Hardening and Plugin Architecture unless milestones are regrouped.
+1. S3-compatible / cloud storage integration.
+2. Production upload streaming.
+3. Broader storage adapter ecosystem.
+4. Additional production hardening.
 
-## Release workflow for documentation
+These are roadmap items, not published API guarantees.
 
-Before publishing a new BCP release:
+## Repository authority
 
-```bash
-npm run typecheck
-npm run test:unit
-npm run rc:check
-```
+The framework repository remains authoritative for:
 
-After npm publication, the docs website can update its displayed stable version.
+```text
+source
+public exports
+tests
+docs
+release notes
+```
 
-The framework repository remains authoritative for API correctness; `bcp-docs` is the presentation layer for that content.
+`bcp-docs-web` should be treated as the presentation/search/navigation layer for this content rather than a competing documentation source.