@cplace/test-mcp-server 1.0.0 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/de-visualistik-visualRoadmap-widget/research.md

@@ -0,0 +1,277 @@
+# Visual Roadmap Widget Research
+
+## Widget Information
+- **Widget ID**: `de.visualistik.visualRoadmap.widget`
+- **Widget Name**: Visual Roadmap
+- **Repository**: `cplace-gtv`
+- **Plugin**: `de.visualistik.visualRoadmap`
+
+## 1. Purpose
+
+### Short Description
+The Visual Roadmap widget displays timeline-based data in a customizable roadmap visualization, organizing items into groups and swimlanes with configurable visual properties (colors, hatching patterns, icons).
+
+### Detailed Description
+The Visual Roadmap widget is a sophisticated visualization component that renders hierarchical, time-based data in a roadmap format. It uses a custom web component (`app-entry`) powered by the Visual-Roadmap bundle to create interactive timeline visualizations. The widget transforms cplace page data into structured roadmap elements through a configurable JavaScript script, allowing users to visualize project timelines, releases, milestones, or any time-based data with rich visual customization options.
+
+## 2. Use Cases
+
+### Primary Use Cases
+
+1. **Project Timeline Visualization**
+   - Display project phases, milestones, and deliverables on a timeline
+   - Organize projects into categories and sub-categories (groups and swimlanes)
+   - Visualize start and end dates for different project elements
+
+2. **Release Planning & Roadmapping**
+   - Show product releases and feature rollouts over time
+   - Group features by release cycles or product lines
+   - Categorize items using visual indicators (colors, patterns, icons)
+
+3. **Resource Planning & Capacity Visualization**
+   - Display resource allocation across different projects or teams
+   - Visualize overlapping timelines and dependencies
+   - Track different types of work items with distinct visual styling
+
+4. **Portfolio Management**
+   - Aggregate multiple projects or initiatives into a unified view
+   - Group by business units, departments, or strategic themes
+   - Provide executive-level overview of organizational initiatives
+
+### Example from Test Data
+
+The test data shows a practical example with bikes:
+- **Groups**: Different bike categories (Downhill, Road, All Mountain, Gravel)
+- **Swimlanes**: Series or product lines within each category
+- **Base Items**: Individual bikes with:
+  - Start and end dates
+  - State/status indicators
+  - Visual customization based on category and type
+  - Interactive selection capabilities
+
+## 3. Core Functionality
+
+### Data Processing Flow
+
+1. **Data Source**: Widget pulls pages from cplace based on configured data source (search, connected table, or manual selection)
+
+2. **Script Transformation**: JavaScript script transforms page data into roadmap structure:
+   ```javascript
+   {
+     configuration: {
+       hatchingMap: { /* visual patterns */ },
+       colorMap: { /* color mappings */ },
+       iconMap: { /* icon mappings */ }
+     },
+     groups: [
+       {
+         name: "Group Name",
+         id: "group_id",
+         swimlanes: [
+           {
+             name: "Swimlane Name",
+             baseItemElements: [
+               {
+                 name: "Item Name",
+                 id: "item_id",
+                 startDate: "MM-dd-yyyy",
+                 endDate: "MM-dd-yyyy",
+                 state: "status",
+                 type: "category"
+               }
+             ]
+           }
+         ]
+       }
+     ]
+   }
+   ```
+
+3. **Visual Rendering**: Web component renders the roadmap with configured visual properties
+
+4. **User Interaction**: Users can:
+   - Select items (emits `SelectedSingleEvent`)
+   - Toggle fullscreen mode
+   - Interact with timeline elements
+
+### Integration Points
+
+- **Connected Table Support**: Can be connected to a table widget to filter/refresh data
+- **Event System**:
+  - Listens to `WidgetEvents.TABLE_REFRESH` and `TABLE_DATA_CHANGED`
+  - Emits `SelectedSingleEvent` when items are selected
+- **Dynamic Data Loading**: Loads data via handler endpoint with widget and embedding context
+
+## 4. Configuration Concepts
+
+### 4.1 Data Source Configuration
+
+The widget supports three data source types through the `DATA_SOURCE` attribute grouping:
+
+1. **Search-based**: Define a search query to dynamically find pages
+   - `SEARCH`: Search configuration
+   - `SORT_COLUMN`: Column to sort by
+   - `SORT_ORDER`: Sort direction
+
+2. **Connected Table**: Link to a table widget for synchronized data
+   - `CONNECTED_TABLE`: ID of the connected table widget
+   - Data refreshes when table data changes
+
+3. **Manual Selection**: Explicitly select pages to display
+   - `SELECTION`: Multi-page reference for manual page selection
+
+### 4.2 Visual Customization
+
+The widget supports three types of visual configuration maps:
+
+1. **Color Map**: Map attribute values to specific colors
+   - Can be configured for base items and sub-items
+   - Maps property keys to hex color values
+   - Example: `{"#d0bef5": ["Downhill", "Road"]}`
+
+2. **Hatching Map**: Apply pattern overlays to items
+   - Three patterns available: LIGHT, MID, SOLID
+   - Provides additional visual differentiation
+   - Can distinguish between different states or categories
+
+3. **Icon Map**: Associate Font Awesome icons with items
+   - Maps property values to icon names
+   - Provides semantic meaning through iconography
+   - Example: `{"car-battery": ["Downhill", "Road"]}`
+
+### 4.3 Script Configuration
+
+- **Required Field**: The `SCRIPT` attribute is mandatory
+- **Purpose**: Transforms source pages into roadmap data structure
+- **Capabilities**:
+  - Access to `pages` (search results) and `embeddingPage` (context)
+  - Can use cplace low-code API (Search, Filters)
+  - Must return JSON with `configuration` and `groups`
+  - Flexible data grouping and transformation logic
+
+### 4.4 Display Configuration
+
+- **Title**: Localized string for widget title (optional)
+- **Height**: Fixed height for the widget (optional)
+  - When set, widget renders at specified height
+  - Widget has no padding (`isNoPadding() = true`)
+
+## 5. Technical Architecture
+
+### Backend Components
+
+1. **VisualRoadmapWidgetDefinition** (`VisualRoadmapWidgetDefinition.java:38`)
+   - Main widget definition class
+   - Configures widget type and configuration schema
+   - Handles template substitution and state initialization
+
+2. **VisualRoadmapLoadDataHandler** (`VisualRoadmapLoadDataHandler.java:22`)
+   - Handler for loading widget data
+   - Validates access and retrieves widget configuration
+   - Delegates to `VisualRoadmapWidgetData` for data processing
+
+3. **VisualRoadmapWidgetData** (`VisualRoadmapWidgetData.java:33`)
+   - Executes the configured JavaScript script
+   - Provides bindings: `embeddingPage` and `pages`
+   - Converts script output to JSON
+   - Handles errors and logging
+
+4. **Type Containers**:
+   - `VisualRoadmapWidgetTypeContainer` (`VisualRoadmapWidgetTypeContainer.java:26`): Widget configuration type definition
+   - `VisualRoadmapConfigurationTypeContainer` (`VisualRoadmapConfigurationTypeContainer.java:21`): Separate configuration page type for visual mappings
+
+### Frontend Components
+
+1. **VisualRoadmapWidgetDirective** (`VisualRoadmapWidgetDirective.ts:9`)
+   - Angular directive for widget integration
+   - Initializes the web component with state
+
+2. **VisualRoadmapWidgetCtrl** (`VisualRoadmapWidgetCtrl.ts:9`)
+   - Controller managing widget lifecycle
+   - Handles event communication with cplace platform
+   - Manages connected table synchronization
+   - Emits element selection events
+
+3. **Visual-Roadmap Web Component**
+   - Bundled JavaScript component (`Visual-Roadmap.bundle.js`)
+   - Renders the actual roadmap visualization
+   - Provides `apiUrl` attribute for data loading
+   - Emits `baseItemSelectionEntry` events
+
+### Data Flow
+
+```
+User Configuration
+       ↓
+Widget Definition (configuration type)
+       ↓
+VisualRoadmapLoadDataHandler (on load)
+       ↓
+VisualRoadmapWidgetData (script execution)
+       ↓
+JSON output (configuration + groups)
+       ↓
+Frontend directive/controller
+       ↓
+Visual-Roadmap web component
+       ↓
+Rendered visualization
+```
+
+## 6. Configuration Page Type
+
+The plugin includes a separate page type `de.visualistik.visualRoadmap.visualRoadmapConfiguration` for managing visual configuration mappings:
+
+- **Purpose**: Create reusable configuration mappings that can be referenced in scripts
+- **Attributes**:
+  - `CONFIGURATION_TYPE_MAP`: Choose between hatchingMap, colorMap, or iconMap
+  - `ITEM_TYPE`: Specify baseItem or subItem
+  - `DISPLAYED_VALUE`: The visual value to display (color, pattern, or icon)
+  - `PROPERTY_KEY_VALUES`: List of attribute values that map to the displayed value
+
+This allows administrators to create configuration pages that define visual mappings, which can then be queried and used in widget scripts.
+
+## 7. Related Features
+
+### Prerequisites
+- Pages with date attributes (for timeline visualization)
+- Understanding of JavaScript for script configuration
+- Knowledge of cplace low-code API for data transformation
+
+### Dependencies
+- Visual-Roadmap web component (bundled)
+- cplace widget framework
+- cplace low-code scripting engine
+
+### Integration Capabilities
+- Works with any cplace page type
+- Integrates with table widgets via connected table feature
+- Supports cplace event system for selection synchronization
+- Compatible with fullscreen widget mode
+
+## 8. Key Characteristics
+
+- **Highly Customizable**: Visual appearance controlled through configuration maps
+- **Script-Driven**: Flexible data transformation via JavaScript
+- **Interactive**: Supports item selection and event emission
+- **Hierarchical**: Three-level structure (groups → swimlanes → base items)
+- **Timeline-Based**: Designed for date-based visualizations
+- **Responsive**: Supports fullscreen toggle
+- **Connected**: Can synchronize with table widgets
+
+## 9. Configuration Workflow
+
+1. **Choose Data Source**: Select between search, connected table, or manual selection
+2. **Write Transform Script**: Create JavaScript to transform pages into roadmap structure
+3. **Define Visual Mappings**: Configure colors, patterns, and icons in script
+4. **Set Display Options**: Configure title and height as needed
+5. **Embed in Page**: Add widget to page with appropriate sizing
+
+## 10. Limitations & Considerations
+
+- **Script Complexity**: Requires JavaScript knowledge for complex transformations
+- **Visual Configuration**: All visual mappings must be defined in script (not UI-configurable)
+- **Web Component**: Uses custom web component, not standard cplace rendering
+- **Date Format**: Expects specific date format in output ("MM-dd-yyyy")
+- **Performance**: Script execution happens on each data load
+- **No Pagination**: Loads all matching pages at once

