# Application and documentation coordination Maintain reader guides, migration instructions, and API references in [apps/docs](../apps/docs/README.md). VitePress and the application share the workspace lockfile and load interactive examples from the same workspace. Previous site content and history remain in [ray-template-doc](https://github.com/XiaoDaiGua-Ray/ray-template-doc). The site targets v6. Source links use monorepo paths, and release builds use `RAY_TEMPLATE_SOURCE_REF` to pin links to the release commit. Inline examples build against workspace source. See the [version boundary](../apps/docs/migration.md) for v5 source and release tags. | Area | Application evidence | Boundaries to explain | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Component entry points and TablePro | [Public exports](../apps/admin/src/components/index.ts), [TablePro contract](../packages/ui/src/RTablePro/README.md), [table examples](../apps/admin/src/views/demo/tables) | Deep `base/` and `pro/` paths are obsolete; `RTable` and `useTable` were removed. `useTablePro` retains registration-style usage and exposes `isReady` and current-page data access. Remote `total` counts filtered records. Cancellation depends on forwarding signal. Export and print default to visible data columns on the current page. | | Routing and permissions | [Routing guide](../apps/admin/src/router/README.md), [route types](../apps/admin/src/router/types.ts), [permission guards](../apps/admin/src/router/utils/permission.ts) | Menu visibility is not access authorization. Backends validate sessions and API permissions. Caching requires route names to match component names. Verify menu entry, direct access, and reload. | | Layout and Pinia | [Layout slots and preferences](../apps/admin/src/layout/README.md), [store conventions](../apps/admin/src/store/README.md) | Global UI singletons moved to `runtime` and are not persisted. Preserve historical settings and lock-screen formats. Custom content-slot integrations must retain request cancellation and route caching. | | Requests and mocks | [Axios implementation](../apps/admin/src/axios/instance.ts), [canceller](../packages/http/src/RequestCanceler.ts), [standard business API](../apps/admin/src/api/admin/index.ts) | Instances return the body on success and reject on failure. A caller-supplied signal disables default template signal injection. Development and static online demos share MSW HTTP mocks; disabling mocks connects directly to standard backend endpoints. | | Hooks, utilities, and icons | [Hook behavior](../apps/admin/src/hooks/README.md), [utility compatibility entry points](../apps/admin/src/utils/README.md), [icon generation](../packages/icons/src/A_README.md) | Keep public `@/hooks` and `@/utils` entry points. Migrate legacy bare icon names only at cache-read boundaries when the name is unique. Screenshot and print tests do not establish native browser acceptance. | | Toolchain and deployment | [Toolchain record](toolchain-upgrade.md), [architecture map](architecture.md), [Vite configuration](../vite.custom.config.ts) | Node/pnpm requirements come from manifests. The admin base is `/ray-template/`; bundled documentation uses `/ray-template/docs/`. The previously published site still uses `/ray-template-doc/`. | ## Update workflow 1. When application changes affect public imports, configuration, caching, or behavior, update the module notes and affected `apps/docs` pages/examples in the same change. Add breaking changes to the migration guide. 2. Display source from the running example. Lightweight examples live in `apps/docs/examples` and use public shared-package entry points. Examples needing application context embed `example.html`, with source references pointing to the actual admin demo page. Use the [documentation topic index](../harness/context/docs.md) to locate them. 3. Run relevant tests or scope checks for application changes. For documentation structure, links, code examples, or theme changes, run `pnpm harness verify docs`. Wording-only corrections need source and formatting checks. Reuse a completed check that includes `docs:check` if its relevant files have not changed since. 4. Select browser coverage using the [Harness impact dimensions](../harness/README.md#browser-verification). View the changed page when rendering structure or layout is at risk; exercise only the affected interactive example. Add navigation, search, legacy paths, themes, and narrow widths only when each is affected. For site themes, global navigation, or release acceptance, select representative pages for shared behavior. Maintainer documentation and wording-only reader-documentation corrections do not trigger browser checks. 5. Use `pnpm docs:preview` for documentation pages and lightweight examples. For changes to embedded admin examples, deployment bases, or combined output, use `pnpm pages:build` and the combined preview. Verify old and new live URLs separately for a site migration. ## Pending reader-guide updates Application evidence is available in the [routing integration guide](../apps/admin/src/router/README.md), [schema](../packages/api-contracts/src/routes.ts), [Segment notes](../packages/ui/src/RSegment/README.md), and [page design guide](ui-design.md). Add source switching, API examples, and version validation to `apps/docs/guide/routing.md`; document `fitContent` selection states and transitions in the component reference. Use updated login and management-page screenshots and check deployment subpaths. Update `guide/layout.md` for reduced motion and the floating exit button. Add visual and JSON entry points to `guide/routing.md`, making clear that applying visual configuration stores it only in the current browser. Explain in `reference/hooks/layout.md` that loading indicators are positioned relative to the visible content area. Update `guide/layout.md` for preference import/export in the settings drawer: JSON contains only drawer preferences, saves immediately after successful validation, and is independent of route-management JSON configuration.