@cplace/mcp-server 1.6.0 → 1.6.2

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-citizenAi-askYourPageWidget/research.md

@@ -1,319 +0,0 @@
-# Research: Ask Your Page Widget
-
-## Widget Information
-
-- **Widget ID**: `cf.cplace.citizenAi.askYourPageWidget`
-- **Widget Name**: Ask Your Page
-- **Repository**: cplace-citizen-ai
-- **Plugin**: Citizen AI (`cf.cplace.citizenAi`)
-- **Definition Class**: `cf.cplace.citizenAi/src/main/java/cf/cplace/citizenAi/widgets/AskYourPageWidgetDefinition.java`
-- **Icon**: fa-code
-
-## 1. Purpose & Core Functionality
-
-### What This Widget Does
-
-The Ask Your Page widget is an AI-powered chat interface that enables users to ask natural language questions about the current page they're viewing and get intelligent responses. It's a context-aware AI assistant that has deep knowledge about the page's attributes, relationships, files, and connected data.
-
-### Key Features
-
-1. **Page-Focused AI Assistant**: Automatically understands the context of the embedding page, including:
-   - All page attributes (name, content, creator, creation date, modifier, last modification timestamp)
-   - Page type and structure
-   - Incoming references from other pages
-   - Attached files and documents
-
-2. **AI-Powered Tools**: The assistant has access to three specialized tools:
-   - `getPageById`: Retrieves detailed information about any page by its ID
-   - `getFileContent`: Accesses and reads the content of files attached to pages
-   - `getReferencingPages`: Finds all pages that reference a given page of a specific type
-
-3. **Persistent Chat Memory**: Maintains conversation history per user on each page, allowing contextual follow-up questions
-
-4. **Smart URL Generation**: The AI provides clickable links to pages and files instead of exposing internal IDs to users
-
-## 2. Use Cases
-
-### Primary Use Cases
-
-1. **Page Exploration & Discovery**
-   - "What is this page about?"
-   - "Show me all the key information on this page"
-   - "What files are attached to this page?"
-   - "Which other pages reference this one?"
-
-2. **Relationship Navigation**
-   - "Show me all projects that reference this requirement"
-   - "What tasks are linked to this milestone?"
-   - "Find all related documentation pages"
-
-3. **Content Analysis**
-   - "Summarize the content of the attached document"
-   - "What are the main attributes of this page?"
-   - "When was this page last modified and by whom?"
-
-4. **Cross-Page Information Gathering**
-   - "Get details about page X that's referenced here"
-   - "What's the status of the linked project?"
-   - "Show me the content of the specification document attached to the related page"
-
-### When to Use This Widget
-
-- **Information-rich pages**: Pages with many attributes, relationships, or attached documents
-- **Complex data structures**: When pages have multiple incoming/outgoing references
-- **Documentation pages**: Technical specifications, requirements, or knowledge base articles
-- **Project/task pages**: Where users need to understand relationships and dependencies
-- **Pages requiring frequent information lookup**: Where users regularly need to query page data
-
-### When NOT to Use This Widget
-
-- **Simple pages with minimal content**: The widget adds overhead for pages that don't benefit from AI assistance
-- **Pages where data input is the focus**: This is a read-only query interface, not for data entry
-- **Public-facing pages**: Requires Low-Code permissions (see Access Control below)
-
-## 3. Configuration Concepts
-
-### Available Configuration Options
-
-1. **Show Widget Frame** (boolean, default: `true`)
-   - Controls whether the widget displays in a bordered frame or inline
-   - Set to false for seamless integration into page layouts
-
-2. **Localized Title** (localized string, default: "What can I help you with?")
-   - Customizable title displayed at the top of the chat interface
-   - Supports multiple languages
-
-3. **Maximum Number of Messages** (number, default: 30)
-   - Limits the chat history retention
-   - When exceeded, oldest messages are automatically evicted
-   - Helps manage memory and storage
-
-4. **Show Tool Executions** (boolean, default: `false`)
-   - When enabled, displays when the AI assistant is executing tools (e.g., "Getting page by ID...")
-   - Provides transparency into AI operations
-   - Useful for debugging or understanding AI behavior
-
-5. **Disclaimer** (localized string, default: "AI models can make mistakes. Always verify important information.")
-   - Legal/informational disclaimer displayed to users
-   - Can be customized per organization policy
-
-6. **Height** (number, default: 500px)
-   - Fixed height of the widget in pixels
-   - Ensures consistent layout across pages
-
-### System Message Template
-
-The widget uses a predefined system message that provides the AI with:
-- Current date context
-- Page name and context
-- Available tools and their usage
-- Instructions to use links instead of IDs
-- Guidance on how to structure responses
-
-## 4. Context & Relationships
-
-### Relationship to Other Features
-
-#### Citizen AI Chat Widget (`cf.cplace.lowcode.ai.chatWidget`)
-
-The Ask Your Page widget is a **specialized, simplified version** of the more flexible Chat Widget:
-
-**Differences:**
-
-| Feature | Ask Your Page Widget | Chat Widget |
-|---------|---------------------|-------------|
-| **Purpose** | Page-specific Q&A | General-purpose AI chat |
-| **Data Source** | Always the embedding page | Configurable (search, table, selection) |
-| **Customization** | Fixed tools, no scripting | Fully scriptable via Low-Code |
-| **Tools** | Built-in page tools | Custom tools via script |
-| **User Scope** | Always user-specific | Can be shared or user-specific |
-| **Complexity** | Simple, zero-config | Advanced, requires Low-Code scripting |
-| **Use Case** | Quick page exploration | Complex workflows, custom AI behavior |
-
-**When to choose Ask Your Page over Chat:**
-- You want a ready-to-use solution without scripting
-- Focus is exclusively on the current page and its relationships
-- Users need simple question-answer functionality
-- No custom AI behavior required
-
-**When to choose Chat over Ask Your Page:**
-- Need to query multiple pages or a data source
-- Require custom tools or AI behavior
-- Want to implement specific workflows
-- Need shared chat history across users
-
-### Plugin Dependencies
-
-The widget is part of the **Citizen AI plugin** (`cf.cplace.citizenAi`) which:
-- Extends cPlace's AI capabilities with Low-Code integration
-- Provides reusable AI Assistant configurations
-- Requires the platform's AI configuration to be enabled
-- Depends on LangChain4j for AI orchestration
-
-### Access Control
-
-**Permissions Required:**
-1. **Embedding Permission**: Users must have Low-Code edit permission (`GlobalPermissions.mayEditLowCode()`) to add this widget to a page
-2. **Usage Permission**: Once embedded, any user with page view access can interact with the widget
-3. **Plugin Setting**: The "Ask Your Page" feature must be enabled in plugin settings (`isAskYourPageEnabled()`)
-4. **Default Model**: A default AI model must be configured in plugin settings
-
-**Read-Only Mode:**
-- The widget automatically enters read-only mode if it's not embedded in a Page (e.g., in layouts or other contexts)
-- This prevents chat functionality in unsupported contexts
-
-### Technical Architecture
-
-**Backend Components:**
-- `AskYourPageService`: Core service handling message processing and AI orchestration
-- `AskYourPageController`: REST endpoint (`/cplace-fe/cf.cplace.citizenAi/ask-your-page/messages`)
-- `AskYourPageTools`: Built-in tools for page information retrieval
-- `PersistentAiChatMemory`: Chat history storage per user/page/widget
-
-**AI Model Integration:**
-- Uses LangChain4j for AI assistant orchestration
-- Configurable model via plugin settings (default model ID)
-- Temperature: DEFAULT, Seed: 12345 for reproducibility
-- Retrieval-Augmented Generation (RAG) capabilities for page content
-
-**Data Flow:**
-1. User sends message via frontend
-2. Backend retrieves widget configuration and page context
-3. System message is constructed with page details
-4. AI assistant processes message with access to three tools
-5. AI can call tools to retrieve additional information
-6. Response is returned with markdown formatting and links
-7. Conversation history is persisted for future context
-
-## 5. Key Implementation Details
-
-### Built-in Attributes Included
-
-When converting a page to context for the AI, these attributes are always included:
-- `name`: Page title
-- `content`: Page description/content
-- `creator`: User who created the page
-- `createdAt`: Creation timestamp
-- `modifier`: User who last modified the page
-- `lastModificationTimestamp`: Last modification date
-
-### File Handling
-
-- Only files with searchable content (fulltext) are included
-- Files are presented as links with names and URLs
-- File content can be retrieved via the `getFileContent` tool
-- Supports document summarization and content analysis
-
-### Reference Handling
-
-- Incoming references are grouped by type
-- The AI receives a list of all types that reference the page
-- Can retrieve detailed information about referencing pages by type
-- References are sorted by creation date
-
-### Markdown Output
-
-The AI generates responses in markdown format, including:
-- Page links: `[Page Name](url)`
-- File links: `[File Name](url)`
-- Structured content with headers, lists, and formatting
-- Code blocks for technical content
-
-## 6. Configuration vs. Chat Widget Comparison
-
-### Similarities
-- Both support localized titles
-- Both have message limits
-- Both can show/hide tool executions
-- Both display disclaimers
-- Both use persistent chat memory
-
-### Unique to Ask Your Page
-- No scripting required (zero Low-Code configuration)
-- Automatic page context injection
-- Built-in page exploration tools
-- Always user-specific (no shared mode)
-- Simpler permission model
-
-### Unique to Chat Widget
-- Script attribute for custom behavior
-- Data source configuration (search/table/selection)
-- Custom tool implementation
-- Prompt suggestions via script
-- Access control via script
-- Can be shared across users
-- More flexible data binding
-
-## 7. Best Practices & Recommendations
-
-### Configuration Best Practices
-
-1. **Enable Tool Executions During Testing**: Set `showToolExecutions: true` when first deploying to help users understand AI behavior
-
-2. **Adjust Message Limit Based on Use Case**:
-   - Simple pages: 20-30 messages
-   - Complex pages with frequent queries: 50+ messages
-   - Consider storage implications for high-traffic pages
-
-3. **Customize the Title**: Use descriptive titles like "Ask About This Requirement" or "Project Q&A"
-
-4. **Frame vs. Frameless**:
-   - Use frame (default) for standalone widgets
-   - Disable frame for tighter integration in custom layouts
-
-### Use Case Recommendations
-
-**Recommended for:**
-- Technical documentation pages
-- Requirement specifications
-- Project dashboards
-- Knowledge base articles
-- Complex data pages with many relationships
-
-**Not recommended for:**
-- Form pages (use Chat Widget with custom scripts)
-- Simple list pages
-- Pages without significant content or relationships
-- Highly dynamic pages where data changes frequently
-
-### Performance Considerations
-
-- Each message triggers AI model inference (cost consideration)
-- Tool executions add latency (getPageById, getFileContent)
-- Large files may take longer to process
-- Chat memory persisted in database (storage consideration)
-
-## 8. Future Extension Points
-
-Based on the code structure, potential extensions could include:
-
-1. **Custom Tool Addition**: Extend `AskYourPageTools` with domain-specific tools
-2. **Enhanced File Support**: Add support for image analysis, PDF parsing
-3. **Search Integration**: Add tool to search across workspace
-4. **Workflow Integration**: Tools to trigger actions or workflows
-5. **Export Capabilities**: Export conversations or summaries
-6. **Analytics**: Track common questions and AI performance
-
-## 9. Summary
-
-The Ask Your Page widget is a **specialized, zero-configuration AI chat interface** designed for page exploration and information discovery. It excels at helping users understand page content, navigate relationships, and access connected information through natural language queries.
-
-**Key Strengths:**
-- Simple to deploy (no scripting required)
-- Intelligent page context awareness
-- Built-in tools for page/file/reference exploration
-- User-friendly natural language interface
-
-**Key Limitations:**
-- Limited to page-centric queries
-- Cannot be customized without code changes
-- No shared chat mode
-- Requires Low-Code permissions to embed
-
-**Ideal Use Cases:**
-- Documentation and knowledge management
-- Complex pages requiring frequent information lookup
-- Pages with rich relationships and attached files
-- Scenarios where users need to quickly understand page context
-
-For more advanced use cases requiring custom AI behavior, data source flexibility, or shared conversations, the Chat Widget is the better choice.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-cplaceReportGeneration-generateReportWidget/research.md