package/dist/widget-specifications/_research_from_ga_products/msg-scripts-imagegallery-basic/research.md

@@ -0,0 +1,112 @@
+# Widget Research: msg.scripts.imagegallery.basic
+
+## Widget Overview
+
+**Widget ID:** `msg.scripts.imagegallery.basic`
+**Display Name:** Document Gallery (EN) / Dokumentengalerie (DE)
+**Repository:** cplace-paw
+**Plugin:** `com.msgsystems.cplace.imagegallery`
+**Definition Class:** `DocumentGalleryWidgetDefinition.java`
+
+## Short Description
+
+The Document Gallery widget displays documents attached to a page (or a referenced page) as an interactive gallery, supporting images, PDFs, ODP presentations, and video files with carousel-style navigation.
+
+## Purpose and Core Functionality
+
+This widget provides a visually appealing way to browse and view documents attached to cplace pages. Rather than displaying documents as a simple list, it presents them in a full-featured gallery/carousel interface powered by the Fotorama library.
+
+### Key Capabilities
+
+1. **Multi-format Document Support**
+   - **Images:** JPG, JPEG, BMP, GIF, TIFF, SVG, PNG
+   - **Documents:** PDF, ODP (OpenDocument Presentation) via ViewerJS
+   - **Videos:** MP4, MOV with HTML5 video player
+
+2. **Interactive Gallery Experience**
+   - Carousel/slider navigation between documents
+   - Optional thumbnail navigation
+   - Responsive width (100% container width)
+   - Configurable height and aspect ratio
+
+3. **Source Flexibility**
+   - Displays documents from the current page (default)
+   - Can reference documents from a different page via configuration
+
+## Use Cases
+
+### 1. Project Photo Documentation
+When a project page has multiple photos documenting progress, milestones, or deliverables, this widget allows stakeholders to browse through all images in a polished gallery format rather than viewing them individually.
+
+### 2. Product/Asset Image Showcase
+For pages representing products, assets, or inventory items that have multiple associated images, this widget enables users to see all product views in an engaging slideshow format.
+
+### 3. Presentation Viewing
+When ODP or PDF presentations are attached to a page, users can view them directly within the widget without downloading, making it easy to share slide decks or reports.
+
+### 4. Video Collection Display
+For pages with attached video content (MP4, MOV), the widget provides an integrated video player experience, useful for training materials, recorded meetings, or media assets.
+
+### 5. Document Hub Pages
+A page can be configured to display documents from another page (via the BASEPAGE configuration), allowing creation of document "hub" views that aggregate content from different sources.
+
+## Configuration Options
+
+| Configuration | Type | Description |
+|---------------|------|-------------|
+| **Title** | Localized String | Custom widget title (default: "Document Gallery") |
+| **Page** (basePage) | Page Reference | Source page for documents; if not set, uses the current page |
+| **Height** | Number | Height of the document display in pixels (default: 600px) |
+| **Ratio** | String | Aspect ratio (e.g., "4/3") - overrides height if specified |
+| **Show Navigation** | Enum | Controls thumbnail navigation: "When required" (default) or "Never" |
+| **Show Widget Frame** | Boolean | Whether to display the widget frame/border (default: true) |
+
+### Navigation Behavior
+
+- **"When required"**: Shows thumbnail navigation strip when there are multiple documents
+- **"Never"**: Hides navigation completely (documents still navigable via click/swipe)
+
+## Technical Implementation Details
+
+### Third-Party Libraries
+
+1. **Fotorama 4.6.3** - jQuery gallery plugin providing the carousel/slider functionality
+2. **ViewerJS** - JavaScript library for rendering PDF and ODP files in-browser without plugins
+
+### Document Filtering
+
+The widget automatically filters documents attached to the source page, including only those with viewable file extensions. Documents are sorted alphabetically by name.
+
+### Rendering Approach
+
+- Images are rendered as standard `<img>` elements
+- PDFs/ODP files are rendered in an iframe using ViewerJS
+- Videos are rendered with HTML5 `<video>` elements with native controls
+
+## Related Widgets and Alternatives
+
+The cplace-paw repository contains several widgets that deal with documents and media:
+
+- **cf.cplace.pdfPreview** - Specialized for PDF preview
+- **cf.cplace.dragAndDropImageView** - Image-focused with drag-and-drop positioning
+
+The Document Gallery widget is more comprehensive, handling multiple media types in a unified gallery experience.
+
+## Dependencies
+
+- **cf.cplace.platform** - Core cplace platform (only dependency)
+- No dependencies on other paw plugins
+
+## Migration Notes
+
+The widget includes migration support for:
+- Converting legacy non-localized `TITLE` attribute to the newer `LOCALIZED_TITLE` format
+- Setting default value for `SHOW_NAV` on older configurations
+
+## Summary for Documentation
+
+**One-sentence description:**
+Displays page documents (images, PDFs, presentations, and videos) in an interactive carousel gallery with configurable navigation and sizing options.
+
+**Conceptual summary:**
+The Document Gallery widget transforms document attachments into a visual browsing experience. It automatically collects all viewable documents from a page, organizes them into a slideshow format, and provides intuitive navigation through thumbnails or direct clicking. The widget handles multiple media types seamlessly - images display directly, PDFs and presentations render via an embedded viewer, and videos play with native HTML5 controls. Configuration options allow customization of the display size, aspect ratio, and navigation behavior to fit different page layouts and use cases.

