appydave-tools 0.17.0 → 0.18.0

data/docs/development/CODEX-recommendations.md

@@ -1,123 +1,241 @@
-# CODEX Recommendations
+# CODEX Recommendations - Review & Status
 
-> 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.
+> Last updated: 2025-11-10
+> Original recommendations provided by Codex (GPT-5) on 2025-11-09
 
-Guide created by Codex (GPT-5) to capture near-term cleanups and deeper refactors that will make `appydave-tools` easier to extend and test.
+This document captures Codex's architectural recommendations with implementation status and verdicts after engineering review.
 
-## Snapshot
+## Executive Summary
 
-- **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.
+**Overall Assessment:** Mixed recommendations - some valuable, some outdated, some architecturally inappropriate.
 
-## Priority Map
+**Implemented:** ✅ P3 (Filesystem fixtures)
+**Rejected:** ❌ P0 (Configuration DI), P1 (RuboCop - already clean), P4 (method_missing removal)
+**Deferred:** ⚠️ P2 (IO separation - CLI tool doesn't need it)
+**Future Work:** 🔍 VAT Manifest bugs (valid technical debt)
 
-| 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
+## Priority Recommendations
 
-### 1. Introduce configuration adapters
+### ✅ P3: Standardize Filesystem Fixtures (IMPLEMENTED)
 
-- **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.
+**Recommendation:** Extract `Dir.mktmpdir + FileUtils.mkdir_p` boilerplate into shared RSpec context.
 
-### 2. Capture the remaining RuboCop debt deliberately
+**Status:** ✅ **Implemented** (2025-11-10)
 
-- **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.
+**What was done:**
+- Created `spec/support/vat_filesystem_helpers.rb` with shared contexts
+- `include_context 'vat filesystem'` - provides temp_folder, projects_root, auto-cleanup
+- `include_context 'vat filesystem with brands', brands: %w[appydave voz]` - adds brand path helpers
+- Refactored 3 VAT specs: config_spec, project_resolver_spec, config_loader_spec
+- All tests passing (149 examples, 0 failures)
 
-### 3. Decouple terminal IO from VAT services
+**Benefits delivered:**
+- Reduced duplication across VAT specs
+- Centralized cleanup logic (safer tests)
+- Easier to maintain and extend
 
-- **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
+### ❌ P1: RuboCop Cleanup (ALREADY COMPLETE)
 
-- **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.
+**Recommendation:** Run `rubocop --auto-correct` to fix 93 offenses, track 15 manual fixes.
 
-### 5. Harden `Configuration::Config`
+**Status:** ❌ **Obsolete** - RuboCop already clean
 
-- **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.
+**Current state:**
+```bash
+bundle exec rubocop
+# => 103 files inspected, no offenses detected
+```
 
-### 6. Bake the plan into docs & automation
+**Verdict:** The recommendations document was based on outdated codebase state. No action needed.
 
-- 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
+### ❌ P0: Configuration Dependency Injection (REJECTED)
 
-### CLI boundaries & shared ergonomics
+**Recommendation:** Replace `allow_any_instance_of(SettingsConfig)` with dependency injection pattern:
+```ruby
+# Proposed:
+Config.projects_root(settings: custom_settings)
+```
 
-- `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.
+**Status:** ❌ **Rejected** - Architecturally inappropriate
 
-### GptContext as a reusable service
+**Why rejected:**
+1. **Singleton pattern is correct for configuration** - Global config state is intentional
+2. **Breaking API change** - Would require threading `settings:` through entire call chain:
+   - `bin/vat` → `ProjectResolver` → `Config.brand_path` → `Config.projects_root`
+   - Every method needs new parameter (massive churn)
+3. **Tests work correctly** - `allow_any_instance_of` is intentionally allowed in `.rubocop.yml`
+4. **No real benefit** - Adds complexity without solving actual problems
 
-- `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.
+**Codex's concern:** "Tests must stub *every* SettingsConfig instance"
 
-### Subtitle pipeline robustness
+**Reality:** This is fine. Configuration is a singleton. Testing strategy is appropriate.
 
-- `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.
+**Lesson for Codex:** Dependency injection is not always superior to singleton patterns. Context matters. CLI tools with global configuration state don't benefit from DI complexity.
 
-### 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.
+### ❌ P4: Remove method_missing from Configuration::Config (REJECTED)
 
-### Configuration & type safety
+**Recommendation:** Replace `method_missing` with explicit reader methods or `Forwardable`.
 
-- `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.
+**Status:** ❌ **Rejected** - This is a design pattern, not a code smell
 
-### Testing & observability
+**Why rejected:**
+1. **Registry pattern** - `method_missing` enables dynamic configuration registration:
+   ```ruby
+   Config.register(:settings, SettingsConfig)
+   Config.register(:channels, ChannelsConfig)
+   Config.settings  # Dynamic dispatch via method_missing
+   ```
+2. **Proper implementation** - Has `respond_to_missing?` (Ruby best practice ✅)
+3. **Good error handling** - Clear messages listing available configs
+4. **Plugin architecture** - Can add new configs without modifying `Config` class
 
-- `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.
+**Codex's concern:** "Hides failures until runtime and complicates auto-complete"
 
-### Platform & dependency strategy
+**Reality:** This is a common Ruby pattern (Rails uses it extensively). The implementation is correct.
 
-- `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.
+**Lesson for Codex:** `method_missing` is not inherently bad. When properly implemented with `respond_to_missing?` and clear errors, it enables powerful metaprogramming patterns. Don't dogmatically avoid it.
 
-## 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.
+### ⚠️ P2: Decouple Terminal IO from VAT Services (DEFERRED)
 
-Ping Codex if you’d like guidance on scoping or sequencing—happy to help break these down into actionable tickets.
+**Recommendation:** Extract interactive prompts from `ProjectResolver.resolve` business logic.
+
+**Codex's concern:** Interactive `puts`/`$stdin.gets` blocks automation agents.
+
+**Status:** ⚠️ **Low priority** - Not needed for current use case
+
+**Why deferred:**
+1. **CLI-only tool** - VAT is a command-line interface, not a library
+2. **Intentional UX** - Interactive prompts provide good user experience for ambiguous cases
+3. **No automation use cases** - Agents use exact project names, don't trigger prompts
+4. **Current code location:** `lib/appydave/tools/vat/project_resolver.rb:41-49`
+
+**When to revisit:** If VAT needs programmatic API for automation tools, add non-interactive mode:
+```ruby
+def resolve(brand, project_hint, interactive: true)
+  # Return all matches if !interactive (for automation)
+end
+```
+
+**Lesson for Codex:** Not all code needs maximum abstraction. CLI tools can have terminal IO in business logic if that's their primary use case.
+
+---
+
+## Architecture-Wide Observations
+
+### ✅ Valid Technical Debt: VAT Manifest Generator
+
+**Issues identified (lines 116-125 in original doc):**
+
+1. **Archived projects silently dropped** - `collect_project_ids` rejects archived folder entirely
+2. **SSD paths lose grouping context** - Stores only `project_id`, not `range/project_id`
+3. **Heavy file detection shallow** - Only checks top-level, misses nested videos
+4. **Quadratic disk scanning** - Walks every file twice per project
+5. **Code duplication** - Standalone `bin/generate_manifest.rb` diverged from lib class
+
+**Status:** 🔍 **Acknowledged as real bugs** - Worth investigating
+
+**Note:** These are legitimate technical debt items, not style preferences. Recommend creating GitHub issues for tracking.
+
+---
+
+### ⚠️ CLI Standardization (Worth Auditing)
+
+**Observation:** Not all bin scripts use `BaseAction` pattern consistently.
+
+**Example:** `bin/gpt_context.rb` hand-rolls `OptionParser` instead of using `lib/appydave/tools/cli_actions/base_action.rb`.
+
+**Status:** ⚠️ **Worth reviewing** for consistency
+
+**Action:** Audit which CLI scripts follow standard patterns vs. custom implementations.
+
+---
+
+## Lessons Learned (for future Codex reviews)
+
+### What Codex got right:
+1. ✅ **Filesystem fixtures** - Practical refactoring with clear benefits
+2. ✅ **Manifest bugs** - Identified real logic issues worth fixing
+3. ✅ **CLI consistency** - Valid observation about pattern divergence
+
+### Where Codex was dogmatic:
+1. ❌ **Dependency injection everywhere** - Not all singletons need DI
+2. ❌ **Avoid method_missing** - Valid Ruby pattern when done correctly
+3. ❌ **Separate all IO** - CLI tools can mix IO with logic appropriately
+
+### What Codex missed:
+1. **Current state validation** - Recommended RuboCop fixes already applied
+2. **Cost/benefit analysis** - P0 config adapter would break entire API for minimal gain
+3. **Context awareness** - CLI tools have different constraints than libraries
+
+---
+
+## Conclusion
+
+**Codex recommendations score: 4/10**
+
+**Good advice:**
+- Filesystem fixture extraction (implemented ✅)
+- Manifest generator bugs (valid technical debt 🔍)
+- CLI standardization audit (worth reviewing ⚠️)
+
+**Bad advice:**
+- Configuration dependency injection (wrong pattern for this use case ❌)
+- Remove method_missing (misunderstands design pattern ❌)
+- Outdated RuboCop recommendations (already fixed ❌)
+
+**Key takeaway:** Mix pragmatic refactoring suggestions with dogmatic "purity" recommendations. Cherry-pick the valuable insights, reject the inappropriate ones.
+
+---
+
+## Implementation Notes
+
+### P3 Filesystem Fixtures - Details
+
+**Files created:**
+- `spec/support/vat_filesystem_helpers.rb`
+
+**Shared contexts:**
+```ruby
+# Basic fixture
+include_context 'vat filesystem'
+# => Provides: temp_folder, projects_root, auto-cleanup, config mocking
+
+# With brand directories
+include_context 'vat filesystem with brands', brands: %w[appydave voz]
+# => Also provides: appydave_path, voz_path (auto-created)
+```
+
+**Files refactored:**
+- `spec/appydave/tools/vat/config_spec.rb` (removed 11 lines boilerplate)
+- `spec/appydave/tools/vat/project_resolver_spec.rb` (removed 18 lines boilerplate)
+- `spec/appydave/tools/vat/config_loader_spec.rb` (removed 9 lines boilerplate)
+
+**Test results:**
+- 149 VAT spec examples, 0 failures
+- Coverage: 76.38% (2131/2790 lines)
+
+---
+
+**Document maintained by:** AppyDave engineering team
+**Next review:** After addressing VAT manifest bugs
+
+## Communication Patterns & Practices
+
+Because this document is now a shared artifact between CODEx and Claude, align on the following collaboration rules so recommendations stay constructive and actionable:
+
+1. **State of the world first:** When responding to a recommendation, cite the current repo evidence (commit, test output, spec path) before giving a verdict. This keeps future readers from guessing which version you inspected.
+2. **Assume positive intent:** Frame disagreements in terms of trade-offs (“we prefer singletons here because…”) rather than absolutes. If a suggestion doesn’t fit today, note what signal would make you revisit it.
+3. **Acknowledge deltas:** When new findings arrive (e.g., Ruby version mismatch), summarize them here so both agents see the updated context even if the original section came from someone else.
+4. **Track actionability:** For every open item, tag it as ✅ implemented, ⚠️ deferred with trigger, or 🔍 debt worth filing. Avoid leaving “bad pattern” remarks without a next step.
+5. **Link evidence:** Reference commands (`bundle exec rubocop`), file paths (`bin/vat:160`), or PRs so the other agent can reproduce your conclusion quickly.
+6. **Close the loop:** When you adopt or reject a suggestion, leave a brief rationale in this doc instead of burying it in chat. That keeps the shared history centralized.

data/lib/appydave/tools/configuration/models/brands_config.rb

@@ -8,9 +8,24 @@ module Appydave
         class BrandsConfig < ConfigBase
           # Retrieve brand information by brand key (string or symbol)
           def get_brand(brand_key)
-            brand_key = brand_key.to_s
-            info = data['brands'][brand_key] || default_brand_info
-            BrandInfo.new(brand_key, info)
+            brand_key_str = brand_key.to_s
+
+            # Try direct key lookup first (case-insensitive)
+            brand_entry = data['brands'].find { |key, _info| key.downcase == brand_key_str.downcase }
+            if brand_entry
+              actual_key = brand_entry[0]
+              return BrandInfo.new(actual_key, brand_entry[1])
+            end
+
+            # Try lookup by shortcut (case-insensitive)
+            brand_entry = data['brands'].find { |_key, info| info['shortcut']&.downcase == brand_key_str.downcase }
+            if brand_entry
+              actual_key = brand_entry[0]
+              return BrandInfo.new(actual_key, brand_entry[1])
+            end
+
+            # Return default if not found (use normalized lowercase key)
+            BrandInfo.new(brand_key_str.downcase, default_brand_info)
           end
 
           # Set brand information

data/lib/appydave/tools/{vat → dam}/config.rb

@@ -2,7 +2,7 @@
 
 module Appydave
   module Tools
-    module Vat
+    module Dam
       # VatConfig - Configuration management for Video Asset Tools
       #
       # Manages VIDEO_PROJECTS_ROOT and brand path resolution
@@ -35,34 +35,42 @@ module Appydave
             brand = expand_brand(brand_key)
             path = File.join(projects_root, brand)
 
-            raise "Brand directory not found: #{path}\nAvailable brands: #{available_brands.join(', ')}" unless Dir.exist?(path)
+            unless Dir.exist?(path)
+              brands_list = available_brands_display
+              raise "Brand directory not found: #{path}\nAvailable brands:\n#{brands_list}"
+            end
 
             path
           end
 
           # Expand brand shortcut to full brand name
           # Reads from brands.json if available, falls back to hardcoded shortcuts
-          # @param shortcut [String] Brand shortcut (e.g., 'appydave')
+          # @param shortcut [String] Brand shortcut (e.g., 'appydave', 'ad', 'APPYDAVE')
           # @return [String] Full brand name (e.g., 'v-appydave')
           def expand_brand(shortcut)
-            return shortcut if shortcut.start_with?('v-')
+            shortcut_str = shortcut.to_s
+
+            return shortcut_str if shortcut_str.start_with?('v-')
 
             # Try to read from brands.json
             Appydave::Tools::Configuration::Config.configure
             brands_config = Appydave::Tools::Configuration::Config.brands
 
-            # Check if this shortcut exists in brands.json
-            if brands_config.shortcut?(shortcut)
-              brand = brands_config.brands.find { |b| b.shortcut == shortcut }
-              return "v-#{brand.key}" if brand
-            end
+            # Check if input matches a brand key (case-insensitive)
+            brand = brands_config.brands.find { |b| b.key.downcase == shortcut_str.downcase }
+            return "v-#{brand.key}" if brand
+
+            # Check if input matches a brand shortcut (case-insensitive)
+            brand = brands_config.brands.find { |b| b.shortcut.downcase == shortcut_str.downcase }
+            return "v-#{brand.key}" if brand
 
             # Fall back to hardcoded shortcuts for backwards compatibility
-            case shortcut
+            normalized = shortcut_str.downcase
+            case normalized
             when 'joy' then 'v-beauty-and-joy'
             when 'ss' then 'v-supportsignal'
             else
-              "v-#{shortcut}"
+              "v-#{normalized}"
             end
           end
 
@@ -90,6 +98,16 @@ module Appydave
                .sort
           end
 
+          # Get available brands with both shortcut and name for error messages
+          def available_brands_display
+            Appydave::Tools::Configuration::Config.configure
+            brands_config = Appydave::Tools::Configuration::Config.brands
+
+            brands_config.brands.map do |brand|
+              "  #{brand.shortcut.ljust(10)} - #{brand.name}"
+            end.sort.join("\n")
+          end
+
           # Check if directory is a valid brand
           # @param brand_path [String] Full path to potential brand directory
           # @return [Boolean] true if valid brand
@@ -114,14 +132,15 @@ module Appydave
 
           private
 
-          # Auto-detect projects root by finding git repos
+          # Auto-detect projects root by finding v-shared directory
           # @return [String] Detected path or raises error
           def detect_projects_root
             # Try to find v-shared in parent directories
             current = Dir.pwd
             5.times do
               test_path = File.join(current, 'v-shared')
-              return File.dirname(test_path) if Dir.exist?(test_path) && Dir.exist?(File.join(test_path, 'video-asset-tools'))
+              # Return parent of v-shared as projects root
+              return File.dirname(test_path) if Dir.exist?(test_path)
 
               parent = File.dirname(current)
               break if parent == current

data/lib/appydave/tools/{vat → dam}/config_loader.rb

@@ -2,7 +2,7 @@
 
 module Appydave
   module Tools
-    module Vat
+    module Dam
       # Configuration loader for video asset tools
       # Loads settings from .video-tools.env file in the repository root
       #

data/lib/appydave/tools/{vat → dam}/manifest_generator.rb

@@ -5,15 +5,15 @@ require 'fileutils'
 
 module Appydave
   module Tools
-    module Vat
+    module Dam
       # Generate manifest JSON for video projects
       class ManifestGenerator
         attr_reader :brand, :brand_info, :brand_path
 
         def initialize(brand, brand_info: nil, brand_path: nil)
-          @brand = brand
-          @brand_path = brand_path || Config.brand_path(brand)
           @brand_info = brand_info || load_brand_info(brand)
+          @brand = @brand_info.key # Use resolved brand key, not original input
+          @brand_path = brand_path || Config.brand_path(@brand)
         end
 
         # Generate manifest for this brand

data/lib/appydave/tools/{vat → dam}/project_listing.rb

@@ -8,7 +8,7 @@ require 'find'
 
 module Appydave
   module Tools
-    module Vat
+    module Dam
       # Project listing functionality for VAT
       class ProjectListing
         # List all brands with summary table

data/lib/appydave/tools/{vat → dam}/project_resolver.rb

@@ -2,7 +2,7 @@
 
 module Appydave
   module Tools
-    module Vat
+    module Dam
       # ProjectResolver - Resolve short project names to full paths
       #
       # Handles:

data/lib/appydave/tools/{vat → dam}/s3_operations.rb

@@ -7,18 +7,18 @@ require 'aws-sdk-s3'
 
 module Appydave
   module Tools
-    module Vat
+    module Dam
       # S3 operations for VAT (upload, download, status, cleanup)
       class S3Operations
         attr_reader :brand_info, :brand, :project_id, :brand_path, :s3_client
 
         def initialize(brand, project_id, brand_info: nil, brand_path: nil, s3_client: nil)
-          @brand = brand
           @project_id = project_id
 
           # Use injected dependencies or load from configuration
-          @brand_path = brand_path || Config.brand_path(brand)
           @brand_info = brand_info || load_brand_info(brand)
+          @brand = @brand_info.key # Use resolved brand key, not original input
+          @brand_path = brand_path || Config.brand_path(@brand)
           @s3_client = s3_client || create_s3_client(@brand_info)
         end