Plan simulation mode and drop docs zip checksum

.github/workflows/build.yml

@@ -87,16 +87,12 @@ jobs:
           ARCHIVE="alchemist-website-${{ steps.ver.outputs.version }}.zip"
           cd build
           zip -r "../${ARCHIVE}" .
-          cd ..
-          sha256sum "${ARCHIVE}" > "${ARCHIVE}.sha256"
 
       - name: Upload docs artifact
         uses: actions/upload-artifact@v4
         with:
           name: alchemist-website
-          path: |
-            alchemist-website-${{ steps.ver.outputs.version }}.zip
-            alchemist-website-${{ steps.ver.outputs.version }}.zip.sha256
+          path: alchemist-website-${{ steps.ver.outputs.version }}.zip
 
   build-frontend:
     runs-on: ubuntu-latest

040.md

@@ -0,0 +1,322 @@
+# 040 — Product Planning: Simulation, Library Intelligence, and Decision Clarity
+
+## Priority Summary
+
+| Initiative | Priority | Intent |
+|---|---:|---|
+| Planning / simulation mode | 10/10 | Highest-value next feature |
+| Library intelligence | 6/10 | Strong medium-term differentiator |
+| Clearer skip / failure detail | 5/10 | Trust and diagnosability improvement |
+| Media server integration | 1/10 | Explicitly deferred |
+
+## Recommended Order
+
+1. Planning / simulation mode
+2. Clearer skip / failure detail
+3. Library intelligence
+4. Media server integration
+
+This order is intentional. Simulation mode depends on stronger
+decision explainability, and library intelligence becomes much
+more useful once its recommendations can be previewed in a
+simulation workflow. Media server integration should stay
+deferred until the decision engine and operator trust surfaces
+are stronger.
+
+## 1. Planning / Simulation Mode (10/10)
+
+## Goal
+
+Let users answer:
+
+- "If I point Alchemist at this library, what would it do?"
+- "How much space would I likely save?"
+- "What would be skipped, remuxed, or transcoded, and why?"
+- "What changes if I switch profiles, codec targets, or thresholds?"
+
+This must work **without performing encodes** and without
+mutating the library.
+
+## Product Shape
+
+Simulation mode should exist as a first-class operator flow,
+not as a hidden debug feature.
+
+### Core outputs
+
+- Estimated total bytes recoverable
+- Count of files by action:
+  - transcode
+  - remux
+  - skip
+  - undecidable / analysis failed
+- Breakdown by codec, resolution, and top-level library path
+- Top reasons for skips
+- A browsable table of per-file predicted actions
+
+### Comparison use cases
+
+- Compare current settings vs proposed settings
+- Compare one profile vs another on the same path set
+- Compare codec targets (AV1 vs HEVC vs H.264)
+
+## Implementation Direction
+
+### Backend
+
+- Add a dedicated simulation pipeline that reuses:
+  - scanner
+  - FFprobe analyzer
+  - planner
+- It must stop before executor / post-encode stages.
+- The planner output needs a richer serializable result for
+  simulation than the current job-facing decision strings.
+
+### Required backend additions
+
+- A stable "predicted action" model:
+  - action
+  - reason code
+  - human explanation
+  - source metadata summary
+  - estimated output codec / container
+  - estimated size delta or "unknown"
+- A size-estimation layer:
+  - start with a heuristic estimate
+  - explicitly surface confidence level
+  - do not pretend precision where the estimate is weak
+- A simulation run record:
+  - run id
+  - created at
+  - settings snapshot or profile snapshot
+  - scanned roots
+  - aggregate totals
+
+### UI
+
+- Add a dedicated simulation entry point in the app, not buried
+  inside settings.
+- Simulation results page should include:
+  - headline savings estimate
+  - action distribution
+  - skip reason distribution
+  - per-library/profile breakdown
+  - per-file result table with filters
+- Add "compare against current settings" as the default mode.
+
+## Non-goals for v1
+
+- No automatic queue population from simulation results
+- No exact final output-size promise
+- No live streaming simulation as files are analyzed unless it
+  falls out naturally from existing SSE patterns
+
+## Acceptance Criteria
+
+- A user can run a simulation on configured library roots.
+- The system returns aggregate predicted savings and per-file
+  decisions without starting any encode jobs.
+- Results can be filtered by action and reason.
+- Results can be compared across two settings/profile snapshots.
+
+## 2. Clearer Skip / Failure Detail (5/10)
+
+## Goal
+
+Make every skip and failure immediately understandable without
+forcing the user to inspect raw FFmpeg logs or machine-oriented
+reason strings.
+
+## Product Shape
+
+### Skip detail
+
+- Show:
+  - machine reason code
+  - plain-English explanation
+  - relevant threshold values
+  - current measured values
+  - direct "what to change" guidance when applicable
+
+### Failure detail
+
+- Distinguish:
+  - probe/analyze failure
+  - planner rejection
+  - encoder availability failure
+  - FFmpeg execution failure
+  - output validation failure
+  - promotion/replacement failure
+
+### UI surfacing
+
+- Jobs list should summarize failure/skip class at a glance.
+- Job detail panel should show:
+  - concise summary first
+  - technical detail second
+  - full logs last
+
+## Implementation Direction
+
+### Backend
+
+- Replace loose reason-string-only semantics with a structured
+  decision/failure model that includes:
+  - code
+  - summary
+  - detail
+  - measured values
+  - suggested operator action
+- Keep storing the machine-readable code for compatibility, but
+  derive a richer payload for UI/API consumption.
+
+### UI
+
+- Add dedicated rendering for common skip/failure classes instead
+  of generic log dumps.
+- Add copyable raw technical detail for debugging/reporting.
+
+## Acceptance Criteria
+
+- A skipped file tells the user exactly which threshold blocked
+  it and what the measured values were.
+- A failed file shows the failing stage and the shortest useful
+  explanation before the raw logs.
+
+## 3. Library Intelligence (6/10)
+
+## Goal
+
+Expand Alchemist from "good transcode decisions" to "library
+optimization intelligence."
+
+## What belongs here
+
+- Duplicate / alternate-version detection
+- Wasteful container detection
+- Remux-only opportunities
+- Suspicious audio layout detection
+- Subtitle pathology detection
+- Probably-corrupt / low-value file identification beyond the
+  current Library Doctor checks
+
+This should remain focused on **storage and media-library
+quality**, not become a general media manager.
+
+## Recommended Scope for v1
+
+### Opportunity classes
+
+- Remux-only savings candidates
+- Files with excessive audio tracks relative to likely use
+- Files with commentary / descriptive tracks that stream rules
+  would strip
+- Duplicate-ish files in the same title folder
+- Container mismatch cases where playback or size can improve
+  without full transcode
+
+### Product form
+
+- Add an "Intelligence" or "Recommendations" surface
+- Present findings as actionable recommendations, not passive
+  diagnostics
+- Allow filtering by confidence and recommendation class
+
+## Implementation Direction
+
+### Backend
+
+- Add a recommendation engine layer separate from the core
+  transcode planner.
+- Reuse analyzer metadata and library indexing information.
+- Recommendations should carry:
+  - type
+  - confidence
+  - explanation
+  - suggested action
+  - whether the action is already automatable by Alchemist
+
+### Relationship to simulation mode
+
+- Simulation mode should be able to include intelligence-backed
+  recommendation counts and projected savings.
+- Library intelligence should not block simulation v1, but its
+  data model should be compatible with it.
+
+## Acceptance Criteria
+
+- The app can surface recommendation classes with clear operator
+  value.
+- Recommendations are filterable and do not require reading raw
+  metadata dumps.
+
+## 4. Media Server Integration (1/10)
+
+## Position
+
+Deliberately deferred.
+
+This is low-priority until:
+
+- simulation mode exists
+- decision transparency improves
+- library intelligence is useful enough to justify tighter
+  ecosystem coupling
+
+## Minimal future direction
+
+When revisited, the first integration scope should be:
+
+- library refresh / rescan hooks for Plex/Jellyfin/Emby
+- avoid working on active streams
+- optional priority hints from watch activity
+
+Do **not** start with deep account linking, OAuth, or broad
+server-side orchestration.
+
+## Cross-Cutting Requirements
+
+## Data model discipline
+
+- Prefer structured decision/recommendation payloads over freeform
+  strings
+- Preserve compatibility with current job/decsion storage where
+  possible
+- New UI/API surfaces should be designed around stable codes,
+  not brittle text parsing
+
+## Performance expectations
+
+- Simulation and intelligence work must be bounded and measurable
+- Expensive operations should be reusable across:
+  - scans
+  - simulation runs
+  - recommendation generation
+
+## UX expectations
+
+- Always lead with "what happened / what would happen"
+- Show operator value first, implementation detail second
+
+## Concrete Next Milestone
+
+## Milestone A — Simulation Foundations
+
+Deliver first:
+
+- structured planner decision payload
+- simulation run API and persistence
+- aggregate results summary
+- per-file predicted actions table
+- settings/profile comparison flow
+
+Once that exists, follow immediately with:
+
+- richer skip/failure UI built on the same structured decision model
+
+Only after that:
+
+- library intelligence recommendations
+
+Media server integration stays deferred until those three are
+stable.