package/dist/widget-specifications/_research_from_ga_products/phase-0-discovery-approach.md

@@ -0,0 +1,248 @@
+# Phase 0: Discovery Approach - Lessons Learned
+
+**Date:** 2026-01-16
+**Objective:** Find widget definition classes for 97 target widgets
+
+---
+
+## Strategies That Worked
+
+### 1. Glob Search for `*WidgetDefinition.java` Files
+
+**Approach:** Search all repositories for files matching `*WidgetDefinition.java` and `*WidgetDefinition.kt` patterns.
+
+**Why it worked:**
+- Widget definitions follow a consistent naming convention across the codebase
+- The pattern is highly specific - very few false positives
+- Found 126 widget definition files across 21 repositories in a single pass
+
+**Example:**
+```
+Glob pattern: **/*WidgetDefinition.java
+Result: 126 files found
+```
+
+### 2. Reading the `KIND` Constant or `getWidgetKind()` Method
+
+**Approach:** After finding definition files, read each to extract the widget ID from the `KIND` constant or `getWidgetKind()` return value.
+
+**Why it worked:**
+- Every widget definition has a `getWidgetKind()` method (required by the interface)
+- Most classes define a `public static final String KIND = "..."` constant
+- The widget ID is always a string literal or constructed from known constants
+
+**Pattern observed:**
+```java
+public static final String KIND = "cf.cplace.cboard.main.board";
+
+@Override
+public String getWidgetKind() {
+    return KIND;
+}
+```
+
+### 3. Tracing Constant References
+
+**Approach:** When `KIND` references another constant (e.g., `TYPE_PREFIX + ".widget"`), follow the reference to its source.
+
+**Why it worked:**
+- Constants are typically defined in Plugin classes or dedicated Types classes
+- Following the reference chain always leads to the actual string value
+
+**Example:**
+```java
+// In CurvesWidgetDefinition.java
+public static final String KIND = PREFIX + "widget";
+
+// In CurvesPlugin.java
+public static final String PREFIX = "de.2lforge.curves.";
+
+// Result: "de.2lforge.curves.widget"
+```
+
+### 4. Repository Discovery via Search
+
+**Approach:** When widgets weren't found in the initial repository list, search for widget ID strings to discover additional repositories.
+
+**Why it worked:**
+- Widget IDs are unique strings that appear in the defining class
+- Searching for `"cf.platform.attributes"` led to discovering the `main` repository
+
+**Key discovery:** The `main` repository at `/Users/thomasbuechner/dev/repos/main/cf.cplace.platform` contained 24 platform widgets and wasn't in the initial working directory list.
+
+---
+
+## Strategies That Did NOT Work Well
+
+### 1. Assuming Widget ID Matches Class Name
+
+**Attempted approach:** Derive widget ID from class name (e.g., `BoardWidgetDefinition` → `board`).
+
+**Why it failed:**
+- Widget IDs don't follow class naming conventions
+- `RichStringWithoutFrameWidgetDefinition` → `cf.cplace.demoWidgets.demoRichString` (no correlation)
+- `DocumentGalleryWidgetDefinition` → `msg.scripts.imagegallery.basic` (completely different)
+
+**Lesson:** Always read the actual `KIND` constant.
+
+### 2. Assuming Widget ID Matches Package Structure
+
+**Attempted approach:** Derive widget ID from Java package (e.g., `cf.cplace.board.main` → `cf.cplace.board.main.*`).
+
+**Why it failed:**
+- Package structure and widget IDs are independent
+- Package: `com.msgsystems.cplace.imagegallery` → Widget ID: `msg.scripts.imagegallery.basic`
+- Package: `cf.cplace.dragAndDropImageView.widget` → Widget ID: `cf.cplace.dragAndDropImageView.widget` (coincidental match)
+
+**Lesson:** Package names are hints, not reliable mappings.
+
+### 3. Searching Only in Working Directories
+
+**Attempted approach:** Limit search to the 40 repositories listed in the working directories.
+
+**Why it failed:**
+- The `main` repository (containing core platform widgets) wasn't in the list
+- 24 widgets (25% of total) would have been missed
+
+**Lesson:** Be prepared to discover additional repositories during the search.
+
+### 4. Assuming Widget Repository Matches Widget ID Prefix
+
+**Attempted approach:** Look for `cf.platform.*` widgets in a `cplace-platform` repository.
+
+**Why it failed:**
+- `cf.platform.*` widgets are in `main/cf.cplace.platform`, not `cplace-platform`
+- `cf.cplace.visualizations.*` widgets are in `cplace-paw`, not `cplace-visualizations`
+
+**Lesson:** Widget ID prefixes don't map to repository names.
+
+---
+
+## Challenges Encountered
+
+### 1. Indirect Widget ID Construction
+
+Some widgets construct their ID from multiple constants:
+
+```java
+// ChatWidgetDefinition.java in cplace-citizen-ai
+public static final String KIND = CitizenAiPlugin.TYPE_PREFIX_BEFORE_PLUGIN_NAME_UPDATE + ".chatWidget";
+
+// CitizenAiPlugin.java
+public static final String TYPE_PREFIX_BEFORE_PLUGIN_NAME_UPDATE = "cf.cplace.lowcode.ai";
+
+// Result: "cf.cplace.lowcode.ai.chatWidget"
+```
+
+**Solution:** Follow all constant references to their string literal definitions.
+
+### 2. Multiple Repositories with Similar Widgets
+
+The `chatWidget` existed in two places:
+- `cplace-citizen-ai`: `cf.cplace.lowcode.ai.chatWidget` (via backward-compat constant)
+- `cplace-lowcode-ai`: `cf.cplace.lowcode.ai.chatWidget`
+
+**Solution:** Verified which repository is authoritative by checking the constant definitions.
+
+### 3. Widget IDs with Unusual Prefixes
+
+Some widget IDs don't follow the `cf.cplace.*` or `cf.platform.*` pattern:
+- `msg.scripts.imagegallery.basic`
+- `de.2lforge.curves.widget`
+- `de.visualistik.visualRoadmap.widget`
+- `com.dataciders.portfolio.connectedPortfolioWidget`
+
+**Solution:** The glob search for `*WidgetDefinition.java` found these regardless of their ID prefix.
+
+### 4. Deprecated vs Active Widgets
+
+Some widgets reference deprecated constants or have migration paths:
+
+```java
+/**
+ * @deprecated use {@link SubscriptionsWidgetDefinitionConstants.WIDGET_TYPE_SUBSCRIPTIONS}
+ */
+public static final String WIDGET_TYPE_SUBSCRIPTIONS = SubscriptionsWidgetDefinitionConstants.WIDGET_TYPE_SUBSCRIPTIONS;
+```
+
+**Solution:** Follow to the non-deprecated constant to get the canonical widget ID.
+
+---
+
+## Recommended Approach for Future Discovery
+
+1. **Start with glob search** for `*WidgetDefinition.java` across all accessible repositories
+2. **Extract widget IDs** by reading the `KIND` constant from each file
+3. **Trace constant references** when IDs are constructed from other constants
+4. **Cross-reference** found widgets against the target list to identify gaps
+5. **Search for missing widget IDs** as string literals to discover additional repositories
+6. **Document repository locations** for widgets to enable efficient Phase 1 research
+
+---
+
+## Statistics
+
+| Metric | Value |
+|--------|-------|
+| Initial repositories searched | 40 |
+| Additional repositories discovered | 1 (main) |
+| Total widget definition files found | 126 |
+| Target widgets mapped | 97/97 (100%) |
+| Widgets with indirect ID construction | ~15 |
+| Widgets with non-standard prefixes | 5 |
+
+---
+
+## Phase 1 Research Generation Workflow
+
+The discovery output feeds directly into the automated research generation workflow.
+
+### Directory Structure
+
+```
+specs/2026-01-16/widget-research-generation/
+├── generate.sh          # Main execution script
+├── template.md          # Prompt template with placeholders
+├── widgets.txt          # Tab-separated widget data (97 entries)
+└── parse-mapping.sh     # Script to parse mapping file into widgets.txt
+```
+
+### Input File: `widgets.txt`
+
+Tab-separated file with columns:
+1. `widget_id` - The widget identifier (e.g., `cf.cplace.cboard.main.board`)
+2. `repository` - Repository name (e.g., `cplace-board`)
+3. `definition_class_path` - Path to definition class within the repository
+
+Example:
+```
+cf.cplace.cboard.main.board	cplace-board	cf.cplace.cboard.main/src/main/java/cf/cplace/cboard/main/script/BoardWidgetDefinition.java
+```
+
+### Template: `template.md`
+
+Uses the `/spec-driven-development:research_codebase` command with placeholders:
+- `{{WIDGET_ID}}` - Widget identifier
+- `{{REPOSITORY}}` - Repository name
+- `{{DEFINITION_CLASS_PATH}}` - Path to definition class
+
+### Execution
+
+```bash
+cd specs/2026-01-16/widget-research-generation
+./generate.sh
+```
+
+Options:
+- `PARALLEL=8 ./generate.sh` - Run with 8 concurrent processes (default: 4)
+- Skips widgets that already have `research.md` files
+- Creates output in `specs/2026-01-16/{widget-folder}/research.md`
+
+### Output
+
+For each widget, creates:
+```
+specs/2026-01-16/{widget-id-with-dashes}/research.md
+```
+
+Example: `cf.cplace.cboard.main.board` → `specs/2026-01-16/cf-cplace-cboard-main-board/research.md`