update docs for release 0.8.x

CLAUDE.md

@@ -0,0 +1,132 @@
+# CLAUDE.md
+
+## Project purpose
+
+This repository is the documentation website for `@dfsync/client`.
+
+`@dfsync/client` is a Node.js and TypeScript HTTP client for service-to-service communication. It focuses on reliable backend HTTP calls with retry, auth, lifecycle hooks, request metadata, response validation, and structured errors.
+
+Package source:
+
+- https://github.com/dfsyncjs/dfsync/tree/main/packages/client
+
+Documentation website:
+
+- https://github.com/dfsyncjs/dfsyncjs.github.io
+
+## Source of truth
+
+Documentation must match the current release branch or PR in the `dfsync` monorepo.
+
+Before updating docs for a release, inspect the package source and tests instead of guessing behavior:
+
+- `packages/client/src/index.ts`
+- `packages/client/src/types/*`
+- `packages/client/src/errors/*`
+- `packages/client/src/core/request.ts`
+- `packages/client/src/core/should-retry.ts`
+- `packages/client/tests`
+
+If behavior is unclear, check the release branch or ask before documenting it.
+
+## Documentation structure
+
+Markdown docs live in:
+
+- `docs/<package-slug>/<version>/*.md`
+
+Current `@dfsync/client` docs live in:
+
+- `docs/client/v1/*.md`
+
+Docs are loaded by:
+
+- `src/content/docsContent.ts`
+
+Default docs constants are defined in:
+
+- `src/content/docsNavigation.ts`
+
+Package docs navigation and markdown imports are defined in `docsPackages` inside `src/content/docsContent.ts`.
+
+When adding a new markdown page, add it to the relevant package/version entry in `docsPackages` unless the page is intentionally hidden.
+
+The default docs package is `client`, so `#/docs` is treated as `@dfsync/client` documentation.
+
+Canonical docs URLs use:
+
+- `#/docs/<package-slug>/<version>/<page-slug>`
+
+For example:
+
+- `#/docs/client/v1/getting-started`
+
+## Current docs pages
+
+- Getting Started
+- Installation
+- Create Client
+- Response Handling
+- Auth
+- Hooks
+- Observability
+- Retry
+- Errors
+- Examples
+- API Reference
+
+## Important API concepts
+
+Keep these names and behaviors consistent across the docs:
+
+- `baseUrl`, never `baseURL`
+- `createClient`
+- `get`, `delete`, `post`, `put`, `patch`, `request`
+- auth strategies: `bearer`, `apiKey`, `custom`
+- retry config: `attempts`, `retryOn`, `retryMethods`, `backoff`, `baseDelayMs`
+- request metadata: `requestId`, `x-request-id`
+- idempotency: `idempotencyKey`, `idempotency-key`
+- response validation: `validateResponse`, `ResponseValidator`, `ValidationError`
+- hooks: `beforeRequest`, `afterResponse`, `onError`, `onRetry`
+- errors: `DfsyncError`, `HttpError`, `NetworkError`, `TimeoutError`, `ValidationError`, `RequestAbortedError`
+
+## Release docs checklist
+
+When preparing docs for a new `@dfsync/client` release:
+
+1. Compare the release branch against `main` in `packages/client`.
+2. Check public exports from `packages/client/src/index.ts`.
+3. Check public config, request, hook, and auth types.
+4. Check new or changed error classes.
+5. Check tests for behavioral rules.
+6. Update relevant docs pages.
+7. Update `docsPackages` in `docsContent.ts` if adding pages or packages.
+8. Run verification commands.
+
+## Adding another package
+
+When adding docs for another package:
+
+1. Create `docs/<package-slug>/<version>`.
+2. Add the package to `docsPackages` in `src/content/docsContent.ts`.
+3. Define package label, default version, default page slug, navigation, and markdown imports.
+4. Keep `client` as the default docs package unless the product direction changes.
+5. Verify package routes under `#/docs/<package-slug>/<version>/<page-slug>`.
+
+## Local commands
+
+```bash
+npm run dev
+npm run build
+npm run typecheck
+npm run lint
+npm run format:check
+```
+
+## Writing rules
+
+- Keep docs factual and implementation-aligned.
+- Prefer examples that compile against the real public API.
+- Do not document behavior unless it is confirmed by source or tests.
+- Keep examples focused on backend and service-to-service use cases.
+- Keep release notes and docs versioned around `@dfsync/client`, not the full monorepo.

