docs: document file ingest and characterization flows

[orangewolf]

Summary

• Adds documentation/file-ingest-characterization.md — a developer-oriented reference covering the complete file ingest, characterization, and derivative-generation pipeline in Hyrax.
• Documents both the ActiveFedora actor-stack path (actors → AttachFilesToWorkJob → FileSetActor → IngestJob → FileActor → CharacterizeJob → CreateDerivativesJob) and the Valkyrie transaction path (WorkCreate transaction → Steps::AddFileSets → WorkUploadsHandler → ValkyrieIngestJob → ValkyrieUpload → ValkyrieCharacterizationJob → ValkyrieCreateDerivativesJob).
• Covers the event system (Dry::Events/Hyrax.publisher) that decouples ingest stages in the Valkyrie path.
• Documents Wings as the AF ↔ Valkyrie bridge and the dispatch points where the two paths diverge (AttachFilesToWorkJob, FileListener).
• Includes concrete class/file references, configuration knobs, and a Developer Cautions section on known footguns (characterization metadata clearing, io.use_valkyrie = false, idempotency guard gaps, disk_path requirements, listener registration).

Verification

• All source files referenced in the doc were confirmed to exist in the repo via glob/grep before committing.
• git diff --check on the new file returned no whitespace errors.
• No application code was modified; this is documentation only.

Commands to verify

# Confirm file exists
ls documentation/file-ingest-characterization.md

# Spot-check key source references
ls app/actors/hyrax/actors/file_actor.rb
ls app/jobs/valkyrie_ingest_job.rb
ls app/services/hyrax/work_uploads_handler.rb
ls lib/hyrax/transactions/steps/add_file_sets.rb
ls app/services/hyrax/listeners/file_listener.rb

🤖 Generated with Claude Code

[github-actions]

Test Results

    1 files   -     16      1 suites   - 16   0s ⏱️ - 3h 28m 41s
1 839 tests  -  5 500  1 839 ✅  -  5 194  0 💤  - 306  0 ❌ ±0 
1 839 runs   - 22 855  1 839 ✅  - 22 264  0 💤  - 591  0 ❌ ±0 

Results for commit 38f5e72. ± Comparison against base commit b7a1c55.