appydave-tools 0.76.7 → 0.76.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51ac1542f215f90d518a24c96b5185cf954b9db2beab4bbb93c8d43f3b106fb7
-  data.tar.gz: 11acb6d8817125846945e4f7ba3bfb77b305155093f507f346a21477c4102cdb
+  metadata.gz: 837cfa631ce3f72655208add542964a605efa385aea01abfe49c55fb9110cdbb
+  data.tar.gz: 4adfd72dad7dc7a41f909857a21616d3385b259ee11969d94641c75731713924
 SHA512:
-  metadata.gz: 02a5b3623de62bbb09d343101c1edc48b711fc8682d9396689043afcdd134276c887de57d802e8a717db9adaeb34b48eb14dd6a199e085d64430a0525300cf1e
-  data.tar.gz: ce60ac62a7753a206768335c7cc51c8d4765223efd9dd34d4a490fc250f8af63aca11fd532f9918f15ac075be8e7698bd7613704040a16f66777a0455ca54c25
+  metadata.gz: 2748e05e28b1c0cd4a7e6ec99f13a513c68ec49115d6b90bd0090d25467958eb0dd759cbf6fb8b94f210fc1835ee5d2c77cac79e3d7043cac2127513d982d89f
+  data.tar.gz: cf039ebec627c4899f5abc6c309829894c4dbca2ec71daf6ceb1143f61b72a46edb480223c9a8ab6acd5892ef343980f5395d6f6363276352056f111c3753026

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.76.7](https://github.com/appydave/appydave-tools/compare/v0.76.6...v0.76.7) (2026-03-19)
+
+
+### Bug Fixes
+
+* extract S3ArgParser module from VatCLI; add spec ([9bbd709](https://github.com/appydave/appydave-tools/commit/9bbd7099c26b774b68103f4d37d0a25f22f4abc2))
+
 ## [0.76.6](https://github.com/appydave/appydave-tools/compare/v0.76.5...v0.76.6) (2026-03-19)
 
 

data/docs/planning/AGENTS.md

@@ -45,7 +45,7 @@ kfeat "add feature description"             # Minor version bump
 kfix "fix bug description"                  # Patch version bump
 ```
 
-**Baseline (2026-03-19):** 831 examples, 0 failures, ~85.92% line coverage
+**Baseline (2026-03-19):** 847 examples, 0 failures, ~86.21% line coverage
 
 ---
 
@@ -221,9 +221,9 @@ Appydave::Tools::Configuration::Config.configure
 
 ## Quality Gates
 
-- **Tests:** `bundle exec rspec` — 831 examples, 0 failures (do not ship if any fail)
+- **Tests:** `bundle exec rspec` — 847 examples, 0 failures (do not ship if any fail)
 - **Lint:** `bundle exec rubocop --format clang` — 0 offenses (CI will reject)
-- **Coverage:** ≥ 85.92% line coverage
+- **Coverage:** ≥ 86.21% line coverage
 - **frozen_string_literal:** Required on every new `.rb` file
 - **Commit format:** `kfeat`/`kfix` only — triggers semantic versioning + CI wait
 
@@ -248,6 +248,12 @@ Appydave::Tools::Configuration::Config.configure
 - **Jump Commands layer is undertested:** `Commands::Remove`, `Commands::Add`, `Commands::Update` have zero dedicated specs. Auto-regenerate CLI spec does not substitute for command-layer unit tests verifying `--force` guards, error codes, and suggestion logic (see B018).
 - **Jump report commands** got `--limit` and `--skip-unassigned` flags after initial implementation. Jump tool scope grows incrementally.
 
+### From extract-vat-cli (2026-03-19)
+
+- **Do NOT carry over rubocop-disable comments when extracting methods.** Run rubocop on the new file first — methods that needed disables in a 1,600-line God class often don't exceed thresholds in a properly-scoped library class. Carrying them over causes CI to flag `Lint/RedundantCopDisableDirective` and requires a second fix commit.
+- **grep for callers before writing the plan.** `format_bytes` had 4 callers in bin/dam, not 3 as counted from memory. The orphaned-projects loop was missed.
+- **`valid_brand?` needs `Config.brands` mock, not just `SettingsConfig` mock.** The shared `'with vat filesystem and brands'` context only mocks `SettingsConfig#video_projects_root`. Any method calling `Config.brands` directly needs an explicit brands config mock.
+
 ### From Three-Lens Audit (2026-03-19)
 
 - **`file_collector.rb` has two landmines before FR-2:** `puts @working_directory` at line 15 pollutes stdout; `FileUtils.cd` without `ensure` leaves process in wrong directory on exception. Fix both before adding any code to this class.

data/docs/planning/BACKLOG.md

@@ -1,7 +1,7 @@
 # Project Backlog — AppyDave Tools
 
-**Last updated**: 2026-03-19 (micro-cleanup campaign complete)
-**Total**: 33 | Pending: 7 | In Progress: 1 | Done: 25 | Deferred: 0 | Rejected: 0
+**Last updated**: 2026-03-19 (extract-vat-cli campaign complete)
+**Total**: 37 | Pending: 11 | Done: 26 | Deferred: 0 | Rejected: 0
 
 ---
 
@@ -14,8 +14,12 @@
 - [ ] B008 — Performance: cache git/S3 status with 5-min TTL | Priority: low
 - [ ] B009 — UX: progress indicators for dam operations > 5s | Priority: low
 - [ ] B010 — UX: auto-adjust dam table column widths to terminal width | Priority: low
-- [~] B011 — Arch: extract VatCLI business logic from bin/dam (1,600-line God class) | Campaign: extract-vat-cli
+- [x] B011 — Arch: extract VatCLI business logic from bin/dam (1,600-line God class) | Completed: extract-vat-cli (2026-03-19)
 - [ ] B020 — Arch: split S3Operations (1,030 lines, mixed I/O + logic) | Priority: low
+- [ ] B034 — Fix: replace exit 1 with typed exceptions in S3ScanCommand + S3ArgParser | Priority: high (blocks B007 + test coverage)
+- [ ] B035 — Fix: remove ENV['BRAND_PATH'] side effect from S3ArgParser | Priority: high (blocks B007 parallelism)
+- [ ] B036 — Tests: improve S3ScanCommand spec from D to B (depends on B034) | Priority: medium
+- [ ] B037 — Tests: LocalSyncStatus :partial case, local_file_count assertion, Zone.Identifier exclusion | Priority: medium
 
 ---
 

data/docs/planning/extract-vat-cli/IMPLEMENTATION_PLAN.md

@@ -5,13 +5,13 @@
 **Target**: All 4 complete; 831+ examples passing; rubocop 0 offenses; no regressions
 
 ## Summary
-- Total: 4 | Complete: 0 | In Progress: 0 | Pending: 4 | Failed: 0
+- Total: 4 | Complete: 4 | In Progress: 0 | Pending: 0 | Failed: 0
 
 ## Pending
 - [x] extract-format-bytes — Replaced 4 callers (plan said 3; orphaned-projects loop in display_s3_scan_table was a 4th). format_bytes deleted. rubocop 0 offenses. Commit: 3cd362f.
 - [x] extract-local-sync-status — LocalSyncStatus module created, 7 specs added (838 total), both methods gone from VatCLI. Side-fix: restored youtube_automation_config require incorrectly removed in prior commit. v0.76.5.
 - [x] extract-s3-scan-command — S3ScanCommand created, 2 smoke tests added (840 total), 3 methods gone from VatCLI. Note: rubocop-disable directives became redundant once methods left God class — needed 2nd kfix to remove them. v0.76.6.
-- [~] extract-s3-arg-parser — Extract `parse_s3_args` + `valid_brand?` + `parse_share_args` + `show_share_usage_and_exit` + `parse_discover_args` → new `S3ArgParser` class; add spec
+- [x] extract-s3-arg-parser — S3ArgParser module created, 7 specs added (847 total), 5 methods + 8 callers updated, all gone from VatCLI. Note: valid_brand? needed Config.brands mock (shared context only mocks SettingsConfig). v0.76.7.
 
 ## In Progress
 

data/docs/planning/extract-vat-cli/assessment.md

@@ -0,0 +1,107 @@
+# Assessment: extract-vat-cli
+
+**Campaign**: extract-vat-cli
+**Date**: 2026-03-19 → 2026-03-19
+**Results**: 4/4 complete, 0 failed
+
+---
+
+## Results Summary
+
+| Work Unit | Outcome | Version | Notes |
+|---|---|---|---|
+| extract-format-bytes | ✅ Complete | v0.76.4→ | 4 callers replaced (plan said 3; orphaned-projects loop was 4th) |
+| extract-local-sync-status | ✅ Complete | v0.76.5 | Side-fix: restored youtube_automation_config require removed in prior commit |
+| extract-s3-scan-command | ✅ Complete | v0.76.6 | Needed 2nd kfix: inherited rubocop-disable directives became redundant |
+| extract-s3-arg-parser | ✅ Complete | v0.76.7 | valid_brand? needed BrandsConfig mock; parse_share fully tested |
+
+**Suite:** 831 → 847 examples (+16), 0 failures, 86.21% coverage. rubocop 0 offenses. CI green on all 4 commits.
+
+---
+
+## What Worked Well
+
+1. **Sequential wave strategy was correct.** All 4 work units touched bin/dam — wave size = 1 was the only safe option. No conflicts, no merge issues, zero failed agents.
+
+2. **AGENTS.md quality was sufficient.** All agents executed cleanly without confusion about which methods to move or which callers to update. The detailed WU-specific instructions in the campaign AGENTS.md were the right level of specificity.
+
+3. **format_bytes extraction was genuinely trivial.** FileHelper.format_size already existed and was identical. WU1 was pure deletion + caller update — no logic risk.
+
+4. **LocalSyncStatus came out clean.** The module_function pattern worked correctly, the shared filesystem context covered most branches, and the side-fix of youtube_automation_config was a net win.
+
+5. **bin/dam went from 1,600 → 1,223 lines (−23%) and 20+ → 5 rubocop-disables.** The remaining 5 are structural (help text dispatch, not logic). Significant improvement.
+
+---
+
+## What Didn't Work
+
+1. **Inherited rubocop-disable directives caused 2nd kfix commits** (WU3, WU4). Methods that needed `Metrics/MethodLength` disable in the God class context don't exceed thresholds in properly-scoped library classes. CI rubocop 1.85.1 flags them as redundant. Rule: don't carry over rubocop-disable comments when extracting — run rubocop fresh on the new file.
+
+2. **Caller count was wrong in the plan.** Plan said 3 callers for format_bytes; there were 4 (orphaned-projects loop in display_s3_scan_table). This was a minor issue (caught and fixed by WU1 agent) but points to a planning discipline gap: grep for callers, don't count from memory.
+
+3. **exit 1 calls were carried into library code.** `S3ScanCommand` and `S3ArgParser` both call `exit 1` in response to invalid inputs. This was the pre-existing VatCLI pattern — the extraction was faithful — but it now lives in library classes where it's a boundary violation. Makes testing error paths impossible and blocks safe parallelism (B007).
+
+4. **S3ScanCommand spec is F-grade (confirmed by independent test audit).** Two `respond_to` tests confirm the class loads; nothing more. 90 lines of orchestration logic — manifest merging, orphan detection, LocalSyncStatus wiring — are completely unprotected. The `exit 1` call at line 55 makes the "no manifest" path untestable without production code changes first.
+
+5. **`Zone.Identifier` exclusion in LocalSyncStatus has no test.** The filter for Windows metadata files (line 26) is untested — removal or inversion would pass all current specs silently.
+
+6. **`ENV['BRAND_PATH']` side-effect never asserted in S3ArgParser spec.** All three parse methods set it; none of the specs check it. A key-name change would silently break ConfigLoader downstream.
+
+---
+
+## Key Learnings — Application
+
+1. **Don't carry over rubocop-disable comments when extracting.** Run rubocop fresh on the new file; only add disables if actually triggered.
+2. **grep for callers before writing the plan.** Don't count from memory or code review alone.
+3. **Library classes must not call `exit`.** Raise typed exceptions (`ConfigurationError`, `UsageError`) — let the CLI layer print and exit. Required before B007.
+4. **`valid_brand?` and anything calling `Config.brands` needs BrandsConfig mock** — the shared context only mocks `SettingsConfig#video_projects_root`.
+5. **ENV['BRAND_PATH'] side effect now in library code.** S3ArgParser sets a process-wide env var as a side effect of argument parsing. Must be resolved before parallelism (B007).
+
+---
+
+## Key Learnings — Ralph Loop
+
+1. **Wave size = 1 was correct for God-class extraction.** When all work units share a single target file, parallel waves cause conflicts. Plan for sequential from the start.
+2. **Detailed WU-specific AGENTS.md sections paid off.** Specifying exact line numbers, method names, and new class signatures eliminated agent confusion. Worth the upfront effort.
+3. **Side-fixes happen.** WU2 found and fixed a pre-existing require omission. Good — agents should fix what they find. Update the plan notes so the next session knows.
+4. **2nd kfix commits were needed on 2/4 work units** — predictable pattern for extractions. Build in a "check for redundant rubocop directives" step in future extraction AGENTS.md.
+
+---
+
+## Promote to Main KDD?
+
+- "Don't carry over rubocop-disable when extracting" → yes, promote
+- "grep for callers before planning" → yes, promote
+- "Library classes must not call exit" → yes, promote (already in project AGENTS.md, promote to KDD)
+
+---
+
+## Suggestions for Next Campaign
+
+### Debt introduced by this campaign (should address before B007)
+
+**B034 — Fix: replace `exit 1` with typed exceptions in S3ScanCommand + S3ArgParser**
+- `S3ScanCommand#scan_single` calls `exit 1` at line 55 (no manifest path)
+- `S3ArgParser` calls `exit 1` at 4 locations (invalid brand, PWD auto-detect fail, discover missing args, share missing args)
+- Fix: raise `Appydave::Tools::Dam::ConfigurationError` / new `UsageError` subclass
+- VatCLI `rescue StandardError` already handles these at command level
+- Unblocks proper testing of error paths AND safe parallelism
+
+**B035 — Fix: remove ENV['BRAND_PATH'] side effect from S3ArgParser**
+- `parse_s3`, `parse_share`, `parse_discover` all set `ENV['BRAND_PATH']` as a side effect
+- Acceptable in a single-process CLI; unsafe in parallel execution
+- Fix: return the brand_path in the result hash and let VatCLI set it, or extract to explicit `S3ArgParser.configure_env!(brand)`
+
+**B036 — Tests: improve S3ScanCommand spec from D to B**
+- Depends on B034 (exit → exception) — can't test "no manifest" path until that's fixed
+- Add: mocked S3Scanner + filesystem fixture, assert manifest merge logic, assert LocalSyncStatus wiring
+
+**B037 — Tests: add LocalSyncStatus :partial case + local_file_count assertion**
+- Add `:partial` context (1 file in staging, s3 has 3) — assert `:partial` status and `local_file_count: 1`
+- Add assertion that `:synced` case sets `local_file_count` correctly
+
+### Mode recommendation for next session
+
+**4. Extend** — these are small debt items, same stack, inherit this AGENTS.md.
+
+Or, if you want to move forward to B007 (parallelism) instead: address B034 + B035 first (1-wave campaign), then B007 becomes buildable.

data/docs/planning/extract-vat-cli/learnings/wave-learnings.md

@@ -0,0 +1,36 @@
+# Wave Learnings — extract-vat-cli
+
+**Campaign:** extract-vat-cli
+**Date:** 2026-03-19
+**Result:** 4/4 complete. 831 → 847 examples (+16). v0.76.3 → v0.76.7.
+
+---
+
+## Application Learnings
+
+### 1. format_bytes had 4 callers, not 3
+The orphaned-projects loop in `display_s3_scan_table` had its own `format_bytes` call. Plan said 3 callers; there were 4. Always grep for callers before writing the plan rather than counting from memory.
+
+### 2. rubocop-disable directives become redundant when methods leave God class
+WU3 and WU4 both needed a second `kfix` to remove `rubocop:disable Metrics/MethodLength` and `Metrics/CyclomaticComplexity` directives that were valid in the 1,600-line VatCLI context but flagged as redundant by CI rubocop 1.85.1 once the methods were in properly-scoped library classes.
+
+**Rule for future extractions:** Do NOT carry over rubocop-disable comments. Run rubocop locally on the new file first — only add disables if rubocop actually flags an offense.
+
+### 3. valid_brand? needed Config.brands mock, not just SettingsConfig mock
+The shared context `'with vat filesystem and brands'` only mocks `SettingsConfig#video_projects_root`. Testing `valid_brand?` (which calls `Config.brands`) required an explicit `Config.configure` + `Config.brands` mock with a test `BrandsConfig` instance. Document this in AGENTS.md for future S3ArgParser specs.
+
+### 4. youtube_automation_config require was missing (pre-existing)
+WU2 agent discovered that a prior `chore(cleanup)` commit had incorrectly removed `require 'appydave/tools/youtube_automation_config'` from `lib/appydave/tools.rb`. The CI was failing on a `NameError` for `YoutubeAutomationConfig` unrelated to our work. Agent restored it as a side-fix. This was confirmed pre-existing in WU1's CI output.
+
+---
+
+## Loop Meta-Learnings
+
+### Wave size = 1 was correct
+All 4 work units touched `bin/dam`. Sequential was the only safe option. No conflicts, no merge issues.
+
+### Agents produced clean rubocop output when not inheriting disables
+WU1 (no rubocop disables to inherit) was cleanest. WU2 produced clean output first-pass. WU3 and WU4 needed a second pass due to inherited directives — preventable with the "don't carry over disables" rule above.
+
+### 4 agents, all successful, no failures
+Every work unit completed in a single run (plus occasional second kfix for rubocop cleanup). AGENTS.md quality was sufficient — agents didn't get confused about which methods to move or which callers to update.

data/docs/planning/library-boundary-cleanup/AGENTS.md

@@ -0,0 +1,653 @@
+# AGENTS.md — AppyDave Tools / library-boundary-cleanup campaign
+
+> Operational knowledge for every background agent. Self-contained — you receive only this file + your work unit prompt.
+> Inherited from: extract-vat-cli campaign (2026-03-19)
+> Updated for: library-boundary-cleanup campaign (2026-03-19)
+
+---
+
+## Project Overview
+
+**What:** Ruby gem providing CLI productivity tools for AppyDave's YouTube content creation workflow.
+**Stack:** Ruby 3.4.2, Bundler 2.6.2, RSpec, RuboCop, semantic-release CI/CD.
+**Active campaign:** library-boundary-cleanup — fixing two boundary violations left by extract-vat-cli:
+  1. `exit 1` calls inside library code (S3ScanCommand + S3ArgParser)
+  2. `ENV['BRAND_PATH']` side-effect inside library argument parser (S3ArgParser)
+**Commits:** Trigger automated semantic versioning via GitHub Actions. Always use `kfeat`/`kfix` — never `git commit`.
+
+---
+
+## ⚠️ Pre-Commit Check (Mandatory Every Commit)
+
+Before running `kfix`, always run:
+```bash
+git status
+```
+Confirm ONLY the files you intentionally changed are staged. If unexpected files appear, run `git diff` to investigate before proceeding. Never commit files you didn't intentionally change.
+
+**Why:** Prior campaign accidentally staged a pre-existing uncommitted change when running `kfix`. Required a follow-up fix commit.
+
+---
+
+## Build & Run Commands
+
+```bash
+# Initialize rbenv (required if rbenv not in PATH)
+eval "$(rbenv init -)"
+
+# Run tests
+bundle exec rspec                           # All tests
+bundle exec rspec spec/path/to/file_spec.rb # Single file
+RUBYOPT="-W0" bundle exec rspec             # Suppress Ruby 3.4 platform warnings
+
+# Lint
+bundle exec rubocop --format clang          # Standard lint check (matches CI)
+
+# Commit (never use git commit directly)
+kfeat "add feature description"             # Minor version bump
+kfix "fix bug description"                  # Patch version bump
+```
+
+**Baseline (start of library-boundary-cleanup):** 847 examples, 0 failures, ~85.92% line coverage
+
+---
+
+## Directory Structure
+
+```
+bin/
+  dam                           Main DAM CLI entry point (VatCLI class — 1,600 lines, being reduced)
+exe/                            Thin wrappers for gem installation (no .rb extension)
+lib/appydave/tools/
+  dam/                          Digital Asset Management — main active area
+    brand_resolver.rb           Centralizes ALL brand name transformations (appydave ↔ v-appydave)
+    errors.rb                   Custom exception hierarchy — ADD UsageError here in B034
+    fuzzy_matcher.rb            Levenshtein distance for "did you mean?" suggestions
+    git_helper.rb               Extracted git command wrappers
+    file_helper.rb              File utility methods (format_size, calculate_directory_size, format_age)
+    config.rb                   Delegates brand resolution to BrandResolver; memoized Config loading
+    project_resolver.rb         Project name resolution with regex pattern matching
+    project_listing.rb          Table display for `dam list` command
+    s3_operations.rb            S3 upload/download/status with MD5 comparison
+    s3_scanner.rb               S3 bucket scanner for s3-scan command
+    status.rb                   Project git/S3 status display
+    manifest_generator.rb       Video project manifest
+    sync_from_ssd.rb            SSD sync operations
+    ssd_status.rb               SSD backup status
+    share_operations.rb         Pre-signed URL generation
+    config_loader.rb            Loads .video-tools.env per brand
+    local_sync_status.rb        Enriches project data with local s3-staging sync status
+    s3_scan_command.rb          S3 scan orchestration + display — HAS exit 1 AT LINE 55 (B034 target)
+    s3_arg_parser.rb            CLI argument parsing for S3 commands — HAS exit 1 + ENV side-effects (B034/B035 targets)
+lib/appydave/tools.rb           Require file — already includes s3_scan_command and s3_arg_parser
+spec/
+  appydave/tools/dam/           One spec file per dam/ class
+  support/
+    dam_filesystem_helpers.rb   Shared contexts for DAM filesystem testing
+```
+
+---
+
+## This Campaign: What We're Fixing
+
+### The Two Problems
+
+**Problem 1: `exit 1` in library code** — Library classes must not terminate the process. VatCLI's `rescue StandardError` already catches and prints errors. Fix: replace `exit 1` with typed exceptions.
+
+**Problem 2: `ENV['BRAND_PATH']` side-effect in library** — `S3ArgParser` sets a process-wide env var during argument parsing. Unsafe for parallelism. Fix: return `brand_path:` in result hash; move the `ENV[]=` call to VatCLI.
+
+### Work Unit Dependencies
+
+```
+B034: extract-exit-calls       (no deps — do first)
+B035: extract-env-side-effect  (DEPENDS ON B034 — both touch s3_arg_parser.rb)
+B036: tests-s3-scan-command    (DEPENDS ON B034 — can't test exceptions until they exist)
+B037: tests-local-sync-status  (no deps — but run after B035 for clean baseline)
+
+Wave 1: B034
+Wave 2: B035
+Wave 3: B036 + B037 (parallel — different spec files)
+```
+
+---
+
+## B034: extract-exit-calls
+
+**Files touched:** `lib/appydave/tools/dam/errors.rb`, `lib/appydave/tools/dam/s3_scan_command.rb`, `lib/appydave/tools/dam/s3_arg_parser.rb`
+
+### Step 1 — Add UsageError to errors.rb
+
+After the existing `GitOperationError` line, add:
+
+```ruby
+# Raised when CLI arguments are invalid or missing
+class UsageError < DamError; end
+```
+
+### Step 2 — Fix S3ScanCommand (line 55)
+
+Replace:
+```ruby
+unless File.exist?(manifest_path)
+  puts "❌ Manifest not found: #{manifest_path}"
+  puts "   Run: dam manifest #{brand_key}"
+  puts "   Then retry: dam s3-scan #{brand_key}"
+  exit 1
+end
+```
+
+With:
+```ruby
+unless File.exist?(manifest_path)
+  raise Appydave::Tools::Dam::ConfigurationError,
+        "Manifest not found: #{manifest_path}. Run: dam manifest #{brand_key}"
+end
+```
+
+Remove the `puts` lines above — the exception message carries the information. VatCLI's rescue prints it.
+
+### Step 3 — Fix S3ArgParser (4 exit locations)
+
+**parse_s3 — PWD auto-detect fail (around line 25):**
+
+Replace:
+```ruby
+if brand.nil? || project_id.nil?
+  puts '❌ Could not auto-detect brand/project from current directory'
+  puts "Usage: dam #{command} <brand> <project> [--dry-run]"
+  exit 1
+end
+```
+
+With:
+```ruby
+raise Appydave::Tools::Dam::UsageError,
+      "Could not auto-detect brand/project from current directory. Usage: dam #{command} <brand> <project> [--dry-run]" if brand.nil? || project_id.nil?
+```
+
+**parse_s3 — invalid brand (around line 43):**
+
+Replace:
+```ruby
+unless valid_brand?(brand_arg)
+  puts "❌ Invalid brand: '#{brand_arg}'"
+  puts ''
+  puts 'Valid brands:'
+  # ... puts lines ...
+  puts "Usage: dam #{command} <brand> <project> [--dry-run]"
+  exit 1
+end
+```
+
+With:
+```ruby
+unless valid_brand?(brand_arg)
+  raise Appydave::Tools::Dam::UsageError,
+        "Invalid brand: '#{brand_arg}'. Valid brands: appydave, voz, aitldr, kiros, joy, ss. Usage: dam #{command} <brand> <project> [--dry-run]"
+end
+```
+
+**parse_discover — missing args (around line 100):**
+
+Replace:
+```ruby
+if brand_arg.nil? || project_arg.nil?
+  puts 'Usage: dam s3-discover <brand> <project> [--shareable]'
+  # ... puts lines ...
+  exit 1
+end
+```
+
+With:
+```ruby
+raise Appydave::Tools::Dam::UsageError,
+      'Usage: dam s3-discover <brand> <project> [--shareable]' if brand_arg.nil? || project_arg.nil?
+```
+
+**show_share_usage_and_exit — rename and replace:**
+
+Rename the method to `raise_share_usage_error`. Replace:
+```ruby
+def show_share_usage_and_exit
+  puts 'Usage: dam s3-share ...'
+  # ... puts lines ...
+  exit 1
+end
+```
+
+With:
+```ruby
+def raise_share_usage_error
+  raise Appydave::Tools::Dam::UsageError,
+        'Usage: dam s3-share <brand> <project> <file> [--expires 7d] [--download]'
+end
+```
+
+Update the caller in `parse_share`:
+```ruby
+# Before:
+show_share_usage_and_exit if brand_arg.nil? || project_arg.nil? || file_arg.nil?
+# After:
+raise_share_usage_error if brand_arg.nil? || project_arg.nil? || file_arg.nil?
+```
+
+### Done when B034 is complete
+- `errors.rb` contains `UsageError < DamError`
+- 0 occurrences of `exit 1` in `s3_scan_command.rb` or `s3_arg_parser.rb`
+- `show_share_usage_and_exit` renamed to `raise_share_usage_error`
+- `bundle exec rubocop --format clang` → 0 offenses
+- `RUBYOPT="-W0" bundle exec rspec` → 847 examples, 0 failures (no new specs in this WU)
+- `git status` clean before `kfix`
+
+---
+
+## B035: extract-env-side-effect
+
+**Files touched:** `lib/appydave/tools/dam/s3_arg_parser.rb`, `bin/dam`
+
+**Prerequisite:** B034 complete.
+
+### Step 1 — Remove ENV side-effects from S3ArgParser
+
+In `parse_s3` (around line 51): remove `ENV['BRAND_PATH'] = ...`. Add `brand_path:` to returned hash:
+
+```ruby
+# Before:
+ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand)
+{ brand: brand_key, project: project_id, dry_run: dry_run, force: force }
+
+# After (auto-detect path):
+brand_path = Appydave::Tools::Dam::Config.brand_path(brand_key)
+{ brand: brand_key, project: project_id, dry_run: dry_run, force: force, brand_path: brand_path }
+```
+
+Note: In the `brand_arg.nil?` branch, `brand` is set from `ProjectResolver.detect_from_pwd` — use `brand` not `brand_arg` for path resolution there.
+
+In `parse_share` (around line 82): remove `ENV['BRAND_PATH'] = ...`. Add `brand_path:` to returned hash:
+
+```ruby
+# Before:
+ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand)
+{ brand: brand_key, project: project_id, file: file_arg, expires: expires, download: download }
+
+# After:
+brand_path = Appydave::Tools::Dam::Config.brand_path(brand)
+{ brand: brand_key, project: project_id, file: file_arg, expires: expires, download: download, brand_path: brand_path }
+```
+
+In `parse_discover` (around line 108): same pattern:
+
+```ruby
+# Before:
+ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand)
+{ brand_key: brand_key, project_id: project_id, shareable: shareable }
+
+# After:
+brand_path = Appydave::Tools::Dam::Config.brand_path(brand)
+{ brand_key: brand_key, project_id: project_id, shareable: shareable, brand_path: brand_path }
+```
+
+### Step 2 — Update VatCLI callers in bin/dam
+
+Search for every call to `S3ArgParser.parse_s3`, `S3ArgParser.parse_share`, `S3ArgParser.parse_discover` in `bin/dam`. After each call, add:
+
+```ruby
+options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-up')
+ENV['BRAND_PATH'] = options[:brand_path]
+```
+
+Same pattern for `parse_share` and `parse_discover` callers.
+
+**Affected VatCLI methods** (grep `S3ArgParser` in bin/dam to confirm):
+- `s3_up_command` → uses `parse_s3`
+- `s3_down_command` → uses `parse_s3`
+- `s3_status_command` → uses `parse_s3`
+- `s3_cleanup_remote_command` → uses `parse_s3`
+- `s3_cleanup_local_command` → uses `parse_s3`
+- `archive_command` → uses `parse_s3`
+- `s3_share_command` → uses `parse_share`
+- `s3_discover_command` → uses `parse_discover`
+
+### Done when B035 is complete
+- 0 occurrences of `ENV['BRAND_PATH'] =` in `s3_arg_parser.rb`
+- All 3 parse methods return `brand_path:` in their result hash
+- All VatCLI callers set `ENV['BRAND_PATH'] = options[:brand_path]` after parsing
+- `bundle exec rubocop --format clang` → 0 offenses
+- `RUBYOPT="-W0" bundle exec rspec` → 847 examples, 0 failures
+- `git status` clean before `kfix`
+
+---
+
+## B036: tests-s3-scan-command
+
+**File touched:** `spec/appydave/tools/dam/s3_scan_command_spec.rb`
+
+**Prerequisite:** B034 complete (exceptions must exist before testing them).
+
+Current state: 2 smoke tests (`respond_to` checks). Replace with real behaviour tests.
+
+### Target: 8–10 examples covering
+
+```ruby
+RSpec.describe Appydave::Tools::Dam::S3ScanCommand do
+  include_context 'with vat filesystem and brands', brands: %w[appydave]
+
+  let(:scanner) { described_class.new }
+  let(:brand_key) { 'appydave' }
+
+  before do
+    allow(Appydave::Tools::Dam::S3Scanner).to receive(:new).and_return(mock_s3_scanner)
+    allow(Appydave::Tools::Configuration::Config).to receive(:configure)
+    allow(Appydave::Tools::Configuration::Config).to receive(:brands).and_return(mock_brands_config)
+  end
+
+  describe '#scan_single' do
+    context 'when manifest exists and S3 returns results' do
+      # Write a fixture projects.json to brand_path
+      # Mock scanner.scan_all_projects to return { 'b65-test' => { file_count: 3, total_bytes: 1000, last_modified: '...' } }
+      # Expect: manifest updated, updated_count == 1, no error
+    end
+
+    context 'when manifest not found' do
+      # Do NOT write projects.json
+      # Mock scanner to return results
+      # expect { scanner.scan_single(brand_key) }.to raise_error(Appydave::Tools::Dam::ConfigurationError, /Manifest not found/)
+    end
+
+    context 'when S3 returns empty results' do
+      # Mock scanner.scan_all_projects to return {}
+      # Expect: early return (no raise, no manifest write)
+    end
+
+    context 'when S3 has orphaned projects' do
+      # projects.json has ['b65-test'], S3 returns { 'b65-test' => ..., 'b99-orphan' => ... }
+      # Expect: orphaned_projects contains 'b99-orphan', matched_projects contains 'b65-test'
+    end
+  end
+
+  describe '#scan_all' do
+    context 'when one brand fails' do
+      # brands_config.brands returns [appydave, voz]
+      # scan_single raises for voz
+      # Expect: results array has appydave success: true, voz success: false
+      # Expect: no re-raise (scan_all rescues per-brand)
+    end
+  end
+end
+```
+
+**Fixture pattern for projects.json:**
+```ruby
+manifest = {
+  config: { last_updated: Time.now.utc.iso8601, note: 'test' },
+  projects: [{ id: 'b65-test-project', storage: { s3: {} } }]
+}
+File.write(File.join(brand_path, 'projects.json'), JSON.generate(manifest))
+```
+
+### Done when B036 is complete
+- `spec/appydave/tools/dam/s3_scan_command_spec.rb` has 8+ real behaviour examples
+- `respond_to` smoke tests removed or replaced
+- `RUBYOPT="-W0" bundle exec rspec` → 855+ examples, 0 failures
+- `bundle exec rubocop --format clang` → 0 offenses
+- `git status` clean before `kfix`
+
+---
+
+## B037: tests-local-sync-status
+
+**File touched:** `spec/appydave/tools/dam/local_sync_status_spec.rb`
+
+**No prerequisites** — but run after B035 for clean baseline.
+
+### Gaps to fill
+
+**1. `:partial` case in `#enrich!`**
+
+Set up `s3-staging` folder with 2 files but `file_count: 3` in S3 data:
+```ruby
+context 'when local s3-staging has fewer files than S3' do
+  before do
+    FileUtils.mkdir_p(File.join(appydave_path, 'b65-test', 's3-staging'))
+    FileUtils.touch(File.join(appydave_path, 'b65-test', 's3-staging', 'file1.mp4'))
+    FileUtils.touch(File.join(appydave_path, 'b65-test', 's3-staging', 'file2.mp4'))
+  end
+
+  it 'sets status to :partial' do
+    matched = { 'b65-test' => { file_count: 3 } }
+    described_class.enrich!(matched, 'appydave')
+    expect(matched['b65-test'][:local_status]).to eq(:partial)
+  end
+
+  it 'sets local_file_count to 2' do
+    matched = { 'b65-test' => { file_count: 3 } }
+    described_class.enrich!(matched, 'appydave')
+    expect(matched['b65-test'][:local_file_count]).to eq(2)
+  end
+end
+```
+
+**2. `local_file_count` assertion in existing `:synced` test**
+
+Find the existing synced context and add:
+```ruby
+it 'sets local_file_count correctly' do
+  expect(data[:local_file_count]).to eq(3) # adjust to match your fixture
+end
+```
+
+**3. Zone.Identifier exclusion**
+
+Windows NTFS streams appear as `filename:Zone.Identifier` in samba mounts. These must NOT count as local files:
+```ruby
+context 'when s3-staging contains Zone.Identifier files' do
+  before do
+    FileUtils.mkdir_p(File.join(appydave_path, 'b65-test', 's3-staging'))
+    FileUtils.touch(File.join(appydave_path, 'b65-test', 's3-staging', 'file1.mp4'))
+    FileUtils.touch(File.join(appydave_path, 'b65-test', 's3-staging', 'file1.mp4:Zone.Identifier'))
+    FileUtils.touch(File.join(appydave_path, 'b65-test', 's3-staging', 'file2.mp4'))
+  end
+
+  it 'excludes Zone.Identifier files from local_file_count' do
+    matched = { 'b65-test' => { file_count: 2 } }
+    described_class.enrich!(matched, 'appydave')
+    expect(matched['b65-test'][:local_file_count]).to eq(2)
+    expect(matched['b65-test'][:local_status]).to eq(:synced)
+  end
+end
+```
+
+**4. Unknown status guard in `#format`**
+
+```ruby
+describe '.format' do
+  it 'returns Unknown for unrecognised status' do
+    expect(described_class.format(:unknown, nil, 0)).to eq('Unknown')
+  end
+end
+```
+
+Check the actual `format` implementation first — if it already has an `else` branch returning `'Unknown'`, this is a documentation test. If it has no `else`, add one to `local_sync_status.rb` before writing this spec.
+
+### Done when B037 is complete
+- `:partial` case tested with `local_file_count` assertion
+- `:synced` case has `local_file_count` assertion
+- `Zone.Identifier` exclusion tested
+- `format(:unknown, ...)` tested
+- `RUBYOPT="-W0" bundle exec rspec` → 851+ examples, 0 failures
+- `bundle exec rubocop --format clang` → 0 offenses
+- `git status` clean before `kfix`
+
+---
+
+## Success Criteria (Every Work Unit)
+
+Every work unit must satisfy ALL of the following before marking `[x]`:
+
+- [ ] `RUBYOPT="-W0" bundle exec rspec` — 847+ examples, 0 failures (rising with each WU)
+- [ ] `bundle exec rubocop --format clang` — 0 offenses
+- [ ] Line coverage stays ≥ 85.92%
+- [ ] Any new `.rb` files start with `# frozen_string_literal: true`
+- [ ] `git status` confirmed clean before `kfix`
+
+---
+
+## Reference Patterns
+
+### Shared Context for DAM Specs — THE STANDARD PATTERN
+
+```ruby
+# spec/appydave/tools/dam/some_class_spec.rb
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Appydave::Tools::Dam::SomeClass do
+  include_context 'with vat filesystem and brands', brands: %w[appydave voz]
+
+  before do
+    FileUtils.mkdir_p(File.join(appydave_path, 'b65-test-project'))
+  end
+
+  describe '.some_method' do
+    it 'does the thing' do
+      expect(described_class.some_method('appydave')).to eq('expected')
+    end
+  end
+end
+```
+
+**Available from shared context:**
+- `temp_folder` — temp root (auto-cleaned after each example)
+- `projects_root` — `/path/to/temp/video-projects`
+- `appydave_path`, `voz_path`, etc. — brand dirs (created on demand)
+- `SettingsConfig#video_projects_root` is mocked to return `projects_root`
+
+### FileHelper — Use These, Don't Duplicate
+
+```ruby
+Appydave::Tools::Dam::FileHelper.format_size(bytes)             # "1.5 GB"
+Appydave::Tools::Dam::FileHelper.calculate_directory_size(path) # Integer bytes
+Appydave::Tools::Dam::FileHelper.format_age(time)               # "3d", "2w", etc.
+```
+
+### BrandResolver — All Brand Name Transformations
+
+```ruby
+BrandResolver.expand('appydave')      # => 'v-appydave'
+BrandResolver.expand('ad')            # => 'v-appydave' (shortcut)
+BrandResolver.normalize('v-appydave') # => 'appydave'
+BrandResolver.validate('appydave')    # => 'appydave' or raises BrandNotFoundError
+```
+
+### Typed Exception Pattern
+
+```ruby
+raise Appydave::Tools::Dam::ConfigurationError, 'Manifest not found: /path'
+raise Appydave::Tools::Dam::UsageError, 'Usage: dam s3-up <brand> <project>'
+raise ProjectNotFoundError, 'Project name is required' if project_hint.nil?
+raise BrandNotFoundError.new(brand, available_brands, fuzzy_suggestions)
+```
+
+### Config.brand_path — Correct Call
+
+```ruby
+# brand_key is the short form ('appydave'), brand is expanded ('v-appydave')
+brand_path = Appydave::Tools::Dam::Config.brand_path(brand_key)
+# OR:
+brand_path = Appydave::Tools::Dam::Config.brand_path(brand)
+# Both work — Config.brand_path resolves via BrandResolver internally
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ `exit 1` in library code — use typed exceptions from `errors.rb` instead
+- ❌ `ENV['BRAND_PATH'] = ...` in library code — return `brand_path:` in result hash; set ENV in VatCLI
+- ❌ Inline brand transformations — never write `"v-#{brand}"` outside BrandResolver
+- ❌ `format_bytes` — does not exist; use `FileHelper.format_size`
+- ❌ Mocking Config class methods in DAM specs — use shared filesystem context instead
+- ❌ Multiple `before` blocks in same RSpec context — merge them (triggers RSpec/ScatteredSetup)
+- ❌ `$?` for subprocess status — use `$CHILD_STATUS` (rubocop Style/SpecialGlobalVars)
+- ❌ `raise 'string error'` in DAM module — use typed exceptions from `errors.rb`
+- ❌ `include FileUtils` — use dam's `FileHelper` instead
+- ❌ Hardcoded header strings for table output — always use `format()` matching data row format
+- ❌ Adding new `Config.configure` calls — memoized but called redundantly; don't spread further
+
+---
+
+## Mock Patterns
+
+### ENV Stubbing (if needed in specs)
+
+```ruby
+allow(ENV).to receive(:[]).and_call_original
+allow(ENV).to receive(:[]).with('BRAND_PATH').and_return('/tmp/test/v-appydave')
+```
+
+**Do NOT use climate_control gem** — project doesn't have it.
+
+### S3Scanner Mocking (for B036)
+
+```ruby
+let(:mock_s3_scanner) { instance_double(Appydave::Tools::Dam::S3Scanner) }
+
+before do
+  allow(Appydave::Tools::Dam::S3Scanner).to receive(:new).with(brand_key).and_return(mock_s3_scanner)
+  allow(mock_s3_scanner).to receive(:scan_all_projects).and_return({
+    'b65-test-project' => { file_count: 3, total_bytes: 1_500_000, last_modified: '2025-01-01T00:00:00Z' }
+  })
+end
+```
+
+### Config::Brands Mocking (for B036 scan_all)
+
+```ruby
+let(:mock_brands_config) { instance_double(Appydave::Tools::Configuration::BrandsConfig) }
+let(:mock_brand_info) { instance_double(Appydave::Tools::Configuration::BrandInfo, key: 'appydave') }
+
+before do
+  allow(mock_brands_config).to receive(:brands).and_return([mock_brand_info])
+end
+```
+
+---
+
+## Quality Gates
+
+- **Tests:** `RUBYOPT="-W0" bundle exec rspec` — 847+ examples, 0 failures
+- **Lint:** `bundle exec rubocop --format clang` — 0 offenses (CI will reject)
+- **Coverage:** ≥ 85.92% line coverage
+- **frozen_string_literal:** Required on every new `.rb` file
+- **Commit format:** `kfeat`/`kfix` only — triggers semantic versioning + CI wait
+- **Pre-commit:** Always run `git status` before `kfix` — confirm staged files
+
+---
+
+## Learnings
+
+### From DAM Enhancement Sprint (Jan 2025)
+
+- **BrandResolver is the critical path.** All `dam` commands flow through it. Any change to brand resolution must be tested with all shortcuts.
+- **`Regexp.last_match` is reset by `.sub()` calls.** Always capture regex groups BEFORE any string transformation.
+- **`Config.configure` is memoized but called redundantly.** Don't add new calls.
+- **Table format() pattern is non-obvious.** Headers misaligned 3 times in UAT. Always verify with real data.
+
+### From micro-cleanup (2026-03-19)
+
+- **Dirty working tree + kfix = accidental staging.** Always run `git status` before committing.
+- **Pre-existing "already fixed" items:** Check B-items aren't already done before acting (B031, B033, B015, B019 were all already committed).
+
+### From Architectural Review (2026-03-19)
+
+- **bin/dam is the primary DAM CLI entry point.** Regressions here affect real workflows. Test every command path after extraction.
+- **`ENV['BRAND_PATH']` is set in 5 places in bin/dam.** Three are in parse methods (being extracted to B035). Two remain in `generate_single_manifest` and `sync_ssd_command` — out of scope for this campaign.
+- **Do NOT attempt B020 (split S3Operations) in this campaign.** Different class, different risk profile.
+
+### From extract-vat-cli (2026-03-19)
+
+- **valid_brand? needs Config.brands mock.** The shared filesystem context only mocks `SettingsConfig`. When testing code that calls `Config.brands`, mock it separately: `allow(Appydave::Tools::Configuration::Config).to receive(:brands).and_return(...)`.
+- **rubocop-disable directives become redundant when methods move.** After extracting to a library class, check the VatCLI file for orphaned disable/enable pairs and remove them.
+- **VatCLI rescue blocks already catch StandardError.** No changes to VatCLI rescue needed when replacing `exit 1` with exceptions — the existing rescue chain handles it.
+- **S3ScanCommand#scan_all already rescues per-brand.** The `rescue StandardError` inside `scan_all` means per-brand failures are isolated. Once `scan_single` raises instead of calling `exit`, `scan_all` catches it correctly — no structural change needed.

data/docs/planning/library-boundary-cleanup/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,61 @@
+# IMPLEMENTATION_PLAN.md — library-boundary-cleanup
+
+**Goal**: Fix two architectural boundary violations introduced by extract-vat-cli, then fill the test gaps they blocked. Prerequisite for B007 (parallelism) and clean library boundaries.
+**Started**: 2026-03-19
+**Target**: 4 items complete; 847+ examples passing; rubocop 0 offenses; no regressions
+
+## Summary
+- Total: 4 | Complete: 0 | In Progress: 1 | Pending: 3 | Failed: 0
+
+## Pending
+- [ ] B035 — extract-env-side-effect — Remove `ENV['BRAND_PATH']` side-effect from S3ArgParser; return `brand_path:` in result hash; update VatCLI callers (DEPENDS ON B034)
+- [ ] B036 — tests-s3-scan-command — Rebuild S3ScanCommand spec from D-grade to B; 8–10 examples covering happy path, manifest missing, empty results, orphaned projects (DEPENDS ON B034)
+- [ ] B037 — tests-local-sync-status — Add :partial case, local_file_count assertion, Zone.Identifier exclusion, unknown format guard
+
+## In Progress
+- [~] B034 — extract-exit-calls — Replace `exit 1` with typed exceptions in S3ScanCommand + S3ArgParser; add `UsageError` to errors.rb
+
+## Complete
+
+## Failed / Needs Retry
+
+## Notes & Decisions
+
+### Wave Plan
+
+**Wave 1 — B034** (alone)
+- Touches: `s3_scan_command.rb`, `s3_arg_parser.rb`, `errors.rb`
+- No parallel candidates — all three files must be edited together
+
+**Wave 2 — B035** (after B034)
+- Touches: `s3_arg_parser.rb`, `bin/dam`
+- Cannot run with B034 (shared `s3_arg_parser.rb`)
+- No behaviour change — moves ENV side-effect to CLI layer only
+
+**Wave 3 — B036 + B037** (parallel — different spec files, no shared edits)
+- B036: `spec/appydave/tools/dam/s3_scan_command_spec.rb`
+- B037: `spec/appydave/tools/dam/local_sync_status_spec.rb`
+- Both depend on B034 being complete (exceptions must exist before testing them)
+
+### Sequencing Constraints
+- B034 must complete before B035 (both touch s3_arg_parser.rb)
+- B034 must complete before B036 (can't test raised exceptions until they exist)
+- B035 must complete before B036 + B037 (ENV side-effect removal may affect test setup)
+- B036 and B037 are fully parallel once B034 + B035 are done
+
+### Exit Locations Confirmed (read 2026-03-19)
+- `S3ScanCommand#scan_single` line 55: manifest not found → raise `ConfigurationError`
+- `S3ArgParser#parse_s3` line 25: PWD auto-detect fail → raise `UsageError`
+- `S3ArgParser#parse_s3` line 43: invalid brand → raise `UsageError`
+- `S3ArgParser#parse_discover` line 100: missing brand/project args → raise `UsageError`
+- `S3ArgParser#show_share_usage_and_exit` line 131: missing share args → raise `UsageError`
+
+### ENV Side-Effect Locations Confirmed (read 2026-03-19)
+- `S3ArgParser#parse_s3` line 51: `ENV['BRAND_PATH'] = ...`
+- `S3ArgParser#parse_share` line 82: `ENV['BRAND_PATH'] = ...`
+- `S3ArgParser#parse_discover` line 108: `ENV['BRAND_PATH'] = ...`
+- Fix: return `brand_path:` in each result hash; update VatCLI callers to set ENV there
+
+### VatCLI Rescue Blocks
+- `s3_scan_command`, `s3_up_command`, etc. already rescue `StandardError => e` and `puts "❌ Error: #{e.message}"`
+- No VatCLI rescue changes needed for B034 — existing rescues already catch DamError (which inherits from StandardError)

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

@@ -34,6 +34,9 @@ module Appydave
 
       # Raised when git operation fails
       class GitOperationError < DamError; end
+
+      # Raised when CLI arguments are invalid or missing
+      class UsageError < DamError; end
     end
   end
 end

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

@@ -20,26 +20,15 @@ module Appydave
             # Auto-detect from PWD
             brand, project_id = Appydave::Tools::Dam::ProjectResolver.detect_from_pwd
             if brand.nil? || project_id.nil?
-              puts '❌ Could not auto-detect brand/project from current directory'
-              puts "Usage: dam #{command} <brand> <project> [--dry-run]"
-              exit 1
+              raise Appydave::Tools::Dam::UsageError,
+                    "Could not auto-detect brand/project from current directory. Usage: dam #{command} <brand> <project> [--dry-run]"
             end
             brand_key = brand # Already detected, use as-is
           else
             # Validate brand exists before trying to resolve project
             unless valid_brand?(brand_arg)
-              puts "❌ Invalid brand: '#{brand_arg}'"
-              puts ''
-              puts 'Valid brands:'
-              puts '  appydave  → v-appydave         (AppyDave brand)'
-              puts '  voz       → v-voz              (VOZ client)'
-              puts '  aitldr    → v-aitldr           (AITLDR brand)'
-              puts '  kiros     → v-kiros            (Kiros client)'
-              puts '  joy       → v-beauty-and-joy   (Beauty & Joy)'
-              puts '  ss        → v-supportsignal    (SupportSignal)'
-              puts ''
-              puts "Usage: dam #{command} <brand> <project> [--dry-run]"
-              exit 1
+              raise Appydave::Tools::Dam::UsageError,
+                    "Invalid brand: '#{brand_arg}'. Valid brands: appydave, voz, aitldr, kiros, joy, ss. Usage: dam #{command} <brand> <project> [--dry-run]"
             end
 
             brand_key = brand_arg # Use the shortcut/key (e.g., 'appydave')
@@ -72,7 +61,7 @@ module Appydave
           project_arg = args[1]
           file_arg = args[2]
 
-          show_share_usage_and_exit if brand_arg.nil? || project_arg.nil? || file_arg.nil?
+          raise_share_usage_error if brand_arg.nil? || project_arg.nil? || file_arg.nil?
 
           brand_key = brand_arg
           brand = Appydave::Tools::Dam::Config.expand_brand(brand_arg)
@@ -92,12 +81,8 @@ module Appydave
           project_arg = args[1]
 
           if brand_arg.nil? || project_arg.nil?
-            puts 'Usage: dam s3-discover <brand> <project> [--shareable]'
-            puts ''
-            puts 'Examples:'
-            puts '  dam s3-discover appydave b70              # List files'
-            puts '  dam s3-discover appydave b70 --shareable  # Generate share commands'
-            exit 1
+            raise Appydave::Tools::Dam::UsageError,
+                  'Usage: dam s3-discover <brand> <project> [--shareable]'
           end
 
           brand_key = brand_arg
@@ -116,19 +101,9 @@ module Appydave
           brands.key?(brand_key) || brands.shortcut?(brand_key)
         end
 
-        def show_share_usage_and_exit
-          puts 'Usage: dam s3-share <brand> <project> <file> [--expires 7d] [--download]'
-          puts ''
-          puts 'Options:'
-          puts '  --expires TIME    Expiry time (default: 7d)'
-          puts '  --download        Force download instead of viewing in browser'
-          puts ''
-          puts 'Examples:'
-          puts '  dam s3-share appydave b70 video.mp4'
-          puts '  dam s3-share appydave b70 video.mp4 --expires 24h'
-          puts '  dam s3-share appydave b70 video.mp4 --download'
-          puts '  dam s3-share voz boy-baker final-edit.mov --expires 3d --download'
-          exit 1
+        def raise_share_usage_error
+          raise Appydave::Tools::Dam::UsageError,
+                'Usage: dam s3-share <brand> <project> <file> [--expires 7d] [--download]'
         end
       end
     end

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

@@ -49,10 +49,8 @@ module Appydave
           manifest_path = File.join(brand_path, 'projects.json')
 
           unless File.exist?(manifest_path)
-            puts "❌ Manifest not found: #{manifest_path}"
-            puts "   Run: dam manifest #{brand_key}"
-            puts "   Then retry: dam s3-scan #{brand_key}"
-            exit 1
+            raise Appydave::Tools::Dam::ConfigurationError,
+                  "Manifest not found: #{manifest_path}. Run: dam manifest #{brand_key}"
           end
 
           manifest = JSON.parse(File.read(manifest_path), symbolize_names: true)

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.76.7'
+    VERSION = '0.76.8'
   end
 end

data/package.json

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appydave-tools
 version: !ruby/object:Gem::Version
-  version: 0.76.7
+  version: 0.76.8
 platform: ruby
 authors:
 - David Cruwys
@@ -302,12 +302,16 @@ files:
 - docs/planning/bugfix-and-security/assessment.md
 - docs/planning/extract-vat-cli/AGENTS.md
 - docs/planning/extract-vat-cli/IMPLEMENTATION_PLAN.md
+- docs/planning/extract-vat-cli/assessment.md
+- docs/planning/extract-vat-cli/learnings/wave-learnings.md
 - docs/planning/final-test-gaps/AGENTS.md
 - docs/planning/final-test-gaps/IMPLEMENTATION_PLAN.md
 - docs/planning/final-test-gaps/assessment.md
 - docs/planning/fr2-gpt-context-help/AGENTS.md
 - docs/planning/fr2-gpt-context-help/IMPLEMENTATION_PLAN.md
 - docs/planning/fr2-gpt-context-help/assessment.md
+- docs/planning/library-boundary-cleanup/AGENTS.md
+- docs/planning/library-boundary-cleanup/IMPLEMENTATION_PLAN.md
 - docs/planning/micro-cleanup/AGENTS.md
 - docs/planning/micro-cleanup/IMPLEMENTATION_PLAN.md
 - docs/planning/micro-cleanup/assessment.md