chore(env): add some instructions

.github/instructions/nx.instructions.md

@@ -4,7 +4,7 @@ applyTo: '**'
 
 // This file is automatically generated by Nx Console
 
-You are in an nx workspace using Nx 21.2.4 and pnpm as the package manager.
+You are in an nx workspace using Nx 21.3.1 and pnpm as the package manager.
 
 You have access to the Nx MCP server and the tools it provides. Use them. Follow these guidelines in order to best help the user:
 

CLAUDE.md

@@ -0,0 +1,161 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Trilium Notes is a hierarchical note-taking application with advanced features like synchronization, scripting, and rich text editing. It's built as a TypeScript monorepo using NX, with multiple applications and shared packages.
+
+## Development Commands
+
+### Setup
+- `pnpm install` - Install all dependencies
+- `corepack enable` - Enable pnpm if not available
+
+### Running Applications
+- `pnpm run server:start` - Start development server (http://localhost:8080)
+- `pnpm nx run server:serve` - Alternative server start command
+- `pnpm nx run desktop:serve` - Run desktop Electron app
+- `pnpm run server:start-prod` - Run server in production mode
+
+### Building
+- `pnpm nx build <project>` - Build specific project (server, client, desktop, etc.)
+- `pnpm run client:build` - Build client application
+- `pnpm run server:build` - Build server application
+- `pnpm run electron:build` - Build desktop application
+
+### Testing
+- `pnpm test:all` - Run all tests (parallel + sequential)
+- `pnpm test:parallel` - Run tests that can run in parallel
+- `pnpm test:sequential` - Run tests that must run sequentially (server, ckeditor5-mermaid, ckeditor5-math)
+- `pnpm nx test <project>` - Run tests for specific project
+- `pnpm coverage` - Generate coverage reports
+
+### Linting & Type Checking
+- `pnpm nx run <project>:lint` - Lint specific project
+- `pnpm nx run <project>:typecheck` - Type check specific project
+
+## Architecture Overview
+
+### Monorepo Structure
+- **apps/**: Runnable applications
+  - `client/` - Frontend application (shared by server and desktop)
+  - `server/` - Node.js server with web interface
+  - `desktop/` - Electron desktop application
+  - `web-clipper/` - Browser extension for saving web content
+  - Additional tools: `db-compare`, `dump-db`, `edit-docs`
+
+- **packages/**: Shared libraries
+  - `commons/` - Shared interfaces and utilities
+  - `ckeditor5/` - Custom rich text editor with Trilium-specific plugins
+  - `codemirror/` - Code editor customizations
+  - `highlightjs/` - Syntax highlighting
+  - Custom CKEditor plugins: `ckeditor5-admonition`, `ckeditor5-footnotes`, `ckeditor5-math`, `ckeditor5-mermaid`
+
+### Core Architecture Patterns
+
+#### Three-Layer Cache System
+- **Becca** (Backend Cache): Server-side entity cache (`apps/server/src/becca/`)
+- **Froca** (Frontend Cache): Client-side mirror of backend data (`apps/client/src/services/froca.ts`)
+- **Shaca** (Share Cache): Optimized cache for shared/published notes (`apps/server/src/share/`)
+
+#### Entity System
+Core entities are defined in `apps/server/src/becca/entities/`:
+- `BNote` - Notes with content and metadata
+- `BBranch` - Hierarchical relationships between notes (allows multiple parents)
+- `BAttribute` - Key-value metadata attached to notes
+- `BRevision` - Note version history
+- `BOption` - Application configuration
+
+#### Widget-Based UI
+Frontend uses a widget system (`apps/client/src/widgets/`):
+- `BasicWidget` - Base class for all UI components
+- `NoteContextAwareWidget` - Widgets that respond to note changes
+- `RightPanelWidget` - Widgets displayed in the right panel
+- Type-specific widgets in `type_widgets/` directory
+
+#### API Architecture
+- **Internal API**: REST endpoints in `apps/server/src/routes/api/`
+- **ETAPI**: External API for third-party integrations (`apps/server/src/etapi/`)
+- **WebSocket**: Real-time synchronization (`apps/server/src/services/ws.ts`)
+
+### Key Files for Understanding Architecture
+
+1. **Application Entry Points**:
+   - `apps/server/src/main.ts` - Server startup
+   - `apps/client/src/desktop.ts` - Client initialization
+
+2. **Core Services**:
+   - `apps/server/src/becca/becca.ts` - Backend data management
+   - `apps/client/src/services/froca.ts` - Frontend data synchronization
+   - `apps/server/src/services/backend_script_api.ts` - Scripting API
+
+3. **Database Schema**:
+   - `apps/server/src/assets/db/schema.sql` - Core database structure
+
+4. **Configuration**:
+   - `nx.json` - NX workspace configuration
+   - `package.json` - Project dependencies and scripts
+
+## Note Types and Features
+
+Trilium supports multiple note types, each with specialized widgets:
+- **Text**: Rich text with CKEditor5 (markdown import/export)
+- **Code**: Syntax-highlighted code editing with CodeMirror
+- **File**: Binary file attachments
+- **Image**: Image display with editing capabilities
+- **Canvas**: Drawing/diagramming with Excalidraw
+- **Mermaid**: Diagram generation
+- **Relation Map**: Visual note relationship mapping
+- **Web View**: Embedded web pages
+- **Doc/Book**: Hierarchical documentation structure
+
+## Development Guidelines
+
+### Testing Strategy
+- Server tests run sequentially due to shared database
+- Client tests can run in parallel
+- E2E tests use Playwright for both server and desktop apps
+- Build validation tests check artifact integrity
+
+### Scripting System
+Trilium provides powerful user scripting capabilities:
+- Frontend scripts run in browser context
+- Backend scripts run in Node.js context with full API access
+- Script API documentation available in `docs/Script API/`
+
+### Internationalization
+- Translation files in `apps/client/src/translations/`
+- Supported languages: English, German, Spanish, French, Romanian, Chinese
+
+### Security Considerations
+- Per-note encryption with granular protected sessions
+- CSRF protection for API endpoints
+- OpenID and TOTP authentication support
+- Sanitization of user-generated content
+
+## Common Development Tasks
+
+### Adding New Note Types
+1. Create widget in `apps/client/src/widgets/type_widgets/`
+2. Register in `apps/client/src/services/note_types.ts`
+3. Add backend handling in `apps/server/src/services/notes.ts`
+
+### Extending Search
+- Search expressions handled in `apps/server/src/services/search/`
+- Add new search operators in search context files
+
+### Custom CKEditor Plugins
+- Create new package in `packages/` following existing plugin structure
+- Register in `packages/ckeditor5/src/plugins.ts`
+
+### Database Migrations
+- Add migration scripts in `apps/server/src/migrations/`
+- Update schema in `apps/server/src/assets/db/schema.sql`
+
+## Build System Notes
+- Uses NX for monorepo management with build caching
+- Vite for fast development builds
+- ESBuild for production optimization
+- pnpm workspaces for dependency management
+- Docker support with multi-stage builds