appydave-tools 0.15.0 → 0.16.0

data/docs/tools/index.md

@@ -0,0 +1,324 @@
+# AppyDave Tools Documentation
+
+Complete documentation for all appydave-tools with practical examples and AI agent use cases.
+
+## Quick Navigation
+
+### Core Content Tools
+
+| Tool | Purpose | Status | Read Time |
+|------|---------|--------|-----------|
+| **[gpt-context](gpt-context.md)** | Gather project files for AI context | ✅ Active | 10 min |
+| **[youtube-manager](youtube-manager.md)** | Manage YouTube video metadata | ✅ Active | 8 min |
+| **[subtitle-processor](subtitle-processor.md)** | Clean and merge SRT files | ✅ Active | 7 min |
+| **[move-images](move-images.md)** | Organize image assets for videos | ✅ Active | 8 min |
+
+### Workflow & Automation Tools
+
+| Tool | Purpose | Status | Read Time |
+|------|---------|--------|-----------|
+| **[youtube-automation](youtube-automation.md)** | Orchestrate YouTube workflows | ✅ Active | 8 min |
+| **[configuration](configuration.md)** | Multi-channel setup & management | ✅ Active | 9 min |
+| **[cli-actions](cli-actions.md)** | Framework for CLI tools | ✅ Infrastructure | 10 min |
+| **[name-manager](name-manager.md)** | Parse and generate project names | ✅ Infrastructure | 8 min |
+
+### Legacy & Specialized Tools
+
+| Tool | Purpose | Status | Read Time |
+|------|---------|--------|-----------|
+| **[prompt-tools](prompt-tools.md)** | Text completion (OpenAI API) | ⚠️ Deprecated | 6 min |
+| **[bank-reconciliation](bank-reconciliation.md)** | Process transaction data | ✅ Private | 8 min |
+
+---
+
+## Tool Categories
+
+### 🎥 Video Production Tools
+
+For managing video content workflows:
+
+1. **[youtube-manager](youtube-manager.md)** - Update video metadata at scale
+2. **[subtitle-processor](subtitle-processor.md)** - Clean and merge subtitles
+3. **[move-images](move-images.md)** - Organize image assets
+4. **[youtube-automation](youtube-automation.md)** - Automate workflows
+
+### 🤖 AI & Context Tools
+
+For working with AI assistants:
+
+1. **[gpt-context](gpt-context.md)** - Gather files for AI (most important for AI agents)
+2. **[prompt-tools](prompt-tools.md)** - Legacy OpenAI API (deprecated)
+
+### ⚙️ Infrastructure Tools
+
+For system setup and management:
+
+1. **[configuration](configuration.md)** - Channel and API setup
+2. **[cli-actions](cli-actions.md)** - Build custom CLI tools
+3. **[name-manager](name-manager.md)** - Project naming patterns
+
+### 💰 Financial Tools
+
+For personal financial management:
+
+1. **[bank-reconciliation](bank-reconciliation.md)** - Process transactions
+
+---
+
+## Getting Started
+
+### First Time Users
+
+1. **Read [configuration](configuration.md)** - Set up your channels
+2. **Choose your workflow**:
+   - Video content? → Start with [youtube-manager](youtube-manager.md)
+   - AI assistance? → Start with [gpt-context](gpt-context.md)
+   - Subtitles? → Read [subtitle-processor](subtitle-processor.md)
+
+### For AI Agents
+
+Each tool document includes **10 AI agent use cases** showing how AI can leverage the tool:
+
+- **Code Review** - Gather context, analyze
+- **Bug Fixing** - Understand codebase, suggest fixes
+- **Automation** - Orchestrate workflows
+- **Batch Processing** - Handle multiple items
+- **Integration** - Combine tools for complex tasks
+
+→ Check "Use Cases for AI Agents" section in each tool doc
+
+### Command Examples
+
+Quick reference for most-used commands:
+
+```bash
+# Gather context for AI
+gpt_context -i '**/*.rb' -e 'spec/**/*' -d -o context.txt
+
+# Get YouTube video details
+youtube_manager get -v dQw4w9WgXcQ
+
+# Update video metadata
+youtube_manager update -v dQw4w9WgXcQ -t "New Title" -d "New description"
+
+# Clean SRT subtitles
+subtitle_processor clean -f input.srt -o output.srt
+
+# Organize image assets
+move_images -f project-name intro city-skyline
+
+# Set up configuration
+configuration create-channel
+```
+
+---
+
+## Documentation Structure
+
+Each tool document includes:
+
+### 📝 "What It Does"
+- Clear description of the tool's purpose
+- What problems it solves
+- Key capabilities
+
+### 📖 "How to Use"
+- Practical, copy-paste examples
+- Common usage patterns
+- Command reference with all options
+- Configuration details
+
+### 🤖 "Use Cases for AI Agents"
+- **10 specific scenarios** showing AI agent integration
+- Examples of how AI can discover and use the tool
+- Workflow coordination examples
+- Batch processing patterns
+
+### 🔧 "Command Reference"
+- Complete option lists
+- Parameter descriptions
+- Required vs optional flags
+- Examples for each option
+
+### 🐛 "Troubleshooting"
+- Common issues and solutions
+- Error messages and fixes
+- FAQ section
+- Configuration problems
+
+### 💡 "Tips & Tricks"
+- Best practices
+- Efficiency suggestions
+- Common patterns
+- Performance tips
+
+---
+
+## Tool Relationships
+
+### Data Flow
+
+```
+Downloaded Images
+       ↓
+[move-images]
+       ↓
+Organized Assets
+       ↓
+[youtube-manager]
+       ↓
+Video Metadata
+       ↓
+[youtube-automation]
+       ↓
+Published Videos
+```
+
+### AI Agent Workflow
+
+```
+Codebase
+       ↓
+[gpt-context]
+       ↓
+Project Context
+       ↓
+AI Agent
+       ↓
+Analysis/Code/Docs
+```
+
+### Configuration Hub
+
+```
+[configuration]
+     ↓ provides setup for ↓
+[youtube-manager]
+[youtube-automation]
+[gpt-context]
+[cli-actions]
+```
+
+---
+
+## Key Features Across Tools
+
+### Parallel to Understand
+
+**All tools follow consistent patterns:**
+
+- **Option parsing**: `-i` for input, `-o` for output, `-d` for debug
+- **Multiple patterns**: Can process multiple files with patterns
+- **Flexible output**: Clipboard, file, or both
+- **Help available**: All tools support `-h` or `--help`
+- **Batch capable**: Most tools can process multiple items
+
+### Common Options Across Tools
+
+| Option | Meaning | Tools Using It |
+|--------|---------|----------------|
+| `-i` | Include/input | gpt_context, bank_reconciliation |
+| `-e` | Exclude | gpt_context |
+| `-o` | Output | gpt_context, subtitle_processor, others |
+| `-d` | Debug | gpt_context, youtube_automation |
+| `-f` | File/folder | subtitle_processor, bank_reconciliation |
+| `-v` | Video ID | youtube_manager, get_video_action |
+| `-t` | Title | youtube_manager, update_video_action |
+
+---
+
+## Use Case Finder
+
+**Looking for a specific task?**
+
+- **Batch update 50 YouTube videos?** → [youtube-manager](youtube-manager.md) + script
+- **Understand a codebase before refactoring?** → [gpt-context](gpt-context.md)
+- **Fix corrupted subtitles?** → [subtitle-processor](subtitle-processor.md)
+- **Set up multi-channel YouTube?** → [configuration](configuration.md)
+- **Prepare images for video?** → [move-images](move-images.md)
+- **Build custom CLI tool?** → [cli-actions](cli-actions.md)
+- **Manage project names?** → [name-manager](name-manager.md)
+- **Automate video workflows?** → [youtube-automation](youtube-automation.md)
+- **Process bank data?** → [bank-reconciliation](bank-reconciliation.md)
+
+---
+
+## Related Documentation
+
+### Archive & Reference
+
+- `archive/` folder contains:
+  - `documentation-framework-proposal.md` - How we organize docs
+  - `test-coverage-quick-wins.md` - Testing priorities
+  - `codebase-audit-2025-01.md` - Codebase inventory
+  - Other reference materials
+
+### Digital Asset Management
+
+- `dam/` folder contains:
+  - `overview.md` - DAM system design
+
+---
+
+## Contributing to Documentation
+
+### To Add Use Cases
+Each tool has 10 AI agent use cases. To add more:
+1. Open the tool's `.md` file
+2. Find "Use Cases for AI Agents" section
+3. Add new numbered use case with:
+   - Brief command example
+   - Bold "AI discovers:" line explaining what the agent learns
+   - How the agent can apply it
+
+### To Fix or Improve
+- Suggest improvements via PR
+- Follow the structure: What → How → Use Cases
+- Keep examples practical and copy-paste ready
+
+---
+
+## Quick Command Cheat Sheet
+
+```bash
+# AI Context (most important for AI agents)
+gpt_context -i '**/*.rb' -e 'spec/**/*' -d -o context.txt
+
+# YouTube Operations
+youtube_manager get -v VIDEO_ID
+youtube_manager update -v VIDEO_ID -t "Title" -d "Description"
+
+# Subtitles
+subtitle_processor clean -f input.srt -o output.srt
+subtitle_processor join -d ./ -f "*.srt" -o merged.srt
+
+# Assets
+move_images -f project-name section prefix
+
+# Setup
+configuration create-channel
+configuration validate
+
+# Automation
+youtube_automation execute workflow_name
+youtube_automation status job_id
+```
+
+---
+
+## Status Legend
+
+- ✅ **Active** - Stable, regularly used in production
+- ⚠️ **Deprecated** - Still works but plan to migrate
+- 🔧 **Maintenance** - Works, not actively developed
+- 🟢 **Infrastructure** - Internal framework/utilities
+- 🔴 **Private** - Personal/financial tools, not for sharing
+
+---
+
+**Last Updated**: November 2024
+**Total Documentation**: ~2,900 lines
+**Tools Documented**: 10
+**Use Cases**: 100+ (10 per tool)
+
+**Start reading**: Choose a tool above that matches your task!

