@cplace/mcp-server 1.6.0 → 1.6.2

package/dist/plugins/core-app-catalog/cf.cplace.buildingBlockSchedule/README.md

@@ -0,0 +1,181 @@
+# Building Blocks (cf.cplace.buildingBlockSchedule)
+
+## Overview
+
+The Building Blocks app extends the Project Planning apps by introducing the concept of reusable schedule templates called "Building Blocks." It allows users to mark schedules as building blocks, which can then be inserted into other schedules as pre-configured templates.
+
+**Key Capabilities:**
+- Mark any Schedule as a Building Block via a checkbox attribute
+- Insert Building Block content into other schedules
+- Reuse common project patterns across multiple schedules
+- Standardize project structures with predefined task and milestone templates
+
+## Dependencies
+
+| App | Qualified Name | Auto-Installed |
+|-----|----------------|----------------|
+| cplace Basis | `cf.cplace.platform` | Yes (platform base) |
+| Project Planning (Basic) | `cf.cplace.projektplanung.projektplanungBasic` | Yes |
+| Project Planning (Extended) | `cf.cplace.projektplanung.projektplanungExtended` | Yes |
+
+**Note:** Installing Building Blocks automatically installs both Project Planning (Basic) and (Extended) apps, giving you full Gantt chart functionality including subscriptions and delegations.
+
+## Types Provided
+
+The Building Blocks app does not introduce new types. Instead, it **extends** the existing `cf.schedule` type (from Project Planning Basic) with a single attribute that enables the Building Block functionality.
+
+### Type Extensions
+
+#### cf.schedule (Schedule)
+**Extended Attribute:**
+
+| Attribute | Internal Name | Type | Required | Description |
+|-----------|---------------|------|----------|-------------|
+| Building Block | `cf.cplace.isBuildingBlock` | Boolean | Yes (default: false) | Activate this checkbox to define the schedule as a building block, so its content can be inserted into other schedules |
+
+## Types Available After Installation
+
+When Building Blocks is installed, the following types become available (provided by dependencies):
+
+### cf.schedule (Schedule)
+
+The top-level container for project planning elements. Schedules contain tasks and milestones and define overall project timeline boundaries.
+
+| Attribute | Internal Name | Type | Description |
+|-----------|---------------|------|-------------|
+| Start | `startDate` | Date | Schedule start date (morning of the specified day) |
+| Finish | `endDate` | Date | Schedule finish date (evening of the specified day) |
+| Duration | `duration` | Number | Calculated duration |
+| Duration Unit | `durationUnit` | Enumeration | Unit for duration (days, weeks, etc.) |
+| % Completed | `percentComplete` | Number | Completion percentage (0-100) |
+| RAG Rating | `ratingLight` | Enumeration | Traffic light status indicator |
+| Note | `note` | Rich String | Additional notes |
+| Target Start | `baselineStartDate` | Date | Baseline start date for tracking |
+| Target Finish | `baselineEndDate` | Date | Baseline finish date for tracking |
+| Task Class | `activityClass` | Reference | Visual styling category |
+| Parent Project | `parentProject` | Reference | Hierarchical project structure |
+| Building Block | `cf.cplace.isBuildingBlock` | Boolean | **Building Blocks extension** |
+| Backwards scheduling | `scheduleBackwards` | Boolean | Forward vs. backward scheduling mode |
+| Allow Subscribing | `allowSubscription` | Boolean | Enable task subscription feature |
+| Allow Delegating | `allowDelegation` | Boolean | Enable task delegation feature |
+
+### cf.activity (Task)
+
+Work items with duration within a schedule. Tasks can be nested to create hierarchies (summary tasks).
+
+| Attribute | Internal Name | Type | Description |
+|-----------|---------------|------|-------------|
+| Parent object | `parent` | Reference | Parent schedule or summary task |
+| Schedule | `containingSchedule` | Reference | Containing schedule (computed) |
+| Start | `startDate` | Date | Task start date |
+| Finish | `endDate` | Date | Task finish date |
+| Duration | `duration` | Number | Task duration |
+| % Completed | `percentComplete` | Number | Completion percentage |
+| RAG Rating | `ratingLight` | Enumeration | Traffic light status |
+| Automatically scheduled | `automaticScheduling` | Boolean | Auto-reschedule on predecessor changes |
+| Note | `note` | Rich String | Additional notes |
+| Target Start | `baselineStartDate` | Date | Baseline start date |
+| Target Finish | `baselineEndDate` | Date | Baseline finish date |
+| Task Class | `activityClass` | Reference | Visual styling category |
+| Delegated from | `delegationSource` | Reference | Source of delegated task |
+| Rollup | `rollup` | Boolean | Display in parent row |
+| Must Start | `mustStartOnDate` | Boolean | Fixed start constraint |
+| Must End | `mustFinishOnDate` | Boolean | Fixed end constraint |
+| Startline | `startlineDate` | Date | "No earlier than" constraint |
+| Deadline | `deadlineDate` | Date | "No later than" constraint |
+
+### cf.milestone (Milestone)
+
+Zero-duration events marking key project dates.
+
+| Attribute | Internal Name | Type | Description |
+|-----------|---------------|------|-------------|
+| Parent object | `parent` | Reference | Parent schedule or task |
+| Schedule | `containingSchedule` | Reference | Containing schedule (computed) |
+| Date | `date` | Date | Milestone date (evening of specified day) |
+| % Completed | `percentComplete` | Number | Completion percentage (0 or 100) |
+| RAG Rating | `ratingLight` | Enumeration | Traffic light status |
+| Automatically scheduled | `automaticScheduling` | Boolean | Auto-reschedule on predecessor changes |
+| Note | `note` | Rich String | Additional notes |
+| Target Start | `baselineStartDate` | Date | Baseline date |
+| Task Class | `activityClass` | Reference | Visual styling category |
+| Delegated from | `delegationSource` | Reference | Source of delegated milestone |
+| Rollup | `rollup` | Boolean | Display in parent row |
+| Must Start | `mustStartOnDate` | Boolean | Fixed start constraint |
+| Must End | `mustFinishOnDate` | Boolean | Fixed end constraint |
+
+## Widgets Available After Installation
+
+The following widgets become available from the Project Planning dependencies:
+
+| Widget | Widget Kind | Required App | Description |
+|--------|-------------|--------------|-------------|
+| Gantt chart | `cf.projektplanung.singleGantt` | Basic | Single schedule Gantt visualization |
+| Multi Gantt Chart | `cf.projektplanung.multiGantt` | Basic | Multiple schedules in one view |
+| Open Gantt Chart | `cf.projektplanung.singleGanttLink` | Basic | Button to open Gantt in new tab |
+| Structured Table for Schedules | `cf.projektplanung.scheduleTreeTable` | Basic | Tree-table view of tasks/milestones |
+| Schedule Edit State | `cf.cplace.projektplanung.scheduleLockState` | Basic | Shows who is editing the schedule |
+| Subscriptions | `cf.cplace.projektplanung.subscriptions` | Extended | Cross-schedule subscription table |
+
+**Note:** The Building Blocks app itself does not provide any widgets. The Building Block insertion functionality is integrated into the existing Gantt chart widgets.
+
+## Use Cases
+
+### Creating Reusable Project Templates
+Define common project patterns (e.g., "Software Release Process", "Marketing Campaign", "Product Launch") as Building Block schedules. Project managers can then insert these templates into their schedules to quickly set up standardized structures.
+
+### Standardizing Project Phases
+Create Building Blocks for specific project phases (Planning, Development, Testing, Deployment). Teams can compose their schedules from these standardized phase templates.
+
+### Organizational Best Practices
+Encode organizational best practices as Building Blocks. Ensures compliance with standard processes across all projects.
+
+### Onboarding Templates
+Create Building Blocks for common onboarding activities (Employee Onboarding, Customer Onboarding, Vendor Onboarding) that can be quickly inserted and adapted.
+
+## Design Patterns
+
+### Building Block Structure
+1. Create a Schedule with the complete task/milestone structure you want to reuse
+2. Check the "Building Block" checkbox (`cf.cplace.isBuildingBlock = true`)
+3. The schedule now appears as an option when inserting Building Blocks into other schedules
+
+### Composition Pattern
+- **Atomic Building Blocks**: Small, focused templates (3-10 tasks) for specific activities
+- **Composite Building Blocks**: Larger templates composed of multiple activity groups
+- **Skeleton Building Blocks**: High-level structure with placeholders for team customization
+
+### Best Practices
+- Keep Building Block names descriptive and consistent
+- Document assumptions in the Schedule's note field
+- Set reasonable default durations (can be adjusted after insertion)
+- Use Task Classes for visual consistency
+
+## When to Use Building Blocks
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Frequently repeated project patterns | **Use Building Blocks** |
+| One-off unique project structures | Standard schedule creation |
+| Organization-wide standardization | Building Blocks + governance |
+| Ad-hoc task creation | Direct Gantt editing |
+
+## Related Apps
+
+| App | Qualified Name | Relationship |
+|-----|----------------|--------------|
+| Task Classes | `cf.cplace.projektplanungMasterData` | Visual styling for tasks/milestones |
+| Project Structure | `cf.cplace.projectTree` | Hierarchical project organization |
+| New Gantt | `cf.cplace.projectPlanning.app.gantt2.gantt2` | Modern Gantt widget (Bryntum-based) |
+| Presentation Graphic | `cf.cplace.pptexport` | PowerPoint export of schedules |
+
+## Investigation Metadata
+
+| Property | Value |
+|----------|-------|
+| Investigation Date | 2026-02-02 |
+| Investigation Workspace | `h07n4sg4y6jfy8r1nsu1jgxqb` |
+| Apps After Install | 4 (platform + Basic + Extended + Building Blocks) |
+| New Types | 3 (Schedule, Task, Milestone - from dependencies) |
+| Type Extensions | 1 (cf.cplace.isBuildingBlock on Schedule) |
+| New Widgets | 6 (from Project Planning dependencies) |

