appydave-tools 0.15.0 → 0.17.0

data/docs/configuration/README.md

@@ -0,0 +1,394 @@
+# AppyDave Tools Configuration Guide
+
+This guide explains how to configure AppyDave Tools for your environment.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Configuration Files](#configuration-files)
+  - [settings.json](#settingsjson)
+  - [channels.json](#channelsjson)
+  - [.env](#env)
+- [Configuration Commands](#configuration-commands)
+- [Migration from Legacy Config](#migration-from-legacy-config)
+
+---
+
+## Quick Start
+
+### 1. Create Default 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
+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/` in VS Code 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
+```
+
+---
+
+## Configuration Files
+
+### `settings.json`
+
+**Location:** `~/.config/appydave/settings.json`
+
+**Purpose:** Stores paths and preferences (non-secret configuration)
+
+**Example:**
+```json
+{
+  "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"
+}
+```
+
+**Settings Reference:**
+
+| 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)
+
+---
+
+### `channels.json`
+
+**Location:** `~/.config/appydave/channels.json`
+
+**Purpose:** Defines YouTube channels and their project locations
+
+**Example:**
+```json
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
+**Channel Properties:**
+
+| 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"` |
+
+**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 |
+
+**Using "NOT-SET":**
+
+If you don't have a location configured yet, use `"NOT-SET"` as a placeholder:
+
+```json
+"content_projects": "NOT-SET"
+```
+
+This makes it clear that the value needs to be configured later.
+
+**Safe to:**
+- ✅ Version control structure (remove personal paths first)
+- ⚠️  Each developer customizes paths locally
+- ✅ Share channel definitions (codes, names, handles)
+
+---
+
+### `.env`
+
+**Location:** `.env` (project root directory)
+
+**Purpose:** Stores secrets and API keys
+
+**⚠️ CRITICAL: This file is gitignored and should NEVER be committed!**
+
+**Example:**
+```bash
+# OpenAI API Configuration
+OPENAI_ACCESS_TOKEN=sk-your-actual-api-key-here
+OPENAI_ORGANIZATION_ID=org-your-actual-org-id
+
+# Optional: Enable OpenAI tools
+TOOLS_ENABLED=true
+```
+
+**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 |
+
+**Getting API Keys:**
+- OpenAI: https://platform.openai.com/api-keys
+
+**Safe to:**
+- ❌ NEVER version control
+- ❌ NEVER share
+- ❌ NEVER commit to git
+- ✅ Keep local only
+- ✅ Share `.env.example` template
+
+---
+
+## Configuration Commands
+
+### List All Configurations
+
+```bash
+ad_config -l
+```
+
+Shows which configuration files exist and their paths.
+
+**Example Output:**
+```
+NAME               | EXISTS | PATH
+-------------------|--------|------------------------------------------------------------
+settings           | true   | /Users/yourname/.config/appydave/settings.json
+channels           | true   | /Users/yourname/.config/appydave/channels.json
+youtube_automation | true   | /Users/yourname/.config/appydave/youtube-automation.json
+```
+
+### Create Missing Configurations
+
+```bash
+ad_config -c
+```
+
+Creates any configuration files that don't exist yet.
+
+**Safety:** This command will NOT overwrite existing files. It only creates missing ones.
+
+### Print Configuration Values
+
+```bash
+# Print all configurations
+ad_config -p
+
+# Print specific configurations
+ad_config -p settings
+ad_config -p channels
+ad_config -p settings,channels
+```
+
+Shows the current values in your configuration files.
+
+### Edit in VS Code
+
+```bash
+ad_config -e
+```
+
+Opens the configuration directory (`~/.config/appydave/`) in Visual Studio Code.
+
+---
+
+## Migration from Legacy Config
+
+### From `~/.vat-config` (Deprecated)
+
+If you have an old `~/.vat-config` file, migrate to `settings.json`:
+
+**Old format** (`~/.vat-config`):
+```
+VIDEO_PROJECTS_ROOT=/Users/yourname/dev/video-projects
+```
+
+**New format** (`~/.config/appydave/settings.json`):
+```json
+{
+  "video-projects-root": "/Users/yourname/dev/video-projects"
+}
+```
+
+**Migration steps:**
+
+1. Check your current VAT config:
+   ```bash
+   cat ~/.vat-config
+   ```
+
+2. Add the value to settings.json:
+   ```bash
+   ad_config -e
+   ```
+
+3. In `settings.json`, add:
+   ```json
+   "video-projects-root": "/your/path/from/vat/config"
+   ```
+
+4. Test that VAT still works:
+   ```bash
+   vat list
+   ```
+
+5. Delete the old file:
+   ```bash
+   rm ~/.vat-config
+   ```
+
+**Note:** The `vat init` command is deprecated. Use `ad_config` instead.
+
+---
+
+## Backup & Recovery
+
+### Automatic Backups
+
+Every time you save a configuration, a timestamped backup is created automatically:
+
+```
+~/.config/appydave/settings.json.backup.20251109-203015
+```
+
+**Backup format:** `filename.backup.YYYYMMDD-HHMMSS`
+
+### Restoring from Backup
+
+```bash
+# List available backups
+ls -la ~/.config/appydave/*.backup.*
+
+# Restore from backup
+cp ~/.config/appydave/settings.json.backup.20251109-203015 \
+   ~/.config/appydave/settings.json
+```
+
+---
+
+## Troubleshooting
+
+### "VIDEO_PROJECTS_ROOT not configured" Error
+
+**Problem:** VAT commands fail with configuration error.
+
+**Solution:**
+```bash
+ad_config -e
+```
+
+Add to `settings.json`:
+```json
+{
+  "video-projects-root": "/path/to/your/video-projects"
+}
+```
+
+### Configuration Files Missing
+
+**Problem:** Configuration files don't exist.
+
+**Solution:**
+```bash
+ad_config -c
+```
+
+This creates default empty configuration files.
+
+### OpenAI API Errors
+
+**Problem:** "OpenAI API key not configured"
+
+**Solution:**
+
+1. Create `.env` file in project root:
+   ```bash
+   cp docs/configuration/.env.example .env
+   ```
+
+2. Add your API key:
+   ```bash
+   OPENAI_ACCESS_TOKEN=sk-your-actual-key
+   OPENAI_ORGANIZATION_ID=org-your-org-id
+   TOOLS_ENABLED=true
+   ```
+
+3. Never commit `.env` to git (it's gitignored by default)
+
+---
+
+## Best Practices
+
+1. **Use `ad_config -c` for initialization** - It's safe and won't overwrite existing files
+2. **Use "NOT-SET" for unconfigured paths** - Makes it clear what needs to be set
+3. **Keep secrets in `.env`** - Never put API keys in `settings.json`
+4. **Backup before major changes** - Automatic backups are created, but you can manually backup too
+5. **Use `ad_config -p` to verify** - Check your configuration values are correct
+6. **Share examples, not actual configs** - Use `.example` files for team sharing
+
+---
+
+## Need Help?
+
+- Check CLAUDE.md for project-specific configuration
+- Run `ad_config --help` for command options
+- See example files in `docs/configuration/`

data/docs/configuration/channels.example.json

@@ -0,0 +1,26 @@
+{
+  "channels": {
+    "your-channel-key": {
+      "code": "yc",
+      "name": "Your Channel Name",
+      "youtube_handle": "@yourhandle",
+      "locations": {
+        "content_projects": "/path/to/content/projects",
+        "video_projects": "/path/to/video/projects",
+        "published_projects": "/path/to/published/projects",
+        "abandoned_projects": "/path/to/abandoned/projects"
+      }
+    },
+    "second-channel": {
+      "code": "sc",
+      "name": "Second Channel",
+      "youtube_handle": "@secondchannel",
+      "locations": {
+        "content_projects": "NOT-SET",
+        "video_projects": "/path/to/video-projects/v-second-channel",
+        "published_projects": "NOT-SET",
+        "abandoned_projects": "NOT-SET"
+      }
+    }
+  }
+}

data/docs/configuration/settings.example.json

@@ -0,0 +1,6 @@
+{
+  "video-projects-root": "/Users/YOUR_USERNAME/dev/video-projects",
+  "ecamm-recording-folder": "/Users/YOUR_USERNAME/ecamm",
+  "download-folder": "/Users/YOUR_USERNAME/Downloads",
+  "download-image-folder": "/Users/YOUR_USERNAME/Downloads/images"
+}

data/docs/development/CODEX-recommendations.md

@@ -0,0 +1,123 @@
+# CODEX Recommendations
+
+> Last updated: 2025-11-09 13:36:08 UTC  
+> Maintenance note: whenever files outside this document change, review them and reflect any new patterns/risks here so the recommendations stay authoritative.
+
+Guide created by Codex (GPT-5) to capture near-term cleanups and deeper refactors that will make `appydave-tools` easier to extend and test.
+
+## Snapshot
+
+- **Primary friction**: global configuration access makes VAT objects hard to test, forcing `allow_any_instance_of` overrides in specs such as `spec/appydave/tools/vat/config_spec.rb:6`.
+- **Secondary friction**: command classes mix terminal IO with core logic (see `lib/appydave/tools/vat/project_resolver.rb:19-50`), which complicates automation and reuse.
+- **Tooling debt**: RuboCop is configured (`.rubocop.yml`) but not enforced; the current run emits 108 offenses (93 auto-correctable per Claude logs) and engineers silence cops instead of resolving root causes.
+
+## Priority Map
+
+| Order | Theme | Why it matters |
+| --- | --- | --- |
+| P0 | Make configuration/services injectable | Unlocks clean tests, eliminates global stubs, and keeps future CLIs composable. |
+| P1 | Re-enable effective lint/test automation | 93 auto-fixes are “free”; the remaining 15 surface real architecture problems that deserve explicit debt tracking. |
+| P2 | Separate IO from business logic in CLI helpers | Enables automation agents (Claude) and humans to reuse services without TTY prompts. |
+| P3 | Standardize filesystem fixtures | Reduces the bespoke `Dir.mktmpdir` + `FileUtils` boilerplate sprinkled through VAT specs; faster, safer tests. |
+
+## Detailed Recommendations
+
+### 1. Introduce configuration adapters
+
+- **Problem**: `Appydave::Tools::Vat::Config.projects_root` reaches directly into `Configuration::Config.settings` (`lib/appydave/tools/vat/config.rb:13-21`), so specs must stub *every* `SettingsConfig` instance (`spec/appydave/tools/vat/config_spec.rb:14`).  
+- **Action**:
+  1. Create a lightweight `SettingsProvider` (duck-typed or interface module) that exposes `video_projects_root`.
+  2. Update VAT entry points to accept `settings:` or `config:` keyword args defaulting to the singleton, e.g. `def projects_root(settings: default_settings)`.
+  3. Provide a `Config.with_settings(temp_settings) { ... }` helper for specs and CLI overrides.
+- **Impact**: RSpec can inject fakes without `allow_any_instance_of`; RuboCop warning disappears with no cop disable required.
+
+### 2. Capture the remaining RuboCop debt deliberately
+
+- **Problem**: Engineers currently choose between “ignore 108 offenses” or “disable cops,” which erodes lint value. `.rubocop.yml` already sets generous limits (200-char lines, spec exclusions), so remaining issues are meaningful.
+- **Action plan**:
+  1. Run `bundle exec rubocop --auto-correct` and commit format-only fixes (expect ~93 files touched).
+  2. For the 15 blocking offenses, open a short-lived spreadsheet (or GH issue tracker) that records *cop → file → fix owner*. This keeps the queue visible without blocking merges.
+  3. Add a CI step (GitHub Action or Circle job) that executes `bundle exec rubocop` plus `bundle exec rake spec`, failing PRs that reintroduce offenses.
+- **Fallback**: If any `allow_any_instance_of` remains after Step 1, convert it to the adapter pattern described above; avoid new `rubocop:disable` directives unless there’s a written justification beside them.
+
+### 3. Decouple terminal IO from VAT services
+
+- **Problem**: `ProjectResolver.resolve` blends filesystem globbing with interactive prompts (`puts`/`$stdin.gets`, `lib/appydave/tools/vat/project_resolver.rb:41-48`). These prompts block automation agents, and the logic cannot be reused inside other CLIs or tests without stubbing global IO.
+- **Action**:
+  1. Extract the pure resolution logic so it always returns a result set (possibly multi-match) and never prints.
+  2. Create an `InteractiveResolver` (or CLI layer) that takes `io_in:`/`io_out:` and handles messaging/selection.
+  3. Update `bin/vat` commands to use the interactive wrapper; specs can cover both the pure resolver and the IO adapter with deterministic streams.
+- **Bonus**: While refactoring, move the repeated `Dir.glob` filtering into a shared helper (e.g., `Projects::Scanner`) so CLAUDE/Code agents can reuse it for listing commands.
+
+### 4. Standardize filesystem fixtures
+
+- **Observation**: VAT specs repeatedly open temp dirs, `mkdir_p` brand/project skeletons, and remember to clean up (see blocks at `spec/appydave/tools/vat/config_spec.rb:22-178` and `spec/appydave/tools/vat/project_resolver_spec.rb:9-70`). Minor mistakes (missing cleanup, duplicated brand shortcuts) cause flaky tests locally.
+- **Action**:
+  1. Add `spec/support/filesystem_helpers.rb` with helpers like `with_projects_root(brands: %w[appydave]) { |root| ... }`.
+  2. Include the helper in `spec/spec_helper.rb`, then convert VAT specs to the helper to remove boilerplate and centralize cleanup.
+  3. Consider shipping seeded sample trees under `spec/samples/video-projects` for regression-style tests that need deeper structures.
+
+### 5. Harden `Configuration::Config`
+
+- **Problem**: `Configuration::Config` uses `method_missing` to expose registered configs (`lib/appydave/tools/configuration/config.rb:31-39`), which hides failures until runtime and complicates auto-complete.
+- **Action**:
+  1. Replace `method_missing` with explicit reader methods or `Forwardable`, or at minimum raise descriptive errors that list the registered keys (`configurations.keys`).
+  2. Expose a `fetch(:settings)` API that returns nil-friendly values for easier dependency injection.
+  3. Document the registration flow in `docs/development/cli-architecture-patterns.md` so new tools follow the same adapter approach.
+
+### 6. Bake the plan into docs & automation
+
+- Add a **Claude Impact** note whenever a CLI behavior changes (per `AGENTS.md`), and link back to this file so the agent knows why tests may require new prompts.
+- Create a short checklist in `docs/development/README.md` (“Before merging VAT changes: run rubocop, run VAT specs, update configuration adapters”) to keep the recommendations visible.
+
+## Architecture-Wide Opportunities
+
+### CLI boundaries & shared ergonomics
+
+- `bin/gpt_context.rb:15-88` hand-rolls its `OptionParser` setup even though `lib/appydave/tools/cli_actions/base_action.rb:8-44` already codifies a reusable CLI contract. Promote `BaseAction` to the default entrypoint for every CLI (gpt_context, prompt_tools, subtitle_processor, Ito/AI-TLDR helpers) so options, `-h`, and validation logic stay consistent.  
+- Extract a `Cli::Runner` that discovers actions via naming (`Appydave::Tools::<Tool>::Cli::<Command>`) and wire it into each `bin/*` – this keeps future tools (Hey Ito, BMAD, etc.) aligned without duplicating boilerplate.  
+- Add smoke specs that exercise each executable via `CLIHelpers.run('bin/gpt_context.rb --help')` to catch option regressions and ensure Guard/Claude can rely on deterministic output.
+
+### GptContext as a reusable service
+
+- `lib/appydave/tools/gpt_context/file_collector.rb:12-77` mutates global process state with `FileUtils.cd` and prints the working directory from inside the constructor. Replace this with `Dir.chdir(working_dir) { … }` blocks and pass a logger so the class can run quietly when invoked programmatically.  
+- The collector silently reads every match into memory; for large worktrees (Ito + AppyDave), the CLI will thrash. Consider yielding per-file chunks to a stream-aware `OutputHandler` so future AI agents can request incremental context.  
+- Normalize include/exclude matching by compiling glob patterns once (e.g., using `File::FNM_EXTGLOB`) to avoid repeated `Dir.glob` passes, and consider exposing a dry-run mode that returns candidate file lists for Claude prompt generation.
+
+### Subtitle pipeline robustness
+
+- `lib/appydave/tools/subtitle_processor/clean.rb:9-95` combines parsing, normalization, and IO side-effects. Break this into (1) a pure parser that operates on enumerables, (2) a formatter that emits SRT or VTT, and (3) a CLI wrapper for file IO. Doing so makes it easier to add BMAD-specific filters (emoji stripping, custom timelines) without forking the entire class.  
+- Add quick fuzz tests that feed malformed SRT snippets to ensure the parser fails fast instead of silently swallowing lines.  
+- Document the workflow in `docs/tools/subtitle_processor.md` (currently absent) so collaborators understand how to integrate Hey Ito or AI-TLDR narration scripts.
+
+### YouTube automation hardening
+
+- `lib/appydave/tools/youtube_manager/youtube_base.rb:8-17` constructs a Google API client on every command invocation. Cache the service in a memoized factory or inject it so tests can supply a fake client.  
+- `lib/appydave/tools/youtube_manager/authorization.rb:9-54` shells out a WEBrick server and prints instructions; wrap this interaction in a strategy object so Claude can be told “launch headless auth” versus “prompt operator David Cruwys.”  
+- Build retries and quota awareness around `@service.update_video` (`lib/appydave/tools/youtube_manager/update_video.rb:31-43`) so Ito/BMAD batch jobs can recover from `Google::Apis::RateLimitError` instead of crashing half-way through.
+
+### Configuration & type safety
+
+- `lib/appydave/tools/types/base_model.rb` + siblings provide a mini ActiveModel alternative but many tools now depend directly on `ActiveModel` (see `appydave-tools.gemspec:28-34`). Decide whether to lean fully into ActiveModel validations (Ruby 3-ready) or keep the custom types. If the latter, add coercion specs to lock down behavior for indifferent hashes (useful for AI ingestion).  
+- Expose typed settings objects per feature (`VatSettings`, `YoutubeSettings`) that wrap `SettingsConfig` so each CLI only sees the keys it needs. This makes future schema evolution (e.g., extra Ito endpoints) less risky.
+
+### Testing & observability
+
+- `spec/spec_helper.rb:5-41` always bootstraps SimpleCov/WebMock, which slows down iterative TDD. Guard these with ENV flags (`COVERAGE=true`, `ALLOW_NET=true`) so developers can opt into faster loops when needed.  
+- Add contract tests for each CLI that ensure stdout/stderr remain machine-readable—critical for Claude pipelines documented in `CLAUDE.md`. Snapshot testing (via `rspec-snapshot`) works well for command help text.  
+- Extend logging: `k_log` is only used inside configuration; wire it into VAT, GPT Context, and YouTube workflows so all tools share the same structured logging style. Include context like `brand=appydave` or `persona=Hey Ito` to help when multiple personas (Ito, AI-TLDR, AppyDave, BMAD) run jobs concurrently.
+
+### Platform & dependency strategy
+
+- `appydave-tools.gemspec:11-37` still declares `required_ruby_version >= 2.7`, but dependencies such as `activemodel ~> 8` and `google-api-client` are already Ruby 3-first. Move the baseline to Ruby 3.2 (or 3.3) so pattern matching, numbered parameters, and improved GC become available.  
+- Once on Ruby 3.2+, enable YJIT in local scripts (document via `docs/development/README.md`) to speed up large jobs like GPT context scans.  
+- Create a `Dependabot` (or Renovate) config so gem bumps don’t surprise automation—Ito and Hey Ito will benefit from predictable upgrade cadences. Pair this with a changelog checklist entry reminding you to note **Claude Impact** when APIs change.
+
+## Suggested Next Steps
+
+1. **Week 1**: Implement the configuration adapter + filesystem helper, convert VAT specs, and remove the `RSpec/AnyInstance` disable comment.
+2. **Week 2**: Run RuboCop auto-correct, triage the residual offenses, and wire RuboCop/spec runs into CI.
+3. **Week 3**: Refactor `ProjectResolver` IO separation and document the new contract for CLI callers.
+4. **Week 4**: Revisit other CLIs (`youtube_manager`, `subtitle_processor`) and apply the same adapter/IO patterns once VAT proves the approach.
+
+Ping Codex if you’d like guidance on scoping or sequencing—happy to help break these down into actionable tickets.

data/docs/development/README.md

@@ -0,0 +1,100 @@
+# Development Documentation
+
+This directory contains comprehensive guides for developing and extending appydave-tools.
+
+## Quick Links
+
+### Architecture Guides
+- [CLI Architecture Patterns](./cli-architecture-patterns.md) - **START HERE** when creating new tools
+
+## Quick Pattern Selection
+
+When creating a new CLI tool, use this quick reference:
+
+### Single Operation Tool → Pattern 1
+**Use when:** Tool performs ONE operation with various options
+
+**Examples:** `gpt_context`, `move_images`
+
+**Key files:**
+```
+bin/tool_name.rb                    # CLI executable
+lib/appydave/tools/tool_name/
+  ├── options.rb                    # Options struct
+  └── main_logic.rb                 # Business logic
+```
+
+**Read:** [Pattern 1 Details](./cli-architecture-patterns.md#pattern-1-single-command-tools)
+
+---
+
+### 2-5 Commands → Pattern 2
+**Use when:** Tool has 2-5 related commands with simple routing
+
+**Examples:** `subtitle_processor`, `configuration`
+
+**Key files:**
+```
+bin/tool_name.rb                    # CLI with inline routing
+lib/appydave/tools/tool_name/
+  ├── command_one.rb                # Command implementation
+  └── command_two.rb                # Command implementation
+```
+
+**Read:** [Pattern 2 Details](./cli-architecture-patterns.md#pattern-2-multi-command-with-inline-routing)
+
+---
+
+### 6+ Commands or Shared Patterns → Pattern 3
+**Use when:** Tool has many commands OR commands share validation/execution patterns
+
+**Examples:** `youtube_manager`
+
+**Key files:**
+```
+bin/tool_name.rb                    # CLI with BaseAction routing
+lib/appydave/tools/
+  ├── cli_actions/
+  │   ├── base_action.rb            # Shared base (already exists)
+  │   ├── tool_cmd_one_action.rb    # Command as Action class
+  │   └── tool_cmd_two_action.rb
+  └── tool_name/
+      └── service.rb                # Business logic
+```
+
+**Read:** [Pattern 3 Details](./cli-architecture-patterns.md#pattern-3-multi-command-with-baseaction)
+
+---
+
+## Common Tasks
+
+### Adding a New Tool
+1. Choose pattern using [Decision Tree](./cli-architecture-patterns.md#decision-tree)
+2. Follow [Migration Guide](./cli-architecture-patterns.md#migration-guide)
+3. Register in `appydave-tools.gemspec`
+4. Document in `CLAUDE.md`
+
+### Understanding Existing Code
+- See [Directory Structure](./cli-architecture-patterns.md#directory-structure)
+- Review [Best Practices](./cli-architecture-patterns.md#best-practices)
+
+### Writing Tests
+- Read [Testing Approach](./cli-architecture-patterns.md#testing-approach)
+- No `require` statements in specs (handled by `spec_helper`)
+- Test business logic, not CLI executables
+
+---
+
+## Philosophy
+
+AppyDave Tools follows a **consolidated toolkit philosophy**:
+- Multiple independent tools in one repository
+- Each tool solves one specific problem
+- Clear separation between CLI and business logic
+- Business logic can be used programmatically (no CLI dependencies in `lib/`)
+
+**Full Philosophy:** [Purpose and Philosophy](../purpose-and-philosophy.md)
+
+---
+
+**Last updated:** 2025-11-08