docs: Add comprehensive handler documentation (#298)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: ben <ben@prologe.io>

tutorials/CommonWorkflows.md

@@ -0,0 +1,64 @@
+# Common Workflows
+
+This document describes common combinations of tools and how they work together to accomplish complex tasks.
+
+## Renaming Untitled Files
+
+### Step 1: Retrieve Untitled Files
+```
+Could you retrieve all my untitled files?
+```
+This triggers the search tool to find files matching the "untitled" pattern.
+
+### Step 2: Rename Files
+```
+rename files with something meaningful
+```
+This triggers the ExecuteActionsHandler to:
+1. Analyze the content of each file
+2. Generate meaningful names
+3. Show a confirmation button
+4. Execute the renaming when confirmed
+
+### What Happens Behind the Scenes
+1. The first prompt triggers `searchByName` with pattern "Untitled*"
+2. Files are added to context
+3. The second prompt triggers `executeActionsOnFileBasedOnPrompt`
+4. The ExecuteActionsHandler processes each file
+
+## Using Screenpipe Data for Organization
+
+### Step 1: Get Activity Data
+```
+based on my screenpipe activity give me a small summary of my day 
+```
+
+This uses the Screenpipe context so you can create daily logs of based on your activity right in Obidian.
+
+
+
+## Finding and Tagging Recent Files
+
+### Step 1: Get Recent Files
+```
+get my last 7 files
+```
+This retrieves your most recently modified files.
+
+### Step 2: Add Tags
+```
+tag these files based on their content
+```
+This analyzes and tags the files appropriately.
+
+### What Happens Behind the Scenes
+1. First prompt triggers `getLastModifiedFiles`
+2. Files are added to context
+3. Second prompt triggers `executeActionsOnFileBasedOnPrompt` with tag action
+4. Tags are suggested and applied with confirmation
+
+## Tips for Effective Workflows
+1. Always check the confirmation messages
+2. Review suggested changes before confirming
+3. Use specific language to trigger desired actions
+4. Combine tools in sequence for complex operations

tutorials/ExecuteActionsHandler.md

@@ -0,0 +1,44 @@
+# ExecuteActionsHandler
+
+## Overview
+The ExecuteActionsHandler is a powerful tool that can analyze file content and perform various actions like tagging, moving to folders, or renaming files based on their content.
+
+## Usage
+
+### Basic Command
+The handler is typically triggered after selecting files to process, using a natural language prompt like:
+```
+rename files with something meaningful
+```
+
+This will trigger the `executeActionsOnFileBasedOnPrompt` tool in the chat interface.
+
+### Parameters
+The handler accepts:
+- `filePaths`: Array of file paths to analyze
+- `userPrompt`: Instructions for how to rename/re-tag/re-folder the files
+
+### Actions Available
+The handler can perform three types of actions based on the user prompt:
+1. **Tags** (triggered by words like "tag" or "label")
+   - Recommends and adds tags based on content
+2. **Folders** (triggered by words like "folder", "move", or "organize")
+   - Suggests and moves files to appropriate folders
+3. **Names** (default action)
+   - Recommends and applies meaningful names based on content
+
+### How It Works
+1. The handler:
+   - Analyzes the user prompt to determine the action type
+   - Processes each file individually
+   - Shows a confirmation button before executing actions
+   - Provides visual feedback for each operation
+
+### Example Response
+The handler shows:
+- Success: "✅ Added tag [tag] to [filename]"
+- Info: "ℹ️ No suggestions for [filename]"
+- Error: "❌ Error processing [filename]"
+
+### Code Reference
+The handler is implemented in `packages/plugin/views/ai-chat/tool-handlers/execute-actions-handler.tsx` and is triggered through the chat interface defined in `packages/web/app/api/(newai)/chat/route.ts`.

tutorials/LastModifiedHandler.md

@@ -0,0 +1,41 @@
+# LastModifiedHandler
+
+## Overview
+The LastModifiedHandler allows you to retrieve recently modified files from your vault. It's particularly useful for finding files you've recently worked on.
+
+## Usage
+
+### Basic Command
+To get your recently modified files, use a natural language prompt like:
+```
+get my last 7 files
+```
+
+This will trigger the `getLastModifiedFiles` tool in the chat interface.
+
+### Parameters
+The handler accepts one parameter:
+- `count`: The number of last modified files to retrieve
+
+### How It Works
+1. When triggered, the handler:
+   - Gets all markdown files from the vault
+   - Sorts them by modification time
+   - Retrieves the specified number of most recent files
+   - Adds the files to the context for further operations
+
+### Example Response
+The handler will show:
+- Loading state: "Fetching last modified files..."
+- Success state: "Found X recently modified files"
+- Error state: "No recently modified files found"
+
+### File Information Retrieved
+For each file, the handler returns:
+- Title (basename)
+- Content
+- Path
+- Last modified timestamp
+
+### Code Reference
+The handler is implemented in `packages/plugin/views/ai-chat/tool-handlers/last-modified-handler.tsx` and is triggered through the chat interface defined in `packages/web/app/api/(newai)/chat/route.ts`.

tutorials/ScreenpipeHandler.md

@@ -0,0 +1,37 @@
+# ScreenpipeHandler
+
+## Overview
+The ScreenpipeHandler is a tool that allows you to retrieve and analyze your Screenpipe activity data. It processes screen recording data and provides insights about your daily activities.
+
+## Usage
+
+### Basic Command
+To retrieve your Screenpipe activity, you can use a natural language prompt like:
+```
+based on my screenpipe activity
+```
+
+This will trigger the `getScreenpipeDailySummary` tool in the chat interface.
+
+### Parameters
+The handler accepts the following parameters:
+- `startTime` (optional): Start time in ISO format
+- `endTime` (optional): End time in ISO format
+
+If no times are specified, it will use default time ranges.
+
+### How It Works
+1. When triggered, the handler:
+   - Fetches daily information using the `getDailyInformation` function
+   - Clears existing context
+   - Adds new Screenpipe data to the context
+   - Returns the results with success/failure status
+
+### Example Response
+The handler will show:
+- A loading state: "Fetching Screenpipe data..."
+- Success state: "Screenpipe data successfully retrieved"
+- Error state: "Failed to fetch Screenpipe data"
+
+### Code Reference
+The handler is implemented in `packages/plugin/views/ai-chat/tool-handlers/screenpipe-handler.tsx` and is triggered through the chat interface defined in `packages/web/app/api/(newai)/chat/route.ts`.