package/dist/plugins/core-app-catalog/cf.cplace.cboard.main/README.md

@@ -0,0 +1,148 @@
+# Board (cf.cplace.cboard.main)
+
+## Overview
+
+The Board app provides a highly configurable Kanban-style board widget for visualizing and managing pages as cards across columns and swimlanes. It enables different agile working methods through drag-and-drop interactions that update attribute values in real-time.
+
+**Key Capabilities:**
+- Display any page type as cards on a board
+- Organize cards into columns (based on enumeration or date attributes)
+- Optionally group cards into swimlanes (second dimension)
+- Drag-and-drop to move cards between columns/swimlanes (updates the underlying attribute)
+- Rich card display with titles, descriptions, assignees, dates, tags, and icons
+- Real-time synchronization across multiple users
+
+## Dependencies
+
+| App | Qualified Name | Auto-Installed |
+|-----|----------------|----------------|
+| cplace Basis | `cf.cplace.platform` | Yes (platform base) |
+
+**Note:** The Board app has no additional dependencies beyond the platform base.
+
+## Types Provided
+
+**None.** The Board app does not introduce any new types. It is a pure widget app that works with existing types in your workspace.
+
+## Widgets Provided
+
+| Widget | Widget Kind | Description |
+|--------|-------------|-------------|
+| Board | `cf.cplace.cboard.main.board` | Configurable Kanban board for visualizing pages as cards |
+
+### Board Widget Details
+
+The Board widget is the sole feature of this app. It transforms structured cplace data into an interactive visual board.
+
+#### Widget Attributes
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `cf.cplace.cboard.title` | Localized String | No | Board title displayed in the widget header |
+| `cf.cplace.cboard.searchConfigurations` | JSON (multiple) | Yes | Card source configurations (search queries defining which pages appear) |
+| `cf.cplace.cboard.columnMapping` | JSON | Yes | Column definitions and attribute mappings |
+| `cf.cplace.cboard.swimlaneMapping` | JSON | No | Swimlane definitions and attribute mappings |
+| `cf.cplace.cboard.visualComponents` | JSON | No | Visual settings (card appearance, colors, icons) |
+| `cf.cplace.cboard.height` | Number | No | Widget height in pixels |
+
+#### Configuration Tools
+
+The MCP server provides specialized tools for configuring board widgets:
+
+| Tool | Purpose |
+|------|---------|
+| `cplace_board_get_configuration` | Get current configuration in a friendly format |
+| `cplace_board_configure_cards` | Configure card sources (search queries) |
+| `cplace_board_configure_columns` | Configure columns (static or dynamic) |
+| `cplace_board_configure_swimlanes` | Configure swimlanes (or disable) |
+| `cplace_board_configure_visual` | Configure UI settings |
+
+#### Minimal Initial Configuration
+
+When adding a board widget via `cplace_define_layout` / `layout.define()`, use this minimal configuration:
+
+```json
+{
+  "cf.cplace.cboard.searchConfigurations": ["{}"],
+  "cf.cplace.cboard.columnMapping": "{}"
+}
+```
+
+Then use the specialized configuration tools to set up the board properly.
+
+## Use Cases
+
+### Kanban Workflow Management
+Map work items through workflow stages (Backlog, In Progress, Review, Done). Status attribute maps to columns. Drag cards to update status instantly.
+
+### Sprint Planning
+Organize stories across sprints with sprint as swimlanes and status as columns. Visualize work distribution per sprint.
+
+### Project Portfolio View
+Track projects through phases with phase as columns and department as swimlanes. Executive-level overview of project states.
+
+### Order/Request Tracking
+Monitor orders through fulfillment stages. Order status as columns, priority or customer as swimlanes.
+
+### Time-Based Planning
+Use dynamic date-based columns (weeks, months, quarters) for event planning or release scheduling.
+
+## Design Patterns
+
+### Column Types
+
+1. **Static Columns**: Predefined columns with explicit labels and order
+   - Best for: Fixed workflow stages, known status values
+
+2. **Dynamic Columns**: Auto-generated from attribute values
+   - Best for: Data-driven boards where values may change
+
+3. **Date-Based Dynamic**: Columns representing time periods
+   - Best for: Timeline views, release planning, event scheduling
+
+### Board Structures
+
+- **Flat Board** (columns only): Simple workflows, single categorization
+- **Two-Dimensional** (columns + swimlanes): Cross-categorization (e.g., status x priority)
+
+### Common Combinations
+
+- **Board + Table**: Visual workflow alongside detailed data analysis
+- **Board + Charts**: Individual items + aggregated metrics (e.g., burndown)
+- **Master-Detail**: Click card to show details in connected widget
+
+## When to Use Board vs. Alternatives
+
+| Scenario | Best Widget |
+|----------|-------------|
+| Visualize workflow stages | **Board** |
+| Enable drag-and-drop status updates | **Board** |
+| Detailed data analysis with sorting/filtering | Table |
+| Hierarchical parent-child structures | Tree |
+| Quantitative metrics and trends | Charts |
+| Complex search and bulk operations | Search/Table |
+
+## Usage Notes
+
+1. **No Types Required**: The Board app works with any existing types - it displays pages matching your search queries as cards.
+
+2. **Attribute Requirements**: For columns/swimlanes to work, the underlying pages need:
+   - An enumeration attribute (for static/dynamic columns)
+   - Or a date attribute (for date-based columns)
+   - Drag-and-drop updates the mapped attribute value
+
+3. **Performance**: Configure card limits to prevent performance issues with large datasets.
+
+4. **Real-Time Sync**: Multiple users see updates automatically through polling.
+
+5. **Unmapped Cards**: Cards that don't match any column/swimlane appear in an optional sidebar.
+
+## Investigation Metadata
+
+| Property | Value |
+|----------|-------|
+| Investigation Date | 2026-02-02 |
+| Investigation Workspace | `gzatw4vf7lvh37bo581gimk9y` |
+| Apps After Install | 2 (platform + Board) |
+| New Types | 0 |
+| New Widgets | 1 |

