appydave-tools 0.21.2 → 0.22.0

data/lib/appydave/tools/dam/s3_operations.rb

@@ -389,7 +389,21 @@ module Appydave
 
         # Calculate MD5 hash of a file
         def file_md5(file_path)
-          Digest::MD5.file(file_path).hexdigest
+          # Use chunked reading for large files to avoid "Invalid argument @ io_fread" errors
+          puts "  🔍 Calculating MD5 for #{File.basename(file_path)}..." if ENV['DEBUG']
+          md5 = Digest::MD5.new
+          File.open(file_path, 'rb') do |file|
+            while (chunk = file.read(8192))
+              md5.update(chunk)
+            end
+          end
+          result = md5.hexdigest
+          puts "  ✓ MD5: #{result[0..7]}..." if ENV['DEBUG']
+          result
+        rescue StandardError => e
+          puts "  ⚠️  Warning: Failed to calculate MD5 for #{File.basename(file_path)}: #{e.message}"
+          puts '  → Will upload without MD5 comparison'
+          nil
         end
 
         # Get MD5 of file in S3 (from ETag)
@@ -413,21 +427,59 @@ module Appydave
           # Detect MIME type for proper browser handling
           content_type = detect_content_type(local_file)
 
-          File.open(local_file, 'rb') do |file|
-            s3_client.put_object(
+          # For large files, use TransferManager for managed uploads (supports multipart)
+          file_size = File.size(local_file)
+          start_time = Time.now
+
+          if file_size > 100 * 1024 * 1024 # > 100MB
+            puts "  📤 Uploading large file (#{file_size_human(file_size)})..."
+
+            # Use TransferManager for multipart upload (modern AWS SDK approach)
+            transfer_manager = Aws::S3::TransferManager.new(client: s3_client)
+            transfer_manager.upload_file(
+              local_file,
               bucket: brand_info.aws.s3_bucket,
               key: s3_path,
-              body: file,
               content_type: content_type
             )
+          else
+            # For smaller files, use direct put_object
+            File.open(local_file, 'rb') do |file|
+              s3_client.put_object(
+                bucket: brand_info.aws.s3_bucket,
+                key: s3_path,
+                body: file,
+                content_type: content_type
+              )
+            end
           end
 
-          puts "  ✓ Uploaded: #{File.basename(local_file)} (#{file_size_human(File.size(local_file))})"
+          elapsed = Time.now - start_time
+          elapsed_str = format_duration(elapsed)
+          puts "  ✓ Uploaded: #{File.basename(local_file)} (#{file_size_human(file_size)}) in #{elapsed_str}"
           true
         rescue Aws::S3::Errors::ServiceError => e
           puts "  ✗ Failed: #{File.basename(local_file)}"
           puts "    Error: #{e.message}"
           false
+        rescue StandardError => e
+          puts "  ✗ Failed: #{File.basename(local_file)}"
+          puts "    Error: #{e.class} - #{e.message}"
+          false
+        end
+
+        def format_duration(seconds)
+          if seconds < 60
+            "#{seconds.round(1)}s"
+          elsif seconds < 3600
+            minutes = (seconds / 60).floor
+            secs = (seconds % 60).round
+            "#{minutes}m #{secs}s"
+          else
+            hours = (seconds / 3600).floor
+            minutes = ((seconds % 3600) / 60).floor
+            "#{hours}h #{minutes}m"
+          end
         end
 
         def detect_content_type(filename)

data/lib/appydave/tools/dam/s3_scanner.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-s3'
+
+module Appydave
+  module Tools
+    module Dam
+      # Scan S3 bucket for project files
+      class S3Scanner
+        attr_reader :brand_info, :brand, :s3_client
+
+        def initialize(brand, brand_info: nil, s3_client: nil)
+          @brand_info = brand_info || load_brand_info(brand)
+          @brand = @brand_info.key
+          @s3_client = s3_client || create_s3_client(@brand_info)
+        end
+
+        # Scan S3 for a specific project
+        # @param project_id [String] Project ID (e.g., "b65-guy-monroe-marketing-plan")
+        # @return [Hash] S3 file data with :file_count, :total_bytes, :last_modified
+        def scan_project(project_id)
+          bucket = @brand_info.aws.s3_bucket
+          prefix = File.join(@brand_info.aws.s3_prefix, project_id, '')
+
+          puts "  🔍 Scanning #{project_id}..."
+
+          files = list_s3_objects(bucket, prefix)
+
+          if files.empty?
+            return {
+              exists: false,
+              file_count: 0,
+              total_bytes: 0,
+              last_modified: nil
+            }
+          end
+
+          total_bytes = files.sum(&:size)
+          last_modified = files.map(&:last_modified).max
+
+          {
+            exists: true,
+            file_count: files.size,
+            total_bytes: total_bytes,
+            last_modified: last_modified.utc.iso8601
+          }
+        rescue Aws::S3::Errors::ServiceError => e
+          puts "  ⚠️  S3 scan failed for #{project_id}: #{e.message}"
+          { exists: false, file_count: 0, total_bytes: 0, last_modified: nil, error: e.message }
+        end
+
+        # Scan all projects in brand's S3 bucket
+        # @return [Hash] Map of project_id => scan result
+        def scan_all_projects
+          bucket = @brand_info.aws.s3_bucket
+          prefix = @brand_info.aws.s3_prefix
+
+          puts "🔍 Scanning all projects in S3: s3://#{bucket}/#{prefix}"
+          puts ''
+
+          # List all "directories" (prefixes) under brand prefix
+          project_prefixes = list_s3_prefixes(bucket, prefix)
+
+          if project_prefixes.empty?
+            puts '  📭 No projects found in S3'
+            return {}
+          end
+
+          puts "  Found #{project_prefixes.size} projects in S3"
+          puts ''
+
+          results = {}
+          project_prefixes.each do |project_id|
+            results[project_id] = scan_project(project_id)
+          end
+
+          results
+        end
+
+        private
+
+        def load_brand_info(brand)
+          Appydave::Tools::Configuration::Config.configure
+          Appydave::Tools::Configuration::Config.brands.get_brand(brand)
+        end
+
+        def create_s3_client(brand_info)
+          profile_name = brand_info.aws.profile
+          raise "AWS profile not configured for brand '#{@brand}'" if profile_name.nil? || profile_name.empty?
+
+          credentials = Aws::SharedCredentials.new(profile_name: profile_name)
+
+          Aws::S3::Client.new(
+            credentials: credentials,
+            region: brand_info.aws.region,
+            http_wire_trace: false,
+            ssl_verify_peer: false
+          )
+        end
+
+        # List all objects under a prefix
+        def list_s3_objects(bucket, prefix)
+          objects = []
+          continuation_token = nil
+
+          loop do
+            resp = s3_client.list_objects_v2(
+              bucket: bucket,
+              prefix: prefix,
+              continuation_token: continuation_token
+            )
+
+            objects.concat(resp.contents)
+            break unless resp.is_truncated
+
+            continuation_token = resp.next_continuation_token
+          end
+
+          objects
+        end
+
+        # List project-level prefixes (directories) under brand prefix
+        def list_s3_prefixes(bucket, prefix)
+          resp = s3_client.list_objects_v2(
+            bucket: bucket,
+            prefix: prefix,
+            delimiter: '/'
+          )
+
+          # common_prefixes returns array of prefixes like "staging/v-appydave/b65-guy-monroe/"
+          resp.common_prefixes.map do |cp|
+            # Extract project ID from prefix
+            File.basename(cp.prefix.chomp('/'))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.21.2'
+    VERSION = '0.22.0'
   end
 end

data/lib/appydave/tools.rb

@@ -56,6 +56,7 @@ require 'appydave/tools/dam/config'
 require 'appydave/tools/dam/project_resolver'
 require 'appydave/tools/dam/config_loader'
 require 'appydave/tools/dam/s3_operations'
+require 'appydave/tools/dam/s3_scanner'
 require 'appydave/tools/dam/share_operations'
 require 'appydave/tools/dam/project_listing'
 require 'appydave/tools/dam/manifest_generator'

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appydave-tools",
-  "version": "0.21.2",
+  "version": "0.22.0",
   "description": "AppyDave YouTube Automation Tools",
   "scripts": {
     "release": "semantic-release"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appydave-tools
 version: !ruby/object:Gem::Version
-  version: 0.21.2
+  version: 0.22.0
 platform: ruby
 authors:
 - David Cruwys
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-17 00:00:00.000000000 Z
+date: 2025-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -228,42 +228,46 @@ files:
 - bin/youtube_automation.rb
 - bin/youtube_manager.rb
 - docs/README.md
+- docs/architecture/cli/cli-pattern-comparison.md
+- docs/architecture/cli/cli-patterns.md
+- docs/architecture/configuration/configuration-systems.md
+- docs/architecture/dam/dam-cli-enhancements.md
+- docs/architecture/dam/dam-cli-implementation-guide.md
+- docs/architecture/dam/dam-data-model.md
+- docs/architecture/dam/dam-vision.md
+- docs/architecture/dam/dam-visualization-requirements.md
+- docs/architecture/dam/design-decisions/002-client-sharing.md
+- docs/architecture/dam/design-decisions/003-git-integration.md
+- docs/architecture/dam/implementation-roadmap.md
+- docs/architecture/dam/jan-collaboration-guide.md
+- docs/architecture/design-decisions/001-unified-brands-config.md
+- docs/architecture/design-decisions/session-2025-11-09.md
 - docs/archive/codebase-audit-2025-01.md
 - docs/archive/documentation-framework-proposal.md
 - docs/archive/purpose-and-philosophy.md
 - docs/archive/test-coverage-quick-wins.md
 - docs/archive/tool-discovery.md
 - docs/archive/tool-documentation-analysis.md
-- docs/configuration/.env.example
-- docs/configuration/README.md
-- docs/configuration/channels.example.json
-- docs/configuration/settings.example.json
-- docs/dam/dam-testing-plan.md
-- docs/dam/dam-vision.md
-- docs/dam/prd-client-sharing.md
-- docs/dam/prd-git-integration.md
-- docs/dam/session-summary-2025-11-09.md
-- docs/dam/usage.md
-- docs/dam/windows/README.md
-- docs/dam/windows/dam-testing-plan-windows-powershell.md
-- docs/dam/windows/installation.md
-- docs/development/CODEX-recommendations.md
-- docs/development/README.md
-- docs/development/cli-architecture-patterns.md
-- docs/development/pattern-comparison.md
-- docs/prd-unified-brands-configuration.md
-- docs/project-brand-systems-analysis.md
-- docs/tools/bank-reconciliation.md
-- docs/tools/cli-actions.md
-- docs/tools/configuration.md
-- docs/tools/gpt-context.md
-- docs/tools/index.md
-- docs/tools/move-images.md
-- docs/tools/name-manager.md
-- docs/tools/prompt-tools.md
-- docs/tools/subtitle-processor.md
-- docs/tools/youtube-automation.md
-- docs/tools/youtube-manager.md
+- docs/guides/configuration-setup.md
+- docs/guides/platforms/windows/README.md
+- docs/guides/platforms/windows/dam-testing-plan-windows-powershell.md
+- docs/guides/platforms/windows/installation.md
+- docs/guides/tools/bank-reconciliation.md
+- docs/guides/tools/cli-actions.md
+- docs/guides/tools/configuration.md
+- docs/guides/tools/dam/dam-testing-plan.md
+- docs/guides/tools/dam/dam-usage.md
+- docs/guides/tools/gpt-context.md
+- docs/guides/tools/index.md
+- docs/guides/tools/move-images.md
+- docs/guides/tools/name-manager.md
+- docs/guides/tools/prompt-tools.md
+- docs/guides/tools/subtitle-processor.md
+- docs/guides/tools/youtube-automation.md
+- docs/guides/tools/youtube-manager.md
+- docs/templates/.env.example
+- docs/templates/channels.example.json
+- docs/templates/settings.example.json
 - exe/ad_config
 - exe/dam
 - exe/gpt_context
@@ -297,6 +301,7 @@ files:
 - lib/appydave/tools/dam/repo_status.rb
 - lib/appydave/tools/dam/repo_sync.rb
 - lib/appydave/tools/dam/s3_operations.rb
+- lib/appydave/tools/dam/s3_scanner.rb
 - lib/appydave/tools/dam/share_operations.rb
 - lib/appydave/tools/dam/status.rb
 - lib/appydave/tools/dam/sync_from_ssd.rb

data/docs/development/CODEX-recommendations.md

@@ -1,258 +0,0 @@
-# CODEX Recommendations - Review & Status
-
-> Last updated: 2025-11-10 11:01:36 UTC
-> Original recommendations provided by Codex (GPT-5) on 2025-11-09
-
-This document captures Codex's architectural recommendations with implementation status and verdicts after engineering review.
-
-## Executive Summary
-
-**Overall Assessment:** Mixed recommendations - some valuable, some outdated, some architecturally inappropriate.
-
-**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)
-
----
-
-## Priority Recommendations
-
-### ✅ P3: Standardize Filesystem Fixtures (IMPLEMENTED)
-
-**Recommendation:** Extract `Dir.mktmpdir + FileUtils.mkdir_p` boilerplate into shared RSpec context.
-
-**Status:** ✅ **Implemented** (2025-11-10)
-
-**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)
-
-**Benefits delivered:**
-- Reduced duplication across VAT specs
-- Centralized cleanup logic (safer tests)
-- Easier to maintain and extend
-
----
-
-### ❌ P1: RuboCop Cleanup (ALREADY COMPLETE)
-
-**Recommendation:** Run `rubocop --auto-correct` to fix 93 offenses, track 15 manual fixes.
-
-**Status:** ❌ **Obsolete** - RuboCop already clean
-
-**Current state:**
-```bash
-bundle exec rubocop
-# => 103 files inspected, no offenses detected
-```
-
-**Verdict:** The recommendations document was based on outdated codebase state. No action needed.
-
----
-
-### ❌ P0: Configuration Dependency Injection (REJECTED)
-
-**Recommendation:** Replace `allow_any_instance_of(SettingsConfig)` with dependency injection pattern:
-```ruby
-# Proposed:
-Config.projects_root(settings: custom_settings)
-```
-
-**Status:** ❌ **Rejected** - Architecturally inappropriate
-
-**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
-
-**Codex's concern:** "Tests must stub *every* SettingsConfig instance"
-
-**Reality:** This is fine. Configuration is a singleton. Testing strategy is appropriate.
-
-**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.
-
----
-
-### ❌ P4: Remove method_missing from Configuration::Config (REJECTED)
-
-**Recommendation:** Replace `method_missing` with explicit reader methods or `Forwardable`.
-
-**Status:** ❌ **Rejected** - This is a design pattern, not a code smell
-
-**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
-
-**Codex's concern:** "Hides failures until runtime and complicates auto-complete"
-
-**Reality:** This is a common Ruby pattern (Rails uses it extensively). The implementation is correct.
-
-**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.
-
----
-
-### ⚠️ P2: Decouple Terminal IO from VAT Services (DEFERRED)
-
-**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.
-
-### 🔍 DAM Manifest & Sync Addendum (2025-11-10)
-
-Phase 1 added S3/git metadata, but several inconsistencies remain between the manifest generator and the SSD sync tooling:
-
-- **Range directories are inconsistent:** `ManifestGenerator#determine_range` groups projects in 50-count buckets per letter (`lib/appydave/tools/dam/manifest_generator.rb:271-285`), but `SyncFromSsd#determine_range` still assumes only `b`-series projects and uses 10-count buckets (`lib/appydave/tools/dam/sync_from_ssd.rb:186-196`). Any non-`b` brand (AITLDR, VOZ) or the new 50-count scheme will pick the wrong destination folder.  
-- **SSD paths are lossy:** Manifests store `storage[:ssd][:path] = project_id` even when the data actually lives under `ssd/<range>/<project>` (`lib/appydave/tools/dam/manifest_generator.rb:178-185`). `SyncFromSsd#sync_project` then only checks `ssd/<project>` (`lib/appydave/tools/dam/sync_from_ssd.rb:162-170`), so range-based backups always report “SSD path not found” despite `ssd_exists: true` in the manifest. Persist the relative range folder so both tools agree on the same layout.  
-- **Heavy file detection still stops at the top level:** `heavy_files?` only scans `dir/*.{mp4,...}` (`lib/appydave/tools/dam/manifest_generator.rb:314-318`), so nested footage (e.g., `final/video.mp4`) reports `has_heavy_files: false`, skewing SSD/cleanup metrics. Mirror the recursive approach used in `light_files?`.  
-- **Exclude patterns are fragile:** `SyncFromSsd#excluded_file?` strips `**/` from patterns and only compares path segments (`lib/appydave/tools/dam/sync_from_ssd.rb:198-223`), which means globs like `**/.DS_Store` or `**/*.lock` do not behave like actual glob patterns. Replace the manual parsing with `File.fnmatch?(pattern, relative_path, File::FNM_PATHNAME | File::FNM_DOTMATCH)` so `.git`, `.turbo`, etc., are consistently ignored.
-
-Action: Align the manifest and sync code on the same range conventions and relative paths before we rely on Phase 2 git workflows; otherwise `dam sync-ssd` will never restore the projects that manifests say exist.
-
-### ⚠️ DAM Git Workflow (Phase 2)
-
-- **Project resolver instantiated incorrectly:** Both `Status#resolve_project_path` and `RepoPush#validate_project` call `ProjectResolver.new.resolve` (`lib/appydave/tools/dam/status.rb:36-40`, `lib/appydave/tools/dam/repo_push.rb:45-63`), but `ProjectResolver` only exposes class methods inside `class << self`. These code paths raise `NoMethodError` the moment you ask for project status or run `dam repo-push … <project>`. Switch to `ProjectResolver.resolve(...)` (or add an instance API) before shipping.  
-- **Auto-detected brands pollute configuration:** When you run `dam status` from inside `v-appydave`, the auto-detect logic passes the literal `v-appydave` string (`bin/dam:269-290`) into `Status`, which in turn calls `Config.git_remote`. That method persists the inferred remote under whatever key it was given (`lib/appydave/tools/dam/config.rb:43-71`), so a new `v-appydave` entry gets written to `brands.json`, duplicating the real `appydave` record. Normalize auto-detected names back to the canonical brand key before calling configuration APIs.  
-- **Naming drift in the CLI:** `bin/dam` still defines `class VatCLI` (line 11), so stack traces and help output reference the old VAT class name. Rename the class (and any references) to avoid confusion when both `vat` and `dam` binaries coexist.
-
----
-
-### ⚠️ 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.