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 869 tests   1 869 ✅  0s ⏱️
    1 suites      0 💤
    1 files        0 ❌

Results for commit 93a8ba3.

♻️ This comment has been updated with latest results.

[dlpierce]

Thanks for this!