package/dist/plugins/core-app-catalog/cf.cplace.ctts.main/README.md

@@ -0,0 +1,106 @@
+# Timebooking (cf.cplace.ctts.main)
+
+## Overview
+
+The Timebooking app provides a comprehensive Collaborative Time Tracking System (CTTS) for employees to enter, track, and manage work hours across projects and activities. It offers interactive time booking interfaces with calendar and grid views, along with reporting widgets for both employees and project managers.
+
+**Key Capabilities:**
+- Interactive time entry with multiple formats (hours:minutes, decimal)
+- Daily, weekly, and monthly booking views
+- Calendar integration with holiday/non-working day support
+- Time validation and approval workflows (month locking/release)
+- Representative mode for booking time on behalf of others
+- Employee and project manager reporting perspectives
+
+## Dependencies
+
+| App | Qualified Name | Notes |
+|-----|----------------|-------|
+| cplace Basis | `cf.cplace.platform` | Base platform (always present) |
+
+No additional dependencies are auto-installed with this app.
+
+## Types Provided
+
+**None.** This is a widget-only app that provides time tracking functionality through widgets. Time booking data is managed internally by the app's infrastructure rather than through standard cplace types.
+
+## Widgets Provided
+
+| Widget | Widget Kind | Description | Use Case |
+|--------|-------------|-------------|----------|
+| **CTTS Timebooking** | `cf.cplace.ctts.main.widget` | Interactive time booking grid for entering work hours | Primary data entry interface for employees to record daily time allocations across multiple projects |
+| **Employee Report Grid** | `cf.cplace.ctts.main.employeeReportGrid` | Tabular view of time bookings for an employee | Review aggregated time entries across all booking targets with monthly breakdown |
+| **Employee Report Chart** | `cf.cplace.ctts.main.employeeReportChart` | Chart visualization of employee time data | Analyze time distribution patterns and trends visually |
+| **Project Leader Report Grid** | `cf.cplace.ctts.main.projectmanagerReportGrid` | Tabular view showing which employees worked on which projects | Project managers monitor resource allocation and verify time entries |
+| **Project Leader Report Chart** | `cf.cplace.ctts.main.projectmanagerReportChart` | Chart visualization of project time data | Visual analysis of time distribution across managed projects |
+
+### Widget Details
+
+#### CTTS Timebooking (`cf.cplace.ctts.main.widget`)
+
+The primary time entry interface with features including:
+- **Time Formats:** Hours/minutes (8:30) or decimal (8.5/8,5)
+- **Time Increments:** Configurable (1 second, 1 minute, 15/30 minutes, 1 hour)
+- **Views:** Daily, weekly, or monthly booking modes
+- **Validation:** Maximum daily hours, overbooking limits, negative bookings support
+- **Workflows:** Month locking/release for approval cycles
+- **Favorites:** Quick access to frequently used booking targets
+- **Subsequent Booking:** Retroactive time entry within configured limits
+
+#### Report Widgets
+
+Two perspectives with two visualization modes each:
+
+| Perspective | Grid Widget | Chart Widget |
+|-------------|-------------|--------------|
+| Employee | Shows personal time across all targets | Stacked bar chart of personal time trends |
+| Project Manager | Shows team time per project | Stacked bar chart of project time trends |
+
+All report widgets support:
+- Date range selection (start/end year and month)
+- Representative mode for viewing others' data (with permissions)
+- Export functionality (when templates configured)
+
+## Usage Notes
+
+### When to Use This App
+
+- Employee time tracking against projects/activities
+- Time-based billing and invoicing requirements
+- Resource utilization monitoring
+- Approval workflows for time submissions
+- Multi-project time allocation analysis
+
+### Configuration Requirements
+
+The app uses app-level configuration for:
+- **ALLOWED_GROUPS:** Controls which users can access time tracking features
+- **Workspace filtering:** Option to restrict booking targets to current workspace
+- **Subsequent booking limits:** Maximum retroactive booking period
+- **Validation rules:** Daily limits, overbooking tolerances
+
+### Integration Patterns
+
+- Time booking data entered via the main widget flows to all report widgets
+- Report widgets share common data retrieval architecture
+- Representative mode uses separate contexts for employee vs. project manager views
+
+### Permissions
+
+Access is controlled through group membership configured at the app level. Users not in allowed groups will see "You cannot make time bookings" or "View not allowed" messages.
+
+### Common Pitfalls
+
+1. **Permission Setup:** Users must be assigned to configured allowed groups
+2. **Month Locking:** Released months cannot be edited without revoking release
+3. **Workspace Filtering:** Targets in other workspaces may be hidden if filtering is enabled
+4. **Time Format Mismatch:** Users may confuse hours:minutes and decimal formats
+
+## Investigation Details
+
+- **Investigation Date:** 2026-02-02
+- **Workspace ID:** 534p2pii8j8adcqflckmrb472
+- **Pre-installation Apps:** cf.cplace.platform only
+- **Post-installation Apps:** cf.cplace.platform, cf.cplace.ctts.main
+- **Types Added:** None (widget-only app)
+- **Widgets Added:** 5 time tracking widgets

