docs: add CLAUDE.md files for AI-assisted development

CLAUDE.md

@@ -0,0 +1,60 @@
+# Fluid Framework
+
+Distributed real-time collaborative web application framework using JavaScript/TypeScript.
+
+## Build System
+
+- Uses **pnpm** as package manager (required)
+- Enable corepack: `corepack enable`
+- Install dependencies: `pnpm install`
+- Build all: `pnpm build`
+- Build specific package: `pnpm build --filter @fluidframework/<package-name>`
+
+## Commands
+
+- `pnpm build` - Build all packages
+- `pnpm test` - Run tests across all packages
+- `pnpm lint` - Run linting
+- `pnpm lint:fix` - Fix linting issues
+- `pnpm format` - Format code with Biome
+- `pnpm clean` - Clean build artifacts
+
+## Workspace Structure
+
+This is a pnpm monorepo with multiple release groups:
+
+- **packages/**: Core Fluid Framework packages (`@fluidframework/*`)
+  - `common/` - Shared interfaces and utilities
+  - `dds/` - Distributed Data Structures
+  - `drivers/` - Service drivers
+  - `framework/` - Framework components
+  - `loader/` - Container loading
+  - `runtime/` - Runtime components
+  - `service-clients/` - Service client implementations
+  - `test/` - Test utilities
+  - `tools/` - Developer tools
+  - `utils/` - Shared utilities
+- **experimental/**: Experimental packages (`@fluid-experimental/*`)
+- **examples/**: Example applications (`@fluid-example/*`, not published)
+- **azure/packages/**: Azure-specific packages
+- **tools/**: Build and development tools
+
+## Code Style
+
+- TypeScript with strict mode
+- ESLint for linting
+- Biome for formatting
+- API Extractor for API documentation and release tags
+
+## Testing
+
+- Uses Mocha for most packages
+- Use `pnpm test` in package directory
+- Coverage via c8: `pnpm test:coverage`
+
+## Key Conventions
+
+- Package exports use release tags: `/public`, `/beta`, `/alpha`, `/legacy`, `/internal`
+- Dual ESM/CJS builds (lib/ for ESM, dist/ for CJS)
+- Use `workspace:~` for internal dependencies
+- Follow conventional commits for commit messages

azure/packages/azure-local-service/CLAUDE.md

@@ -0,0 +1,32 @@
+# @fluidframework/azure-local-service
+
+Local implementation of the Azure Fluid Relay service for testing/development use. This is a thin wrapper around `tinylicious`.
+
+## Build
+
+This package has no build step - it's a simple JavaScript entry point.
+
+- `pnpm clean` - Remove generated files
+
+## Run
+
+- `pnpm start` - Start the local service using pm2
+- `pnpm start:debug` - Start with Node.js inspector enabled (port 9229)
+- `pnpm stop` - Stop the pm2-managed service
+
+## Lint
+
+- `pnpm lint` - Run all linting
+- `pnpm lint:fix` - Auto-fix lint issues
+- `pnpm check:format` - Check formatting with Biome
+
+## Key Files
+
+- `index.js` - Entry point that imports and runs tinylicious
+
+## Notes
+
+- This package wraps `tinylicious` to provide a local Azure Fluid Relay-compatible service
+- Uses pm2 for process management in production mode
+- No tests are defined for this package
+- Type validation is disabled

azure/packages/azure-service-utils/CLAUDE.md

@@ -0,0 +1,36 @@
+# @fluidframework/azure-service-utils
+
+Helper service-side utilities for connecting to Azure Fluid Relay service. Provides token generation utilities for backend APIs.
+
+## Build
+
+- `pnpm build` - Full build (compile + API reports)
+- `pnpm build:compile` - Compile TypeScript only
+- `pnpm build:esnext` - Build ESM output to `lib/`
+- `pnpm tsc` - Build CommonJS output to `dist/`
+- `pnpm clean` - Remove generated files
+
+## Lint
+
+- `pnpm lint` - Run all linting
+- `pnpm lint:fix` - Auto-fix lint issues
+- `pnpm check:format` - Check formatting with Biome
+
+## API Reports
+
+- `pnpm build:api-reports` - Generate API reports
+- `pnpm api` - Run API extractor
+
+## Key Files
+
+- `src/index.ts` - Main entry point, exports `generateToken` and types
+- `src/generateToken.ts` - Token generation logic using jsrsasign
+- Dual CJS/ESM output with multiple export paths (public, legacy, internal)
+
+## Notes
+
+- Primary export is `generateToken` for creating Azure Fluid Relay tokens
+- Uses `jsrsasign` for JWT token generation
+- Exports are tiered: public (default), legacy, and internal
+- No tests are currently defined
+- Type validation uses the "legacy" entrypoint

common/build/eslint-config-fluid/CLAUDE.md

@@ -0,0 +1,37 @@
+# @fluidframework/eslint-config-fluid
+
+Shareable ESLint config for the Fluid Framework. Provides multiple configuration presets for consistent linting across Fluid packages.
+
+## Build
+
+- `pnpm build` - Print configs and run prettier check
+- `pnpm print-configs` - Generate printed config files to `printed-configs/`
+- `pnpm clean` - Remove dist and build logs
+
+## Format
+
+- `pnpm format` - Format code with prettier
+- `pnpm prettier` - Check formatting without fixing
+- `pnpm prettier:fix` - Fix formatting issues
+
+## Test
+
+- No tests currently implemented
+
+## Key Files
+
+- `index.js` - Main entry point
+- `base.js` - Base ESLint configuration
+- `recommended.js` - Recommended rules configuration
+- `strict.js` - Strict rules configuration
+- `strict-biome.js` - Strict config with Biome compatibility
+- `flat.mts` - Flat config format (ESLint 9+)
+- `minimal-deprecated.js` - Minimal/deprecated rules configuration
+- `scripts/print-configs.ts` - Script to generate printed config output
+
+## Notes
+
+- This is a private package (not published to npm)
+- Uses ESLint 9 flat config format via `flat.mts`
+- The `print-configs` script outputs expanded configs to `printed-configs/` for debugging
+- Integrates multiple ESLint plugins: TypeScript, import-x, jsdoc, unicorn, react, and more

examples/apps/blobs/CLAUDE.md

@@ -0,0 +1,34 @@
+# @fluid-example/blobs
+
+Example of using blobs in Fluid Framework.
+
+## Build
+
+- `pnpm build` - Build the package
+- `pnpm build:esnext` - TypeScript compilation only
+- `pnpm clean` - Remove build artifacts
+
+## Run
+
+- `pnpm start` - Start with Tinylicious (t9s) service
+- `pnpm start:local` - Start with local service
+- `pnpm start:t9s` - Start with Tinylicious service
+- `pnpm start:odsp` - Start with ODSP service
+
+## Test
+
+- `pnpm test` - Run Jest tests with Puppeteer
+- `pnpm test:jest:verbose` - Run tests with verbose output
+
+## Lint
+
+- `pnpm lint` - Run linting
+- `pnpm lint:fix` - Fix lint issues
+- `pnpm format` - Format code with Biome
+
+## Notes
+
+- This is a private example application (not published to npm)
+- Uses React for UI rendering
+- Demonstrates blob handling with SharedMap
+- Webpack-based build with multiple service configurations

examples/apps/collaborative-textarea/CLAUDE.md

@@ -0,0 +1,32 @@
+# @fluid-example/collaborative-textarea
+
+A minimal example using the React collaborative-textarea component.
+
+## Build
+
+- `pnpm build` - Build the package
+- `pnpm build:esnext` - TypeScript compilation only
+- `pnpm clean` - Remove build artifacts
+
+## Run
+
+- `pnpm start` - Start the webpack dev server
+- `pnpm start:test` - Start with test configuration
+
+## Test
+
+- `pnpm test` - Run Jest tests with Puppeteer
+- `pnpm test:jest:verbose` - Run tests with verbose output
+
+## Lint
+
+- `pnpm lint` - Run linting
+- `pnpm lint:fix` - Fix lint issues
+- `pnpm format` - Format code with Biome
+
+## Notes
+
+- This is a private example application (not published to npm)
+- Uses React for UI and @fluidframework/sequence for collaborative text
+- Demonstrates real-time collaborative text editing
+- Built with @fluidframework/aqueduct DataObject pattern

examples/apps/contact-collection/CLAUDE.md

@@ -0,0 +1,32 @@
+# @fluid-example/contact-collection
+
+Example of using a Fluid Object as a collection of items.
+
+## Build
+
+- `pnpm build` - Build the package
+- `pnpm build:esnext` - TypeScript compilation only
+- `pnpm clean` - Remove build artifacts
+
+## Run
+
+- `pnpm start` - Start the webpack dev server
+- `pnpm start:test` - Start with test configuration
+
+## Test
+
+- `pnpm test` - Run Jest tests with Puppeteer
+- `pnpm test:jest:verbose` - Run tests with verbose output
+
+## Lint
+
+- `pnpm lint` - Run linting
+- `pnpm lint:fix` - Fix lint issues
+- `pnpm format` - Format code with Biome
+
+## Notes
+
+- This is a private example application (not published to npm)
+- Uses React for UI rendering
+- Demonstrates managing a collection of contact items with Fluid
+- Built with @fluidframework/aqueduct DataObject pattern

examples/apps/data-object-grid/CLAUDE.md

@@ -0,0 +1,34 @@
+# @fluid-example/data-object-grid
+
+Data object grid creates child data objects from a registry and lays them out in a grid.
+
+## Build
+
+- `pnpm build` - Build the package
+- `pnpm build:esnext` - TypeScript compilation only
+- `pnpm build:copy` - Copy CSS files to lib
+- `pnpm clean` - Remove build artifacts
+
+## Run
+
+- `pnpm start` - Start the webpack dev server
+- `pnpm start:test` - Start with test configuration
+- `pnpm dev` - Run webpack in development mode
+
+## Test
+
+- `pnpm test` - Run Jest tests with Puppeteer
+- `pnpm test:jest:verbose` - Run tests with verbose output
+
+## Lint
+
+- `pnpm lint` - Run linting
+- `pnpm lint:fix` - Fix lint issues
+- `pnpm format` - Format code with Biome
+
+## Notes
+
+- This is a private example application (not published to npm)
+- Uses Fluent UI React components and react-grid-layout
+- Demonstrates composing multiple Fluid examples (clicker, codemirror, prosemirror, etc.)
+- Built with @fluidframework/aqueduct DataObject pattern

examples/apps/diceroller/CLAUDE.md

@@ -0,0 +1,34 @@
+# @fluid-example/diceroller
+
+Minimal Fluid Container and Object sample to implement a collaborative dice roller.
+
+## Build
+
+- `pnpm build` - Build the package
+- `pnpm build:esnext` - TypeScript compilation only
+- `pnpm clean` - Remove build artifacts
+
+## Run
+
+- `pnpm start` - Start with Tinylicious (t9s) service
+- `pnpm start:local` - Start with local service
+- `pnpm start:t9s` - Start with Tinylicious service
+- `pnpm start:odsp` - Start with ODSP service
+
+## Test
+
+- `pnpm test` - Run Jest tests with Puppeteer
+- `pnpm test:jest:verbose` - Run tests with verbose output
+
+## Lint
+
+- `pnpm lint` - Run linting
+- `pnpm lint:fix` - Fix lint issues
+- `pnpm format` - Format code with Biome
+
+## Notes
+
+- This is a private example application (not published to npm)
+- Uses React for UI and @fluidframework/map for shared state
+- Minimal example demonstrating basic Fluid Framework usage
+- Supports multiple service backends (local, t9s, ODSP)

examples/apps/presence-tracker/CLAUDE.md

@@ -0,0 +1,34 @@
+# @fluid-example/presence-tracker
+
+Example application that tracks page focus and mouse position using the Fluid Framework presence features.
+
+## Build
+
+- `pnpm build` - Build the package
+- `pnpm build:esnext` - TypeScript compilation only
+- `pnpm clean` - Remove build artifacts
+
+## Run
+
+- `pnpm start` - Start both Tinylicious server and client
+- `pnpm start:client` - Start only the webpack dev server
+- `pnpm start:tinylicious` - Start only the Tinylicious server
+
+## Test
+
+- `pnpm test` - Run Jest tests (starts Tinylicious automatically)
+- `pnpm test:jest:verbose` - Run tests with verbose output
+
+## Lint
+
+- `pnpm lint` - Run linting
+- `pnpm lint:fix` - Fix lint issues
+- `pnpm format` - Format code with Biome
+
+## Notes
+
+- This is a private example application (not published to npm)
+- Uses @fluidframework/presence for real-time presence tracking
+- Uses @fluidframework/tinylicious-client and fluid-framework
+- Requires Tinylicious server running on port 7070
+- Uses start-server-and-test for coordinated server/client startup