@cplace/mcp-server 1.3.14

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-lowCodeWidgets-lowCodeText/research.md

@@ -0,0 +1,176 @@
+# Low-Code Text Widget Research
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.lowCodeWidgets.lowCodeText`
+**Widget Name:** Low-Code Text
+**Repository:** `cplace-paw`
+**Definition Class:** `cf.cplace.lowCodeWidgets.script.LowCodeTextWidgetDefinition`
+
+### Purpose (1-2 Sentence Description)
+
+The Low-Code Text widget executes a cplaceJS script and renders the returned string (which may contain HTML) as inline content within a rich string widget. It reactively re-evaluates its script when connected table data or selections change, enabling dynamic computed text that updates without page reload.
+
+---
+
+## Conceptual Documentation
+
+### Core Functionality
+
+The Low-Code Text widget allows administrators and low-code developers to embed dynamic, script-computed content directly within rich string widgets. When the page loads, the widget evaluates a JavaScript script that has access to contextual data (pages from search, connected tables, or explicit selections) and renders the returned value as HTML text. Unlike the Low-Code Button (which executes on click), the Low-Code Text widget evaluates automatically and updates reactively when its data sources change.
+
+### Use Cases
+
+#### 1. **Dynamic Computed Values in Rich Text**
+Display calculated or derived information inline within formatted page content:
+- Show aggregated metrics (sums, averages, counts) based on search results
+- Display conditional text based on page attributes or states
+- Render formatted summaries from multiple data sources
+
+#### 2. **Reactive Dashboards with Connected Tables**
+Create text content that updates when users interact with connected table widgets:
+- Show details about selected table rows
+- Display summary statistics that update as the table's data changes
+- Render context-specific information based on table selection
+
+#### 3. **Internationalized Dynamic Content**
+Generate localized content using the `messages` binding:
+- Display status messages in the user's language
+- Show dynamically computed text with proper localization
+- Combine static rich text layout with dynamic localized values
+
+#### 4. **Data-Driven HTML Rendering**
+Generate custom HTML markup based on page data:
+- Create visual indicators (colored badges, progress bars) based on attribute values
+- Render mini-tables or formatted lists from search results
+- Display formatted dates, numbers, or computed expressions
+
+---
+
+## Configuration Concepts
+
+### Script Structure
+
+The widget requires a cplaceJS script that returns a value to display. Unlike the Low-Code Button, the script does not need to return an object with methods -- it simply returns the text/HTML to render.
+
+Supported return types:
+- **String**: Rendered directly as HTML (sanitized via `RichStringUtilities.clean()`)
+- **Number**: Converted to string
+- **Boolean**: Converted to string
+- **Date**: Converted to string representation
+- **Localized object**: Object with language keys (e.g., `{en: "Hello", de: "Hallo"}`) -- resolved to user's language
+
+### Script Bindings
+
+The script has access to the following bindings:
+
+| Binding | Type | Description |
+|---------|------|-------------|
+| `pages` | `Iterable<WrappedPage>` | Pages from the configured data source (search, selection, or connected table) |
+| `searchResults` | `Iterable<WrappedCustomEntity<?>>` | All search results (if "Include All Search Results" is enabled) |
+| `embeddingPage` | `WrappedPage` | The page on which the widget is embedded |
+| `messages` | `CplaceJSTypeMessageProvider` | Access to internationalized messages defined in the embedding page's type definition |
+
+### Main Configuration Options
+
+#### 1. **Script Configuration**
+- **Script**: The cplaceJS script that produces the text to display. **Required.**
+
+#### 2. **Data Source Options**
+Multiple ways to provide data to the script (same as Low-Code Button):
+
+- **Search**: Define a search query whose results are available as the `pages` binding, with optional sort column and order
+- **Connected Table**: Connect to a table widget on the same page
+  - **Selection Only**: Only selected rows from the table are available
+  - Supports nested connected tables (connected table's own connected table)
+- **Selection**: Manually select specific pages to provide as the `pages` binding
+- **Include All Search Results**: Provides raw search results (not just pages) in the `searchResults` binding
+
+### Reactive Behavior
+
+The widget re-evaluates its script in response to connected table events:
+
+1. **Table data refresh**: When the connected table's data changes, the text widget re-evaluates (unless in "selection only" mode)
+2. **Row selection change**: When the user's row selection changes in the connected table (in "selection only" mode)
+3. **Nested table selection**: When a connected table's own connected table fires a selection event
+
+Re-evaluation is performed via an AJAX POST to `EvaluateTextHandler`, which re-runs the script server-side and returns the new HTML text.
+
+### Embedding Constraint
+
+This widget can **only** be embedded inside rich string widgets (`WidgetEmbedding.INSIDE_RICHSTRING`). It cannot be placed directly on a page layout. It renders without a frame and without padding, making it blend seamlessly into the surrounding rich text content.
+
+### Permissions and Access Control
+
+- **Embedding Permission**: Only users with "Low-Code permission" (`GlobalPermissions.mayEditLowCode()`) can embed this widget
+- **Script Editing**: The script attribute is only visible/editable to users with Low-Code permission
+
+### Integration with Other Widgets
+
+The Low-Code Text widget is:
+- **Embedded in**: Rich String widgets (`cf.platform.richString`) or Rich String Without Frame (`cf.cplace.demoWidgets.demoRichString`)
+- **Connected to**: Embedded Search as Table widgets (to react to data/selection changes)
+- **Nested**: Can work with connected tables that are themselves connected to other tables
+
+---
+
+## Related Concepts
+
+### Comparison with Low-Code Button Widget
+
+The Low-Code Text is part of a family of Low-Code widgets:
+
+| Aspect | Low-Code Text | Low-Code Button |
+|--------|---------------|-----------------|
+| **Purpose** | Display computed text/HTML | Execute actions on click |
+| **Script return** | String, number, date, or localized object | Object with `checkAccess()` and `call()` methods |
+| **Execution** | Automatic on page load + reactive | User-triggered on click |
+| **Execution mode** | Always synchronous | Async (default) or synchronous |
+| **Embedding** | Rich string only | Anywhere, including attribute groups |
+| **Frame** | Never (frameless, no padding) | Configurable |
+| **Data source** | Identical 3-mode grouping | Identical 3-mode grouping |
+
+### Low-Code Script Engine
+
+The widget uses the cplace Low-Code script engine with:
+- **Sandboxed execution**: Scripts run in a controlled environment
+- **Type safety**: Access to typed wrappers for cplace entities
+- **Search/Filter access**: Scripts can use `Search` and `Filters` classes
+- **HTML sanitization**: Output is cleaned via `RichStringUtilities.clean()`
+
+---
+
+## Technical Details
+
+### Key Classes
+
+- **Definition**: `cf.cplace.lowCodeWidgets.script.LowCodeTextWidgetDefinition` (cf.cplace.lowCodeWidgets/src/main/java/cf/cplace/lowCodeWidgets/script/LowCodeTextWidgetDefinition.java:35)
+- **Evaluation**: `cf.cplace.lowCodeWidgets.utils.LowCodeTextWidgetUtils` (cf.cplace.lowCodeWidgets/src/main/java/cf/cplace/lowCodeWidgets/utils/LowCodeTextWidgetUtils.java:52)
+- **Handler**: `EvaluateTextHandler` (cf.cplace.lowCodeWidgets/src/main/java/cf/cplace/lowCodeWidgets/handler/EvaluateTextHandler.java:27)
+- **Configuration Type**: `LowCodeWidgetsWidgetTypes.LOW_CODE_TEXT_WIDGET` (cf.cplace.lowCodeWidgets/src/main/java/cf/cplace/lowCodeWidgets/LowCodeWidgetsWidgetTypes.java:37)
+
+### Frontend Components
+
+- **Controller**: `LowCodeTextWidgetCtrl` (cf.cplace.lowCodeWidgets/assets/ts/controllers/LowCodeTextWidgetCtrl.ts:11)
+- **Directive**: `lowCodeTextWidgetDirective` (cf.cplace.lowCodeWidgets/assets/ts/directives/lowCodeTextWidgetDirective.ts:4)
+- **Template**: `lowCodeTextWidgetDefinition.htm` (cf.cplace.lowCodeWidgets/src/main/resources/cf/cplace/lowCodeWidgets/script/lowCodeTextWidgetDefinition.htm)
+
+### Configuration Attributes
+
+| Attribute | Type | Required | Purpose |
+|-----------|------|----------|---------|
+| `SCRIPT` | SingleString (script) | Yes | The cplaceJS script to execute |
+| `SEARCH` | SingleString (search) | No | Search definition for finding pages |
+| `SORT_COLUMN` | SingleString | No | Column to sort search results by |
+| `SORT_ORDER` | SingleString | No | Sort direction |
+| `CONNECTED_TABLE` | SingleString | No | Widget ID of connected table |
+| `CONNECTED_TABLE_SELECTION_ONLY` | SingleBoolean | No | Use only selected rows |
+| `SELECTION` | MultiPageReference | No | Explicit page references |
+| `DATA_SOURCE` | AttributeGrouping | Yes | Switches between search/connected-table/selection modes |
+| `INCLUDE_ALL_SEARCH_RESULTS` | SingleBoolean | No | Also provide searchResults binding |
+
+---
+
+## Summary
+
+The Low-Code Text widget is the declarative counterpart to the Low-Code Button widget. While the button executes user-triggered actions, the text widget automatically evaluates a script and renders the result as HTML content within a rich string widget. Its reactive behavior with connected tables makes it suitable for building dynamic, data-driven page content that updates in response to user interactions elsewhere on the page.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-lowcode-ai-chatWidget/research.md

@@ -0,0 +1,194 @@
+# Chat Widget Research (`cf.cplace.lowcode.ai.chatWidget`)
+
+## Widget Overview
+
+The Chat Widget provides an embeddable AI-powered chat interface that allows users to interact with AI assistants through natural language conversations. It enables low-code developers to create custom conversational AI experiences by configuring a CplaceJS script that defines the chat behavior and access control.
+
+**Widget ID:** `cf.cplace.lowcode.ai.chatWidget`
+**Repository:** `cplace-citizen-ai`
+**Definition Class:** `cf.cplace.citizenAi/src/main/java/cf/cplace/citizenAi/widgets/ChatWidgetDefinition.java`
+
+---
+
+## Purpose and Core Functionality
+
+### What This Widget Does
+
+The Chat Widget embeds a chat interface on cplace pages where users can have conversational interactions with an AI assistant. The widget:
+
+1. **Displays a chat UI** - Uses a frontend web component (`cf-lowcode-ai`) to render the chat interface
+2. **Executes custom business logic** - Runs a CplaceJS script on each user message that defines how the AI responds
+3. **Persists conversations** - Stores chat history using `PersistentAiChatMemory`, either per-user or shared across all users
+4. **Provides page context** - Makes the embedding page, search results, and selected pages available to the script
+
+### Technical Architecture
+
+```
+User Input → Chat Widget Frontend (Angular)
+           → REST Endpoint (/chat/messages)
+           → ChatService.postMessage()
+           → ChatWidgetScriptExecutionProcessor.execute()
+           → CplaceJS Script (call() function)
+           → CitizenAiAssistant.generate()
+           → AI Model Response
+           → Persisted to Memory
+           → Response to Frontend
+```
+
+---
+
+## Use Cases
+
+### When to Use This Widget
+
+1. **Custom AI Chat Assistants** - Create page-specific AI assistants that can answer questions about projects, summarize data, or provide contextual help based on the page content
+
+2. **Data-Driven Conversations** - Build chat interfaces that can query and reason about pages retrieved from searches or connected tables, enabling users to ask questions about collections of data
+
+3. **Guided User Interactions** - Use prompt suggestions to guide users toward common questions or actions, making the AI more discoverable and useful
+
+4. **User-Specific vs. Shared Conversations** - Support both individual chat histories (each user sees their own conversation) or shared chat rooms (all users see the same conversation)
+
+5. **AI-Assisted Page Operations** - Allow the assistant to perform actions on pages (read/write) through No-Code Tools configured on the AI Assistant
+
+### Example Scenarios
+
+- **Project Dashboard Chat**: A project manager views a project page and asks the AI to "summarize the open high risks" - the AI analyzes related risk pages and provides a summary
+- **Document Q&A**: Users ask questions about documents embedded or linked to a page
+- **Status Reports**: Users request "create a management summary" and the AI generates a report based on configured data sources
+- **Interactive Help**: Domain-specific help that understands the context of the current page
+
+---
+
+## Configuration Concepts
+
+### Required Configuration
+
+| Configuration | Description |
+|--------------|-------------|
+| **Script** | CplaceJS script containing `checkAccess()` and `call()` functions (required) |
+
+### Core Configuration Options
+
+| Configuration | Type | Default | Description |
+|--------------|------|---------|-------------|
+| `showFrame` | Boolean | `false` | Whether to show the widget frame/border |
+| `localizedTitle` | Localized String | (default) | Title displayed in the widget header |
+| `isUserSpecificChat` | Boolean | `true` | If true, each user has their own chat history; if false, all users share the same conversation |
+| `maxMessages` | Number | `30` | Maximum messages retained in chat memory |
+| `showToolExecutions` | Boolean | `true` | Whether to display tool execution details in the UI |
+| `disclaimer` | Localized String | (default) | Disclaimer text shown in the chat interface |
+| `height` | Number | `500` | Widget height in pixels |
+
+### Data Source Configuration
+
+The widget supports configuring data sources that determine which pages are available to the script:
+
+| Option | Description |
+|--------|-------------|
+| **Search** | Pages from a configured search query (default) |
+| **Selection** | Explicitly selected pages |
+| **Connected Table** | Pages from a connected table widget |
+| `includeAllSearchResults` | Boolean to include all search results (not just paginated subset) |
+
+### Script Structure
+
+The CplaceJS script must return an object with specific functions:
+
+```javascript
+return {
+    // Required: Determines if the current user can use the chat
+    checkAccess: function() {
+        return true; // or false to disable
+    },
+
+    // Optional: Provide suggested prompts to users
+    suggestPrompts: function() {
+        return [{
+            "label": "My Project Status",
+            "icon": "fa-traffic-light",    // optional
+            "color": "#112233",            // optional
+            "prompt": 'Summarize the project...'
+        }];
+    },
+
+    // Required: Contains the actual business logic
+    call: function() {
+        const assistant = cplace.actions("cf.cplace.citizenAi")
+            .createAssistant(embeddingPage.getSpace(), "default", memory);
+        assistant.generate(userInput);
+    }
+}
+```
+
+### Script Bindings (Available Variables)
+
+| Binding | Type | Description |
+|---------|------|-------------|
+| `userInput` | String | The message text entered by the user |
+| `memory` | AiChatMemory | The persistent chat memory for context |
+| `pages` | Iterable\<WrappedPage\> | Pages from the configured data source |
+| `searchResults` | Iterable\<WrappedCustomEntity\> | All search results (if `includeAllSearchResults` is true) |
+| `embeddingPage` | WrappedPage | The page where the widget is embedded |
+
+---
+
+## Related Widgets and Context
+
+### Related Widget: Ask Your Page (`cf.cplace.citizenAi.askYourPageWidget`)
+
+- Simpler variant without script configuration
+- Provides pre-configured "Ask Your Page" functionality
+- Requires feature to be enabled in plugin settings
+- Same frontend component (`cf-wc-bridge` with `cf-lowcode-ai`)
+
+### Relationship to AI Assistants
+
+The Chat Widget works with **AI Assistant Configuration** pages:
+- Assistants are created via `cplace.actions("cf.cplace.citizenAi").createAssistant()`
+- Assistants can be configured with:
+  - Model ID (specifies which AI model to use)
+  - System message (defines the AI's persona/behavior)
+  - No-Code Tools (actions the AI can take)
+  - Temperature, max tokens, seed parameters
+
+### Dependencies
+
+| Dependency | Description |
+|------------|-------------|
+| Citizen AI Plugin | Core plugin providing AI functionality |
+| Low-Code permission | Required to embed and configure the widget |
+| AI Assistant Configuration | Optional - assistants can be created programmatically or from configuration pages |
+| Frontend Package | `@cplace-lowcode-ai-fe/cf-lowcode-ai` Angular web component |
+
+---
+
+## Permission Requirements
+
+1. **Embedding**: Only users with "Low-Code" edit permission can embed the widget
+2. **Access Control**: The `checkAccess()` function in the script determines runtime access
+3. **Space Embedding**: Widget can only be embedded in pages within spaces where the Citizen AI app is present
+4. **Script Visibility**: The script attribute is only visible in edit mode to users with Low-Code permission
+
+---
+
+## Key Implementation Files
+
+| File | Purpose |
+|------|---------|
+| `ChatWidgetDefinition.java` | Widget definition, configuration, and content rendering |
+| `AiWidgetTypes.java` | Configuration attribute definitions |
+| `ChatWidgetScriptUtils.java` | Creates script engine with bindings |
+| `ChatWidgetScriptExecutionProcessor.java` | Executes the CplaceJS script |
+| `ChatService.java` | REST service handling message operations |
+| `ChatWidgetContextualHelp.java` | Contextual help for the script attribute |
+| `chatWidgetDefinition.htm` | Frontend template with web component bridge |
+| `getHelpMarkup.htm` | Script template documentation |
+| `LowcodeAiActions.java` | API for creating assistants from scripts |
+| `CitizenAiAssistant.java` | AI assistant implementation with tool support |
+
+---
+
+## Summary
+
+The Chat Widget is a flexible, script-driven widget for embedding AI chat functionality into cplace pages. It provides a low-code approach to building custom AI assistants by allowing developers to write CplaceJS scripts that define the chat behavior while leveraging the platform's AI infrastructure (model connections, memory persistence, tool execution). The widget is suitable for scenarios requiring contextual AI assistance, data-driven Q&A, or interactive AI-powered features within the cplace application.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-meeting-pageHeader/research.md

@@ -0,0 +1,208 @@
+# Widget Research: cf.cplace.meeting.pageHeader
+
+## Widget Identification
+
+- **Widget ID**: `cf.cplace.meeting.pageHeader`
+- **Widget Name**: Meeting Details
+- **Repository**: cplace-paw
+- **Plugin**: cf.cplace.meeting
+- **Definition Class**: `cf.cplace.meeting.script.MeetingPageHeaderWidgetDefinition`
+
+## Purpose
+
+The Meeting Details widget displays comprehensive meeting/appointment information in a structured header format, showing time, location, participants (organizer, required and optional attendees), and providing quick access to edit attendees and export the meeting to Outlook calendar format (.ics file).
+
+## Overview
+
+This widget serves as the primary information display for appointment pages within the cplace Meetings app. It renders meeting metadata in a visually organized layout without a frame, providing an at-a-glance view of all essential meeting details along with actionable links for editing and calendar export.
+
+## Use Cases
+
+### Primary Use Case: Appointment Page Header
+The widget is automatically embedded as the default page header for all appointment pages (type `cf.appointment`) within the Meetings app. It provides users with:
+
+1. **Meeting Overview Display**
+   - Shows start and end dates with day-of-week formatting
+   - Displays meeting location
+   - Shows organizer information with profile image
+   - Lists required and optional attendees with profile images
+
+2. **Meeting Management Actions**
+   - Edit Attendees: Quick access to modify required and optional attendees
+   - Calendar Export: Download meeting as .ics file for Outlook/calendar integration
+
+3. **Visual Organization**
+   - Color-coded participant roles (organizer, required, optional)
+   - Profile images for all participants
+   - Structured layout with clear sections
+
+### Typical User Scenarios
+
+**Scenario 1: Viewing Meeting Details**
+- User opens an appointment page
+- Widget displays all meeting information at the top
+- User can quickly see who is invited, when the meeting is, and where it takes place
+
+**Scenario 2: Managing Attendees**
+- User clicks "Edit Attendees" link in the widget
+- Modal opens allowing modification of required/optional attendees
+- Changes are saved and widget updates to reflect new attendee list
+
+**Scenario 3: Calendar Integration**
+- User clicks the Outlook/calendar download link
+- Widget generates .ics file with meeting details
+- User imports file into their personal calendar application
+
+## Data Model Integration
+
+The widget integrates with the **APPOINTMENT** type (`cf.appointment`) which includes:
+
+### Required Attributes
+- **Subject** (`cf.appointmentSubject`): Meeting title
+- **Organizer** (`cf.appointmentOrganizer`): Person reference for meeting organizer
+- **Start Date** (`cf.appointmentDtstart`): Meeting start date
+- **Start Time** (`cf.appointmentDtstartTime`): Meeting start time (HH:mm format)
+- **End Date** (`cf.appointmentFinish`): Meeting end date
+- **End Time** (`cf.appointmentEndTime`): Meeting end time (HH:mm format)
+
+### Optional Attributes
+- **Required Attendees** (`cf.appointmentReqAttendees`): Multi-person reference
+- **Optional Attendees** (`cf.appointmentOptAttendees`): Multi-person reference
+- **Location** (`cf.appointmentLocation`): String value for meeting location
+- **Summary** (`cf.appointmentSummary`): Rich text description/agenda
+- **Minutes** (`cf.appointmentMinutes`): Rich text for meeting notes
+
+## Configuration Concepts
+
+### Widget Behavior
+- **Frame Display**: The widget renders without a frame (`showFrame() = false`)
+- **Scope Object**: Uses the appointment page as the scope object
+- **Initialization**: Widget automatically binds to the appointment page it's embedded in
+
+### No User-Configurable Options
+This widget does not expose configuration parameters. It operates with a fixed behavior:
+- Automatically displays all appointment attributes
+- Links are generated based on the current page context
+- Styling is controlled by the plugin's LESS stylesheet
+
+### Template Substitutions
+The widget provides the following data to its template:
+- `editAttendeesUrl`: URL for editing attendees
+- `dtStartDateWithWeekDay`: Formatted start date with weekday name
+- `dtFinishDateWithWeekDay`: Formatted end date with weekday name
+- `downloadAsCalFileUrl`: URL for downloading .ics file
+- `organizerImage`: Profile image URL for organizer
+- `organizerName`: Name of the organizer
+- `reqAttendees`: List of required attendees with image and name
+- `optAttendees`: List of optional attendees with image and name
+
+## Related Components
+
+### Related Handlers
+1. **EditHandler** (`cf.cplace.meeting.handler.EditHandler`)
+   - Provides editing interface for meeting attendees
+   - Accessed via "Edit Attendees" link in widget
+   - Requires edit permissions on the appointment page
+
+2. **DownloadAsCalFileHandler** (`cf.cplace.meeting.handler.DownloadAsCalFileHandler`)
+   - Generates iCalendar (.ics) file from appointment data
+   - Includes all meeting details, attendees, and links
+   - Accessed via "Open in Outlook" link in widget
+
+### Default Page Layout
+The widget is part of the default layout for appointment pages:
+```
+Row 1:
+  Column 1 (8 units):
+    - Meeting Page Header Widget (this widget)
+    - Minutes (rich text attribute widget)
+  Column 2 (4 units):
+    - Files Widget
+    - Comments Widget
+```
+
+### Styling
+- Custom CSS class: `.cf-cplace-meeting-headerPage-widget-body`
+- Branded colors based on plugin theme (`@meeting-plugin-base-color`)
+- Responsive design with mobile breakpoint at 991px
+- Visual distinction for organizer (gray), required attendees (green), optional attendees (blue)
+
+## Technical Details
+
+### Widget Definition Location
+- File: `/cf.cplace.meeting/src/main/java/cf/cplace/meeting/script/MeetingPageHeaderWidgetDefinition.java`
+- Package: `cf.cplace.meeting.script`
+- Extends: `WidgetDefinition`
+
+### Internationalization
+- Widget name and description defined in: `cf/cplace/meeting/messages_en.properties`
+- English name: "Meeting Details"
+- English description: "Displays meeting details such as time, location, participants and agenda."
+- Additional message keys for labels (organizer, required, optional, location, etc.)
+
+### Date Formatting
+- Uses `InternalDateFormats.NAME_OF_DAY` for displaying dates with weekday names
+- Respects user locale for date formatting (`SessionLocal.getUserLocale()`)
+
+### Person/User Integration
+- Works specifically with `Person` entities for organizer and attendees
+- Displays profile images using `FunctionsHelper.proxy("profileImgUrl", person)`
+- Falls back to empty string if reference is not a Person entity
+
+## Dependencies
+
+### Plugin Dependencies
+- **cf.cplace.platform** (version 25.3.80): Core platform functionality
+
+### App Context
+Part of the **Meetings** app (`cf.cplace.meeting.MeetingApp`):
+- App display name: "Meetings"
+- App icon: `fa-calendar`
+- App description: "With the 'Meetings' app, you can create appointments as pages and keep minutes. You can download the appointments as .ics files to send them or save them in your personal calendar."
+
+## Usage Constraints
+
+### Prerequisites
+1. The Meetings app must be installed and enabled in the workspace
+2. Appointment type must be available
+3. User must have read permissions on the appointment page
+
+### Limitations
+1. Widget only works on appointment pages (type `cf.appointment`)
+2. Returns `null` for meeting if embedded entity is not a Page
+3. No configuration options - fixed behavior
+4. Requires Person entities for proper attendee display
+
+## Key Features Summary
+
+1. **Comprehensive Meeting Information Display**
+   - All critical meeting data in one place
+   - Formatted dates with weekday names
+   - Visual participant organization
+
+2. **Quick Actions**
+   - One-click access to edit attendees
+   - Direct calendar export functionality
+
+3. **Visual Design**
+   - Profile images for human context
+   - Color-coded participant roles
+   - Responsive layout for mobile devices
+
+4. **Integration**
+   - Seamlessly works with Person directory
+   - Calendar file export for external tool integration
+   - Locale-aware date formatting
+
+## Code References
+
+### Key Files
+- Widget Definition: `/cf.cplace.meeting/src/main/java/cf/cplace/meeting/script/MeetingPageHeaderWidgetDefinition.java:30`
+- Type Definition: `/cf.cplace.meeting/src/main/java/cf/cplace/meeting/MeetingAppTypes.java:31`
+- Edit Handler: `/cf.cplace.meeting/src/main/java/cf/cplace/meeting/handler/EditHandler.java:16`
+- Calendar Export Handler: `/cf.cplace.meeting/src/main/java/cf/cplace/meeting/handler/DownloadAsCalFileHandler.java:21`
+- Styling: `/cf.cplace.meeting/assets/less/plugin.less:11`
+
+### Default Widget Inclusion
+The widget is included by default in the appointment type definition at:
+`/cf.cplace.meeting/src/main/java/cf/cplace/meeting/MeetingAppTypes.java:115`