package/dist/plugins/core-app-catalog/cf.cplace.draggablePageList/README.md

@@ -0,0 +1,121 @@
+# Drag and Drop List (cf.cplace.draggablePageList)
+
+## Overview
+
+The Drag and Drop List app provides a widget that displays pages in a sortable list where users can change the order using drag and drop. Instead of manually entering numeric priority values, users can simply drag items into the desired order, and the widget automatically persists the changes to a configurable numeric attribute.
+
+The widget supports separating sorted entries from unsorted ones in single or dual list layouts, making it ideal for backlog management, priority queues, and any workflow requiring visual ordering of items.
+
+## Dependencies
+
+- **cf.cplace.platform** (cplace Basis) - Base platform, always installed
+
+No additional app dependencies are auto-installed.
+
+## Types Provided
+
+**None** - This app provides only a widget; it does not introduce any new types.
+
+## Widgets Provided
+
+| Widget | Widget Kind | Description |
+|--------|-------------|-------------|
+| Drag and Drop Prioritization | `cf.cplace.draggablePageList.widget` | Displays pages in a sortable list with drag-and-drop reordering |
+
+### Widget: Drag and Drop Prioritization
+
+**Purpose:** Displays pages from a search query in a sortable list where users can change the order using drag and drop. The order is persisted in a configurable numeric attribute.
+
+**Operating Modes:**
+- **Single List Mode:** Shows only sorted entries (all items have an order value)
+- **Vertical Dual List Mode:** Sorted entries on top, unsorted entries below
+- **Horizontal Dual List Mode:** Sorted and unsorted entries side-by-side (backlog vs prioritized)
+
+**Key Configuration Attributes:**
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `search` | Search | Yes | Search query returning pages to display (must return single type) |
+| `cf.cplace.draggablePageListWidget.orderAttribute` | Dynamic Enumeration | Yes | Numeric attribute to store order/priority values |
+| `cf.cplace.draggablePageListWidget.showUnsortedEntries` | Boolean | Yes | Whether to show unsorted entries |
+| `cf.cplace.draggablePageListWidget.showUnstortedEntriesHorizontally` | Boolean | Yes | Whether to show unsorted entries in a second column |
+| `cf.cplace.draggablePageList.title` | Localized String | No | Widget title |
+| `cf.cplace.draggablePageListWidget.hitCountLimit` | Number | No | Maximum items to display (default: 1000) |
+| `cf.cplace.draggablePageListWidget.blockedAttribute` | Dynamic Enumeration | No | Boolean attribute to highlight blocked items |
+| `cf.cplace.draggablePageListWidget.typeIconAttribute` | Dynamic Enumeration | No | Enumeration attribute for type indicator icons |
+| `cf.cplace.draggablePageListWidget.responsibleUserAttribute` | Dynamic Enumeration | No | User reference attribute for responsible person |
+| `cf.cplace.draggablePageListWidget.labelIndicatorReferenceAttribute` | Dynamic Enumeration | No | Attributes whose values display as labels (multiple) |
+| `cf.cplace.draggablePageListWidget.additionalIconAttributes` | Dynamic Enumeration | No | Additional icon attributes (multiple) |
+| `cf.cplace.draggablePageListWidget.height` | Number | No | Widget height in pixels |
+
+**Rich Item Display Features:**
+- Item title with clickable link to the page
+- Type indicator icons from configurable attribute
+- Responsible user avatars (with "+N" overflow handling)
+- Label indicators as tags
+- Additional icon attributes
+- Blocked item highlighting
+
+## Use Cases
+
+### Task and Backlog Management
+- Managing task backlogs where items need to be ordered by priority
+- Sprint planning with drag-and-drop story prioritization
+- Work item ranking and ordering
+- Queue management for items awaiting processing
+
+### Roadmap and Planning
+- Ordering features or initiatives by priority
+- Timeline sequencing of deliverables
+- Release planning with priority-based sorting
+- Sequential process planning
+
+### Resource Management
+- Prioritizing resource requests or assignments
+- Budget allocation ordering
+- Service request queue management
+- Workflow step ordering
+
+## Data Model Requirements
+
+To use this widget, your target page type needs:
+
+1. **Required:** A numeric attribute for storing order/priority values
+2. **Optional:** User reference attribute for displaying responsible parties
+3. **Optional:** Enumeration attributes for icons and labels
+4. **Optional:** Boolean attribute for blocked status indicators
+
+**Important:** The search configuration must return pages of a single type to ensure consistent attribute handling.
+
+## Usage Notes
+
+### When to Use
+- You need visual management of priority or order for a set of pages
+- Users benefit from an intuitive drag-and-drop interface rather than manual numeric entry
+- You need to separate sorted items from unsorted/new items
+- You want to display responsible users and metadata alongside items
+
+### When Not to Use
+- For simple display of search results without ordering (use Table widget instead)
+- When the dataset exceeds 1000 items (performance considerations)
+- When you need to display pages of multiple types in the same list
+
+### Common Pitfalls
+- **Search returning multiple types:** Widget requires single-type search results
+- **Missing order attribute:** Without a numeric attribute, drag-and-drop cannot persist changes
+- **Exceeding hit count limits:** Large search results trigger error alerts; refine search or adjust `hitCountLimit`
+- **Incorrect attribute types:** Order attribute must be numeric and sortable
+
+### Permission Requirements
+- **Edit permissions** on the order attribute to reorder items through drag-and-drop
+- **Read permissions** to view listed pages and their metadata
+
+## Related Widgets
+
+- **cf.platform.embeddedSearchAsTable** - Use for standard search results lists when drag-and-drop ordering is not needed
+- **cf.cplace.cboard.main.board** - Use for Kanban-style boards with status-based columns
+- **cf.platform.embeddedSearchAsList** - Use for simple list display without ordering capabilities
+
+---
+*Investigation Date: 2026-02-02*
+*Investigation Workspace: [App Investigation] cf.cplace.draggablePageList (ueqop5b5o246hwc7k0baczcbn)*