appydave-tools 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f220893e70bf53b9a6da3b1a46857c3221f2672aba453616e4bab5b87528d65
-  data.tar.gz: 1e5aef7918151c423393131dcfc8e2538cd6b95632b2a58dd8f23a1c864f1c06
+  metadata.gz: '0819e2db66666e4729144ba1a8dac0032a5b323f4475f9cdc84459aa9309cd49'
+  data.tar.gz: ce1185ecbf19793175fa91f4a5c3e401df36394349ec454c7c47fa38e2193727
 SHA512:
-  metadata.gz: fe5e90a6677bcb82e0d1af5fde786eba72d2380f1dcbe291b4fe998b239f71c6381bd33b7dfa87755e2b9390d97241387422c84522d3763236e87688668ed861
-  data.tar.gz: 70abc6727a6e318d329097b42a72fc8de4061965d60e7d33d013fa361b00a1c6e3b9eabe94a7a15a5e993523ea6ba96b69231c83bdae0f030f16ad0ec4a1e50d
+  metadata.gz: d1c6e936fa7d41f160152cf3e037485c9c0e509377f81970df9295cb38bdcc33bfea489da5ab666baa87042d645d609f35048b96826241bc636097c192525015
+  data.tar.gz: b4accc9229eda2cd3777f6828e2a3b6988208033a1a5df55f5c487519321a76845cf908fac1056598231973c26d8a9866ab311307157b30dcac472534d42465f

data/.rubocop.yml

@@ -127,6 +127,12 @@ RSpec/PendingWithoutReason:
 RSpec/MultipleMemoizedHelpers:
   Enabled: false
 
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/StubbedMock:
+  Enabled: false
+
 Metrics/AbcSize:
   Max: 25
   Exclude:

data/AGENTS.md

