appydave-tools 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfc47ae2c891b47ff973f7f5605c18f0d05f98f44045c7b40590d03d63fdf276
-  data.tar.gz: cd97470ff0937e41972b1777eabaaaf2da3321e2f0a8d1cd6845125b8a15d705
+  metadata.gz: '0819e2db66666e4729144ba1a8dac0032a5b323f4475f9cdc84459aa9309cd49'
+  data.tar.gz: ce1185ecbf19793175fa91f4a5c3e401df36394349ec454c7c47fa38e2193727
 SHA512:
-  metadata.gz: c2ce45fd490af1172db2e274e733fdb329d9ef143078ada86f90aadc1cc4860bdde91c4ca19cf781dffd128de909118271ce9087657edfd6a7ad98c38ba68b94
-  data.tar.gz: 931ca82db8f193bb2b6f581d1691893ac8912949d37384d1a7f2baea35cf7fc90343c2234a259f73f69489a9405bd07c984699c0dc7716416103c65b9e8406bf
+  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,15 @@
+# [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)
 
 

data/CLAUDE.md

@@ -60,6 +60,7 @@ bin/console         # Interactive Ruby console for experimentation
 | **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 |
@@ -142,7 +143,73 @@ bin/subtitle_processor.rb join -d ./subs -f "*.srt" -s inferred -b 200 -o output
 
 **Note:** Renamed from `subtitle_manager` to `subtitle_processor` (accurate - processes files, doesn't manage state)
 
-#### 4. Prompt Tools (`bin/prompt_tools.rb`) ⚠️ DEPRECATED API
+#### 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
+
+# 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
@@ -266,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
@@ -365,94 +434,180 @@ gem build           # Build gemspec into .gem file
 ## 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:**
 
-### Configuration Locations
-Configuration files are typically stored in:
-- `~/.config/appydave-tools/` (user-level)
-- Or project-specific locations as defined in settings
+| 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 |
 
-### Environment Variables
-The gem uses `dotenv` for environment variable management. Create a `.env` file in your project root:
+Use `"NOT-SET"` as a placeholder for unconfigured locations.
+
+**Safe to:**
+- ✅ Version control structure (remove personal paths first)
+- ⚠️ Each developer customizes paths locally
+- ✅ Share channel definitions (codes, names, handles)
+
+#### 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
 

data/README.md

@@ -12,6 +12,7 @@ Instead of managing dozens of separate repositories, everything lives here - one
 - 🤖 Feed entire codebases to AI assistants in seconds
 - 📹 Batch update YouTube video metadata without clicking through the UI (update 50 videos in 5 minutes)
 - 📝 Process subtitle files - clean formatting, merge multi-part recordings, synchronize timelines
+- 🎬 Manage video projects across local/S3/SSD storage with smart sync (collaborate on 50GB+ projects)
 - 🖼️ Organize downloaded images into project folders automatically (video asset workflow)
 - ⚙️ Manage multi-channel configurations from the command line (team-shareable JSON configs)
 
@@ -27,6 +28,62 @@ Or add to your Gemfile:
 gem 'appydave-tools'
 ```
 
+## Quick Start: Configuration
+
+Most tools work out of the box, but some features (VAT, YouTube Manager, OpenAI tools) require configuration.
+
+### First-Time Setup
+
+**1. Create configuration files:**
+
+```bash
+ad_config -c
+```
+
+This creates empty configuration files at `~/.config/appydave/`:
+- `settings.json` - Paths and preferences
+- `channels.json` - YouTube channel definitions
+- `youtube-automation.json` - Automation workflows
+
+**2. Option A: Copy example files**
+
+```bash
+# Copy examples to your config directory
+cp docs/configuration/settings.example.json ~/.config/appydave/settings.json
+cp docs/configuration/channels.example.json ~/.config/appydave/channels.json
+
+# Copy .env to project root (for API keys)
+cp docs/configuration/.env.example .env
+```
+
+Then edit each file and replace placeholders with your actual values.
+
+**2. Option B: Edit directly in VS Code**
+
+```bash
+ad_config -e
+```
+
+Opens `~/.config/appydave/` for editing.
+
+**3. Add your values**
+
+Update the configuration files with your specific paths and settings.
+
+**Required for VAT (Video Asset Tools):**
+```json
+{
+  "video-projects-root": "/path/to/your/video-projects"
+}
+```
+
+**Required for OpenAI tools:**
+```bash
+OPENAI_ACCESS_TOKEN=sk-your-actual-api-key
+```
+
+**Full configuration guide:** [docs/configuration/README.md](./docs/configuration/README.md)
+
 ## The Tools
 
 ### 🤖 GPT Context Gatherer
@@ -124,6 +181,56 @@ subtitle_processor join -f "part1.srt,part2.srt" -b 200 -o merged.srt
 
 ---
 
+### 🎬 VAT (Video Asset Tools)
+
+**The problem:** Managing large video files across local storage, cloud collaboration (S3), and archival storage (SSD) is complex and error-prone.
+
+**The solution:** Unified CLI for multi-tenant video project management with smart sync, pattern matching, and workflow automation.
+
+```bash
+# List all brands
+vat list
+
+# List projects for AppyDave brand
+vat list appydave
+
+# Upload files to S3 for collaboration
+vat s3-up appydave b65
+
+# Download collaborator's edits from S3
+vat s3-down appydave b65
+
+# Check sync status
+vat s3-status appydave b65
+
+# Clean up S3 after project completion
+vat s3-cleanup appydave b65 --force
+```
+
+**Configuration required:** Add `video-projects-root` to `settings.json` (see [Quick Start](#quick-start-configuration) above).
+
+**Key Features:**
+- **Multi-tenant**: Manages 6 brands (appydave, voz, aitldr, kiros, joy, ss)
+- **Smart sync**: MD5-based file comparison (skip unchanged files)
+- **Pattern matching**: `vat list appydave 'b6*'` (lists b60-b69)
+- **Short names**: `b65` → `b65-guy-monroe-marketing-plan` (FliVideo workflow)
+- **Auto-detection**: Run commands from project directory without args
+- **Hybrid storage**: Local → S3 (collaboration) → SSD (archive)
+
+**Workflows:**
+- **FliVideo** (AppyDave): Sequential chapter-based recording with short name support
+- **Storyline** (VOZ, AITLDR): Script-first narrative content with full project names
+
+**Use cases:**
+- Collaborate on video edits with team members via S3
+- Archive completed projects to external SSD
+- Manage video assets across multiple brands/clients
+- Quick project discovery with pattern matching
+
+[Full documentation →](./docs/usage/vat.md)
+
+---
+
 ### 🎯 Prompt Tools *(Experimental - Not actively used)*
 
 **The problem:** Running OpenAI prompts with placeholder substitution and output management.
@@ -200,7 +307,7 @@ youtube_automation -s 01-1 -d
 # List all configurations
 ad_config -l
 
-# Create missing config files with templates
+# Create missing config files (safe - won't overwrite existing files)
 ad_config -c
 
 # Edit configurations in VS Code
@@ -214,21 +321,47 @@ ad_config -p
 ```
 
 **What it manages:**
-- **settings.json**: Project folder paths (content, video, published, abandoned)
-- **channels.json**: YouTube channel definitions (code, name, youtube_handle)
-- **youtube_automation.json**: Automation sequence configurations
+
+| File | Purpose | Safe to Version Control? |
+|------|---------|-------------------------|
+| `settings.json` | Paths and preferences (video-projects-root, download folders, etc.) | ✅ Yes (after removing personal paths) |
+| `channels.json` | YouTube channel definitions (code, name, youtube_handle, locations) | ✅ Yes (share structure, customize paths locally) |
+| `youtube_automation.json` | Automation workflow configurations | ✅ Yes (if no sensitive data) |
+| `.env` | **Secrets and API keys** | ❌ **NEVER** (gitignored) |
+
+**Key Settings:**
+
+- **video-projects-root** - Root directory for all video projects (required for VAT)
+- **ecamm-recording-folder** - Where Ecamm Live saves recordings
+- **download-folder** - General downloads directory
+- **download-image-folder** - Image downloads (defaults to download-folder)
+
+**Channel Configuration:**
+
+Each channel defines:
+- **code** - Short code for project naming (e.g., "ad" for AppyDave)
+- **name** - Display name
+- **youtube_handle** - YouTube @ handle
+- **locations** - Four project location types:
+  - `content_projects` - Content planning/scripts
+  - `video_projects` - Active video projects (**required**)
+  - `published_projects` - Published video archives
+  - `abandoned_projects` - Abandoned projects
+
+Use `"NOT-SET"` as a placeholder for unconfigured locations.
 
 **Use cases:**
 - **Multi-channel management**: Switch between different YouTube channels
-- **Team collaboration**: Share configuration files via Git/Dropbox (excluding secrets)
-- **Workflow standardization**: Consistent paths across team members
+- **Team collaboration**: Share configuration structure via Git (each developer customizes paths)
+- **Workflow standardization**: Consistent channel codes/names across team
 - **Automation setup**: Define reusable prompt sequences
 
-**Team collaboration notes:**
-- Configuration files can be version-controlled (they contain no secrets)
-- Each team member can maintain their own `~/.config/appydave/` directory
-- Paths can be customized per developer machine
-- Secrets (API keys) stored separately in `.env` files (gitignored)
+**Safety Features:**
+- **Automatic backups**: Every config save creates timestamped backup (`.backup.YYYYMMDD-HHMMSS`)
+- **Safe creation**: `ad_config -c` only creates missing files, never overwrites existing ones
+- **Secrets separation**: API keys stored in `.env` files (gitignored), not in configs
+
+**Full configuration guide:** [docs/configuration/README.md](./docs/configuration/README.md)
 
 ---