@@ -1,295 +0,0 @@
-# Generate Report Widget Research
-
-## Widget Information
-- **Widget ID**: `cf.cplace.cplaceReportGeneration.generateReportWidget`
-- **Widget Name**: Report Creation
-- **Repository**: `cplace-office-reports`
-- **Definition Class**: `cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/script/GenerateReportWidgetDefinition.java`
-- **App**: cplace Report Generation
-
-## 1. Purpose & Description
-
-### Short Description
-This widget provides a button for generating and downloading Office reports (Word, PowerPoint, Excel) based on configurable templates and Low-Code scripts that pull data from cplace.
-
-### Detailed Description
-The Generate Report Widget is a user interface component that enables users to trigger the generation of Office documents (Word, PowerPoint, or Excel) directly from within cplace pages. When clicked, the widget button initiates a background job that executes a Low-Code script to populate a pre-defined Office template with data from cplace, then makes the generated report available for download or automatically attaches it to a specified page.
-
-The widget integrates with the broader cplace Office Reports functionality, which allows administrators to create Report Configuration pages that define:
-- The Office template to use (DOCX, PPTX, or XLSX)
-- A Low-Code script that specifies what data to include and how to populate template placeholders
-- File naming conventions
-- Attachment targets and behaviors
-
-**Key Characteristics:**
-- Class-level documentation (line 52-54 in GenerateReportWidgetDefinition.java): "Widget for the generation of reports. Can be hidden with custom logic by implementing CheckAccessInterceptors.AsPluginExtension on GenerateReportHandler."
-- Default button label: "Generate Report"
-- Default widget title: "Report {0}" (where {0} is the name of the linked Report Configuration)
-- Widget description: "Widget for generating and downloading Office reports"
-
-## 2. Use Cases
-
-### Primary Use Cases
-
-1. **On-Demand Report Generation from Page Context**
-   - Users need to generate a formatted Office document based on the current page's data
-   - Example: Generate a project status report (Word/PowerPoint) from a project page showing current milestones, risks, and team members
-   - The widget button appears on the page, and clicking it triggers report generation with the page as context
-
-2. **Batch Report Generation from Search Results**
-   - Users need to generate a report containing data from multiple pages matching specific criteria
-   - Example: Generate an Excel report listing all active projects in a portfolio with their KPIs
-   - The widget is configured with a search query, and the Low-Code script accesses all search results to populate the report
-
-3. **Report Generation from Table Selections**
-   - Users need to generate reports based on specific rows they've selected in a connected table widget
-   - Example: User selects 5 tasks from a table and generates a detailed task report for just those items
-   - The widget can be configured to work with table selections or the entire table result set
-
-4. **Custom Report with Additional User Input**
-   - Users need to provide additional data at report generation time that isn't stored in cplace
-   - Example: Generate a project report and prompt user to enter a comment or reporting period
-   - The widget can trigger a dialog to collect additional data before generating the report
-
-5. **Automated Document Attachment to Pages**
-   - System needs to automatically attach generated reports to specific pages for record-keeping
-   - Example: Monthly status report is generated and automatically attached to the project page's document attribute
-   - The widget can be configured to attach reports to the embedding page or a related page
-
-### Integration Scenarios
-
-- **Embedded in Attributes Group Widgets**: The widget can be embedded inside AttributesGroupWidgetDefinition or ConnectedAttributesGroupWidgetDefinition (lines 93-98 in GenerateReportWidgetDefinition.java)
-- **Page Actions**: Can be integrated as a page action for report generation workflows
-- **Dashboard Widgets**: Can be placed on dashboards for quick access to frequently generated reports
-
-## 3. Configuration Concepts
-
-### Core Configuration Attributes
-
-#### 3.1 Report Configuration (Required)
-- **Attribute**: `REPORT_CONFIGURATION` (SinglePageReferenceAttributeDef)
-- **Purpose**: Links to a Report Configuration page that defines the template, script, and report behavior
-- **Type Constraint**: Must reference a page of type `cf.cplace.officeReports.configuration`
-- **Description**: This is the master configuration that defines:
-  - Report template (Office document with placeholders)
-  - Low-Code script for data population
-  - Report type (Word/PowerPoint/Excel)
-  - Default attachment behaviors
-
-#### 3.2 Data Source
-- **Attribute**: `DATA_SOURCE` (AttributeGroupingAttributeDef)
-- **Purpose**: Defines where the data for the report comes from
-- **Options**:
-  - **Search Data Source**: Define a search query whose results will be available to the report script
-  - **Connected Table Data Source**: Pull data from a connected table widget on the same page
-  - **Selection Data Source**: Use manually selected pages
-
-**Search-related sub-attributes**:
-- `SEARCH`: JSON search configuration (optional)
-- `SORT_COLUMN`: Sorting criteria for search results
-- `SORT_ORDER`: Sort direction (ascending/descending)
-
-**Connected Table sub-attributes**:
-- `CONNECTED_TABLE`: Widget ID of the connected table
-- `CONNECTED_TABLE_SELECTION_ONLY`: Boolean flag - if true, only generate report for selected table rows
-
-#### 3.3 Presentation & Labeling
-- **Title** (`TITLE`): Optional custom title for the widget (defaults to "Report {ReportConfigName}")
-- **Button Label** (`BUTTON_LABEL`): Custom text for the generation button (defaults to "Generate Report")
-- **Show Frame** (`SHOW_FRAME`): Boolean to control whether widget displays in a frame (default: true)
-
-#### 3.4 File Naming
-- **File Name** (`FILENAME`): Custom name for the generated file (no spaces allowed)
-- **Fixed Filename** (`IS_FILENAME_FIXED`): When true, no timestamp/UUID is appended to filename
-  - Enables version history for documents
-  - Warning: Overwrites existing files with same name without confirmation
-
-#### 3.5 Output Format
-- **Generate Report as PDF** (`GENERATE_REPORT_AS_PDF`): Convert the Office document to PDF format (default: false)
-
-#### 3.6 Attachment Configuration
-- **Attach to Widget Embedding Page** (`ATTACH_TO_WIDGET_EMBEDDING_PAGE`): Automatically attach the generated report to the page where the widget is embedded (default: false)
-- **Attachment Page Attribute** (`ATTACHMENT_PAGE_ATTRIBUTE`): Specific document attribute on the embedding page to attach the report to
-- **Attachment Type** (`ATTACHMENT_TYPE`): Document type classification for the attached file
-
-#### 3.7 Additional Data Collection
-- **Additional Data Type** (`ADDITIONAL_DATA_TYPE`): Enables a dialog for collecting extra information at generation time
-- **Additional Data Attributes** (`ADDITIONAL_DATA_ATTRIBUTES`): Specific attributes to collect in the dialog
-- **Additional Data Dialog Title** (`ADDITIONAL_DATA_TYPE_DIALOG_TITLE`): Custom title for the data collection dialog
-
-### Configuration Modes
-
-The widget supports three primary data source modes:
-
-1. **Search Mode**: Report script receives search results as `pagesInfo` binding
-2. **Connected Table Mode**: Report script can access table data and selections
-3. **Direct Mode**: Report script works with the embedding page only (`embeddingPage` binding)
-
-### Migration Support
-The widget includes comprehensive migration support (lines 187-247 in GenerateReportWidgetDefinition.java):
-- Automatic attribute name migration when type definitions change
-- Search configuration migration
-- Sort column and additional data attribute migration
-- Data source grouping migration (e.g., "connectedTableWithOptionalSelection" → "ConnectedTableDataSourceAttributeGroup")
-
-## 4. Technical Architecture
-
-### Frontend Components
-
-**TypeScript Controller**: `GenerateReportWidgetCtrl.ts`
-- Manages button click handler
-- Listens for table refresh and selection events
-- Builds handler URL with connected table selection parameters
-- Integrates with AngularJS widget framework
-
-**Key Frontend Behaviors**:
-- Responds to `widgets.tableRefresh` events to update connected table selection context
-- Responds to `AbstractFlexiCtrl.EVENT_ROW_SELECTION_CHANGED` events for table row selections
-- Dynamically builds handler URL with selection parameters
-
-### Backend Components
-
-**Handler**: `GenerateReportHandler.java`
-- Validates access to report configuration
-- Handles additional data collection workflow (if configured)
-- Creates and starts `GenerateReportJob` in a separate thread
-- Returns job status as JSON
-
-**Job Execution**: `GenerateReportJob`
-- Background job for report generation
-- Executes Low-Code script with bindings:
-  - `report`: Report builder object
-  - `embeddingPage`: The page where widget is embedded
-  - `pagesInfo`: Search results (if search configured)
-  - `additionalData`: User-provided additional data (if configured)
-  - `configInfo`: Helper for accessing images/presentations
-  - `log`: Logging helper for user feedback
-- Populates template placeholders
-- Generates final Office document
-- Handles file attachment and download
-
-### Widget State
-
-The widget exposes state information via `GenerateReportWidgetState`:
-- `widgetId`: Unique widget identifier
-- `reportButtonName`: Displayed button label
-- `embeddedIn`: UID of the embedding page
-- `definingWidgetId`: ID of defining widget (if nested)
-- `connectedTableWidgetId`: Connected table reference
-- `hasAdditionalDataType`: Whether additional data collection is enabled
-
-### Access Control
-
-- Widget can be hidden dynamically by implementing `CheckAccessInterceptors.AsPluginExtension` on `GenerateReportHandler`
-- Report configuration accessibility is checked before generation
-- Widget automatically hides if handler URL is empty (e.g., due to access restrictions)
-
-## 5. Related Components
-
-### Sister Widgets in Office Reports Plugin
-
-1. **cf.cplace.officeReports.headlineForReports**
-   - Purpose: Display visual report type indicator on Report Configuration pages
-   - Relationship: Used in Report Configuration page layouts
-
-2. **cf.cplace.officeReports.scriptPlaceholders**
-   - Purpose: Display and manage script-defined placeholders
-   - Relationship: Configuration aid for Report Configuration pages
-
-3. **cf.cplace.officeReports.templatePlaceholders**
-   - Purpose: Display placeholders found in Office templates
-   - Relationship: Configuration aid for Report Configuration pages
-
-### Dependencies
-
-- **Report Configuration Type** (`cf.cplace.officeReports.configuration`): Master configuration entity
-- **Office Templates**: Word, PowerPoint, or Excel files with placeholder markers
-- **Low-Code Scripts**: JavaScript/TypeScript code for data extraction and population
-- **Document Attachment System**: cplace's document management for file storage
-
-### Report Types Supported
-
-From `ReportType` enum:
-- **Word** (DOCX): Text-heavy reports, letters, documentation
-- **PowerPoint** (PPTX): Presentations, visual reports, slide decks
-- **Excel** (XLSX): Data tables, spreadsheets, numerical reports
-
-## 6. Key Insights & Observations
-
-### Design Philosophy
-- **Separation of Concerns**: Widget configuration is separate from Report Configuration, allowing reuse of the same report template with different data sources
-- **Progressive Enhancement**: Basic usage requires minimal configuration; advanced features (additional data, attachments) are opt-in
-- **Async Job Pattern**: Report generation happens in background jobs to avoid blocking the UI for long-running operations
-
-### Flexibility Features
-- Can work with or without a search configuration
-- Supports both bulk generation and selective generation (via table selections)
-- Can generate reports for download or auto-attach them to pages
-- Supports runtime data collection via additional data dialogs
-
-### Common Patterns
-- Widget typically embedded on entity pages (project pages, portfolio pages, etc.)
-- Report Configuration is created once and referenced by multiple widget instances
-- Low-Code scripts use template placeholders to define substitution points
-
-### Limitations & Constraints
-- Can only be embedded in AttributesGroup or ConnectedAttributesGroup widgets
-- Filename must not contain spaces
-- Fixed filenames overwrite without confirmation (when enabled)
-- Report configuration must be accessible to the user
-
-### Version History Support
-The fixed filename feature (line 112-116 in CplaceReportGenerationWidgetTypes.java) enables document version history by preventing automatic timestamp/UUID suffixes. This allows cplace to track versions of repeatedly generated reports with the same name.
-
-## 7. Research Sources
-
-### Primary Sources Analyzed
-1. **GenerateReportWidgetDefinition.java** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/script/GenerateReportWidgetDefinition.java`)
-   - Lines 1-279: Complete widget definition including configuration, substitution, and migration logic
-
-2. **CplaceReportGenerationWidgetTypes.java** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/CplaceReportGenerationWidgetTypes.java`)
-   - Lines 36-236: GENERATE_REPORT_WIDGET configuration type definition with all attributes
-
-3. **GenerateReportHandler.java** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/handler/GenerateReportHandler.java`)
-   - Lines 1-127: Handler logic for report generation requests
-
-4. **GenerateReportWidgetCtrl.ts** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/assets/ts/controllers/GenerateReportWidgetCtrl.ts`)
-   - Lines 1-84: Frontend controller for button interactions and table integration
-
-5. **messages_en.properties** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/build/resources/main/cf/cplace/officeReports/messages_en.properties`)
-   - Lines 1-100: English localization messages including widget names, descriptions, and help text
-
-6. **OfficeReportsAppTypes.java** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/OfficeReportsAppTypes.java`)
-   - Lines 1-150: Report Configuration type definition and related types
-
-### Key Findings from Code Analysis
-
-- **Widget Kind**: `"cf.cplace.cplaceReportGeneration.generateReportWidget"` (line 58 in GenerateReportWidgetDefinition.java)
-- **App Context**: Part of `cplaceReportGenerationApp` within the Office Reports Plugin
-- **Embedding Constraints**: Explicitly restricts embedding to AttributesGroup variants (lines 93-98)
-- **Template System**: Uses `WidgetTemplateSubstitution` pattern for rendering
-- **Access Control**: Leverages `CheckAccessInterceptors` for dynamic visibility
-- **State Management**: Implements `WidgetState` interface for serializable state exposure
-
-## 8. Documentation Strategy Recommendations
-
-### Essential Topics for User Documentation
-1. **Getting Started Guide**: Step-by-step process for creating first report (Report Config → Template Upload → Script → Widget Placement)
-2. **Data Source Configuration**: Detailed explanation of search vs. table vs. selection modes
-3. **Low-Code Script Reference**: Available bindings, common patterns, template placeholder syntax
-4. **Template Guidelines**: How to create templates with placeholders for Word/PowerPoint/Excel
-5. **Attachment Workflows**: Configuring automatic attachment to pages
-
-### Advanced Topics
-1. **Additional Data Collection**: Creating dialogs for runtime user input
-2. **Table Integration**: Working with connected table selections
-3. **Access Control**: Implementing custom visibility logic
-4. **Version History**: Using fixed filenames for versioned documents
-5. **PDF Generation**: Converting Office documents to PDF
-
-### Common Pitfalls to Document
-- Filename restrictions (no spaces)
-- Fixed filename overwrite behavior
-- Access requirements for Report Configuration
-- Embedding limitations (only in attribute groups)
-- Report Configuration page setup requirements