docs: add dedicated frontend docs section

Author: rockyshi1993

README.md

@@ -274,7 +274,7 @@ Production builds also write `dist/client/deploy-manifest.json` for CDN or stati
 
 For React hydration performance budgets, set fields such as `frontend.build.budgets.maxInitialJsBrotliBytes`, `maxRouteInitialJsBrotliBytes`, or `maxAppOwnedInitialJsBrotliBytes`. The default frontend i18n mode uses `frontend.i18n.clientLoad: "current"` so the browser loads only the SSR locale during hydration; use `"all"` only when a page needs no-reload locale switching. Advanced React CDN/import-map usage remains opt-in through `frontend.build.client.external` plus `externalRuntime`; React-related externals must provide runtime mappings.
 
-For the frontend user guide, start with [Frontend Overview](https://vextjs.github.io/frontend/overview), then continue through project structure, pages, data/API calls, layouts, styles/assets, i18n, error pages, configuration, build/deploy, and troubleshooting from the Frontend menu.
+For the frontend user guide, start with [Frontend Overview](https://vextjs.github.io/frontend/overview). The Frontend section has its own navigation for getting started, routing/pages, SSR, hydration, CSR fallback, render data cache, Fast Refresh, code splitting, static assets/CDN, performance budgets, configuration, and troubleshooting.
 
 When `frontend.apiClient` is enabled, Vext also emits `client-contract.json` and `api.generated.ts` next to the frontend output for tooling or advanced external frontend integrations. Normal page code does not need to hand-write route contracts; for first-screen data, prepare services in the route handler and pass props through `res.render()`.
 

changelogs/unreleased.md

@@ -3,6 +3,7 @@
 ## 2026-06-23
 
 - **Config profile selection** Added `--config <name>` and `VEXT_CONFIG=<name>` as the official way to select `src/config/{profile}.ts` for `vext start`, `vext dev`, `vext build`, and `vext deploy assets`; `vext start` now forces production runtime `NODE_ENV` while keeping legacy custom `NODE_ENV` profile fallback with a migration warning.
+- **Frontend documentation** Added the dedicated frontend documentation space with frontend-only navigation and updated the overview/status wording to describe current built-in frontend capabilities instead of an in-development target.
 
 ## 2026-06-22
 

website/docs/en/frontend/api-client-and-contracts.md

@@ -0,0 +1,58 @@
+# API Client and Contracts
+
+Vext pages do not need a generated API client for first-screen data. Use route handlers and `res.render()` for that.
+
+## Primary Data Path
+
+```text
+route handler -> app.services -> res.render(page, props)
+```
+
+This path keeps service calls server-side and produces SSR HTML with hydration data.
+
+## Generated Artifacts
+
+When `frontend.apiClient` is enabled, Vext can emit:
+
+```text
+client-contract.json
+api.generated.ts
+```
+
+These artifacts are useful for:
+
+- external frontend adapters
+- type probes
+- client-side API calls after hydration
+- documentation or tooling
+
+## Public Entry
+
+The frontend public entry exposes contract helpers:
+
+```ts
+import {
+  createVextApiClient,
+  createVextFetchAdapter,
+} from "vextjs/frontend";
+```
+
+Use them when you need a typed client boundary. Do not add them to simple pages just to read first-screen data.
+
+## Plain Fetch Is Fine
+
+For small client interactions after hydration:
+
+```ts
+await fetch("/api/preferences", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify(payload),
+});
+```
+
+Make sure client requests send the right `Accept` header so API calls are not treated as HTML navigation inside a SPA fallback scope.
+
+## Boundary Rule
+
+Generated client artifacts describe HTTP contracts. They do not make `src/services/**` browser-safe. Service modules remain server-only.

website/docs/en/frontend/boundaries-and-roadmap.md

@@ -0,0 +1,64 @@
+# Boundaries and Roadmap
+
+This page separates current frontend targets from future capability tracks.
+
+## Current Target
+
+The current Vext frontend direction is:
+
+- `src/frontend/**` as the user frontend source root
+- `src/routes/**` as URL and server data entry
+- `res.render(page, props?, options?)`
+- React 19 SSR plus hydration
+- nested layout chain
+- default error pages and `renderError()`
+- Vext JSCSS plus CSS/CSS Modules
+- frontend i18n with `useVextI18n(locale?)`
+- Fast Refresh and render refresh in development
+- esbuild-powered production build
+- route assets, code splitting, size reports, budgets, deploy manifest, SRI, and incremental static upload
+
+## Version Boundary
+
+This section documents the current frontend capability in the Vext documentation set. For an installed package version, use that version's release notes and changelog to check exactly which frontend features are available.
+
+## API-only Projects
+
+API-only projects remain first-class:
+
+```bash
+npx vextjs create my-api --template api --frontend none
+```
+
+Or disable frontend in config:
+
+```ts
+export default {
+  frontend: false,
+};
+```
+
+## External Frontend Adapters
+
+Vext can expose contracts for external frontend frameworks through `vextjs/frontend`, generated API artifacts, and stable HTTP boundaries. The default integrated experience remains Vext-owned full-stack React.
+
+## Future Tracks
+
+These are not first-phase commitments, but can be evaluated later:
+
+- React Server Components
+- Server Actions
+- streaming SSR
+- persistent client layout navigation
+- built-in image/font optimization components
+- deeper external framework adapters
+
+Each track needs separate requirements, performance evidence, and compatibility review before becoming default behavior.
+
+## Current Non-goals
+
+- hiding server imports in browser bundles
+- making page files create routes automatically
+- treating global SPA fallback as the default
+- uploading SSR HTML as a static asset by default
+- adding cloud-provider SDKs to core for asset upload

website/docs/en/frontend/build-and-deploy.md

@@ -0,0 +1,80 @@
+# Build and Deploy
+
+`vext build` compiles server output and frontend output in one command.
+
+## Output
+
+When frontend is enabled, production output includes:
+
+```text
+dist/
+  server/
+  client/
+    index.html
+    manifest.json
+    render-manifest.json
+    deploy-manifest.json
+    size-report.json
+    assets/
+```
+
+`vext start` serves the built client assets and uses `render-manifest.json` for SSR.
+
+## Build Command
+
+```bash
+vext build
+```
+
+To upload static assets after build:
+
+```bash
+vext build --upload-assets
+```
+
+Or run upload separately:
+
+```bash
+vext deploy assets --dry-run
+vext deploy assets
+```
+
+## Deploy Manifest
+
+`deploy-manifest.json` records static assets that can be uploaded:
+
+- JS and CSS assets
+- imported images/fonts/media
+- copied `public/**` files
+- content type
+- sha256
+- SRI for eligible assets
+- upload key and public URL
+
+HTML is not uploaded by default because SSR still belongs to the server runtime.
+
+## Incremental Upload
+
+The upload state file stores known sha256 values. Unchanged assets are skipped, so images and fonts are not uploaded again on every release.
+
+Keep `stateFile` outside the frontend outDir because build output is normally cleaned.
+
+## Configuration
+
+```ts
+frontend: {
+  deploy: {
+    assetBaseUrl: "https://cdn.example.com/my-app/",
+    integrity: true,
+    upload: {
+      enabled: true,
+      adapter: "filesystem",
+      targetDir: ".vext/frontend-cdn",
+      publicBaseUrl: "https://cdn.example.com/my-app/",
+      prefix: "my-app",
+      stateFile: ".vext/deploy/frontend-assets-state.json",
+      exclude: ["**/*.map"],
+    },
+  },
+}
+```