docs(user): integrate server installation docs

docs/Developer Guide/Developer Guide/Architecture/API-Architecture.md

@@ -0,0 +1,900 @@
+# API-Architecture
+## API Architecture
+
+Trilium provides multiple API layers for different use cases: Internal API for frontend-backend communication, ETAPI for external integrations, and WebSocket for real-time synchronization. This document details each API layer's design, usage, and best practices.
+
+## API Layers Overview
+
+```
+graph TB
+    subgraph "Client Applications"
+        WebApp[Web Application]
+        Desktop[Desktop App]
+        Mobile[Mobile App]
+        External[External Apps]
+        Scripts[User Scripts]
+    end
+    
+    subgraph "API Layers"
+        Internal[Internal API<br/>REST + WebSocket]
+        ETAPI[ETAPI<br/>External API]
+        WS[WebSocket<br/>Real-time Sync]
+    end
+    
+    subgraph "Backend Services"
+        Routes[Route Handlers]
+        Services[Business Logic]
+        Becca[Becca Cache]
+        DB[(Database)]
+    end
+    
+    WebApp --> Internal
+    Desktop --> Internal
+    Mobile --> Internal
+    External --> ETAPI
+    Scripts --> ETAPI
+    
+    Internal --> Routes
+    ETAPI --> Routes
+    WS --> Services
+    
+    Routes --> Services
+    Services --> Becca
+    Becca --> DB
+    
+    style Internal fill:#e3f2fd
+    style ETAPI fill:#fff3e0
+    style WS fill:#f3e5f5
+```
+
+## Internal API
+
+**Location**: `/apps/server/src/routes/api/`
+
+The Internal API handles communication between Trilium's frontend and backend, providing full access to application functionality.
+
+### Architecture
+
+```typescript
+// Route structure
+/api/
+├── notes.ts           // Note operations
+├── branches.ts        // Branch management
+├── attributes.ts      // Attribute operations
+├── tree.ts           // Tree structure
+├── search.ts         // Search functionality
+├── sync.ts           // Synchronization
+├── options.ts        // Configuration
+└── special.ts        // Special operations
+```
+
+### Request/Response Pattern
+
+```typescript
+// Typical API endpoint structure
+router.get('/notes/:noteId', (req, res) => {
+    const note = becca.getNote(req.params.noteId);
+    
+    if (!note) {
+        return res.status(404).json({ 
+            error: 'Note not found' 
+        });
+    }
+    
+    res.json(note.getPojo());
+});
+
+router.put('/notes/:noteId', (req, res) => {
+    const note = becca.getNoteOrThrow(req.params.noteId);
+    
+    note.title = req.body.title;
+    note.content = req.body.content;
+    note.save();
+    
+    res.json({ success: true });
+});
+```
+
+### Key Endpoints
+
+#### Note Operations
+
+```typescript
+// Get note with content
+GET /api/notes/:noteId
+Response: {
+    noteId: string,
+    title: string,
+    type: string,
+    content: string,
+    dateCreated: string,
+    dateModified: string
+}
+
+// Update note
+PUT /api/notes/:noteId
+Body: {
+    title?: string,
+    content?: string,
+    type?: string,
+    mime?: string
+}
+
+// Create note
+POST /api/notes/:parentNoteId/children
+Body: {
+    title: string,
+    type: string,
+    content?: string,
+    position?: number
+}
+
+// Delete note
+DELETE /api/notes/:noteId
+```
+
+#### Tree Operations
+
+```typescript
+// Get tree structure
+GET /api/tree
+Query: {
+    subTreeNoteId?: string,
+    includeAttributes?: boolean
+}
+Response: {
+    notes: FNoteRow[],
+    branches: FBranchRow[],
+    attributes: FAttributeRow[]
+}
+
+// Move branch
+PUT /api/branches/:branchId/move
+Body: {
+    parentNoteId: string,
+    position: number
+}
+```
+
+#### Search Operations
+
+```typescript
+// Execute search
+GET /api/search
+Query: {
+    query: string,
+    fastSearch?: boolean,
+    includeArchivedNotes?: boolean,
+    ancestorNoteId?: string
+}
+Response: {
+    results: Array<{
+        noteId: string,
+        title: string,
+        path: string,
+        score: number
+    }>
+}
+```
+
+### Authentication & Security
+
+```typescript
+// CSRF protection
+app.use(csrfMiddleware);
+
+// Session authentication
+router.use((req, res, next) => {
+    if (!req.session.loggedIn) {
+        return res.status(401).json({ 
+            error: 'Not authenticated' 
+        });
+    }
+    next();
+});
+
+// Protected note access
+router.get('/notes/:noteId', (req, res) => {
+    const note = becca.getNote(req.params.noteId);
+    
+    if (note.isProtected && !protectedSessionService.isProtectedSessionAvailable()) {
+        return res.status(403).json({ 
+            error: 'Protected session required' 
+        });
+    }
+    
+    res.json(note.getPojo());
+});
+```
+
+## ETAPI (External API)
+
+**Location**: `/apps/server/src/etapi/`
+
+ETAPI provides a stable, versioned API for external applications and scripts to interact with Trilium.
+
+### Architecture
+
+```typescript
+// ETAPI structure
+/etapi/
+├── etapi.openapi.yaml    // OpenAPI specification
+├── auth.ts               // Authentication
+├── notes.ts              // Note endpoints
+├── branches.ts           // Branch endpoints
+├── attributes.ts         // Attribute endpoints
+├── attachments.ts        // Attachment endpoints
+└── special_notes.ts      // Special note operations
+```
+
+### Authentication
+
+ETAPI uses token-based authentication:
+
+```typescript
+// Creating ETAPI token
+POST /etapi/auth/login
+Body: {
+    username: string,
+    password: string
+}
+Response: {
+    authToken: string
+}
+
+// Using token in requests
+GET /etapi/notes/:noteId
+Headers: {
+    Authorization: "authToken"
+}
+```
+
+### Key Endpoints
+
+#### Note CRUD Operations
+
+```typescript
+// Create note
+POST /etapi/notes
+Body: {
+    noteId?: string,
+    parentNoteId: string,
+    title: string,
+    type: string,
+    content?: string,
+    position?: number
+}
+
+// Get note
+GET /etapi/notes/:noteId
+Response: {
+    noteId: string,
+    title: string,
+    type: string,
+    mime: string,
+    isProtected: boolean,
+    attributes: Array<{
+        attributeId: string,
+        type: string,
+        name: string,
+        value: string
+    }>,
+    parentNoteIds: string[],
+    childNoteIds: string[],
+    dateCreated: string,
+    dateModified: string
+}
+
+// Update note content
+PUT /etapi/notes/:noteId/content
+Body: string | Buffer
+Headers: {
+    "Content-Type": mime-type
+}
+
+// Delete note
+DELETE /etapi/notes/:noteId
+```
+
+#### Attribute Management
+
+```typescript
+// Create attribute
+POST /etapi/attributes
+Body: {
+    noteId: string,
+    type: 'label' | 'relation',
+    name: string,
+    value: string,
+    isInheritable?: boolean
+}
+
+// Update attribute
+PATCH /etapi/attributes/:attributeId
+Body: {
+    value?: string,
+    isInheritable?: boolean
+}
+```
+
+#### Search
+
+```typescript
+// Search notes
+GET /etapi/notes/search
+Query: {
+    search: string,
+    limit?: number,
+    orderBy?: string,
+    orderDirection?: 'asc' | 'desc'
+}
+Response: {
+    results: Array<{
+        noteId: string,
+        title: string,
+        // Other note properties
+    }>
+}
+```
+
+### Client Libraries
+
+```javascript
+// JavaScript client example
+class EtapiClient {
+    constructor(serverUrl, authToken) {
+        this.serverUrl = serverUrl;
+        this.authToken = authToken;
+    }
+    
+    async getNote(noteId) {
+        const response = await fetch(
+            `${this.serverUrl}/etapi/notes/${noteId}`,
+            {
+                headers: {
+                    'Authorization': this.authToken
+                }
+            }
+        );
+        return response.json();
+    }
+    
+    async createNote(parentNoteId, title, content) {
+        const response = await fetch(
+            `${this.serverUrl}/etapi/notes`,
+            {
+                method: 'POST',
+                headers: {
+                    'Authorization': this.authToken,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    parentNoteId,
+                    title,
+                    type: 'text',
+                    content
+                })
+            }
+        );
+        return response.json();
+    }
+}
+```
+
+### Python Client Example
+
+```python
+import requests
+
+class TriliumETAPI:
+    def __init__(self, server_url, auth_token):
+        self.server_url = server_url
+        self.auth_token = auth_token
+        self.headers = {'Authorization': auth_token}
+    
+    def get_note(self, note_id):
+        response = requests.get(
+            f"{self.server_url}/etapi/notes/{note_id}",
+            headers=self.headers
+        )
+        return response.json()
+    
+    def create_note(self, parent_note_id, title, content=""):
+        response = requests.post(
+            f"{self.server_url}/etapi/notes",
+            headers=self.headers,
+            json={
+                'parentNoteId': parent_note_id,
+                'title': title,
+                'type': 'text',
+                'content': content
+            }
+        )
+        return response.json()
+    
+    def search_notes(self, query):
+        response = requests.get(
+            f"{self.server_url}/etapi/notes/search",
+            headers=self.headers,
+            params={'search': query}
+        )
+        return response.json()
+```
+
+## WebSocket Real-time Synchronization
+
+**Location**: `/apps/server/src/services/ws.ts`
+
+WebSocket connections provide real-time updates and synchronization between clients.
+
+### Architecture
+
+```typescript
+// WebSocket message types
+interface WSMessage {
+    type: string;
+    data: any;
+}
+
+// Common message types
+type MessageType = 
+    | 'entity-changes'      // Entity updates
+    | 'sync'               // Sync events
+    | 'note-content-change' // Content updates
+    | 'refresh-tree'       // Tree structure changes
+    | 'options-changed'    // Configuration updates
+```
+
+### Connection Management
+
+```typescript
+// Client connection
+const ws = new WebSocket('wss://server/ws');
+
+ws.on('open', () => {
+    // Authenticate
+    ws.send(JSON.stringify({
+        type: 'auth',
+        token: sessionToken
+    }));
+});
+
+ws.on('message', (data) => {
+    const message = JSON.parse(data);
+    handleWSMessage(message);
+});
+
+// Server-side handling
+import WebSocket from 'ws';
+
+const wss = new WebSocket.Server({ server });
+
+wss.on('connection', (ws, req) => {
+    const session = parseSession(req);
+    
+    if (!session.authenticated) {
+        ws.close(1008, 'Not authenticated');
+        return;
+    }
+    
+    clients.add(ws);
+    
+    ws.on('message', (message) => {
+        handleClientMessage(ws, message);
+    });
+    
+    ws.on('close', () => {
+        clients.delete(ws);
+    });
+});
+```
+
+### Message Broadcasting
+
+```typescript
+// Broadcast entity changes
+function broadcastEntityChanges(changes: EntityChange[]) {
+    const message = {
+        type: 'entity-changes',
+        data: changes
+    };
+    
+    for (const client of clients) {
+        if (client.readyState === WebSocket.OPEN) {
+            client.send(JSON.stringify(message));
+        }
+    }
+}
+
+// Targeted messages
+function sendToClient(clientId: string, message: WSMessage) {
+    const client = clients.get(clientId);
+    if (client?.readyState === WebSocket.OPEN) {
+        client.send(JSON.stringify(message));
+    }
+}
+```
+
+### Real-time Sync Protocol
+
+```typescript
+// Entity change notification
+{
+    type: 'entity-changes',
+    data: [
+        {
+            entityName: 'notes',
+            entityId: 'noteId123',
+            action: 'update',
+            entity: { /* note data */ }
+        }
+    ]
+}
+
+// Sync pull request
+{
+    type: 'sync-pull',
+    data: {
+        lastSyncId: 12345
+    }
+}
+
+// Sync push
+{
+    type: 'sync-push',
+    data: {
+        entities: [ /* changed entities */ ]
+    }
+}
+```
+
+### Client-side Handling
+
+```typescript
+// Froca WebSocket integration
+class WSClient {
+    constructor() {
+        this.ws = null;
+        this.reconnectTimeout = null;
+        this.connect();
+    }
+    
+    connect() {
+        this.ws = new WebSocket(this.getWSUrl());
+        
+        this.ws.onmessage = (event) => {
+            const message = JSON.parse(event.data);
+            this.handleMessage(message);
+        };
+        
+        this.ws.onclose = () => {
+            // Reconnect with exponential backoff
+            this.scheduleReconnect();
+        };
+    }
+    
+    handleMessage(message: WSMessage) {
+        switch (message.type) {
+            case 'entity-changes':
+                this.handleEntityChanges(message.data);
+                break;
+            case 'refresh-tree':
+                froca.loadInitialTree();
+                break;
+            case 'note-content-change':
+                this.handleContentChange(message.data);
+                break;
+        }
+    }
+    
+    handleEntityChanges(changes: EntityChange[]) {
+        for (const change of changes) {
+            if (change.entityName === 'notes') {
+                froca.reloadNotes([change.entityId]);
+            }
+        }
+    }
+}
+```
+
+## API Security
+
+### Authentication Methods
+
+```typescript
+// 1. Session-based (Internal API)
+app.use(session({
+    secret: config.sessionSecret,
+    resave: false,
+    saveUninitialized: false
+}));
+
+// 2. Token-based (ETAPI)
+router.use('/etapi', (req, res, next) => {
+    const token = req.headers.authorization;
+    
+    const etapiToken = becca.getEtapiToken(token);
+    if (!etapiToken || etapiToken.isExpired()) {
+        return res.status(401).json({ 
+            error: 'Invalid or expired token' 
+        });
+    }
+    
+    req.etapiToken = etapiToken;
+    next();
+});
+
+// 3. WebSocket authentication
+ws.on('connection', (socket) => {
+    socket.on('auth', (token) => {
+        if (!validateToken(token)) {
+            socket.close(1008, 'Invalid token');
+        }
+    });
+});
+```
+
+### Rate Limiting
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+// Global rate limit
+const globalLimiter = rateLimit({
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    max: 1000 // limit each IP to 1000 requests per windowMs
+});
+
+// Strict limit for authentication
+const authLimiter = rateLimit({
+    windowMs: 15 * 60 * 1000,
+    max: 5,
+    message: 'Too many authentication attempts'
+});
+
+app.use('/api', globalLimiter);
+app.use('/api/auth', authLimiter);
+```
+
+### Input Validation
+
+```typescript
+import { body, validationResult } from 'express-validator';
+
+router.post('/api/notes',
+    body('title').isString().isLength({ min: 1, max: 1000 }),
+    body('type').isIn(['text', 'code', 'file', 'image']),
+    body('content').optional().isString(),
+    (req, res) => {
+        const errors = validationResult(req);
+        if (!errors.isEmpty()) {
+            return res.status(400).json({ 
+                errors: errors.array() 
+            });
+        }
+        
+        // Process valid input
+    }
+);
+```
+
+## Performance Optimization
+
+### Caching Strategies
+
+```typescript
+// Response caching
+const cache = new Map();
+
+router.get('/api/notes/:noteId', (req, res) => {
+    const cacheKey = `note:${req.params.noteId}`;
+    const cached = cache.get(cacheKey);
+    
+    if (cached && cached.expires > Date.now()) {
+        return res.json(cached.data);
+    }
+    
+    const note = becca.getNote(req.params.noteId);
+    const data = note.getPojo();
+    
+    cache.set(cacheKey, {
+        data,
+        expires: Date.now() + 60000 // 1 minute
+    });
+    
+    res.json(data);
+});
+```
+
+### Batch Operations
+
+```typescript
+// Batch API endpoint
+router.post('/api/batch', async (req, res) => {
+    const operations = req.body.operations;
+    const results = [];
+    
+    await sql.transactional(async () => {
+        for (const op of operations) {
+            const result = await executeOperation(op);
+            results.push(result);
+        }
+    });
+    
+    res.json({ results });
+});
+
+// Client batch usage
+const batch = [
+    { method: 'PUT', path: '/notes/1', body: { title: 'Note 1' }},
+    { method: 'PUT', path: '/notes/2', body: { title: 'Note 2' }},
+    { method: 'POST', path: '/notes/3/attributes', body: { type: 'label', name: 'todo' }}
+];
+
+await api.post('/batch', { operations: batch });
+```
+
+### Streaming Responses
+
+```typescript
+// Stream large data
+router.get('/api/export', (req, res) => {
+    res.writeHead(200, {
+        'Content-Type': 'application/x-ndjson',
+        'Transfer-Encoding': 'chunked'
+    });
+    
+    const noteStream = createNoteExportStream();
+    
+    noteStream.on('data', (note) => {
+        res.write(JSON.stringify(note) + '\n');
+    });
+    
+    noteStream.on('end', () => {
+        res.end();
+    });
+});
+```
+
+## Error Handling
+
+### Standard Error Responses
+
+```typescript
+// Error response format
+interface ErrorResponse {
+    error: string;
+    code?: string;
+    details?: any;
+}
+
+// Error handling middleware
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+    console.error('API Error:', err);
+    
+    if (err instanceof NotFoundError) {
+        return res.status(404).json({
+            error: err.message,
+            code: 'NOT_FOUND'
+        });
+    }
+    
+    if (err instanceof ValidationError) {
+        return res.status(400).json({
+            error: err.message,
+            code: 'VALIDATION_ERROR',
+            details: err.details
+        });
+    }
+    
+    // Generic error
+    res.status(500).json({
+        error: 'Internal server error',
+        code: 'INTERNAL_ERROR'
+    });
+});
+```
+
+## API Documentation
+
+### OpenAPI/Swagger
+
+```yaml
+# etapi.openapi.yaml
+openapi: 3.0.0
+info:
+  title: Trilium ETAPI
+  version: 1.0.0
+  description: External API for Trilium Notes
+
+paths:
+  /etapi/notes/{noteId}:
+    get:
+      summary: Get note by ID
+      parameters:
+        - name: noteId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Note found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Note'
+        404:
+          description: Note not found
+
+components:
+  schemas:
+    Note:
+      type: object
+      properties:
+        noteId:
+          type: string
+        title:
+          type: string
+        type:
+          type: string
+          enum: [text, code, file, image]
+```
+
+### API Testing
+
+```typescript
+// API test example
+describe('Notes API', () => {
+    it('should create a note', async () => {
+        const response = await request(app)
+            .post('/api/notes/root/children')
+            .send({
+                title: 'Test Note',
+                type: 'text',
+                content: 'Test content'
+            })
+            .expect(200);
+            
+        expect(response.body).toHaveProperty('noteId');
+        expect(response.body.title).toBe('Test Note');
+    });
+    
+    it('should handle errors', async () => {
+        const response = await request(app)
+            .get('/api/notes/invalid')
+            .expect(404);
+            
+        expect(response.body).toHaveProperty('error');
+    });
+});
+```
+
+## Best Practices
+
+### API Design
+
+1.  **RESTful conventions**: Use appropriate HTTP methods and status codes
+2.  **Consistent naming**: Use camelCase for JSON properties
+3.  **Versioning**: Version the API to maintain compatibility
+4.  **Documentation**: Keep OpenAPI spec up to date
+
+### Security
+
+1.  **Authentication**: Always verify user identity
+2.  **Authorization**: Check permissions for each operation
+3.  **Validation**: Validate all input data
+4.  **Rate limiting**: Prevent abuse with appropriate limits
+
+### Performance
+
+1.  **Pagination**: Limit response sizes with pagination
+2.  **Caching**: Cache frequently accessed data
+3.  **Batch operations**: Support bulk operations
+4.  **Async processing**: Use queues for long-running tasks
+
+## Related Documentation
+
+*   [Three-Layer Cache System](Three-Layer-Cache-System.md) - Cache architecture
+*   [Entity System](Entity-System.md) - Data model
+*   [ETAPI Reference](#root/YCSbHgSqH9PA) - OpenAPI specification

docs/Developer Guide/Developer Guide/Architecture/Entity-System.md

@@ -0,0 +1,614 @@
+# Entity-System
+## Entity System Architecture
+
+The Entity System forms the core data model of Trilium Notes, providing a flexible and powerful structure for organizing information. This document details the entities, their relationships, and usage patterns.
+
+## Core Entities Overview
+
+```
+erDiagram
+    Note ||--o{ Branch : "parent-child"
+    Note ||--o{ Attribute : "has"
+    Note ||--o{ Revision : "history"
+    Note ||--o{ Attachment : "contains"
+    Attachment ||--|| Blob : "stores in"
+    Revision ||--|| Blob : "stores in"
+    Note }o--o{ Note : "relates via Attribute"
+    
+    Note {
+        string noteId PK
+        string title
+        string type
+        string content
+        boolean isProtected
+        string dateCreated
+        string dateModified
+    }
+    
+    Branch {
+        string branchId PK
+        string noteId FK
+        string parentNoteId FK
+        integer notePosition
+        string prefix
+        boolean isExpanded
+    }
+    
+    Attribute {
+        string attributeId PK
+        string noteId FK
+        string type "label or relation"
+        string name
+        string value
+        integer position
+        boolean isInheritable
+    }
+    
+    Revision {
+        string revisionId PK
+        string noteId FK
+        string title
+        string type
+        boolean isProtected
+        string dateCreated
+    }
+    
+    Attachment {
+        string attachmentId PK
+        string ownerId FK
+        string role
+        string mime
+        string title
+        string blobId FK
+    }
+    
+    Blob {
+        string blobId PK
+        binary content
+        string dateModified
+    }
+    
+    Option {
+        string name PK
+        string value
+        boolean isSynced
+    }
+```
+
+## Entity Definitions
+
+### BNote - Notes with Content and Metadata
+
+**Location**: `/apps/server/src/becca/entities/bnote.ts`
+
+Notes are the fundamental unit of information in Trilium. Each note can contain different types of content and maintain relationships with other notes.
+
+#### Properties
+
+```typescript
+class BNote {
+    noteId: string;           // Unique identifier
+    title: string;            // Display title
+    type: string;             // Content type (text, code, file, etc.)
+    mime: string;             // MIME type for content
+    isProtected: boolean;     // Encryption flag
+    dateCreated: string;      // Creation timestamp
+    dateModified: string;     // Last modification
+    utcDateCreated: string;   // UTC creation
+    utcDateModified: string;  // UTC modification
+    
+    // Relationships
+    parentBranches: BBranch[];  // Parent connections
+    children: BBranch[];        // Child connections
+    attributes: BAttribute[];   // Metadata
+    
+    // Content
+    content?: string | Buffer;  // Note content (lazy loaded)
+    
+    // Computed
+    isDecrypted: boolean;       // Decryption status
+}
+```
+
+#### Note Types
+
+*   **text**: Rich text content with HTML formatting
+*   **code**: Source code with syntax highlighting
+*   **file**: Binary file attachment
+*   **image**: Image with preview capabilities
+*   **search**: Saved search query
+*   **book**: Container for hierarchical documentation
+*   **relationMap**: Visual relationship diagram
+*   **canvas**: Drawing canvas (Excalidraw)
+*   **mermaid**: Mermaid diagram
+*   **mindMap**: Mind mapping visualization
+*   **webView**: Embedded web content
+*   **noteMap**: Tree visualization
+
+#### Usage Examples
+
+```typescript
+// Create a new note
+const note = new BNote({
+    noteId: generateNoteId(),
+    title: "My Note",
+    type: "text",
+    mime: "text/html",
+    content: "<p>Note content</p>"
+});
+note.save();
+
+// Get note with content
+const note = becca.getNote(noteId);
+await note.loadContent();
+
+// Update note
+note.title = "Updated Title";
+note.save();
+
+// Protect note
+note.isProtected = true;
+note.encrypt();
+note.save();
+```
+
+### BBranch - Hierarchical Relationships
+
+**Location**: `/apps/server/src/becca/entities/bbranch.ts`
+
+Branches define the parent-child relationships between notes, allowing a note to have multiple parents (cloning).
+
+#### Properties
+
+```typescript
+class BBranch {
+    branchId: string;        // Unique identifier
+    noteId: string;          // Child note ID
+    parentNoteId: string;    // Parent note ID
+    notePosition: number;    // Order among siblings
+    prefix: string;          // Optional prefix label
+    isExpanded: boolean;     // Tree UI state
+    
+    // Computed
+    childNote: BNote;        // Reference to child
+    parentNote: BNote;       // Reference to parent
+}
+```
+
+#### Key Features
+
+*   **Multiple Parents**: Notes can appear in multiple locations
+*   **Ordering**: Explicit positioning among siblings
+*   **Prefixes**: Optional labels for context (e.g., "Chapter 1:")
+*   **UI State**: Expansion state persisted per branch
+
+#### Usage Examples
+
+```typescript
+// Create parent-child relationship
+const branch = new BBranch({
+    noteId: childNote.noteId,
+    parentNoteId: parentNote.noteId,
+    notePosition: 10
+});
+branch.save();
+
+// Clone note to another parent
+const cloneBranch = childNote.cloneTo(otherParent.noteId);
+
+// Reorder children
+parentNote.sortChildren((a, b) => 
+    a.title.localeCompare(b.title)
+);
+
+// Add prefix
+branch.prefix = "Important: ";
+branch.save();
+```
+
+### BAttribute - Key-Value Metadata
+
+**Location**: `/apps/server/src/becca/entities/battribute.ts`
+
+Attributes provide flexible metadata and relationships between notes.
+
+#### Types
+
+1.  **Labels**: Key-value pairs for metadata
+2.  **Relations**: References to other notes
+
+#### Properties
+
+```typescript
+class BAttribute {
+    attributeId: string;     // Unique identifier
+    noteId: string;          // Owning note
+    type: 'label' | 'relation';
+    name: string;            // Attribute name
+    value: string;           // Value or target noteId
+    position: number;        // Display order
+    isInheritable: boolean;  // Inherited by children
+    
+    // Computed
+    note: BNote;             // Owner note
+    targetNote?: BNote;      // For relations
+}
+```
+
+#### Common Patterns
+
+```typescript
+// Add label
+note.addLabel("status", "active");
+note.addLabel("priority", "high");
+
+// Add relation
+note.addRelation("template", templateNoteId);
+note.addRelation("renderNote", renderNoteId);
+
+// Query by attributes
+const todos = becca.findAttributes("label", "todoItem");
+const templates = becca.findAttributes("label", "template");
+
+// Inheritable attributes
+note.addLabel("workspace", "project", true); // Children inherit
+```
+
+#### System Attributes
+
+Special attributes with system behavior:
+
+*   `#hidePromotedAttributes`: Hide promoted attributes in UI
+*   `#readOnly`: Prevent note editing
+*   `#autoReadOnlyDisabled`: Disable auto read-only
+*   `#hideChildrenOverview`: Hide children count
+*   `~template`: Note template relation
+*   `~renderNote`: Custom rendering relation
+
+### BRevision - Version History
+
+**Location**: `/apps/server/src/becca/entities/brevision.ts`
+
+Revisions provide version history and recovery capabilities.
+
+#### Properties
+
+```typescript
+class BRevision {
+    revisionId: string;      // Unique identifier
+    noteId: string;          // Parent note
+    type: string;            // Content type
+    mime: string;            // MIME type
+    title: string;           // Historical title
+    isProtected: boolean;    // Encryption flag
+    dateCreated: string;     // Creation time
+    utcDateCreated: string;  // UTC time
+    dateModified: string;    // Content modification
+    blobId: string;          // Content storage
+    
+    // Methods
+    getContent(): string | Buffer;
+    restore(): void;
+}
+```
+
+#### Revision Strategy
+
+*   Created automatically on significant changes
+*   Configurable retention period
+*   Day/week/month/year retention rules
+*   Protected note revisions are encrypted
+
+#### Usage Examples
+
+```typescript
+// Get note revisions
+const revisions = note.getRevisions();
+
+// Restore revision
+const revision = becca.getRevision(revisionId);
+revision.restore();
+
+// Manual revision creation
+note.saveRevision();
+
+// Compare revisions
+const diff = revision1.getContent() !== revision2.getContent();
+```
+
+### BOption - Application Configuration
+
+**Location**: `/apps/server/src/becca/entities/boption.ts`
+
+Options store application and user preferences.
+
+#### Properties
+
+```typescript
+class BOption {
+    name: string;            // Option key
+    value: string;           // Option value
+    isSynced: boolean;       // Sync across instances
+    utcDateModified: string; // Last change
+}
+```
+
+#### Common Options
+
+```typescript
+// Theme settings
+setOption("theme", "dark");
+
+// Protected session timeout
+setOption("protectedSessionTimeout", "600");
+
+// Sync settings
+setOption("syncServerHost", "https://sync.server");
+
+// Note settings
+setOption("defaultNoteType", "text");
+```
+
+### BAttachment - File Attachments
+
+**Location**: `/apps/server/src/becca/entities/battachment.ts`
+
+Attachments link binary content to notes.
+
+#### Properties
+
+```typescript
+class BAttachment {
+    attachmentId: string;    // Unique identifier
+    ownerId: string;         // Parent note ID
+    role: string;            // Attachment role
+    mime: string;            // MIME type
+    title: string;           // Display title
+    blobId: string;          // Content reference
+    utcDateScheduledForDeletion: string;
+    
+    // Methods
+    getContent(): Buffer;
+    getBlob(): BBlob;
+}
+```
+
+#### Usage Patterns
+
+```typescript
+// Add attachment to note
+const attachment = note.addAttachment({
+    role: "file",
+    mime: "application/pdf",
+    title: "document.pdf",
+    content: buffer
+});
+
+// Get attachments
+const attachments = note.getAttachments();
+
+// Download attachment
+const content = attachment.getContent();
+```
+
+## Entity Relationships
+
+### Parent-Child Hierarchy
+
+```typescript
+// Single parent
+childNote.setParent(parentNote.noteId);
+
+// Multiple parents (cloning)
+childNote.cloneTo(parent1.noteId);
+childNote.cloneTo(parent2.noteId);
+
+// Get parents
+const parents = childNote.getParentNotes();
+
+// Get children
+const children = parentNote.getChildNotes();
+
+// Get subtree
+const subtree = parentNote.getSubtreeNotes();
+```
+
+### Attribute Relationships
+
+```typescript
+// Direct relations
+note.addRelation("author", authorNote.noteId);
+
+// Bidirectional relations
+note1.addRelation("related", note2.noteId);
+note2.addRelation("related", note1.noteId);
+
+// Get related notes
+const related = note.getRelations("related");
+
+// Get notes relating to this one
+const targetRelations = note.getTargetRelations();
+```
+
+## Entity Lifecycle
+
+### Creation
+
+```typescript
+// Note creation
+const note = new BNote({
+    noteId: generateNoteId(),
+    title: "New Note",
+    type: "text"
+});
+note.save();
+
+// With parent
+const child = parentNote.addChild({
+    title: "Child Note",
+    type: "text",
+    content: "Content"
+});
+```
+
+### Updates
+
+```typescript
+// Atomic updates
+note.title = "New Title";
+note.save();
+
+// Batch updates
+sql.transactional(() => {
+    note1.title = "Title 1";
+    note1.save();
+    
+    note2.content = "Content 2";
+    note2.save();
+});
+```
+
+### Deletion
+
+```typescript
+// Soft delete (move to trash)
+note.deleteNote();
+
+// Mark for deletion
+note.isDeleted = true;
+note.save();
+
+// Permanent deletion (after grace period)
+note.eraseNote();
+```
+
+## Performance Considerations
+
+### Lazy Loading
+
+```typescript
+// Note content loaded on demand
+const note = becca.getNote(noteId); // Metadata only
+await note.loadContent(); // Load content when needed
+
+// Revisions loaded on demand
+const revisions = note.getRevisions(); // Database query
+```
+
+### Batch Operations
+
+```typescript
+// Efficient bulk loading
+const notes = becca.getNotes(noteIds);
+
+// Batch attribute queries
+const attributes = sql.getRows(`
+    SELECT * FROM attributes 
+    WHERE noteId IN (???) 
+    AND name = ?
+`, [noteIds, 'label']);
+```
+
+### Indexing
+
+```typescript
+// Attribute index for fast lookups
+const labels = becca.findAttributes("label", "important");
+
+// Branch index for relationship queries
+const branch = becca.getBranchFromChildAndParent(childId, parentId);
+```
+
+## Best Practices
+
+### Entity Creation
+
+```typescript
+// Always use transactions for multiple operations
+sql.transactional(() => {
+    const note = new BNote({...});
+    note.save();
+    
+    note.addLabel("status", "draft");
+    note.addRelation("template", templateId);
+});
+```
+
+### Entity Updates
+
+```typescript
+// Check existence before update
+const note = becca.getNote(noteId);
+if (note) {
+    note.title = "Updated";
+    note.save();
+}
+
+// Use proper error handling
+try {
+    const note = becca.getNoteOrThrow(noteId);
+    note.save();
+} catch (e) {
+    log.error(`Note ${noteId} not found`);
+}
+```
+
+### Querying
+
+```typescript
+// Use indexed queries
+const attrs = becca.findAttributes("label", "task");
+
+// Avoid N+1 queries
+const noteIds = [...];
+const notes = becca.getNotes(noteIds); // Single batch
+
+// Use SQL for complex queries
+const results = sql.getRows(`
+    SELECT n.noteId, n.title, COUNT(b.branchId) as childCount
+    FROM notes n
+    LEFT JOIN branches b ON b.parentNoteId = n.noteId
+    GROUP BY n.noteId
+`);
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1.  **Circular References**
+    
+    ```typescript
+    // Detect cycles before creating branches
+    if (!parentNote.hasAncestor(childNote.noteId)) {
+        childNote.setParent(parentNote.noteId);
+    }
+    ```
+2.  **Orphaned Entities**
+    
+    ```typescript
+    // Find orphaned notes
+    const orphans = sql.getRows(`
+        SELECT noteId FROM notes
+        WHERE noteId != 'root'
+        AND noteId NOT IN (SELECT noteId FROM branches)
+    `);
+    ```
+3.  **Attribute Conflicts**
+    
+    ```typescript
+    // Handle duplicate attributes
+    const existing = note.getAttribute("label", "status");
+    if (existing) {
+        existing.value = "new value";
+        existing.save();
+    } else {
+        note.addLabel("status", "new value");
+    }
+    ```
+
+## Related Documentation
+
+*   [Three-Layer Cache System](Three-Layer-Cache-System.md) - Cache architecture
+*   [Database Schema](#root/eZcnGfMUmic0) - Database structure
+*   [Script API](#root/7Pp4moCrBVzA) - Entity API for scripts

docs/Developer Guide/Developer Guide/Architecture/Monorepo-Structure.md

@@ -0,0 +1,612 @@
+# Monorepo-Structure
+## Monorepo Structure
+
+Trilium is organized as a TypeScript monorepo using NX, facilitating code sharing, consistent tooling, and efficient build processes. This document provides a comprehensive overview of the project structure, build system, and development workflow.
+
+## Project Organization
+
+```
+TriliumNext/Trilium/
+├── apps/                      # Runnable applications
+│   ├── client/               # Frontend web application
+│   ├── server/               # Node.js backend server
+│   ├── desktop/              # Electron desktop application
+│   ├── web-clipper/          # Browser extension
+│   ├── db-compare/           # Database comparison tool
+│   ├── dump-db/              # Database dump utility
+│   └── edit-docs/            # Documentation editor
+├── packages/                  # Shared libraries
+│   ├── commons/              # Shared interfaces and utilities
+│   ├── ckeditor5/            # Rich text editor
+│   ├── codemirror/           # Code editor
+│   ├── highlightjs/          # Syntax highlighting
+│   ├── ckeditor5-admonition/ # CKEditor plugin
+│   ├── ckeditor5-footnotes/  # CKEditor plugin
+│   ├── ckeditor5-math/       # CKEditor plugin
+│   └── ckeditor5-mermaid/    # CKEditor plugin
+├── docs/                      # Documentation
+├── nx.json                    # NX workspace configuration
+├── package.json              # Root package configuration
+├── pnpm-workspace.yaml       # PNPM workspace configuration
+└── tsconfig.base.json        # Base TypeScript configuration
+```
+
+## Applications
+
+### Client (`/apps/client`)
+
+The frontend application shared by both server and desktop versions.
+
+```
+apps/client/
+├── src/
+│   ├── components/         # Core UI components
+│   ├── entities/           # Frontend entities (FNote, FBranch, etc.)
+│   ├── services/           # Business logic and API calls
+│   ├── widgets/            # UI widgets system
+│   │   ├── type_widgets/   # Note type specific widgets
+│   │   ├── dialogs/        # Dialog components
+│   │   └── panels/         # Panel widgets
+│   ├── public/
+│   │   ├── fonts/          # Font assets
+│   │   ├── images/         # Image assets
+│   │   └── libraries/      # Third-party libraries
+│   └── desktop.ts          # Desktop entry point
+├── package.json
+├── project.json            # NX project configuration
+└── vite.config.ts          # Vite build configuration
+```
+
+#### Key Files
+
+*   `desktop.ts` - Main application initialization
+*   `services/froca.ts` - Frontend cache implementation
+*   `widgets/basic_widget.ts` - Base widget class
+*   `services/server.ts` - API communication layer
+
+### Server (`/apps/server`)
+
+The Node.js backend providing API, database, and business logic.
+
+```
+apps/server/
+├── src/
+│   ├── becca/              # Backend cache system
+│   │   ├── entities/       # Core entities (BNote, BBranch, etc.)
+│   │   └── becca.ts        # Cache interface
+│   ├── routes/             # Express routes
+│   │   ├── api/            # Internal API endpoints
+│   │   └── pages/          # HTML page routes
+│   ├── etapi/              # External API
+│   ├── services/           # Business services
+│   ├── share/              # Note sharing functionality
+│   │   └── shaca/          # Share cache
+│   ├── migrations/         # Database migrations
+│   ├── assets/
+│   │   ├── db/             # Database schema
+│   │   └── doc_notes/      # Documentation notes
+│   └── main.ts             # Server entry point
+├── package.json
+├── project.json
+└── webpack.config.js       # Webpack configuration
+```
+
+#### Key Services
+
+*   `services/sql.ts` - Database access layer
+*   `services/sync.ts` - Synchronization logic
+*   `services/ws.ts` - WebSocket server
+*   `services/protected_session.ts` - Encryption handling
+
+### Desktop (`/apps/desktop`)
+
+Electron wrapper for the desktop application.
+
+```
+apps/desktop/
+├── src/
+│   ├── main.ts             # Electron main process
+│   ├── preload.ts          # Preload script
+│   ├── services/           # Desktop-specific services
+│   └── utils/              # Desktop utilities
+├── resources/              # Desktop resources (icons, etc.)
+├── package.json
+└── electron-builder.yml    # Electron Builder configuration
+```
+
+### Web Clipper (`/apps/web-clipper`)
+
+Browser extension for saving web content to Trilium.
+
+```
+apps/web-clipper/
+├── src/
+│   ├── background.js       # Background script
+│   ├── content.js          # Content script
+│   ├── popup/              # Extension popup
+│   └── options/            # Extension options
+├── manifest.json           # Extension manifest
+└── package.json
+```
+
+## Packages
+
+### Commons (`/packages/commons`)
+
+Shared TypeScript interfaces and utilities used across applications.
+
+```typescript
+// packages/commons/src/types.ts
+export interface NoteRow {
+    noteId: string;
+    title: string;
+    type: string;
+    mime: string;
+    isProtected: boolean;
+    dateCreated: string;
+    dateModified: string;
+}
+
+export interface BranchRow {
+    branchId: string;
+    noteId: string;
+    parentNoteId: string;
+    notePosition: number;
+    prefix: string;
+    isExpanded: boolean;
+}
+```
+
+### CKEditor5 (`/packages/ckeditor5`)
+
+Custom CKEditor5 build with Trilium-specific plugins.
+
+```
+packages/ckeditor5/
+├── src/
+│   ├── ckeditor.ts         # Editor configuration
+│   ├── plugins.ts          # Plugin registration
+│   └── trilium/            # Custom plugins
+├── theme/                  # Editor themes
+└── package.json
+```
+
+#### Custom Plugins
+
+*   **Admonition**: Note boxes with icons
+*   **Footnotes**: Reference footnotes
+*   **Math**: LaTeX equation rendering
+*   **Mermaid**: Diagram integration
+
+### CodeMirror (`/packages/codemirror`)
+
+Code editor customizations for the code note type.
+
+```typescript
+// packages/codemirror/src/index.ts
+export function createCodeMirror(element: HTMLElement, options: CodeMirrorOptions) {
+    return CodeMirror(element, {
+        ...defaultOptions,
+        ...options,
+        // Trilium-specific customizations
+    });
+}
+```
+
+## Build System
+
+### NX Configuration
+
+**`nx.json`**
+
+```json
+{
+  "tasksRunnerOptions": {
+    "default": {
+      "runner": "nx/tasks-runners/default",
+      "options": {
+        "cacheableOperations": ["build", "test", "lint"],
+        "parallel": 3
+      }
+    }
+  },
+  "targetDefaults": {
+    "build": {
+      "dependsOn": ["^build"],
+      "cache": true
+    },
+    "test": {
+      "cache": true
+    }
+  }
+}
+```
+
+### Project Configuration
+
+Each application and package has a `project.json` defining its targets:
+
+```json
+{
+  "name": "server",
+  "targets": {
+    "build": {
+      "executor": "@nx/webpack:webpack",
+      "options": {
+        "outputPath": "dist/apps/server",
+        "main": "apps/server/src/main.ts",
+        "tsConfig": "apps/server/tsconfig.app.json"
+      }
+    },
+    "serve": {
+      "executor": "@nx/node:node",
+      "options": {
+        "buildTarget": "server:build"
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "options": {
+        "jestConfig": "apps/server/jest.config.ts"
+      }
+    }
+  }
+}
+```
+
+### Build Commands
+
+```sh
+# Build specific project
+pnpm nx build server
+pnpm nx build client
+
+# Build all projects
+pnpm nx run-many --target=build --all
+
+# Build with dependencies
+pnpm nx build server --with-deps
+
+# Production build
+pnpm nx build server --configuration=production
+```
+
+## Development Workflow
+
+### Initial Setup
+
+```sh
+# Install dependencies
+pnpm install
+
+# Enable corepack for pnpm
+corepack enable
+
+# Build all packages
+pnpm nx run-many --target=build --all
+```
+
+### Development Commands
+
+```sh
+# Start development server
+pnpm run server:start
+# or
+pnpm nx run server:serve
+
+# Start desktop app
+pnpm nx run desktop:serve
+
+# Run client dev server
+pnpm nx run client:serve
+
+# Watch mode for packages
+pnpm nx run commons:build --watch
+```
+
+### Testing
+
+```sh
+# Run all tests
+pnpm test:all
+
+# Run tests for specific project
+pnpm nx test server
+pnpm nx test client
+
+# Run tests in watch mode
+pnpm nx test server --watch
+
+# Generate coverage
+pnpm nx test server --coverage
+```
+
+### Linting and Type Checking
+
+```sh
+# Lint specific project
+pnpm nx lint server
+
+# Type check
+pnpm nx run server:typecheck
+
+# Lint all projects
+pnpm nx run-many --target=lint --all
+
+# Fix lint issues
+pnpm nx lint server --fix
+```
+
+## Dependency Management
+
+### Package Dependencies
+
+Dependencies are managed at both root and project levels:
+
+```json
+// Root package.json - shared dev dependencies
+{
+  "devDependencies": {
+    "@nx/workspace": "^17.0.0",
+    "typescript": "^5.0.0",
+    "eslint": "^8.0.0"
+  }
+}
+
+// Project package.json - project-specific dependencies
+{
+  "dependencies": {
+    "express": "^4.18.0",
+    "better-sqlite3": "^9.0.0"
+  }
+}
+```
+
+### Adding Dependencies
+
+```sh
+# Add to root
+pnpm add -D typescript
+
+# Add to specific project
+pnpm add express --filter server
+
+# Add to multiple projects
+pnpm add lodash --filter server --filter client
+```
+
+### Workspace References
+
+Internal packages are referenced using workspace protocol:
+
+```json
+{
+  "dependencies": {
+    "@triliumnext/commons": "workspace:*"
+  }
+}
+```
+
+## TypeScript Configuration
+
+### Base Configuration
+
+**`tsconfig.base.json`**
+
+```json
+{
+  "compilerOptions": {
+    "rootDir": ".",
+    "sourceMap": true,
+    "declaration": false,
+    "moduleResolution": "node",
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022", "dom"],
+    "skipLibCheck": true,
+    "skipDefaultLibCheck": true,
+    "baseUrl": ".",
+    "paths": {
+      "@triliumnext/commons": ["packages/commons/src/index.ts"]
+    }
+  }
+}
+```
+
+### Project-Specific Configuration
+
+```json
+// apps/server/tsconfig.json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["**/*.spec.ts"]
+}
+```
+
+## Build Optimization
+
+### NX Cloud
+
+```sh
+# Enable NX Cloud for distributed caching
+pnpm nx connect-to-nx-cloud
+```
+
+### Affected Commands
+
+```sh
+# Build only affected projects
+pnpm nx affected:build --base=main
+
+# Test only affected projects
+pnpm nx affected:test --base=main
+
+# Lint only affected projects
+pnpm nx affected:lint --base=main
+```
+
+### Build Caching
+
+NX caches build outputs to speed up subsequent builds:
+
+```sh
+# Clear cache
+pnpm nx reset
+
+# Run with cache disabled
+pnpm nx build server --skip-nx-cache
+
+# See cache statistics
+pnpm nx report
+```
+
+## Production Builds
+
+### Building for Production
+
+```sh
+# Build server for production
+pnpm nx build server --configuration=production
+
+# Build client with optimization
+pnpm nx build client --configuration=production
+
+# Build desktop app
+pnpm nx build desktop --configuration=production
+pnpm electron:build  # Creates distributables
+```
+
+### Docker Build
+
+```dockerfile
+# Multi-stage build
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+COPY package*.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+
+COPY . .
+RUN pnpm nx build server --configuration=production
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=builder /app/dist/apps/server ./
+COPY --from=builder /app/node_modules ./node_modules
+
+CMD ["node", "main.js"]
+```
+
+## Continuous Integration
+
+### GitHub Actions Example
+
+```yaml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v3
+      
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+          
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          
+      - run: pnpm install --frozen-lockfile
+      
+      - run: pnpm nx affected:lint --base=origin/main
+      
+      - run: pnpm nx affected:test --base=origin/main
+      
+      - run: pnpm nx affected:build --base=origin/main
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1.  **Build Cache Issues**
+    
+    ```sh
+    # Clear NX cache
+    pnpm nx reset
+    
+    # Clear node_modules and reinstall
+    rm -rf node_modules
+    pnpm install
+    ```
+2.  **Dependency Version Conflicts**
+    
+    ```sh
+    # Check for duplicate packages
+    pnpm list --depth=0
+    
+    # Update all dependencies
+    pnpm update --recursive
+    ```
+3.  **TypeScript Path Resolution**
+    
+    ```sh
+    # Verify TypeScript paths
+    pnpm nx run server:typecheck --traceResolution
+    ```
+
+### Debug Commands
+
+```sh
+# Show project graph
+pnpm nx graph
+
+# Show project dependencies
+pnpm nx print-affected --type=app --select=projects
+
+# Verbose output
+pnpm nx build server --verbose
+
+# Profile build performance
+pnpm nx build server --profile
+```
+
+## Best Practices
+
+### Project Structure
+
+1.  **Keep packages focused**: Each package should have a single, clear purpose
+2.  **Minimize circular dependencies**: Use dependency graph to identify issues
+3.  **Share common code**: Extract shared logic to packages/commons
+
+### Development
+
+1.  **Use NX generators**: Generate consistent code structure
+2.  **Leverage caching**: Don't skip-nx-cache unless debugging
+3.  **Run affected commands**: Save time by only building/testing changed code
+
+### Testing
+
+1.  **Colocate tests**: Keep test files next to source files
+2.  **Use workspace scripts**: Define common scripts in root package.json
+3.  **Parallel execution**: Use `--parallel` flag for faster execution
+
+## Related Documentation
+
+*   [Environment Setup](#root/tFVKyUp99QEc) - Development environment setup
+*   [Project Structure](#root/NurKhC1Zq1CN) - Detailed project structure
+*   [Build Information](#root/m5GSI5gIyqs5) - Build details

docs/Developer Guide/Developer Guide/Architecture/README.md

@@ -0,0 +1,97 @@
+# README
+## Trilium Architecture Documentation
+
+This comprehensive guide documents the architecture of Trilium Notes, providing developers with detailed information about the system's core components, data flow, and design patterns.
+
+## Table of Contents
+
+1.  [Three-Layer Cache System](Three-Layer-Cache-System.md)
+2.  [Entity System](Entity-System.md)
+3.  [Widget-Based UI Architecture](Widget-Based-UI-Architecture.md)
+4.  [API Architecture](API-Architecture.md)
+5.  [Monorepo Structure](Monorepo-Structure.md)
+
+## Overview
+
+Trilium Notes is built as a TypeScript monorepo using NX, featuring a sophisticated architecture that balances performance, flexibility, and maintainability. The system is designed around several key architectural patterns:
+
+*   **Three-layer caching system** for optimal performance across backend, frontend, and shared content
+*   **Entity-based data model** supporting hierarchical note structures with multiple parent relationships
+*   **Widget-based UI architecture** enabling modular and extensible interface components
+*   **Multiple API layers** for internal operations, external integrations, and real-time synchronization
+*   **Monorepo structure** facilitating code sharing and consistent development patterns
+
+## Quick Start for Developers
+
+If you're new to Trilium development, start with these sections:
+
+1.  [Monorepo Structure](Monorepo-Structure.md) - Understand the project organization
+2.  [Entity System](Entity-System.md) - Learn about the core data model
+3.  [Three-Layer Cache System](Three-Layer-Cache-System.md) - Understand data flow and caching
+
+For UI development, refer to:
+
+*   [Widget-Based UI Architecture](Widget-Based-UI-Architecture.md)
+
+For API integration, see:
+
+*   [API Architecture](API-Architecture.md)
+
+## Architecture Principles
+
+### Performance First
+
+*   Lazy loading of note content
+*   Efficient caching at multiple layers
+*   Optimized database queries with prepared statements
+
+### Flexibility
+
+*   Support for multiple note types
+*   Extensible through scripting
+*   Plugin architecture for UI widgets
+
+### Data Integrity
+
+*   Transactional database operations
+*   Revision history for all changes
+*   Synchronization conflict resolution
+
+### Security
+
+*   Per-note encryption
+*   Protected sessions
+*   API authentication tokens
+
+## Development Workflow
+
+1.  **Setup Development Environment**
+    
+    ```sh
+    pnpm install
+    pnpm run server:start
+    ```
+2.  **Make Changes**
+    
+    *   Backend changes in `apps/server/src/`
+    *   Frontend changes in `apps/client/src/`
+    *   Shared code in `packages/`
+3.  **Test Your Changes**
+    
+    ```sh
+    pnpm test:all
+    pnpm nx run <project>:lint
+    ```
+4.  **Build for Production**
+    
+    ```sh
+    pnpm nx build server
+    pnpm nx build client
+    ```
+
+## Further Reading
+
+*   [Development Environment Setup](#root/tFVKyUp99QEc)
+*   [Adding a New Note Type](#root/6aV1LKciq0CF)
+*   [Database Schema](#root/eZcnGfMUmic0)
+*   [Script API Documentation](#root/7Pp4moCrBVzA)

docs/Developer Guide/Developer Guide/Architecture/Three-Layer-Cache-System.md

@@ -0,0 +1,374 @@
+# Three-Layer-Cache-System
+## Three-Layer Cache System Architecture
+
+Trilium implements a sophisticated three-layer caching system to optimize performance and reduce database load. This architecture ensures fast access to frequently used data while maintaining consistency across different application contexts.
+
+## Overview
+
+The three cache layers are:
+
+1.  **Becca** (Backend Cache) - Server-side entity cache
+2.  **Froca** (Frontend Cache) - Client-side mirror of backend data
+3.  **Shaca** (Share Cache) - Optimized cache for shared/published notes
+
+```
+graph TB
+    subgraph "Database Layer"
+        DB[(SQLite Database)]
+    end
+    
+    subgraph "Backend Layer"
+        Becca[Becca Cache<br/>Backend Cache]
+        API[API Layer]
+    end
+    
+    subgraph "Frontend Layer"
+        Froca[Froca Cache<br/>Frontend Cache]
+        UI[UI Components]
+    end
+    
+    subgraph "Share Layer"
+        Shaca[Shaca Cache<br/>Share Cache]
+        Share[Public Share Interface]
+    end
+    
+    DB <--> Becca
+    Becca <--> API
+    API <--> Froca
+    Froca <--> UI
+    DB <--> Shaca
+    Shaca <--> Share
+    
+    style Becca fill:#e1f5fe
+    style Froca fill:#fff3e0
+    style Shaca fill:#f3e5f5
+```
+
+## Becca (Backend Cache)
+
+**Location**: `/apps/server/src/becca/`
+
+Becca is the authoritative cache layer that maintains all notes, branches, attributes, and options in server memory.
+
+### Key Components
+
+#### Becca Interface (`becca-interface.ts`)
+
+```typescript
+export default class Becca {
+    loaded: boolean;
+    notes: Record<string, BNote>;
+    branches: Record<string, BBranch>;
+    childParentToBranch: Record<string, BBranch>;
+    attributes: Record<string, BAttribute>;
+    attributeIndex: Record<string, BAttribute[]>;
+    options: Record<string, BOption>;
+    etapiTokens: Record<string, BEtapiToken>;
+    allNoteSetCache: NoteSet | null;
+}
+```
+
+### Features
+
+*   **In-memory storage**: All active entities are kept in memory for fast access
+*   **Lazy loading**: Related entities (revisions, attachments) loaded on demand
+*   **Index structures**: Optimized lookups via `childParentToBranch` and `attributeIndex`
+*   **Cache invalidation**: Automatic cache updates on entity changes
+*   **Protected note decryption**: On-demand decryption of encrypted content
+
+### Usage Example
+
+```typescript
+import becca from "./becca/becca.js";
+
+// Get a note
+const note = becca.getNote("noteId");
+
+// Find attributes by type and name
+const labels = becca.findAttributes("label", "todoItem");
+
+// Get branch relationships
+const branch = becca.getBranchFromChildAndParent(childId, parentId);
+```
+
+### Data Flow
+
+1.  **Initialization**: Load all notes, branches, and attributes from database
+2.  **Access**: Direct memory access for cached entities
+3.  **Updates**: Write-through cache with immediate database persistence
+4.  **Invalidation**: Automatic cache refresh on entity changes
+
+## Froca (Frontend Cache)
+
+**Location**: `/apps/client/src/services/froca.ts`
+
+Froca is the frontend mirror of Becca, maintaining a subset of backend data for client-side operations.
+
+### Key Components
+
+#### Froca Implementation (`froca.ts`)
+
+```typescript
+class FrocaImpl implements Froca {
+    notes: Record<string, FNote>;
+    branches: Record<string, FBranch>;
+    attributes: Record<string, FAttribute>;
+    attachments: Record<string, FAttachment>;
+    blobPromises: Record<string, Promise<FBlob | null> | null>;
+}
+```
+
+### Features
+
+*   **Lazy loading**: Notes loaded on-demand with their immediate context
+*   **Subtree loading**: Efficient loading of note hierarchies
+*   **Real-time updates**: WebSocket synchronization with backend changes
+*   **Search note support**: Virtual branches for search results
+*   **Promise-based blob loading**: Asynchronous content loading
+
+### Loading Strategy
+
+```typescript
+// Initial load - loads root and immediate children
+await froca.loadInitialTree();
+
+// Load subtree on demand
+const note = await froca.loadSubTree(noteId);
+
+// Reload specific notes
+await froca.reloadNotes([noteId1, noteId2]);
+```
+
+### Synchronization
+
+Froca maintains consistency with Becca through:
+
+1.  **Initial sync**: Load essential tree structure on startup
+2.  **On-demand loading**: Fetch notes as needed
+3.  **WebSocket updates**: Real-time push of changes from backend
+4.  **Batch reloading**: Efficient refresh of multiple notes
+
+## Shaca (Share Cache)
+
+**Location**: `/apps/server/src/share/shaca/`
+
+Shaca is a specialized cache for publicly shared notes, optimized for read-only access.
+
+### Key Components
+
+#### Shaca Interface (`shaca-interface.ts`)
+
+```typescript
+export default class Shaca {
+    notes: Record<string, SNote>;
+    branches: Record<string, SBranch>;
+    childParentToBranch: Record<string, SBranch>;
+    attributes: Record<string, SAttribute>;
+    attachments: Record<string, SAttachment>;
+    aliasToNote: Record<string, SNote>;
+    shareRootNote: SNote | null;
+    shareIndexEnabled: boolean;
+}
+```
+
+### Features
+
+*   **Read-only optimization**: Streamlined for public access
+*   **Alias support**: URL-friendly note access via aliases
+*   **Share index**: Optional indexing of all shared subtrees
+*   **Minimal memory footprint**: Only shared content cached
+*   **Security isolation**: Separate from main application cache
+
+### Usage Patterns
+
+```typescript
+// Get shared note by ID
+const note = shaca.getNote(noteId);
+
+// Access via alias
+const aliasedNote = shaca.aliasToNote[alias];
+
+// Check if note is shared
+const isShared = shaca.hasNote(noteId);
+```
+
+## Cache Interaction and Data Flow
+
+### 1\. Create/Update Flow
+
+```
+sequenceDiagram
+    participant Client
+    participant Froca
+    participant API
+    participant Becca
+    participant DB
+    
+    Client->>API: Update Note
+    API->>Becca: Update Cache
+    Becca->>DB: Persist Change
+    Becca->>API: Confirm
+    API->>Froca: Push Update (WebSocket)
+    Froca->>Client: Update UI
+```
+
+### 2\. Read Flow
+
+```
+sequenceDiagram
+    participant Client
+    participant Froca
+    participant API
+    participant Becca
+    
+    Client->>Froca: Request Note
+    alt Note in Cache
+        Froca->>Client: Return Cached Note
+    else Note not in Cache
+        Froca->>API: Fetch Note
+        API->>Becca: Get Note
+        Becca->>API: Return Note
+        API->>Froca: Send Note Data
+        Froca->>Froca: Cache Note
+        Froca->>Client: Return Note
+    end
+```
+
+### 3\. Share Access Flow
+
+```
+sequenceDiagram
+    participant Browser
+    participant ShareUI
+    participant Shaca
+    participant DB
+    
+    Browser->>ShareUI: Access Shared URL
+    ShareUI->>Shaca: Get Shared Note
+    alt Note in Cache
+        Shaca->>ShareUI: Return Cached
+    else Not in Cache
+        Shaca->>DB: Load Shared Tree
+        DB->>Shaca: Return Data
+        Shaca->>Shaca: Build Cache
+        Shaca->>ShareUI: Return Note
+    end
+    ShareUI->>Browser: Render Content
+```
+
+## Performance Considerations
+
+### Memory Management
+
+*   **Becca**: Keeps entire note tree in memory (~100-500MB for typical use)
+*   **Froca**: Loads notes on-demand, automatic cleanup of unused notes
+*   **Shaca**: Minimal footprint, only shared content
+
+### Cache Warming
+
+*   **Becca**: Full load on server startup
+*   **Froca**: Progressive loading based on user navigation
+*   **Shaca**: Lazy loading with configurable index
+
+### Optimization Strategies
+
+1.  **Attribute Indexing**: Pre-built indexes for fast attribute queries
+2.  **Batch Operations**: Group updates to minimize round trips
+3.  **Partial Loading**: Load only required fields for lists
+4.  **WebSocket Compression**: Compressed real-time updates
+
+## Best Practices
+
+### When to Use Each Cache
+
+**Use Becca when**:
+
+*   Implementing server-side business logic
+*   Performing bulk operations
+*   Handling synchronization
+*   Managing protected notes
+
+**Use Froca when**:
+
+*   Building UI components
+*   Handling user interactions
+*   Displaying note content
+*   Managing client state
+
+**Use Shaca when**:
+
+*   Serving public content
+*   Building share pages
+*   Implementing read-only access
+*   Creating public APIs
+
+### Cache Invalidation
+
+```typescript
+// Becca - automatic on entity save
+note.save(); // Cache updated automatically
+
+// Froca - manual reload when needed
+await froca.reloadNotes([noteId]);
+
+// Shaca - rebuild on share changes
+shaca.reset();
+shaca.load();
+```
+
+### Error Handling
+
+```typescript
+// Becca - throw on missing required entities
+const note = becca.getNoteOrThrow(noteId); // throws NotFoundError
+
+// Froca - graceful degradation
+const note = await froca.getNote(noteId);
+if (!note) {
+    // Handle missing note
+}
+
+// Shaca - check existence first
+if (shaca.hasNote(noteId)) {
+    const note = shaca.getNote(noteId);
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1.  **Cache Inconsistency**
+    
+    *   Symptom: UI shows outdated data
+    *   Solution: Force reload with `froca.reloadNotes()`
+2.  **Memory Growth**
+    
+    *   Symptom: Server memory usage increases
+    *   Solution: Check for memory leaks in custom scripts
+3.  **Slow Initial Load**
+    
+    *   Symptom: Long startup time
+    *   Solution: Optimize database queries, add indexes
+
+### Debug Commands
+
+```javascript
+// Check cache sizes
+console.log('Becca notes:', Object.keys(becca.notes).length);
+console.log('Froca notes:', Object.keys(froca.notes).length);
+console.log('Shaca notes:', Object.keys(shaca.notes).length);
+
+// Force cache refresh
+await froca.loadInitialTree();
+
+// Clear and reload Shaca
+shaca.reset();
+await shaca.load();
+```
+
+## Related Documentation
+
+*   [Entity System](Entity-System.md) - Detailed entity documentation
+*   [Database Schema](#root/eZcnGfMUmic0) - Database structure
+*   [WebSocket Synchronization](#root/UBgXVlHv3d66) - Real-time updates

docs/Developer Guide/Developer Guide/Architecture/Widget-Based-UI-Architecture.md

@@ -0,0 +1,514 @@
+# Widget-Based-UI-Architecture
+## Widget-Based UI Architecture
+
+Trilium's user interface is built on a widget system where each UI element is a self-contained component. This approach makes the interface modular, allowing developers to create custom widgets and extend the application's functionality.
+
+## Understanding Widgets
+
+Widgets in Trilium form a hierarchy, with each level adding specific capabilities. At the base, every widget is a Component that can have children and communicate with other widgets. The BasicWidget layer adds DOM manipulation, while NoteContextAwareWidget provides automatic updates when notes change.
+
+## Core Widget Classes
+
+### Component (Base Class)
+
+**Location**: `/apps/client/src/components/component.js`
+
+Every UI element in Trilium inherits from Component, which provides the foundation for parent-child relationships and event communication between widgets.
+
+### BasicWidget
+
+**Location**: `/apps/client/src/widgets/basic_widget.ts`
+
+BasicWidget extends Component with DOM manipulation capabilities. It provides a fluent API for styling and composing UI elements:
+
+```typescript
+class MyWidget extends BasicWidget {
+    doRender() {
+        this.$widget = $('<div class="my-widget">');
+        this.$widget.append($('<h3>').text('Title'));
+        return this.$widget;
+    }
+}
+
+// Compose widgets using method chaining
+const container = new FlexContainer('column')
+    .id('main-container')
+    .css('padding', '10px')
+    .child(new MyWidget());
+```
+
+The chaining API makes it easy to build complex UIs declaratively. Methods like `css()`, `class()`, and `child()` return the widget itself, allowing you to chain multiple operations together.
+
+### NoteContextAwareWidget
+
+**Location**: `/apps/client/src/widgets/note_context_aware_widget.ts`
+
+Widgets that need to react to note changes extend NoteContextAwareWidget. This class automatically calls your widget's methods when the active note changes, making it easy to keep the UI synchronized with the current note.
+
+```typescript
+class MyNoteWidget extends NoteContextAwareWidget {
+    async refreshWithNote(note) {
+        // Automatically called when note changes
+        this.$widget.find('.title').text(note.title);
+    }
+}
+```
+
+Key lifecycle methods:
+
+*   `refreshWithNote(note)` - Called when the active note changes
+*   `noteSwitched()` - Called after switching to a different note
+*   `noteTypeMimeChanged()` - Called when the note's type changes
+
+The widget automatically maintains references to the current note, making it simple to build note-aware UI components.
+
+### RightPanelWidget
+
+**Location**: `/apps/client/src/widgets/right_panel_widget.ts`
+
+Widgets in the right sidebar extend RightPanelWidget. These widgets appear as collapsible panels and can show note-specific information or tools.
+
+```typescript
+class InfoWidget extends RightPanelWidget {
+    getTitle() { return "Note Info"; }
+    getIcon() { return "info"; }
+    
+    async doRenderBody() {
+        return $('<div class="info-widget">');
+    }
+    
+    async refreshWithNote(note: FNote) {
+        this.$body.find('.created').text(`Created: ${note.dateCreated}`);
+        this.$body.find('.modified').text(`Modified: ${note.dateModified}`);
+        
+        const wordCount = this.calculateWordCount(await note.getContent());
+        this.$body.find('.word-count').text(`Words: ${wordCount}`);
+    }
+}
+```
+
+## Type-Specific Widgets
+
+**Location**: `/apps/client/src/widgets/type_widgets/`
+
+Each note type has a specialized widget for rendering and editing.
+
+### TypeWidget Interface
+
+```typescript
+abstract class TypeWidget extends NoteContextAwareWidget {
+    abstract static getType(): string;
+    
+    // Content management
+    async getContent(): Promise<string>;
+    async saveContent(content: string): Promise<void>;
+    
+    // Focus management
+    async focus(): Promise<void>;
+    async blur(): Promise<void>;
+    
+    // Cleanup
+    async cleanup(): Promise<void>;
+}
+```
+
+### Common Type Widgets
+
+#### TextTypeWidget
+
+```typescript
+class TextTypeWidget extends TypeWidget {
+    static getType() { return 'text'; }
+    
+    private textEditor: TextEditor;
+    
+    async doRender() {
+        const $editor = $('<div class="ck-editor">');
+        this.textEditor = await TextEditor.create($editor[0], {
+            noteId: this.noteId,
+            content: await this.note.getContent()
+        });
+        
+        return $editor;
+    }
+    
+    async getContent() {
+        return this.textEditor.getData();
+    }
+}
+```
+
+#### CodeTypeWidget
+
+```typescript
+class CodeTypeWidget extends TypeWidget {
+    static getType() { return 'code'; }
+    
+    private codeMirror: CodeMirror;
+    
+    async doRender() {
+        const $container = $('<div class="code-editor">');
+        
+        this.codeMirror = CodeMirror($container[0], {
+            value: await this.note.getContent(),
+            mode: this.note.mime,
+            theme: 'default',
+            lineNumbers: true
+        });
+        
+        return $container;
+    }
+}
+```
+
+## Widget Composition
+
+### Container Widgets
+
+```typescript
+// Flexible container layouts
+class FlexContainer extends BasicWidget {
+    constructor(private direction: 'row' | 'column') {
+        super();
+    }
+    
+    doRender() {
+        this.$widget = $('<div class="flex-container">')
+            .css('display', 'flex')
+            .css('flex-direction', this.direction);
+            
+        for (const child of this.children) {
+            this.$widget.append(child.render());
+        }
+        
+        return this.$widget;
+    }
+}
+
+// Tab container
+class TabContainer extends BasicWidget {
+    private tabs: Array<{title: string, widget: BasicWidget}> = [];
+    
+    addTab(title: string, widget: BasicWidget) {
+        this.tabs.push({title, widget});
+        this.child(widget);
+        return this;
+    }
+    
+    doRender() {
+        // Render tab headers and content panels
+    }
+}
+```
+
+### Composite Widgets
+
+```typescript
+class NoteEditorWidget extends NoteContextAwareWidget {
+    private typeWidget: TypeWidget;
+    private titleWidget: NoteTitleWidget;
+    private toolbarWidget: NoteToolbarWidget;
+    
+    constructor() {
+        super();
+        
+        this.child(
+            this.toolbarWidget = new NoteToolbarWidget(),
+            this.titleWidget = new NoteTitleWidget(),
+            // Type widget added dynamically
+        );
+    }
+    
+    async refreshWithNote(note: FNote) {
+        // Remove old type widget
+        if (this.typeWidget) {
+            this.typeWidget.remove();
+        }
+        
+        // Add appropriate type widget
+        const WidgetClass = typeWidgetService.getWidgetClass(note.type);
+        this.typeWidget = new WidgetClass();
+        this.child(this.typeWidget);
+        
+        await this.typeWidget.refresh();
+    }
+}
+```
+
+## Widget Communication
+
+### Event System
+
+```typescript
+// Publishing events
+class PublisherWidget extends BasicWidget {
+    async handleClick() {
+        // Local event
+        this.trigger('itemSelected', { itemId: '123' });
+        
+        // Global event
+        appContext.triggerEvent('noteChanged', { noteId: this.noteId });
+    }
+}
+
+// Subscribing to events
+class SubscriberWidget extends BasicWidget {
+    constructor() {
+        super();
+        
+        // Local event subscription
+        this.on('itemSelected', (event) => {
+            console.log('Item selected:', event.itemId);
+        });
+        
+        // Global event subscription
+        appContext.addEventListener('noteChanged', (event) => {
+            this.handleNoteChange(event.noteId);
+        });
+    }
+}
+```
+
+### Command System
+
+```typescript
+// Registering commands
+class CommandWidget extends BasicWidget {
+    constructor() {
+        super();
+        
+        this.bindCommand('saveNote', () => this.saveNote());
+        this.bindCommand('deleteNote', () => this.deleteNote());
+    }
+    
+    getCommands() {
+        return [
+            {
+                command: 'myWidget:doAction',
+                handler: () => this.doAction(),
+                hotkey: 'ctrl+shift+a'
+            }
+        ];
+    }
+}
+```
+
+## Custom Widget Development
+
+### Creating Custom Widgets
+
+```typescript
+// 1. Define widget class
+class TaskListWidget extends NoteContextAwareWidget {
+    doRender() {
+        this.$widget = $('<div class="task-list-widget">');
+        this.$list = $('<ul>').appendTo(this.$widget);
+        return this.$widget;
+    }
+    
+    async refreshWithNote(note: FNote) {
+        const tasks = await this.loadTasks(note);
+        
+        this.$list.empty();
+        for (const task of tasks) {
+            $('<li>')
+                .text(task.title)
+                .toggleClass('completed', task.completed)
+                .appendTo(this.$list);
+        }
+    }
+    
+    private async loadTasks(note: FNote) {
+        // Load task data from note attributes
+        const taskLabels = note.getLabels('task');
+        return taskLabels.map(label => JSON.parse(label.value));
+    }
+}
+
+// 2. Register widget
+api.addWidget(TaskListWidget);
+```
+
+### Widget Lifecycle
+
+```typescript
+class LifecycleWidget extends NoteContextAwareWidget {
+    // 1. Construction
+    constructor() {
+        super();
+        console.log('Widget constructed');
+    }
+    
+    // 2. Initial render
+    doRender() {
+        console.log('Initial render');
+        return $('<div>');
+    }
+    
+    // 3. Context initialization
+    async refresh() {
+        console.log('Context refresh');
+        await super.refresh();
+    }
+    
+    // 4. Note updates
+    async refreshWithNote(note: FNote) {
+        console.log('Note refresh:', note.noteId);
+    }
+    
+    // 5. Cleanup
+    async cleanup() {
+        console.log('Widget cleanup');
+        // Release resources
+    }
+}
+```
+
+## Performance Optimization
+
+### Lazy Loading
+
+```typescript
+class LazyWidget extends BasicWidget {
+    private contentLoaded = false;
+    
+    async becomeVisible() {
+        if (!this.contentLoaded) {
+            await this.loadContent();
+            this.contentLoaded = true;
+        }
+    }
+    
+    private async loadContent() {
+        // Heavy content loading
+        const data = await server.get('expensive-data');
+        this.renderContent(data);
+    }
+}
+```
+
+### Debouncing Updates
+
+```typescript
+class DebouncedWidget extends NoteContextAwareWidget {
+    private refreshDebounced = utils.debounce(
+        () => this.doRefresh(),
+        500
+    );
+    
+    async refreshWithNote(note: FNote) {
+        // Debounce rapid updates
+        this.refreshDebounced();
+    }
+    
+    private async doRefresh() {
+        // Actual refresh logic
+    }
+}
+```
+
+### Virtual Scrolling
+
+```typescript
+class VirtualListWidget extends BasicWidget {
+    private visibleItems: any[] = [];
+    
+    renderVisibleItems(scrollTop: number) {
+        const itemHeight = 30;
+        const containerHeight = this.$widget.height();
+        
+        const startIndex = Math.floor(scrollTop / itemHeight);
+        const endIndex = Math.ceil((scrollTop + containerHeight) / itemHeight);
+        
+        this.visibleItems = this.allItems.slice(startIndex, endIndex);
+        this.renderItems();
+    }
+}
+```
+
+## Best Practices
+
+### Widget Design
+
+1.  **Single Responsibility**: Each widget should have one clear purpose
+2.  **Composition over Inheritance**: Use composition for complex UIs
+3.  **Lazy Initialization**: Load resources only when needed
+4.  **Event Cleanup**: Remove event listeners in cleanup()
+
+### State Management
+
+```typescript
+class StatefulWidget extends NoteContextAwareWidget {
+    private state = {
+        isExpanded: false,
+        selectedItems: new Set<string>()
+    };
+    
+    setState(updates: Partial<typeof this.state>) {
+        Object.assign(this.state, updates);
+        this.renderState();
+    }
+    
+    private renderState() {
+        this.$widget.toggleClass('expanded', this.state.isExpanded);
+        // Update DOM based on state
+    }
+}
+```
+
+### Error Handling
+
+```typescript
+class ResilientWidget extends BasicWidget {
+    async refreshWithNote(note: FNote) {
+        try {
+            await this.loadData(note);
+        } catch (error) {
+            this.showError('Failed to load data');
+            console.error('Widget error:', error);
+        }
+    }
+    
+    private showError(message: string) {
+        this.$widget.html(`
+            <div class="alert alert-danger">
+                ${message}
+            </div>
+        `);
+    }
+}
+```
+
+## Testing Widgets
+
+```typescript
+// Widget test example
+describe('TaskListWidget', () => {
+    let widget: TaskListWidget;
+    let note: FNote;
+    
+    beforeEach(() => {
+        widget = new TaskListWidget();
+        note = createMockNote({
+            noteId: 'test123',
+            attributes: [
+                { type: 'label', name: 'task', value: '{"title":"Task 1"}' }
+            ]
+        });
+    });
+    
+    it('should render tasks', async () => {
+        await widget.refreshWithNote(note);
+        
+        const tasks = widget.$widget.find('li');
+        expect(tasks.length).toBe(1);
+        expect(tasks.text()).toBe('Task 1');
+    });
+});
+```
+
+## Related Documentation
+
+*   [Frontend Basics](#root/8Cc2LnZFcF3K) - Frontend scripting guide
+*   [Custom Widgets](#root/VAerafq2qHO1) - Creating custom widgets
+*   [Script API](#root/7Pp4moCrBVzA) - Widget API reference

docs/Developer Guide/Developer Guide/Plugin Development/Custom Widget Development Guid.md

@@ -0,0 +1,694 @@
+# Custom Widget Development Guide
+Widgets are the building blocks of Trilium's user interface. This guide shows you how to create your own widgets to extend Trilium with custom functionality.
+
+## Getting Started
+
+To develop widgets, you'll need basic JavaScript knowledge and familiarity with jQuery. Widgets in Trilium follow a simple hierarchy where each type adds specific capabilities - BasicWidget for general UI, NoteContextAwareWidget for note-responsive widgets, and RightPanelWidget for sidebar panels.
+
+## Creating Your First Widget
+
+### Basic Widget
+
+Start with a simple widget that displays static content:
+
+```javascript
+class MyWidget extends BasicWidget {
+    doRender() {
+        this.$widget = $('<div>Hello from my widget!</div>');
+    }
+}
+```
+
+### Note-Aware Widget
+
+To make your widget respond to note changes, extend NoteContextAwareWidget:
+
+```javascript
+class NoteInfoWidget extends NoteContextAwareWidget {
+    doRender() {
+        this.$widget = $('<div class="note-info"></div>');
+    }
+    
+    async refreshWithNote(note) {
+        this.$widget.html(`
+            <h3>${note.title}</h3>
+            <p>Type: ${note.type}</p>
+        `);
+    }
+}
+```
+
+The `refreshWithNote` method is automatically called whenever the user switches to a different note.
+
+### Right Panel Widget
+
+For widgets in the sidebar, extend RightPanelWidget:
+
+```javascript
+class StatsWidget extends RightPanelWidget {
+    get widgetTitle() { return "Statistics"; }
+    
+    async doRenderBody() {
+        this.$body.html('<div class="stats">Loading...</div>');
+    }
+    
+    async refreshWithNote(note) {
+        const content = await note.getContent();
+        const words = content.split(/\s+/).length;
+        this.$body.find('.stats').text(`Words: ${words}`);
+    }
+}
+```
+
+## Widget Lifecycle
+
+Widgets go through three main phases:
+
+**Initialization**: The `doRender()` method creates your widget's HTML structure. This happens once when the widget is first displayed.
+
+**Updates**: The `refresh()` or `refreshWithNote()` methods update your widget's content. These are called when data changes or the user switches notes.
+
+**Cleanup**: If your widget creates timers or external connections, override `cleanup()` to properly dispose of them.
+
+## Handling Events
+
+Widgets automatically subscribe to events based on method names. Simply define a method ending with "Event" to handle that event:
+
+```javascript
+class ReactiveWidget extends NoteContextAwareWidget {
+    // Triggered when note content changes
+    async noteContentChangedEvent({ noteId }) {
+        if (this.noteId === noteId) {
+            await this.refresh();
+        }
+    }
+    
+    // Triggered when user switches notes
+    async noteSwitchedEvent() {
+        console.log('Switched to:', this.noteId);
+    }
+}
+```
+
+Common events include `noteSwitched`, `noteContentChanged`, and `entitiesReloaded`. The event system ensures your widget stays synchronized with Trilium's state.
+
+## State Management
+
+### Local State
+
+Store widget-specific state in instance properties:
+
+```typescript
+class StatefulWidget extends BasicWidget {
+    constructor() {
+        super();
+        this.isExpanded = false;
+        this.cachedData = null;
+    }
+    
+    toggleExpanded() {
+        this.isExpanded = !this.isExpanded;
+        this.$widget.toggleClass('expanded', this.isExpanded);
+    }
+}
+```
+
+### Persistent State
+
+Use options or attributes for persistent state:
+
+```typescript
+class PersistentWidget extends NoteContextAwareWidget {
+    async saveState(state) {
+        await server.put('options', {
+            name: 'widgetState',
+            value: JSON.stringify(state)
+        });
+    }
+    
+    async loadState() {
+        const option = await server.get('options/widgetState');
+        return option ? JSON.parse(option.value) : {};
+    }
+}
+```
+
+## Accessing Trilium APIs
+
+### Frontend Services
+
+```typescript
+import froca from "../services/froca.js";
+import server from "../services/server.js";
+import linkService from "../services/link.js";
+import toastService from "../services/toast.js";
+import dialogService from "../services/dialog.js";
+
+class ApiWidget extends NoteContextAwareWidget {
+    async doRenderBody() {
+        // Access notes
+        const note = await froca.getNote(this.noteId);
+        
+        // Get attributes
+        const attributes = note.getAttributes();
+        
+        // Create links
+        const $link = await linkService.createLink(note.noteId);
+        
+        // Show notifications
+        toastService.showMessage("Widget loaded");
+        
+        // Open dialogs
+        const result = await dialogService.confirm("Continue?");
+    }
+}
+```
+
+### Server Communication
+
+```typescript
+class ServerWidget extends BasicWidget {
+    async loadData() {
+        // GET request
+        const data = await server.get('custom-api/data');
+        
+        // POST request
+        const result = await server.post('custom-api/process', {
+            noteId: this.noteId,
+            action: 'analyze'
+        });
+        
+        // PUT request
+        await server.put(`notes/${this.noteId}`, {
+            title: 'Updated Title'
+        });
+    }
+}
+```
+
+## Styling Widgets
+
+### Inline Styles
+
+```typescript
+class StyledWidget extends BasicWidget {
+    doRender() {
+        this.$widget = $('<div>');
+        this.css('padding', '10px')
+            .css('background-color', '#f0f0f0')
+            .css('border-radius', '4px');
+    }
+}
+```
+
+### CSS Classes
+
+```typescript
+class ClassedWidget extends BasicWidget {
+    doRender() {
+        this.$widget = $('<div>');
+        this.class('custom-widget')
+            .class('bordered');
+    }
+}
+```
+
+### CSS Blocks
+
+```typescript
+class CSSBlockWidget extends BasicWidget {
+    doRender() {
+        this.$widget = $('<div class="my-widget">Content</div>');
+        
+        this.cssBlock(`
+            .my-widget {
+                padding: 15px;
+                background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+                color: white;
+                border-radius: 8px;
+            }
+            
+            .my-widget:hover {
+                transform: translateY(-2px);
+                box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+            }
+        `);
+    }
+}
+```
+
+## Performance Optimization
+
+### Lazy Loading
+
+```typescript
+class LazyWidget extends NoteContextAwareWidget {
+    constructor() {
+        super();
+        this.dataLoaded = false;
+    }
+    
+    async refreshWithNote(note) {
+        if (!this.isVisible()) {
+            return; // Don't load if not visible
+        }
+        
+        if (!this.dataLoaded) {
+            await this.loadExpensiveData();
+            this.dataLoaded = true;
+        }
+        
+        this.updateDisplay();
+    }
+}
+```
+
+### Debouncing Updates
+
+```typescript
+import SpacedUpdate from "../services/spaced_update.js";
+
+class DebouncedWidget extends NoteContextAwareWidget {
+    constructor() {
+        super();
+        this.spacedUpdate = new SpacedUpdate(async () => {
+            await this.performUpdate();
+        }, 500); // 500ms delay
+    }
+    
+    async handleInput(value) {
+        await this.spacedUpdate.scheduleUpdate();
+    }
+}
+```
+
+### Caching
+
+```typescript
+class CachedWidget extends NoteContextAwareWidget {
+    constructor() {
+        super();
+        this.cache = new Map();
+    }
+    
+    async getProcessedData(noteId) {
+        if (!this.cache.has(noteId)) {
+            const data = await this.processExpensiveOperation(noteId);
+            this.cache.set(noteId, data);
+        }
+        return this.cache.get(noteId);
+    }
+    
+    cleanup() {
+        this.cache.clear();
+    }
+}
+```
+
+## Debugging Widgets
+
+### Console Logging
+
+```typescript
+class DebugWidget extends BasicWidget {
+    doRender() {
+        console.log('Widget rendering', this.componentId);
+        console.time('render');
+        
+        this.$widget = $('<div>');
+        
+        console.timeEnd('render');
+    }
+}
+```
+
+### Error Handling
+
+```typescript
+class SafeWidget extends NoteContextAwareWidget {
+    async refreshWithNote(note) {
+        try {
+            await this.riskyOperation();
+        } catch (error) {
+            console.error('Widget error:', error);
+            this.logRenderingError(error);
+            this.$widget.html('<div class="error">Failed to load</div>');
+        }
+    }
+}
+```
+
+### Development Tools
+
+```typescript
+class DevWidget extends BasicWidget {
+    doRender() {
+        this.$widget = $('<div>');
+        
+        // Add debug information in development
+        if (window.glob.isDev) {
+            this.$widget.attr('data-debug', 'true');
+            this.$widget.append(`
+                <div class="debug-info">
+                    Component ID: ${this.componentId}
+                    Position: ${this.position}
+                </div>
+            `);
+        }
+    }
+}
+```
+
+## Complete Example: Note Statistics Widget
+
+Here's a complete example implementing a custom note statistics widget:
+
+```typescript
+import RightPanelWidget from "../widgets/right_panel_widget.js";
+import server from "../services/server.js";
+import froca from "../services/froca.js";
+import toastService from "../services/toast.js";
+import SpacedUpdate from "../services/spaced_update.js";
+
+class NoteStatisticsWidget extends RightPanelWidget {
+    constructor() {
+        super();
+        
+        // Initialize state
+        this.statistics = {
+            words: 0,
+            characters: 0,
+            paragraphs: 0,
+            readingTime: 0,
+            links: 0,
+            images: 0
+        };
+        
+        // Debounce updates for performance
+        this.spacedUpdate = new SpacedUpdate(async () => {
+            await this.calculateStatistics();
+        }, 300);
+    }
+    
+    get widgetTitle() {
+        return "Note Statistics";
+    }
+    
+    get help() {
+        return {
+            title: "Note Statistics",
+            text: "Displays various statistics about the current note including word count, reading time, and more."
+        };
+    }
+    
+    async doRenderBody() {
+        this.$body.html(`
+            <div class="note-statistics">
+                <div class="stat-group">
+                    <h5>Content</h5>
+                    <div class="stat-item">
+                        <span class="stat-label">Words:</span>
+                        <span class="stat-value" data-stat="words">0</span>
+                    </div>
+                    <div class="stat-item">
+                        <span class="stat-label">Characters:</span>
+                        <span class="stat-value" data-stat="characters">0</span>
+                    </div>
+                    <div class="stat-item">
+                        <span class="stat-label">Paragraphs:</span>
+                        <span class="stat-value" data-stat="paragraphs">0</span>
+                    </div>
+                </div>
+                
+                <div class="stat-group">
+                    <h5>Reading</h5>
+                    <div class="stat-item">
+                        <span class="stat-label">Reading time:</span>
+                        <span class="stat-value" data-stat="readingTime">0 min</span>
+                    </div>
+                </div>
+                
+                <div class="stat-group">
+                    <h5>Elements</h5>
+                    <div class="stat-item">
+                        <span class="stat-label">Links:</span>
+                        <span class="stat-value" data-stat="links">0</span>
+                    </div>
+                    <div class="stat-item">
+                        <span class="stat-label">Images:</span>
+                        <span class="stat-value" data-stat="images">0</span>
+                    </div>
+                </div>
+                
+                <div class="stat-actions">
+                    <button class="btn btn-sm refresh-stats">Refresh</button>
+                    <button class="btn btn-sm export-stats">Export</button>
+                </div>
+            </div>
+        `);
+        
+        this.cssBlock(`
+            .note-statistics {
+                padding: 10px;
+            }
+            
+            .stat-group {
+                margin-bottom: 15px;
+                padding-bottom: 15px;
+                border-bottom: 1px solid var(--main-border-color);
+            }
+            
+            .stat-group:last-child {
+                border-bottom: none;
+            }
+            
+            .stat-group h5 {
+                margin: 0 0 10px 0;
+                color: var(--muted-text-color);
+                font-size: 12px;
+                text-transform: uppercase;
+                letter-spacing: 0.5px;
+            }
+            
+            .stat-item {
+                display: flex;
+                justify-content: space-between;
+                padding: 5px 0;
+            }
+            
+            .stat-label {
+                color: var(--main-text-color);
+            }
+            
+            .stat-value {
+                font-weight: 600;
+                color: var(--primary-color);
+            }
+            
+            .stat-actions {
+                margin-top: 15px;
+                display: flex;
+                gap: 10px;
+            }
+            
+            .stat-actions .btn {
+                flex: 1;
+            }
+        `);
+        
+        // Bind events
+        this.$body.on('click', '.refresh-stats', () => this.handleRefresh());
+        this.$body.on('click', '.export-stats', () => this.handleExport());
+    }
+    
+    async refreshWithNote(note) {
+        if (!note) {
+            this.clearStatistics();
+            return;
+        }
+        
+        // Schedule statistics calculation
+        await this.spacedUpdate.scheduleUpdate();
+    }
+    
+    async calculateStatistics() {
+        try {
+            const note = this.note;
+            if (!note) return;
+            
+            const content = await note.getContent();
+            
+            if (note.type === 'text') {
+                // Parse HTML content
+                const $content = $('<div>').html(content);
+                const textContent = $content.text();
+                
+                // Calculate statistics
+                this.statistics.words = this.countWords(textContent);
+                this.statistics.characters = textContent.length;
+                this.statistics.paragraphs = $content.find('p').length;
+                this.statistics.readingTime = Math.ceil(this.statistics.words / 200);
+                this.statistics.links = $content.find('a').length;
+                this.statistics.images = $content.find('img').length;
+            } else if (note.type === 'code') {
+                // For code notes, count lines and characters
+                const lines = content.split('\n');
+                this.statistics.words = lines.length; // Show lines instead of words
+                this.statistics.characters = content.length;
+                this.statistics.paragraphs = 0;
+                this.statistics.readingTime = 0;
+                this.statistics.links = 0;
+                this.statistics.images = 0;
+            }
+            
+            this.updateDisplay();
+            
+        } catch (error) {
+            console.error('Failed to calculate statistics:', error);
+            toastService.showError("Failed to calculate statistics");
+        }
+    }
+    
+    countWords(text) {
+        const words = text.match(/\b\w+\b/g);
+        return words ? words.length : 0;
+    }
+    
+    clearStatistics() {
+        this.statistics = {
+            words: 0,
+            characters: 0,
+            paragraphs: 0,
+            readingTime: 0,
+            links: 0,
+            images: 0
+        };
+        this.updateDisplay();
+    }
+    
+    updateDisplay() {
+        this.$body.find('[data-stat="words"]').text(this.statistics.words);
+        this.$body.find('[data-stat="characters"]').text(this.statistics.characters);
+        this.$body.find('[data-stat="paragraphs"]').text(this.statistics.paragraphs);
+        this.$body.find('[data-stat="readingTime"]').text(`${this.statistics.readingTime} min`);
+        this.$body.find('[data-stat="links"]').text(this.statistics.links);
+        this.$body.find('[data-stat="images"]').text(this.statistics.images);
+    }
+    
+    async handleRefresh() {
+        await this.calculateStatistics();
+        toastService.showMessage("Statistics refreshed");
+    }
+    
+    async handleExport() {
+        const note = this.note;
+        if (!note) return;
+        
+        const exportData = {
+            noteId: note.noteId,
+            title: note.title,
+            statistics: this.statistics,
+            timestamp: new Date().toISOString()
+        };
+        
+        // Create a CSV
+        const csv = [
+            'Metric,Value',
+            `Words,${this.statistics.words}`,
+            `Characters,${this.statistics.characters}`,
+            `Paragraphs,${this.statistics.paragraphs}`,
+            `Reading Time,${this.statistics.readingTime} minutes`,
+            `Links,${this.statistics.links}`,
+            `Images,${this.statistics.images}`
+        ].join('\n');
+        
+        // Download CSV
+        const blob = new Blob([csv], { type: 'text/csv' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = `statistics-${note.noteId}.csv`;
+        a.click();
+        URL.revokeObjectURL(url);
+        
+        toastService.showMessage("Statistics exported");
+    }
+    
+    async noteContentChangedEvent({ noteId }) {
+        if (this.noteId === noteId) {
+            await this.spacedUpdate.scheduleUpdate();
+        }
+    }
+    
+    cleanup() {
+        this.$body.off('click');
+        this.spacedUpdate = null;
+    }
+}
+
+export default NoteStatisticsWidget;
+```
+
+## Best Practices
+
+### 1\. Memory Management
+
+*   Clean up event listeners in `cleanup()`
+*   Clear caches and timers when widget is destroyed
+*   Avoid circular references
+
+### 2\. Performance
+
+*   Use debouncing for frequent updates
+*   Implement lazy loading for expensive operations
+*   Cache computed values when appropriate
+
+### 3\. Error Handling
+
+*   Always wrap async operations in try-catch
+*   Provide user feedback for errors
+*   Log errors for debugging
+
+### 4\. User Experience
+
+*   Show loading states for async operations
+*   Provide clear error messages
+*   Ensure widgets are responsive
+
+### 5\. Code Organization
+
+*   Keep widgets focused on a single responsibility
+*   Extract reusable logic into services
+*   Use composition over inheritance when possible
+
+## Troubleshooting
+
+### Widget Not Rendering
+
+*   Check `doRender()` creates `this.$widget`
+*   Verify widget is properly registered
+*   Check console for errors
+
+### Events Not Firing
+
+*   Ensure event method name matches pattern: `${eventName}Event`
+*   Check event is being triggered
+*   Verify widget is active/visible
+
+### State Not Persisting
+
+*   Use options or attributes for persistence
+*   Check save operations complete successfully
+*   Verify data serialization
+
+### Performance Issues
+
+*   Profile with browser dev tools
+*   Implement caching and debouncing
+*   Optimize DOM operations
+
+## Next Steps
+
+*   Explore existing widgets in `/apps/client/src/widgets/` for examples
+*   Review the Frontend Script API documentation
+*   Join the Trilium community for support and sharing widgets

docs/User Guide/User Guide/Advanced Usage/Search/Advanced-Search-Expressions.md

@@ -0,0 +1,465 @@
+# Advanced-Search-Expressions
+## Advanced Search Expressions
+
+This guide covers complex search expressions that combine multiple criteria, use advanced operators, and leverage Trilium's relationship system for sophisticated queries.
+
+## Complex Query Construction
+
+### Boolean Logic with Parentheses
+
+Use parentheses to group expressions and control evaluation order:
+
+```
+(#book OR #article) AND #author=Tolkien
+```
+
+Finds notes that are either books or articles, written by Tolkien.
+
+```
+#project AND (#status=active OR #status=pending)
+```
+
+Finds active or pending projects.
+
+```
+meeting AND (#priority=high OR #urgent) AND note.dateCreated >= TODAY-7
+```
+
+Finds recent high-priority or urgent meetings.
+
+### Negation Patterns
+
+Use `NOT` or the `not()` function to exclude certain criteria:
+
+```
+#book AND not(#genre=fiction)
+```
+
+Finds non-fiction books.
+
+```
+project AND not(note.isArchived=true)
+```
+
+Finds non-archived notes containing "project".
+
+```
+#!completed
+```
+
+Short syntax for notes without the "completed" label.
+
+### Mixed Search Types
+
+Combine full-text, attribute, and property searches:
+
+```
+development #category=work note.type=text note.dateModified >= TODAY-30
+```
+
+Finds text notes about development, categorized as work, modified in the last 30 days.
+
+## Advanced Attribute Searches
+
+### Fuzzy Attribute Matching
+
+When fuzzy attribute search is enabled, you can use partial matches:
+
+```
+#lang
+```
+
+Matches labels like "language", "languages", "programming-lang", etc.
+
+```
+#category=prog
+```
+
+Matches categories like "programming", "progress", "program", etc.
+
+### Multiple Attribute Conditions
+
+```
+#book #author=Tolkien #publicationYear>=1950 #publicationYear<1960
+```
+
+Finds Tolkien's books published in the 1950s.
+
+```
+#task #priority=high #status!=completed
+```
+
+Finds high-priority incomplete tasks.
+
+### Complex Label Value Patterns
+
+Use various operators for sophisticated label matching:
+
+```
+#isbn %= '978-[0-9-]+' 
+```
+
+Finds notes with ISBN labels matching the pattern (regex).
+
+```
+#email *=* @company.com
+```
+
+Finds notes with email labels containing "@company.com".
+
+```
+#version >= 2.0
+```
+
+Finds notes with version labels of 2.0 or higher (numeric comparison).
+
+## Relationship Traversal
+
+### Basic Relation Queries
+
+```
+~author.title *=* Tolkien
+```
+
+Finds notes with an "author" relation to notes containing "Tolkien" in the title.
+
+```
+~project.labels.status = active
+```
+
+Finds notes related to projects with active status.
+
+### Multi-Level Relationships
+
+```
+~author.relations.publisher.title = "Penguin Books"
+```
+
+Finds notes authored by someone published by Penguin Books.
+
+```
+~project.children.title *=* documentation
+```
+
+Finds notes related to projects that have child notes about documentation.
+
+### Relationship Direction
+
+```
+note.children.title = "Chapter 1"
+```
+
+Finds parent notes that have a child titled "Chapter 1".
+
+```
+note.parents.labels.category = book
+```
+
+Finds notes whose parents are categorized as books.
+
+```
+note.ancestors.title = "Literature"
+```
+
+Finds notes with "Literature" anywhere in their ancestor chain.
+
+## Property-Based Searches
+
+### Note Metadata Queries
+
+```
+note.type=code note.mime=text/javascript note.dateCreated >= MONTH
+```
+
+Finds JavaScript code notes created this month.
+
+```
+note.isProtected=true note.contentSize > 1000
+```
+
+Finds large protected notes.
+
+```
+note.childrenCount >= 10 note.type=text
+```
+
+Finds text notes with many children.
+
+### Advanced Property Combinations
+
+```
+note.parentCount > 1 #template
+```
+
+Finds template notes that are cloned in multiple places.
+
+```
+note.attributeCount > 5 note.type=text note.contentSize < 500
+```
+
+Finds small text notes with many attributes (heavily tagged short notes).
+
+```
+note.revisionCount > 10 note.dateModified >= TODAY-7
+```
+
+Finds frequently edited notes modified recently.
+
+## Date and Time Expressions
+
+### Relative Date Calculations
+
+```
+#dueDate <= TODAY+7 #dueDate >= TODAY
+```
+
+Finds tasks due in the next week.
+
+```
+note.dateCreated >= MONTH-2 note.dateCreated < MONTH
+```
+
+Finds notes created in the past two months.
+
+```
+#eventDate = YEAR note.dateCreated >= YEAR-1
+```
+
+Finds events scheduled for this year that were planned last year.
+
+### Complex Date Logic
+
+```
+(#startDate <= TODAY AND #endDate >= TODAY) OR #status=ongoing
+```
+
+Finds current events or ongoing items.
+
+```
+#reminderDate <= NOW+3600 #reminderDate > NOW
+```
+
+Finds reminders due in the next hour (using seconds offset).
+
+## Fuzzy Search Techniques
+
+### Fuzzy Exact Matching
+
+```
+#title ~= managment
+```
+
+Finds notes with titles like "management" even with typos.
+
+```
+~category.title ~= progaming
+```
+
+Finds notes related to categories like "programming" with misspellings.
+
+### Fuzzy Contains Matching
+
+```
+note.content ~* algoritm
+```
+
+Finds notes containing words like "algorithm" with spelling variations.
+
+```
+#description ~* recieve
+```
+
+Finds notes with descriptions containing "receive" despite the common misspelling.
+
+### Progressive Fuzzy Strategy
+
+By default, Trilium uses exact matching first, then fuzzy as fallback:
+
+```
+development project
+```
+
+First finds exact matches for "development" and "project", then adds fuzzy matches if needed.
+
+To force fuzzy behavior:
+
+```
+#title ~= development #category ~= projet
+```
+
+## Ordering and Limiting
+
+### Multiple Sort Criteria
+
+```
+#book orderBy #publicationYear desc, note.title asc limit 20
+```
+
+Orders books by publication year (newest first), then by title alphabetically, limited to 20 results.
+
+```
+#task orderBy #priority desc, #dueDate asc
+```
+
+Orders tasks by priority (high first), then by due date (earliest first).
+
+### Dynamic Ordering
+
+```
+#meeting note.dateCreated >= TODAY-30 orderBy note.dateModified desc
+```
+
+Finds recent meetings ordered by last modification.
+
+```
+#project #status=active orderBy note.childrenCount desc limit 10
+```
+
+Finds the 10 most complex active projects (by number of sub-notes).
+
+## Performance Optimization Patterns
+
+### Efficient Query Structure
+
+Start with the most selective criteria:
+
+```
+#book #author=Tolkien note.dateCreated >= 1950-01-01
+```
+
+Better than:
+
+```
+note.dateCreated >= 1950-01-01 #book #author=Tolkien
+```
+
+### Fast Search for Large Datasets
+
+```
+#category=project #status=active
+```
+
+With fast search enabled, this searches only attributes, not content.
+
+### Limiting Expensive Operations
+
+```
+note.content *=* "complex search term" limit 50
+```
+
+Limits content search to prevent performance issues.
+
+## Error Handling and Debugging
+
+### Syntax Validation
+
+Invalid syntax produces helpful error messages:
+
+```
+#book AND OR #author=Tolkien
+```
+
+Error: "Mixed usage of AND/OR - always use parentheses to group AND/OR expressions."
+
+### Debug Mode
+
+Enable debug mode to see how queries are parsed:
+
+```
+#book #author=Tolkien
+```
+
+With debug enabled, shows the internal expression tree structure.
+
+### Common Pitfalls
+
+*   Unescaped special characters: Use quotes or backslashes
+*   Missing parentheses in complex boolean expressions
+*   Incorrect property names: Use `note.title` not `title`
+*   Case sensitivity assumptions: All searches are case-insensitive
+
+## Expression Shortcuts
+
+### Label Shortcuts
+
+Full syntax:
+
+```
+note.labels.category = book
+```
+
+Shortcut:
+
+```
+#category = book
+```
+
+### Relation Shortcuts
+
+Full syntax:
+
+```
+note.relations.author.title *=* Tolkien
+```
+
+Shortcut:
+
+```
+~author.title *=* Tolkien
+```
+
+### Property Shortcuts
+
+Some properties have convenient shortcuts:
+
+```
+note.text *=* content
+```
+
+Searches both title and content for "content".
+
+## Real-World Complex Examples
+
+### Project Management
+
+```
+(#project OR #task) AND #status!=completed AND 
+(#priority=high OR #dueDate <= TODAY+7) AND 
+not(note.isArchived=true) 
+orderBy #priority desc, #dueDate asc
+```
+
+### Research Organization
+
+```
+(#paper OR #article OR #book) AND 
+~author.title *=* smith AND 
+#topic *=* "machine learning" AND 
+note.dateCreated >= YEAR-2 
+orderBy #citationCount desc limit 25
+```
+
+### Content Management
+
+```
+note.type=text AND note.contentSize > 5000 AND 
+#category=documentation AND note.childrenCount >= 3 AND 
+note.dateModified >= MONTH-1 
+orderBy note.dateModified desc
+```
+
+### Knowledge Base Maintenance
+
+```
+note.attributeCount = 0 AND note.childrenCount = 0 AND 
+note.parentCount = 1 AND note.contentSize < 100 AND 
+note.dateModified < TODAY-90
+```
+
+Finds potential cleanup candidates: small, untagged, isolated notes not modified in 90 days.
+
+## Next Steps
+
+*   [Search Examples and Use Cases](Search-Examples-and-Use-Cases.md) - Practical applications
+*   [Saved Searches](Saved-Searches.md) - Creating reusable search configurations
+*   [Technical Search Details](Technical-Search-Details.md) - Implementation details and performance tuning

docs/User Guide/User Guide/Advanced Usage/Search/README.md

@@ -0,0 +1,160 @@
+# README
+## Trilium Search Documentation
+
+Welcome to the comprehensive guide for Trilium's powerful search capabilities. This documentation covers everything from basic text searches to advanced query expressions and performance optimization.
+
+## Quick Start
+
+New to Trilium search? Start here:
+
+*   **[Search Fundamentals](Search-Fundamentals.md)** - Basic concepts, syntax, and operators
+
+## Documentation Sections
+
+### Core Search Features
+
+*   **[Search Fundamentals](Search-Fundamentals.md)** - Basic search syntax, operators, and concepts
+*   **[Advanced Search Expressions](Advanced-Search-Expressions.md)** - Complex queries, boolean logic, and relationship traversal
+
+### Practical Applications
+
+*   **[Search Examples and Use Cases](Search-Examples-and-Use-Cases.md)** - Real-world examples for common workflows
+*   **[Saved Searches](Saved-Searches.md)** - Creating dynamic collections and dashboards
+
+### Technical Reference
+
+*   **[Technical Search Details](Technical-Search-Details.md)** - Performance, implementation, and optimization
+
+## Key Search Capabilities
+
+### Full-Text Search
+
+*   Search note titles and content
+*   Exact phrase matching with quotes
+*   Case-insensitive with diacritic normalization
+*   Support for multiple note types (text, code, mermaid, canvas)
+
+### Attribute-Based Search
+
+*   Label searches: `#tag`, `#category=book`
+*   Relation searches: `~author`, `~author.title=Tolkien`
+*   Complex attribute combinations
+*   Fuzzy attribute matching
+
+### Property Search
+
+*   Note metadata: `note.type=text`, `note.dateCreated >= TODAY-7`
+*   Hierarchical queries: `note.parents.title=Books`
+*   Relationship traversal: `note.children.labels.status=active`
+
+### Advanced Features
+
+*   **Progressive Search**: Exact matching first, fuzzy fallback when needed
+*   **Fuzzy Search**: Typo tolerance and spelling variations
+*   **Boolean Logic**: Complex AND/OR/NOT combinations
+*   **Date Arithmetic**: Dynamic date calculations (TODAY-30, YEAR+1)
+*   **Regular Expressions**: Pattern matching with `%=` operator
+*   **Ordering and Limiting**: Custom sort orders and result limits
+
+## Search Operators Quick Reference
+
+### Text Operators
+
+*   `=` - Exact match
+*   `!=` - Not equal
+*   `*=*` - Contains
+*   `=*` - Starts with
+*   `*=` - Ends with
+*   `%=` - Regular expression
+*   `~=` - Fuzzy exact match
+*   `~*` - Fuzzy contains match
+
+### Numeric Operators
+
+*   `=`, `!=`, `>`, `>=`, `<`, `<=`
+
+### Boolean Operators
+
+*   `AND`, `OR`, `NOT`
+
+### Special Syntax
+
+*   `#labelName` - Label exists
+*   `#labelName=value` - Label equals value
+*   `~relationName` - Relation exists
+*   `~relationName.property` - Relation target property
+*   `note.property` - Note property access
+*   `"exact phrase"` - Quoted phrase search
+
+## Common Search Patterns
+
+### Simple Searches
+
+```
+hello world          # Find notes containing both words
+"project management" # Find exact phrase
+#task               # Find notes with "task" label
+~author             # Find notes with "author" relation
+```
+
+### Attribute Searches
+
+```
+#book #author=Tolkien           # Books by Tolkien
+#task #priority=high #status!=completed  # High-priority incomplete tasks
+~project.title *=* alpha        # Notes related to projects with "alpha" in title
+```
+
+### Date-Based Searches
+
+```
+note.dateCreated >= TODAY-7     # Notes created in last week
+#dueDate <= TODAY+30            # Items due in next 30 days
+#eventDate = YEAR               # Events scheduled for this year
+```
+
+### Complex Queries
+
+```
+(#book OR #article) AND #topic=programming AND note.dateModified >= MONTH
+#project AND (#status=active OR #status=pending) AND not(note.isArchived=true)
+```
+
+## Getting Started Checklist
+
+1.  **Learn Basic Syntax** - Start with simple text and tag searches
+2.  **Understand Operators** - Master the core operators (`=`, `*=*`, etc.)
+3.  **Practice Attributes** - Use `#` for labels and `~` for relations
+4.  **Try Boolean Logic** - Combine searches with AND/OR/NOT
+5.  **Explore Properties** - Use `note.` prefix for metadata searches
+6.  **Create Saved Searches** - Turn useful queries into dynamic collections
+7.  **Optimize Performance** - Learn about fast search and limits
+
+## Performance Tips
+
+*   **Use Fast Search** for attribute-only queries
+*   **Set Reasonable Limits** to prevent large result sets
+*   **Start Specific** with the most selective criteria first
+*   **Leverage Attributes** instead of content search when possible
+*   **Cache Common Queries** as saved searches
+
+## Need Help?
+
+*   **Examples**: Check [Search Examples and Use Cases](Search-Examples-and-Use-Cases.md) for practical patterns
+*   **Complex Queries**: See [Advanced Search Expressions](Advanced-Search-Expressions.md) for sophisticated techniques
+*   **Performance Issues**: Review [Technical Search Details](Technical-Search-Details.md) for optimization
+*   **Dynamic Collections**: Learn about [Saved Searches](Saved-Searches.md) for automated organization
+
+## Search Workflow Integration
+
+Trilium's search integrates seamlessly with your note-taking workflow:
+
+*   **Quick Search** (Ctrl+S) for instant access
+*   **Saved Searches** for dynamic organization
+*   **Search from Subtree** for focused queries
+*   **Auto-complete** suggestions in search dialogs
+*   **URL-triggered searches** for bookmarkable queries
+
+Start with the fundamentals and gradually explore advanced features as your needs grow. Trilium's search system is designed to scale from simple text queries to sophisticated knowledge management systems.
+
+Happy searching! 🔍

docs/User Guide/User Guide/Advanced Usage/Search/Saved-Searches.md

@@ -0,0 +1,429 @@
+# Saved-Searches
+## Saved Searches
+
+Saved searches in Trilium allow you to create dynamic collections of notes that automatically update based on search criteria. They appear as special notes in your tree and provide a powerful way to organize and access related content.
+
+## Understanding Saved Searches
+
+A saved search is a special note type that:
+
+*   Stores search criteria and configuration
+*   Dynamically displays matching notes as children
+*   Updates automatically when notes change
+*   Can be bookmarked and accessed like any other note
+*   Supports all search features including ordering and limits
+
+## Creating Saved Searches
+
+### From Search Dialog
+
+1.  Open the search dialog (Ctrl+S or search icon)
+2.  Configure your search criteria and options
+3.  Click "Save to note" button
+4.  Choose a name and location for the saved search
+
+### Manual Creation
+
+1.  Create a new note and set its type to "Saved Search"
+2.  Configure the search using labels:
+    *   `#searchString` - The search query
+    *   `#fastSearch` - Enable fast search mode
+    *   `#includeArchivedNotes` - Include archived notes
+    *   `#orderBy` - Sort field
+    *   `#orderDirection` - "asc" or "desc"
+    *   `#limit` - Maximum number of results
+
+### Using Search Scripts
+
+For complex logic, create a JavaScript note and link it:
+
+*   `~searchScript` - Relation pointing to a backend script note
+
+## Basic Saved Search Examples
+
+### Simple Text Search
+
+```
+#searchString=project management
+```
+
+Finds all notes containing "project management".
+
+### Tag-Based Collection
+
+```
+#searchString=#book #author=Tolkien
+#orderBy=publicationYear
+#orderDirection=desc
+```
+
+Creates a collection of Tolkien's books ordered by publication year.
+
+### Task Dashboard
+
+```
+#searchString=#task #status!=completed #assignee=me
+#orderBy=priority
+#orderDirection=desc
+#limit=20
+```
+
+Shows your top 20 incomplete tasks by priority.
+
+### Recent Activity
+
+```
+#searchString=note.dateModified >= TODAY-7
+#orderBy=dateModified
+#orderDirection=desc
+#limit=50
+```
+
+Shows the 50 most recently modified notes from the last week.
+
+## Advanced Saved Search Patterns
+
+### Dynamic Date-Based Collections
+
+#### This Week's Content
+
+```
+#searchString=note.dateCreated >= TODAY-7 note.dateCreated < TODAY
+#orderBy=dateCreated
+#orderDirection=desc
+```
+
+#### Monthly Review Collection
+
+```
+#searchString=#reviewed=false note.dateCreated >= MONTH note.dateCreated < MONTH+1
+#orderBy=dateCreated
+```
+
+#### Upcoming Deadlines
+
+```
+#searchString=#dueDate >= TODAY #dueDate <= TODAY+14 #status!=completed
+#orderBy=dueDate
+#orderDirection=asc
+```
+
+### Project-Specific Collections
+
+#### Project Dashboard
+
+```
+#searchString=#project=alpha (#task OR #milestone OR #document)
+#orderBy=priority
+#orderDirection=desc
+```
+
+#### Project Health Monitor
+
+```
+#searchString=#project=alpha #status=blocked OR (#dueDate < TODAY #status!=completed)
+#orderBy=dueDate
+#orderDirection=asc
+```
+
+### Content Type Collections
+
+#### Documentation Hub
+
+```
+#searchString=(#documentation OR #guide OR #manual) #product=api
+#orderBy=dateModified
+#orderDirection=desc
+```
+
+#### Learning Path
+
+```
+#searchString=#course #level=beginner #topic=programming
+#orderBy=difficulty
+#orderDirection=asc
+```
+
+## Search Script Examples
+
+For complex logic that can't be expressed in search strings, use JavaScript:
+
+### Custom Business Logic
+
+```javascript
+// Find notes that need attention based on complex criteria
+const api = require('api');
+
+const cutoffDate = new Date();
+cutoffDate.setDate(cutoffDate.getDate() - 30);
+
+const results = [];
+
+// Find high-priority tasks overdue by more than a week
+const overdueTasks = api.searchForNotes(`
+    #task #priority=high #dueDate < TODAY-7 #status!=completed
+`);
+
+// Find projects with no recent activity
+const staleProjets = api.searchForNotes(`
+    #project #status=active note.dateModified < TODAY-30
+`);
+
+// Find notes with many attributes but no content
+const overlabeledNotes = api.searchForNotes(`
+    note.attributeCount > 5 note.contentSize < 100
+`);
+
+return [...overdueTasks, ...staleProjects, ...overlabeledNotes]
+    .map(note => note.noteId);
+```
+
+### Dynamic Tag-Based Grouping
+
+```javascript
+// Group notes by quarter based on creation date
+const api = require('api');
+
+const currentYear = new Date().getFullYear();
+const results = [];
+
+for (let quarter = 1; quarter <= 4; quarter++) {
+    const startMonth = (quarter - 1) * 3 + 1;
+    const endMonth = quarter * 3;
+    
+    const quarterNotes = api.searchForNotes(`
+        note.dateCreated >= "${currentYear}-${String(startMonth).padStart(2, '0')}-01"
+        note.dateCreated < "${currentYear}-${String(endMonth + 1).padStart(2, '0')}-01"
+        #project
+    `);
+    
+    results.push(...quarterNotes.map(note => note.noteId));
+}
+
+return results;
+```
+
+### Conditional Search Logic
+
+```javascript
+// Smart dashboard that changes based on day of week
+const api = require('api');
+
+const today = new Date();
+const dayOfWeek = today.getDay(); // 0 = Sunday, 1 = Monday, etc.
+
+let searchQuery;
+
+if (dayOfWeek === 1) { // Monday - weekly planning
+    searchQuery = '#task #status=planned #week=' + getWeekNumber(today);
+} else if (dayOfWeek === 5) { // Friday - weekly review
+    searchQuery = '#task #completed=true #week=' + getWeekNumber(today);
+} else { // Regular days - focus on today's work
+    searchQuery = '#task #dueDate=TODAY #status!=completed';
+}
+
+const notes = api.searchForNotes(searchQuery);
+return notes.map(note => note.noteId);
+
+function getWeekNumber(date) {
+    const firstDay = new Date(date.getFullYear(), 0, 1);
+    const pastDays = Math.floor((date - firstDay) / 86400000);
+    return Math.ceil((pastDays + firstDay.getDay() + 1) / 7);
+}
+```
+
+## Performance Optimization
+
+### Fast Search for Large Collections
+
+For collections that don't need content search:
+
+```
+#searchString=#category=reference #type=article
+#fastSearch=true
+#limit=100
+```
+
+### Efficient Ordering
+
+Use indexed properties for better performance:
+
+```
+#orderBy=dateCreated
+#orderBy=title
+#orderBy=noteId
+```
+
+Avoid complex calculated orderings in large collections.
+
+### Result Limiting
+
+Always set reasonable limits for large collections:
+
+```
+#limit=50
+```
+
+For very large result sets, consider breaking into multiple saved searches.
+
+## Saved Search Organization
+
+### Hierarchical Organization
+
+Create a folder structure for saved searches:
+
+```
+📁 Searches
+├── 📁 Projects
+│   ├── 🔍 Active Projects
+│   ├── 🔍 Overdue Tasks  
+│   └── 🔍 Project Archive
+├── 📁 Content
+│   ├── 🔍 Recent Drafts
+│   ├── 🔍 Published Articles
+│   └── 🔍 Review Queue
+└── 📁 Maintenance
+    ├── 🔍 Untagged Notes
+    ├── 🔍 Cleanup Candidates
+    └── 🔍 Orphaned Notes
+```
+
+### Search Naming Conventions
+
+Use clear, descriptive names:
+
+*   "Active High-Priority Tasks"
+*   "This Month's Meeting Notes"
+*   "Unprocessed Inbox Items"
+*   "Literature Review Papers"
+
+### Search Labels
+
+Tag saved searches for organization:
+
+```
+#searchType=dashboard
+#searchType=maintenance  
+#searchType=archive
+#frequency=daily
+#frequency=weekly
+```
+
+## Dashboard Creation
+
+### Personal Dashboard
+
+Combine multiple saved searches in a parent note:
+
+```
+📋 My Dashboard
+├── 🔍 Today's Tasks
+├── 🔍 Urgent Items
+├── 🔍 Recent Notes
+├── 🔍 Upcoming Deadlines
+└── 🔍 Weekly Review Items
+```
+
+### Project Dashboard
+
+```
+📋 Project Alpha Dashboard  
+├── 🔍 Active Tasks
+├── 🔍 Blocked Items
+├── 🔍 Recent Updates
+├── 🔍 Milestones
+└── 🔍 Team Notes
+```
+
+### Content Dashboard
+
+```
+📋 Content Management
+├── 🔍 Draft Articles
+├── 🔍 Review Queue
+├── 🔍 Published This Month
+├── 🔍 High-Engagement Posts
+└── 🔍 Content Ideas
+```
+
+## Maintenance and Updates
+
+### Regular Review
+
+Periodically review saved searches for:
+
+*   Outdated search criteria
+*   Performance issues
+*   Unused collections
+*   Scope creep
+
+### Search Evolution
+
+As your note-taking evolves, update searches:
+
+*   Add new tags to existing searches
+*   Refine criteria based on usage patterns
+*   Split large collections into smaller ones
+*   Merge rarely-used collections
+
+### Performance Monitoring
+
+Watch for performance issues:
+
+*   Slow-loading saved searches
+*   Memory usage with large result sets
+*   Search timeout errors
+
+## Troubleshooting
+
+### Common Issues
+
+#### Empty Results
+
+*   Check search syntax
+*   Verify tag spellings
+*   Ensure notes have required attributes
+*   Test search components individually
+
+#### Performance Problems
+
+*   Add `#fastSearch=true` for attribute-only searches
+*   Reduce result limits
+*   Simplify complex criteria
+*   Use indexed properties for ordering
+
+#### Unexpected Results
+
+*   Enable debug mode to see query parsing
+*   Test search in search dialog first
+*   Check for case sensitivity issues
+*   Verify date formats and ranges
+
+### Best Practices
+
+#### Search Design
+
+*   Start simple and add complexity gradually
+*   Test searches thoroughly before saving
+*   Document complex search logic
+*   Use meaningful names and descriptions
+
+#### Performance
+
+*   Set appropriate limits
+*   Use fast search when possible
+*   Avoid overly complex expressions
+*   Monitor search execution time
+
+#### Organization
+
+*   Group related searches
+*   Use consistent naming conventions
+*   Archive unused searches
+*   Regular cleanup and maintenance
+
+## Next Steps
+
+*   [Technical Search Details](Technical-Search-Details.md) - Understanding search performance and implementation
+*   [Search Examples and Use Cases](Search-Examples-and-Use-Cases.md) - More practical examples
+*   [Advanced Search Expressions](Advanced-Search-Expressions.md) - Complex query construction

docs/User Guide/User Guide/Advanced Usage/Search/Search-Examples-and-Use-Cases.md

@@ -0,0 +1,539 @@
+# Search-Examples-and-Use-Cases
+## Search Examples and Use Cases
+
+This guide provides practical examples of how to use Trilium's search capabilities for common organizational patterns and workflows.
+
+## Personal Knowledge Management
+
+### Research and Learning
+
+Track your learning progress and find related materials:
+
+```
+#topic=javascript #status=learning
+```
+
+Find all JavaScript materials you're currently learning.
+
+```
+#course #completed=false note.dateCreated >= MONTH-1
+```
+
+Find courses started in the last month that aren't completed.
+
+```
+#book #topic *=* programming #rating >= 4
+```
+
+Find highly-rated programming books.
+
+```
+#paper ~author.title *=* "Andrew Ng" #field=machine-learning
+```
+
+Find machine learning papers by Andrew Ng.
+
+### Meeting and Event Management
+
+Organize meetings, notes, and follow-ups:
+
+```
+#meeting note.dateCreated >= TODAY-7 #attendee *=* smith
+```
+
+Find this week's meetings with Smith.
+
+```
+#meeting #actionItems #status!=completed
+```
+
+Find meetings with outstanding action items.
+
+```
+#event #date >= TODAY #date <= TODAY+30
+```
+
+Find upcoming events in the next 30 days.
+
+```
+#meeting #project=alpha note.dateCreated >= MONTH
+```
+
+Find this month's meetings about project alpha.
+
+### Note Organization and Cleanup
+
+Maintain and organize your note structure:
+
+```
+note.childrenCount = 0 note.parentCount = 1 note.contentSize < 50 note.dateModified < TODAY-180
+```
+
+Find small, isolated notes not modified in 6 months (cleanup candidates).
+
+```
+note.attributeCount = 0 note.type=text note.contentSize > 1000
+```
+
+Find large text notes without any labels (might need categorization).
+
+```
+#draft note.dateCreated < TODAY-30
+```
+
+Find old draft notes that might need attention.
+
+```
+note.parentCount > 3 note.type=text
+```
+
+Find notes that are heavily cloned (might indicate important content).
+
+## Project Management
+
+### Task Tracking
+
+Manage tasks and project progress:
+
+```
+#task #priority=high #status!=completed #assignee=me
+```
+
+Find your high-priority incomplete tasks.
+
+```
+#task #dueDate <= TODAY+3 #dueDate >= TODAY #status!=completed
+```
+
+Find tasks due in the next 3 days.
+
+```
+#project=website #task #status=blocked
+```
+
+Find blocked tasks in the website project.
+
+```
+#task #estimatedHours > 0 #actualHours > 0 orderBy note.dateModified desc
+```
+
+Find tasks with time tracking data, sorted by recent updates.
+
+### Project Oversight
+
+Monitor project health and progress:
+
+```
+#project #status=active note.children.labels.status = blocked
+```
+
+Find active projects with blocked tasks.
+
+```
+#project #startDate <= TODAY-90 #status!=completed
+```
+
+Find projects that started over 90 days ago but aren't completed.
+
+```
+#milestone #targetDate <= TODAY #status!=achieved
+```
+
+Find overdue milestones.
+
+```
+#project orderBy note.childrenCount desc limit 10
+```
+
+Find the 10 largest projects by number of sub-notes.
+
+### Resource Planning
+
+Track resources and dependencies:
+
+```
+#resource #type=person #availability < 50
+```
+
+Find people with low availability.
+
+```
+#dependency #status=pending #project=mobile-app
+```
+
+Find pending dependencies for the mobile app project.
+
+```
+#budget #project #spent > #allocated
+```
+
+Find projects over budget.
+
+## Content Creation and Writing
+
+### Writing Projects
+
+Manage articles, books, and documentation:
+
+```
+#article #status=draft #wordCount >= 1000
+```
+
+Find substantial draft articles.
+
+```
+#chapter #book=novel #status=outline
+```
+
+Find novel chapters still in outline stage.
+
+```
+#blog-post #published=false #topic=technology
+```
+
+Find unpublished technology blog posts.
+
+```
+#documentation #lastReviewed < TODAY-90 #product=api
+```
+
+Find API documentation not reviewed in 90 days.
+
+### Editorial Workflow
+
+Track editing and publication status:
+
+```
+#article #editor=jane #status=review
+```
+
+Find articles assigned to Jane for review.
+
+```
+#manuscript #submissionDate >= TODAY-30 #status=pending
+```
+
+Find manuscripts submitted in the last 30 days still pending.
+
+```
+#publication #acceptanceDate >= YEAR #status=accepted
+```
+
+Find accepted publications this year.
+
+### Content Research
+
+Organize research materials and sources:
+
+```
+#source #reliability >= 8 #topic *=* climate
+```
+
+Find reliable sources about climate topics.
+
+```
+#quote #author *=* Einstein #verified=true
+```
+
+Find verified Einstein quotes.
+
+```
+#citation #used=false #relevance=high
+```
+
+Find high-relevance citations not yet used.
+
+## Business and Professional Use
+
+### Client Management
+
+Track client relationships and projects:
+
+```
+#client=acme #project #status=active
+```
+
+Find active projects for ACME client.
+
+```
+#meeting #client #date >= MONTH #followUp=required
+```
+
+Find client meetings this month requiring follow-up.
+
+```
+#contract #renewalDate <= TODAY+60 #renewalDate >= TODAY
+```
+
+Find contracts expiring in the next 60 days.
+
+```
+#invoice #status=unpaid #dueDate < TODAY
+```
+
+Find overdue unpaid invoices.
+
+### Process Documentation
+
+Maintain procedures and workflows:
+
+```
+#procedure #department=engineering #lastUpdated < TODAY-365
+```
+
+Find engineering procedures not updated in a year.
+
+```
+#workflow #status=active #automation=possible
+```
+
+Find active workflows that could be automated.
+
+```
+#checklist #process=onboarding #role=developer
+```
+
+Find onboarding checklists for developers.
+
+### Compliance and Auditing
+
+Track compliance requirements and audits:
+
+```
+#compliance #standard=sox #nextReview <= TODAY+30
+```
+
+Find SOX compliance items due for review soon.
+
+```
+#audit #finding #severity=high #status!=resolved
+```
+
+Find unresolved high-severity audit findings.
+
+```
+#policy #department=hr #effectiveDate >= YEAR
+```
+
+Find HR policies that became effective this year.
+
+## Academic and Educational Use
+
+### Course Management
+
+Organize courses and educational content:
+
+```
+#course #semester=fall-2024 #assignment #dueDate >= TODAY
+```
+
+Find upcoming assignments for fall 2024 courses.
+
+```
+#lecture #course=physics #topic *=* quantum
+```
+
+Find physics lectures about quantum topics.
+
+```
+#student #grade < 70 #course=mathematics
+```
+
+Find students struggling in mathematics.
+
+```
+#syllabus #course #lastUpdated < TODAY-180
+```
+
+Find syllabi not updated in 6 months.
+
+### Research Management
+
+Track research projects and publications:
+
+```
+#experiment #status=running #endDate <= TODAY+7
+```
+
+Find experiments ending in the next week.
+
+```
+#dataset #size > 1000000 #cleaned=true #public=false
+```
+
+Find large, cleaned, private datasets.
+
+```
+#hypothesis #tested=false #priority=high
+```
+
+Find high-priority untested hypotheses.
+
+```
+#collaboration #institution *=* stanford #status=active
+```
+
+Find active collaborations with Stanford.
+
+### Grant and Funding
+
+Manage funding applications and requirements:
+
+```
+#grant #deadline <= TODAY+30 #deadline >= TODAY #status=in-progress
+```
+
+Find grant applications due in the next 30 days.
+
+```
+#funding #amount >= 100000 #status=awarded #startDate >= YEAR
+```
+
+Find large grants awarded this year.
+
+```
+#report #funding #dueDate <= TODAY+14 #status!=submitted
+```
+
+Find funding reports due in 2 weeks.
+
+## Technical Documentation
+
+### Code and Development
+
+Track code-related notes and documentation:
+
+```
+#bug #severity=critical #status!=fixed #product=webapp
+```
+
+Find critical unfixed bugs in the web app.
+
+```
+#feature #version=2.0 #status=implemented #tested=false
+```
+
+Find version 2.0 features that are implemented but not tested.
+
+```
+#api #endpoint #deprecated=true #removalDate <= TODAY+90
+```
+
+Find deprecated API endpoints scheduled for removal soon.
+
+```
+#architecture #component=database #lastReviewed < TODAY-180
+```
+
+Find database architecture documentation not reviewed in 6 months.
+
+### System Administration
+
+Manage infrastructure and operations:
+
+```
+#server #status=maintenance #scheduledDate >= TODAY #scheduledDate <= TODAY+7
+```
+
+Find servers scheduled for maintenance this week.
+
+```
+#backup #status=failed #date >= TODAY-7
+```
+
+Find backup failures in the last week.
+
+```
+#security #vulnerability #severity=high #patched=false
+```
+
+Find unpatched high-severity vulnerabilities.
+
+```
+#monitoring #alert #frequency > 10 #period=week
+```
+
+Find alerts triggering more than 10 times per week.
+
+## Data Analysis and Reporting
+
+### Performance Tracking
+
+Monitor metrics and KPIs:
+
+```
+#metric #kpi=true #trend=declining #period=month
+```
+
+Find declining monthly KPIs.
+
+```
+#report #frequency=weekly #lastGenerated < TODAY-10
+```
+
+Find weekly reports that haven't been generated in 10 days.
+
+```
+#dashboard #stakeholder=executive #lastUpdated < TODAY-7
+```
+
+Find executive dashboards not updated this week.
+
+### Trend Analysis
+
+Track patterns and changes over time:
+
+```
+#data #source=sales #period=quarter #analyzed=false
+```
+
+Find unanalyzed quarterly sales data.
+
+```
+#trend #direction=up #significance=high #period=month
+```
+
+Find significant positive monthly trends.
+
+```
+#forecast #accuracy < 80 #model=linear #period=quarter
+```
+
+Find inaccurate quarterly linear forecasts.
+
+## Search Strategy Tips
+
+### Building Effective Queries
+
+1.  **Start Specific**: Begin with the most selective criteria
+2.  **Add Gradually**: Build complexity incrementally
+3.  **Test Components**: Verify each part of complex queries
+4.  **Use Shortcuts**: Leverage `#` and `~` shortcuts for efficiency
+
+### Performance Optimization
+
+1.  **Use Fast Search**: For large databases, enable fast search when content isn't needed
+2.  **Limit Results**: Add limits to prevent overwhelming result sets
+3.  **Order Strategically**: Put the most useful results first
+4.  **Cache Common Queries**: Save frequently used searches
+
+### Maintenance Patterns
+
+Regular queries for note maintenance:
+
+```
+# Weekly cleanup check
+note.attributeCount = 0 note.type=text note.contentSize < 100 note.dateModified < TODAY-30
+
+# Monthly project review  
+#project #status=active note.dateModified < TODAY-30
+
+# Quarterly archive review
+note.isArchived=false note.dateModified < TODAY-90 note.childrenCount = 0
+```
+
+## Next Steps
+
+*   [Saved Searches](Saved-Searches.md) - Convert these examples into reusable saved searches
+*   [Technical Search Details](Technical-Search-Details.md) - Understanding performance and implementation
+*   [Search Fundamentals](Search-Fundamentals.md) - Review basic concepts and syntax

docs/User Guide/User Guide/Advanced Usage/Search/Search-Fundamentals.md

@@ -0,0 +1,214 @@
+# Search-Fundamentals
+## Search Fundamentals
+
+Trilium's search system is a powerful tool for finding and organizing notes. It supports multiple search modes, from simple text queries to complex expressions using attributes, relationships, and note properties.
+
+## Search Types Overview
+
+Trilium provides three main search approaches:
+
+1.  **Full-text Search** - Searches within note titles and content
+2.  **Attribute Search** - Searches based on labels and relations attached to notes
+3.  **Property Search** - Searches based on note metadata (type, creation date, etc.)
+
+These can be combined in powerful ways to create precise queries.
+
+## Basic Search Syntax
+
+### Simple Text Search
+
+```
+hello world
+```
+
+Finds notes containing both "hello" and "world" anywhere in the title or content.
+
+### Quoted Text Search
+
+```
+"hello world"
+```
+
+Finds notes containing the exact phrase "hello world".
+
+### Attribute Search
+
+```
+#tag
+```
+
+Finds notes with the label "tag".
+
+```
+#category=book
+```
+
+Finds notes with label "category" set to "book".
+
+### Relation Search
+
+```
+~author
+```
+
+Finds notes with a relation named "author".
+
+```
+~author.title=Tolkien
+```
+
+Finds notes with an "author" relation pointing to a note titled "Tolkien".
+
+## Search Operators
+
+### Text Operators
+
+*   `=` - Exact match
+*   `!=` - Not equal
+*   `*=*` - Contains (substring)
+*   `=*` - Starts with
+*   `*=` - Ends with
+*   `%=` - Regular expression match
+*   `~=` - Fuzzy exact match
+*   `~*` - Fuzzy contains match
+
+### Numeric Operators
+
+*   `=` - Equal
+*   `!=` - Not equal
+*   `>` - Greater than
+*   `>=` - Greater than or equal
+*   `<` - Less than
+*   `<=` - Less than or equal
+
+### Boolean Operators
+
+*   `AND` - Both conditions must be true
+*   `OR` - Either condition must be true
+*   `NOT` or `not()` - Condition must be false
+
+## Search Context and Scope
+
+### Search Scope
+
+By default, search covers:
+
+*   Note titles
+*   Note content (for text-based note types)
+*   Label names and values
+*   Relation names
+*   Note properties
+
+### Fast Search Mode
+
+When enabled, fast search:
+
+*   Searches only titles and attributes
+*   Skips note content
+*   Provides faster results for large databases
+
+### Archived Notes
+
+*   Excluded by default
+*   Can be included with "Include archived" option
+
+## Case Sensitivity and Normalization
+
+*   All searches are case-insensitive
+*   Diacritics are normalized ("café" matches "cafe")
+*   Unicode characters are properly handled
+
+## Performance Considerations
+
+### Content Size Limits
+
+*   Note content is limited to 10MB for search processing
+*   Larger notes are still searchable by title and attributes
+
+### Progressive Search Strategy
+
+1.  **Exact Search Phase**: Fast exact matching (handles 90%+ of searches)
+2.  **Fuzzy Search Phase**: Activated when exact search returns fewer than 5 high-quality results
+3.  **Result Ordering**: Exact matches always appear before fuzzy matches
+
+### Search Optimization Tips
+
+*   Use specific terms rather than very common words
+*   Combine full-text with attribute searches for precision
+*   Use fast search for large databases when content search isn't needed
+*   Limit results when dealing with very large result sets
+
+## Special Characters and Escaping
+
+### Reserved Characters
+
+These characters have special meaning in search queries:
+
+*   `#` - Label indicator
+*   `~` - Relation indicator
+*   `()` - Grouping
+*   `"` `'` `` ` `` - Quotes for exact phrases
+
+### Escaping Special Characters
+
+Use backslash to search for literal special characters:
+
+```
+\#hashtag
+```
+
+Searches for the literal text "#hashtag" instead of a label.
+
+Use quotes to include special characters in phrases:
+
+```
+"note.txt file"
+```
+
+Searches for the exact phrase including the dot.
+
+## Date and Time Values
+
+### Special Date Keywords
+
+*   `TODAY` - Current date
+*   `NOW` - Current date and time
+*   `MONTH` - Current month
+*   `YEAR` - Current year
+
+### Date Arithmetic
+
+```
+#dateCreated >= TODAY-30
+```
+
+Finds notes created in the last 30 days.
+
+```
+#eventDate = YEAR+1
+```
+
+Finds notes with eventDate set to next year.
+
+## Search Results and Scoring
+
+### Result Ranking
+
+Results are ordered by:
+
+1.  Relevance score (based on term frequency and position)
+2.  Note depth (closer to root ranks higher)
+3.  Alphabetical order for ties
+
+### Progressive Search Behavior
+
+*   Exact matches always rank before fuzzy matches
+*   High-quality exact matches prevent fuzzy search activation
+*   Fuzzy matches help find content with typos or variations
+
+## Next Steps
+
+*   [Advanced Search Expressions](Advanced-Search-Expressions.md) - Complex queries and combinations
+*   [Search Examples and Use Cases](Search-Examples-and-Use-Cases.md) - Practical applications
+*   [Saved Searches](Saved-Searches.md) - Creating dynamic collections
+*   [Technical Search Details](Technical-Search-Details.md) - Under-the-hood implementation

docs/User Guide/User Guide/Advanced Usage/Search/Technical-Search-Details.md

@@ -0,0 +1,589 @@
+# Technical-Search-Details
+## Technical Search Details
+
+This guide provides technical information about Trilium's search implementation, performance characteristics, and optimization strategies for power users and administrators.
+
+## Search Architecture Overview
+
+### Three-Layer Search System
+
+Trilium's search operates across three cache layers:
+
+1.  **Becca (Backend Cache)**: Server-side entity cache containing notes, attributes, and relationships
+2.  **Froca (Frontend Cache)**: Client-side mirror providing fast UI updates
+3.  **Database Layer**: SQLite database with FTS (Full-Text Search) support
+
+### Search Processing Pipeline
+
+1.  **Lexical Analysis**: Query parsing and tokenization
+2.  **Expression Building**: Converting tokens to executable expressions
+3.  **Progressive Execution**: Exact search followed by optional fuzzy search
+4.  **Result Scoring**: Relevance calculation and ranking
+5.  **Result Presentation**: Formatting and highlighting
+
+## Query Processing Details
+
+### Lexical Analysis (Lex)
+
+The lexer breaks down search queries into components:
+
+```javascript
+// Input: 'project #status=active note.dateCreated >= TODAY-7'
+// Output:
+{
+  fulltextTokens: ['project'],
+  expressionTokens: ['#status', '=', 'active', 'note', '.', 'dateCreated', '>=', 'TODAY-7']
+}
+```
+
+#### Token Types
+
+*   **Fulltext Tokens**: Regular search terms
+*   **Expression Tokens**: Attributes, operators, and property references
+*   **Quoted Strings**: Exact phrase matches
+*   **Escaped Characters**: Literal special characters
+
+### Expression Building (Parse)
+
+Tokens are converted into executable expression trees:
+
+```javascript
+// Expression tree for: #book AND #author=Tolkien
+AndExp([
+  AttributeExistsExp('label', 'book'),
+  LabelComparisonExp('label', 'author', equals('tolkien'))
+])
+```
+
+#### Expression Types
+
+*   `AndExp`, `OrExp`, `NotExp`: Boolean logic
+*   `AttributeExistsExp`: Label/relation existence
+*   `LabelComparisonExp`: Label value comparison
+*   `RelationWhereExp`: Relation target queries
+*   `PropertyComparisonExp`: Note property filtering
+*   `NoteContentFulltextExp`: Content search
+*   `OrderByAndLimitExp`: Result ordering and limiting
+
+### Progressive Search Strategy
+
+#### Phase 1: Exact Search
+
+```javascript
+// Fast exact matching
+const exactResults = performSearch(expression, searchContext, false);
+```
+
+Characteristics:
+
+*   Substring matching for text
+*   Exact attribute matching
+*   Property-based filtering
+*   Handles 90%+ of searches
+*   Sub-second response time
+
+#### Phase 2: Fuzzy Fallback
+
+```javascript
+// Activated when exact results < 5 high-quality matches
+if (highQualityResults.length < 5) {
+  const fuzzyResults = performSearch(expression, searchContext, true);
+  return mergeExactAndFuzzyResults(exactResults, fuzzyResults);
+}
+```
+
+Characteristics:
+
+*   Edit distance calculations
+*   Phrase proximity matching
+*   Typo tolerance
+*   Performance safeguards
+*   Exact matches always rank first
+
+## Performance Characteristics
+
+### Search Limits and Thresholds
+
+| Parameter | Value | Purpose |
+| --- | --- | --- |
+| `MAX_SEARCH_CONTENT_SIZE` | 2MB | Database-level content filtering |
+| `MIN_FUZZY_TOKEN_LENGTH` | 3 chars | Minimum length for fuzzy matching |
+| `MAX_EDIT_DISTANCE` | 2 chars | Maximum character changes for fuzzy |
+| `MAX_PHRASE_PROXIMITY` | 10 words | Maximum distance for phrase matching |
+| `RESULT_SUFFICIENCY_THRESHOLD` | 5 results | Threshold for fuzzy activation |
+| `ABSOLUTE_MAX_CONTENT_SIZE` | 100MB | Hard limit to prevent system crash |
+| `ABSOLUTE_MAX_WORD_COUNT` | 2M words | Hard limit for word processing |
+
+### Performance Optimization
+
+#### Database-Level Optimizations
+
+```mariadb
+-- Content size filtering at database level
+SELECT noteId, type, mime, content, isProtected
+FROM notes JOIN blobs USING (blobId)
+WHERE type IN ('text', 'code', 'mermaid', 'canvas', 'mindMap') 
+  AND isDeleted = 0 
+  AND LENGTH(content) < 2097152  -- 2MB limit
+```
+
+#### Memory Management
+
+*   Single-array edit distance calculation
+*   Early termination for distant matches
+*   Progressive content processing
+*   Cached regular expressions
+
+#### Search Context Optimization
+
+```javascript
+// Efficient search context configuration
+const searchContext = new SearchContext({
+  fastSearch: true,           // Skip content search
+  limit: 50,                 // Reasonable result limit
+  orderBy: 'dateCreated',    // Use indexed property
+  includeArchivedNotes: false // Reduce search space
+});
+```
+
+## Fuzzy Search Implementation
+
+### Edit Distance Algorithm
+
+Trilium uses an optimized Levenshtein distance calculation:
+
+```javascript
+// Optimized single-array implementation
+function calculateOptimizedEditDistance(str1, str2, maxDistance) {
+  // Early termination checks
+  if (Math.abs(str1.length - str2.length) > maxDistance) {
+    return maxDistance + 1;
+  }
+  
+  // Single array optimization
+  let previousRow = Array.from({ length: str2.length + 1 }, (_, i) => i);
+  let currentRow = new Array(str2.length + 1);
+  
+  for (let i = 1; i <= str1.length; i++) {
+    currentRow[0] = i;
+    let minInRow = i;
+    
+    for (let j = 1; j <= str2.length; j++) {
+      const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+      currentRow[j] = Math.min(
+        previousRow[j] + 1,        // deletion
+        currentRow[j - 1] + 1,     // insertion
+        previousRow[j - 1] + cost  // substitution
+      );
+      minInRow = Math.min(minInRow, currentRow[j]);
+    }
+    
+    // Early termination if row minimum exceeds threshold
+    if (minInRow > maxDistance) return maxDistance + 1;
+    
+    [previousRow, currentRow] = [currentRow, previousRow];
+  }
+  
+  return previousRow[str2.length];
+}
+```
+
+### Phrase Proximity Matching
+
+For multi-token fuzzy searches:
+
+```javascript
+// Check if tokens appear within reasonable proximity
+function hasProximityMatch(tokenPositions, maxDistance = 10) {
+  // For 2 tokens, simple distance check
+  if (tokenPositions.length === 2) {
+    const [pos1, pos2] = tokenPositions;
+    return pos1.some(p1 => pos2.some(p2 => Math.abs(p1 - p2) <= maxDistance));
+  }
+  
+  // For multiple tokens, find sequence within range
+  const findSequence = (remaining, currentPos) => {
+    if (remaining.length === 0) return true;
+    const [nextPositions, ...rest] = remaining;
+    return nextPositions.some(pos => 
+      Math.abs(pos - currentPos) <= maxDistance && 
+      findSequence(rest, pos)
+    );
+  };
+  
+  const [firstPositions, ...rest] = tokenPositions;
+  return firstPositions.some(startPos => findSequence(rest, startPos));
+}
+```
+
+## Indexing and Storage
+
+### Database Schema Optimization
+
+```mariadb
+-- Relevant indexes for search performance
+CREATE INDEX idx_notes_type ON notes(type);
+CREATE INDEX idx_notes_isDeleted ON notes(isDeleted);
+CREATE INDEX idx_notes_dateCreated ON notes(dateCreated);
+CREATE INDEX idx_notes_dateModified ON notes(dateModified);
+CREATE INDEX idx_attributes_name ON attributes(name);
+CREATE INDEX idx_attributes_type ON attributes(type);
+CREATE INDEX idx_attributes_value ON attributes(value);
+```
+
+### Content Processing
+
+Notes are processed differently based on type:
+
+```javascript
+// Content preprocessing by note type
+function preprocessContent(content, type, mime) {
+  content = normalize(content.toString());
+  
+  if (type === "text" && mime === "text/html") {
+    content = stripTags(content);
+    content = content.replace(/&nbsp;/g, " ");
+  } else if (type === "mindMap" && mime === "application/json") {
+    content = processMindmapContent(content);
+  } else if (type === "canvas" && mime === "application/json") {
+    const canvasData = JSON.parse(content);
+    const textElements = canvasData.elements
+      .filter(el => el.type === "text" && el.text)
+      .map(el => el.text);
+    content = normalize(textElements.join(" "));
+  }
+  
+  return content.trim();
+}
+```
+
+## Search Result Processing
+
+### Scoring Algorithm
+
+Results are scored based on multiple factors:
+
+```javascript
+function computeScore(fulltextQuery, highlightedTokens, enableFuzzyMatching) {
+  let score = 0;
+  
+  // Title matches get higher score
+  if (this.noteTitle.toLowerCase().includes(fulltextQuery.toLowerCase())) {
+    score += 10;
+  }
+  
+  // Path matches (hierarchical context)
+  const pathMatch = this.notePathArray.some(pathNote => 
+    pathNote.title.toLowerCase().includes(fulltextQuery.toLowerCase())
+  );
+  if (pathMatch) score += 5;
+  
+  // Attribute matches
+  score += this.attributeMatches * 3;
+  
+  // Content snippet quality
+  if (this.contentSnippet && this.contentSnippet.length > 0) {
+    score += 2;
+  }
+  
+  // Fuzzy match penalty
+  if (enableFuzzyMatching && this.isFuzzyMatch) {
+    score *= 0.8; // 20% penalty for fuzzy matches
+  }
+  
+  return score;
+}
+```
+
+### Result Merging
+
+Exact and fuzzy results are carefully merged:
+
+```javascript
+function mergeExactAndFuzzyResults(exactResults, fuzzyResults) {
+  // Deduplicate - exact results take precedence
+  const exactNoteIds = new Set(exactResults.map(r => r.noteId));
+  const additionalFuzzyResults = fuzzyResults.filter(r => 
+    !exactNoteIds.has(r.noteId)
+  );
+  
+  // Sort within each category
+  exactResults.sort(byScoreAndDepth);
+  additionalFuzzyResults.sort(byScoreAndDepth);
+  
+  // CRITICAL: Exact matches always come first
+  return [...exactResults, ...additionalFuzzyResults];
+}
+```
+
+## Performance Monitoring
+
+### Search Metrics
+
+Monitor these performance indicators:
+
+```javascript
+// Performance tracking
+const searchMetrics = {
+  totalQueries: 0,
+  exactSearchTime: 0,
+  fuzzySearchTime: 0,
+  resultCount: 0,
+  cacheHitRate: 0,
+  slowQueries: [] // queries taking > 1 second
+};
+```
+
+### Memory Usage
+
+Track memory consumption:
+
+```javascript
+// Memory monitoring
+const memoryMetrics = {
+  searchCacheSize: 0,
+  activeSearchContexts: 0,
+  largeContentNotes: 0, // notes > 1MB
+  indexSize: 0
+};
+```
+
+### Query Complexity Analysis
+
+Identify expensive queries:
+
+```javascript
+// Query complexity factors
+const complexityFactors = {
+  tokenCount: query.split(' ').length,
+  hasRegex: query.includes('%='),
+  hasFuzzy: query.includes('~=') || query.includes('~*'),
+  hasRelationTraversal: query.includes('.relations.'),
+  hasNestedProperties: (query.match(/\./g) || []).length > 2,
+  hasOrderBy: query.includes('orderBy'),
+  estimatedResultSize: 'unknown'
+};
+```
+
+## Troubleshooting Performance Issues
+
+### Common Performance Problems
+
+#### Slow Full-Text Search
+
+```javascript
+// Diagnosis
+- Check note content sizes
+- Verify content type filtering
+- Monitor regex usage
+- Review fuzzy search activation
+
+// Solutions
+- Enable fast search for attribute-only queries
+- Add content size limits
+- Optimize regex patterns
+- Tune fuzzy search thresholds
+```
+
+#### Memory Issues
+
+```javascript
+// Diagnosis
+- Monitor result set sizes
+- Check for large content processing
+- Review search context caching
+- Identify memory leaks
+
+// Solutions
+- Add result limits
+- Implement progressive loading
+- Clear unused search contexts
+- Optimize content preprocessing
+```
+
+#### High CPU Usage
+
+```javascript
+// Diagnosis
+- Profile fuzzy search operations
+- Check edit distance calculations
+- Monitor regex compilation
+- Review phrase proximity matching
+
+// Solutions
+- Increase minimum fuzzy token length
+- Reduce maximum edit distance
+- Cache compiled regexes
+- Limit phrase proximity distance
+```
+
+### Debugging Tools
+
+#### Debug Mode
+
+Enable search debugging:
+
+```javascript
+// Search context with debugging
+const searchContext = new SearchContext({
+  debug: true // Logs expression parsing and execution
+});
+```
+
+Output includes:
+
+*   Token parsing results
+*   Expression tree structure
+*   Execution timing
+*   Result scoring details
+
+#### Performance Profiling
+
+```javascript
+// Manual performance measurement
+const startTime = Date.now();
+const results = searchService.findResultsWithQuery(query, searchContext);
+const endTime = Date.now();
+console.log(`Search took ${endTime - startTime}ms for ${results.length} results`);
+```
+
+#### Query Analysis
+
+```javascript
+// Analyze query complexity
+function analyzeQuery(query) {
+  return {
+    tokenCount: query.split(/\s+/).length,
+    hasAttributes: /#|\~/.test(query),
+    hasProperties: /note\./.test(query),
+    hasRegex: /%=/.test(query),
+    hasFuzzy: /~[=*]/.test(query),
+    complexity: calculateComplexityScore(query)
+  };
+}
+```
+
+## Configuration and Tuning
+
+### Server Configuration
+
+Relevant settings in `config.ini`:
+
+```toml
+# Search-related settings
+[Search]
+maxContentSize=2097152          # 2MB content limit
+minFuzzyTokenLength=3          # Minimum chars for fuzzy
+maxEditDistance=2              # Edit distance limit
+resultSufficiencyThreshold=5   # Fuzzy activation threshold
+enableProgressiveSearch=true   # Enable progressive strategy
+cacheSearchResults=true        # Cache frequent searches
+
+# Performance settings
+[Performance]
+searchTimeoutMs=30000         # 30 second search timeout
+maxSearchResults=1000         # Hard limit on results
+enableSearchProfiling=false   # Performance logging
+```
+
+### Runtime Tuning
+
+Adjust search behavior programmatically:
+
+```javascript
+// Dynamic configuration
+const searchConfig = {
+  maxContentSize: 1024 * 1024,  // 1MB for faster processing
+  enableFuzzySearch: false,      // Exact only for speed
+  resultLimit: 50,               // Smaller result sets
+  useIndexedPropertiesOnly: true // Skip expensive calculations
+};
+```
+
+## Best Practices for Performance
+
+### Query Design
+
+1.  **Start Specific**: Use selective criteria first
+2.  **Limit Results**: Always set reasonable limits
+3.  **Use Indexes**: Prefer indexed properties for ordering
+4.  **Avoid Regex**: Use simple operators when possible
+5.  **Cache Common Queries**: Save frequently used searches
+
+### System Administration
+
+1.  **Monitor Performance**: Track slow queries and memory usage
+2.  **Regular Maintenance**: Clean up unused notes and attributes
+3.  **Index Optimization**: Ensure database indexes are current
+4.  **Content Management**: Archive or compress large content
+
+### Development Guidelines
+
+1.  **Test Performance**: Benchmark complex queries
+2.  **Profile Regularly**: Identify performance regressions
+3.  **Optimize Incrementally**: Make small, measured improvements
+4.  **Document Complexity**: Note expensive operations
+
+## Advanced Configuration
+
+### Custom Search Extensions
+
+Extend search functionality with custom expressions:
+
+```javascript
+// Custom expression example
+class CustomDateRangeExp extends Expression {
+  constructor(dateField, startDate, endDate) {
+    super();
+    this.dateField = dateField;
+    this.startDate = startDate;
+    this.endDate = endDate;
+  }
+  
+  execute(inputNoteSet, executionContext, searchContext) {
+    // Custom logic for date range filtering
+    // with optimized performance characteristics
+  }
+}
+```
+
+### Search Result Caching
+
+Implement result caching for frequent queries:
+
+```javascript
+// Simple LRU cache for search results
+class SearchResultCache {
+  constructor(maxSize = 100) {
+    this.cache = new Map();
+    this.maxSize = maxSize;
+  }
+  
+  get(queryKey) {
+    if (this.cache.has(queryKey)) {
+      // Move to end (most recently used)
+      const value = this.cache.get(queryKey);
+      this.cache.delete(queryKey);
+      this.cache.set(queryKey, value);
+      return value;
+    }
+    return null;
+  }
+  
+  set(queryKey, results) {
+    if (this.cache.size >= this.maxSize) {
+      // Remove least recently used
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(queryKey, results);
+  }
+}
+```
+
+## Next Steps
+
+*   [Search Fundamentals](Search-Fundamentals.md) - Basic concepts and syntax
+*   [Advanced Search Expressions](Advanced-Search-Expressions.md) - Complex query construction
+*   [Search Examples and Use Cases](Search-Examples-and-Use-Cases.md) - Practical applications
+*   [Saved Searches](Saved-Searches.md) - Creating dynamic collections

docs/User Guide/User Guide/Installation & Setup/Security/Protected Notes and Encryption.md

@@ -0,0 +1,279 @@
+# Protected Notes and Encryption
+Trilium provides robust encryption capabilities through its Protected Notes system, ensuring your sensitive information remains secure even if your database is compromised.
+
+## Overview
+
+Protected notes in Trilium use **AES-128-CBC encryption** with scrypt-based key derivation to protect sensitive content. The encryption is designed to be:
+
+*   **Secure**: Uses industry-standard AES encryption with strong key derivation
+*   **Selective**: Only notes marked as protected are encrypted
+*   **Session-based**: Decrypted content remains accessible during a protected session
+*   **Zero-knowledge**: The server never stores unencrypted protected content
+
+## How Encryption Works
+
+### Encryption Algorithm
+
+*   **Cipher**: AES-128-CBC (Advanced Encryption Standard in Cipher Block Chaining mode)
+*   **Key Derivation**: Scrypt with configurable parameters (N=16384, r=8, p=1)
+*   **Initialization Vector**: 16-byte random IV generated for each encryption operation
+*   **Integrity Protection**: SHA-1 digest (first 4 bytes) prepended to plaintext for tamper detection
+
+### Key Management
+
+1.  **Master Password**: User-provided password used for key derivation
+2.  **Data Key**: 32-byte random key generated during setup, encrypted with password-derived key
+3.  **Password-Derived Key**: Generated using scrypt from master password and salt
+4.  **Session Key**: Data key loaded into memory during protected session
+
+### Encryption Process
+
+```
+1. Generate random 16-byte IV
+2. Compute SHA-1 digest of plaintext (use first 4 bytes)
+3. Prepend digest to plaintext
+4. Encrypt (digest + plaintext) using AES-128-CBC
+5. Prepend IV to encrypted data
+6. Encode result as Base64
+```
+
+### Decryption Process
+
+```
+1. Decode Base64 ciphertext
+2. Extract IV (first 16 bytes) and encrypted data
+3. Decrypt using AES-128-CBC with data key and IV
+4. Extract digest (first 4 bytes) and plaintext
+5. Verify integrity by comparing computed vs. stored digest
+6. Return plaintext if verification succeeds
+```
+
+## Setting Up Protected Notes
+
+### Initial Setup
+
+1.  **Set Master Password**: Configure a strong password during initial setup
+2.  **Create Protected Note**: Right-click a note and select "Toggle Protected Status"
+3.  **Enter Protected Session**: Click the shield icon or use Ctrl+Shift+P
+
+### Password Requirements
+
+*   **Minimum Length**: 8 characters (recommended: 12+ characters)
+*   **Complexity**: Use a mix of uppercase, lowercase, numbers, and symbols
+*   **Uniqueness**: Don't reuse passwords from other services
+*   **Storage**: Consider using a password manager for complex passwords
+
+### Best Practices
+
+1.  **Strong Passwords**: Use passphrases or generated passwords
+2.  **Regular Changes**: Update passwords periodically
+3.  **Secure Storage**: Store password recovery information securely
+4.  **Backup Strategy**: Ensure encrypted backups are properly secured
+
+## Protected Sessions
+
+### Session Management
+
+*   **Automatic Timeout**: Sessions expire after configurable timeout (default: 10 minutes)
+*   **Manual Control**: Explicitly enter/exit protected sessions
+*   **Activity Tracking**: Session timeout resets with each protected note access
+*   **Multi-client**: Each client maintains its own protected session
+
+### Session Lifecycle
+
+1.  **Enter Session**: User enters master password
+2.  **Key Derivation**: System derives data key from password
+3.  **Session Active**: Protected content accessible in plaintext
+4.  **Timeout/Logout**: Data key removed from memory
+5.  **Protection Restored**: Content returns to encrypted state
+
+### Configuration Options
+
+Access via Options → Protected Session:
+
+*   **Session Timeout**: Duration before automatic logout (seconds)
+*   **Password Verification**: Enable/disable password strength requirements
+*   **Recovery Options**: Configure password recovery mechanisms
+
+## Performance Considerations
+
+### Encryption Overhead
+
+*   **CPU Impact**: Scrypt key derivation is intentionally CPU-intensive
+*   **Memory Usage**: Minimal additional memory for encrypted content
+*   **Storage Size**: Encrypted content is slightly larger due to Base64 encoding
+*   **Network Transfer**: Encrypted notes transfer as Base64 strings
+
+### Optimization Tips
+
+1.  **Selective Protection**: Only encrypt truly sensitive notes
+2.  **Session Management**: Keep sessions active during intensive work
+3.  **Hardware Acceleration**: Modern CPUs provide AES acceleration
+4.  **Batch Operations**: Group protected note operations when possible
+
+## Security Considerations
+
+### Threat Model
+
+**Protected Against**:
+
+*   Database theft or unauthorized access
+*   Network interception (data at rest)
+*   Server-side data breaches
+*   Backup file compromise
+
+**Not Protected Against**:
+
+*   Keyloggers or screen capture malware
+*   Physical access to unlocked device
+*   Memory dumps during active session
+*   Social engineering attacks
+
+### Limitations
+
+1.  **Note Titles**: Currently encrypted, may leak structural information
+2.  **Metadata**: Creation dates, modification times remain unencrypted
+3.  **Search Indexing**: Protected notes excluded from full-text search
+4.  **Sync Conflicts**: May be harder to resolve for protected content
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Could not decrypt string" Error
+
+**Causes**:
+
+*   Incorrect password entered
+*   Corrupted encrypted data
+*   Database migration issues
+
+**Solutions**:
+
+1.  Verify password spelling and case sensitivity
+2.  Check for active protected session
+3.  Restart application and retry
+4.  Restore from backup if corruption suspected
+
+#### Protected Session Won't Start
+
+**Causes**:
+
+*   Password verification hash mismatch
+*   Missing encryption salt
+*   Database schema issues
+
+**Solutions**:
+
+1.  Check error logs for specific error messages
+2.  Verify database integrity
+3.  Restore from known good backup
+4.  Contact support with error details
+
+#### Performance Issues
+
+**Symptoms**:
+
+*   Slow password verification
+*   Long delays entering protected session
+*   High CPU usage during encryption
+
+**Solutions**:
+
+1.  Reduce scrypt parameters (advanced users only)
+2.  Limit number of protected notes
+3.  Upgrade hardware (more RAM/faster CPU)
+4.  Close other resource-intensive applications
+
+### Recovery Procedures
+
+#### Password Recovery
+
+If you forget your master password:
+
+1.  **No Built-in Recovery**: Trilium cannot recover forgotten passwords
+2.  **Backup Restoration**: Restore from backup with known password
+3.  **Data Export**: Export unprotected content before password change
+4.  **Complete Reset**: Last resort - lose all protected content
+
+#### Data Recovery
+
+For corrupted protected notes:
+
+1.  **Verify Backup**: Check if backups contain uncorrupted data
+2.  **Export/Import**: Try exporting and re-importing the note
+3.  **Database Repair**: Use database repair tools if available
+4.  **Professional Help**: Contact data recovery services for critical data
+
+## Advanced Configuration
+
+### Custom Encryption Parameters
+
+**Warning**: Modifying encryption parameters requires advanced knowledge and may break compatibility.
+
+For expert users, encryption parameters can be modified in the source code:
+
+```typescript
+// In my_scrypt.ts
+const scryptParams = {
+    N: 16384,  // CPU/memory cost parameter
+    r: 8,      // Block size parameter  
+    p: 1       // Parallelization parameter
+};
+```
+
+### Integration with External Tools
+
+Protected notes can be accessed programmatically:
+
+```javascript
+// Backend script example
+const protectedNote = api.getNote('noteId');
+if (protectedNote.isProtected) {
+    // Content will be encrypted unless in protected session
+    const content = protectedNote.getContent();
+}
+```
+
+## Compliance and Auditing
+
+### Encryption Standards
+
+*   **Algorithm**: AES-128-CBC (FIPS 140-2 approved)
+*   **Key Derivation**: Scrypt (RFC 7914)
+*   **Random Generation**: Node.js crypto.randomBytes() (OS entropy)
+
+### Audit Trail
+
+*   Protected session entry/exit events logged
+*   Encryption/decryption operations tracked
+*   Password verification attempts recorded
+*   Key derivation operations monitored
+
+### Compliance Considerations
+
+*   **GDPR**: Encryption provides data protection safeguards
+*   **HIPAA**: AES encryption meets security requirements
+*   **SOX**: Audit trails support compliance requirements
+*   **PCI DSS**: Strong encryption protects sensitive data
+
+## Migration and Backup
+
+### Backup Strategies
+
+1.  **Encrypted Backups**: Regular backups preserve encrypted state
+2.  **Unencrypted Exports**: Export protected content during session
+3.  **Key Management**: Securely store password recovery information
+4.  **Testing**: Regularly test backup restoration procedures
+
+### Migration Procedures
+
+When moving to new installation:
+
+1.  **Export Data**: Export all notes including protected content
+2.  **Backup Database**: Create complete database backup
+3.  **Transfer Files**: Move exported files to new installation
+4.  **Import Data**: Import using same master password
+5.  **Verify**: Confirm all protected content accessible
+
+Remember: The security of protected notes ultimately depends on choosing a strong master password and following security best practices for your overall system.

docs/User Guide/User Guide/Installation & Setup/Server Installation.md

@@ -1,62 +1,63 @@
 # Server Installation
-This guide outlines the steps to install Trilium on your own server. You might consider this option if you want to set up [synchronization](Synchronization.md) or use Trilium in a browser - accessible from anywhere.
+Running Trilium on a server lets you access your notes from any device through a web browser and enables synchronization between multiple Trilium instances. This guide covers the different ways to install and configure Trilium on your server.
 
-## Installation Options
+## Choose Your Installation Method
 
-There are several ways to install Trilium on a server, each with its own advantages:
+The easiest way to get started is with Docker, which works on most systems and architectures. If you prefer not to manage your own server, PikaPods offers managed hosting.
 
-*   **Recommended**: [Docker Installation](Server%20Installation/1.%20Installing%20the%20server/Using%20Docker.md) - Available for **AMD64** and **ARM** architectures.
-*   [Packaged Server Installation](Server%20Installation/1.%20Installing%20the%20server/Packaged%20version%20for%20Linux.md)
-*   [PikaPods managed hosting](https://www.pikapods.com/pods?run=trilium-next)
-*   [Manual Installation](Server%20Installation/1.%20Installing%20the%20server/Manually.md)
-*   [Kubernetes](Server%20Installation/1.%20Installing%20the%20server/Using%20Kubernetes.md)
-*   [Cloudron](https://www.cloudron.io/store/com.github.trilium.cloudronapp.html)
-*   [HomelabOS](https://homelabos.com/docs/software/trilium/)
-*   [NixOS Module](Server%20Installation/1.%20Installing%20the%20server/On%20NixOS.md)
+**Recommended approaches:**
 
-The server installation includes both web and [mobile frontends](Mobile%20Frontend.md).
+*   [Docker Installation](1_Server%20Installation/1.%20Installing%20the%20server/Using%20Docker.md) - Works on AMD64 and ARM architectures
+*   [PikaPods managed hosting](https://www.pikapods.com/pods?run=trilium-next) - No server management required
+*   [Packaged Server Installation](1_Server%20Installation/1.%20Installing%20the%20server/Packaged%20version%20for%20Linux.md) - Native Linux packages
+
+**Advanced options:**
+
+*   [Manual Installation](1_Server%20Installation/1.%20Installing%20the%20server/Manually.md) - Full control over the setup
+*   [Kubernetes](1_Server%20Installation/1.%20Installing%20the%20server/Using%20Kubernetes.md) - For container orchestration
+*   [NixOS Module](1_Server%20Installation/1.%20Installing%20the%20server/On%20NixOS.md) - Declarative configuration
+
+All server installations include both desktop and mobile web interfaces.
 
 ## Configuration
 
-After setting up your server installation, you may want to configure settings such as the port or enable [TLS](Server%20Installation/HTTPS%20\(TLS\).md). Configuration is managed via the Trilium `config.ini` file, which is located in the [data directory](Data%20directory.md) by default. To begin customizing your setup, copy the provided `config-sample.ini` file with default values to `config.ini`.
+Trilium stores its configuration in a `config.ini` file located in the [data directory](#root/dvbMBRXYMM2G). To customize your installation, copy the sample configuration file and modify it:
 
-You can also review the [configuration](../Advanced%20Usage/Configuration%20\(config.ini%20or%20e.md) file to provide all `config.ini` values as environment variables instead.
-
-### Config Location
-
-By default, `config.ini`, the [database](../Advanced%20Usage/Database.md), and other important Trilium data files are stored in the [data directory](Data%20directory.md). If you prefer a different location, you can change it by setting the `TRILIUM_DATA_DIR` environment variable:
-
-```
-export TRILIUM_DATA_DIR=/home/myuser/data/my-trilium-data
+```sh
+cp config-sample.ini config.ini
 ```
 
-### Disabling / Modifying the Upload Limit
+You can also use environment variables instead of the config file. This is particularly useful for Docker deployments. See the [configuration guide](#root/SneMubD5wTR6) for all available options.
 
-If you're running into the 250MB limit imposed on the server by default, and you'd like to increase the upload limit, you can set the `TRILIUM_NO_UPLOAD_LIMIT` environment variable to `true` to disable it completely:
+### Changing the Data Directory
 
-```
-export TRILIUM_NO_UPLOAD_LIMIT=true 
+To store Trilium's data (database, config, backups) in a custom location, set the `TRILIUM_DATA_DIR` environment variable:
+
+```sh
+export TRILIUM_DATA_DIR=/path/to/your/trilium-data
 ```
 
-Or, if you'd simply like to _increase_ the upload limit size to something beyond 250MB, you can set the `MAX_ALLOWED_FILE_SIZE_MB` environment variable to something larger than the integer `250` (e.g. `450` in the following example):
+### Upload Size Limits
 
-```
+By default, Trilium limits file uploads to 250MB. You can adjust this limit based on your needs:
+
+```sh
+# Increase limit to 450MB
 export MAX_ALLOWED_FILE_SIZE_MB=450
+
+# Remove limit entirely (use with caution)
+export TRILIUM_NO_UPLOAD_LIMIT=true
 ```
 
 ### Disabling Authentication
 
-See <a class="reference-link" href="Server%20Installation/Authentication.md">Authentication</a>.
+See <a class="reference-link" href="1_Server%20Installation/Authentication.md">Authentication</a>.
 
 ## Reverse Proxy Setup
 
-To configure a reverse proxy for Trilium, you can use either **nginx** or **Apache**. You can also check out the documentation stored in the Reverse proxy folder.
+If you want to access Trilium through a domain name or alongside other web services, you'll need to configure a reverse proxy. Here's a basic nginx configuration:
 
-### nginx
-
-Add the following configuration to your `nginx` setup to proxy requests to Trilium:
-
-```
+```nginx
 location /trilium/ {
     proxy_pass http://127.0.0.1:8080/;
     proxy_http_version 1.1;
@@ -65,15 +66,9 @@ location /trilium/ {
     proxy_set_header Host $host;
     proxy_cache_bypass $http_upgrade;
 }
+
+# Allow larger file uploads (in server block)
+client_max_body_size 0;  # 0 = unlimited
 ```
 
-To avoid limiting the size of payloads, include this in the `server {}` block:
-
-```
-# Set to 0 for unlimited. Default is 1M.
-client_max_body_size 0;
-```
-
-### Apache
-
-For an Apache setup, refer to the [Apache proxy setup](Server%20Installation/2.%20Reverse%20proxy/Apache%20using%20Docker.md) guide.
+For Apache configuration, see the [Apache proxy setup](1_Server%20Installation/2.%20Reverse%20proxy/Apache.md) guide.

docs/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Manually.md

@@ -62,4 +62,4 @@ The application by default starts up on port 8080, so you can open your browser
 
 ## TLS
 
-Don't forget to [configure TLS](../HTTPS%20\(TLS\).md) which is required for secure usage!
+Don't forget to [configure TLS](../TLS%20Configuration.md) which is required for secure usage!

docs/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Multiple server instances.md

@@ -1,5 +1,5 @@
 # Multiple server instances
-Trilium does not support multiple users. In order to have two or more persons with their own set of notes, multiple server instances must be set up. It is also not possible to use multiple [sync](../../Synchronization.md) servers.
+Trilium does not support multiple users. In order to have two or more persons with their own set of notes, multiple server instances must be set up. It is also not possible to use multiple [sync](#root/KFhm9yCthQOh) servers.
 
 To allow multiple server instances on a single physical server:
 

docs/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Packaged version for Linux.md

@@ -174,8 +174,8 @@ Error: /usr/lib64/libstdc++.so.6: version `GLIBCXX_3.4.21' not found (required b
     at tryModuleLoad (module.js:505:12)
 ```
 
-If you get an error like this, you need to either upgrade your glibc (typically by upgrading to up-to-date distribution version) or use some other [server installation](../../Server%20Installation.md) method.
+If you get an error like this, you need to either upgrade your glibc (typically by upgrading to up-to-date distribution version) or use some other [server installation](../../1_Server%20Installation.md) method.
 
 ## TLS
 
-Don't forget to [configure TLS](../HTTPS%20\(TLS\).md), which is required for secure usage!
+Don't forget to [configure TLS](../TLS%20Configuration.md), which is required for secure usage!

docs/User Guide/User Guide/Installation & Setup/Server Installation/1. Installing the server/Using Docker.md

@@ -109,7 +109,7 @@ If you want to run your instance in a non-default way, please use the volume swi
 ## Reverse Proxy
 
 1.  [Nginx](../2.%20Reverse%20proxy/Nginx.md)
-2.  [Apache](../2.%20Reverse%20proxy/Apache%20using%20Docker.md)
+2.  [Apache](../2.%20Reverse%20proxy/Apache.md)
 
 ### Note on --user Directive
 
@@ -187,7 +187,7 @@ docker run -d --name trilium -p 8080:8080 --user $(id -u):$(id -g) -v ~/trilium-
 *   `TRILIUM_GID`: GID to use for the container process (passed to Docker's `--user` flag)
 *   `TRILIUM_DATA_DIR`: Path to the data directory inside the container (default: `/home/node/trilium-data`)
 
-For a complete list of configuration environment variables (network settings, authentication, sync, etc.), see <a class="reference-link" href="../../../Advanced%20Usage/Configuration%20(config.ini%20or%20e.md">Configuration (config.ini or environment variables)</a>.
+For a complete list of configuration environment variables (network settings, authentication, sync, etc.), see <a class="reference-link" href="#root/1CEQXvOOO4EK">Configuration (config.ini or environment variables)</a>.
 
 ### Volume Permissions
 

docs/User Guide/User Guide/Installation & Setup/Server Installation/2. Reverse proxy/Apache.md

@@ -0,0 +1,81 @@
+# Apache
+I've assumed you have created a DNS A record for `trilium.yourdomain.com` that you want to use for your Trilium server.
+
+1.  Download docker image and create container
+    
+    ```
+     docker pull triliumnext/trilium:[VERSION]
+     docker create --name trilium -t -p 127.0.0.1:8080:8080 -v ~/trilium-data:/home/node/trilium-data triliumnext/trilium:[VERSION]
+    ```
+2.  Configure Apache proxy and websocket proxy
+    
+    1.  Enable apache proxy modules
+        
+        ```
+         a2enmod ssl
+         a2enmod proxy
+         a2enmod proxy_http
+         a2enmod proxy_wstunnel
+        ```
+    2.  Create a new let's encrypt certificate
+        
+        ```
+         sudo certbot certonly -d trilium.mydomain.com
+        ```
+        
+        Choose standalone (2) and note the location of the created certificates (typically /etc/letsencrypt/live/...)
+    3.  Create a new virtual host file for apache (you may want to use `apachectl -S` to determine the server root location, mine is /etc/apache2)
+        
+        ```
+         sudo nano /etc/apache2/sites-available/trilium.yourdomain.com.conf
+        ```
+        
+        Paste (and customize) the following text into the configuration file
+        
+        ```
+         
+             ServerName http://trilium.yourdomain.com
+             RewriteEngine on
+                 RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,QSA,R=permanent]
+         
+         
+             ServerName https://trilium.yourdomain.com
+             RewriteEngine On
+             RewriteCond %{HTTP:Connection} Upgrade [NC]
+             RewriteCond %{HTTP:Upgrade} websocket [NC]
+             RewriteRule /(.*) ws://localhost:8080/$1 [P,L]
+             AllowEncodedSlashes NoDecode
+             ProxyPass / http://localhost:8080/ nocanon
+             ProxyPassReverse / http://localhost:8080/
+             SSLCertificateFile /etc/letsencrypt/live/trilium.yourdomain.com/fullchain.pem
+             SSLCertificateKeyFile /etc/letsencrypt/live/trilium.yourdomain.com/privkey.pem
+             Include /etc/letsencrypt/options-ssl-apache.conf
+         
+        ```
+    4.  Enable the virtual host with `sudo a2ensite trilium.yourdomain.com.conf`
+    5.  Reload apache2 with `sudo systemctl reload apache2`
+3.  Create and enable a systemd service to start the docker container on boot
+    
+    1.  Create a new empty file called `/lib/systemd/system/trilium.service` with the contents
+        
+        ```
+         [Unit]
+         Description=Trilium Server
+         Requires=docker.service
+         After=docker.service
+        
+         [Service]
+         Restart=always
+         ExecStart=/usr/bin/docker start -a trilium
+         ExecStop=/usr/bin/docker stop -t 2 trilium
+        
+         [Install]
+         WantedBy=local.target
+        ```
+    2.  Install, enable and start service
+        
+        ```
+         sudo systemctl daemon-reload
+         sudo systemctl enable trilium.service
+         sudo systemctl start trilium.service
+        ```

docs/User Guide/User Guide/Installation & Setup/Server Installation/2. Reverse proxy/Nginx.md

@@ -1,24 +1,19 @@
 # Nginx
-Configure Nginx proxy and HTTPS. The operating system here is Ubuntu.
+Configure Nginx proxy and HTTPS. The operating system here is Ubuntu 18.04.
 
-## Installing Nginx
-
-Download Nginx and remove Apache2
-
-```
-sudo apt-get install nginx
-sudo apt-get remove apache2
-```
-
-## Build the configuration file
-
-1.  First, create the configuration file:
+1.  Download Nginx and remove Apache2
+    
+    ```
+    sudo apt-get install nginx
+    sudo apt-get remove apache2
+    ```
+2.  Create configure file
     
     ```
     cd /etc/nginx/conf.d
     vim default.conf
     ```
-2.  Fill the file with the context shown below, part of the setting show be changed. Then you can enjoy your web with HTTPS forced and proxy.
+3.  Fill the file with the context shown below, part of the setting show be changed. Then you can enjoy your web with HTTPS forced and proxy.
     
     ```
     # This part configures, where your Trilium server is running
@@ -59,29 +54,23 @@ sudo apt-get remove apache2
         return 301 https://$server_name$request_uri;
     }
     ```
-
-## Serving under a different path
-
-Alternatively if you want to serve the instance under a different path (useful e.g. if you want to serve multiple instances), update the location block like so:
-
-*   update the location with your desired path (make sure to not leave a trailing slash "/", if your `proxy_pass` does not end on a slash as well)
-*   add the `proxy_cookie_path` directive with the same path: this allows you to stay logged in at multiple instances at the same time.
-
-```
-    location /trilium/instance-one {
-        rewrite /trilium/instance-one/(.*) /$1  break;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-        proxy_pass http://trilium;
-        proxy_cookie_path / /trilium/instance-one
-        proxy_read_timeout 90;
-    }
-```
-
-## Configuring the trusted proxy
-
-After setting up a reverse proxy, make sure to configure the <a class="reference-link" href="Trusted%20proxy.md">Trusted proxy</a>.
+4.  Alternatively if you want to serve the instance under a different path (useful e.g. if you want to serve multiple instances), update the location block like so:
+    
+    *   update the location with your desired path (make sure to not leave a trailing slash "/", if your `proxy_pass` does not end on a slash as well)
+    *   add the `proxy_cookie_path` directive with the same path: this allows you to stay logged in at multiple instances at the same time.
+    
+    ```
+        location /trilium/instance-one {
+            rewrite /trilium/instance-one/(.*) /$1  break;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "upgrade";
+            proxy_pass http://trilium;
+            proxy_cookie_path / /trilium/instance-one
+            proxy_read_timeout 90;
+        }
+    
+    ```

docs/User Guide/User Guide/Installation & Setup/Server Installation/Authentication.md

@@ -25,7 +25,7 @@ When “Remember me” is unchecked, the behavior is different. At client/browse
 
 ## Viewing active sessions
 
-The login sessions are now stored in the same <a class="reference-link" href="../../Advanced%20Usage/Database.md">Database</a> as the user data. In order to view which sessions are active, open the <a class="reference-link" href="../../Advanced%20Usage/Database/Manually%20altering%20the%20database/SQL%20Console.md">SQL Console</a> and run the following query:
+The login sessions are now stored in the same <a class="reference-link" href="#root/lvXOQ00dcRlk">Database</a> as the user data. In order to view which sessions are active, open the <a class="reference-link" href="#root/hDJ4mPkZJQ4E">SQL Console</a> and run the following query:
 
 ```
 SELECT * FROM sessions

docs/User Guide/User Guide/Installation & Setup/Server Installation/Multi-Factor Authentication.md

@@ -36,7 +36,7 @@ MFA can only be set up on a server instance.
 
 In order to setup OpenID, you will need to setup a authentication provider. This requires a bit of extra setup. Follow [these instructions](https://developers.google.com/identity/openid-connect/openid-connect) to setup an OpenID service through google. The Redirect URL of Trilium is `https://<your-trilium-domain>/callback`.
 
-1.  Set the `oauthBaseUrl`, `oauthClientId` and `oauthClientSecret` in the `config.ini` file (check <a class="reference-link" href="../../Advanced%20Usage/Configuration%20(config.ini%20or%20e.md">Configuration (config.ini or environment variables)</a> for more information).
+1.  Set the `oauthBaseUrl`, `oauthClientId` and `oauthClientSecret` in the `config.ini` file (check <a class="reference-link" href="#root/SneMubD5wTR6">Configuration (config.ini or environment variables)</a> for more information).
     1.  You can also setup through environment variables:
         *   Standard: `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHBASEURL`, `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTID`, `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET`
         *   Legacy (still supported): `TRILIUM_OAUTH_BASE_URL`, `TRILIUM_OAUTH_CLIENT_ID`, `TRILIUM_OAUTH_CLIENT_SECRET`

docs/User Guide/User Guide/Installation & Setup/Server Installation/TLS Configuration.md

@@ -0,0 +1,53 @@
+# TLS Configuration
+Configuring TLS is essential for [server installation](../1_Server%20Installation.md) in Trilium. This guide details the steps to set up TLS within Trilium itself.
+
+For a more robust solution, consider using TLS termination with a reverse proxy (recommended, e.g., Nginx). You can follow a [guide like this](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-20-04) for such setups.
+
+## Obtaining a TLS Certificate
+
+You have two options for obtaining a TLS certificate:
+
+*   **Recommended**: Obtain a TLS certificate signed by a root certificate authority. For personal use, [Let's Encrypt](https://letsencrypt.org) is an excellent choice. It is free, automated, and straightforward. Certbot can facilitate automatic TLS setup.
+*   Generate a self-signed certificate. This option is not recommended due to the additional complexity of importing the certificate into all machines connecting to the server.
+
+## Modifying `config.ini`
+
+Once you have your certificate, modify the `config.ini` file in the [data directory](#root/dvbMBRXYMM2G) to configure Trilium to use it:
+
+```
+[Network]
+port=8080
+# Set to true for TLS/SSL/HTTPS (secure), false for HTTP (insecure).
+https=true
+# Path to the certificate (run "bash bin/generate-cert.sh" to generate a self-signed certificate).
+# Relevant only if https=true
+certPath=/[username]/.acme.sh/[hostname]/fullchain.cer
+keyPath=/[username]/.acme.sh/[hostname]/example.com.key
+```
+
+You can also review the [configuration](#root/SneMubD5wTR6) file to provide all `config.ini` values as environment variables instead. For example, you can configure TLS using environment variables:
+
+```sh
+export TRILIUM_NETWORK_HTTPS=true
+export TRILIUM_NETWORK_CERTPATH=/path/to/cert.pem
+export TRILIUM_NETWORK_KEYPATH=/path/to/key.pem
+```
+
+The above example shows how this is set up in an environment where the certificate was generated using Let's Encrypt's ACME utility. Your paths may differ. For Docker installations, ensure these paths are within a volume or another directory accessible by the Docker container, such as `/home/node/trilium-data/[DIR IN DATA DIRECTORY]`.
+
+After configuring `config.ini`, restart Trilium and access the hostname using "https".
+
+## Self-Signed Certificate
+
+If you opt to use a self-signed certificate for your server instance, note that the desktop instance will not trust it by default.
+
+To bypass this, disable certificate validation by setting the following environment variable (for Linux):
+
+```
+export NODE_TLS_REJECT_UNAUTHORIZED=0
+trilium
+```
+
+Trilium provides scripts to start in this mode, such as `trilium-no-cert-check.bat` for Windows.
+
+**Warning**: Disabling TLS certificate validation is insecure. Proceed only if you fully understand the implications.