@@ -0,0 +1,22 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Core Ruby code lives in `lib/appydave/tools/` with one folder per CLI (gpt_context, youtube_manager, subtitle_processor, etc.). Executables in `bin/` are for development helpers, while packaged entrypoints reside in `exe/`. Specs mirror the library layout under `spec/`, supported by sample data in `spec/samples/`. Shared docs and walkthroughs are collected under `docs/`. Temporary or generated artifacts (`coverage/`, `tmp/`, `transient/`) should stay out of commits.
+
+## Build, Test, and Development Commands
+`bin/setup` installs gem dependencies and any Node helpers declared in `package.json`. Run `bundle exec rake spec` (aliased as `rake spec`) for the full test suite, and keep `guard` running during feature work to auto-rerun specs. Use `bundle exec rubocop` to enforce lint rules, and `bin/console` for an interactive Pry session preloaded with the gem. CLI binaries can be invoked directly, e.g., `bin/gpt_context.rb -i '**/*.rb' -d`.
+
+## Coding Style & Naming Conventions
+The codebase targets Ruby 2.7 with two-space indentation and descriptive method names. Follow `.rubocop.yml`: 200-character line limit, relaxed metrics inside `spec/`, and RuboCop RSpec/Rake plugins enabled. Namespaces follow `AppyDave::Tools::<Feature>` inside `lib/`, and CLI filenames stay snake_case (`bin/move_images.rb`). Prefer keyword args, early returns, and guard clauses over deeply nested conditionals.
+
+## Testing Guidelines
+RSpec is the canonical framework. Name files `*_spec.rb` that mirror lib paths (e.g., `spec/gpt_context/collector_spec.rb`). Isolate behavior with `describe '#method'` blocks, keep helpers in `spec/support`, and favor `let`/`let!` over global state. Run focused tests via `bundle exec rspec spec/path/to/file_spec.rb` when iterating, then finish with `rake spec`. Add regression tests for every bug fix to keep CLI behavior stable.
+
+## Commit & Pull Request Guidelines
+Commits follow conventional commits consumed by semantic-release (`feat:`, `fix:`, `chore:`, `feat!:`, etc.). Scope messages to a single tool when possible (`fix(subtitle_processor): correct offset buffer`). Before opening a PR, ensure `rake spec` and `rubocop` pass, summarize the change, link issues or YouTube scripts, and include CLI output or screenshots if user-facing behavior shifts. Leave follow-up tasks in checklists so reviewers can track outstanding work.
+
+## Agent Coordination
+Claude is the primary automation agent; align with the collaboration notes in `CLAUDE.md` before introducing new flows or prompt templates. When scripting repeatable tasks (gpt_context runs, metadata syncs), document the expected Claude inputs/outputs so the agent can reproduce them. Flag breaking CLI changes in PR descriptions with a dedicated **Claude Impact** subsection to keep downstream automations in sync.
+
+## Security & Configuration Tips
+Keep API keys and OAuth secrets in `.env` or `~/.config/appydave/` (managed via `ad_config`). Never commit those files; `.gitignore` already excludes them. Validate YouTube API changes against a test channel before touching production content, and rotate credentials when machines change owners.

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [0.16.0](https://github.com/appydave/appydave-tools/compare/v0.15.0...v0.16.0) (2025-11-08)
+
+
+### Bug Fixes
+
+* fix cops ([6c1d59b](https://github.com/appydave/appydave-tools/commit/6c1d59bd870af519825556f7304d6ca1677d8649))
+
+
+### Features
+
+* update documentation and general purpose rename and fixes via claude ([027c3df](https://github.com/appydave/appydave-tools/commit/027c3dff11e572359e6f2d1ebc17010dc3b8d7ee))
+
+# [0.15.0](https://github.com/appydave/appydave-tools/compare/v0.14.1...v0.15.0) (2025-11-08)
+
+
+### Features
+
+* update claude and git leaks ([0b8212f](https://github.com/appydave/appydave-tools/commit/0b8212fa65a920c608876c4f4f37c166dc552039))
+
 ## [0.14.1](https://github.com/appydave/appydave-tools/compare/v0.14.0...v0.14.1) (2025-08-06)
 
 

data/CLAUDE.md

@@ -2,9 +2,48 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Project Purpose
+
+**AppyDave Tools** is a consolidated productivity toolkit built for AppyDave's YouTube content creation workflow. All utilities live in one repository for easier maintenance than managing separate codebases.
+
+**📖 See [docs/purpose-and-philosophy.md](./docs/purpose-and-philosophy.md) for complete philosophy and design principles.**
+
+**Key Points:**
+- **Consolidated toolkit** - One codebase for easier maintenance
+- **YouTube workflow** - Built specifically for content creator productivity
+- **Single-purpose tools** - Each tool solves one problem independently
+- **Shareable individually** - Tools can be featured in standalone videos
+- **Language flexible** - Currently Ruby, could be rewritten if needed
+
 ## Common Commands
 
 ### Development Setup
+
+**⚠️ IMPORTANT: Bundler Setup for Claude Code**
+
+This project requires Bundler 2.6.2. If you encounter `Could not find 'bundler' (2.6.2)` errors during Claude Code execution:
+
+**Automatic fix (recommended):**
+```bash
+eval "$(rbenv init -)" && gem install bundler:2.6.2
+```
+
+**Make permanent** - Add to your `.zshrc` or `.bashrc`:
+```bash
+# Add rbenv to PATH and initialize
+eval "$(rbenv init - zsh)"
+```
+
+**For Claude Code:** The `eval "$(rbenv init -)"` command is automatically prepended to bash commands when needed.
+
+**Manual verification:**
+```bash
+which ruby          # Should show: /Users/[user]/.rbenv/shims/ruby
+ruby --version      # Should show: ruby 3.4.2
+bundler --version   # Should show: Bundler version 2.6.2
+```
+
+**Standard setup:**
 ```bash
 bin/setup           # Install dependencies and setup development environment
 bin/console         # Interactive Ruby console for experimentation
@@ -16,15 +55,16 @@ bin/console         # Interactive Ruby console for experimentation
 
 #### Quick Reference Index
 
-| Command | Gem Command | Description |
-|---------|-------------|-------------|
-| **GPT Context** | `gpt_context` | Collect project files for AI context ⭐ |
-| **YouTube Manager** | `youtube_manager` | Manage YouTube video metadata via API |
-| **Subtitle Manager** | `subtitle_manager` | Process and join SRT subtitle files |
-| **Prompt Tools** | `prompt_tools` | AI prompt completion workflows |
-| **YouTube Automation** | `youtube_automation` | Automated YouTube workflows with GPT agents |
-| **Configuration** | `ad_config` | Manage appydave-tools configuration files |
-| **Move Images** | N/A (dev only) | Organize video project images (development tool) |
+| Command | Gem Command | Description | Status |
+|---------|-------------|-------------|--------|
+| **GPT Context** | `gpt_context` | Collect project files for AI context | ⭐ PRIMARY |
+| **YouTube Manager** | `youtube_manager` | CRUD operations on YouTube video metadata | ✅ ACTIVE |
+| **Subtitle Processor** | `subtitle_processor` | Transform SRT files (clean/merge) | ✅ ACTIVE |
+| **VAT (Video Asset Tools)** | `vat` | Multi-tenant video project storage orchestration | ✅ ACTIVE |
+| **Configuration** | `ad_config` | Manage JSON configs (channels, paths, sequences) | ✅ ACTIVE |
+| **Move Images** | N/A (dev only) | Organize video asset images | ✅ ACTIVE |
+| **Prompt Tools** | `prompt_tools` | OpenAI Completion API wrapper | ⚠️ DEPRECATED API |
+| **YouTube Automation** | `youtube_automation` | Prompt sequence runner | ⚠️ INTERNAL USE |
 
 ---
 
@@ -73,21 +113,25 @@ bin/youtube_manager.rb update --video-id ID --category-id 28
 - Update video title, description, tags, and category
 - Generate detailed reports
 
-#### 3. Subtitle Manager (`bin/subtitle_manager.rb`)
+#### 3. Subtitle Processor (`bin/subtitle_processor.rb`)
 Process and manage SRT subtitle files:
 
 ```bash
 # Clean and normalize SRT files
-bin/subtitle_manager.rb clean -f input.srt -o cleaned.srt
+bin/subtitle_processor.rb clean -f input.srt -o cleaned.srt
 
 # Join multiple SRT files
-bin/subtitle_manager.rb join -d ./subtitles -f "*.srt" -o merged.srt
-bin/subtitle_manager.rb join -f "part1.srt,part2.srt" -s asc -b 100 -o final.srt
+bin/subtitle_processor.rb join -d ./subtitles -f "*.srt" -o merged.srt
+bin/subtitle_processor.rb join -f "part1.srt,part2.srt" -s asc -b 100 -o final.srt
 
 # Join with options
-bin/subtitle_manager.rb join -d ./subs -f "*.srt" -s inferred -b 200 -o output.srt -L detail
+bin/subtitle_processor.rb join -d ./subs -f "*.srt" -s inferred -b 200 -o output.srt -L detail
 ```
 
+**Operations:**
+- **clean**: Removes HTML tags (`<u>`), merges duplicate entries, normalizes spacing
+- **join**: Parses multiple SRT files, adjusts timestamps with buffer, merges timeline
+
 **Options:**
 - `-d, --directory` - Directory containing SRT files
 - `-f, --files` - File pattern or comma-separated list
@@ -95,22 +139,100 @@ bin/subtitle_manager.rb join -d ./subs -f "*.srt" -s inferred -b 200 -o output.s
 - `-b, --buffer` - Buffer between files in milliseconds (default: 100)
 - `-L, --log-level` - Log level: none, info, detail
 
-**Note:** Internal module is called `SubtitleMaster` but CLI tool is `subtitle_manager`
+**Use cases:** Cleaning YouTube auto-captions, merging FliVideo multi-part recording subtitles
+
+**Note:** Renamed from `subtitle_manager` to `subtitle_processor` (accurate - processes files, doesn't manage state)
+
+#### 4. VAT - Video Asset Tools (`bin/vat`)
+Multi-tenant video project storage orchestration:
+
+```bash
+# List all brands
+vat list
+
+# List projects for a brand
+vat list appydave
+vat list appydave 'b6*'  # Pattern matching
+
+# Upload to S3 (collaboration)
+vat s3-up appydave b65
+vat s3-up voz boy-baker --dry-run
+
+# Download from S3
+vat s3-down appydave b65
+vat s3-down --dry-run  # Auto-detect from PWD
+
+# Check sync status
+vat s3-status appydave b65
+
+# Clean up S3
+vat s3-cleanup appydave b65 --force
 
-#### 4. Prompt Tools (`bin/prompt_tools.rb`)
-AI prompt completion workflows:
+# Archive to SSD
+vat archive appydave b63
+
+# Sync from SSD
+vat sync-ssd appydave
+```
+
+**Core Features:**
+- **Multi-tenant**: Manages 6 brands (appydave, voz, aitldr, kiros, joy, ss)
+- **Smart sync**: MD5-based file comparison (skips unchanged files)
+- **Pattern matching**: `'b6*'` expands to b60-b69 projects
+- **Short names**: `b65` → `b65-guy-monroe-marketing-plan` (FliVideo pattern)
+- **Auto-detection**: Detects brand/project from current directory
+- **Hybrid storage**: Local → S3 (90-day collaboration) → SSD (archive)
+
+**Brand Shortcuts:**
+- `appydave` → `v-appydave`
+- `voz` → `v-voz`
+- `aitldr` → `v-aitldr`
+- `kiros` → `v-kiros`
+- `joy` → `v-beauty-and-joy`
+- `ss` → `v-supportsignal`
+
+**Workflows:**
+- **FliVideo** (AppyDave): Sequential chapter recording, short name support (`b65`)
+- **Storyline** (VOZ, AITLDR): Script-first content, full project names (`boy-baker`)
+
+**Use cases:**
+- Collaborate on video edits with team (upload → edit → download)
+- Archive completed projects to external SSD
+- Quick project discovery across multiple brands
+- Manage 50GB+ video files with smart sync
+
+**Configuration:**
+- System: `video-projects-root` in `~/.config/appydave/settings.json` (**required**)
+- Per-brand: `.video-tools.env` (AWS credentials, S3 bucket, SSD path)
+
+**Migration note:** The old `~/.vat-config` file is deprecated. VAT now uses `settings.json`. See [Configuration Management](#configuration-management) section below.
+
+See detailed usage guide: [docs/usage/vat.md](./docs/usage/vat.md)
+
+#### 5. Prompt Tools (`bin/prompt_tools.rb`) ⚠️ DEPRECATED API
+OpenAI Completion API wrapper with template support:
 
 ```bash
-# Run AI prompt completion
-bin/prompt_tools.rb completion [options]
+# Run prompt from text
+bin/prompt_tools.rb completion -p "Your prompt" -o output.txt
+
+# Run prompt from file with placeholders
+bin/prompt_tools.rb completion -f template.md -k key1=value1,key2=value2 -c
 ```
 
-**Features:**
-- OpenAI GPT integration
-- Prompt execution and management
+**What it does:**
+- Sends prompts to OpenAI **Completion API** (older GPT-3 models like `davinci-codex`)
+- Supports template files with `{placeholder}` substitution
+- Outputs to file, clipboard, or stdout
 
-#### 5. YouTube Automation (`bin/youtube_automation.rb`)
-Automated YouTube workflows using GPT agents:
+**Status:** ⚠️ **Not in active use** - Uses **deprecated OpenAI Completion API**
+
+**Modern alternative:** Use ChatGPT/Claude directly or migrate to OpenAI Chat API
+
+**Potential use cases:** Template-based content generation (if migrated to Chat API)
+
+#### 5. YouTube Automation (`bin/youtube_automation.rb`) ⚠️ INTERNAL USE
+Prompt sequence runner for content workflows:
 
 ```bash
 # Run automation sequence
@@ -118,6 +240,21 @@ bin/youtube_automation.rb -s 01-1
 bin/youtube_automation.rb -s 01-1 -d  # with debug output
 ```
 
+**What it does:**
+- Loads sequence config from `~/.config/appydave/youtube_automation.json`
+- Reads prompt templates from Dropbox path (`_common/raw_prompts/`)
+- Executes OpenAI Completion API calls
+- Saves responses to output files
+
+**Requirements:**
+- Sequence definitions in JSON config
+- Prompt template files in configured Dropbox location
+- `OPENAI_ACCESS_TOKEN` environment variable
+
+**Status:** ⚠️ **Internal tool** - Hardcoded paths, deprecated API, not documented for external use
+
+**Relationship to Move Images:** These are separate tools - Move Images organizes downloaded images into video asset folders
+
 **Options:**
 - `-s, --sequence` - Sequence number (required, e.g., 01-1)
 - `-d, --debug` - Enable debug mode
@@ -140,9 +277,15 @@ bin/configuration.rb -e
 ```
 
 **Configuration Types:**
-- **settings** - General settings and paths
+- **settings** - General settings and paths (project folders: content, video, published, abandoned)
 - **channels** - YouTube channel definitions (code, name, youtube_handle)
-- **youtube_automation** - Automation workflow configurations
+- **youtube_automation** - Automation workflow configurations (prompt sequences)
+
+**Team Collaboration Features:**
+- **Shareable configs**: JSON files can be version-controlled (no secrets included)
+- **Per-developer paths**: Each team member customizes paths in their `~/.config/appydave/`
+- **Consistent structure**: Same channel codes/names across team
+- **Secrets separation**: API keys stored in `.env` files (gitignored), not in configs
 
 #### 7. Move Images (`bin/move_images.rb`)
 Organize and rename downloaded images into video project asset folders.
@@ -190,10 +333,12 @@ Bank transaction reconciliation tool - **DEPRECATED, DO NOT USE**
 ```bash
 rake spec           # Run all RSpec tests
 rake                # Default task: compile, spec (clobber compile spec)
-guard               # Watch files and auto-run tests + rubocop on changes
+RUBYOPT="-W0" guard # Watch files and auto-run tests + rubocop (suppress Ruby 3.4 warnings)
 bundle exec rspec -f doc  # Run tests with detailed documentation format
 ```
 
+**Note:** Ruby 3.4.2 shows platform constant warnings from Bundler. Use `RUBYOPT="-W0"` to suppress them.
+
 ### Linting & Style
 ```bash
 rubocop             # Run RubyGem style checks
@@ -210,12 +355,20 @@ gem build           # Build gemspec into .gem file
 
 ## Architecture Overview
 
-This is a Ruby gem called `appydave-tools` that provides YouTube automation and content creation tools.
+`appydave-tools` is AppyDave's consolidated productivity toolkit for YouTube content creation. Single-purpose utilities in one repository for easier maintenance than separate codebases.
+
+**Philosophy:** See [docs/purpose-and-philosophy.md](./docs/purpose-and-philosophy.md) for project philosophy and design principles.
+
+**Tool Categories:**
+- AI & Context Management (GPT Context, Prompt Tools)
+- Content & Media (Subtitles, YouTube Manager, YouTube Automation, Move Images)
+- Configuration (Multi-channel config management)
 
 ### Core Structure
 - **CLI Tools**: Multiple executable scripts in `bin/` for different functionalities
 - **Modular Design**: Organized into focused modules under `lib/appydave/tools/`
-- **Configuration System**: Flexible config management with channel and project settings
+- **Independent Operation**: Each tool solves a specific problem standalone
+- **Configuration System**: Flexible config management for multi-project workflows
 - **Type System**: Custom type classes for data validation and transformation
 
 ### Key Components
@@ -242,7 +395,7 @@ This is a Ruby gem called `appydave-tools` that provides YouTube automation and
 - Caption/subtitle management
 - Detailed reporting capabilities
 
-#### Subtitle Management (`lib/appydave/tools/subtitle_manager/`)
+#### Subtitle Management (`lib/appydave/tools/subtitle_processor/`)
 - SRT file cleaning and normalization
 - Multi-part subtitle joining
 - Timeline synchronization
@@ -281,94 +434,180 @@ This is a Ruby gem called `appydave-tools` that provides YouTube automation and
 ## Configuration Management
 
 ### Configuration Overview
-The gem uses JSON configuration files for managing YouTube channels, OpenAI settings, and automation workflows.
+The gem uses JSON configuration files for managing YouTube channels, settings, and automation workflows. All configuration files are stored in `~/.config/appydave/`.
 
-**Configuration Tool:** `bin/configuration.rb`
+**Configuration Tool:** `bin/configuration.rb` (installed as `ad_config`)
 
-### Setting Up Configuration
+**Complete configuration guide:** [docs/configuration/README.md](./docs/configuration/README.md)
 
-1. **List available configurations:**
-```bash
-bin/configuration.rb -l
-```
+### Quick Start
 
-2. **Create missing configuration files:**
+**First-time setup:**
 ```bash
+# Create empty configuration files (safe - won't overwrite existing files)
 bin/configuration.rb -c
+
+# Copy example files
+cp docs/configuration/settings.example.json ~/.config/appydave/settings.json
+cp docs/configuration/channels.example.json ~/.config/appydave/channels.json
+cp docs/configuration/.env.example .env
+
+# Edit your values
+bin/configuration.rb -e
 ```
 
-3. **View configuration values:**
+### Configuration Commands
+
 ```bash
+# List all configurations
+bin/configuration.rb -l
+
+# Create missing configuration files (safe - won't overwrite)
+bin/configuration.rb -c
+
+# View configuration values
 bin/configuration.rb -p settings,channels,youtube_automation
-```
 
-4. **Edit configurations in VS Code:**
-```bash
+# Edit configurations in VS Code
 bin/configuration.rb -e
 ```
 
 ### Configuration Types
 
-#### 1. Settings Config
-General application settings and paths.
+#### 1. Settings Config (`~/.config/appydave/settings.json`)
+General application settings and paths (non-secret configuration).
 
-**Typical structure:**
+**Structure:**
 ```json
 {
-  "project_paths": {
-    "content": "/path/to/content",
-    "video": "/path/to/video",
-    "published": "/path/to/published",
-    "abandoned": "/path/to/abandoned"
-  }
+  "video-projects-root": "/Users/yourname/dev/video-projects",
+  "ecamm-recording-folder": "/Users/yourname/ecamm",
+  "download-folder": "/Users/yourname/Downloads",
+  "download-image-folder": "/Users/yourname/Downloads/images"
 }
 ```
 
-#### 2. Channels Config
+**Key Settings:**
+
+| Key | Purpose | Used By | Required |
+|-----|---------|---------|----------|
+| `video-projects-root` | Root directory for all video projects | VAT commands | ✅ For VAT |
+| `ecamm-recording-folder` | Where Ecamm Live saves recordings | Move Images | Optional |
+| `download-folder` | General downloads directory | Move Images | Optional |
+| `download-image-folder` | Image downloads (defaults to `download-folder`) | Move Images | Optional |
+
+**Safe to:**
+- ✅ Version control (after removing personal paths)
+- ✅ Share with team (as template)
+- ✅ Commit to git (as `.example` file)
+
+#### 2. Channels Config (`~/.config/appydave/channels.json`)
 YouTube channel definitions for multi-channel management.
 
-**Typical structure:**
+**Structure:**
 ```json
 {
-  "channels": [
-    {
-      "code": "main",
-      "name": "Main Channel",
-      "youtube_handle": "@channelhandle"
+  "channels": {
+    "appydave": {
+      "code": "ad",
+      "name": "AppyDave",
+      "youtube_handle": "@appydave",
+      "locations": {
+        "content_projects": "/path/to/content",
+        "video_projects": "/Users/yourname/dev/video-projects/v-appydave",
+        "published_projects": "/path/to/published",
+        "abandoned_projects": "/path/to/abandoned"
+      }
     }
-  ]
+  }
 }
 ```
 
-#### 3. YouTube Automation Config
-Automation workflow configurations and sequences.
+**Channel Properties:**
 
-#### 4. OpenAI Config (via dotenv)
-OpenAI API integration settings managed through environment variables:
+| Property | Description | Example |
+|----------|-------------|---------|
+| `key` | Internal identifier (object key) | `"appydave"` |
+| `code` | Short code for project naming | `"ad"` |
+| `name` | Display name | `"AppyDave"` |
+| `youtube_handle` | YouTube @ handle | `"@appydave"` |
 
-```bash
-# .env file
-OPENAI_API_KEY=your_api_key_here
-```
+**Location Properties:**
+
+| Location | Purpose | Can Use "NOT-SET" |
+|----------|---------|-------------------|
+| `content_projects` | Content planning/scripts | ✅ Yes |
+| `video_projects` | Active video projects | ❌ No (required) |
+| `published_projects` | Published video archives | ✅ Yes |
+| `abandoned_projects` | Abandoned projects | ✅ Yes |
+
+Use `"NOT-SET"` as a placeholder for unconfigured locations.
 
-### Configuration Locations
-Configuration files are typically stored in:
-- `~/.config/appydave-tools/` (user-level)
-- Or project-specific locations as defined in settings
+**Safe to:**
+- ✅ Version control structure (remove personal paths first)
+- ⚠️ Each developer customizes paths locally
+- ✅ Share channel definitions (codes, names, handles)
 
-### Environment Variables
-The gem uses `dotenv` for environment variable management. Create a `.env` file in your project root:
+#### 3. YouTube Automation Config (`~/.config/appydave/youtube_automation.json`)
+Automation workflow configurations and sequences (internal use).
+
+#### 4. Environment Variables (`.env` file - project root)
+**⚠️ CRITICAL: Secrets and API keys stored here, NEVER commit to version control!**
 
 ```bash
-# Required for YouTube API
-GOOGLE_CLIENT_ID=your_client_id
-GOOGLE_CLIENT_SECRET=your_client_secret
+# OpenAI API Configuration (required for prompt_tools and youtube_automation)
+# Get your API key from: https://platform.openai.com/api-keys
+OPENAI_ACCESS_TOKEN=sk-your-actual-api-key-here
+OPENAI_ORGANIZATION_ID=org-your-actual-org-id
 
-# Required for OpenAI features
-OPENAI_API_KEY=your_openai_api_key
+# Enable OpenAI tools (set to 'true' to enable)
+TOOLS_ENABLED=false
 ```
 
-**IMPORTANT:** Never commit `.env` files to version control. Ensure `.env` is in your `.gitignore`.
+**Environment Variables:**
+
+| Variable | Purpose | Required For | Secret? |
+|----------|---------|--------------|---------|
+| `OPENAI_ACCESS_TOKEN` | OpenAI API key | prompt_tools, youtube_automation | ✅ SECRET |
+| `OPENAI_ORGANIZATION_ID` | OpenAI org ID | prompt_tools, youtube_automation | ✅ SECRET |
+| `TOOLS_ENABLED` | Enable OpenAI configuration | Optional | ❌ No |
+
+**Safe to:**
+- ❌ **NEVER** version control
+- ❌ **NEVER** share
+- ❌ **NEVER** commit to git
+- ✅ Keep local only
+- ✅ Share `.env.example` template
+
+### Safety Features
+
+**Automatic Backups:**
+- Every config save creates timestamped backup: `filename.backup.YYYYMMDD-HHMMSS`
+- Backups stored alongside config files in `~/.config/appydave/`
+- Restore from backup: `cp settings.json.backup.20251109-203015 settings.json`
+
+**Safe Configuration Creation:**
+- `ad_config -c` only creates missing files, never overwrites existing ones
+- Prevents accidental data loss from running setup commands
+
+**Secrets Separation:**
+- API keys stored in `.env` files (gitignored), not in JSON configs
+- Configuration files can be safely version-controlled (after removing personal paths)
+
+### Migration from Legacy Config
+
+**From `~/.vat-config` (DEPRECATED):**
+
+The old `~/.vat-config` file is no longer used. VAT now uses `settings.json`.
+
+**Migration steps:**
+1. Check your old config: `cat ~/.vat-config`
+2. Add value to settings.json: `ad_config -e`
+3. Add: `"video-projects-root": "/your/path/from/vat/config"`
+4. Test VAT still works: `vat list`
+5. Delete old file: `rm ~/.vat-config`
+
+**Note:** The `vat init` command is deprecated. Use `ad_config -c` instead.
 
 ## Git Hooks & Security