README.md

@@ -1,73 +1,133 @@
-# React + TypeScript + Vite
+# dfsyncjs.github.io
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+Documentation website for [`@dfsync/client`](https://github.com/dfsyncjs/dfsync/tree/main/packages/client).
 
-Currently, two official plugins are available:
+`@dfsync/client` is a Node.js and TypeScript HTTP client for service-to-service communication. It provides retries, auth, lifecycle hooks, request metadata, response validation, and structured errors.
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+Website repository:
 
-## React Compiler
+- https://github.com/dfsyncjs/dfsyncjs.github.io
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+Package monorepo:
 
-## Expanding the ESLint configuration
+- https://github.com/dfsyncjs/dfsync
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+## Tech stack
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+- React
+- TypeScript
+- Vite
+- Material UI
+- React Router
+- `react-markdown` with `remark-gfm`
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+## Project structure
 
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-]);
+```text
+docs/<package>/<version>/        Markdown documentation content
+docs/client/v1/                  @dfsync/client v1 documentation
+src/content/docsContent.ts      Package docs registry and markdown import map
+src/content/docsNavigation.ts   Default docs package/version constants
+src/pages/Docs/                 Documentation page renderer
+src/components/                 Shared UI components
+src/services/analytics/         Analytics helpers
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x';
-import reactDom from 'eslint-plugin-react-dom';
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-]);
+## Documentation pages
+
+The current `v1` docs include:
+
+- Getting Started
+- Installation
+- Create Client
+- Response Handling
+- Auth
+- Hooks
+- Observability
+- Retry
+- Errors
+- Examples
+- API Reference
+
+`#/docs` is the default documentation entry point for `@dfsync/client`.
+
+Canonical documentation URLs use:
+
+```text
+#/docs/<package>/<version>/<page>
+```
+
+For example:
+
+```text
+#/docs/client/v1/getting-started
+```
+
+When adding a new markdown file under `docs/<package>/<version>`, also add it to the relevant package/version entry in:
+
+- `src/content/docsContent.ts`
+
+## Adding package docs
+
+To add documentation for another package:
+
+1. Create `docs/<package>/<version>`.
+2. Add the package to `docsPackages` in `src/content/docsContent.ts`.
+3. Define the package label, default version, default page, navigation, and markdown imports.
+4. Verify routes under `#/docs/<package>/<version>/<page>`.
+
+## Source of truth
+
+Docs should match the current `@dfsync/client` source in the monorepo:
+
+- `packages/client/src/index.ts`
+- `packages/client/src/types/*`
+- `packages/client/src/errors/*`
+- `packages/client/src/core/*`
+- `packages/client/tests`
+
+For release documentation, compare the release branch or PR against `main` before editing this site.
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Start the dev server:
+
+```bash
+npm run dev
+```
+
+Build for production:
+
+```bash
+npm run build
 ```
+
+Preview the production build:
+
+```bash
+npm run preview
+```
+
+## Verification
+
+Run these before opening or merging documentation changes:
+
+```bash
+npm run format:check
+npm run typecheck
+npm run lint
+npm run build
+```
+
+## Notes for docs updates
+
+- Use `baseUrl`, not `baseURL`.
+- Keep examples aligned with the public `@dfsync/client` API.
+- Do not document behavior unless it is confirmed by source or tests.
+- If a behavior is release-specific, check the active release branch or PR.