data/docs/tools/move-images.md

@@ -0,0 +1,295 @@
+# Move Images
+
+Organize and rename downloaded images for use in video projects with section-based folder structure.
+
+## What It Does
+
+**Move Images** organizes image assets for video production:
+
+- Moves downloaded images from smart-downloads to project folders
+- Renames images with section-based prefixes for organization
+- Creates nested folder structure automatically (assets/section/)
+- Indexes images sequentially for easy reference
+- Maintains asset library organization for video projects
+
+## How to Use
+
+### Basic Usage
+
+```bash
+move_images -f <folder> <section> <prefix>
+```
+
+**Parameters**:
+- `-f` / `--folder`: Video project folder (e.g., `appydave-b60`)
+- `section`: Asset category (e.g., `intro`, `content`, `outro`)
+- `prefix`: Image name prefix (e.g., `city`)
+
+### Example
+
+```bash
+# Move downloaded images for AppyDave video 60, intro section
+move_images -f appydave-b60 intro city
+
+# Result:
+# ~/Sync/smart-downloads/download-images/image-001.jpg →
+# /Volumes/Expansion/Sync/tube-channels/video-projects/appydave-b60/assets/intro/city-intro-1.jpg
+#
+# ~/Sync/smart-downloads/download-images/image-002.jpg →
+# /Volumes/Expansion/Sync/tube-channels/video-projects/appydave-b60/assets/intro/city-intro-2.jpg
+```
+
+### Multiple Sections
+
+```bash
+# Organize intro images
+move_images -f video-project intro opening
+
+# Later, organize content images
+move_images -f video-project content landscape
+
+# Later, organize outro images
+move_images -f video-project outro closing
+
+# Result folder structure:
+# video-project/assets/
+# ├── intro/
+# │   ├── opening-intro-1.jpg
+# │   ├── opening-intro-2.jpg
+# │   └── ...
+# ├── content/
+# │   ├── landscape-content-1.jpg
+# │   ├── landscape-content-2.jpg
+# │   └── ...
+# └── outro/
+#     ├── closing-outro-1.jpg
+#     ├── closing-outro-2.jpg
+#     └── ...
+```
+
+## Directory Structure
+
+### Source Structure
+```
+~/Sync/smart-downloads/download-images/
+├── image-001.jpg
+├── image-002.jpg
+├── image-003.jpg
+└── ... (downloaded from web, browser auto-saves)
+```
+
+### Destination Structure
+```
+/Volumes/Expansion/Sync/tube-channels/video-projects/
+└── {project-name}/
+    └── assets/
+        ├── intro/
+        │   ├── {prefix}-intro-1.jpg
+        │   └── {prefix}-intro-2.jpg
+        ├── content/
+        │   ├── {prefix}-content-1.jpg
+        │   └── {prefix}-content-2.jpg
+        └── outro/
+            ├── {prefix}-outro-1.jpg
+            └── {prefix}-outro-2.jpg
+```
+
+## Use Cases for AI Agents
+
+### 1. Bulk Asset Organization
+```bash
+# AI orchestrates: Download → Move → Organize
+# For multiple images across multiple sections
+for image_set in intro content outro transition; do
+  move_images -f project-name "$image_set" "prefix-for-$image_set"
+done
+```
+**AI discovers**: Asset organization workflow, section patterns. Can systematically organize image libraries.
+
+### 2. Asset Library Maintenance
+```bash
+# AI reviews asset structure
+# Ensures all sections are properly organized
+# Identifies orphaned or misplaced images
+```
+**AI discovers**: Current asset state, what's organized/disorganized. Can clean up asset libraries.
+
+### 3. Video Production Workflow
+```bash
+# Part of larger workflow:
+# 1. Search/download images (browser smart-download)
+# 2. Move images to project (move_images)
+# 3. Reference in video editing (from assets folder)
+# 4. FliVideo imports from assets
+```
+**AI discovers**: Image integration into video pipeline. Can automate asset management in video workflows.
+
+### 4. Multi-Section Asset Management
+```bash
+# Complex video with many sections
+# AI orchestrates moving images for each section
+# Ensures proper folder structure throughout
+```
+**AI discovers**: Project complexity, section organization. Can manage multi-part asset structures.
+
+### 5. Asset Inventory
+```bash
+# After moving images, create inventory
+# Count assets per section
+# Generate asset report for video editor
+```
+**AI discovers**: What assets are available for each section. Can provide asset inventory for planning.
+
+### 6. Naming Convention Enforcement
+```bash
+# Ensure consistent naming:
+# {prefix}-{section}-{number}.jpg
+# AI validates moved files follow pattern
+```
+**AI discovers**: Naming scheme, consistency. Can enforce standard naming across projects.
+
+### 7. Batch Project Setup
+```bash
+# Set up image assets for multiple projects
+# Each project: multiple sections with different image sets
+# AI coordinates: move_images for each section
+```
+**AI discovers**: Project requirements, multi-section needs. Can batch-organize multiple projects.
+
+### 8. Asset Deduplication
+```bash
+# Before moving, check if images already exist
+# Avoid duplicate assets in project
+# AI coordinates smart deduplication
+```
+**AI discovers**: Existing assets, duplicates. Can prevent redundant downloads/moves.
+
+### 9. Workflow Validation
+```bash
+# After moving, verify:
+# - All images in correct folders
+# - Naming follows convention
+# - No images left in download folder
+# - Asset count matches expectation
+```
+**AI discovers**: Workflow correctness. Can validate asset organization integrity.
+
+### 10. Asset Tracking & Metadata
+```bash
+# Track which images went where
+# Create manifest of assets per section
+# Link images to video timeline positions
+```
+**AI discovers**: Asset-to-content mapping. Can create detailed asset metadata for video production.
+
+## Command Reference
+
+### Move Images
+```bash
+move_images -f <folder> <section> <prefix>
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `-f FOLDER` / `--folder FOLDER` | Video project folder name (required) |
+| `section` | Asset category: intro, content, outro, transition, thumb, teaser, etc. |
+| `prefix` | Image name prefix for organization (e.g., "city", "beach", "nature") |
+
+### Supported Sections (Common)
+
+- `intro` - Introduction/opening images
+- `content` - Main content images
+- `outro` - Closing/ending images
+- `transition` - Between-section transition images
+- `thumb` - Thumbnail candidate images
+- `teaser` - Teaser/preview images
+- Custom sections allowed (any string)
+
+## Folder Paths
+
+### Configuration
+- **Base directory**: `/Volumes/Expansion/Sync/tube-channels/video-projects`
+- **Source folder**: `~/Sync/smart-downloads/download-images/`
+- **Destination**: `{base}/{project}/assets/{section}/`
+
+## Image Naming Convention
+
+Generated filename format:
+```
+{prefix}-{section}-{number}.jpg
+```
+
+Examples:
+- `city-intro-1.jpg`
+- `city-intro-2.jpg`
+- `landscape-content-1.jpg`
+- `beach-outro-1.jpg`
+
+## Workflow Integration
+
+Typical video production workflow:
+
+```
+1. Research & Download (Browser → smart-downloads)
+2. Move & Organize (move_images tool)
+3. Reference in Planning (asset folders organized by section)
+4. Video Editing (editor selects from assets/{section}/)
+5. FliVideo (can reference assets from organized structure)
+6. Publish (video with organized asset trail)
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Folder doesn't exist" | Create project folder first in video-projects/ |
+| "No images found" | Verify images exist in ~/Sync/smart-downloads/download-images/ |
+| "Permission denied" | Check folder permissions, verify external drive is mounted |
+| "Images not moved" | Check source folder path, verify .jpg extension |
+
+## Tips & Tricks
+
+1. **Use descriptive prefixes**: "city-skyline" is better than "img"
+2. **Process in order**: intro → content → outro
+3. **Batch similar images**: Download all for one section, move them together
+4. **Check results**: Verify folder structure matches expectation
+5. **Multiple images**: First move, then use for reference in video editing
+
+## Example Workflow
+
+```bash
+# Step 1: Download images (using browser, auto-saves to smart-downloads)
+# Images saved as image-001.jpg, image-002.jpg, etc.
+
+# Step 2: Organize for intro
+move_images -f appydave-b60 intro "opening-scene"
+
+# Step 3: Download more images, organize for content
+move_images -f appydave-b60 content "landscape"
+
+# Step 4: Download final images, organize for outro
+move_images -f appydave-b60 outro "sunset"
+
+# Result:
+# appydave-b60/assets/
+# ├── intro/
+# │   ├── opening-scene-intro-1.jpg
+# │   ├── opening-scene-intro-2.jpg
+# │   └── opening-scene-intro-3.jpg
+# ├── content/
+# │   ├── landscape-content-1.jpg
+# │   ├── landscape-content-2.jpg
+# │   └── landscape-content-3.jpg
+# └── outro/
+#     ├── sunset-outro-1.jpg
+#     └── sunset-outro-2.jpg
+```
+
+---
+
+**Related Tools**:
+- `configuration` - Project folder setup
+- FliVideo - Uses organized assets in video production
+- Video editing software - Selects images from organized assets
+
+**Integration**: Part of AppyDave video production pipeline