refactor(domain): freeze Movie and Episode, switch track collections to tuple

Movie and Episode become @dataclass(frozen=True, eq=False), with
audio_tracks/subtitle_tracks held as tuple[...] instead of list[...].
Identity-based equality is preserved via the existing __eq__/__hash__.
__post_init__ coercion (imdb_id, title, season_number, episode_number)
uses object.__setattr__ to stay compatible with frozen.

The MediaWithTracks mixin contract is updated to tuple accordingly.

Callers projecting enrichment results (probe output, file metadata) now
rebuild via dataclasses.replace(...) — same pattern recently adopted for
ParsedRelease.

Season and TVShow stay mutable for now: freezing the aggregate root
would cascade a full reconstruction on every add_episode, deferred.

.env.alfred

@@ -0,0 +1,80 @@
+# --- IMPORTANT ---
+# Settings are split across multiple files for clarity.
+# Files (loaded in this order, last wins):
+#   .env.alfred   — app config and service addresses (safe to commit)
+#   .env.secrets  — generated secrets, passwords, URIs and API keys (DO NOT COMMIT)
+#   .env.make     — build metadata synced from pyproject.toml (safe to commit)
+#
+# To customize: edit .env.alfred for config, .env.secrets for secrets.
+
+# --- Alfred ---
+MAX_HISTORY_MESSAGES=10
+MAX_TOOL_ITERATIONS=10
+REQUEST_TIMEOUT=30
+
+# LLM Settings
+LLM_TEMPERATURE=0.2
+
+# Persistence
+DATA_STORAGE_DIR=data
+
+# Network
+HOST=0.0.0.0
+PORT=3080
+
+# --- DATABASES ---
+# Passwords and connection URIs are auto-generated in .env.secrets.
+# Edit host/port/user/dbname here if needed.
+
+# MongoDB (Application Data)
+MONGO_HOST=mongodb
+MONGO_PORT=27017
+MONGO_USER=alfred
+MONGO_DB_NAME=alfred
+
+# PostgreSQL (Vector Database / RAG)
+POSTGRES_HOST=vectordb
+POSTGRES_PORT=5432
+POSTGRES_USER=alfred
+POSTGRES_DB_NAME=alfred
+
+# --- EXTERNAL SERVICES ---
+
+# TMDB — Media metadata (required). Get your key at https://www.themoviedb.org/
+# → TMDB_API_KEY goes in .env.secrets
+TMDB_BASE_URL=https://api.themoviedb.org/3
+
+# qBittorrent
+# → QBITTORRENT_PASSWORD goes in .env.secrets
+QBITTORRENT_URL=https://qb.lan.anustart.top
+QBITTORRENT_USERNAME=letmein
+QBITTORRENT_PORT=16140
+# Path translation: host-side prefix → container-side prefix
+QBITTORRENT_HOST_PATH=/mnt/testipool
+QBITTORRENT_CONTAINER_PATH=/mnt/data
+
+# Meilisearch
+# → MEILI_MASTER_KEY goes in .env.secrets
+# MEILI_ENABLED=false # KEY DOESN'T EXISTS => SEARCH IS THE PROPER KEY
+SEARCH=false
+MEILI_NO_ANALYTICS=true
+MEILI_HOST=http://meilisearch:7700
+
+# --- LLM CONFIGURATION ---
+# Providers: local, openai, anthropic, deepseek, google, kimi
+# → API keys go in .env.secrets
+DEFAULT_LLM_PROVIDER=deepseek
+
+# Local LLM (Ollama)
+#OLLAMA_BASE_URL=http://ollama:11434
+#OLLAMA_MODEL=llama3.3:latest
+
+OLLAMA_BASE_URL=http://10.0.0.11:11434
+OLLAMA_MODEL=glm-4.7-flash:latest
+
+# --- RAG ENGINE ---
+RAG_ENABLED=TRUE
+RAG_API_URL=http://rag_api:8000
+RAG_API_PORT=8000
+EMBEDDINGS_PROVIDER=ollama
+EMBEDDINGS_MODEL=nomic-embed-text

.env.example

@@ -1,3 +1,13 @@
+# --- IMPORTANT ---
+# Settings are split across multiple files for clarity.
+# Files (loaded in this order, last wins):
+#   .env.alfred   — app config and service addresses (safe to commit)
+#   .env.secrets  — generated secrets, passwords, URIs and API keys (DO NOT COMMIT)
+#   .env.make     — build metadata synced from pyproject.toml (safe to commit)
+#
+# To customize: edit .env.alfred for config, .env.secrets for secrets.
+
+# --- Alfred ---
 MAX_HISTORY_MESSAGES=10
 MAX_TOOL_ITERATIONS=10
 REQUEST_TIMEOUT=30
@@ -8,84 +18,54 @@ LLM_TEMPERATURE=0.2
 # Persistence
 DATA_STORAGE_DIR=data
 
-# Network configuration
+# Network
 HOST=0.0.0.0
 PORT=3080
 
-# Build informations (Synced with pyproject.toml via bootstrap)
-ALFRED_VERSION=
-IMAGE_NAME=
-LIBRECHAT_VERSION=
-PYTHON_VERSION=
-PYTHON_VERSION_SHORT=
-RAG_VERSION=
-RUNNER=
-SERVICE_NAME=
-
-# --- SECURITY KEYS (CRITICAL) ---
-# These are used for session tokens and encrypting sensitive data in MongoDB.
-# If you lose these, you lose access to encrypted stored credentials.
-JWT_SECRET=
-JWT_REFRESH_SECRET=
-CREDS_KEY=
-CREDS_IV=
-
-# --- DATABASES (AUTO-SECURED) ---
-# Alfred uses MongoDB for application state and PostgreSQL for Vector RAG.
-# Passwords will be generated as 24-character secure tokens if left blank.
+# --- DATABASES ---
+# Passwords and connection URIs are auto-generated in .env.secrets.
+# Edit host/port/user/dbname here if needed.
 
 # MongoDB (Application Data)
-MONGO_URI=
 MONGO_HOST=mongodb
 MONGO_PORT=27017
 MONGO_USER=alfred
-MONGO_PASSWORD=
 MONGO_DB_NAME=LibreChat
 
 # PostgreSQL (Vector Database / RAG)
-POSTGRES_URI=
 POSTGRES_HOST=vectordb
 POSTGRES_PORT=5432
 POSTGRES_USER=alfred
-POSTGRES_PASSWORD=
 POSTGRES_DB_NAME=alfred
 
 # --- EXTERNAL SERVICES ---
-# Media Metadata (Required)
-# Get your key at https://www.themoviedb.org/
-TMDB_API_KEY=
+
+# TMDB — Media metadata (required). Get your key at https://www.themoviedb.org/
+# → TMDB_API_KEY goes in .env.secrets
 TMDB_BASE_URL=https://api.themoviedb.org/3
 
-# qBittorrent integration
+# qBittorrent
+# → QBITTORRENT_PASSWORD goes in .env.secrets
 QBITTORRENT_URL=http://qbittorrent:16140
 QBITTORRENT_USERNAME=admin
-QBITTORRENT_PASSWORD=
 QBITTORRENT_PORT=16140
 
 # Meilisearch
+# → MEILI_MASTER_KEY goes in .env.secrets
 MEILI_ENABLED=FALSE
 MEILI_NO_ANALYTICS=TRUE
 MEILI_HOST=http://meilisearch:7700
-MEILI_MASTER_KEY=
 
 # --- LLM CONFIGURATION ---
-# Providers: 'local', 'openai', 'anthropic', 'deepseek', 'google', 'kimi'
+# Providers: local, openai, anthropic, deepseek, google, kimi
+# → API keys go in .env.secrets
 DEFAULT_LLM_PROVIDER=local
 
 # Local LLM (Ollama)
 OLLAMA_BASE_URL=http://ollama:11434
 OLLAMA_MODEL=llama3.3:latest
 
-# --- API KEYS (OPTIONAL) ---
-# Fill only the ones you intend to use.
-ANTHROPIC_API_KEY=
-DEEPSEEK_API_KEY=
-GOOGLE_API_KEY=
-KIMI_API_KEY=
-OPENAI_API_KEY=
-
 # --- RAG ENGINE ---
-# Enable/Disable the Retrieval Augmented Generation system
 RAG_ENABLED=TRUE
 RAG_API_URL=http://rag_api:8000
 RAG_API_PORT=8000

.env.librechat

@@ -0,0 +1,878 @@
+#=====================================================================#
+#                       LibreChat Configuration                       #
+#=====================================================================#
+# Please refer to the reference documentation for assistance          #
+# with configuring your LibreChat environment.                        #
+#                                                                     #
+# https://www.librechat.ai/docs/configuration/dotenv                  #
+#=====================================================================#
+
+#==================================================#
+#               Server Configuration               #
+#==================================================#
+
+HOST=localhost
+PORT=3080
+
+MONGO_URI=mongodb://127.0.0.1:27017/LibreChat
+#The maximum number of connections in the connection pool. */
+MONGO_MAX_POOL_SIZE=
+#The minimum number of connections in the connection pool. */
+MONGO_MIN_POOL_SIZE=
+#The maximum number of connections that may be in the process of being established concurrently by the connection pool. */
+MONGO_MAX_CONNECTING=
+#The maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed. */
+MONGO_MAX_IDLE_TIME_MS=
+#The maximum time in milliseconds that a thread can wait for a connection to become available. */
+MONGO_WAIT_QUEUE_TIMEOUT_MS=
+# Set to false to disable automatic index creation for all models associated with this connection. */
+MONGO_AUTO_INDEX=
+# Set to `false` to disable Mongoose automatically calling `createCollection()` on every model created on this connection. */
+MONGO_AUTO_CREATE=
+
+DOMAIN_CLIENT=http://localhost:3080
+DOMAIN_SERVER=http://localhost:3080
+
+NO_INDEX=true
+# Use the address that is at most n number of hops away from the Express application.
+# req.socket.remoteAddress is the first hop, and the rest are looked for in the X-Forwarded-For header from right to left.
+# A value of 0 means that the first untrusted address would be req.socket.remoteAddress, i.e. there is no reverse proxy.
+# Defaulted to 1.
+TRUST_PROXY=1
+
+# Minimum password length for user authentication
+# Default: 8
+# Note: When using LDAP authentication, you may want to set this to 1 
+# to bypass local password validation, as LDAP servers handle their own
+# password policies.
+# MIN_PASSWORD_LENGTH=8
+
+# When enabled, the app will continue running after encountering uncaught exceptions
+# instead of exiting the process. Not recommended for production unless necessary.
+# CONTINUE_ON_UNCAUGHT_EXCEPTION=false
+
+#===============#
+# JSON Logging  #
+#===============#
+
+# Use when process console logs in cloud deployment like GCP/AWS
+CONSOLE_JSON=false
+
+#===============#
+# Debug Logging #
+#===============#
+
+DEBUG_LOGGING=true
+DEBUG_CONSOLE=false
+# Set to true to enable agent debug logging
+AGENT_DEBUG_LOGGING=false
+
+# Enable memory diagnostics (logs heap/RSS snapshots every 60s, auto-enabled with --inspect)
+# MEM_DIAG=true
+
+#=============#
+# Permissions #
+#=============#
+
+# UID=1000
+# GID=1000
+
+#==============#
+# Node Options #
+#==============#
+
+# NOTE: NODE_MAX_OLD_SPACE_SIZE is NOT recognized by Node.js directly.
+# This variable is used as a build argument for Docker or CI/CD workflows,
+# and is NOT used by Node.js to set the heap size at runtime.
+# To configure Node.js memory, use NODE_OPTIONS, e.g.:
+# NODE_OPTIONS="--max-old-space-size=6144"
+# See: https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-mib
+NODE_MAX_OLD_SPACE_SIZE=6144
+
+#===============#
+# Configuration #
+#===============#
+# Use an absolute path, a relative path, or a URL
+
+# CONFIG_PATH="/alternative/path/to/librechat.yaml"
+
+#==================#
+# Langfuse Tracing #
+#==================#
+
+# Get Langfuse API keys for your project from the project settings page: https://cloud.langfuse.com
+
+# LANGFUSE_PUBLIC_KEY=
+# LANGFUSE_SECRET_KEY=
+# LANGFUSE_BASE_URL=
+
+#===================================================#
+#                     Endpoints                     #
+#===================================================#
+
+# ENDPOINTS=openAI,assistants,azureOpenAI,google,anthropic
+
+PROXY=
+
+#===================================#
+# Known Endpoints - librechat.yaml  #
+#===================================#
+# https://www.librechat.ai/docs/configuration/librechat_yaml/ai_endpoints
+
+# ANYSCALE_API_KEY=
+# APIPIE_API_KEY=
+# COHERE_API_KEY=
+# DEEPSEEK_API_KEY=
+# DATABRICKS_API_KEY=
+# FIREWORKS_API_KEY=
+# GROQ_API_KEY=
+# HUGGINGFACE_TOKEN=
+# MISTRAL_API_KEY=
+# OPENROUTER_KEY=
+# PERPLEXITY_API_KEY=
+# SHUTTLEAI_API_KEY=
+# TOGETHERAI_API_KEY=
+# UNIFY_API_KEY=
+# XAI_API_KEY=
+
+#============#
+# Anthropic  #
+#============#
+
+ANTHROPIC_API_KEY=user_provided
+# ANTHROPIC_MODELS=claude-sonnet-4-6,claude-opus-4-6,claude-opus-4-20250514,claude-sonnet-4-20250514,claude-3-7-sonnet-20250219,claude-3-5-sonnet-20241022,claude-3-5-haiku-20241022,claude-3-opus-20240229,claude-3-sonnet-20240229,claude-3-haiku-20240307
+# ANTHROPIC_REVERSE_PROXY=
+
+# Set to true to use Anthropic models through Google Vertex AI instead of direct API
+# ANTHROPIC_USE_VERTEX=
+# ANTHROPIC_VERTEX_REGION=us-east5
+
+#============#
+# Azure      #
+#============#
+
+# Note: these variables are DEPRECATED
+# Use the `librechat.yaml` configuration for `azureOpenAI` instead
+# You may also continue to use them if you opt out of using the `librechat.yaml` configuration
+
+# AZURE_OPENAI_DEFAULT_MODEL=gpt-3.5-turbo # Deprecated
+# AZURE_OPENAI_MODELS=gpt-3.5-turbo,gpt-4 # Deprecated
+# AZURE_USE_MODEL_AS_DEPLOYMENT_NAME=TRUE # Deprecated
+# AZURE_API_KEY= # Deprecated
+# AZURE_OPENAI_API_INSTANCE_NAME= # Deprecated
+# AZURE_OPENAI_API_DEPLOYMENT_NAME= # Deprecated
+# AZURE_OPENAI_API_VERSION= # Deprecated
+# AZURE_OPENAI_API_COMPLETIONS_DEPLOYMENT_NAME= # Deprecated
+# AZURE_OPENAI_API_EMBEDDINGS_DEPLOYMENT_NAME= # Deprecated
+
+#=================#
+#   AWS Bedrock   #
+#=================#
+
+# BEDROCK_AWS_DEFAULT_REGION=us-east-1 # A default region must be provided
+# BEDROCK_AWS_ACCESS_KEY_ID=someAccessKey
+# BEDROCK_AWS_SECRET_ACCESS_KEY=someSecretAccessKey
+# BEDROCK_AWS_SESSION_TOKEN=someSessionToken
+
+# Note: This example list is not meant to be exhaustive. If omitted, all known, supported model IDs will be included for you.
+# BEDROCK_AWS_MODELS=anthropic.claude-sonnet-4-6,anthropic.claude-opus-4-6-v1,anthropic.claude-3-5-sonnet-20240620-v1:0,meta.llama3-1-8b-instruct-v1:0
+# Cross-region inference model IDs: us.anthropic.claude-sonnet-4-6,us.anthropic.claude-opus-4-6-v1,global.anthropic.claude-opus-4-6-v1
+
+# See all Bedrock model IDs here: https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html#model-ids-arns
+
+# Notes on specific models:
+# The following models are not support due to not supporting streaming:
+# ai21.j2-mid-v1
+
+# The following models are not support due to not supporting conversation history:
+# ai21.j2-ultra-v1, cohere.command-text-v14, cohere.command-light-text-v14
+
+#============#
+# Google     #
+#============#
+
+GOOGLE_KEY=user_provided
+
+# GOOGLE_REVERSE_PROXY=
+# Some reverse proxies do not support the X-goog-api-key header, uncomment to pass the API key in Authorization header instead.
+# GOOGLE_AUTH_HEADER=true
+
+# Gemini API (AI Studio)
+# GOOGLE_MODELS=gemini-3.1-pro-preview,gemini-3.1-pro-preview-customtools,gemini-3.1-flash-lite-preview,gemini-2.5-pro,gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.0-flash,gemini-2.0-flash-lite
+
+# Vertex AI
+# GOOGLE_MODELS=gemini-3.1-pro-preview,gemini-3.1-pro-preview-customtools,gemini-3.1-flash-lite-preview,gemini-2.5-pro,gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.0-flash-001,gemini-2.0-flash-lite-001
+
+# GOOGLE_TITLE_MODEL=gemini-2.0-flash-lite-001
+
+# Google Cloud region for Vertex AI (used by both chat and image generation)
+# GOOGLE_LOC=us-central1
+
+# Alternative region env var for Gemini Image Generation
+# GOOGLE_CLOUD_LOCATION=global
+
+# Vertex AI Service Account Configuration
+# Path to your Google Cloud service account JSON file
+# GOOGLE_SERVICE_KEY_FILE=/path/to/service-account.json
+
+# Google Safety Settings
+# NOTE: These settings apply to both Vertex AI and Gemini API (AI Studio)
+#
+# For Vertex AI:
+# To use the BLOCK_NONE setting, you need either:
+# (a) Access through an allowlist via your Google account team, or
+# (b) Switch to monthly invoiced billing: https://cloud.google.com/billing/docs/how-to/invoiced-billing
+#
+# For Gemini API (AI Studio):
+# BLOCK_NONE is available by default, no special account requirements.
+#
+# Available options: BLOCK_NONE, BLOCK_ONLY_HIGH, BLOCK_MEDIUM_AND_ABOVE, BLOCK_LOW_AND_ABOVE
+#
+# GOOGLE_SAFETY_SEXUALLY_EXPLICIT=BLOCK_ONLY_HIGH
+# GOOGLE_SAFETY_HATE_SPEECH=BLOCK_ONLY_HIGH
+# GOOGLE_SAFETY_HARASSMENT=BLOCK_ONLY_HIGH
+# GOOGLE_SAFETY_DANGEROUS_CONTENT=BLOCK_ONLY_HIGH
+# GOOGLE_SAFETY_CIVIC_INTEGRITY=BLOCK_ONLY_HIGH
+
+#========================#
+# Gemini Image Generation #
+#========================#
+
+# Gemini Image Generation Tool (for Agents)
+# Supports multiple authentication methods in priority order:
+# 1. User-provided API key (via GUI)
+# 2. GEMINI_API_KEY env var (admin-configured)
+# 3. GOOGLE_KEY env var (shared with Google chat endpoint)
+# 4. Vertex AI service account (via GOOGLE_SERVICE_KEY_FILE)
+
+# Option A: Use dedicated Gemini API key for image generation
+# GEMINI_API_KEY=your-gemini-api-key
+
+# Vertex AI model for image generation (defaults to gemini-2.5-flash-image)
+# GEMINI_IMAGE_MODEL=gemini-2.5-flash-image
+
+#============#
+# OpenAI     #
+#============#
+
+OPENAI_API_KEY=user_provided
+# OPENAI_MODELS=gpt-5,gpt-5-codex,gpt-5-mini,gpt-5-nano,o3-pro,o3,o4-mini,gpt-4.1,gpt-4.1-mini,gpt-4.1-nano,o3-mini,o1-pro,o1,gpt-4o,gpt-4o-mini
+
+DEBUG_OPENAI=false
+
+# TITLE_CONVO=false
+# OPENAI_TITLE_MODEL=gpt-4o-mini
+
+# OPENAI_SUMMARIZE=true
+# OPENAI_SUMMARY_MODEL=gpt-4o-mini
+
+# OPENAI_FORCE_PROMPT=true
+
+# OPENAI_REVERSE_PROXY=
+
+# OPENAI_ORGANIZATION=
+
+#====================#
+#   Assistants API   #
+#====================#
+
+ASSISTANTS_API_KEY=user_provided
+# ASSISTANTS_BASE_URL=
+# ASSISTANTS_MODELS=gpt-4o,gpt-4o-mini,gpt-3.5-turbo-0125,gpt-3.5-turbo-16k-0613,gpt-3.5-turbo-16k,gpt-3.5-turbo,gpt-4,gpt-4-0314,gpt-4-32k-0314,gpt-4-0613,gpt-3.5-turbo-0613,gpt-3.5-turbo-1106,gpt-4-0125-preview,gpt-4-turbo-preview,gpt-4-1106-preview
+
+#==========================#
+#   Azure Assistants API   #
+#==========================#
+
+# Note: You should map your credentials with custom variables according to your Azure OpenAI Configuration
+# The models for Azure Assistants are also determined by your Azure OpenAI configuration.
+
+# More info, including how to enable use of Assistants with Azure here:
+# https://www.librechat.ai/docs/configuration/librechat_yaml/ai_endpoints/azure#using-assistants-with-azure
+
+CREDS_KEY=f34be427ebb29de8d88c107a71546019685ed8b241d8f2ed00c3df97ad2566f0
+CREDS_IV=e2341419ec3dd3d19b13a1a87fafcbfb
+
+# Azure AI Search
+#-----------------
+AZURE_AI_SEARCH_SERVICE_ENDPOINT=
+AZURE_AI_SEARCH_INDEX_NAME=
+AZURE_AI_SEARCH_API_KEY=
+
+AZURE_AI_SEARCH_API_VERSION=
+AZURE_AI_SEARCH_SEARCH_OPTION_QUERY_TYPE=
+AZURE_AI_SEARCH_SEARCH_OPTION_TOP=
+AZURE_AI_SEARCH_SEARCH_OPTION_SELECT=
+
+# OpenAI Image Tools Customization
+#----------------
+# IMAGE_GEN_OAI_API_KEY= # Create or reuse OpenAI API key for image generation tool
+# IMAGE_GEN_OAI_BASEURL= # Custom OpenAI base URL for image generation tool
+# IMAGE_GEN_OAI_AZURE_API_VERSION= # Custom Azure OpenAI deployments
+# IMAGE_GEN_OAI_MODEL=gpt-image-1 # OpenAI image model (e.g., gpt-image-1, gpt-image-1.5)
+# IMAGE_GEN_OAI_DESCRIPTION=
+# IMAGE_GEN_OAI_DESCRIPTION_WITH_FILES=Custom description for image generation tool when files are present
+# IMAGE_GEN_OAI_DESCRIPTION_NO_FILES=Custom description for image generation tool when no files are present
+# IMAGE_EDIT_OAI_DESCRIPTION=Custom description for image editing tool
+# IMAGE_GEN_OAI_PROMPT_DESCRIPTION=Custom prompt description for image generation tool
+# IMAGE_EDIT_OAI_PROMPT_DESCRIPTION=Custom prompt description for image editing tool
+
+# DALL·E
+#----------------
+# DALLE_API_KEY=
+# DALLE3_API_KEY=
+# DALLE2_API_KEY=
+# DALLE3_SYSTEM_PROMPT=
+# DALLE2_SYSTEM_PROMPT=
+# DALLE_REVERSE_PROXY=
+# DALLE3_BASEURL=
+# DALLE2_BASEURL=
+
+# DALL·E (via Azure OpenAI)
+# Note: requires some of the variables above to be set
+#----------------
+# DALLE3_AZURE_API_VERSION=
+# DALLE2_AZURE_API_VERSION=
+
+# Flux
+#-----------------
+FLUX_API_BASE_URL=https://api.us1.bfl.ai
+# FLUX_API_BASE_URL = 'https://api.bfl.ml';
+
+# Get your API key at https://api.us1.bfl.ai/auth/profile
+# FLUX_API_KEY=
+
+# Google
+#-----------------
+GOOGLE_SEARCH_API_KEY=
+GOOGLE_CSE_ID=
+
+# Stable Diffusion
+#-----------------
+SD_WEBUI_URL=http://host.docker.internal:7860
+
+# Tavily
+#-----------------
+TAVILY_API_KEY=
+
+# Traversaal
+#-----------------
+TRAVERSAAL_API_KEY=
+
+# WolframAlpha
+#-----------------
+WOLFRAM_APP_ID=
+
+# Zapier
+#-----------------
+ZAPIER_NLA_API_KEY=
+
+#==================================================#
+#                      Search                      #
+#==================================================#
+
+SEARCH=true
+MEILI_NO_ANALYTICS=true
+MEILI_HOST=http://0.0.0.0:7700
+MEILI_MASTER_KEY=DrhYf7zENyR6AlUCKmnz0eYASOQdl6zxH7s7MKFSfFCt
+
+# Optional: Disable indexing, useful in a multi-node setup
+# where only one instance should perform an index sync.
+# MEILI_NO_SYNC=true
+
+#==================================================#
+#          Speech to Text & Text to Speech         #
+#==================================================#
+
+STT_API_KEY=
+TTS_API_KEY=
+
+#==================================================#
+#                        RAG                       #
+#==================================================#
+# More info: https://www.librechat.ai/docs/configuration/rag_api
+
+# RAG_OPENAI_BASEURL=
+# RAG_OPENAI_API_KEY=
+# RAG_USE_FULL_CONTEXT=
+# EMBEDDINGS_PROVIDER=openai
+# EMBEDDINGS_MODEL=text-embedding-3-small
+
+#===================================================#
+#                    User System                    #
+#===================================================#
+
+#========================#
+# Moderation             #
+#========================#
+
+OPENAI_MODERATION=false
+OPENAI_MODERATION_API_KEY=
+# OPENAI_MODERATION_REVERSE_PROXY=
+
+BAN_VIOLATIONS=true
+BAN_DURATION=1000 * 60 * 60 * 2
+BAN_INTERVAL=20
+
+LOGIN_VIOLATION_SCORE=1
+REGISTRATION_VIOLATION_SCORE=1
+CONCURRENT_VIOLATION_SCORE=1
+MESSAGE_VIOLATION_SCORE=1
+NON_BROWSER_VIOLATION_SCORE=20
+TTS_VIOLATION_SCORE=0
+STT_VIOLATION_SCORE=0
+FORK_VIOLATION_SCORE=0
+IMPORT_VIOLATION_SCORE=0
+FILE_UPLOAD_VIOLATION_SCORE=0
+
+LOGIN_MAX=7
+LOGIN_WINDOW=5
+REGISTER_MAX=5
+REGISTER_WINDOW=60
+
+LIMIT_CONCURRENT_MESSAGES=true
+CONCURRENT_MESSAGE_MAX=2
+
+LIMIT_MESSAGE_IP=true
+MESSAGE_IP_MAX=40
+MESSAGE_IP_WINDOW=1
+
+LIMIT_MESSAGE_USER=false
+MESSAGE_USER_MAX=40
+MESSAGE_USER_WINDOW=1
+
+ILLEGAL_MODEL_REQ_SCORE=5
+
+#========================#
+# Balance                #
+#========================#
+
+# CHECK_BALANCE=false
+# START_BALANCE=20000 # note: the number of tokens that will be credited after registration.
+
+#========================#
+# Registration and Login #
+#========================#
+
+ALLOW_EMAIL_LOGIN=true
+ALLOW_REGISTRATION=true
+ALLOW_SOCIAL_LOGIN=false
+ALLOW_SOCIAL_REGISTRATION=false
+ALLOW_PASSWORD_RESET=false
+# ALLOW_ACCOUNT_DELETION=true # note: enabled by default if omitted/commented out
+ALLOW_UNVERIFIED_EMAIL_LOGIN=true
+
+SESSION_EXPIRY=1000 * 60 * 15
+REFRESH_TOKEN_EXPIRY=(1000 * 60 * 60 * 24) * 7
+
+JWT_SECRET=16f8c0ef4a5d391b26034086c628469d3f9f497f08163ab9b40137092f2909ef
+JWT_REFRESH_SECRET=eaa5191f2914e30b9387fd84e254e4ba6fc51b4654968a9b0803b456a54b8418
+
+# Discord
+DISCORD_CLIENT_ID=
+DISCORD_CLIENT_SECRET=
+DISCORD_CALLBACK_URL=/oauth/discord/callback
+
+# Facebook
+FACEBOOK_CLIENT_ID=
+FACEBOOK_CLIENT_SECRET=
+FACEBOOK_CALLBACK_URL=/oauth/facebook/callback
+
+# GitHub
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+GITHUB_CALLBACK_URL=/oauth/github/callback
+# GitHub Enterprise
+# GITHUB_ENTERPRISE_BASE_URL=
+# GITHUB_ENTERPRISE_USER_AGENT=
+
+# Google
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+GOOGLE_CALLBACK_URL=/oauth/google/callback
+
+# Apple
+APPLE_CLIENT_ID=
+APPLE_TEAM_ID=
+APPLE_KEY_ID=
+APPLE_PRIVATE_KEY_PATH=
+APPLE_CALLBACK_URL=/oauth/apple/callback
+
+# OpenID
+OPENID_CLIENT_ID=
+OPENID_CLIENT_SECRET=
+OPENID_ISSUER=
+OPENID_SESSION_SECRET=
+OPENID_SCOPE="openid profile email"
+OPENID_CALLBACK_URL=/oauth/openid/callback
+OPENID_REQUIRED_ROLE=
+OPENID_REQUIRED_ROLE_TOKEN_KIND=
+OPENID_REQUIRED_ROLE_PARAMETER_PATH=
+OPENID_ADMIN_ROLE=
+OPENID_ADMIN_ROLE_PARAMETER_PATH=
+OPENID_ADMIN_ROLE_TOKEN_KIND=
+# Set to determine which user info property returned from OpenID Provider to store as the User's username
+OPENID_USERNAME_CLAIM=
+# Set to determine which user info property returned from OpenID Provider to store as the User's name
+OPENID_NAME_CLAIM=
+# Set to determine which user info claim to use as the email/identifier for user matching (e.g., "upn" for Entra ID)
+# When not set, defaults to: email -> preferred_username -> upn
+OPENID_EMAIL_CLAIM=
+# Optional audience parameter for OpenID authorization requests
+OPENID_AUDIENCE=
+
+OPENID_BUTTON_LABEL=
+OPENID_IMAGE_URL=
+# Set to true to automatically redirect to the OpenID provider when a user visits the login page
+# This will bypass the login form completely for users, only use this if OpenID is your only authentication method
+OPENID_AUTO_REDIRECT=false
+# Set to true to use PKCE (Proof Key for Code Exchange) for OpenID authentication
+OPENID_USE_PKCE=false
+#Set to true to reuse openid tokens for authentication management instead of using the mongodb session and the custom refresh token.
+OPENID_REUSE_TOKENS=
+#By default, signing key verification results are cached in order to prevent excessive HTTP requests to the JWKS endpoint.
+#If a signing key matching the kid is found, this will be cached and the next time this kid is requested the signing key will be served from the cache.
+#Default is true.
+OPENID_JWKS_URL_CACHE_ENABLED=
+OPENID_JWKS_URL_CACHE_TIME= # 600000 ms eq to 10 minutes leave empty to disable caching
+#Set to true to trigger token exchange flow to acquire access token for the userinfo endpoint.
+OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=
+OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE="user.read" # example for Scope Needed for Microsoft Graph API
+# Set to true to use the OpenID Connect end session endpoint for logout
+OPENID_USE_END_SESSION_ENDPOINT=
+# URL to redirect to after OpenID logout (defaults to ${DOMAIN_CLIENT}/login)
+OPENID_POST_LOGOUT_REDIRECT_URI=
+# Maximum logout URL length before using logout_hint instead of id_token_hint (default: 2000)
+OPENID_MAX_LOGOUT_URL_LENGTH=
+
+#========================#
+# SharePoint Integration #
+#========================#
+# Requires Entra ID (OpenID) authentication to be configured
+
+# Enable SharePoint file picker in chat and agent panels
+# ENABLE_SHAREPOINT_FILEPICKER=true
+
+# SharePoint tenant base URL (e.g., https://yourtenant.sharepoint.com)
+# SHAREPOINT_BASE_URL=https://yourtenant.sharepoint.com
+
+# Microsoft Graph API And SharePoint scopes for file picker
+# SHAREPOINT_PICKER_SHAREPOINT_SCOPE==https://yourtenant.sharepoint.com/AllSites.Read
+# SHAREPOINT_PICKER_GRAPH_SCOPE=Files.Read.All
+#========================#
+
+# SAML
+# Note: If OpenID is enabled, SAML authentication will be automatically disabled.
+SAML_ENTRY_POINT=
+SAML_ISSUER=
+SAML_CERT=
+SAML_CALLBACK_URL=/oauth/saml/callback
+SAML_SESSION_SECRET=
+
+# Attribute mappings (optional)
+SAML_EMAIL_CLAIM=
+SAML_USERNAME_CLAIM=
+SAML_GIVEN_NAME_CLAIM=
+SAML_FAMILY_NAME_CLAIM=
+SAML_PICTURE_CLAIM=
+SAML_NAME_CLAIM=
+
+# Logint buttion settings (optional)
+SAML_BUTTON_LABEL=
+SAML_IMAGE_URL=
+
+# Whether the SAML Response should be signed.
+# - If "true", the entire `SAML Response` will be signed.
+# - If "false" or unset, only the `SAML Assertion` will be signed (default behavior).
+# SAML_USE_AUTHN_RESPONSE_SIGNED=
+
+
+#===============================================#
+# Microsoft Graph API / Entra ID Integration  #
+#===============================================#
+
+# Enable Entra ID people search integration in permissions/sharing system
+# When enabled, the people picker will search both local database and Entra ID
+USE_ENTRA_ID_FOR_PEOPLE_SEARCH=false
+
+# When enabled, entra id groups owners will be considered as members of the group
+ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS=false
+
+# Microsoft Graph API scopes needed for people/group search
+# Default scopes provide access to user profiles and group memberships
+OPENID_GRAPH_SCOPES=User.Read,People.Read,GroupMember.Read.All
+
+# LDAP
+LDAP_URL=
+LDAP_BIND_DN=
+LDAP_BIND_CREDENTIALS=
+LDAP_USER_SEARCH_BASE=
+#LDAP_SEARCH_FILTER="mail="
+LDAP_CA_CERT_PATH=
+# LDAP_TLS_REJECT_UNAUTHORIZED=
+# LDAP_STARTTLS=
+# LDAP_LOGIN_USES_USERNAME=true
+# LDAP_ID=
+# LDAP_USERNAME=
+# LDAP_EMAIL=
+# LDAP_FULL_NAME=
+
+#========================#
+# Email Password Reset   #
+#========================#
+
+EMAIL_SERVICE=
+EMAIL_HOST=
+EMAIL_PORT=25
+EMAIL_ENCRYPTION=
+EMAIL_ENCRYPTION_HOSTNAME=
+EMAIL_ALLOW_SELFSIGNED=
+# Leave both empty for SMTP servers that do not require authentication
+EMAIL_USERNAME=
+EMAIL_PASSWORD=
+EMAIL_FROM_NAME=
+EMAIL_FROM=noreply@librechat.ai
+
+#========================#
+#      Mailgun API       #
+#========================#
+
+# MAILGUN_API_KEY=your-mailgun-api-key
+# MAILGUN_DOMAIN=mg.yourdomain.com
+# EMAIL_FROM=noreply@yourdomain.com
+# EMAIL_FROM_NAME="LibreChat"
+
+# # Optional: For EU region
+# MAILGUN_HOST=https://api.eu.mailgun.net
+
+#========================#
+# Firebase CDN           #
+#========================#
+
+FIREBASE_API_KEY=
+FIREBASE_AUTH_DOMAIN=
+FIREBASE_PROJECT_ID=
+FIREBASE_STORAGE_BUCKET=
+FIREBASE_MESSAGING_SENDER_ID=
+FIREBASE_APP_ID=
+
+#========================#
+# S3 AWS Bucket          #
+#========================#
+
+AWS_ENDPOINT_URL=
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_REGION=
+AWS_BUCKET_NAME=
+# Required for path-style S3-compatible providers (MinIO, Hetzner, Backblaze B2, etc.)
+# that don't support virtual-hosted-style URLs (bucket.endpoint). Not needed for AWS S3.
+# AWS_FORCE_PATH_STYLE=false
+
+#========================#
+# Azure Blob Storage     #
+#========================#
+
+AZURE_STORAGE_CONNECTION_STRING=
+AZURE_STORAGE_PUBLIC_ACCESS=false
+AZURE_CONTAINER_NAME=files
+
+#========================#
+# Shared Links           #
+#========================#
+
+ALLOW_SHARED_LINKS=true
+# Allows unauthenticated access to shared links. Defaults to false (auth required) if not set.
+ALLOW_SHARED_LINKS_PUBLIC=false
+
+#==============================#
+# Static File Cache Control    #
+#==============================#
+
+# Leave commented out to use defaults: 1 day (86400 seconds) for s-maxage and 2 days (172800 seconds) for max-age
+# NODE_ENV must be set to production for these to take effect
+# STATIC_CACHE_MAX_AGE=172800
+# STATIC_CACHE_S_MAX_AGE=86400
+
+# If you have another service in front of your LibreChat doing compression, disable express based compression here
+# DISABLE_COMPRESSION=true
+
+# If you have gzipped version of uploaded image images in the same folder, this will enable gzip scan and serving of these images
+# Note: The images folder will be scanned on startup and a ma kept in memory. Be careful for large number of images.
+# ENABLE_IMAGE_OUTPUT_GZIP_SCAN=true
+
+#===================================================#
+#                        UI                         #
+#===================================================#
+
+APP_TITLE=LibreChat
+# CUSTOM_FOOTER="My custom footer"
+HELP_AND_FAQ_URL=https://librechat.ai
+
+# SHOW_BIRTHDAY_ICON=true
+
+# Google tag manager id
+#ANALYTICS_GTM_ID=user provided google tag manager id
+
+# limit conversation file imports to a certain number of bytes in size to avoid the container
+# maxing out memory limitations by unremarking this line and supplying a file size in bytes
+# such as the below example of 250 mib
+# CONVERSATION_IMPORT_MAX_FILE_SIZE_BYTES=262144000
+
+
+#===============#
+# REDIS Options #
+#===============#
+
+# Enable Redis for caching and session storage
+# USE_REDIS=true
+# Enable Redis for resumable LLM streams (defaults to USE_REDIS value if not set)
+# Set to false to use in-memory storage for streams while keeping Redis for other caches
+# USE_REDIS_STREAMS=true
+
+# Single Redis instance
+# REDIS_URI=redis://127.0.0.1:6379
+
+# Redis cluster (multiple nodes)
+# REDIS_URI=redis://127.0.0.1:7001,redis://127.0.0.1:7002,redis://127.0.0.1:7003
+
+# Redis with TLS/SSL encryption and CA certificate
+# REDIS_URI=rediss://127.0.0.1:6380
+# REDIS_CA=/path/to/ca-cert.pem
+
+# Elasticache may need to use an alternate dnsLookup for TLS connections.  see "Special Note: Aws Elasticache Clusters with TLS" on this webpage: https://www.npmjs.com/package/ioredis
+# Enable alternative dnsLookup for redis
+# REDIS_USE_ALTERNATIVE_DNS_LOOKUP=true
+
+# Redis authentication (if required)
+# REDIS_USERNAME=your_redis_username
+# REDIS_PASSWORD=your_redis_password
+
+# Redis key prefix configuration
+# Use environment variable name for dynamic prefix (recommended for cloud deployments)
+# REDIS_KEY_PREFIX_VAR=K_REVISION
+# Or use static prefix directly
+# REDIS_KEY_PREFIX=librechat
+
+# Redis connection limits
+# REDIS_MAX_LISTENERS=40
+
+# Redis ping interval in seconds (0 = disabled, >0 = enabled)
+# When set to a positive integer, Redis clients will ping the server at this interval to keep connections alive
+# When unset or 0, no pinging is performed (recommended for most use cases)
+# REDIS_PING_INTERVAL=300
+
+# Force specific cache namespaces to use in-memory storage even when Redis is enabled
+# Comma-separated list of CacheKeys
+# Defaults to CONFIG_STORE,APP_CONFIG so YAML-derived config stays per-container (safe for blue/green deployments)
+# Set to empty string to force all namespaces through Redis: FORCED_IN_MEMORY_CACHE_NAMESPACES=
+# FORCED_IN_MEMORY_CACHE_NAMESPACES=CONFIG_STORE,APP_CONFIG
+
+# Leader Election Configuration (for multi-instance deployments with Redis)
+# Duration in seconds that the leader lease is valid before it expires (default: 25)
+# LEADER_LEASE_DURATION=25
+# Interval in seconds at which the leader renews its lease (default: 10)
+# LEADER_RENEW_INTERVAL=10
+# Maximum number of retry attempts when renewing the lease fails (default: 3)
+# LEADER_RENEW_ATTEMPTS=3
+# Delay in seconds between retry attempts when renewing the lease (default: 0.5)
+# LEADER_RENEW_RETRY_DELAY=0.5
+
+#==================================================#
+#                      Others                      #
+#==================================================#
+#   You should leave the following commented out   #
+
+# NODE_ENV=
+
+# E2E_USER_EMAIL=
+# E2E_USER_PASSWORD=
+
+#=====================================================#
+#                  Cache Headers                      #
+#=====================================================#
+#   Headers that control caching of the index.html    #
+#   Default configuration prevents caching to ensure  #
+#   users always get the latest version. Customize    #
+#   only if you understand caching implications.      #
+
+# INDEX_CACHE_CONTROL=no-cache, no-store, must-revalidate
+# INDEX_PRAGMA=no-cache
+# INDEX_EXPIRES=0
+
+# no-cache: Forces validation with server before using cached version
+# no-store: Prevents storing the response entirely
+# must-revalidate: Prevents using stale content when offline
+
+#=====================================================#
+#                  OpenWeather                        #
+#=====================================================#
+OPENWEATHER_API_KEY=
+
+#====================================#
+# LibreChat Code Interpreter API     #
+#====================================#
+
+# https://code.librechat.ai
+# LIBRECHAT_CODE_API_KEY=your-key
+
+#======================#
+# Web Search           #
+#======================#
+
+# Note: All of the following variable names can be customized.
+# Omit values to allow user to provide them.
+
+# For more information on configuration values, see:
+# https://librechat.ai/docs/features/web_search
+
+# Search Provider (Required)
+# SERPER_API_KEY=your_serper_api_key
+
+# Scraper (Required)
+# FIRECRAWL_API_KEY=your_firecrawl_api_key
+# Optional: Custom Firecrawl API URL
+# FIRECRAWL_API_URL=your_firecrawl_api_url
+
+# Reranker (Required)
+# JINA_API_KEY=your_jina_api_key
+# or
+# COHERE_API_KEY=your_cohere_api_key
+
+#======================#
+# MCP Configuration    #
+#======================#
+
+# Treat 401/403 responses as OAuth requirement when no oauth metadata found
+# MCP_OAUTH_ON_AUTH_ERROR=true
+
+# Timeout for OAuth detection requests in milliseconds
+# MCP_OAUTH_DETECTION_TIMEOUT=5000
+
+# Cache connection status checks for this many milliseconds to avoid expensive verification
+# MCP_CONNECTION_CHECK_TTL=60000
+
+# Skip code challenge method validation (e.g., for AWS Cognito that supports S256 but doesn't advertise it)
+# When set to true, forces S256 code challenge even if not advertised in .well-known/openid-configuration
+# MCP_SKIP_CODE_CHALLENGE_CHECK=false
+
+# Circuit breaker: max connect/disconnect cycles before tripping (per server)
+# MCP_CB_MAX_CYCLES=7
+
+# Circuit breaker: sliding window (ms) for counting cycles
+# MCP_CB_CYCLE_WINDOW_MS=45000
+
+# Circuit breaker: cooldown (ms) after the cycle breaker trips
+# MCP_CB_CYCLE_COOLDOWN_MS=15000
+
+# Circuit breaker: max consecutive failed connection rounds before backoff
+# MCP_CB_MAX_FAILED_ROUNDS=3
+
+# Circuit breaker: sliding window (ms) for counting failed rounds
+# MCP_CB_FAILED_WINDOW_MS=120000
+
+# Circuit breaker: base backoff (ms) after failed round threshold is reached
+# MCP_CB_BASE_BACKOFF_MS=30000
+
+# Circuit breaker: max backoff cap (ms) for exponential backoff
+# MCP_CB_MAX_BACKOFF_MS=300000

.env.make

@@ -0,0 +1,8 @@
+# Auto-generated from pyproject.toml — do not edit manually
+ALFRED_VERSION=0.1.7
+PYTHON_VERSION=3.14.3
+IMAGE_NAME=alfred_media_organizer
+SERVICE_NAME=alfred
+LIBRECHAT_VERSION=v0.8.4
+RAG_VERSION=v0.7.3
+UV_VERSION=0.11.6

.gitignore

@@ -55,13 +55,24 @@ coverage.xml
 Thumbs.db
 
 # Secrets
-.env
+.env.secrets
 
 # Backup files
 *.backup
+*.bak
+env_backup/
 
 # Application data dir
 data/*
 
 # Application logs
 logs/*
+
+# Documentation folder
+docs/
+
+# .md files (project-level Markdown is brol-y; allow-list the ones we track)
+*.md
+!CHANGELOG.md
+
+#

CHANGELOG.md

@@ -0,0 +1,724 @@
+# Changelog
+
+All notable changes to Alfred are documented here.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Alfred is not yet on SemVer — entries are grouped by **dated work blocks** instead
+of release numbers. Granularity targets behavioral or API-visible changes; refer
+to `git log` for commit-level detail.
+
+Sections used per block: **Added** / **Changed** / **Deprecated** / **Removed** /
+**Fixed** / **Internal** (for tech-debt and refactor noise that doesn't affect
+callers).
+
+---
+
+## [Unreleased]
+
+### Fixed
+
+- **Multi-episode chain (e.g. `S14E09E10E11`) now collapses to a full
+  range.** The parser previously captured `episode=9, episode_end=10`
+  and dropped E11+. It now returns `episode=first, episode_end=last`,
+  with intermediate values implied. Fixture
+  `shitty/archer_multi_episode/` updated from anti-regression-of-bug
+  to anti-regression-of-fix.
+- **Apostrophes in titles no longer push the release through the AI
+  fallback.** `Honey.Don't.2025.2160p.WEBRip.DSNP.DV.HDR.x265-Amen`
+  previously parsed with `parse_path="ai"` and everything UNKNOWN
+  because `'` is in the forbidden-chars list. Apostrophes are now
+  pre-stripped before the well-formed check, so the parse completes
+  normally (`title=Honey.Dont, year=2025, quality=2160p, ...`); only
+  the title text loses its apostrophe. `parse_path` becomes
+  `sanitized` to surface the cleanup. Side win: PoP fixture
+  `the_prodigy_full_chaos/` also moves from total failure to a
+  partially-correct parse (year, source, codec extracted).
+- **Season-range markers (`Sxx-yy`) are now recognized as
+  `tv_complete`.** `Der.Tatortreiniger.S01-06.GERMAN...` previously
+  parsed as `media_type=movie` with `S01-06` glued onto the title.
+  The parser now recognizes the range, sets `season=first`,
+  `media_type=tv_complete`, and removes the marker from the title.
+  `is_season_pack` flips to `true`.
+- **Pure-punctuation TITLE tokens are dropped at assembly.** Releases
+  with surrounding ` - ` separators (`Vinyl - 1x01 - FHD`) previously
+  produced `title="Vinyl.-"`. Such tokens (a stray dash, a wide pipe
+  `｜`, …) carry no title content and are now filtered out. Side
+  effect: PoP fixture `khruangbin_yt_wide_pipe/` also benefits — the
+  YouTube wide-pipe no longer leaks into the title.
+
+### Added
+
+- **Fullwidth vertical bar `｜` (U+FF5C) is now a recognized release-name
+  token separator.** Added to `alfred/knowledge/release/separators.yaml`
+  so CJK release names (and the occasional decorative YouTube-style use)
+  tokenize cleanly instead of leaving the wide pipe glued onto an
+  adjacent token. The tokenizer in
+  `alfred/domain/release/parser/pipeline.py` already iterates the
+  separator list as plain strings (no regex), so a multi-byte UTF-8
+  separator works without any code change.
+
+- **`InspectedResult.recommended_action` property** — derived hint that
+  collapses the orchestrator's go / wait / skip decision into a single
+  value (``"process"`` / ``"ask_user"`` / ``"skip"``). Centralizes the
+  exclusion logic that was previously dispersed across road /
+  media_type / main_video checks at each call site. Ordering is part of
+  the contract: ``skip`` (no main video, or media_type == ``"other"``)
+  wins over ``ask_user`` (media_type == ``"unknown"`` or road ==
+  ``"path_of_pain"``) which wins over ``process``. Surfaced through the
+  ``analyze_release`` tool so the LLM can route on it directly.
+  6 new tests in ``tests/application/test_inspect.py`` cover the four
+  branches and the precedence rules.
+- **`LanguageRepository` port** in `alfred.domain.shared.ports`. Structural
+  Protocol covering `from_iso`, `from_any`, `all`, `__contains__`, `__len__`
+  — the surface previously coupled to the concrete `LanguageRegistry`.
+  Mirrors the `MediaProber` / `FilesystemScanner` pattern: domain code
+  depends on the Protocol, infrastructure provides the YAML-backed
+  adapter. Tests in `tests/infrastructure/test_language_registry.py`.
+
+### Changed
+
+- **`Movie` and `Episode` are now frozen dataclasses.** Both entities
+  hold their track collections as `tuple[AudioTrack, ...]` and
+  `tuple[SubtitleTrack, ...]` instead of mutable lists, and are
+  `@dataclass(frozen=True, eq=False)` (identity-based equality
+  preserved via `__eq__`/`__hash__`). `__post_init__` coercion uses
+  `object.__setattr__` for the `imdb_id` / `title` /
+  `season_number` / `episode_number` normalizations. To project
+  enrichment results (probe output, file metadata) callers now rebuild
+  via `dataclasses.replace(...)`. Pattern aligned with the recent
+  `ParsedRelease` freeze. `MediaWithTracks` mixin contract updated to
+  `tuple` accordingly. `Season` and `TVShow` remain mutable for now —
+  freezing the aggregate root would cascade a full reconstruction on
+  every `add_episode`, deferred.
+- **`SubtitleCandidate` renamed to `SubtitleScanResult`.** The old name
+  conflated "this might become a placed subtitle" with "this is what a
+  scan pass produced". The class is the output of a scan/identify pass
+  — language/format may still be `None`, confidence reflects how sure
+  the classifier is, and `raw_tokens` holds the filename fragments
+  under analysis. `SubtitleScanResult` says that directly. Pure rename
+  with a refreshed docstring in `alfred/domain/subtitles/entities.py`;
+  no behavior change. Touches the domain entity + `__init__` export,
+  the matcher / identifier / utils services, the manage_subtitles use
+  case, the placer, the metadata store, the shared-media cross-ref
+  comment, and the seven test modules that imported the type.
+
+- **`ParsedRelease` is now frozen; enrichment passes return new
+  instances.** The VO was mutable so `detect_media_type` and
+  `enrich_from_probe` could patch fields in place — a code smell in a
+  value object whose identity *is* its content. `ParsedRelease` is now
+  `@dataclass(frozen=True)`; `languages` is a `tuple[str, ...]`
+  instead of a `list[str]`. `enrich_from_probe` returns a new
+  `ParsedRelease` via `dataclasses.replace` (only allocates when at
+  least one field actually changed). `inspect_release` rebinds
+  `parsed` after both `detect_media_type` (wrapped in `MediaTypeToken`
+  to satisfy the strict isinstance check that now also runs on
+  replace) and `enrich_from_probe`. Parser pipeline now packs
+  `languages` as a tuple in the assemble dict. Callers updated:
+  `inspect_release`, `testing/recognize_folders_in_downloads.py`, and
+  the enrichment tests (22 call sites + language assertions switched
+  to tuple literals).
+- **`resolve_destination` use cases take `kb` / `prober` as required
+  params; module-level singletons gone.** The four
+  `resolve_{season,episode,movie,series}_destination` use cases now
+  accept `kb: ReleaseKnowledge` and `prober: MediaProber` as required
+  arguments, matching the shape of `inspect_release`. The module-level
+  `_KB = YamlReleaseKnowledge()` and `_PROBER = FfprobeMediaProber()`
+  singletons that previously lived in
+  `alfred/application/filesystem/resolve_destination.py` are removed —
+  the application layer no longer reaches into infrastructure. The
+  singletons now live at the agent-tools frontier
+  (`alfred/agent/tools/filesystem.py`), where the LLM-facing wrappers
+  instantiate them once and thread them through. `analyze_release` no
+  longer needs the dirty `from ... import _KB` indirection. Tests
+  inject their own stubs by keyword (`prober=_StubProber(...)`) instead
+  of monkeypatching a module attribute.
+- **`ParsePath` enum renamed to `TokenizationRoute`.** The old name
+  collided with `pathlib.Path` in code-reading mental models, and was
+  one letter from `parse_path` (the field that holds the value) — making
+  it harder than it needed to be to spot the type vs the attribute.
+  ``TokenizationRoute`` says what it actually captures (DIRECT /
+  SANITIZED / AI = how the name reached the tokenizer), and the class
+  docstring now spells out the orthogonality with ``Road`` (EASY /
+  SHITTY / PATH_OF_PAIN, which captures parser confidence on
+  ``ParseReport``). The ``parse_path`` field name stays unchanged —
+  string values too — so YAML fixtures, the ``analyze_release`` tool
+  spec, and any external consumer are untouched.
+- **`enrich_from_probe` codec mappings moved to YAML.** The three
+  hard-coded module dicts (`_VIDEO_CODEC_MAP`, `_AUDIO_CODEC_MAP`,
+  `_CHANNEL_MAP`) translating ffprobe output to scene tokens
+  (`hevc → x265`, `eac3 → EAC3`, `8 → "7.1"`, …) now live in
+  `alfred/knowledge/release/probe_mappings.yaml` and are loaded into
+  `ReleaseKnowledge.probe_mappings` (new port field, populated by
+  `YamlReleaseKnowledge`). `enrich_from_probe` gains a third `kb`
+  parameter and reads the maps from there. Aligns with the CLAUDE.md
+  rule that lookup tables of domain knowledge belong in YAML, not in
+  Python — and opens the door to a future "learn new codec" pass.
+  Callers updated: `inspect_release`, `testing/recognize_folders_in_downloads.py`,
+  and all 22 sites in `tests/application/test_enrich_from_probe.py`.
+- **`ParsedRelease.tech_string` is now a derived `@property`**
+  (`alfred/domain/release/value_objects.py`). It computes
+  `quality.source.codec` joined by dots on every access, so it stays in
+  sync with the underlying fields by construction. The stored field is
+  gone from the dataclass, the dict returned by `assemble()` no longer
+  carries the key, `parse_release`'s malformed-name fallback drops the
+  `tech_string=""` kwarg, and `enrich_from_probe` no longer re-derives
+  it after filling `quality`/`source`/`codec`. Closes the
+  parser/enrichment double-source-of-truth that `e79ca46` had to fix
+  reactively. The fixtures runner now injects `tech_string` alongside
+  `is_season_pack` since `asdict()` skips properties.
+- **`RuleScope.level` is now an enum (`RuleScopeLevel`).** The set of
+  valid levels (global, release_group, movie, show, season, episode)
+  was documented only in a docstring comment and validated nowhere.
+  `RuleScopeLevel(str, Enum)` keeps wire compatibility (YAML
+  serialization, `.value` access) while making the closed set explicit
+  to type-checkers and IDEs. `to_dict()` emits `.value` strings so
+  YAML output is unchanged.
+- **`FilePath` VO uses `__post_init__` instead of a hand-rolled
+  `__init__`.** Same public API (accepts `str | Path`), same behavior,
+  but the dataclass-generated `__init__` is no longer bypassed. One
+  less smell in the shared VOs.
+- **`Language` VO is strict by default; `Language.from_raw()` factory
+  for normalization.** The previous `__post_init__` mutated `iso` and
+  `aliases` via `object.__setattr__` on a frozen dataclass — a code
+  smell hiding behind the dataclass facade. Split: the direct
+  constructor now rejects un-normalized input (uppercase iso,
+  whitespace in aliases, etc.), and `Language.from_raw()` handles
+  arbitrary YAML/user input. Only one caller (LanguageRegistry loading
+  the ISO YAML) needed migration.
+- **`ParsedRelease.normalised` renamed to `clean`.** The field name
+  promised "dots instead of spaces" but in practice held
+  `raw - site_tag - apostrophes` — only used by `season_folder_name()`.
+  Renamed and docstring corrected.
+- **`ParsedRelease.media_type` / `parse_path` are strict enums.** The
+  fields were already typed as `MediaTypeToken` / `ParsePath`, but a
+  tolerant `__post_init__` coerced raw strings. With both classes
+  being `(str, Enum)`, the coercion served no purpose. Strict
+  constructor; `.value` no longer passed at call sites; dropped the
+  unused `_VALID_MEDIA_TYPES` / `_VALID_PARSE_PATHS` lookup tables.
+
+### Removed
+
+- **`settings.min_movie_size_bytes`** — orphan Pydantic field +
+  validator. Its only consumer (`MovieService.validate_movie_file`)
+  had been removed during an earlier refactor. The "real movie vs
+  sample" rule now lives in extension-based exclusion
+  (`application/release/supported_media.py`) and PoP. If a size
+  threshold is ever needed, it'll go in a knowledge YAML, not in
+  `settings`.
+
+### Internal
+
+- **Flattened `alfred.domain.shared.media/` package into a single
+  `media.py` module.** The 6-file package (audio, video, subtitle,
+  info, matching, tracks_mixin + `__init__`) collapsed into one ~250
+  LoC module. All 12 import sites continue to resolve unchanged
+  (`from alfred.domain.shared.media import AudioTrack, MediaInfo, …`)
+  since Python treats `media.py` and `media/__init__.py`
+  interchangeably for import paths. Easier to scan when the whole
+  bounded-context fits on one screen.
+- **`SubtitleKnowledgeBase` types `language_registry` against the
+  `LanguageRepository` port** instead of the concrete `LanguageRegistry`
+  class. The default constructor still instantiates the concrete adapter
+  when no repository is injected — behaviour is unchanged for existing
+  callers. Opens the door to in-memory fakes in future tests without
+  loading the full ISO 639 YAML.
+- **Moved `detect_media_type` and `enrich_from_probe` from
+  `alfred.application.filesystem` to `alfred.application.release`**.
+  They are inspection-pipeline helpers — their natural home is next to
+  `inspect_release`, not next to the filesystem use cases. The move
+  also eliminates a circular-import workaround in
+  `resolve_destination.py`: `inspect_release` can now be imported at
+  module top instead of lazily inside `_resolve_parsed`. Public
+  surface is unchanged for callers that imported the helpers from
+  their full module paths (the only call sites — `inspect.py`, two
+  tests, one testing script — were updated in this commit).
+
+### Added
+
+- **`resolve_*_destination` use cases now consume `inspect_release`**.
+  `resolve_episode_destination` and `resolve_movie_destination` reuse
+  their existing `source_file` parameter as the inspection target;
+  `resolve_season_destination` and `resolve_series_destination` gain
+  a new **optional** `source_path` parameter (also threaded through
+  the tool wrappers and YAML specs). When the path exists, ffprobe
+  data fills tokens missing from the release name (e.g. quality) and
+  refreshes `tech_string`, so the destination folder / file names
+  end up more accurate. When the path is missing or absent (back-compat
+  callers), the use cases fall back to parse-only — same behavior as
+  before.
+
+### Fixed
+
+- **`enrich_from_probe` now refreshes `tech_string`** after filling
+  `quality` / `source` / `codec`. Previously the field stayed at its
+  parser-time value, so filename builders saw stale tech tokens even
+  after a successful probe. New `TestTechString` class in
+  `tests/application/test_enrich_from_probe.py` locks the behavior.
+
+### Added
+
+- **`inspect_release` orchestrator + `InspectedResult` VO**
+  (`alfred/application/release/inspect.py`). Single composition of the
+  four inspection layers: `parse_release` → `detect_media_type` (patches
+  `parsed.media_type`) → `find_main_video` (top-level scan) →
+  `prober.probe` + `enrich_from_probe` when a video exists and the
+  refined media type isn't in `{"unknown", "other"}`. Returns a frozen
+  `InspectedResult(parsed, report, source_path, main_video, media_info,
+  probe_used)` that downstream callers consume directly instead of
+  rebuilding the same chain. `kb` and `prober` are injected — no
+  module-level singletons. Never raises.
+
+### Changed
+
+- **`analyze_release` tool now delegates to `inspect_release`** — same
+  output shape, plus two new fields: `confidence` (0–100) and `road`
+  (`"easy"` / `"shitty"` / `"path_of_pain"`) surfaced from the parser's
+  `ParseReport`. The tool spec (`specs/analyze_release.yaml`) documents
+  both fields so the LLM can route releases by confidence.
+
+- **`MediaProber` port now covers full media probing**: added
+  `probe(video) -> MediaInfo | None` alongside the existing
+  `list_subtitle_streams`. `FfprobeMediaProber` (in
+  `alfred/infrastructure/probe/`) implements both methods and is now
+  the single adapter shelling out to `ffprobe`. The standalone
+  `alfred/infrastructure/filesystem/ffprobe.py` module was removed —
+  all callers (tools, testing scripts) instantiate
+  `FfprobeMediaProber` instead. Unblocks the upcoming
+  `inspect_release` orchestrator, which depends on the port.
+
+### Removed
+
+- `alfred/infrastructure/filesystem/ffprobe.py` (folded into the
+  `FfprobeMediaProber` adapter).
+
+---
+
+## [2026-05-20] — Release parser confidence scoring + exclusion
+
+### Added
+
+- **Pre-pipeline exclusion helpers** (`alfred/application/release/supported_media.py`):
+  `is_supported_video(path, kb)` (extension-only check against
+  `kb.video_extensions`) and `find_main_video(folder, kb)` (top-level
+  scan, lexicographically-first eligible file, returns `None` when no
+  video qualifies; accepts a bare file as folder for single-file
+  releases). No size threshold, no filename heuristics —
+  PATH_OF_PAIN handles the exotic cases. Foundation for the future
+  `inspect_release` orchestrator.
+
+- **Release parser — parse-confidence scoring** (`alfred/domain/release/parser/scoring.py`,
+  `alfred/knowledge/release/scoring.yaml`). `parse_release` now returns
+  `(ParsedRelease, ParseReport)`. The new `ParseReport` frozen VO
+  carries a 0–100 `confidence`, a `road` (`"easy"` / `"shitty"` /
+  `"path_of_pain"`), the residual UNKNOWN tokens, and the missing
+  critical fields. EASY is decided structurally (a group schema
+  matched); SHITTY vs PATH_OF_PAIN is decided by score against a
+  YAML-configurable cutoff (default 60). Weights and penalties also
+  live in `scoring.yaml` — title 30, media_type 20, year 15, season
+  10, episode 5, tech 5 each; penalty 5 per UNKNOWN token capped at
+  -30. `Road` is a new enum, distinct from `ParsePath` (which records
+  the tokenization route, not the confidence tier). `ReleaseKnowledge`
+  port gains a `scoring: dict` field.
+
+### Changed
+
+- **`parse_release` signature** is now `(name, kb) → tuple[ParsedRelease,
+  ParseReport]` instead of returning a bare `ParsedRelease`. Call
+  sites updated in `application/filesystem/resolve_destination.py` and
+  `agent/tools/filesystem.py`. Tests updated accordingly.
+
+---
+
+## [2026-05-20] — Release parser v2 (EASY + SHITTY)
+
+### Added
+
+- **Release parser v2 — EASY path live** (`alfred/domain/release/parser/`):
+  new annotate-based pipeline (tokenize → annotate → assemble) drives
+  releases from known groups. Exposes `Token` (frozen VO with `index` +
+  `role` + `extra`), `TokenRole` enum (structural/technical/meta families),
+  and `GroupSchema` / `SchemaChunk` value objects.
+  - `pipeline.tokenize`: string-ops separator split (no regex), strips
+    a `[site.tag]` prefix/suffix first.
+  - `pipeline.annotate`: detects the trailing group right-to-left
+    (priority to `codec-GROUP` shape, fallback to any non-source dashed
+    token), looks up its `GroupSchema`, then walks tokens and schema
+    chunks in lockstep — optional chunks that don't match are skipped,
+    mandatory mismatches abort EASY and return `None` so the caller can
+    fall back to SHITTY.
+  - `pipeline.assemble`: folds annotated tokens into a
+    `ParsedRelease`-compatible dict.
+  - `parse_release` (in `release.services`) tries the v2 EASY path first
+    and falls through to the legacy SHITTY heuristic on `None`. Legacy
+    SHITTY/PATH OF PAIN behavior is unchanged.
+  - Knowledge: `alfred/knowledge/release/release_groups/{kontrast,elite,
+    rarbg}.yaml` declare the canonical chunk order per group, loaded via
+    new `ReleaseKnowledge.group_schema(name)` port method.
+  - Tests in `tests/domain/release/test_parser_v2_{scaffolding,easy}.py`
+    cover token VOs, site-tag stripping, group detection, schema-driven
+    annotation (movie, TV episode, season pack with optional source),
+    and field assembly.
+
+- **Release parser v2 — enricher pass** completes the EASY pipeline.
+  The structural schema walk now tolerates non-positional tokens
+  between chunks (instead of aborting on leftover tokens), and a second
+  pass tags them with audio / video-meta / edition / language roles.
+  Multi-token sequences from `audio.yaml`, `video.yaml`, `editions.yaml`
+  (e.g. `DTS.HD.MA`, `DV.HDR10`, `TrueHD.Atmos`, `DIRECTORS.CUT`) are
+  matched before single tokens. Channel layouts like `5.1` and `7.1`
+  (split into two tokens by the `.` separator) are detected as
+  consecutive pairs. Sequence members carry an `extra["sequence_member"]`
+  marker so `assemble` extracts the canonical value only from the
+  primary token. KONTRAST releases with audio / HDR / edition / language
+  metadata now produce a fully populated `ParsedRelease`.
+
+- **Streaming distributor as a separate dimension** from encoding source.
+  New `alfred/knowledge/release/distributors.yaml` (NF, AMZN, DSNP, HMAX,
+  ATVP, HULU, PCOK, PMTP, CR) feeds a new `ReleaseKnowledge.distributors`
+  port field, a `TokenRole.DISTRIBUTOR` annotation, and a
+  `ParsedRelease.distributor` field. `WEB-DL` stays the source; the
+  platform that produced the release is now recorded distinctly. The
+  five entries (NF, AMZN, DSNP, HMAX, ATVP) were correspondingly removed
+  from `sources.yaml`.
+
+- **Real-world release fixtures** under `tests/fixtures/releases/{easy,shitty,path_of_pain}/`,
+  each documenting an expected `ParsedRelease` plus the future `routing`
+  (library / torrents / seed_hardlinks) for the upcoming `organize_media`
+  refactor. EASY bucket seeded with 5 cases (movie, single-episode, season
+  pack, movie + noise, YTS bracket-heavy). SHITTY bucket seeded with 15
+  anti-regression cases covering: 3-level INTEGRALE hierarchy (Angel),
+  French custom titles (Buffy, La Nuit au Musée, Chérie j'ai agrandi),
+  multi-episode chain `S14E09E10E11` (Archer, captures E11 loss),
+  lowercase `s01e01` (Notre Planète), `NxNN` with ` - ` separators
+  (Vinyl, captures dash artifact), title-with-year-suffix (Deutschland.83),
+  season-range `S01-06` (Tatortreiniger, captures movie misclassification),
+  bare folder name (Jurassic Park,
+  media_type=unknown), apostrophe-in-name (Honey Don't, captures full AI-path
+  degeneration), SUBS-tag movie (Hook), space separators (Predator Badlands,
+  captures group=UNKNOWN), subs-only release (Westworld S04).
+  PATH OF PAIN bucket seeded with 10 worst-case fixtures covering:
+  UTF-8 wide pipe yt-dlp slug (Khruangbin), 3-show franchise box-set
+  with double season range and parens-wrapped tech (Deutschland 83-86-89,
+  captures `group=S03` misdetection), accented chars in title (Chérie
+  BéBé with VFF), 8-word stand-up comedy title (Jimmy Carr), site-tag
+  prefix + XviD (OxTorrent), episode title + air-date silently lost
+  (Prodiges), full-chaos apostrophe + spaces + Blu-ray dash + 1080i +
+  multi-word audio codec (The Prodigy, full AI-path degeneration),
+  yt-dlp YouTube ID glued to year (Sleaford Mods), bilingual `[FR-EN]`
+  tag mistaken for group (Super Mario Bros), COMPLETE + S01-S07 range +
+  REPACK + HEVC (Gilmore Girls, the well-behaved exception).
+  Parametrized over `tests/domain/test_release_fixtures.py` for anti-regression.
+- **`NxNN` alt season/episode form supported** by `parse_release`. Releases like
+  `Show.1x05.720p.HDTV.x264-GRP` and `Show.2x07x08.1080p.WEB.x265-GRP` (multi-ep
+  alt form) now parse as TV shows.
+- **`alfred/knowledge/release/separators.yaml`** declares the token separators
+  used by the release-name tokenizer (`.`, ` `, `[`, `]`, `(`, `)`, `_`). New
+  conventions can be added without code changes. The canonical `.` is always
+  present even if missing from YAML.
+
+### Changed
+
+- **Release parser v2 — SHITTY simplified to dict-driven tagging**.
+  The legacy ~480-line heuristic block in `release/services.py` is gone;
+  `pipeline._annotate_shitty` does a single pass that looks each token
+  up in the kb buckets (resolutions / sources / codecs / distributors /
+  year / `SxxExx`) with first-match-wins semantics, and the leftmost
+  contiguous UNKNOWN run becomes the title. `annotate()` no longer
+  returns `None` — SHITTY is the always-on fallback when no group schema
+  matches. `services.py` shrunk from ~525 to ~85 lines. Four fixtures
+  (`deutschland_franchise_box`, `sleaford_yt_slug`,
+  `super_mario_bilingual`, `predator_space_separators` — the last one
+  moved from `shitty/` → `path_of_pain/`) are now marked
+  `pytest.mark.xfail(strict=False)` documenting PoP-grade pathologies
+  that SHITTY intentionally won't handle. `ReleaseFixture` grows an
+  `xfail_reason` field; the parametrized suite wires the xfail mark
+  automatically.
+
+- **`parse_release` tokenizer is now data-driven**: it splits on any character
+  listed in `separators.yaml` (regex character class) instead of `name.split(".")`.
+  This makes YTS-style releases (`The Father (2020) [1080p] [WEBRip] [5.1] [YTS.MX]`),
+  space-separated names (`Inception 2010 1080p BluRay x264-GROUP`), and
+  underscore-separated names parse correctly via the direct path — no more
+  fallback through sanitization.
+- **`parse_release` flow simplified**: site-tag extraction always runs first
+  (so `parse_path == "sanitized"` now reliably indicates a stripped `[tag]`),
+  then well-formedness is checked only against truly forbidden chars
+  (anything not in the configured separator set).
+- **ISO 639-2/B is now the canonical language code project-wide** (was a mix of
+  639-1 and 639-2/T):
+  - `SubtitlePreferences.languages` default is now `["fre", "eng"]` (was
+    `["fr", "en"]`). Old LTM files are not auto-migrated — delete
+    `data/memory/ltm.json` to regenerate with the new defaults.
+  - Subtitle output filenames are now `{iso639_2b}.srt` (e.g. `fre.srt`,
+    `fre.sdh.srt`). Existing `fr.srt` files are still **read** correctly
+    (recognized as French via alias) but new files are written canonically.
+  - `Language` value object docstring corrected: it has always stored 639-2/B
+    (matching what ffprobe emits), not 639-2/T as previously documented.
+- **`MovieService.validate_movie_file` minimum size is now configurable** via
+  `settings.min_movie_size_bytes` (default unchanged: 100 MB). Constructor
+  accepts an optional `min_movie_size_bytes` override for tests.
+- **`SubtitleKnowledgeBase` delegates language lookup to `LanguageRegistry`**
+  rather than duplicating tokens. `subtitles.yaml` now only declares
+  subtitle-specific tokens (e.g. `vostfr`, `vf`, `vff`) under a new
+  `language_tokens` section.
+
+### Removed
+
+- **`alfred/domain/tv_shows/services.py`** and **`alfred/domain/movies/services.py`**
+  deleted entirely. They held fossil parsers (`parse_episode_filename`,
+  `extract_movie_metadata`, …) with zero production callers — superseded by
+  `parse_release` as the single source of truth for release-name parsing.
+  Associated tests (`tests/domain/test_movies.py`, `tests/domain/test_tv_shows_service.py`)
+  removed as well.
+- `_sanitize` and `_normalize` helpers in `alfred/domain/release/services.py` —
+  the new tokenizer makes them redundant.
+- `_LANG_KEYWORDS`, `_SDH_TOKENS`, `_FORCED_TOKENS`, `SUBTITLE_EXTENSIONS`
+  hardcoded dicts in `alfred/domain/subtitles/scanner.py` — all knowledge now
+  lives in YAML (CLAUDE.md compliance).
+- `_MIN_MOVIE_SIZE_BYTES` module-level constant in
+  `alfred/domain/movies/services.py` — replaced by the new setting.
+- Top-level `languages:` block in `subtitles.yaml` — superseded by
+  `language_tokens:` (subtitle-specific only) since iso_languages.yaml is the
+  canonical source.
+
+### Fixed
+
+- **`hi` token no longer marks a subtitle as SDH** (it conflicted with the
+  ISO 639-1 alias for Hindi). SDH is now detected only via `sdh`, `cc`, and
+  `hearing` tokens.
+- `SubtitleKnowledgeBase` default rules used `"fra"` while
+  `iso_languages.yaml` exposes French as `"fre"` — preferred languages
+  defaults now match the canonical form.
+
+### Internal
+
+- **Domain I/O extraction** (`refactor/domain-io-extraction`): the domain
+  layer no longer performs subprocess calls, filesystem scans, or YAML
+  loading. Achieved in a series of focused commits:
+  - **Knowledge YAML loaders moved to infrastructure**:
+    `alfred/domain/release/knowledge.py`,
+    `alfred/domain/shared/knowledge/language_registry.py`, and
+    `alfred/domain/subtitles/knowledge/{base,loader}.py` relocated to
+    `alfred/infrastructure/knowledge/`. Re-exports were dropped — callers
+    import directly from the new location.
+  - **`MediaProber` and `FilesystemScanner` Protocol ports** introduced at
+    `alfred/domain/shared/ports/` with frozen-dataclass DTOs
+    (`SubtitleStreamInfo`, `FileEntry`). `SubtitleIdentifier` and
+    `PatternDetector` are now constructor-injected with concrete adapters
+    (`FfprobeMediaProber` wrapping `subprocess.run(ffprobe)` and
+    `PathlibFilesystemScanner` wrapping `pathlib`). No more direct
+    `subprocess`/`pathlib` usage from the subtitle domain services.
+  - **Live filesystem methods removed from VOs and entities**:
+    `FilePath.exists()` / `.is_file()` / `.is_dir()` deleted —
+    `FilePath` is now a pure address VO. `Movie.has_file()` and
+    `Episode.is_downloaded()` dropped. Callers either rely on a prior
+    detection step or use try/except over pre-checks (eliminates
+    TOCTOU races).
+  - **`SubtitlePlacer` moved to the application layer** at
+    `alfred/application/subtitles/placer.py` — it performs `os.link`
+    I/O, which doesn't belong in the domain. Pre-checks replaced with
+    try/except for `FileNotFoundError`/`FileExistsError`.
+  - **`SubtitleRuleSet.resolve()` no longer reaches into the knowledge
+    base**: the implicit `DEFAULT_RULES()` helper is gone, replaced by
+    an explicit `default_rules: SubtitleMatchingRules` parameter. The
+    `ManageSubtitles` use case loads defaults from the KB once and
+    passes them in.
+  - **`SubtitleKnowledge` Protocol port** at
+    `alfred/domain/subtitles/ports/knowledge.py` declares the read-only
+    query surface domain services consume (7 methods:
+    `known_extensions`, `format_for_extension`, `language_for_token`,
+    `is_known_lang_token`, `type_for_token`, `is_known_type_token`,
+    `patterns`). `SubtitleIdentifier` and `PatternDetector` depend on
+    this Protocol instead of the concrete `SubtitleKnowledgeBase` from
+    infrastructure — `domain/subtitles/` now has zero imports from
+    `infrastructure/`. The remaining domain → infra leak
+    (`domain/release/` loading separator YAML at import-time) is
+    documented in tech-debt and scheduled for its own branch.
+- **`to_dot_folder_name(title)` helper** in
+  `alfred/domain/shared/value_objects.py` — extracts the
+  `re.sub(r"[^\w\s\.\-]", "", title).replace(" ", ".")` pattern that was
+  duplicated between `MovieTitle.normalized()` and `TVShow.get_folder_name()`.
+- **`ParsedRelease.languages` uses `field(default_factory=list)`** instead of
+  a manual `__post_init__` that assigned `[]` via `object.__setattr__`.
+- **`file_extensions.yaml` splits subtitle sidecars (`.srt`, `.sub`, `.idx`,
+  `.ass`, `.ssa`) into a dedicated `subtitle:` category** instead of lumping
+  them under `metadata:`. The `_METADATA_EXTENSIONS` set used by
+  `detect_media_type` remains the union of both (same behavior — subtitles
+  are still ignored when deciding the media type of a folder), but a new
+  `load_subtitle_extensions()` loader is now available for the subtitles
+  domain. Sematic clarity, no functional change.
+- **`tv_shows/entities.py` module docstring** now shows the aggregate
+  ownership as an ASCII tree before the rule text — quicker visual scan
+  of the DDD structure.
+- Removed backward-compat shims `_sanitise_for_fs` /
+  `_strip_episode_from_normalised` from `domain/release/value_objects.py`
+  (zero callers).
+- Cleaned ruff warnings across the codebase: `subprocess.run` calls now pass
+  explicit `check=False` (PLW1510); lazy imports promoted to module top where
+  there was no cycle (PLC0415 in `manage_subtitles.py`, `placer.py`,
+  `qbittorrent/client.py`, `file_manager.py`); fixed module-level import
+  ordering (E402) in `language_registry.py` and `subtitles/knowledge/loader.py`;
+  removed unused locals (F841 / B007); replaced unnecessary set comprehension
+  with `set()` in `release/knowledge.py` (C416).
+- Ruff config: ignore `PLR0911` / `PLR0912` (too-many-returns / too-many-branches)
+  globally — noisy on parser mappers and orchestrator use-cases where early-return
+  validation is essential complexity. Ignore `PLW0603` for the documented memory
+  singleton (`infrastructure/persistence/context.py`).
+- **Release-knowledge DDD purification** (`refactor/domain-release-knowledge`):
+  the last domain → infrastructure leak (`domain/release/value_objects.py`
+  loading YAML at import-time) is gone. Achieved via:
+  - **`ReleaseKnowledge` Protocol port** at
+    `alfred/domain/release/ports/knowledge.py` declares the read-only query
+    surface release parsing needs (token sets for resolutions, sources, codecs,
+    languages, hdr extras; structured dicts for audio, video_meta, editions,
+    media_type_tokens; separators list; file-extension sets used by
+    application/infra callers; `sanitize_for_fs(text)` method).
+  - **`YamlReleaseKnowledge` adapter** at
+    `alfred/infrastructure/knowledge/release_kb.py` loads every YAML constant
+    once at construction. Builds an immutable `str.maketrans` translation
+    table for filesystem sanitization.
+  - **`parse_release(name, kb)`** takes the knowledge as an explicit
+    parameter — no more module-level YAML loading inside the domain. Every
+    internal helper (`_tokenize`, `_extract_tech`, `_extract_languages`,
+    `_extract_audio`, `_extract_video_meta`, `_extract_edition`,
+    `_extract_title`, `_infer_media_type`, `_is_well_formed`) takes `kb`.
+  - **`ParsedRelease` Option B**: sanitization happens once at parse time
+    and is stored on a new `title_sanitized: str` field. Builder methods
+    (`show_folder_name`, `season_folder_name`, `episode_filename`,
+    `movie_folder_name`, `movie_filename`) are now pure — they accept
+    already-sanitized `tmdb_title_safe` / `tmdb_episode_title_safe`
+    arguments. Callers at the use-case boundary sanitize TMDB strings
+    via `kb.sanitize_for_fs(...)` before passing them in.
+  - **All domain-knowledge constants removed from `value_objects.py`**:
+    `_RESOLUTIONS`, `_SOURCES`, `_CODECS`, `_AUDIO`, `_VIDEO_META`,
+    `_EDITIONS`, `_HDR_EXTRA`, `_MEDIA_TYPE_TOKENS`, `_LANGUAGE_TOKENS`,
+    `_FORBIDDEN_CHARS`, `_VIDEO_EXTENSIONS`, `_NON_VIDEO_EXTENSIONS`,
+    `_SUBTITLE_EXTENSIONS`, `_METADATA_EXTENSIONS`, `_WIN_FORBIDDEN_TABLE`,
+    and the `_sanitize_for_fs` helper. The domain module is now pure.
+  - **Application-layer KB singleton**: `resolve_destination.py` instantiates
+    a module-level `_KB: ReleaseKnowledge = YamlReleaseKnowledge()` and
+    threads it through every `parse_release(...)` call. The local
+    `_sanitize` helper and `_WIN_FORBIDDEN` regex were dropped in favor of
+    `_KB.sanitize_for_fs(...)`.
+  - **`detect_media_type(parsed, source_path, kb)` and
+    `find_video_file(path, kb)`** now take the knowledge explicitly
+    instead of importing `_*_EXTENSIONS` constants from the domain.
+    `agent/tools/filesystem.py::analyze_release` imports the application
+    KB singleton and passes it through.
+
+---
+
+## [2026-05-17] — TVShow & Movie aggregate refactor
+
+Multi-phase refonte of the TV show domain into a real DDD aggregate, with
+matching parity work on `Movie`, a language knowledge system, and the
+`shared/media` restructure that supports both.
+
+### Added
+
+- **Language knowledge system** (`alfred/knowledge/iso_languages.yaml` + 42
+  languages including `und` for undetermined).
+  - `Language` value object (frozen dataclass) with `iso`, `english_name`,
+    `native_name`, `aliases`, and a `matches(raw)` cross-format helper.
+  - `LanguageRegistry` loader (`alfred/domain/shared/knowledge/`) merging
+    builtin + learned YAML. Not a singleton — the application layer
+    instantiates it.
+  - ISO 639-2/B is the canonical key; aliases cover 639-1, 639-2/T, English
+    name, native name, and common spellings.
+- **`VideoTrack`** dataclass (`alfred/domain/shared/media/video.py`) with a
+  `resolution` property using width-priority bucket detection (handles
+  cinema/scope crops like 1920×960 → 1080p).
+- **`shared/media/matching.py`** — `track_lang_matches` helper shared by
+  `Episode` and `Movie`. Implements the **"C+" contract** for language helpers:
+  - `Language` query → cross-format match via `Language.matches()`
+  - `str` query → case-insensitive direct comparison (no normalization)
+- **TVShow aggregate composition**:
+  - `TVShow.seasons: dict[SeasonNumber, Season]`
+  - `Season.episodes: dict[EpisodeNumber, Episode]`
+  - `Season.expected_episodes` / `Season.aired_episodes` (split so collection
+    state can compare "owned vs aired today" without confusing in-flight
+    seasons with future ones)
+- **Aggregate methods on `TVShow`**:
+  - `add_episode(ep)` — sole sanctioned mutation entry point (creates the
+    season if missing)
+  - `add_season(season)` — replaces a season wholesale
+  - `collection_status()` → `CollectionStatus.{EMPTY, PARTIAL, COMPLETE}`
+  - `is_complete_series()` — true iff `ENDED + COMPLETE`
+  - `missing_episodes()` — flat list of all aired-but-not-owned
+    `(season, episode)` pairs
+- **`CollectionStatus`** enum (orthogonal to `ShowStatus`).
+- **Episode track helpers** (`has_audio_in`, `has_subtitles_in`,
+  `has_forced_subs`, `audio_languages`, `subtitle_languages`), driven by
+  `Episode.audio_tracks` / `Episode.subtitle_tracks`.
+- **Movie aggregate parity** — `Movie` now carries `audio_tracks` /
+  `subtitle_tracks` and exposes the same helpers as `Episode` (same C+
+  contract).
+- **`CHANGELOG.md`** (this file).
+
+### Changed
+
+- **`shared/media_info.py` exploded into `shared/media/{audio,video,subtitle,info,matching}.py`.**
+  `MediaInfo` is now symmetric: every stream type is a `list[Track]`. Flat
+  accessors (`width`, `height`, `video_codec`, `resolution`) remain as
+  properties that read the first video track.
+- **`MediaInfo.duration_seconds` / `bitrate_kbps`** moved from `VideoTrack` to
+  `MediaInfo` (file-level — they come from the ffprobe `format` block, not a
+  stream). Files without a video stream now correctly expose duration.
+- **`ShowStatus.from_string`** extended to map TMDB strings (`Returning
+  Series`, `In Production`, `Pilot`, `Planned`, `Canceled`, `Cancelled`).
+  Comparison is whitespace-trimmed and case-insensitive.
+- **`Season` / `Episode`** dropped their `show_imdb_id` back-references. They
+  are owned by `TVShow` and reached only through it.
+- **`TVShow.seasons_count` and `episode_count`** are now `@property` (computed
+  from the dict) instead of stored ints.
+- **`TVShowService.parse_episode_from_filename`** rewritten in string
+  operations (no regex). Supports `S01E05` / `s1e5` and `1x05` / `01x5` forms.
+- **`TVShowService.find_next_episode`** now drives off
+  `show.missing_episodes()` instead of the hardcoded "max 50 episodes per
+  season" heuristic.
+- **`TVShowService` constructor** no longer takes `season_repository` /
+  `episode_repository` — the aggregate persists in one block via
+  `TVShowRepository` only.
+- **`SubtitleTrack` in `alfred.domain.subtitles.entities` renamed to
+  `SubtitleCandidate`.** Coexists with the `shared.media.SubtitleTrack`
+  ffprobe-view dataclass (different bounded contexts, kept separate
+  intentionally).
+- **`tv_shows/services.py` `_VIDEO_EXTENSIONS`** now loaded from
+  `knowledge/release/file_extensions.yaml` via `load_video_extensions()`
+  (single source of truth).
+- **`CLAUDE.md`** updated with three new policy sections:
+  - "Tests" — small updates OK during normal work, no mass-update sprees
+  - "Backwards-compatibility shims" — prefer clean migration over shims
+  - "Regex" — not forbidden, use judgment when string ops would be fragile
+
+### Removed
+
+- **Legacy `Season N Episode N` filename form** in
+  `TVShowService.parse_episode_from_filename`. It never appears in the release
+  names Alfred handles, and supporting it forced a regex.
+- **`SeasonRepository` and `EpisodeRepository`** — only the aggregate root has
+  a repository (DDD rule: one repo per aggregate).
+- **`shared/media_info.py`** compatibility shim — callers updated.
+- **`SubtitleTrack` compatibility alias** in `subtitles.entities` — callers
+  updated to `SubtitleCandidate`.
+
+### Fixed
+
+- **`MediaInfo.duration_seconds` returns `None` on audio-only files** instead
+  of crashing through `primary_video.duration_seconds` (see the duration/bitrate
+  move under **Changed**).
+- **`MediaOrganizer`** (`infrastructure/filesystem/organizer.py`) no longer
+  passes the removed `show_imdb_id` / `episode_count` kwargs when constructing
+  a `Season` for folder-name generation.
+
+### Internal
+
+- Test suite rewritten where the aggregate redesign broke fixtures:
+  `tests/domain/test_tv_shows.py` (69 tests), `tests/domain/test_media_info.py`
+  (rewritten for `VideoTrack`), `tests/application/test_enrich_from_probe.py`
+  (helper added), `tests/infrastructure/test_filesystem_extras.py` (fixtures),
+  `tests/domain/test_tv_shows_service.py` (find_next_episode driven by real
+  aggregate state).
+- Subtitle services internal migration: `matcher.py`, `utils.py`, `placer.py`,
+  `identifier.py` updated to import `SubtitleCandidate`.
+- Suite status at end of block: **1066 passed, 8 skipped, 0 failed**.

CONTRIBUTE.md

@@ -1,261 +0,0 @@
-# Contributing to Alfred
-
-## Settings Management System
-
-Alfred uses a **declarative, schema-based configuration system** that ensures type safety, validation, and maintainability.
-
-### Architecture Overview
-
-```
-settings.toml          # Schema definitions (single source of truth)
-    ↓
-settings_schema.py     # Parser & validation
-    ↓
-settings_bootstrap.py  # Generation & resolution
-    ↓
-.env                   # Runtime configuration
-.env.make              # Build variables for Makefile
-    ↓
-settings.py            # Pydantic Settings (runtime validation)
-```
-
-### Key Files
-
-- **`settings.toml`** — Declarative schema for all settings
-- **`alfred/settings_schema.py`** — Schema parser and validation logic
-- **`alfred/settings_bootstrap.py`** — Bootstrap logic (generates `.env` and `.env.make`)
-- **`alfred/settings.py`** — Pydantic Settings class (runtime)
-- **`.env`** — Generated configuration file (gitignored)
-- **`.env.make`** — Build variables for Makefile (gitignored)
-
-### Setting Sources
-
-Settings can come from different sources:
-
-| Source | Description | Example |
-|--------|-------------|---------|
-| `toml` | From `pyproject.toml` | Version numbers, build config |
-| `env` | From `.env` file | User-provided values, API keys |
-| `generated` | Auto-generated secrets | JWT secrets, passwords |
-| `computed` | Calculated from other settings | Database URIs |
-
-### How to Add a New Setting
-
-#### 1. Define in `settings.toml`
-
-```toml
-[tool.alfred.settings_schema.MY_NEW_SETTING]
-type = "string"                    # string, integer, float, boolean, secret, computed
-source = "env"                     # env, toml, generated, computed
-default = "default_value"          # Optional: default value
-description = "Description here"   # Required: clear description
-category = "app"                   # app, api, database, security, build
-required = true                    # Optional: default is true
-validator = "range:1:100"          # Optional: validation rule
-export_to_env_make = false         # Optional: export to .env.make for Makefile
-```
-
-#### 2. Regenerate Configuration
-
-```bash
-make bootstrap
-```
-
-This will:
-- Read the schema from `settings.toml`
-- Generate/update `.env` with the new setting
-- Generate/update `.env.make` if `export_to_env_make = true`
-- Preserve existing secrets
-
-#### 3. Validate
-
-```bash
-make validate
-```
-
-This ensures all settings are valid according to the schema.
-
-#### 4. Use in Code
-
-The setting is automatically available in `settings.py`:
-
-```python
-from alfred.settings import settings
-
-print(settings.my_new_setting)
-```
-
-### Setting Types
-
-#### String Setting
-
-```toml
-[tool.alfred.settings_schema.API_URL]
-type = "string"
-source = "env"
-default = "https://api.example.com"
-description = "API base URL"
-category = "api"
-```
-
-#### Integer Setting with Validation
-
-```toml
-[tool.alfred.settings_schema.MAX_RETRIES]
-type = "integer"
-source = "env"
-default = 3
-description = "Maximum retry attempts"
-category = "app"
-validator = "range:1:10"
-```
-
-#### Secret (Auto-generated)
-
-```toml
-[tool.alfred.settings_schema.API_SECRET]
-type = "secret"
-source = "generated"
-secret_rule = "32:b64"  # 32 bytes, base64 encoded
-description = "API secret key"
-category = "security"
-```
-
-Secret rules:
-- `"32:b64"` — 32 bytes, URL-safe base64
-- `"16:hex"` — 16 bytes, hexadecimal
-
-#### Computed Setting
-
-```toml
-[tool.alfred.settings_schema.DATABASE_URL]
-type = "computed"
-source = "computed"
-compute_from = ["DB_HOST", "DB_PORT", "DB_NAME"]
-compute_template = "postgresql://{DB_HOST}:{DB_PORT}/{DB_NAME}"
-description = "Database connection URL"
-category = "database"
-```
-
-#### From TOML (Build Variables)
-
-```toml
-[tool.alfred.settings_schema.APP_VERSION]
-type = "string"
-source = "toml"
-toml_path = "tool.poetry.version"
-description = "Application version"
-category = "build"
-export_to_env_make = true  # Available in Makefile
-```
-
-### Validators
-
-Available validators:
-
-- **`range:min:max`** — Numeric range validation
-  ```toml
-  validator = "range:0.0:2.0"  # For floats
-  validator = "range:1:100"    # For integers
-  ```
-
-### Categories
-
-Organize settings by category:
-
-- **`app`** — Application settings
-- **`api`** — API keys and external services
-- **`database`** — Database configuration
-- **`security`** — Secrets and security keys
-- **`build`** — Build-time configuration
-
-### Best Practices
-
-1. **Always add a description** — Make it clear what the setting does
-2. **Use appropriate types** — Don't use strings for numbers
-3. **Add validation** — Use validators for numeric ranges
-4. **Categorize properly** — Helps with organization
-5. **Use computed settings** — For values derived from others (e.g., URIs)
-6. **Mark secrets as generated** — Let the system handle secret generation
-7. **Export build vars** — Set `export_to_env_make = true` for Makefile variables
-
-### Workflow Example
-
-```bash
-# 1. Edit settings.toml
-vim settings.toml
-
-# 2. Regenerate configuration
-make bootstrap
-
-# 3. Validate
-make validate
-
-# 4. Test
-python -c "from alfred.settings import settings; print(settings.my_new_setting)"
-
-# 5. Commit (settings.toml only, not .env)
-git add settings.toml
-git commit -m "Add MY_NEW_SETTING"
-```
-
-### Commands
-
-```bash
-make bootstrap  # Generate .env and .env.make from schema
-make validate   # Validate all settings against schema
-make help       # Show all available commands
-```
-
-### Troubleshooting
-
-**Setting not found in schema:**
-```
-KeyError: Missing [tool.alfred.settings_schema] section
-```
-→ Check that `settings.toml` exists and has the correct structure
-
-**Validation error:**
-```
-ValueError: MY_SETTING must be between 1 and 100, got 150
-```
-→ Check the validator in `settings.toml` and adjust the value in `.env`
-
-**Secret not preserved:**
-→ Secrets are automatically preserved during `make bootstrap`. If lost, they were never in `.env` (check `.env` exists before running bootstrap)
-
-### Testing
-
-When adding a new setting, consider adding tests:
-
-```python
-# tests/test_settings_schema.py
-def test_my_new_setting(self, create_schema_file):
-    """Test MY_NEW_SETTING definition."""
-    schema_toml = """
-[tool.alfred.settings_schema.MY_NEW_SETTING]
-type = "string"
-source = "env"
-default = "test"
-"""
-    base_dir = create_schema_file(schema_toml)
-    schema = load_schema(base_dir)
-
-    definition = schema.get("MY_NEW_SETTING")
-    assert definition.default == "test"
-```
-
-### Migration from Old System
-
-If you're migrating from the old system:
-
-1. Settings are now in `settings.toml` instead of scattered across files
-2. No more `.env.example` — schema is the source of truth
-3. Secrets are auto-generated and preserved
-4. Validation happens at bootstrap time, not just runtime
-
----
-
-## Questions?
-
-Open an issue or check the existing settings in `settings.toml` for examples.

Dockerfile

@@ -2,46 +2,36 @@
 # check=skip=InvalidDefaultArgInFrom
 
 ARG PYTHON_VERSION
-ARG PYTHON_VERSION_SHORT
-ARG RUNNER
+ARG UV_VERSION
+
+# Stage 0: uv binary (workaround — --from doesn't support ARG expansion)
+FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv-bin
+
 # ===========================================
 # Stage 1: Builder
 # ===========================================
 FROM python:${PYTHON_VERSION}-slim-bookworm AS builder
 
-# Re-declare ARGs after FROM to make them available in this stage
-ARG RUNNER
-
-# STFU - No need - Write logs asap
 ENV DEBIAN_FRONTEND=noninteractive \
     PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONUNBUFFERED=1
+    PYTHONUNBUFFERED=1 \
+    UV_PROJECT_ENVIRONMENT=/venv
 
-# Install build dependencies (needs root)
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    build-essential \
-    && rm -rf /var/lib/apt/lists/*
+# Install build dependencies
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update \
+    && apt-get install -y --no-install-recommends build-essential
 
-# Install runner globally (needs root) - Save cache for future
-RUN --mount=type=cache,target=/root/.cache/pip \
-    pip install $RUNNER
+# Install uv globally
+COPY --from=uv-bin /uv /usr/local/bin/uv
 
-# Set working directory for dependency installation
 WORKDIR /tmp
 
-# Copy dependency files
-COPY pyproject.toml poetry.lock* uv.lock* Makefile ./
+COPY pyproject.toml uv.lock Makefile ./
 
-# Install dependencies as root (to avoid permission issues with system packages)
-RUN --mount=type=cache,target=/root/.cache/pip \
-    --mount=type=cache,target=/root/.cache/pypoetry \
-    --mount=type=cache,target=/root/.cache/uv \
-    if [ "$RUNNER" = "poetry" ]; then \
-        poetry config virtualenvs.create false && \
-        poetry install --only main --no-root; \
-    elif [ "$RUNNER" = "uv" ]; then \
-        uv pip install --system -r pyproject.toml; \
-    fi
+# Install dependencies into /venv
+RUN --mount=type=cache,target=/root/.cache/uv uv sync
 
 COPY scripts/ ./scripts/
 COPY .env.example ./
@@ -51,16 +41,7 @@ COPY .env.example ./
 # ===========================================
 FROM builder AS test
 
-ARG RUNNER
-
-RUN --mount=type=cache,target=/root/.cache/pip \
-    --mount=type=cache,target=/root/.cache/pypoetry \
-    --mount=type=cache,target=/root/.cache/uv \
-    if [ "$RUNNER" = "poetry" ]; then \
-        poetry install --no-root; \
-    elif [ "$RUNNER" = "uv" ]; then \
-        uv pip install --system -e .[dev]; \
-    fi
+RUN --mount=type=cache,target=/root/.cache/uv uv sync --group dev
 
 COPY alfred/ ./alfred
 COPY scripts ./scripts
@@ -71,52 +52,39 @@ COPY tests/  ./tests
 # ===========================================
 FROM python:${PYTHON_VERSION}-slim-bookworm AS runtime
 
-ARG PYTHON_VERSION_SHORT
-
-# TODO: A-t-on encore besoin de toutes les clés  ?
-ENV LLM_PROVIDER=deepseek \
-    MEMORY_STORAGE_DIR=/data/memory \
-    PYTHONDONTWRITEBYTECODE=1 \
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
     PYTHONPATH=/home/appuser \
-    PYTHONUNBUFFERED=1
+    PATH="/venv/bin:$PATH"
 
-# Install runtime dependencies (needs root)
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    ca-certificates \
-    && rm -rf /var/lib/apt/lists/* \
-    && apt-get clean
+# Install runtime dependencies
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates
 
 # Create non-root user
 RUN useradd -m -u 1000 -s /bin/bash appuser
 
-# Create data directories (needs root for /data)
+# Create data directories
 RUN mkdir -p /data /logs \
     && chown -R appuser:appuser /data /logs
 
-# Switch to non-root user
 USER appuser
-
-# Set working directory (owned by appuser)
 WORKDIR /home/appuser
 
-# Copy Python packages from builder stage
-COPY --from=builder /usr/local/lib/python${PYTHON_VERSION_SHORT}/site-packages /usr/local/lib/python${PYTHON_VERSION_SHORT}/site-packages
-COPY --from=builder /usr/local/bin /usr/local/bin
+# Copy venv from builder stage
+COPY --from=builder /venv /venv
 
-# Copy application code (already owned by appuser)
+# Copy application code
 COPY --chown=appuser:appuser alfred/ ./alfred
 COPY --chown=appuser:appuser scripts/ ./scripts
 COPY --chown=appuser:appuser .env.example ./
 COPY --chown=appuser:appuser pyproject.toml ./
-COPY --chown=appuser:appuser settings.toml ./
 
-# Create volumes for persistent data
 VOLUME ["/data", "/logs"]
-
-# Expose port
 EXPOSE 8000
 
-# Health check
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
     CMD python -c "import requests; requests.get('http://localhost:8000/health', timeout=5).raise_for_status()" || exit 1
 

Makefile

@@ -1,6 +1,7 @@
 .DEFAULT_GOAL := help
 
 # --- Load Config from pyproject.toml ---
+export
 -include .env.make
 
 # --- Profiles management ---
@@ -9,36 +10,29 @@ p ?= full
 PROFILES_PARAM	:= COMPOSE_PROFILES=$(p)
 
 # --- Commands ---
-DOCKER_COMPOSE	:= docker compose
-DOCKER_BUILD	:= docker build --no-cache \
+DOCKER_COMPOSE	:= docker compose \
+					--env-file .env.alfred \
+					--env-file .env.secrets \
+					--env-file .env.make
+DOCKER_BUILD	:= DOCKER_BUILDKIT=1 docker build \
 					--build-arg PYTHON_VERSION=$(PYTHON_VERSION) \
-					--build-arg PYTHON_VERSION_SHORT=$(PYTHON_VERSION_SHORT) \
-					--build-arg RUNNER=$(RUNNER)
+					--build-arg UV_VERSION=$(UV_VERSION)
 
 # --- Phony ---
-.PHONY: .env bootstrap validate up down restart logs ps shell build build-test install \
+.PHONY: bootstrap up down restart logs ps shell build build-test install \
 	update install-hooks test coverage lint format clean major minor patch help
 
 # --- Setup ---
-.env:
+.env.alfred .env.librechat .env.secrets .env.make:
 	@echo "Initializing environment..."
-	@python scripts/bootstrap.py \
+	@uv run python scripts/bootstrap.py \
 		&& echo "✓ Environment ready" \
 		|| (echo "✗ Environment setup failed" && exit 1)
 
-# .env.make is automatically generated by bootstrap.py when .env is created
-.env.make: .env
-
-bootstrap: .env
-
-validate:
-	@echo "Validating settings..."
-	@python scripts/validate_settings.py \
-		&& echo "✓ Settings valid" \
-		|| (echo "✗ Settings validation failed" && exit 1)
+bootstrap: .env.alfred .env.librechat .env.secrets .env.make
 
 # --- Docker ---
-up: .env
+up: .env.alfred .env.secrets
 	@echo "Starting containers with profiles: [full]..."
 	@$(PROFILES_PARAM) $(DOCKER_COMPOSE) up -d --remove-orphans \
 		&& echo "✓ Containers started" \
@@ -83,45 +77,45 @@ build-test: .env.make
 
 # --- Dependencies ---
 install:
-	@echo "Installing dependencies with $(RUNNER)..."
-	@$(RUNNER) install \
+	@echo "Installing dependencies with uv..."
+	@uv install \
 		&& echo "✓ Dependencies installed" \
 		|| (echo "✗ Installation failed" && exit 1)
 
 install-hooks:
 	@echo "Installing pre-commit hooks..."
-	@$(RUNNER) run pre-commit install \
+	@uv run pre-commit install \
 		&& echo "✓ Hooks installed" \
 		|| (echo "✗ Hook installation failed" && exit 1)
 
 update:
-	@echo "Updating dependencies with $(RUNNER)..."
-	@$(RUNNER) update \
+	@echo "Updating dependencies with uv..."
+	@uv update \
 		&& echo "✓ Dependencies updated" \
 		|| (echo "✗ Update failed" && exit 1)
 
 # --- Quality ---
 test:
 	@echo "Running tests..."
-	@$(RUNNER) run pytest \
+	@uv run pytest \
 		&& echo "✓ Tests passed" \
 		|| (echo "✗ Tests failed" && exit 1)
 
 coverage:
 	@echo "Running tests with coverage..."
-	@$(RUNNER) run pytest --cov=. --cov-report=html --cov-report=term \
+	@uv run pytest --cov=. --cov-report=html --cov-report=term \
 		&& echo "✓ Coverage report generated" \
 		|| (echo "✗ Coverage failed" && exit 1)
 
 lint:
 	@echo "Linting code..."
-	@$(RUNNER) run ruff check --fix . \
+	@uv run ruff check --fix . \
 		&& echo "✓ Linting complete" \
 		|| (echo "✗ Linting failed" && exit 1)
 
 format:
 	@echo "Formatting code..."
-	@$(RUNNER) run ruff format . && $(RUNNER) run ruff check --fix . \
+	@uv run ruff format . && uv run ruff check --fix . \
 		&& echo "✓ Code formatted" \
 		|| (echo "✗ Formatting failed" && exit 1)
 
@@ -134,7 +128,7 @@ clean:
 # --- Versioning ---
 major minor patch: _check-main
 	@echo "Bumping $@ version..."
-	@$(RUNNER) run bump-my-version bump $@ \
+	@uv run bump-my-version bump $@ \
 		&& echo "✓ Version bumped" \
 		|| (echo "✗ Version bump failed" && exit 1)
 
@@ -147,8 +141,7 @@ major minor patch: _check-main
 _ci-dump-config:
 	@echo "image_name=$(IMAGE_NAME)"
 	@echo "python_version=$(PYTHON_VERSION)"
-	@echo "python_version_short=$(PYTHON_VERSION_SHORT)"
-	@echo "runner=$(RUNNER)"
+	@echo "uv_version=$(UV_VERSION)"
 	@echo "service_name=$(SERVICE_NAME)"
 
 _ci-run-tests:build-test
@@ -171,11 +164,10 @@ help:
 	@echo "Usage: make [target] [p=profile1,profile2]"
 	@echo ""
 	@echo "Setup:"
-	@echo "  bootstrap   Generate .env and .env.make from schema"
-	@echo "  validate    Validate settings against schema"
+	@echo "  bootstrap   Generate .env.alfred, .env.librechat, .env.secrets and .env.make"
 	@echo ""
 	@echo "Docker:"
-	@echo "  up          Start containers (default profile: full)"
+	@echo "  up          Start containers (default profile: core)"
 	@echo "              Example: make up p=rag,meili"
 	@echo "  down        Stop all containers"
 	@echo "  restart     Restart containers (supports p=...)"
@@ -185,7 +177,8 @@ help:
 	@echo "  build       Build the production Docker image"
 	@echo ""
 	@echo "Dev & Quality:"
-	@echo "  install     Install dependencies via $(RUNNER)"
+	@echo "  setup       Bootstrap .env and security keys"
+	@echo "  install     Install dependencies via uv"
 	@echo "  test        Run pytest suite"
 	@echo "  coverage    Run tests and generate HTML report"
 	@echo "  lint/format Quality and style checks"

README.md

@@ -3,7 +3,7 @@
 An AI-powered agent for managing your local media library with natural language. Search, download, and organize movies and TV shows effortlessly through a conversational interface.
 
 [![Python 3.14](https://img.shields.io/badge/python-3.14-blue.svg)](https://www.python.org/downloads/)
-[![Poetry](https://img.shields.io/badge/dependency%20manager-poetry-blue)](https://python-poetry.org/)
+[![uv](https://img.shields.io/badge/dependency%20manager-uv-purple)](https://github.com/astral-sh/uv)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 
@@ -13,9 +13,10 @@ An AI-powered agent for managing your local media library with natural language.
 - 🔍 **Smart Search** — Find movies and TV shows via TMDB with rich metadata
 - 📥 **Torrent Integration** — Search and download via qBittorrent
 - 🧠 **Contextual Memory** — Remembers your preferences and conversation history
-- 📁 **Auto-Organization** — Keeps your media library tidy and well-structured
-- 🌐 **OpenAI-Compatible API** — Works with any OpenAI-compatible client
-- 🖥️ **LibreChat Frontend** — Beautiful web UI included out of the box
+- 📁 **Auto-Organization** — Moves and renames media files, resolves destinations, handles subtitles
+- 🎞️ **Subtitle Pipeline** — Identifies, matches, and places subtitle tracks automatically
+- 🔄 **Workflow Engine** — YAML-defined multi-step workflows (e.g. `organize_media`)
+- 🌐 **OpenAI-Compatible API** — Works with any OpenAI-compatible client (LibreChat, OpenWebUI, etc.)
 - 🔒 **Secure by Default** — Auto-generated secrets and encrypted credentials
 
 ## 🏗️ Architecture
@@ -26,33 +27,50 @@ Built with **Domain-Driven Design (DDD)** principles for clean separation of con
 alfred/
 ├── agent/              # AI agent orchestration
 │   ├── llm/            # LLM clients (Ollama, DeepSeek)
-│   └── tools/          # Tool implementations
+│   ├── tools/          # Tool implementations (api, filesystem, language)
+│   └── workflows/      # YAML-defined multi-step workflows
 ├── application/        # Use cases & DTOs
-│   ├── movies/         # Movie search use cases
+│   ├── movies/         # Movie search
 │   ├── torrents/       # Torrent management
-│   └── filesystem/     # File operations
+│   └── filesystem/     # File operations (move, list, subtitles, seed links)
 ├── domain/             # Business logic & entities
+│   ├── media/          # Release parsing
 │   ├── movies/         # Movie entities
-│   ├── tv_shows/       # TV show entities
-│   └── subtitles/      # Subtitle entities
+│   ├── tv_shows/       # TV show entities & value objects
+│   ├── subtitles/      # Subtitle scanner, services, knowledge base
+│   └── shared/         # Common value objects (ImdbId, FilePath, FileSize)
 └── infrastructure/     # External services & persistence
-    ├── api/            # External API clients (TMDB, qBittorrent)
-    ├── filesystem/     # File system operations
-    └── persistence/    # Memory & repositories
+    ├── api/            # External API clients (TMDB, qBittorrent, Knaben)
+    ├── filesystem/     # File manager (hard-link based, path-traversal safe)
+    ├── persistence/    # Three-tier memory (LTM/STM/Episodic) + JSON repositories
+    └── subtitle/       # Subtitle infrastructure
 ```
 
-See [docs/architecture_diagram.md](docs/architecture_diagram.md) for detailed architectural diagrams.
+### Key flows
+
+**Agent execution:** `agent.step(user_input)` → LLM call → if tool_calls, execute each via registry → loop until no tool calls or `max_tool_iterations` → return final response.
+
+**Media organization workflow:**
+1. `resolve_destination` — Determines target folder/filename from release name
+2. `move_media` — Hard-links file to library, deletes source
+3. `manage_subtitles` — Scans, classifies, and places subtitle tracks
+4. `create_seed_links` — Hard-links library file back to torrents/ for continued seeding
+
+**Memory tiers:**
+- **LTM** (`data/memory/ltm.json`) — Persisted config, media library, watchlist
+- **STM** — Conversation history (capped at `MAX_HISTORY_MESSAGES`)
+- **Episodic** — Transient search results, active downloads, recent errors
 
 ## 🚀 Quick Start
 
 ### Prerequisites
 
-- **Python 3.14+** (required)
-- **Poetry** (dependency manager)
+- **Python 3.14+**
+- **uv** (dependency manager)
 - **Docker & Docker Compose** (recommended for full stack)
 - **API Keys:**
   - TMDB API key ([get one here](https://www.themoviedb.org/settings/api))
-  - Optional: DeepSeek, OpenAI, Anthropic, or other LLM provider keys
+  - Optional: DeepSeek or other LLM provider keys
 
 ### Installation
 
@@ -64,9 +82,15 @@ cd alfred_media_organizer
 # Install dependencies
 make install
 
+# Install pre-commit hooks
+make install-hooks
+
 # Bootstrap environment (generates .env with secure secrets)
 make bootstrap
 
+# Validate your .env against the schema
+make validate
+
 # Edit .env with your API keys
 nano .env
 ```
@@ -94,162 +118,95 @@ The web interface will be available at **http://localhost:3080**
 ### Running Locally (Development)
 
 ```bash
-# Install dependencies
-poetry install
-
-# Start the API server
-poetry run uvicorn alfred.app:app --reload --port 8000
+uv run uvicorn alfred.app:app --reload --port 8000
 ```
 
 ## ⚙️ Configuration
 
-### Environment Bootstrap
+### Settings system
 
-Alfred uses a smart bootstrap system that:
+`settings.toml` is the single source of truth. The schema flows:
 
-1. **Generates secure secrets** automatically (JWT tokens, database passwords, encryption keys)
-2. **Syncs build variables** from `pyproject.toml` (versions, image names)
-3. **Preserves existing secrets** when re-running (never overwrites your API keys)
-4. **Computes database URIs** automatically from individual components
+```
+settings.toml → settings_schema.py → settings_bootstrap.py → .env + .env.make → settings.py
+```
+
+To add a setting: define it in `settings.toml`, run `make bootstrap`, then access via `settings.my_new_setting`.
 
 ```bash
 # First time setup
 make bootstrap
 
-# Re-run after updating pyproject.toml (secrets are preserved)
+# Validate existing .env against schema
+make validate
+
+# Re-run after settings.toml changes (existing secrets preserved)
 make bootstrap
 ```
 
-### Configuration File (.env)
+**Never commit `.env` or `.env.make`** — both are gitignored and auto-generated.
 
-The `.env` file is generated from `.env.example` with secure defaults:
+### Key settings (.env)
 
 ```bash
-# --- CORE SETTINGS ---
-HOST=0.0.0.0
-PORT=3080
+# --- CORE ---
 MAX_HISTORY_MESSAGES=10
 MAX_TOOL_ITERATIONS=10
 
-# --- LLM CONFIGURATION ---
-# Providers: 'local' (Ollama), 'deepseek', 'openai', 'anthropic', 'google'
-DEFAULT_LLM_PROVIDER=local
-
-# Local LLM (Ollama - included in Docker stack)
+# --- LLM ---
+DEFAULT_LLM_PROVIDER=local     # local (Ollama) | deepseek
 OLLAMA_BASE_URL=http://ollama:11434
 OLLAMA_MODEL=llama3.3:latest
 LLM_TEMPERATURE=0.2
 
-# --- API KEYS (fill only what you need) ---
-TMDB_API_KEY=your-tmdb-key-here        # Required for movie search
+# --- API KEYS ---
+TMDB_API_KEY=your-tmdb-key     # Required for movie/show search
 DEEPSEEK_API_KEY=              # Optional
-OPENAI_API_KEY=                         # Optional
-ANTHROPIC_API_KEY=                      # Optional
 
-# --- SECURITY (auto-generated, don't modify) ---
-JWT_SECRET=<auto-generated>
-JWT_REFRESH_SECRET=<auto-generated>
-CREDS_KEY=<auto-generated>
-CREDS_IV=<auto-generated>
-
-# --- DATABASES (auto-generated passwords) ---
-MONGO_PASSWORD=<auto-generated>
-POSTGRES_PASSWORD=<auto-generated>
+# --- SECURITY (auto-generated) ---
+JWT_SECRET=<auto>
+CREDS_KEY=<auto>
+MONGO_PASSWORD=<auto>
 ```
 
-### Security Keys
-
-Security keys are defined in `pyproject.toml` and generated automatically:
-
-```toml
-[tool.alfred.security]
-jwt_secret = "32:b64"           # 32 bytes, base64 URL-safe
-jwt_refresh_secret = "32:b64"
-creds_key = "32:hex"            # 32 bytes, hexadecimal (AES-256)
-creds_iv = "16:hex"             # 16 bytes, hexadecimal (AES IV)
-mongo_password = "16:hex"
-postgres_password = "16:hex"
-```
-
-**Formats:**
-- `b64` — Base64 URL-safe (for JWT tokens)
-- `hex` — Hexadecimal (for encryption keys, passwords)
-
 ## 🐳 Docker Services
 
-### Service Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     alfred-net (bridge)                      │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
-│  │  LibreChat   │───▶│    Alfred    │───▶│   MongoDB    │  │
-│  │   :3080      │    │   (core)     │    │   :27017     │  │
-│  └──────────────┘    └──────────────┘    └──────────────┘  │
-│         │                   │                               │
-│         │                   ▼                               │
-│         │            ┌──────────────┐                       │
-│         │            │    Ollama    │                       │
-│         │            │   (local)    │                       │
-│         │            └──────────────┘                       │
-│         │                                                   │
-│  ┌──────┴───────────────────────────────────────────────┐  │
-│  │              Optional Services (profiles)             │  │
-│  ├──────────────┬──────────────┬──────────────┬─────────┤  │
-│  │ Meilisearch  │  RAG API     │  VectorDB    │qBittor- │  │
-│  │   :7700      │   :8000      │   :5432      │  rent   │  │
-│  │  [meili]     │   [rag]      │   [rag]      │[qbit..] │  │
-│  └──────────────┴──────────────┴──────────────┴─────────┘  │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
-```
-
 ### Docker Profiles
 
-| Profile | Services | Use Case |
-|---------|----------|----------|
-| (default) | LibreChat, Alfred, MongoDB, Ollama | Basic setup |
-| `meili` | + Meilisearch | Fast search |
-| `rag` | + RAG API, VectorDB | Document retrieval |
-| `qbittorrent` | + qBittorrent | Torrent downloads |
-| `full` | All services | Complete setup |
+| Profile | Extra services | Use case |
+|---------|---------------|----------|
+| (default) | — | LibreChat + Alfred + MongoDB + Ollama |
+| `meili` | Meilisearch | Fast full-text search |
+| `rag` | RAG API + VectorDB (PostgreSQL) | Document retrieval |
+| `qbittorrent` | qBittorrent | Torrent downloads |
+| `full` | All of the above | Complete setup |
 
 ```bash
-# Start with specific profiles
-make up p=rag,meili
-make up p=full
-```
-
-### Docker Commands
-
-```bash
-make up              # Start containers (default profile)
+make up              # Start (default profile)
 make up p=full       # Start with all services
-make down            # Stop all containers
-make restart         # Restart containers
+make down            # Stop
+make restart         # Restart
 make logs            # Follow logs
-make ps              # Show container status
-make shell           # Open bash in Alfred container
-make build           # Build production image
-make build-test      # Build test image
+make ps              # Container status
 ```
 
 ## 🛠️ Available Tools
 
-The agent has access to these tools for interacting with your media library:
-
 | Tool | Description |
 |------|-------------|
 | `find_media_imdb_id` | Search for movies/TV shows on TMDB by title |
 | `find_torrent` | Search for torrents across multiple indexers |
-| `get_torrent_by_index` | Get detailed info about a specific torrent result |
-| `add_torrent_by_index` | Download a torrent by its index in search results |
+| `get_torrent_by_index` | Get detailed info about a specific result |
+| `add_torrent_by_index` | Download a torrent from search results |
 | `add_torrent_to_qbittorrent` | Add a torrent via magnet link directly |
-| `set_path_for_folder` | Configure folder paths for media organization |
-| `list_folder` | List contents of a folder |
-| `set_language` | Set preferred language for searches |
+| `resolve_destination` | Compute the target library path for a release |
+| `move_media` | Hard-link a file to its library destination |
+| `manage_subtitles` | Scan, classify, and place subtitle tracks |
+| `create_seed_links` | Prepare torrent folder so qBittorrent keeps seeding |
+| `learn` | Teach Alfred a new pattern (release group, naming convention) |
+| `set_path_for_folder` | Configure folder paths |
+| `list_folder` | List contents of a configured folder |
+| `set_language` | Set preferred language for the session |
 
 ## 💬 Usage Examples
 
@@ -266,11 +223,12 @@ Alfred: I found 3 torrents for Inception (2010):
 
 You: Download the first one
 Alfred: ✓ Added to qBittorrent! Download started.
-        Saving to: /downloads/Movies/Inception (2010)/
 
-You: What's downloading right now?
-Alfred: You have 1 active download:
-        - Inception.2010.1080p.BluRay.x264 (45% complete, ETA: 12 min)
+You: Organize the Breaking Bad S01 download
+Alfred: ✓ Resolved destination: /tv_shows/Breaking.Bad/Season 01/
+        ✓ Moved 6 episode files
+        ✓ Placed 6 subtitle tracks (fr, en)
+        ✓ Seed links created in /torrents/
 ```
 
 ### Via API
@@ -279,219 +237,147 @@ Alfred: You have 1 active download:
 # Health check
 curl http://localhost:8000/health
 
-# Chat with the agent (OpenAI-compatible)
+# Chat (OpenAI-compatible)
 curl -X POST http://localhost:8000/v1/chat/completions \
   -H "Content-Type: application/json" \
   -d '{
     "model": "alfred",
-    "messages": [
-      {"role": "user", "content": "Find The Matrix 4K"}
-    ]
+    "messages": [{"role": "user", "content": "Find The Matrix 4K"}]
   }'
 
-# List available models
+# List models
 curl http://localhost:8000/v1/models
 
-# View memory state (debug)
+# View memory state
 curl http://localhost:8000/memory/state
-
-# Clear session memory
-curl -X POST http://localhost:8000/memory/clear-session
 ```
 
-### Via OpenWebUI or Other Clients
-
-Alfred is compatible with any OpenAI-compatible client:
-
-1. Add as OpenAI-compatible endpoint: `http://localhost:8000/v1`
-2. Model name: `alfred`
-3. No API key required (or use any placeholder)
+Alfred is compatible with any OpenAI-compatible client. Point it at `http://localhost:8000/v1`, model `alfred`.
 
 ## 🧠 Memory System
 
-Alfred uses a three-tier memory system for context management:
+Alfred uses a three-tier memory system:
 
-### Long-Term Memory (LTM)
-- **Persistent** — Saved to JSON files
-- **Contents:** Configuration, user preferences, media library state
-- **Survives:** Application restarts
-
-### Short-Term Memory (STM)
-- **Session-based** — Stored in RAM
-- **Contents:** Conversation history, current workflow state
-- **Cleared:** On session end or restart
-
-### Episodic Memory
-- **Transient** — Stored in RAM
-- **Contents:** Search results, active downloads, recent errors
-- **Cleared:** Frequently, after task completion
+| Tier | Storage | Contents | Lifetime |
+|------|---------|----------|----------|
+| **LTM** | JSON file (`data/memory/ltm.json`) | Config, library, watchlist, learned patterns | Permanent |
+| **STM** | RAM | Conversation history (capped) | Session |
+| **Episodic** | RAM | Search results, active downloads, errors | Short-lived |
 
 ## 🧪 Development
 
-### Project Setup
-
-```bash
-# Install all dependencies (including dev)
-poetry install
-
-# Install pre-commit hooks
-make install-hooks
-
-# Run the development server
-poetry run uvicorn alfred.app:app --reload
-```
-
 ### Running Tests
 
 ```bash
-# Run all tests (parallel execution)
+# Run full suite (parallel)
 make test
 
 # Run with coverage report
 make coverage
 
-# Run specific test file
-poetry run pytest tests/test_agent.py -v
+# Run a single file
+uv run pytest tests/test_agent.py -v
 
-# Run specific test
-poetry run pytest tests/test_config_loader.py::TestBootstrapEnv -v
+# Run a single class
+uv run pytest tests/test_agent.py::TestAgentInit -v
+
+# Skip slow tests
+uv run pytest -m "not slow"
 ```
 
+### Test coverage
+
+The suite covers:
+- **Agent loop** — tool execution, history, max iterations, error handling
+- **Tool registry** — OpenAI schema format, parameter extraction
+- **Prompts** — system prompt building, tool inclusion
+- **Memory** — LTM/STM/Episodic operations, persistence
+- **Filesystem tools** — path traversal security, folder listing
+- **File manager** — hard-link, move, seed links (real filesystem, no mocks)
+- **Application use cases** — `resolve_destination`, `create_seed_links`, `list_folder`, `move_media`
+- **Domain** — TV show/movie entities, shared value objects (`ImdbId`, `FilePath`, `FileSize`), subtitle scanner
+- **Repositories** — JSON-backed movie, TV show, subtitle repos
+- **Bootstrap** — secret generation, idempotency, URI construction
+- **Workflows** — YAML loading, structure validation
+- **Configuration** — boundary validation for all settings
+
 ### Code Quality
 
 ```bash
-# Lint and auto-fix
-make lint
-
-# Format code
-make format
-
-# Clean build artifacts
-make clean
+make lint        # Ruff check --fix
+make format      # Ruff format + check --fix
 ```
 
 ### Adding a New Tool
 
-1. **Create the tool function** in `alfred/agent/tools/`:
+1. Implement the function in `alfred/agent/tools/`:
 
 ```python
 # alfred/agent/tools/api.py
 def my_new_tool(param: str) -> dict[str, Any]:
-    """
-    Short description of what this tool does.
-    
-    This will be shown to the LLM to help it decide when to use this tool.
-    """
+    """Short description shown to the LLM to decide when to call this tool."""
     memory = get_memory()
-    
-    # Your implementation here
-    result = do_something(param)
-    
-    return {
-        "status": "success",
-        "data": result
-    }
+    # ...
+    return {"status": "ok", "data": result}
 ```
 
-2. **Register in the registry** (`alfred/agent/registry.py`):
+2. Register it in `alfred/agent/registry.py`:
 
 ```python
 tool_functions = [
     # ... existing tools ...
-    api_tools.my_new_tool,  # Add your tool here
+    api_tools.my_new_tool,
 ]
 ```
 
-The tool will be automatically registered with its parameters extracted from the function signature.
+The registry auto-generates the JSON schema from the function signature and docstring.
+
+### Adding a Workflow
+
+Create a YAML file in `alfred/agent/workflows/`:
+
+```yaml
+name: my_workflow
+description: What this workflow does
+steps:
+  - tool: resolve_destination
+    description: Find where the file should go
+  - tool: move_media
+    description: Move the file
+```
+
+Workflows are loaded automatically at startup.
 
 ### Version Management
 
 ```bash
-# Bump version (must be on main branch)
-make patch    # 0.1.7 -> 0.1.8
-make minor    # 0.1.7 -> 0.2.0
-make major    # 0.1.7 -> 1.0.0
+# Must be on main branch
+make patch    # 0.1.7 → 0.1.8
+make minor    # 0.1.7 → 0.2.0
+make major    # 0.1.7 → 1.0.0
 ```
 
 ## 📚 API Reference
 
 ### Endpoints
 
-#### `GET /health`
-Health check endpoint.
-
-```json
-{
-  "status": "healthy",
-  "version": "0.1.7"
-}
-```
-
-#### `GET /v1/models`
-List available models (OpenAI-compatible).
-
-```json
-{
-  "object": "list",
-  "data": [
-    {
-      "id": "alfred",
-      "object": "model",
-      "owned_by": "alfred"
-    }
-  ]
-}
-```
-
-#### `POST /v1/chat/completions`
-Chat with the agent (OpenAI-compatible).
-
-**Request:**
-```json
-{
-  "model": "alfred",
-  "messages": [
-    {"role": "user", "content": "Find Inception"}
-  ],
-  "stream": false
-}
-```
-
-**Response:**
-```json
-{
-  "id": "chatcmpl-xxx",
-  "object": "chat.completion",
-  "created": 1234567890,
-  "model": "alfred",
-  "choices": [{
-    "index": 0,
-    "message": {
-      "role": "assistant",
-      "content": "I found Inception (2010)..."
-    },
-    "finish_reason": "stop"
-  }]
-}
-```
-
-#### `GET /memory/state`
-View full memory state (debug endpoint).
-
-#### `POST /memory/clear-session`
-Clear session memories (STM + Episodic).
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health` | Health check |
+| `GET` | `/v1/models` | List models (OpenAI-compatible) |
+| `POST` | `/v1/chat/completions` | Chat (OpenAI-compatible, streaming supported) |
+| `GET` | `/memory/state` | Full memory dump (debug) |
+| `POST` | `/memory/clear-session` | Clear STM + Episodic |
+| `GET` | `/memory/episodic/search-results` | Current search results |
 
 ## 🔧 Troubleshooting
 
 ### Agent doesn't respond
 
 1. Check API keys in `.env`
-2. Verify LLM provider is running:
+2. Verify the LLM is running:
    ```bash
-   # For Ollama
    docker logs alfred-ollama
-   
-   # Check if model is pulled
    docker exec alfred-ollama ollama list
    ```
 3. Check Alfred logs: `docker logs alfred-core`
@@ -499,76 +385,34 @@ Clear session memories (STM + Episodic).
 ### qBittorrent connection failed
 
 1. Verify qBittorrent is running: `docker ps | grep qbittorrent`
-2. Check Web UI is enabled in qBittorrent settings
-3. Verify credentials in `.env`:
-   ```bash
-   QBITTORRENT_URL=http://qbittorrent:16140
-   QBITTORRENT_USERNAME=admin
-   QBITTORRENT_PASSWORD=<check-your-env>
-   ```
-
-### Database connection issues
-
-1. Check MongoDB is healthy: `docker logs alfred-mongodb`
-2. Verify credentials match in `.env`
-3. Try restarting: `make restart`
+2. Check credentials in `.env` (`QBITTORRENT_URL`, `QBITTORRENT_USERNAME`, `QBITTORRENT_PASSWORD`)
 
 ### Memory not persisting
 
-1. Check `data/` directory exists and is writable
+1. Check `data/` directory is writable
 2. Verify volume mounts in `docker-compose.yaml`
-3. Check file permissions: `ls -la data/`
 
 ### Bootstrap fails
 
-1. Ensure `.env.example` exists
-2. Check `pyproject.toml` has required sections:
-   ```toml
-   [tool.alfred.settings]
-   [tool.alfred.security]
-   ```
-3. Run manually: `python scripts/bootstrap.py`
+```bash
+make validate    # Check what's wrong with .env
+make bootstrap   # Regenerate (preserves existing secrets)
+```
 
 ### Tests failing
 
-1. Update dependencies: `poetry install`
-2. Check Python version: `python --version` (needs 3.14+)
-3. Run specific failing test with verbose output:
-   ```bash
-   poetry run pytest tests/test_failing.py -v --tb=long
-   ```
+```bash
+uv run pytest tests/test_failing.py -v --tb=long
+```
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please follow these steps:
-
-1. **Fork** the repository
-2. **Create** a feature branch: `git checkout -b feature/my-feature`
-3. **Make** your changes
-4. **Run** tests: `make test`
-5. **Run** linting: `make lint && make format`
-6. **Commit**: `git commit -m "feat: add my feature"`
-7. **Push**: `git push origin feature/my-feature`
-8. **Create** a Pull Request
-
-### Commit Convention
-
-We use [Conventional Commits](https://www.conventionalcommits.org/):
-
-- `feat:` New feature
-- `fix:` Bug fix
-- `docs:` Documentation
-- `refactor:` Code refactoring
-- `test:` Adding tests
-- `chore:` Maintenance
-
-## 📖 Documentation
-
-- [Architecture Diagram](docs/architecture_diagram.md) — System architecture overview
-- [Class Diagram](docs/class_diagram.md) — Class structure and relationships
-- [Component Diagram](docs/component_diagram.md) — Component interactions
-- [Sequence Diagram](docs/sequence_diagram.md) — Sequence flows
-- [Flowchart](docs/flowchart.md) — System flowcharts
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Make your changes + add tests
+4. Run `make test && make lint && make format`
+5. Commit with [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `infra:`
+6. Open a Pull Request
 
 ## 📄 License
 
@@ -576,19 +420,13 @@ MIT License — see [LICENSE](LICENSE) file for details.
 
 ## 🙏 Acknowledgments
 
-- [LibreChat](https://github.com/danny-avila/LibreChat) — Beautiful chat interface
+- [LibreChat](https://github.com/danny-avila/LibreChat) — Chat interface
 - [Ollama](https://ollama.ai/) — Local LLM runtime
 - [DeepSeek](https://www.deepseek.com/) — LLM provider
-- [TMDB](https://www.themoviedb.org/) — Movie database
+- [TMDB](https://www.themoviedb.org/) — Movie & TV database
 - [qBittorrent](https://www.qbittorrent.org/) — Torrent client
 - [FastAPI](https://fastapi.tiangolo.com/) — Web framework
-- [Pydantic](https://docs.pydantic.dev/) — Data validation
-
-## 📬 Support
-
-- 📧 Email: francois.hodiaumont@gmail.com
-- 🐛 Issues: [GitHub Issues](https://github.com/francwa/alfred_media_organizer/issues)
-- 💬 Discussions: [GitHub Discussions](https://github.com/francwa/alfred_media_organizer/discussions)
+- [uv](https://github.com/astral-sh/uv) — Fast Python package manager
 
 ---
 

alfred/agent/agent.py

@@ -3,13 +3,16 @@
 import json
 import logging
 from collections.abc import AsyncGenerator
+from pathlib import Path
 from typing import Any
 
+from alfred.infrastructure.metadata import MetadataStore
 from alfred.infrastructure.persistence import get_memory
 from alfred.settings import settings
 
-from .prompts import PromptBuilder
+from .prompt import PromptBuilder
 from .registry import Tool, make_tools
+from .workflows import WorkflowLoader
 
 logger = logging.getLogger(__name__)
 
@@ -33,8 +36,8 @@ class Agent:
         self.settings = settings
         self.llm = llm
         self.tools: dict[str, Tool] = make_tools(settings)
-        self.prompt_builder = PromptBuilder(self.tools)
-        self.settings = settings
+        self.workflow_loader = WorkflowLoader()
+        self.prompt_builder = PromptBuilder(self.tools, self.workflow_loader)
         self.max_tool_iterations = max_tool_iterations
 
     def step(self, user_input: str) -> str:
@@ -139,7 +142,7 @@ class Agent:
         memory.save()
         return final_response
 
-    def _execute_tool_call(self, tool_call: dict[str, Any]) -> dict[str, Any]:
+    def _execute_tool_call(self, tool_call: dict[str, Any]) -> dict[str, Any]:  # noqa: PLR0911
         """
         Execute a single tool call.
 
@@ -168,29 +171,163 @@ class Agent:
                 "available_tools": available,
             }
 
+        # Defensive: reject calls to tools that are not currently in scope.
+        visible = set(self.prompt_builder.visible_tool_names())
+        if tool_name not in visible:
+            return {
+                "error": "tool_out_of_scope",
+                "message": (
+                    f"Tool '{tool_name}' is not available in the current "
+                    "workflow scope. Call end_workflow first or start the "
+                    "appropriate workflow."
+                ),
+                "available_tools": sorted(visible),
+            }
+
         tool = self.tools[tool_name]
+        memory = get_memory()
+
+        # Cache lookup — for tools flagged cacheable, short-circuit on hit.
+        cache_key_value = self._cache_key_for(tool, args)
+        if cache_key_value is not None:
+            cached = memory.stm.tool_results.get(tool_name, cache_key_value)
+            if cached is not None:
+                logger.info(f"Tool cache HIT: {tool_name}[{cache_key_value}]")
+                self._post_tool_side_effects(tool_name, args, cached, from_cache=True)
+                return {**cached, "_from_cache": True}
 
         # Execute tool
         try:
             result = tool.func(**args)
-            return result
         except KeyboardInterrupt:
             # Don't catch KeyboardInterrupt - let it propagate
             raise
         except TypeError as e:
             # Bad arguments
-            memory = get_memory()
             memory.episodic.add_error(tool_name, f"bad_args: {e}")
             return {"error": "bad_args", "message": str(e), "tool": tool_name}
         except Exception as e:
             # Other errors
-            memory = get_memory()
             memory.episodic.add_error(tool_name, str(e))
             return {"error": "execution_failed", "message": str(e), "tool": tool_name}
 
+        # Persist + side effects only on successful results.
+        if isinstance(result, dict) and result.get("status") == "ok":
+            if cache_key_value is not None:
+                memory.stm.tool_results.put(tool_name, cache_key_value, result)
+            self._post_tool_side_effects(tool_name, args, result, from_cache=False)
+            memory.save()
+
+        return result
+
+    @staticmethod
+    def _cache_key_for(tool: Tool, args: dict[str, Any]) -> str | None:
+        """Return the cache key value for this call, or None if not cacheable."""
+        if tool.cache_key is None:
+            return None
+        value = args.get(tool.cache_key)
+        if value is None:
+            return None
+        return str(value)
+
+    def _post_tool_side_effects(
+        self,
+        tool_name: str,
+        args: dict[str, Any],
+        result: dict[str, Any],
+        *,
+        from_cache: bool,
+    ) -> None:
+        """
+        Tool-agnostic side effects applied after a successful run or cache hit.
+
+        Today:
+          - Update release_focus when a path-keyed inspector runs.
+          - Persist inspector results into the release's `.alfred/metadata.yaml`.
+          - Refresh episodic.last_search_results on find_torrent cache hits so
+            get_torrent_by_index keeps pointing at the right list.
+        """
+        memory = get_memory()
+        tool = self.tools.get(tool_name)
+
+        # Release focus: any path-keyed inspector updates current_release_path.
+        if tool is not None and tool.cache_key in {"source_path"}:
+            path = args.get(tool.cache_key)
+            if isinstance(path, str) and path:
+                memory.stm.release_focus.focus(path)
+
+        # Persist inspector results to .alfred/metadata.yaml (skip on cache
+        # hit — the file is already up to date from the original run).
+        if not from_cache:
+            self._maybe_update_alfred(tool_name, args, result)
+
+        # Episodic refresh when find_torrent's cache short-circuits the call.
+        if from_cache and tool_name == "find_torrent":
+            torrents = result.get("torrents") or []
+            query = args.get("media_title") or ""
+            memory.episodic.store_search_results(
+                query=query, results=torrents, search_type="torrent"
+            )
+
+    def _maybe_update_alfred(
+        self,
+        tool_name: str,
+        args: dict[str, Any],
+        result: dict[str, Any],
+    ) -> None:
+        """
+        Persist a successful inspector result into the release's
+        `.alfred/metadata.yaml`. No-op when the release root can't be resolved.
+        """
+        if tool_name not in {"analyze_release", "probe_media", "find_media_imdb_id"}:
+            return
+
+        release_root = self._resolve_release_root(tool_name, args)
+        if release_root is None:
+            return
+
+        try:
+            store = MetadataStore(release_root)
+            if tool_name == "analyze_release":
+                store.update_parse(result)
+            elif tool_name == "probe_media":
+                store.update_probe(result)
+            elif tool_name == "find_media_imdb_id":
+                store.update_tmdb(result)
+        except Exception as e:
+            logger.warning(
+                f"Failed to update .alfred for {tool_name} at {release_root}: {e}"
+            )
+
+    @staticmethod
+    def _resolve_release_root(
+        tool_name: str,
+        args: dict[str, Any],
+    ) -> Path | None:
+        """
+        Figure out which release folder owns this call.
+
+        - analyze_release / probe_media: derived from source_path
+          (folder kept as-is, file walked up to its parent).
+        - find_media_imdb_id: follow the current release focus in STM.
+        """
+        if tool_name in {"analyze_release", "probe_media"}:
+            raw = args.get("source_path")
+            if not isinstance(raw, str) or not raw:
+                return None
+            path = Path(raw)
+            return path if path.is_dir() else path.parent
+
+        # find_media_imdb_id has no path arg — rely on release focus.
+        focus = get_memory().stm.release_focus.current_release_path
+        if not focus:
+            return None
+        path = Path(focus)
+        return path if path.is_dir() else path.parent
+
     async def step_streaming(
         self, user_input: str, completion_id: str, created_ts: int, model: str
-    ) -> AsyncGenerator[dict[str, Any], None]:
+    ) -> AsyncGenerator[dict[str, Any]]:
         """
         Execute agent step with streaming support for LibreChat.
 

alfred/agent/expressions.py

@@ -0,0 +1,79 @@
+"""Expression loader — charge et merge les fichiers YAML d'expressions par user."""
+
+import random
+from pathlib import Path
+
+import yaml
+
+_USERS_DIR = Path(__file__).parent.parent / "knowledge" / "users"
+
+
+def _load_yaml(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+
+
+def load_expressions(username: str | None) -> dict:
+    """
+    Charge common.yaml et le merge avec {username}.yaml.
+
+    Retourne un dict avec :
+      - nickname: str (surnom de l'user, ou username en fallback)
+      - expressions: dict[situation -> list[str]]
+    """
+    common = _load_yaml(_USERS_DIR / "common.yaml")
+    user_data = _load_yaml(_USERS_DIR / f"{username}.yaml") if username else {}
+
+    # Merge expressions : common + user (les phrases user s'ajoutent)
+    common_exprs: dict[str, list] = common.get("expressions", {})
+    user_exprs: dict[str, list] = user_data.get("expressions", {})
+
+    merged: dict[str, list] = {}
+    all_situations = set(common_exprs) | set(user_exprs)
+    for situation in all_situations:
+        base = list(common_exprs.get(situation, []))
+        extra = list(user_exprs.get(situation, []))
+        merged[situation] = base + extra
+
+    nickname = user_data.get("user", {}).get("nickname") or username or "mec"
+
+    return {
+        "nickname": nickname,
+        "expressions": merged,
+    }
+
+
+def pick(expressions: dict, situation: str, nickname: str | None = None) -> str:
+    """
+    Pioche une expression aléatoire pour une situation donnée.
+
+    Résout {user} avec le nickname si fourni.
+    Retourne une string vide si la situation n'existe pas.
+    """
+    options = expressions.get("expressions", {}).get(situation, [])
+    if not options:
+        return ""
+    chosen = random.choice(options)
+    if nickname:
+        chosen = chosen.replace("{user}", nickname)
+    return chosen
+
+
+def build_expressions_context(username: str | None) -> dict:
+    """
+    Point d'entrée principal.
+
+    Retourne :
+      - nickname: str
+      - samples: dict[situation -> une phrase résolue]  — une seule par situation
+    """
+    data = load_expressions(username)
+    nickname = data["nickname"]
+    samples = {
+        situation: pick(data, situation, nickname) for situation in data["expressions"]
+    }
+    return {
+        "nickname": nickname,
+        "samples": samples,
+    }

alfred/agent/llm/deepseek.py

@@ -6,7 +6,8 @@ from typing import Any
 import requests
 from requests.exceptions import HTTPError, RequestException, Timeout
 
-from alfred.settings import Settings, settings
+from alfred.settings import Settings
+from alfred.settings import settings as default_settings
 
 from .exceptions import LLMAPIError, LLMConfigurationError
 
@@ -36,6 +37,7 @@ class DeepSeekClient:
         Raises:
             LLMConfigurationError: If API key is missing
         """
+        self.settings = settings or default_settings
         self.api_key = api_key or self.settings.deepseek_api_key
         self.base_url = base_url or self.settings.deepseek_base_url
         self.model = model or self.settings.deepseek_model
@@ -96,7 +98,7 @@ class DeepSeekClient:
         payload = {
             "model": self.model,
             "messages": messages,
-            "temperature": settings.llm_temperature,
+            "temperature": self.settings.llm_temperature,
         }
 
         # Add tools if provided

alfred/agent/llm/ollama.py

@@ -7,6 +7,7 @@ import requests
 from requests.exceptions import HTTPError, RequestException, Timeout
 
 from alfred.settings import Settings
+from alfred.settings import settings as default_settings
 
 from .exceptions import LLMAPIError, LLMConfigurationError
 
@@ -46,11 +47,12 @@ class OllamaClient:
         Raises:
             LLMConfigurationError: If configuration is invalid
         """
-        self.base_url = base_url or settings.ollama_base_url
-        self.model = model or settings.ollama_model
-        self.timeout = timeout or settings.request_timeout
+        self.settings = settings or default_settings
+        self.base_url = base_url or self.settings.ollama_base_url
+        self.model = model or self.settings.ollama_model
+        self.timeout = timeout or self.settings.request_timeout
         self.temperature = (
-            temperature if temperature is not None else settings.llm_temperature
+            temperature if temperature is not None else self.settings.llm_temperature
         )
 
         if not self.base_url:

alfred/agent/parameters.py

@@ -1,101 +0,0 @@
-# agent/parameters.py
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import Any
-
-
-@dataclass
-class ParameterSchema:
-    """Describes a required parameter for the agent."""
-
-    key: str
-    description: str
-    why_needed: str  # Explanation for the AI
-    type: str  # "string", "number", "object", etc.
-    validator: Callable[[Any], bool] | None = None
-    default: Any = None
-    required: bool = True
-
-
-# Define all required parameters
-REQUIRED_PARAMETERS = [
-    ParameterSchema(
-        key="config",
-        description="Configuration object containing all folder paths",
-        why_needed=(
-            "This contains the paths to all important folders:\n"
-            "- download_folder: Where downloaded files arrive before being organized\n"
-            "- tvshow_folder: Where TV show files are organized and stored\n"
-            "- movie_folder: Where movie files are organized and stored\n"
-            "- torrent_folder: Where torrent structures are saved for the torrent client"
-        ),
-        type="object",
-        validator=lambda x: isinstance(x, dict),
-        required=True,
-        default={},
-    ),
-    ParameterSchema(
-        key="tv_shows",
-        description="List of TV shows the user is following",
-        why_needed=(
-            "This tracks which TV shows you're following. "
-            "Each show includes: IMDB ID, title, number of seasons, and status (ongoing or ended)."
-        ),
-        type="array",
-        validator=lambda x: isinstance(x, list),
-        required=False,
-        default=[],
-    ),
-]
-
-
-def get_parameter_schema(key: str) -> ParameterSchema | None:
-    """Get schema for a specific parameter."""
-    for param in REQUIRED_PARAMETERS:
-        if param.key == key:
-            return param
-    return None
-
-
-def get_missing_required_parameters(memory_data: dict) -> list[ParameterSchema]:
-    """Get list of required parameters that are missing or None."""
-    missing = []
-    for param in REQUIRED_PARAMETERS:
-        if param.required:
-            value = memory_data.get(param.key)
-            if value is None:
-                missing.append(param)
-    return missing
-
-
-def format_parameters_for_prompt() -> str:
-    """Format parameter descriptions for the AI system prompt."""
-    lines = ["REQUIRED PARAMETERS:"]
-    for param in REQUIRED_PARAMETERS:
-        status = "REQUIRED" if param.required else "OPTIONAL"
-        lines.append(f"\n- {param.key} ({status}):")
-        lines.append(f"  Description: {param.description}")
-        lines.append(f"  Why needed: {param.why_needed}")
-        lines.append(f"  Type: {param.type}")
-    return "\n".join(lines)
-
-
-def validate_parameter(key: str, value: Any) -> tuple[bool, str | None]:
-    """
-    Validate a parameter value against its schema.
-
-    Returns:
-        (is_valid, error_message)
-    """
-    schema = get_parameter_schema(key)
-    if not schema:
-        return True, None  # Unknown parameters are allowed
-
-    if schema.validator:
-        try:
-            if not schema.validator(value):
-                return False, f"Validation failed for {key}"
-        except Exception as e:
-            return False, f"Validation error for {key}: {str(e)}"
-
-    return True, None

alfred/agent/prompt.py

@@ -0,0 +1,333 @@
+"""Prompt builder for the agent system."""
+
+import json
+from typing import Any
+
+from alfred.infrastructure.persistence import get_memory
+from alfred.infrastructure.persistence.memory import MemoryRegistry
+
+from .expressions import build_expressions_context
+from .registry import Tool
+from .workflows import WorkflowLoader
+
+# Tools that are always available, regardless of workflow scope.
+# Kept small on purpose — the noyau is what the agent uses to either
+# answer trivially or pivot into a workflow.
+CORE_TOOLS: tuple[str, ...] = (
+    "set_language",
+    "set_path_for_folder",
+    "list_folder",
+    "read_release_metadata",
+    "query_library",
+    "start_workflow",
+    "end_workflow",
+)
+
+
+class PromptBuilder:
+    """Builds system prompts for the agent with memory context."""
+
+    def __init__(
+        self,
+        tools: dict[str, Tool],
+        workflow_loader: WorkflowLoader | None = None,
+    ):
+        self.tools = tools
+        self.workflow_loader = workflow_loader or WorkflowLoader()
+        self._memory_registry = MemoryRegistry()
+
+    def _active_workflow(self, memory) -> dict | None:
+        """Return the YAML definition of the active workflow, or None."""
+        current = memory.stm.workflow.current
+        if current is None:
+            return None
+        return self.workflow_loader.get(current.get("name"))
+
+    def visible_tool_names(self) -> list[str]:
+        """
+        Return the names of the tools currently in scope.
+
+        - Idle (no workflow): core noyau only. The LLM enters a workflow
+          via start_workflow to access more tools.
+        - Workflow active: core noyau + the workflow's declared tools.
+        """
+        memory = get_memory()
+        visible = set(CORE_TOOLS)
+        workflow = self._active_workflow(memory)
+        if workflow is not None:
+            for name in workflow.get("tools", []):
+                visible.add(name)
+        # Only return tools that actually exist in the registry.
+        return [name for name in self.tools if name in visible]
+
+    def _format_identity(self, memory) -> str:
+        """Build Alfred's identity and personality section."""
+        username = memory.stm.get_entity("username")
+        expr = build_expressions_context(username)
+        nickname = expr["nickname"]
+        samples = expr["samples"]
+
+        # Format expressions as situational guidance for the LLM
+        expr_lines = []
+        situation_labels = {
+            "greeting": "Salutation",
+            "success": "Succès",
+            "working": "En cours",
+            "error": "Erreur",
+            "unclear": "Demande floue",
+            "warning": "Avertissement",
+            "not_found": "Introuvable",
+        }
+        for situation, label in situation_labels.items():
+            phrase = samples.get(situation, "")
+            if phrase:
+                expr_lines.append(f'  {label}: "{phrase}"')
+
+        expressions_block = "\n".join(expr_lines)
+
+        return f"""Tu t'appelles Alfred. Tu es un assistant d'organisation de médiathèque — direct, opérationnel, légèrement impertinent.
+
+PERSONNALITÉ:
+- Tu parles franglais : français avec des touches d'anglais quand ça colle mieux
+- Tu es sarcastique et n'as pas peur de te moquer si l'user fait une connerie
+- Tu envoies chier poliment (mais clairement) quand la demande est trop floue
+- Tu ne fais pas de blabla inutile. Si "ok c'est fait" suffit, c'est tout ce que tu dis
+- Tu peux jurer (putain, merde, con, ...) — c'est naturel, pas du remplissage
+- Jamais de "Great question!" ou de politesse creuse
+
+USER COURANT: {nickname}
+
+EXPRESSIONS À UTILISER (une par situation, naturellement intégrées dans ta réponse) :
+{expressions_block}"""
+
+    def build_tools_spec(self) -> list[dict[str, Any]]:
+        """Build the tool specification for the LLM API (scope-filtered)."""
+        visible = set(self.visible_tool_names())
+        tool_specs = []
+        for tool in self.tools.values():
+            if tool.name not in visible:
+                continue
+            spec = {
+                "type": "function",
+                "function": {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "parameters": tool.parameters,
+                },
+            }
+            tool_specs.append(spec)
+        return tool_specs
+
+    def _format_tools_description(self) -> str:
+        """Format the currently-visible tools with description + params."""
+        visible = set(self.visible_tool_names())
+        visible_tools = [t for t in self.tools.values() if t.name in visible]
+        if not visible_tools:
+            return ""
+        return "\n".join(
+            f"- {tool.name}: {tool.description}\n"
+            f"  Parameters: {json.dumps(tool.parameters, ensure_ascii=False)}"
+            for tool in visible_tools
+        )
+
+    def _format_workflow_scope(self, memory) -> str:
+        """Describe the current workflow scope so the LLM has a plan."""
+        workflow = self._active_workflow(memory)
+        if workflow is None:
+            available = self.workflow_loader.names()
+            if not available:
+                return ""
+            lines = ["WORKFLOW SCOPE: idle (broad catalog narrowed to core noyau)."]
+            lines.append(
+                "  Call start_workflow(workflow_name, params) to enter a scope."
+            )
+            lines.append("  Available workflows:")
+            for name in available:
+                wf = self.workflow_loader.get(name) or {}
+                desc = (wf.get("description") or "").strip().splitlines()
+                summary = desc[0] if desc else ""
+                lines.append(f"    - {name}: {summary}")
+            return "\n".join(lines)
+
+        current = memory.stm.workflow.current or {}
+        lines = [
+            f"WORKFLOW SCOPE: active — {current.get('name')} "
+            f"(stage: {current.get('stage')})",
+        ]
+        params = current.get("params")
+        if params:
+            lines.append(f"  Params: {params}")
+        wf_desc = (workflow.get("description") or "").strip()
+        if wf_desc:
+            lines.append(f"  Goal: {wf_desc}")
+        steps = workflow.get("steps", [])
+        if steps:
+            lines.append("  Steps:")
+            for step in steps:
+                step_id = step.get("id", "?")
+                step_tool = step.get("tool") or (
+                    "ask_user" if step.get("ask_user") else "—"
+                )
+                lines.append(f"    - {step_id} ({step_tool})")
+        lines.append("  Call end_workflow(reason) when done, cancelled, or off-topic.")
+        return "\n".join(lines)
+
+    def _format_episodic_context(self, memory) -> str:
+        """Format episodic memory context for the prompt."""
+        lines = []
+
+        if memory.episodic.last_search_results:
+            results = memory.episodic.last_search_results
+            result_list = results.get("results", [])
+            lines.append(
+                f"\nLAST SEARCH: '{results.get('query')}' ({len(result_list)} results)"
+            )
+            # Show first 5 results
+            for i, result in enumerate(result_list[:5]):
+                name = result.get("name", "Unknown")
+                lines.append(f"  {i + 1}. {name}")
+            if len(result_list) > 5:
+                lines.append(f"  ... and {len(result_list) - 5} more")
+
+        if memory.episodic.pending_question:
+            question = memory.episodic.pending_question
+            lines.append(f"\nPENDING QUESTION: {question.get('question')}")
+            lines.append(f"  Type: {question.get('type')}")
+            if question.get("options"):
+                lines.append(f"  Options: {len(question.get('options'))}")
+
+        if memory.episodic.active_downloads:
+            lines.append(f"\nACTIVE DOWNLOADS: {len(memory.episodic.active_downloads)}")
+            for dl in memory.episodic.active_downloads[:3]:
+                lines.append(f"  - {dl.get('name')}: {dl.get('progress', 0)}%")
+
+        if memory.episodic.recent_errors:
+            lines.append("\nRECENT ERRORS (up to 3):")
+            for error in memory.episodic.recent_errors[-3:]:
+                lines.append(
+                    f"  - Action '{error.get('action')}' failed: {error.get('error')}"
+                )
+
+        # Unread events
+        unread = [e for e in memory.episodic.background_events if not e.get("read")]
+        if unread:
+            lines.append(f"\nUNREAD EVENTS: {len(unread)}")
+            for event in unread[:3]:
+                lines.append(f"  - {event.get('type')}: {event.get('data')}")
+
+        return "\n".join(lines)
+
+    def _format_stm_context(self, memory) -> str:
+        """Format short-term memory context for the prompt."""
+        lines = []
+
+        if memory.stm.current_workflow:
+            workflow = memory.stm.current_workflow
+            lines.append(
+                f"CURRENT WORKFLOW: {workflow.get('name')} (stage: {workflow.get('stage')})"
+            )
+            if workflow.get("params"):
+                lines.append(f"  Params: {workflow.get('params')}")
+
+        if memory.stm.current_topic:
+            lines.append(f"CURRENT TOPIC: {memory.stm.current_topic}")
+
+        if memory.stm.extracted_entities:
+            lines.append("EXTRACTED ENTITIES:")
+            for key, value in memory.stm.extracted_entities.items():
+                lines.append(f"  - {key}: {value}")
+
+        if memory.stm.language:
+            lines.append(f"CONVERSATION LANGUAGE: {memory.stm.language}")
+
+        return "\n".join(lines)
+
+    def _format_memory_schema(self) -> str:
+        """Describe available memory components so the agent knows what to read/write and when."""
+        schema = self._memory_registry.schema()
+        tier_labels = {
+            "ltm": "LONG-TERM (persisted)",
+            "stm": "SHORT-TERM (session)",
+            "episodic": "EPISODIC (volatile)",
+        }
+        lines = ["MEMORY COMPONENTS:"]
+
+        for tier, components in schema.items():
+            if not components:
+                continue
+            lines.append(f"\n  [{tier_labels.get(tier, tier.upper())}]")
+            for c in components:
+                access = c.get("access", "read")
+                lines.append(f"  {c['name']} ({access}): {c['description']}")
+                for field_name, field_desc in c.get("fields", {}).items():
+                    lines.append(f"    · {field_name}: {field_desc}")
+
+        return "\n".join(lines)
+
+    def _format_config_context(self, memory) -> str:
+        """Format configuration context."""
+        lines = ["CURRENT CONFIGURATION:"]
+        folders = {
+            **memory.ltm.workspace.as_dict(),
+            **memory.ltm.library_paths.to_dict(),
+        }
+        if folders:
+            for key, value in folders.items():
+                lines.append(f"  - {key}: {value}")
+        else:
+            lines.append("  (no configuration set)")
+        return "\n".join(lines)
+
+    def build_system_prompt(self) -> str:
+        """Build the complete system prompt."""
+        memory = get_memory()
+
+        # Identity + personality
+        identity = self._format_identity(memory)
+
+        # Language instruction
+        language_instruction = (
+            "Si la langue de l'user est différente de la langue courante en STM, "
+            "appelle `set_language` en premier avant de répondre."
+        )
+
+        # Configuration
+        config_section = self._format_config_context(memory)
+
+        # STM context
+        stm_context = self._format_stm_context(memory)
+
+        # Episodic context
+        episodic_context = self._format_episodic_context(memory)
+
+        # Memory schema
+        memory_schema = self._format_memory_schema()
+
+        # Workflow scope (active workflow plan or list of options)
+        workflow_section = self._format_workflow_scope(memory)
+
+        # Available tools (already filtered by scope)
+        tools_desc = self._format_tools_description()
+        tools_section = f"\nOUTILS DISPONIBLES:\n{tools_desc}" if tools_desc else ""
+
+        rules = """
+RÈGLES:
+- Utilise les outils pour accomplir les tâches, pas pour décorer
+- Si des résultats de recherche sont dispo en mémoire épisodique, référence-les par index
+- Confirme toujours avant une opération destructive (move, delete, overwrite)
+- Réponses courtes — si c'est fait, dis-le en une ligne
+- Si la demande est floue, demande un éclaircissement AVANT de lancer quoi que ce soit
+"""
+
+        sections = [
+            identity,
+            language_instruction,
+            config_section,
+            stm_context,
+            episodic_context,
+            memory_schema,
+            workflow_section,
+            tools_section,
+            rules,
+        ]
+        return "\n\n".join(s for s in sections if s and s.strip())

alfred/agent/prompts.py

@@ -1,180 +0,0 @@
-"""Prompt builder for the agent system."""
-
-import json
-from typing import Any
-
-from alfred.infrastructure.persistence import get_memory
-
-from .registry import Tool
-
-
-class PromptBuilder:
-    """Builds system prompts for the agent with memory context."""
-
-    def __init__(self, tools: dict[str, Tool]):
-        self.tools = tools
-
-    def build_tools_spec(self) -> list[dict[str, Any]]:
-        """Build the tool specification for the LLM API."""
-        tool_specs = []
-        for tool in self.tools.values():
-            spec = {
-                "type": "function",
-                "function": {
-                    "name": tool.name,
-                    "description": tool.description,
-                    "parameters": tool.parameters,
-                },
-            }
-            tool_specs.append(spec)
-        return tool_specs
-
-    def _format_tools_description(self) -> str:
-        """Format tools with their descriptions and parameters."""
-        if not self.tools:
-            return ""
-        return "\n".join(
-            f"- {tool.name}: {tool.description}\n"
-            f"  Parameters: {json.dumps(tool.parameters, ensure_ascii=False)}"
-            for tool in self.tools.values()
-        )
-
-    def _format_episodic_context(self, memory) -> str:
-        """Format episodic memory context for the prompt."""
-        lines = []
-
-        if memory.episodic.last_search_results:
-            results = memory.episodic.last_search_results
-            result_list = results.get("results", [])
-            lines.append(
-                f"\nLAST SEARCH: '{results.get('query')}' ({len(result_list)} results)"
-            )
-            # Show first 5 results
-            for i, result in enumerate(result_list[:5]):
-                name = result.get("name", "Unknown")
-                lines.append(f"  {i + 1}. {name}")
-            if len(result_list) > 5:
-                lines.append(f"  ... and {len(result_list) - 5} more")
-
-        if memory.episodic.pending_question:
-            question = memory.episodic.pending_question
-            lines.append(f"\nPENDING QUESTION: {question.get('question')}")
-            lines.append(f"  Type: {question.get('type')}")
-            if question.get("options"):
-                lines.append(f"  Options: {len(question.get('options'))}")
-
-        if memory.episodic.active_downloads:
-            lines.append(f"\nACTIVE DOWNLOADS: {len(memory.episodic.active_downloads)}")
-            for dl in memory.episodic.active_downloads[:3]:
-                lines.append(f"  - {dl.get('name')}: {dl.get('progress', 0)}%")
-
-        if memory.episodic.recent_errors:
-            lines.append("\nRECENT ERRORS (up to 3):")
-            for error in memory.episodic.recent_errors[-3:]:
-                lines.append(
-                    f"  - Action '{error.get('action')}' failed: {error.get('error')}"
-                )
-
-        # Unread events
-        unread = [e for e in memory.episodic.background_events if not e.get("read")]
-        if unread:
-            lines.append(f"\nUNREAD EVENTS: {len(unread)}")
-            for event in unread[:3]:
-                lines.append(f"  - {event.get('type')}: {event.get('data')}")
-
-        return "\n".join(lines)
-
-    def _format_stm_context(self, memory) -> str:
-        """Format short-term memory context for the prompt."""
-        lines = []
-
-        if memory.stm.current_workflow:
-            workflow = memory.stm.current_workflow
-            lines.append(
-                f"CURRENT WORKFLOW: {workflow.get('type')} (stage: {workflow.get('stage')})"
-            )
-            if workflow.get("target"):
-                lines.append(f"  Target: {workflow.get('target')}")
-
-        if memory.stm.current_topic:
-            lines.append(f"CURRENT TOPIC: {memory.stm.current_topic}")
-
-        if memory.stm.extracted_entities:
-            lines.append("EXTRACTED ENTITIES:")
-            for key, value in memory.stm.extracted_entities.items():
-                lines.append(f"  - {key}: {value}")
-
-        if memory.stm.language:
-            lines.append(f"CONVERSATION LANGUAGE: {memory.stm.language}")
-
-        return "\n".join(lines)
-
-    def _format_config_context(self, memory) -> str:
-        """Format configuration context."""
-        lines = ["CURRENT CONFIGURATION:"]
-        if memory.ltm.config:
-            for key, value in memory.ltm.config.items():
-                lines.append(f"  - {key}: {value}")
-        else:
-            lines.append("  (no configuration set)")
-        return "\n".join(lines)
-
-    def build_system_prompt(self) -> str:
-        """Build the complete system prompt."""
-        # Get memory once for all context formatting
-        memory = get_memory()
-
-        # Base instruction
-        base = "You are a helpful AI assistant for managing a media library."
-
-        # Language instruction
-        language_instruction = (
-            "Your first task is to determine the user's language from their message "
-            "and use the `set_language` tool if it's different from the current one. "
-            "After that, proceed to help the user."
-        )
-
-        # Available tools
-        tools_desc = self._format_tools_description()
-        tools_section = f"\nAVAILABLE TOOLS:\n{tools_desc}" if tools_desc else ""
-
-        # Configuration
-        config_section = self._format_config_context(memory)
-        if config_section:
-            config_section = f"\n{config_section}"
-
-        # STM context
-        stm_context = self._format_stm_context(memory)
-        if stm_context:
-            stm_context = f"\n{stm_context}"
-
-        # Episodic context
-        episodic_context = self._format_episodic_context(memory)
-
-        # Important rules
-        rules = """
-IMPORTANT RULES:
-- Use tools to accomplish tasks
-- When search results are available, reference them by index (e.g., "add_torrent_by_index")
-- Always confirm actions with the user before executing destructive operations
-- Provide clear, concise responses
-"""
-
-        # Examples
-        examples = """
-EXAMPLES:
-- User: "Find Inception" → Use find_media_imdb_id, then find_torrent
-- User: "download the 3rd one" → Use add_torrent_by_index with index=3
-- User: "List my downloads" → Use list_folder with folder_type="download"
-"""
-
-        return f"""{base}
-
-{language_instruction}
-{tools_section}
-{config_section}
-{stm_context}
-{episodic_context}
-{rules}
-{examples}
-"""

alfred/agent/registry.py

@@ -1,4 +1,4 @@
-"""Tool registry - defines and registers all available tools for the agent."""
+"""Tool registry — defines and registers all available tools for the agent."""
 
 import inspect
 import logging
@@ -6,6 +6,9 @@ from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any
 
+from .tools.spec import ToolSpec, ToolSpecError
+from .tools.spec_loader import load_tool_specs
+
 logger = logging.getLogger(__name__)
 
 
@@ -17,51 +20,63 @@ class Tool:
     description: str
     func: Callable[..., dict[str, Any]]
     parameters: dict[str, Any]
+    cache_key: str | None = None  # Parameter name to use as STM cache key.
 
 
-def _create_tool_from_function(func: Callable) -> Tool:
+_PY_TYPE_TO_JSON = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+}
+
+
+def _json_type_for(annotation) -> str:
+    """Map a Python type annotation to a JSON Schema 'type' string."""
+    if annotation is inspect.Parameter.empty:
+        return "string"
+    # Strip Optional[X] / X | None to X.
+    args = getattr(annotation, "__args__", None)
+    if args:
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) == 1:
+            annotation = non_none[0]
+    return _PY_TYPE_TO_JSON.get(annotation, "string")
+
+
+def _create_tool_from_function(func: Callable, spec: ToolSpec | None = None) -> Tool:
     """
-    Create a Tool object from a function.
+    Create a Tool object from a function, optionally enriched with a spec.
 
-    Args:
-        func: Function to convert to a tool
-
-    Returns:
-        Tool object with metadata extracted from function
+    Types and required-ness always come from the Python signature (source of
+    truth for the API contract). When a spec is provided, the description
+    and per-parameter docs come from the YAML spec instead of the docstring.
     """
     sig = inspect.signature(func)
-    doc = inspect.getdoc(func)
+    sig_params = {name: p for name, p in sig.parameters.items() if name != "self"}
 
-    # Extract description from docstring (first line)
-    description = doc.strip().split("\n")[0] if doc else func.__name__
-
-    # Build JSON schema from function signature
-    properties = {}
-    required = []
-
-    for param_name, param in sig.parameters.items():
-        if param_name == "self":
-            continue
-
-        # Map Python types to JSON schema types
-        param_type = "string"  # default
-        if param.annotation != inspect.Parameter.empty:
-            if param.annotation is str:
-                param_type = "string"
-            elif param.annotation is int:
-                param_type = "integer"
-            elif param.annotation is float:
-                param_type = "number"
-            elif param.annotation is bool:
-                param_type = "boolean"
-
-        properties[param_name] = {
-            "type": param_type,
-            "description": f"Parameter {param_name}",
+    if spec is not None:
+        _validate_spec_matches_signature(func.__name__, sig_params, spec)
+        description = spec.compile_description()
+        param_descriptions = {
+            name: spec.compile_parameter_description(name) for name in sig_params
         }
+    else:
+        doc = inspect.getdoc(func)
+        description = doc.strip().split("\n")[0] if doc else func.__name__
+        param_descriptions = {name: f"Parameter {name}" for name in sig_params}
 
-        # Add to required if no default value
-        if param.default == inspect.Parameter.empty:
+    properties: dict[str, dict[str, Any]] = {}
+    required: list[str] = []
+
+    for param_name, param in sig_params.items():
+        properties[param_name] = {
+            "type": _json_type_for(param.annotation),
+            "description": param_descriptions[param_name],
+        }
+        if param.default is inspect.Parameter.empty:
             required.append(param_name)
 
     parameters = {
@@ -70,11 +85,38 @@ def _create_tool_from_function(func: Callable) -> Tool:
         "required": required,
     }
 
+    cache_key = spec.cache.key if spec is not None and spec.cache is not None else None
+
     return Tool(
         name=func.__name__,
         description=description,
         func=func,
         parameters=parameters,
+        cache_key=cache_key,
+    )
+
+
+def _validate_spec_matches_signature(
+    func_name: str,
+    sig_params: dict[str, inspect.Parameter],
+    spec: ToolSpec,
+) -> None:
+    """Ensure every signature param has a spec entry and vice versa."""
+    sig_names = set(sig_params.keys())
+    spec_names = set(spec.parameters.keys())
+
+    missing_in_spec = sig_names - spec_names
+    if missing_in_spec:
+        raise ToolSpecError(
+            f"tool '{func_name}': spec is missing entries for parameter(s) "
+            f"{sorted(missing_in_spec)}"
+        )
+
+    extra_in_spec = spec_names - sig_names
+    if extra_in_spec:
+        raise ToolSpecError(
+            f"tool '{func_name}': spec has entries for unknown parameter(s) "
+            f"{sorted(extra_in_spec)} (not in function signature)"
         )
 
 
@@ -83,33 +125,54 @@ def make_tools(settings) -> dict[str, Tool]:
     Create and register all available tools.
 
     Args:
-        settings: Application settings instance
+        settings: Application settings instance.
 
     Returns:
-        Dictionary mapping tool names to Tool objects
+        Dictionary mapping tool names to Tool objects.
     """
-    # Import tools here to avoid circular dependencies
     from .tools import api as api_tools  # noqa: PLC0415
     from .tools import filesystem as fs_tools  # noqa: PLC0415
     from .tools import language as lang_tools  # noqa: PLC0415
+    from .tools import workflow as wf_tools  # noqa: PLC0415
 
-    # List of all tool functions
     tool_functions = [
         fs_tools.set_path_for_folder,
         fs_tools.list_folder,
+        fs_tools.read_release_metadata,
+        fs_tools.query_library,
+        fs_tools.analyze_release,
+        fs_tools.probe_media,
+        fs_tools.resolve_season_destination,
+        fs_tools.resolve_episode_destination,
+        fs_tools.resolve_movie_destination,
+        fs_tools.resolve_series_destination,
+        fs_tools.move_media,
+        fs_tools.move_to_destination,
+        fs_tools.manage_subtitles,
+        fs_tools.create_seed_links,
+        fs_tools.learn,
         api_tools.find_media_imdb_id,
         api_tools.find_torrent,
         api_tools.add_torrent_by_index,
         api_tools.add_torrent_to_qbittorrent,
         api_tools.get_torrent_by_index,
         lang_tools.set_language,
+        wf_tools.start_workflow,
+        wf_tools.end_workflow,
     ]
 
-    # Create Tool objects from functions
-    tools = {}
+    specs = load_tool_specs()
+
+    tools: dict[str, Tool] = {}
     for func in tool_functions:
-        tool = _create_tool_from_function(func)
+        spec = specs.get(func.__name__)
+        tool = _create_tool_from_function(func, spec=spec)
         tools[tool.name] = tool
 
-    logger.info(f"Registered {len(tools)} tools: {list(tools.keys())}")
+    with_spec = sum(1 for fn in tool_functions if fn.__name__ in specs)
+    logger.info(
+        f"Registered {len(tools)} tools "
+        f"({with_spec} with YAML spec, {len(tools) - with_spec} doc-only): "
+        f"{list(tools.keys())}"
+    )
     return tools

alfred/agent/tools/api.py

@@ -14,15 +14,7 @@ logger = logging.getLogger(__name__)
 
 
 def find_media_imdb_id(media_title: str) -> dict[str, Any]:
-    """
-    Find the IMDb ID for a given media title using TMDB API.
-
-    Args:
-        media_title: Title of the media to search for.
-
-    Returns:
-        Dict with IMDb ID and media info, or error details.
-    """
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/find_media_imdb_id.yaml."""
     use_case = SearchMovieUseCase(tmdb_client)
     response = use_case.execute(media_title)
     result = response.to_dict()
@@ -45,18 +37,7 @@ def find_media_imdb_id(media_title: str) -> dict[str, Any]:
 
 
 def find_torrent(media_title: str) -> dict[str, Any]:
-    """
-    Find torrents for a given media title using Knaben API.
-
-    Results are stored in episodic memory so the user can reference them
-    by index (e.g., "download the 3rd one").
-
-    Args:
-        media_title: Title of the media to search for.
-
-    Returns:
-        Dict with torrent list or error details.
-    """
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/find_torrent.yaml."""
     logger.info(f"Searching torrents for: {media_title}")
 
     use_case = SearchTorrentsUseCase(knaben_client)
@@ -76,17 +57,7 @@ def find_torrent(media_title: str) -> dict[str, Any]:
 
 
 def get_torrent_by_index(index: int) -> dict[str, Any]:
-    """
-    Get a torrent from the last search results by its index.
-
-    Allows the user to reference results by number after a search.
-
-    Args:
-        index: 1-based index of the torrent in the search results.
-
-    Returns:
-        Dict with torrent data or error if not found.
-    """
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/get_torrent_by_index.yaml."""
     logger.info(f"Getting torrent at index: {index}")
 
     memory = get_memory()
@@ -113,15 +84,7 @@ def get_torrent_by_index(index: int) -> dict[str, Any]:
 
 
 def add_torrent_to_qbittorrent(magnet_link: str) -> dict[str, Any]:
-    """
-    Add a torrent to qBittorrent using a magnet link.
-
-    Args:
-        magnet_link: Magnet link of the torrent to add.
-
-    Returns:
-        Dict with success status or error details.
-    """
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/add_torrent_to_qbittorrent.yaml."""
     logger.info("Adding torrent to qBittorrent")
 
     use_case = AddTorrentUseCase(qbittorrent_client)
@@ -157,17 +120,7 @@ def add_torrent_to_qbittorrent(magnet_link: str) -> dict[str, Any]:
 
 
 def add_torrent_by_index(index: int) -> dict[str, Any]:
-    """
-    Add a torrent from the last search results by its index.
-
-    Combines get_torrent_by_index and add_torrent_to_qbittorrent.
-
-    Args:
-        index: 1-based index of the torrent in the search results.
-
-    Returns:
-        Dict with success status or error details.
-    """
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/add_torrent_by_index.yaml."""
     logger.info(f"Adding torrent by index: {index}")
 
     torrent_result = get_torrent_by_index(index)

alfred/agent/tools/filesystem.py

@@ -1,40 +1,377 @@
 """Filesystem tools for folder management."""
 
+from pathlib import Path
 from typing import Any
 
-from alfred.application.filesystem import ListFolderUseCase, SetFolderPathUseCase
-from alfred.infrastructure.filesystem import FileManager
+import yaml
+
+import alfred as _alfred_pkg
+from alfred.application.filesystem import (
+    CreateSeedLinksUseCase,
+    ListFolderUseCase,
+    ManageSubtitlesUseCase,
+    MoveMediaUseCase,
+    SetFolderPathUseCase,
+)
+from alfred.application.filesystem.resolve_destination import (
+    resolve_episode_destination as _resolve_episode_destination,
+)
+from alfred.application.filesystem.resolve_destination import (
+    resolve_movie_destination as _resolve_movie_destination,
+)
+from alfred.application.filesystem.resolve_destination import (
+    resolve_season_destination as _resolve_season_destination,
+)
+from alfred.application.filesystem.resolve_destination import (
+    resolve_series_destination as _resolve_series_destination,
+)
+from alfred.infrastructure.filesystem import FileManager, create_folder, move
+from alfred.infrastructure.knowledge.release_kb import YamlReleaseKnowledge
+from alfred.infrastructure.metadata import MetadataStore
+from alfred.infrastructure.persistence import get_memory
+from alfred.infrastructure.probe import FfprobeMediaProber
+
+# Agent-tools frontier: this is the legitimate home for the singletons that
+# back every LLM-exposed wrapper. The use cases below take ``kb`` / ``prober``
+# as required params; tests inject their own stubs.
+_KB = YamlReleaseKnowledge()
+_PROBER = FfprobeMediaProber()
+
+_LEARNED_ROOT = Path(_alfred_pkg.__file__).parent.parent / "data" / "knowledge"
+
+
+def move_media(source: str, destination: str) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/move_media.yaml."""
+    file_manager = FileManager()
+    use_case = MoveMediaUseCase(file_manager)
+    return use_case.execute(source, destination).to_dict()
+
+
+def move_to_destination(source: str, destination: str) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/move_to_destination.yaml."""
+    parent = str(Path(destination).parent)
+    result = create_folder(parent)
+    if result["status"] != "ok":
+        return result
+    return move(source, destination)
+
+
+def resolve_season_destination(
+    release_name: str,
+    tmdb_title: str,
+    tmdb_year: int,
+    confirmed_folder: str | None = None,
+    source_path: str | None = None,
+) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/resolve_season_destination.yaml."""
+    return _resolve_season_destination(
+        release_name,
+        tmdb_title,
+        tmdb_year,
+        _KB,
+        _PROBER,
+        confirmed_folder,
+        source_path,
+    ).to_dict()
+
+
+def resolve_episode_destination(
+    release_name: str,
+    source_file: str,
+    tmdb_title: str,
+    tmdb_year: int,
+    tmdb_episode_title: str | None = None,
+    confirmed_folder: str | None = None,
+) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/resolve_episode_destination.yaml."""
+    return _resolve_episode_destination(
+        release_name,
+        source_file,
+        tmdb_title,
+        tmdb_year,
+        _KB,
+        _PROBER,
+        tmdb_episode_title,
+        confirmed_folder,
+    ).to_dict()
+
+
+def resolve_movie_destination(
+    release_name: str,
+    source_file: str,
+    tmdb_title: str,
+    tmdb_year: int,
+) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/resolve_movie_destination.yaml."""
+    return _resolve_movie_destination(
+        release_name, source_file, tmdb_title, tmdb_year, _KB, _PROBER
+    ).to_dict()
+
+
+def resolve_series_destination(
+    release_name: str,
+    tmdb_title: str,
+    tmdb_year: int,
+    confirmed_folder: str | None = None,
+    source_path: str | None = None,
+) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/resolve_series_destination.yaml."""
+    return _resolve_series_destination(
+        release_name,
+        tmdb_title,
+        tmdb_year,
+        _KB,
+        _PROBER,
+        confirmed_folder,
+        source_path,
+    ).to_dict()
+
+
+def create_seed_links(
+    library_file: str, original_download_folder: str
+) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/create_seed_links.yaml."""
+    file_manager = FileManager()
+    use_case = CreateSeedLinksUseCase(file_manager)
+    return use_case.execute(library_file, original_download_folder).to_dict()
+
+
+def manage_subtitles(source_video: str, destination_video: str) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/manage_subtitles.yaml."""
+    file_manager = FileManager()
+    use_case = ManageSubtitlesUseCase(file_manager)
+    return use_case.execute(source_video, destination_video).to_dict()
+
+
+def learn(pack: str, category: str, key: str, values: list[str]) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/learn.yaml."""
+    _VALID_PACKS = {"subtitles"}
+    _VALID_CATEGORIES = {"languages", "types", "formats"}
+
+    if pack not in _VALID_PACKS:
+        return {
+            "status": "error",
+            "error": "unknown_pack",
+            "message": f"Unknown pack '{pack}'. Valid: {sorted(_VALID_PACKS)}",
+        }
+
+    if category not in _VALID_CATEGORIES:
+        return {
+            "status": "error",
+            "error": "unknown_category",
+            "message": f"Unknown category '{category}'. Valid: {sorted(_VALID_CATEGORIES)}",
+        }
+
+    learned_path = _LEARNED_ROOT / "subtitles_learned.yaml"
+    _LEARNED_ROOT.mkdir(parents=True, exist_ok=True)
+
+    data: dict = {}
+    if learned_path.exists():
+        try:
+            with open(learned_path, encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+        except Exception as e:
+            return {"status": "error", "error": "read_failed", "message": str(e)}
+
+    cat_data = data.setdefault(category, {})
+    entry = cat_data.setdefault(key, {"tokens": []})
+    existing = entry.get("tokens", [])
+    new_tokens = [v for v in values if v not in existing]
+    entry["tokens"] = existing + new_tokens
+
+    tmp = learned_path.with_suffix(".yaml.tmp")
+    try:
+        with open(tmp, "w", encoding="utf-8") as f:
+            yaml.safe_dump(
+                data, f, allow_unicode=True, default_flow_style=False, sort_keys=False
+            )
+        tmp.rename(learned_path)
+    except Exception as e:
+        tmp.unlink(missing_ok=True)
+        return {"status": "error", "error": "write_failed", "message": str(e)}
+
+    return {
+        "status": "ok",
+        "pack": pack,
+        "category": category,
+        "key": key,
+        "added_count": len(new_tokens),
+        "tokens": entry["tokens"],
+    }
 
 
 def set_path_for_folder(folder_name: str, path_value: str) -> dict[str, Any]:
-    """
-    Set a folder path in the configuration.
-
-    Args:
-        folder_name: Name of folder to set (download, tvshow, movie, torrent).
-        path_value: Absolute path to the folder.
-
-    Returns:
-        Dict with status or error information.
-    """
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/set_path_for_folder.yaml."""
     file_manager = FileManager()
     use_case = SetFolderPathUseCase(file_manager)
     response = use_case.execute(folder_name, path_value)
     return response.to_dict()
 
 
+def analyze_release(release_name: str, source_path: str) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/analyze_release.yaml."""
+    from alfred.application.release import inspect_release  # noqa: PLC0415
+
+    result = inspect_release(release_name, Path(source_path), _KB, _PROBER)
+    parsed = result.parsed
+    return {
+        "status": "ok",
+        "media_type": parsed.media_type,
+        "parse_path": parsed.parse_path,
+        "title": parsed.title,
+        "year": parsed.year,
+        "season": parsed.season,
+        "episode": parsed.episode,
+        "episode_end": parsed.episode_end,
+        "quality": parsed.quality,
+        "source": parsed.source,
+        "codec": parsed.codec,
+        "group": parsed.group,
+        "languages": parsed.languages,
+        "audio_codec": parsed.audio_codec,
+        "audio_channels": parsed.audio_channels,
+        "bit_depth": parsed.bit_depth,
+        "hdr_format": parsed.hdr_format,
+        "edition": parsed.edition,
+        "site_tag": parsed.site_tag,
+        "is_season_pack": parsed.is_season_pack,
+        "probe_used": result.probe_used,
+        "confidence": result.report.confidence,
+        "road": result.report.road,
+        "recommended_action": result.recommended_action,
+    }
+
+
+def probe_media(source_path: str) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/probe_media.yaml."""
+    path = Path(source_path)
+    if not path.exists():
+        return {
+            "status": "error",
+            "error": "not_found",
+            "message": f"{source_path} does not exist",
+        }
+
+    media_info = _PROBER.probe(path)
+    if media_info is None:
+        return {
+            "status": "error",
+            "error": "probe_failed",
+            "message": "ffprobe failed to read the file",
+        }
+
+    return {
+        "status": "ok",
+        "video": {
+            "codec": media_info.video_codec,
+            "resolution": media_info.resolution,
+            "width": media_info.width,
+            "height": media_info.height,
+            "duration_seconds": media_info.duration_seconds,
+            "bitrate_kbps": media_info.bitrate_kbps,
+        },
+        "audio_tracks": [
+            {
+                "index": t.index,
+                "codec": t.codec,
+                "channels": t.channels,
+                "channel_layout": t.channel_layout,
+                "language": t.language,
+                "is_default": t.is_default,
+            }
+            for t in media_info.audio_tracks
+        ],
+        "subtitle_tracks": [
+            {
+                "index": t.index,
+                "codec": t.codec,
+                "language": t.language,
+                "is_default": t.is_default,
+                "is_forced": t.is_forced,
+            }
+            for t in media_info.subtitle_tracks
+        ],
+        "audio_languages": media_info.audio_languages,
+        "is_multi_audio": media_info.is_multi_audio,
+    }
+
+
 def list_folder(folder_type: str, path: str = ".") -> dict[str, Any]:
-    """
-    List contents of a configured folder.
-
-    Args:
-        folder_type: Type of folder to list (download, tvshow, movie, torrent).
-        path: Relative path within the folder (default: root).
-
-    Returns:
-        Dict with folder contents or error information.
-    """
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/list_folder.yaml."""
     file_manager = FileManager()
     use_case = ListFolderUseCase(file_manager)
     response = use_case.execute(folder_type, path)
     return response.to_dict()
+
+
+def read_release_metadata(release_path: str) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/read_release_metadata.yaml."""
+    path = Path(release_path)
+    if not path.exists():
+        return {
+            "status": "error",
+            "error": "not_found",
+            "message": f"{release_path} does not exist",
+        }
+    root = path if path.is_dir() else path.parent
+    store = MetadataStore(root)
+    if not store.exists():
+        return {
+            "status": "ok",
+            "release_path": str(root),
+            "has_metadata": False,
+            "metadata": {},
+        }
+    return {
+        "status": "ok",
+        "release_path": str(root),
+        "has_metadata": True,
+        "metadata": store.load(),
+    }
+
+
+def query_library(name: str) -> dict[str, Any]:
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/query_library.yaml."""
+    needle = name.strip().lower()
+    if not needle:
+        return {
+            "status": "error",
+            "error": "empty_name",
+            "message": "name must be a non-empty string",
+        }
+
+    memory = get_memory()
+    roots = memory.ltm.library_paths.to_dict() or {}
+    if not roots:
+        return {
+            "status": "error",
+            "error": "no_libraries",
+            "message": "No library paths configured — call set_path_for_folder first.",
+        }
+
+    matches: list[dict[str, Any]] = []
+    for collection, root in roots.items():
+        root_path = Path(root)
+        if not root_path.is_dir():
+            continue
+        for entry in root_path.iterdir():
+            if not entry.is_dir():
+                continue
+            if needle not in entry.name.lower():
+                continue
+            store = MetadataStore(entry)
+            matches.append(
+                {
+                    "collection": collection,
+                    "name": entry.name,
+                    "path": str(entry),
+                    "has_metadata": store.exists(),
+                }
+            )
+
+    return {
+        "status": "ok",
+        "query": name,
+        "match_count": len(matches),
+        "matches": matches,
+    }

alfred/agent/tools/language.py

@@ -9,15 +9,7 @@ logger = logging.getLogger(__name__)
 
 
 def set_language(language: str) -> dict[str, Any]:
-    """
-    Set the conversation language.
-
-    Args:
-        language: Language code (e.g., 'en', 'fr', 'es', 'de')
-
-    Returns:
-        Status dictionary
-    """
+    """Thin tool wrapper — semantics live in alfred/agent/tools/specs/set_language.yaml."""
     try:
         memory = get_memory()
         memory.stm.set_language(language)

alfred/agent/tools/spec.py

@@ -0,0 +1,221 @@
+"""
+ToolSpec — semantic description of a tool, loaded from YAML.
+
+Each tool exposed to the agent has a matching YAML spec under
+alfred/agent/tools/specs/{tool_name}.yaml. The spec carries everything the
+LLM needs to decide *when* and *why* to call the tool — separated from the
+Python signature, which remains the source of truth for *how* (types,
+required-ness).
+
+The YAML structure is documented in the dataclasses below. Loading a spec
+validates its shape; missing or unexpected fields raise ToolSpecError.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+class ToolSpecError(ValueError):
+    """Raised when a YAML tool spec is malformed or inconsistent."""
+
+
+@dataclass(frozen=True)
+class ParameterSpec:
+    """Semantic description of a single tool parameter."""
+
+    description: str  # Short: what the value represents.
+    why_needed: str  # Why the tool needs this — drives LLM reasoning.
+    example: str | None = None  # Concrete example value, shown to the LLM.
+
+    @classmethod
+    def from_dict(cls, name: str, data: dict) -> ParameterSpec:
+        _require(data, "description", f"parameter '{name}'")
+        _require(data, "why_needed", f"parameter '{name}'")
+        return cls(
+            description=str(data["description"]).strip(),
+            why_needed=str(data["why_needed"]).strip(),
+            example=str(data["example"]).strip()
+            if data.get("example") is not None
+            else None,
+        )
+
+
+@dataclass(frozen=True)
+class ReturnsSpec:
+    """Description of one possible return shape (ok / needs_clarification / error / ...)."""
+
+    description: str
+    fields: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, key: str, data: dict) -> ReturnsSpec:
+        _require(data, "description", f"returns.{key}")
+        fields = data.get("fields") or {}
+        if not isinstance(fields, dict):
+            raise ToolSpecError(
+                f"returns.{key}.fields must be a dict, got {type(fields).__name__}"
+            )
+        return cls(
+            description=str(data["description"]).strip(),
+            fields={str(k): str(v).strip() for k, v in fields.items()},
+        )
+
+
+@dataclass(frozen=True)
+class CacheSpec:
+    """Marks a tool as cacheable in STM.tool_results, keyed by one of its parameters."""
+
+    key: str  # Name of the parameter whose value is the cache key.
+
+    @classmethod
+    def from_dict(cls, data: dict) -> CacheSpec:
+        _require(data, "key", "cache")
+        return cls(key=str(data["key"]).strip())
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    """Full semantic spec for one tool."""
+
+    name: str
+    summary: str  # One-liner — becomes Tool.description.
+    description: str  # Longer paragraph.
+    when_to_use: str
+    when_not_to_use: str | None
+    next_steps: str | None
+    parameters: dict[str, ParameterSpec]  # name -> ParameterSpec
+    returns: dict[str, ReturnsSpec]  # status_key -> ReturnsSpec
+    cache: CacheSpec | None = None  # If present, tool is cached.
+
+    @classmethod
+    def from_yaml_path(cls, path: Path) -> ToolSpec:
+        with open(path, encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+        if not isinstance(data, dict):
+            raise ToolSpecError(f"{path}: top-level must be a mapping")
+        try:
+            return cls.from_dict(data)
+        except ToolSpecError as e:
+            raise ToolSpecError(f"{path}: {e}") from e
+
+    @classmethod
+    def from_dict(cls, data: dict) -> ToolSpec:
+        _require(data, "name", "spec")
+        _require(data, "summary", "spec")
+        _require(data, "description", "spec")
+        _require(data, "when_to_use", "spec")
+
+        params_raw = data.get("parameters") or {}
+        if not isinstance(params_raw, dict):
+            raise ToolSpecError("parameters must be a mapping")
+        parameters = {
+            pname: ParameterSpec.from_dict(pname, pdata or {})
+            for pname, pdata in params_raw.items()
+        }
+
+        returns_raw = data.get("returns") or {}
+        if not isinstance(returns_raw, dict):
+            raise ToolSpecError("returns must be a mapping")
+        returns = {
+            rkey: ReturnsSpec.from_dict(rkey, rdata or {})
+            for rkey, rdata in returns_raw.items()
+        }
+
+        cache_raw = data.get("cache")
+        if cache_raw is not None and not isinstance(cache_raw, dict):
+            raise ToolSpecError("cache must be a mapping")
+        cache = CacheSpec.from_dict(cache_raw) if cache_raw else None
+
+        spec = cls(
+            name=str(data["name"]).strip(),
+            summary=str(data["summary"]).strip(),
+            description=str(data["description"]).strip(),
+            when_to_use=str(data["when_to_use"]).strip(),
+            when_not_to_use=_strip_or_none(data.get("when_not_to_use")),
+            next_steps=_strip_or_none(data.get("next_steps")),
+            parameters=parameters,
+            returns=returns,
+            cache=cache,
+        )
+        if cache is not None and cache.key not in parameters:
+            raise ToolSpecError(
+                f"cache.key '{cache.key}' is not a declared parameter "
+                f"(declared: {sorted(parameters)})"
+            )
+        return spec
+
+    def compile_description(self) -> str:
+        """
+        Build the long description text passed to the LLM as Tool.description.
+
+        Layout:
+            <summary>
+
+            <description>
+
+            When to use:
+              <when_to_use>
+
+            When NOT to use:    (if present)
+              <when_not_to_use>
+
+            Next steps:         (if present)
+              <next_steps>
+
+            Returns:
+              <status>: <description>
+                · <field>: <desc>
+        """
+        parts = [self.summary, "", self.description]
+
+        parts += ["", "When to use:", _indent(self.when_to_use)]
+
+        if self.when_not_to_use:
+            parts += ["", "When NOT to use:", _indent(self.when_not_to_use)]
+
+        if self.next_steps:
+            parts += ["", "Next steps:", _indent(self.next_steps)]
+
+        if self.returns:
+            parts += ["", "Returns:"]
+            for status, ret in self.returns.items():
+                parts.append(f"  {status}: {ret.description}")
+                for fname, fdesc in ret.fields.items():
+                    parts.append(f"    · {fname}: {fdesc}")
+
+        return "\n".join(parts)
+
+    def compile_parameter_description(self, name: str) -> str:
+        """Build the JSON Schema 'description' field for one parameter."""
+        p = self.parameters.get(name)
+        if p is None:
+            raise ToolSpecError(f"tool '{self.name}': no spec for parameter '{name}'")
+        text = f"{p.description} (Why: {p.why_needed})"
+        if p.example:
+            text += f" Example: {p.example}"
+        return text
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _require(data: dict, key: str, where: str) -> None:
+    if data.get(key) is None or (isinstance(data[key], str) and not data[key].strip()):
+        raise ToolSpecError(f"{where}: missing required field '{key}'")
+
+
+def _strip_or_none(value) -> str | None:
+    if value is None:
+        return None
+    s = str(value).strip()
+    return s or None
+
+
+def _indent(text: str, prefix: str = "  ") -> str:
+    return "\n".join(prefix + line for line in text.splitlines())

alfred/agent/tools/spec_loader.py

@@ -0,0 +1,53 @@
+"""
+ToolSpecLoader — discover and load all YAML tool specs from a directory.
+
+Convention: one YAML file per tool, named exactly like the Python function
+that implements it (e.g. resolve_season_destination.yaml).
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from .spec import ToolSpec, ToolSpecError
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_SPECS_DIR = Path(__file__).parent / "specs"
+
+
+def load_tool_specs(specs_dir: Path | None = None) -> dict[str, ToolSpec]:
+    """
+    Load every {tool}.yaml under specs_dir into a {name -> ToolSpec} mapping.
+
+    Args:
+        specs_dir: Directory to scan. Defaults to alfred/agent/tools/specs/.
+
+    Returns:
+        Mapping from tool name to its parsed ToolSpec.
+
+    Raises:
+        ToolSpecError: if a spec is malformed, or if the filename doesn't
+                       match the 'name' field inside the YAML.
+    """
+    root = specs_dir or _DEFAULT_SPECS_DIR
+    if not root.exists():
+        logger.warning(f"Tool specs directory not found: {root}")
+        return {}
+
+    specs: dict[str, ToolSpec] = {}
+    for path in sorted(root.glob("*.yaml")):
+        spec = ToolSpec.from_yaml_path(path)
+        expected_name = path.stem
+        if spec.name != expected_name:
+            raise ToolSpecError(
+                f"{path}: filename stem '{expected_name}' "
+                f"does not match spec.name '{spec.name}'"
+            )
+        if spec.name in specs:
+            raise ToolSpecError(f"duplicate tool spec name: '{spec.name}'")
+        specs[spec.name] = spec
+
+    logger.info(f"Loaded {len(specs)} tool spec(s) from {root}")
+    return specs

alfred/agent/tools/specs/add_torrent_by_index.yaml

@@ -0,0 +1,53 @@
+name: add_torrent_by_index
+
+summary: >
+  Pick a torrent from the last find_torrent results by index and add
+  it to qBittorrent in one call.
+
+description: |
+  Convenience wrapper that combines get_torrent_by_index +
+  add_torrent_to_qbittorrent. Looks up the torrent at the given
+  1-based index, extracts its magnet link, and sends it to
+  qBittorrent. The result mirrors add_torrent_to_qbittorrent's, with
+  the chosen torrent's name appended on success.
+
+when_to_use: |
+  The default action after find_torrent when the user picks a hit by
+  number ("download the second one"). One call, two side effects:
+  episodic memory updated + download started.
+
+when_not_to_use: |
+  - When the user only wants to inspect, not download — use
+    get_torrent_by_index.
+  - When the magnet comes from outside the search results — use
+    add_torrent_to_qbittorrent directly.
+
+next_steps: |
+  - On status=ok: confirm the download started and end the workflow
+    if not already ended.
+  - On status=error (not_found): the index is out of range; show the
+    available count from episodic memory.
+  - On status=error (no_magnet): the search result was malformed —
+    suggest re-running find_torrent.
+
+parameters:
+  index:
+    description: 1-based position of the torrent in the last find_torrent results.
+    why_needed: |
+      Identifies which torrent to add. Out-of-range indices return
+      not_found.
+    example: 3
+
+returns:
+  ok:
+    description: Torrent was added to qBittorrent.
+    fields:
+      status: "'ok'"
+      message: Confirmation message.
+      torrent_name: Name of the torrent that was added.
+
+  error:
+    description: Failed to add.
+    fields:
+      error: Short error code (not_found, no_magnet, ...).
+      message: Human-readable explanation.

alfred/agent/tools/specs/add_torrent_to_qbittorrent.yaml

@@ -0,0 +1,48 @@
+name: add_torrent_to_qbittorrent
+
+summary: >
+  Send a magnet link to qBittorrent and start the download.
+
+description: |
+  Adds a torrent to qBittorrent using its WebUI API. On success, the
+  download is also recorded in episodic memory as an active_download
+  so the agent can track its progress later, the STM topic is set to
+  "downloading", and the current workflow is ended (the user typically
+  leaves the find-and-download scope at this point).
+
+when_to_use: |
+  When the user provides a raw magnet link, or when chaining manually
+  after get_torrent_by_index. For the common "user picked search hit
+  N" case, prefer add_torrent_by_index — one call instead of two.
+
+when_not_to_use: |
+  - For .torrent files (not supported by this tool — magnet only).
+  - When qBittorrent is not configured / reachable — the call will
+    fail and the user has to fix the config first.
+
+next_steps: |
+  - On status=ok: the workflow is already ended; confirm to the user
+    that the download has started.
+  - On status=error: surface the message; common causes are auth
+    failure or qBittorrent being unreachable.
+
+parameters:
+  magnet_link:
+    description: Magnet URI of the torrent to add (magnet:?xt=urn:btih:...).
+    why_needed: |
+      The actual payload sent to qBittorrent. Must be a full magnet
+      URI, not a hash alone.
+    example: "magnet:?xt=urn:btih:abc123..."
+
+returns:
+  ok:
+    description: Torrent accepted by qBittorrent.
+    fields:
+      status: "'ok'"
+      message: Confirmation message.
+
+  error:
+    description: qBittorrent rejected the request or is unreachable.
+    fields:
+      error: Short error code.
+      message: Human-readable explanation.

alfred/agent/tools/specs/analyze_release.yaml

@@ -0,0 +1,85 @@
+name: analyze_release
+
+summary: >
+  One-shot analyzer that parses a release name, detects its media type
+  from the folder layout, and enriches the result with ffprobe data.
+
+description: |
+  Combines three steps in a single call so the agent gets a complete
+  picture before routing:
+    1. parse_release(release_name) — extracts title, year, season,
+       episode, quality, source, codec, group, languages, audio info,
+       HDR, edition, site tag.
+    2. detect_media_type(parsed, path) — uses the on-disk layout
+       (single file vs. folder, presence of S01 dirs, episode count)
+       to choose: movie / tv_episode / tv_season / tv_complete /
+       other / unknown.
+    3. ffprobe enrichment — when the media type is recognised, runs
+       ffprobe on the first video file found and fills in audio
+       codec/channels, bit depth, HDR format. Sets probe_used=true.
+
+when_to_use: |
+  As the very first step of any organize workflow, right after
+  list_folder, on each release the user wants to handle. The output
+  drives which resolve_*_destination to call next.
+
+when_not_to_use: |
+  - When you only need codec/audio info on a specific video file:
+    use probe_media (no parsing, no media-type detection).
+  - For releases the user has already analyzed earlier in the same
+    workflow — the parse is deterministic, no need to re-run.
+
+next_steps: |
+  - media_type == movie       → resolve_movie_destination
+  - media_type == tv_season   → resolve_season_destination
+  - media_type == tv_episode  → resolve_episode_destination
+  - media_type == tv_complete → resolve_series_destination
+  - media_type in (other, unknown) → ask the user what to do; do not
+    auto-route.
+
+cache:
+  key: source_path
+
+parameters:
+  release_name:
+    description: Raw release folder or file name as it appears on disk.
+    why_needed: |
+      Source of all the parsed tokens (quality, codec, group, ...).
+      Don't sanitise it — the parser relies on the exact spelling.
+    example: Breaking.Bad.S01.1080p.BluRay.x265-GROUP
+
+  source_path:
+    description: Absolute path to the release folder or file on disk.
+    why_needed: |
+      Required for layout-based media-type detection and for ffprobe
+      to find a video file inside the release.
+    example: /downloads/Breaking.Bad.S01.1080p.BluRay.x265-GROUP
+
+returns:
+  ok:
+    description: Release analyzed.
+    fields:
+      status: "'ok'"
+      media_type: "One of: movie, tv_episode, tv_season, tv_complete, other, unknown."
+      parse_path: "Which parser branch was taken (debug)."
+      title: Parsed title.
+      year: Parsed year (int) or null.
+      season: Season number (int) or null.
+      episode: Episode number (int) or null.
+      episode_end: Range end episode (multi-episode releases) or null.
+      quality: Resolution token (e.g. 1080p, 2160p).
+      source: Source token (BluRay, WEB-DL, ...).
+      codec: Video codec token (x264, x265, ...).
+      group: Release group name or null.
+      languages: List of detected language tokens.
+      audio_codec: Audio codec from ffprobe (when probe_used=true).
+      audio_channels: Audio channel count from ffprobe.
+      bit_depth: Bit depth from ffprobe.
+      hdr_format: HDR format from ffprobe (HDR10, DV, ...) or null.
+      edition: Edition tag (Extended, Director's Cut, ...) or null.
+      site_tag: Source-site tag if present.
+      is_season_pack: True when the folder contains a full season.
+      probe_used: True when ffprobe successfully enriched the result.
+      confidence: Parser confidence score, 0–100 (higher = more reliable).
+      road: "Parser road: 'easy' (group schema matched), 'shitty' (heuristic but acceptable), or 'path_of_pain' (low confidence — ask the user before auto-routing)."
+      recommended_action: "Orchestrator hint: 'process' (go straight to resolve_*_destination), 'ask_user' (media_type unknown or road=path_of_pain — confirm with the user first), or 'skip' (no main video, or media_type=other — nothing to organize)."

alfred/agent/tools/specs/create_seed_links.yaml

@@ -0,0 +1,59 @@
+name: create_seed_links
+
+summary: >
+  Recreate the original torrent folder structure with hard-links so
+  qBittorrent can keep seeding after the library move.
+
+description: |
+  Hard-links the library video file back into torrents/<original_folder_name>/
+  and copies all remaining files from the original download folder
+  (subtitles, .nfo, .jpg, .txt, …) so the torrent data is complete on
+  disk. qBittorrent then sees the same content at the location it
+  expects and can keep seeding without rehashing the whole torrent.
+
+when_to_use: |
+  Only when the user has confirmed they want to keep seeding after a
+  move. Call right after manage_subtitles (or after move_media if there
+  are no subs).
+
+when_not_to_use: |
+  - When the user explicitly answered "no" to "keep seeding?".
+  - When the download was not from a torrent (e.g. direct download).
+  - Before the library file is in place — this tool reads it.
+
+next_steps: |
+  - After success: optionally call qBittorrent to update the torrent's
+    save path / force a recheck (not yet covered by a tool).
+  - End the workflow.
+
+parameters:
+  library_file:
+    description: Absolute path to the video file now in the library.
+    why_needed: |
+      The source for the hard-link — same inode means qBittorrent sees
+      identical bytes at the seeding path.
+    example: /tv_shows/Oz.1997.1080p.WEBRip.x265-KONTRAST/Season 03/Oz.S03E01.mkv
+
+  original_download_folder:
+    description: Absolute path to the original download folder.
+    why_needed: |
+      Provides the folder name to recreate under torrents/ and the
+      auxiliary files (subs, nfo, ...) to copy over.
+    example: /downloads/Oz.S03.1080p.WEBRip.x265-KONTRAST
+
+returns:
+  ok:
+    description: Seeding folder rebuilt.
+    fields:
+      status: "'ok'"
+      torrent_subfolder: Absolute path of the recreated folder under torrents/.
+      linked_file: Absolute path of the hard-linked video.
+      copied_files: List of auxiliary files that were copied.
+      copied_count: Number of auxiliary files copied.
+      skipped: List of files skipped (already present, unreadable, ...).
+
+  error:
+    description: Failed to rebuild the seeding folder.
+    fields:
+      error: Short error code.
+      message: Human-readable explanation.

alfred/agent/tools/specs/end_workflow.yaml

@@ -0,0 +1,48 @@
+name: end_workflow
+
+summary: >
+  Leave the current workflow scope and return to the broad-catalog mode.
+
+description: |
+  Clears the active workflow from STM. After this call the visible tool
+  catalog returns to the core noyau plus start_workflow, so the agent is
+  ready to handle a different request.
+
+when_to_use: |
+  - When all the workflow's steps have completed successfully.
+  - When the user explicitly cancels the current task.
+  - When the user changes subject mid-conversation and the active
+    workflow is no longer relevant.
+  - When an unrecoverable error makes continuing pointless — explain
+    in 'reason'.
+
+when_not_to_use: |
+  - Do not call when there is no active workflow — it will return an
+    error. Just call start_workflow for the new request instead.
+  - Do not call mid-step just to "free up tools"; finish the step
+    or fail it explicitly first.
+
+next_steps: |
+  - After ending, you can either call start_workflow for a new task or
+    answer the user directly from the broad catalog.
+
+parameters:
+  reason:
+    description: Short reason for ending — completed, cancelled, changed_subject, error, ...
+    why_needed: |
+      Recorded in episodic memory for debugging and future audits. A
+      structured short string is more useful than a long sentence.
+    example: completed
+
+returns:
+  ok:
+    description: Workflow ended; catalog is back to the broad noyau.
+    fields:
+      workflow: Name of the workflow that just ended.
+      reason: The reason that was passed in.
+
+  error:
+    description: Could not end — typically because nothing was active.
+    fields:
+      error: Short error code (no_active_workflow).
+      message: Human-readable explanation.

alfred/agent/tools/specs/find_media_imdb_id.yaml

@@ -0,0 +1,56 @@
+name: find_media_imdb_id
+
+summary: >
+  Search TMDB for a media title and return its canonical title, year,
+  IMDb id, and TMDB id.
+
+description: |
+  Looks up a title on TMDB and returns the canonical metadata needed by
+  the resolve_*_destination tools. On success, the result is also
+  stashed in short-term memory under "last_media_search" so later steps
+  in the workflow can read it without re-calling TMDB. The STM topic
+  is set to "searching_media".
+
+when_to_use: |
+  Right after analyze_release, before calling resolve_*_destination —
+  the resolvers need the canonical title + year and refuse to guess
+  them from the raw release name.
+
+when_not_to_use: |
+  - When you already have the IMDb id in STM from an earlier step in
+    the same workflow.
+  - For torrent search — use find_torrent instead.
+
+next_steps: |
+  - On status=ok: call the appropriate resolve_*_destination with
+    tmdb_title and tmdb_year from the result.
+  - On status=error (not_found): show the error and ask the user for
+    a more precise title.
+
+cache:
+  key: media_title
+
+parameters:
+  media_title:
+    description: Title to search for. Free-form — TMDB does the matching.
+    why_needed: |
+      Drives the TMDB query. Pass a sanitized version (no resolution
+      tokens, no group name) for best results.
+    example: Breaking Bad
+
+returns:
+  ok:
+    description: Match found.
+    fields:
+      status: "'ok'"
+      title: Canonical title as returned by TMDB.
+      year: Release year (movies) or first-air year (series).
+      media_type: "'movie' or 'tv'."
+      imdb_id: IMDb identifier (ttXXXXXXX) or null.
+      tmdb_id: TMDB numeric id.
+
+  error:
+    description: No match or API failure.
+    fields:
+      error: Short error code (not_found, api_error, ...).
+      message: Human-readable explanation.

alfred/agent/tools/specs/find_torrent.yaml

@@ -0,0 +1,52 @@
+name: find_torrent
+
+summary: >
+  Search Knaben for torrents matching a media title; cache results in
+  episodic memory.
+
+description: |
+  Queries the Knaben aggregator for up to 10 torrents matching the
+  given title, then stores the result list in episodic memory under
+  "last_search_results". The user can then refer to a torrent by
+  1-based index ("download the 3rd one") via get_torrent_by_index or
+  add_torrent_by_index. The STM topic is set to "selecting_torrent".
+
+when_to_use: |
+  When the user wants to download something new — typically the first
+  step of a "find + download" sub-task. The agent should usually
+  pre-filter the title (canonical name + year) before searching for
+  cleaner results.
+
+when_not_to_use: |
+  - For TMDB metadata lookup — use find_media_imdb_id.
+  - When a search was already performed in the same session and the
+    user is just picking from the existing list.
+
+next_steps: |
+  - Present the indexed results to the user.
+  - Once chosen: call add_torrent_by_index(N) — that wraps
+    get_torrent_by_index + add_torrent_to_qbittorrent.
+
+cache:
+  key: media_title
+
+parameters:
+  media_title:
+    description: Title to search for on Knaben. Free-form.
+    why_needed: |
+      Drives the search query. Use the canonical title (from
+      find_media_imdb_id) plus quality preferences for better hits.
+    example: Inception 2010 1080p
+
+returns:
+  ok:
+    description: Search returned a list of torrents.
+    fields:
+      status: "'ok'"
+      torrents: "List of {name, size, seeders, leechers, magnet, ...}, up to 10."
+
+  error:
+    description: Search failed.
+    fields:
+      error: Short error code.
+      message: Human-readable explanation.

alfred/agent/tools/specs/get_torrent_by_index.yaml

@@ -0,0 +1,48 @@
+name: get_torrent_by_index
+
+summary: >
+  Retrieve a torrent from the last find_torrent search by its 1-based
+  index.
+
+description: |
+  Reads episodic memory's last_search_results and returns the entry at
+  the given 1-based position. Pure lookup — does not start a download.
+  Fails when the search results are missing or the index is out of
+  range.
+
+when_to_use: |
+  When the user references a search hit by number ("show me the second
+  one") but doesn't yet want to download — e.g. inspection, sharing
+  the magnet, ...
+
+when_not_to_use: |
+  - When the user wants to start downloading: use add_torrent_by_index
+    instead (one call instead of two).
+  - When no search has been performed yet — the result will be
+    not_found.
+
+next_steps: |
+  - Display the torrent to the user.
+  - If they then say "add it", call add_torrent_to_qbittorrent with the
+    magnet, or add_torrent_by_index with the same index.
+
+parameters:
+  index:
+    description: 1-based position in the last find_torrent result list.
+    why_needed: |
+      Maps to a specific torrent entry. Out-of-range values return an
+      error, not a wraparound.
+    example: 3
+
+returns:
+  ok:
+    description: Torrent found at that index.
+    fields:
+      status: "'ok'"
+      torrent: "Full torrent dict (name, size, seeders, leechers, magnet, ...)."
+
+  error:
+    description: No torrent at that index.
+    fields:
+      error: Short error code (not_found).
+      message: Human-readable explanation, e.g. "Search for torrents first."

alfred/agent/tools/specs/learn.yaml

@@ -0,0 +1,76 @@
+name: learn
+
+summary: >
+  Teach Alfred a new token mapping and persist it to the learned
+  knowledge pack so future scans recognise it.
+
+description: |
+  Appends a new token (or list of tokens) to a key inside a knowledge
+  pack and writes the result to `data/knowledge/<pack>_learned.yaml`.
+  The change is persisted atomically (write-tmp + rename) so a crash
+  cannot corrupt the file. Currently only the `subtitles` pack is
+  supported.
+
+when_to_use: |
+  When manage_subtitles returns needs_clarification with unresolved
+  tokens, after confirming with the user what the tokens mean. Call
+  once per (category, key) — multiple values can be added in a single
+  call.
+
+when_not_to_use: |
+  - Without explicit user confirmation of what the token means.
+  - For knowledge that belongs in the static pack
+    (alfred/knowledge/<pack>.yaml) — that's editor territory, not
+    runtime learning.
+
+next_steps: |
+  - After success: re-run the workflow step that triggered the
+    clarification (typically manage_subtitles) so the new mapping is
+    applied.
+
+parameters:
+  pack:
+    description: Knowledge pack name. Currently only "subtitles" is supported.
+    why_needed: |
+      Decides which `*_learned.yaml` file under data/knowledge/ gets
+      written. The pack name is namespaced to avoid collisions across
+      domains.
+    example: subtitles
+
+  category:
+    description: Category within the pack — "languages", "types", or "formats".
+    why_needed: |
+      Different categories use different lookup tables at scan time.
+      A wrong category silently has no effect.
+    example: languages
+
+  key:
+    description: Canonical entry id — ISO 639-1 code, type name, format name.
+    why_needed: |
+      The destination bucket for the new tokens. Existing tokens under
+      this key are kept; only new values are appended.
+    example: es
+
+  values:
+    description: List of token spellings to add.
+    why_needed: |
+      Release groups use many spellings for the same language/type;
+      pass them all in one call instead of multiple round-trips.
+    example: '["spanish", "espanol", "spa"]'
+
+returns:
+  ok:
+    description: Mapping saved.
+    fields:
+      status: "'ok'"
+      pack: Name of the pack that was written to.
+      category: Category that was updated.
+      key: Key that was updated.
+      added_count: Number of values that were actually new (deduplicated).
+      tokens: Full updated token list for that key.
+
+  error:
+    description: Save failed.
+    fields:
+      error: Short error code (unknown_pack, unknown_category, read_failed, write_failed).
+      message: Human-readable explanation.

alfred/agent/tools/specs/list_folder.yaml

@@ -0,0 +1,63 @@
+name: list_folder
+
+summary: >
+  List the contents of a configured folder, optionally below a
+  relative subpath.
+
+description: |
+  Reads a folder previously configured via set_path_for_folder and
+  returns its entries (files + directories). A relative `path` lets you
+  drill down without re-specifying the absolute root each time. Path
+  traversal is rejected (no `..`, no absolute paths) so the agent
+  cannot escape the configured root.
+
+when_to_use: |
+  - At the start of an organize workflow to discover what's available
+    in the download folder.
+  - To browse a library collection ("what tv shows do I have?").
+  - As a sanity check before any move to confirm the target exists.
+
+when_not_to_use: |
+  - For folders that are not configured — call set_path_for_folder
+    first.
+  - To list arbitrary system paths — this tool is intentionally scoped
+    to the known roots.
+
+next_steps: |
+  - After listing the download folder: typically call analyze_release
+    on a specific entry.
+  - After listing a library folder: use the result to disambiguate a
+    destination during resolve_*_destination.
+
+cache:
+  key: path
+
+parameters:
+  folder_type:
+    description: Logical folder key (download, torrent, movie, tv_show, ...).
+    why_needed: |
+      Resolves to an absolute root through LTM. Must have been set via
+      set_path_for_folder beforehand.
+    example: download
+
+  path:
+    description: Relative subpath inside the root (default ".").
+    why_needed: |
+      Lets you drill into a subfolder without expanding the root. No
+      ".." or absolute path is allowed.
+    example: Breaking.Bad.S01.1080p.BluRay.x265-GROUP
+
+returns:
+  ok:
+    description: Listing returned.
+    fields:
+      status: "'ok'"
+      folder_type: The key that was listed.
+      path: The relative path that was listed.
+      entries: List of {name, type, size?} for each entry.
+
+  error:
+    description: Could not list the folder.
+    fields:
+      error: Short error code (folder_not_configured, path_not_found, path_traversal, ...).
+      message: Human-readable explanation.

alfred/agent/tools/specs/manage_subtitles.yaml

@@ -0,0 +1,67 @@
+name: manage_subtitles
+
+summary: >
+  Detect, filter, and place subtitle tracks next to a video that has just
+  been organised into the library.
+
+description: |
+  Scans the source video's surroundings for subtitle files
+  (.srt, .ass, .ssa, .vtt, .sub), classifies them by language and type
+  (standard / SDH / forced), filters by the user's SubtitlePreferences
+  (languages, min size, keep_sdh, keep_forced), and hard-links the
+  passing files next to the destination video using the convention
+  `<lang>.<ext>`, `<lang>.sdh.<ext>`, `<lang>.forced.<ext>`.
+  If no subtitles are found, returns status=ok with placed_count=0 — not
+  an error.
+
+when_to_use: |
+  Always after a successful move_media / move_to_destination, before
+  closing the workflow. Pass the original source path (where subs live)
+  and the new library path (where they should land).
+
+when_not_to_use: |
+  - Do not call before the video itself has been moved — the destination
+    must exist for hard-links to make sense.
+  - Skip when the user explicitly asks not to handle subtitles.
+
+next_steps: |
+  - On status=ok: continue with create_seed_links (if seeding) or end
+    the workflow.
+  - On status=needs_clarification: ask the user about the unresolved
+    tokens, then optionally call learn() to teach the new mapping.
+
+parameters:
+  source_video:
+    description: Absolute path to the original video file (in the download folder).
+    why_needed: |
+      Subtitles typically live next to the source, either as siblings or
+      in a Subs/ subfolder. The scanner walks from this path.
+    example: /downloads/Oz.S03.1080p.WEBRip.x265-KONTRAST/Oz.S03E01.mkv
+
+  destination_video:
+    description: Absolute path to the video file in its library location.
+    why_needed: |
+      Subtitles are hard-linked next to this file so media players pick
+      them up automatically.
+    example: /tv_shows/Oz.1997.1080p.WEBRip.x265-KONTRAST/Season 03/Oz.S03E01.mkv
+
+returns:
+  ok:
+    description: Subtitles scanned (and possibly placed).
+    fields:
+      status: "'ok'"
+      placed: List of {source, destination, filename} for each linked file.
+      placed_count: Number of subtitle files placed.
+      skipped_count: Number of subtitle files filtered out.
+
+  needs_clarification:
+    description: One or more tokens could not be classified.
+    fields:
+      unresolved: List of unrecognised tokens with their context.
+      question: Human-readable question to relay to the user.
+
+  error:
+    description: Scan or placement failed.
+    fields:
+      error: Short error code.
+      message: Human-readable explanation.

alfred/agent/tools/specs/move_media.yaml

@@ -0,0 +1,58 @@
+name: move_media
+
+summary: >
+  Safely move a media file with copy + integrity check + delete source.
+
+description: |
+  Copies the source file to the destination with an integrity check,
+  then deletes the source. Slower than move_to_destination (which is a
+  plain rename) but safer across filesystems where rename is not atomic
+  or when you want a checksum verification.
+
+when_to_use: |
+  Use to move a single file across filesystems or when paranoia about
+  data integrity is justified — e.g. moving a finished download from a
+  scratch disk to the main library array.
+
+when_not_to_use: |
+  - For same-filesystem moves where speed matters: use move_to_destination
+    (instant rename on ZFS/ext4 within the same dataset).
+  - For folder-level moves of complete packs: use move_to_destination —
+    move_media is a single-file operation.
+
+next_steps: |
+  - After a successful move: call manage_subtitles to place any subtitle
+    tracks, then create_seed_links if the user wants to keep seeding.
+  - On error: surface the error code (file_not_found, destination_exists,
+    integrity_check_failed) and ask the user how to proceed.
+
+parameters:
+  source:
+    description: Absolute path to the source video file.
+    why_needed: |
+      The file being moved. Typically lives under the downloads folder
+      after a torrent completes.
+    example: /downloads/Inception.2010.1080p.BluRay.x265-GROUP/movie.mkv
+
+  destination:
+    description: Absolute path of the destination file — must not already exist.
+    why_needed: |
+      Where the file lands in the library. Comes from a resolve_*_destination
+      call so the naming convention is respected.
+    example: /movies/Inception.2010.1080p.BluRay.x265-GROUP/Inception.2010.1080p.BluRay.x265-GROUP.mkv
+
+returns:
+  ok:
+    description: Move succeeded.
+    fields:
+      status: "'ok'"
+      source: Absolute path of the source (now gone).
+      destination: Absolute path of the destination (now in place).
+      filename: Basename of the destination file.
+      size: Size in bytes.
+
+  error:
+    description: Move failed.
+    fields:
+      error: Short error code (file_not_found, destination_exists, integrity_check_failed, ...).
+      message: Human-readable explanation.

alfred/agent/tools/specs/move_to_destination.yaml

@@ -0,0 +1,55 @@
+name: move_to_destination
+
+summary: >
+  Move a file or folder to a destination, creating parent directories as needed.
+
+description: |
+  Performs an actual move on disk. Uses the system 'mv' command, so on the
+  same filesystem (e.g. ZFS) this is an instant rename. Creates the parent
+  directory of the destination if it doesn't exist yet, then moves. Returns
+  before/after paths on success, or an error if the destination already
+  exists or the source can't be moved.
+
+when_to_use: |
+  Use after one of the resolve_*_destination tools returned status=ok, to
+  perform the move it described. The 'source' and 'destination' arguments
+  come directly from the resolved paths.
+
+when_not_to_use: |
+  - Never move when status was not 'ok' (clarification still pending or
+    error happened) — that would leave the library in a half-broken state.
+  - Don't use this for the seed-link step; use create_seed_links for that.
+
+next_steps: |
+  - After a successful move: call manage_subtitles to place any subtitle
+    tracks, then create_seed_links to keep qBittorrent seeding.
+  - On error: surface the message; do not retry blindly — check whether
+    the destination already exists or the source path is correct.
+
+parameters:
+  source:
+    description: Absolute path to the source file or folder to move.
+    why_needed: |
+      The thing being moved. Comes from the user's download folder or from
+      a previous tool's output.
+    example: /downloads/Oz.S03.1080p.WEBRip.x265-KONTRAST
+
+  destination:
+    description: Absolute path of the destination — must not already exist.
+    why_needed: |
+      Where to put the source. Comes from a resolve_*_destination call so
+      that the path matches the library's naming convention.
+    example: /tv_shows/Oz.1997.1080p.WEBRip.x265-KONTRAST/Oz.S03.1080p.WEBRip.x265-KONTRAST
+
+returns:
+  ok:
+    description: Move succeeded.
+    fields:
+      source: Absolute path of the source (now gone).
+      destination: Absolute path of the destination (now in place).
+
+  error:
+    description: Move failed.
+    fields:
+      error: Short error code (source_not_found, destination_exists, mkdir_failed, move_failed).
+      message: Human-readable explanation of what went wrong.

alfred/agent/tools/specs/probe_media.yaml

@@ -0,0 +1,56 @@
+name: probe_media
+
+summary: >
+  Run ffprobe on a single video file and return its technical details.
+
+description: |
+  Inspects a specific video file with ffprobe and returns codec,
+  resolution, duration, bitrate, the list of audio tracks (with
+  language and channel layout), and the list of embedded subtitle
+  tracks. Independent of any release-name parsing — works on any file
+  you can point at.
+
+when_to_use: |
+  - To inspect a file's audio/subtitle tracks before deciding what to
+    do (e.g. choose a default audio language).
+  - To verify a video's resolution / codec when the release name is
+    unreliable.
+  - As a building block when analyze_release is overkill.
+
+when_not_to_use: |
+  - For full release routing — analyze_release does parsing + media
+    type detection + probe in one call.
+  - On non-video files — ffprobe will return probe_failed.
+
+next_steps: |
+  - The returned info typically feeds a user-facing decision (e.g.
+    "this is 7.1 DTS, want to keep it?"); rarely chained directly to
+    another tool.
+
+cache:
+  key: source_path
+
+parameters:
+  source_path:
+    description: Absolute path to the video file to probe.
+    why_needed: |
+      ffprobe needs the exact file (not a folder). For releases use
+      analyze_release; for a known file path, pass it here.
+    example: /downloads/Inception.2010.1080p.BluRay.x265-GROUP/movie.mkv
+
+returns:
+  ok:
+    description: Probe succeeded.
+    fields:
+      status: "'ok'"
+      video: "Dict with codec, resolution, width, height, duration_seconds, bitrate_kbps."
+      audio_tracks: "List of {index, codec, channels, channel_layout, language, is_default}."
+      subtitle_tracks: "List of {index, codec, language, is_default, is_forced}."
+      audio_languages: List of language codes present in audio tracks.
+      is_multi_audio: True when more than one audio language is present.
+
+  error:
+    description: Probe failed.
+    fields:
+      error: Short error code (not_found, probe_failed).
+      message: Human-readable explanation.

alfred/agent/tools/specs/query_library.yaml

@@ -0,0 +1,54 @@
+name: query_library
+
+summary: >
+  Find release folders across all configured library roots whose name
+  contains a substring (case-insensitive).
+
+description: |
+  Scans every configured library root (movies, tv_shows, …) at depth 1
+  and returns folders whose name contains the query. For each match,
+  reports whether a `.alfred/metadata.yaml` exists — handy to spot
+  releases that have not been inspected yet. Does not recurse into
+  seasons / episodes; one entry per release folder.
+
+when_to_use: |
+  - To answer "do I already have X?" without listing whole library
+    roots one by one.
+  - To pick the release_path to feed read_release_metadata or any
+    inspector tool.
+
+when_not_to_use: |
+  - To list the *whole* library — that scan should live behind a
+    dedicated tool (not implemented yet).
+  - To browse a single root — use list_folder instead, it's cheaper
+    and doesn't open every library.
+
+next_steps: |
+  - When one match is found: feed its path to read_release_metadata or
+    analyze_release.
+  - When several match: surface the indexed list to the user and ask
+    which one they mean.
+
+parameters:
+  name:
+    description: Case-insensitive substring of the release name to look for.
+    why_needed: |
+      Library folders are named after the release (Title.Year.... or
+      Title (Year)). A substring is enough to catch typical user
+      phrasings ("foundation", "inception 2010").
+    example: foundation
+
+returns:
+  ok:
+    description: Scan completed (possibly zero matches).
+    fields:
+      status: "'ok'"
+      query: The query string as received.
+      match_count: Number of matching folders.
+      matches: "List of {collection, name, path, has_metadata}."
+
+  error:
+    description: Scan could not run.
+    fields:
+      error: Short error code (no_libraries, empty_name).
+      message: Human-readable explanation.

alfred/agent/tools/specs/read_release_metadata.yaml

@@ -0,0 +1,55 @@
+name: read_release_metadata
+
+summary: >
+  Read the `.alfred/metadata.yaml` file for a release folder.
+
+description: |
+  Returns whatever has been previously persisted by inspector tools
+  (analyze_release, probe_media, find_media_imdb_id) and by the subtitle
+  pipeline. Works for any folder — download or library — as long as the
+  release has been touched at least once. Missing metadata is not an
+  error: the tool returns `has_metadata=false` with an empty dict.
+
+when_to_use: |
+  - Before re-running analyze_release / probe_media on a release you
+    might have already seen — saves a full re-inspection.
+  - To answer "what do we know about X?" without scanning.
+  - To list which releases in a library have no `.alfred` yet (loop +
+    `has_metadata`).
+
+when_not_to_use: |
+  - To search a library by name — use query_library.
+  - When you need a fresh probe/parse — call the inspector directly,
+    the result will be persisted automatically.
+
+next_steps: |
+  - If `has_metadata=false`, decide whether to inspect now
+    (analyze_release / probe_media).
+  - If `has_metadata=true`, read `metadata.parse`, `metadata.probe`,
+    `metadata.tmdb` blocks before deciding next actions.
+
+cache:
+  key: release_path
+
+parameters:
+  release_path:
+    description: Absolute path to the release folder (or any file inside it).
+    why_needed: |
+      The store lives at `<release_root>/.alfred/metadata.yaml`. A file
+      path is auto-resolved to its parent folder.
+    example: /mnt/library/tv_shows/Foundation.2021.1080p.WEBRip.x265-RARBG
+
+returns:
+  ok:
+    description: Release inspected (file may or may not exist).
+    fields:
+      status: "'ok'"
+      release_path: Absolute path of the release folder.
+      has_metadata: True if `.alfred/metadata.yaml` exists.
+      metadata: Full content of the file, or empty dict.
+
+  error:
+    description: Path does not exist on disk.
+    fields:
+      error: Short error code (not_found).
+      message: Human-readable explanation.

alfred/agent/tools/specs/resolve_episode_destination.yaml

@@ -0,0 +1,93 @@
+name: resolve_episode_destination
+
+summary: >
+  Compute destination paths for a single TV episode file (file move).
+
+description: |
+  Resolves the target series folder, season subfolder, and full destination
+  filename for a single-episode release. Returns paths only — does not move
+  anything. If a series folder with a different name already exists, returns
+  needs_clarification.
+
+when_to_use: |
+  Use after analyze_release has identified the release as a single episode
+  (media_type=tv_show, season AND episode both set). TMDB must already be
+  queried for the canonical title/year, and optionally the episode title.
+
+when_not_to_use: |
+  - Season packs (folder containing many episodes): use resolve_season_destination.
+  - Multi-season packs: use resolve_series_destination.
+  - Movies: use resolve_movie_destination.
+
+next_steps: |
+  - On status=ok: call move_to_destination with the source video file and
+    destination=library_file.
+  - On status=needs_clarification: present question/options to the user,
+    then re-call with confirmed_folder set.
+  - On status=error: surface the message; do not move.
+
+parameters:
+  release_name:
+    description: Raw release file name (with extension).
+    why_needed: |
+      Drives extraction of quality/source/codec/group, which become part of
+      the destination filename so each file is self-describing.
+    example: Oz.S03E01.1080p.WEBRip.x265-KONTRAST.mkv
+
+  source_file:
+    description: Absolute path to the source video file on disk.
+    why_needed: |
+      Used to read the source file extension (.mkv, .mp4, .avi…) for the
+      destination filename — release names don't always carry the extension.
+    example: /downloads/Oz.S03E01.1080p.WEBRip.x265-KONTRAST/file.mkv
+
+  tmdb_title:
+    description: Canonical show title from TMDB.
+    why_needed: |
+      Title prefix for both the series folder and the destination filename;
+      ensures consistent naming across all episodes of the show.
+    example: Oz
+
+  tmdb_year:
+    description: Show start year from TMDB.
+    why_needed: |
+      Disambiguates remakes/reboots sharing a title; year is part of the
+      series folder identity.
+    example: "1997"
+
+  tmdb_episode_title:
+    description: Episode title from TMDB. Optional.
+    why_needed: |
+      When present, the destination filename embeds the episode title for
+      human-readability (e.g. Oz.S01E01.The.Routine...).
+    example: The Routine
+
+  confirmed_folder:
+    description: Folder name the user picked after needs_clarification.
+    why_needed: |
+      Forces the use case to skip detection and use this exact folder name.
+    example: Oz.1997.1080p.WEBRip.x265-KONTRAST
+
+returns:
+  ok:
+    description: Paths resolved; ready to move the episode file.
+    fields:
+      series_folder: Absolute path to the series root folder.
+      season_folder: Absolute path to the season subfolder.
+      library_file: Absolute path to the destination .mkv file (move target).
+      series_folder_name: Series folder name for display.
+      season_folder_name: Season folder name for display.
+      filename: Destination filename for display.
+      is_new_series_folder: True if the series folder doesn't exist yet.
+
+  needs_clarification:
+    description: A folder exists with a different name; user must choose.
+    fields:
+      question: Human-readable question.
+      options: List of folder names to pick from.
+
+  error:
+    description: Resolution failed.
+    fields:
+      error: Short error code.
+      message: Human-readable explanation.

alfred/agent/tools/specs/resolve_movie_destination.yaml

@@ -0,0 +1,72 @@
+name: resolve_movie_destination
+
+summary: >
+  Compute destination paths for a movie file (file move).
+
+description: |
+  Resolves the target movie folder and full destination filename for a movie
+  release. Returns paths only — does not move anything. Movies do not have
+  the existing-folder disambiguation problem that TV shows have (each
+  release lands in its own folder named after the canonical title + year +
+  tech).
+
+when_to_use: |
+  Use after analyze_release has identified the release as a movie
+  (media_type=movie). TMDB must already be queried for the canonical title
+  and release year.
+
+when_not_to_use: |
+  - TV shows in any form: use resolve_season_destination /
+    resolve_episode_destination / resolve_series_destination.
+  - Documentaries when they're treated as series rather than standalone
+    films: route them through the TV-show resolvers.
+
+next_steps: |
+  - On status=ok: call move_to_destination with the source video file and
+    destination=library_file.
+  - On status=error: surface the message; do not move.
+
+parameters:
+  release_name:
+    description: Raw release folder or file name.
+    why_needed: |
+      Drives extraction of quality/source/codec/group/edition tokens, which
+      become part of both the movie folder and filename so each release is
+      self-describing on disk.
+    example: Inception.2010.1080p.BluRay.x265-GROUP
+
+  source_file:
+    description: Absolute path to the source video file on disk.
+    why_needed: |
+      Used to read the file extension for the destination filename.
+    example: /downloads/Inception.2010.1080p.BluRay.x265-GROUP/movie.mkv
+
+  tmdb_title:
+    description: Canonical movie title from TMDB.
+    why_needed: |
+      Title prefix for the destination folder/file; ensures the library
+      uses the canonical title and not a sanitized release-name title.
+    example: Inception
+
+  tmdb_year:
+    description: Movie release year from TMDB.
+    why_needed: |
+      Disambiguates remakes that share a title (Dune 1984 vs Dune 2021)
+      and locks the folder identity in time.
+    example: "2010"
+
+returns:
+  ok:
+    description: Paths resolved; ready to move.
+    fields:
+      movie_folder: Absolute path to the movie folder.
+      library_file: Absolute path to the destination .mkv file (move target).
+      movie_folder_name: Folder name for display.
+      filename: Destination filename for display.
+      is_new_folder: True if the movie folder doesn't exist yet.
+
+  error:
+    description: Resolution failed.
+    fields:
+      error: Short error code (e.g. library_not_set).
+      message: Human-readable explanation.

alfred/agent/tools/specs/resolve_season_destination.yaml

@@ -0,0 +1,95 @@
+name: resolve_season_destination
+
+summary: >
+  Compute destination paths for a season pack (folder move) in the TV library.
+
+description: |
+  Resolves the target series folder and season subfolder for a complete-season
+  download. Returns the paths only — does not perform any move. If a series
+  folder for this show already exists in the library with a different name
+  (different group/quality/source), returns needs_clarification so the user
+  can decide whether to merge into the existing folder or create a new one.
+
+when_to_use: |
+  Use after analyze_release has identified the release as a season pack
+  (media_type=tv_show, season set, episode unset). TMDB must already be
+  queried so tmdb_title and tmdb_year are canonical values, not raw tokens
+  from the release name.
+
+when_not_to_use: |
+  - Single-episode files: use resolve_episode_destination instead.
+  - Multi-season packs (S01-S05 etc.): use resolve_series_destination.
+  - Movies: use resolve_movie_destination.
+
+next_steps: |
+  - On status=ok: call move_to_destination with source=<download folder> and
+    destination=season_folder.
+  - On status=needs_clarification: present the question and options to the
+    user, then re-call this tool with confirmed_folder set to the user's pick.
+  - On status=error: surface the message to the user; do not move anything.
+
+parameters:
+  release_name:
+    description: Raw release folder name as it appears on disk.
+    why_needed: |
+      Drives extraction of quality/source/codec/group tokens — these are
+      embedded in the target folder name (Title.Year.Quality.Source.Codec-GROUP)
+      to make releases self-describing on the filesystem.
+    example: Oz.S03.1080p.WEBRip.x265-KONTRAST
+
+  tmdb_title:
+    description: Canonical show title from TMDB.
+    why_needed: |
+      Builds the title prefix of the folder name. Must come from TMDB to
+      avoid typos and variant spellings present in the raw release name.
+    example: Oz
+
+  tmdb_year:
+    description: Show start year from TMDB.
+    why_needed: |
+      Disambiguates shows that share a title across decades (e.g. multiple
+      remakes of "The Office") and locks the folder identity.
+    example: "1997"
+
+  confirmed_folder:
+    description: |
+      Folder name chosen by the user after a previous needs_clarification
+      response.
+    why_needed: |
+      Short-circuits the existing-folder detection and forces the use case
+      to use this exact folder name, even if it doesn't match the computed
+      one.
+    example: Oz.1997.1080p.WEBRip.x265-KONTRAST
+
+  source_path:
+    description: |
+      Absolute path to the release folder on disk. Optional.
+    why_needed: |
+      When provided, the tool runs ffprobe on the main video inside the
+      folder and uses the probe data to fill quality/codec tokens that
+      may be missing from the release name. The enriched tech tokens
+      end up in the destination folder name, so providing source_path
+      gives more accurate names for releases with sparse metadata.
+    example: /downloads/Oz.S03.1080p.WEBRip.x265-KONTRAST
+
+returns:
+  ok:
+    description: Paths resolved unambiguously; ready to move.
+    fields:
+      series_folder: Absolute path to the series root folder.
+      season_folder: Absolute path to the season subfolder (move target).
+      series_folder_name: Just the series folder name, for display.
+      season_folder_name: Just the season folder name, for display.
+      is_new_series_folder: True if the series folder doesn't exist yet.
+
+  needs_clarification:
+    description: A folder already exists with a different name; ask the user.
+    fields:
+      question: Human-readable question for the user.
+      options: List of folder names the user can pick from.
+
+  error:
+    description: Resolution failed (config missing, invalid release name, etc.).
+    fields:
+      error: Short error code (e.g. library_not_set).
+      message: Human-readable explanation.

alfred/agent/tools/specs/resolve_series_destination.yaml

@@ -0,0 +1,87 @@
+name: resolve_series_destination
+
+summary: >
+  Compute the destination path for a complete multi-season series pack (folder move).
+
+description: |
+  Resolves the target series folder for a pack that contains multiple seasons
+  (e.g. S01-S05 in a single release). Returns only the series folder — the
+  whole source folder is moved as-is into the library, no per-season
+  restructuring. If a folder with a different name already exists for this
+  show, returns needs_clarification.
+
+when_to_use: |
+  Use after analyze_release has identified the release as a complete-series
+  pack (media_type=tv_complete, or multi-season indicators). TMDB must
+  already be queried for canonical title/year.
+
+when_not_to_use: |
+  - Single-season packs: use resolve_season_destination.
+  - Single episodes: use resolve_episode_destination.
+  - Movies: use resolve_movie_destination.
+
+next_steps: |
+  - On status=ok: call move_to_destination with source=<download folder> and
+    destination=series_folder.
+  - On status=needs_clarification: ask the user, re-call with
+    confirmed_folder set.
+  - On status=error: surface the message; do not move.
+
+parameters:
+  release_name:
+    description: Raw release folder name as it appears on disk.
+    why_needed: |
+      Drives extraction of quality/source/codec/group tokens for the target
+      folder name, even though the multi-season structure inside is kept
+      as-is.
+    example: The.Wire.S01-S05.1080p.BluRay.x265-GROUP
+
+  tmdb_title:
+    description: Canonical show title from TMDB.
+    why_needed: |
+      Title prefix of the series folder; comes from TMDB to avoid raw
+      release-name spellings.
+    example: The Wire
+
+  tmdb_year:
+    description: Show start year from TMDB.
+    why_needed: |
+      Disambiguates shows that share a title across eras and locks the
+      folder identity.
+    example: "2002"
+
+  confirmed_folder:
+    description: Folder name chosen by the user after needs_clarification.
+    why_needed: |
+      Forces the use case to use this exact folder name and skip detection.
+    example: The.Wire.2002.1080p.BluRay.x265-GROUP
+
+  source_path:
+    description: |
+      Absolute path to the release folder on disk. Optional.
+    why_needed: |
+      When provided, the tool runs ffprobe on the main video inside the
+      folder and uses probe data to fill quality/codec tokens that may
+      be missing from the release name, producing a more accurate
+      destination folder name.
+    example: /downloads/The.Wire.S01-S05.1080p.BluRay.x265-GROUP
+
+returns:
+  ok:
+    description: Path resolved; ready to move the pack.
+    fields:
+      series_folder: Absolute path to the destination series folder.
+      series_folder_name: Folder name for display.
+      is_new_series_folder: True if the folder doesn't exist yet.
+
+  needs_clarification:
+    description: A folder exists with a different name; ask the user.
+    fields:
+      question: Human-readable question.
+      options: List of folder names to pick from.
+
+  error:
+    description: Resolution failed.
+    fields:
+      error: Short error code.
+      message: Human-readable explanation.

alfred/agent/tools/specs/set_language.yaml

@@ -0,0 +1,47 @@
+name: set_language
+
+summary: >
+  Set the conversation language so all subsequent assistant messages
+  match it.
+
+description: |
+  Persists an ISO 639-1 language code in short-term memory under
+  conversation.language. Read by the prompt builder and any tool that
+  needs to localise output. Does not validate the code against an ISO
+  list — the LLM is trusted to pass a sensible value.
+
+when_to_use: |
+  As the very first call when the user writes in a language different
+  from the current STM language. Doing it before answering avoids a
+  mid-reply switch.
+
+when_not_to_use: |
+  - On every turn — only when the language actually changes.
+  - To pick a subtitle language — that lives in SubtitlePreferences,
+    not the conversation language.
+
+next_steps: |
+  - After success: continue the user's request in the newly set
+    language.
+
+parameters:
+  language:
+    description: ISO 639-1 language code (en, fr, es, de, ...).
+    why_needed: |
+      Identifies the target language unambiguously across the UI and
+      any localisation logic.
+    example: fr
+
+returns:
+  ok:
+    description: Language saved.
+    fields:
+      status: "'ok'"
+      message: Confirmation message.
+      language: The language code that was saved.
+
+  error:
+    description: Could not save the language.
+    fields:
+      status: "'error'"
+      error: Short error code or exception message.

alfred/agent/tools/specs/set_path_for_folder.yaml

@@ -0,0 +1,58 @@
+name: set_path_for_folder
+
+summary: >
+  Configure where a known folder lives on disk (download, torrent, or
+  any library collection).
+
+description: |
+  Stores an absolute path in long-term memory under a folder key. Two
+  classes of folders exist:
+    - Workspace paths: "download", "torrent" — single-valued each, used
+      by the organize workflows.
+    - Library paths: any other key (e.g. "movie", "tv_show",
+      "documentary") — these are the collections you organise into.
+  The path must exist and be a directory; otherwise the call fails
+  without changing memory.
+
+when_to_use: |
+  On first run, or when the user moves a folder, or when introducing a
+  new library collection (e.g. "set the documentaries folder to ...").
+
+when_not_to_use: |
+  - For one-off listings — list_folder works without configuration only
+    if the folder is already set.
+  - To rename or delete an existing folder — this only sets paths.
+
+next_steps: |
+  - After success: typical follow-ups are list_folder on the same key,
+    or starting a workflow that needs the path.
+
+parameters:
+  folder_name:
+    description: Logical name of the folder (download, torrent, movie, tv_show, ...).
+    why_needed: |
+      The key the agent uses everywhere afterwards. "download" and
+      "torrent" are reserved for workspace; anything else becomes a
+      library collection.
+    example: tv_show
+
+  path_value:
+    description: Absolute path to the folder on disk.
+    why_needed: |
+      Must exist and be readable. Stored verbatim in LTM — relative
+      paths are rejected.
+    example: /tank/library/tv_shows
+
+returns:
+  ok:
+    description: Path saved to long-term memory.
+    fields:
+      status: "'ok'"
+      folder_name: The logical name that was set.
+      path_value: The absolute path that was saved.
+
+  error:
+    description: Could not set the path.
+    fields:
+      error: Short error code (path_not_found, not_a_directory, invalid_path, ...).
+      message: Human-readable explanation.

alfred/agent/tools/specs/start_workflow.yaml

@@ -0,0 +1,64 @@
+name: start_workflow
+
+summary: >
+  Enter a workflow scope — narrows the visible tool catalog and gives the
+  agent a clear multi-step plan to follow.
+
+description: |
+  Activates a named workflow defined in YAML under agent/workflows/.
+  Once active, only the workflow's declared tools (plus the core noyau)
+  are exposed to the LLM, which keeps the decision space small and
+  focused. The returned plan (description + steps) is the script the
+  agent should execute until end_workflow is called.
+
+when_to_use: |
+  Use as the very first action whenever the user request maps to a
+  known workflow (e.g. "organize Breaking Bad" → media.organize_media).
+  Pass any parameters you already know (release name, target media,
+  flags) in 'params' so later steps can read them from STM.
+
+when_not_to_use: |
+  - Do not start a workflow for purely conversational replies or
+    one-shot lookups that need a single tool call.
+  - Do not start a new workflow while one is already active — call
+    end_workflow first.
+
+next_steps: |
+  - On status=ok: follow the returned 'steps' list, calling the tools
+    in order. The visible tool catalog has already been narrowed.
+  - On status=error (unknown_workflow): surface the available list to
+    the user and ask which one they meant.
+  - On status=error (workflow_already_active): either continue the
+    active workflow or call end_workflow first.
+
+parameters:
+  workflow_name:
+    description: Fully-qualified name of the workflow to start (e.g. media.organize_media).
+    why_needed: |
+      Identifies which YAML definition to load. Names use the
+      'domain.action' convention (media.*, mail.*, ...).
+    example: media.organize_media
+
+  params:
+    description: Initial parameters to seed the workflow with (release name, target, flags).
+    why_needed: |
+      Later steps read these from STM instead of asking the user again.
+      Pass whatever you already extracted from the user's message.
+    example: '{"release_name": "Breaking.Bad.S01.1080p.BluRay.x265-GROUP", "keep_seeding": true}'
+
+returns:
+  ok:
+    description: Workflow activated; catalog has been narrowed.
+    fields:
+      workflow: Name of the activated workflow.
+      description: Human-readable description of what the workflow does.
+      steps: Ordered list of steps to execute.
+      tools: Tools that are now visible (in addition to the core noyau).
+
+  error:
+    description: Could not activate the workflow.
+    fields:
+      error: Short error code (unknown_workflow, workflow_already_active).
+      message: Human-readable explanation.
+      available_workflows: List of valid workflow names (only on unknown_workflow).
+      active_workflow: Name of the currently active workflow (only on workflow_already_active).

alfred/agent/tools/workflow.py

@@ -0,0 +1,86 @@
+"""Workflow scoping tools — start_workflow / end_workflow meta-tools.
+
+These tools let the agent enter and leave a workflow scope. While a
+workflow is active, the PromptBuilder narrows the visible tool catalog
+to the noyau + the workflow's declared tools, so the LLM doesn't have
+to reason over the full set.
+"""
+
+import logging
+from typing import Any
+
+from alfred.infrastructure.persistence import get_memory
+
+from ..workflows import WorkflowLoader
+
+logger = logging.getLogger(__name__)
+
+_loader_cache: list[WorkflowLoader] = []
+
+
+def _get_loader() -> WorkflowLoader:
+    """Lazily build the module-level WorkflowLoader."""
+    if not _loader_cache:
+        _loader_cache.append(WorkflowLoader())
+    return _loader_cache[0]
+
+
+def start_workflow(workflow_name: str, params: dict) -> dict[str, Any]:
+    """See specs/start_workflow.yaml for full description."""
+    loader = _get_loader()
+    workflow = loader.get(workflow_name)
+    if workflow is None:
+        return {
+            "status": "error",
+            "error": "unknown_workflow",
+            "message": f"Workflow '{workflow_name}' not found",
+            "available_workflows": loader.names(),
+        }
+
+    memory = get_memory()
+    current = memory.stm.workflow.current
+    if current is not None:
+        return {
+            "status": "error",
+            "error": "workflow_already_active",
+            "message": (
+                f"Workflow '{current.get('name')}' is already active. "
+                "Call end_workflow before starting a new one."
+            ),
+            "active_workflow": current.get("name"),
+        }
+
+    memory.stm.start_workflow(workflow_name, params or {})
+    memory.save()
+    logger.info(f"start_workflow: '{workflow_name}' with params={params}")
+
+    return {
+        "status": "ok",
+        "workflow": workflow_name,
+        "description": workflow.get("description", ""),
+        "steps": workflow.get("steps", []),
+        "tools": workflow.get("tools", []),
+    }
+
+
+def end_workflow(reason: str) -> dict[str, Any]:
+    """See specs/end_workflow.yaml for full description."""
+    memory = get_memory()
+    current = memory.stm.workflow.current
+    if current is None:
+        return {
+            "status": "error",
+            "error": "no_active_workflow",
+            "message": "No workflow is currently active.",
+        }
+
+    workflow_name = current.get("name")
+    memory.stm.end_workflow()
+    memory.save()
+    logger.info(f"end_workflow: '{workflow_name}' reason={reason!r}")
+
+    return {
+        "status": "ok",
+        "workflow": workflow_name,
+        "reason": reason,
+    }

alfred/agent/workflows/__init__.py

@@ -0,0 +1,3 @@
+from .loader import WorkflowLoader
+
+__all__ = ["WorkflowLoader"]

alfred/agent/workflows/loader.py

@@ -0,0 +1,52 @@
+"""WorkflowLoader — autodiscovers and loads workflow YAML files.
+
+Scans the workflows/ directory for all .yaml files and exposes them
+as dicts. No manual registration needed — drop a new .yaml file and
+it will be picked up automatically.
+"""
+
+import logging
+from pathlib import Path
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+_WORKFLOWS_DIR = Path(__file__).parent
+
+
+class WorkflowLoader:
+    """
+    Loads all workflow definitions from the workflows/ directory.
+
+    Usage:
+        loader = WorkflowLoader()
+        all_workflows = loader.all()
+        workflow = loader.get("media.organize_media")
+    """
+
+    def __init__(self):
+        self._workflows: dict[str, dict] = {}
+        self._load()
+
+    def _load(self) -> None:
+        for path in sorted(_WORKFLOWS_DIR.glob("*.yaml")):
+            try:
+                data = yaml.safe_load(path.read_text(encoding="utf-8"))
+                name = data.get("name") or path.stem
+                self._workflows[name] = data
+                logger.info(f"WorkflowLoader: Loaded '{name}' from {path.name}")
+            except Exception as e:
+                logger.warning(f"WorkflowLoader: Could not load {path.name}: {e}")
+
+    def all(self) -> dict[str, dict]:
+        """Return all loaded workflows keyed by name."""
+        return self._workflows
+
+    def get(self, name: str) -> dict | None:
+        """Return a specific workflow by name, or None if not found."""
+        return self._workflows.get(name)
+
+    def names(self) -> list[str]:
+        """Return all available workflow names."""
+        return list(self._workflows.keys())

alfred/agent/workflows/media.manage_subtitles.yaml

@@ -0,0 +1,69 @@
+name: media.manage_subtitles
+description: >
+  Place subtitle files alongside a video that has just been organised into the library.
+  Detects the release pattern automatically, identifies and classifies all tracks,
+  filters by user rules, and hard-links matching files to the destination.
+  If any tracks are unrecognised, asks the user and optionally teaches Alfred.
+
+trigger:
+  examples:
+    - "handle subtitles for The X-Files S01E01"
+    - "place the subs next to the file"
+    - "subtitles are in the Subs/ folder"
+    - "add subtitles"
+
+tools:
+  - manage_subtitles
+  - learn
+
+memory:
+  SubtitlePreferences: read
+  Workflow: read-write
+
+steps:
+  - id: place_subtitles
+    tool: manage_subtitles
+    description: >
+      Detect release pattern, identify and classify all subtitle tracks,
+      filter by rules, hard-link matching files next to the destination video.
+      Reads SubtitlePreferences from LTM for language/type/format filtering.
+    params:
+      source_video: "{source_video}"
+      destination_video: "{destination_video}"
+      imdb_id: "{imdb_id}"
+      media_type: "{media_type}"
+      release_group: "{release_group}"
+      season: "{season}"
+      episode: "{episode}"
+    on_result:
+      ok_placed_zero: skip               # no subtitles found — not an error
+      needs_clarification: ask_user      # unrecognised tokens found
+
+  - id: ask_user
+    description: >
+      Some tracks could not be classified. Show the user the unresolved tokens
+      and ask if they want to teach Alfred what they mean.
+      If yes → go to learn_tokens. If no → end workflow.
+    ask_user:
+      question: >
+        I could not identify some tokens in the subtitle files: {unresolved}.
+        Do you want to teach me what they mean?
+      answers:
+        yes: { next_step: learn_tokens }
+        no:  { next_step: end }
+
+  - id: learn_tokens
+    tool: learn
+    description: >
+      Persist a new token mapping to the learned knowledge pack so Alfred
+      recognises it in future scans without asking again.
+    params:
+      pack: "subtitles"
+      category: "{token_category}"   # "languages" or "types"
+      key: "{token_key}"             # e.g. "es", "de"
+      values: "{token_values}"       # e.g. ["spanish", "espanol"]
+
+subtitle_naming:
+  standard:  "{lang}.{ext}"
+  sdh:       "{lang}.sdh.{ext}"
+  forced:    "{lang}.forced.{ext}"

alfred/agent/workflows/media.organize_media.yaml

@@ -0,0 +1,92 @@
+name: media.organize_media
+description: >
+  Organise a downloaded series or movie into the media library.
+  Triggered when the user asks to move/organize a specific title.
+  Always moves the video file. Optionally creates seed links in the
+  torrents folder so qBittorrent can keep seeding.
+
+trigger:
+  examples:
+    - "organize Breaking Bad"
+    - "organise Severance season 2"
+    - "move Inception to my library"
+    - "organize Breaking Bad season 1, keep seeding"
+
+tools:
+  - list_folder
+  - analyze_release
+  - probe_media
+  - find_media_imdb_id
+  - resolve_season_destination
+  - resolve_episode_destination
+  - resolve_movie_destination
+  - resolve_series_destination
+  - move_to_destination
+  - manage_subtitles
+  - create_seed_links
+
+memory:
+  WorkspacePaths: read
+  LibraryPaths: read
+  Library: read-write
+  Workflow: read-write
+  Entities: read-write
+
+steps:
+  - id: list_downloads
+    tool: list_folder
+    description: List the download folder to find the target files.
+    params:
+      folder_type: download
+
+  - id: analyze
+    tool: analyze_release
+    description: >
+      Parse the release name to detect media_type (movie / tv_season /
+      tv_episode / tv_complete) and extract season/episode info.
+
+  - id: identify_media
+    tool: find_media_imdb_id
+    description: Confirm canonical title and year via TMDB.
+
+  - id: resolve_destination
+    description: >
+      Call the resolver that matches media_type from analyze_release:
+        movie       → resolve_movie_destination
+        tv_season   → resolve_season_destination
+        tv_episode  → resolve_episode_destination
+        tv_complete → resolve_series_destination
+      If the resolver returns needs_clarification, ask the user and
+      re-call with confirmed_folder.
+
+  - id: move_file
+    tool: move_to_destination
+    description: >
+      Move the video file/folder to the destination returned by the
+      resolver above.
+
+  - id: handle_subtitles
+    tool: manage_subtitles
+    description: >
+      Place subtitle files alongside the video in the library.
+      Pass the original source path and the new library destination path.
+    on_missing: skip
+
+  - id: ask_seeding
+    ask_user:
+      question: "Do you want to keep seeding this torrent?"
+      answers:
+        "yes": { next_step: create_seed_links }
+        "no":  { next_step: end }
+
+  - id: create_seed_links
+    tool: create_seed_links
+    description: >
+      Hard-link the library video file back into torrents/<original_folder>/
+      and copy all remaining files from the original download folder
+      (subs, nfo, jpg, …) so the torrent stays complete for seeding.
+
+naming_convention:
+  # Resolved by domain entities (Movie, Episode) — not hardcoded here
+  tv_show: "{title}/Season {season:02d}/{title}.S{season:02d}E{episode:02d}.{ext}"
+  movie: "{title} ({year})/{title}.{year}.{ext}"

alfred/app.py

@@ -29,7 +29,7 @@ app = FastAPI(
     version="0.2.0",
 )
 
-memory_path = Path(settings.data_storage) / "memory"
+memory_path = Path(settings.data_storage_dir) / "memory"
 init_memory(storage_dir=str(memory_path))
 logger.info(f"Memory context initialized (path: {memory_path})")
 
@@ -37,6 +37,21 @@ logger.info(f"Memory context initialized (path: {memory_path})")
 llm_provider = settings.default_llm_provider.lower()
 
 
+class _UnconfiguredLLM:
+    """Placeholder LLM used when no provider could be configured at import time.
+
+    Importing the FastAPI app must not fail just because credentials are
+    absent (e.g. during test collection). Any actual call surfaces a clear
+    503 error at request time via the handlers below.
+    """
+
+    def __init__(self, reason: str):
+        self.reason = reason
+
+    def complete(self, *args, **kwargs):
+        raise LLMAPIError(f"LLM is not configured: {self.reason}")
+
+
 try:
     if llm_provider == "local":
         logger.info("Using local Ollama LLM")
@@ -49,8 +64,11 @@ try:
     else:
         raise ValueError(f"Unknown LLM provider: {llm_provider}")
 except LLMConfigurationError as e:
+    # Degrade gracefully: keep the app importable so tests can patch agent.step
+    # and so missing credentials surface as a 503 at the endpoint, not as an
+    # import error.
     logger.error(f"Failed to initialize LLM: {e}")
-    raise
+    llm = _UnconfiguredLLM(str(e))
 
 # Initialize agent
 agent = Agent(

alfred/application/filesystem/__init__.py

@@ -1,12 +1,47 @@
 """Filesystem use cases."""
 
-from .dto import ListFolderResponse, SetFolderPathResponse
+from .create_seed_links import CreateSeedLinksUseCase
+from .dto import (
+    CreateSeedLinksResponse,
+    ListFolderResponse,
+    ManageSubtitlesResponse,
+    MoveMediaResponse,
+    PlacedSubtitle,
+    SetFolderPathResponse,
+)
 from .list_folder import ListFolderUseCase
+from .manage_subtitles import ManageSubtitlesUseCase
+from .move_media import MoveMediaUseCase
+from .resolve_destination import (
+    ResolvedEpisodeDestination,
+    ResolvedMovieDestination,
+    ResolvedSeasonDestination,
+    ResolvedSeriesDestination,
+    resolve_episode_destination,
+    resolve_movie_destination,
+    resolve_season_destination,
+    resolve_series_destination,
+)
 from .set_folder_path import SetFolderPathUseCase
 
 __all__ = [
     "SetFolderPathUseCase",
     "ListFolderUseCase",
+    "CreateSeedLinksUseCase",
+    "MoveMediaUseCase",
+    "ManageSubtitlesUseCase",
+    "ResolvedSeasonDestination",
+    "ResolvedEpisodeDestination",
+    "ResolvedMovieDestination",
+    "ResolvedSeriesDestination",
+    "resolve_season_destination",
+    "resolve_episode_destination",
+    "resolve_movie_destination",
+    "resolve_series_destination",
     "SetFolderPathResponse",
     "ListFolderResponse",
+    "CreateSeedLinksResponse",
+    "MoveMediaResponse",
+    "ManageSubtitlesResponse",
+    "PlacedSubtitle",
 ]

alfred/application/filesystem/create_seed_links.py

@@ -0,0 +1,54 @@
+"""CreateSeedLinksUseCase — prepares a torrent folder for continued seeding."""
+
+import logging
+
+from alfred.infrastructure.filesystem import FileManager
+from alfred.infrastructure.persistence import get_memory
+
+from .dto import CreateSeedLinksResponse
+
+logger = logging.getLogger(__name__)
+
+
+class CreateSeedLinksUseCase:
+    """
+    Prepares a torrent subfolder so qBittorrent can keep seeding after a move.
+
+    Hard-links the video file from the library back into torrents/<original_folder>/,
+    then copies all remaining files from the original download folder (subs, nfo, …).
+    """
+
+    def __init__(self, file_manager: FileManager):
+        self.file_manager = file_manager
+
+    def execute(
+        self, library_file: str, original_download_folder: str
+    ) -> CreateSeedLinksResponse:
+        memory = get_memory()
+        torrent_folder = memory.ltm.workspace.torrent
+
+        if not torrent_folder:
+            return CreateSeedLinksResponse(
+                status="error",
+                error="torrent_folder_not_set",
+                message="Torrent folder is not configured. Use set_path_for_folder to set it.",
+            )
+
+        result = self.file_manager.create_seed_links(
+            library_file, original_download_folder, torrent_folder
+        )
+
+        if result.get("status") == "ok":
+            return CreateSeedLinksResponse(
+                status="ok",
+                torrent_subfolder=result.get("torrent_subfolder"),
+                linked_file=result.get("linked_file"),
+                copied_files=result.get("copied_files"),
+                copied_count=result.get("copied_count", 0),
+                skipped=result.get("skipped"),
+            )
+        return CreateSeedLinksResponse(
+            status="error",
+            error=result.get("error"),
+            message=result.get("message"),
+        )

alfred/application/filesystem/dto.py

@@ -1,8 +1,58 @@
 """Filesystem application DTOs."""
 
+from __future__ import annotations
+
 from dataclasses import dataclass
 
 
+@dataclass
+class CopyMediaResponse:
+    """Response from copying a media file."""
+
+    status: str
+    source: str | None = None
+    destination: str | None = None
+    filename: str | None = None
+    size: int | None = None
+    error: str | None = None
+    message: str | None = None
+
+    def to_dict(self) -> dict:
+        if self.error:
+            return {"status": self.status, "error": self.error, "message": self.message}
+        return {
+            "status": self.status,
+            "source": self.source,
+            "destination": self.destination,
+            "filename": self.filename,
+            "size": self.size,
+        }
+
+
+@dataclass
+class MoveMediaResponse:
+    """Response from moving a media file."""
+
+    status: str
+    source: str | None = None
+    destination: str | None = None
+    filename: str | None = None
+    size: int | None = None
+    error: str | None = None
+    message: str | None = None
+
+    def to_dict(self) -> dict:
+        if self.error:
+            return {"status": self.status, "error": self.error, "message": self.message}
+        return {
+            "status": self.status,
+            "source": self.source,
+            "destination": self.destination,
+            "filename": self.filename,
+            "size": self.size,
+        }
+
+
 @dataclass
 class SetFolderPathResponse:
     """Response from setting a folder path."""
@@ -29,6 +79,108 @@ class SetFolderPathResponse:
         return result
 
 
+@dataclass
+class PlacedSubtitle:
+    """One subtitle file successfully placed."""
+
+    source: str
+    destination: str
+    filename: str
+
+    def to_dict(self) -> dict:
+        return {
+            "source": self.source,
+            "destination": self.destination,
+            "filename": self.filename,
+        }
+
+
+@dataclass
+class UnresolvedTrack:
+    """A subtitle track that needs agent clarification before placement."""
+
+    raw_tokens: list[str]
+    file_path: str | None = None
+    file_size_kb: float | None = None
+    reason: str = ""  # "unknown_language" | "low_confidence"
+
+    def to_dict(self) -> dict:
+        return {
+            "raw_tokens": self.raw_tokens,
+            "file_path": self.file_path,
+            "file_size_kb": self.file_size_kb,
+            "reason": self.reason,
+        }
+
+
+@dataclass
+class AvailableSubtitle:
+    """One subtitle track available on an embedded media item."""
+
+    language: str  # ISO 639-2 code
+    subtitle_type: str  # "standard" | "sdh" | "forced" | "unknown"
+
+    def to_dict(self) -> dict:
+        return {"language": self.language, "type": self.subtitle_type}
+
+
+@dataclass
+class ManageSubtitlesResponse:
+    """Response from the manage_subtitles use case."""
+
+    status: str  # "ok" | "needs_clarification" | "error"
+    video_path: str | None = None
+    placed: list[PlacedSubtitle] | None = None
+    skipped_count: int = 0
+    unresolved: list[UnresolvedTrack] | None = None
+    available: list[AvailableSubtitle] | None = None  # embedded tracks summary
+    error: str | None = None
+    message: str | None = None
+
+    def to_dict(self) -> dict:
+        if self.error:
+            return {"status": self.status, "error": self.error, "message": self.message}
+        result = {
+            "status": self.status,
+            "video_path": self.video_path,
+            "placed": [p.to_dict() for p in (self.placed or [])],
+            "placed_count": len(self.placed or []),
+            "skipped_count": self.skipped_count,
+        }
+        if self.unresolved:
+            result["unresolved"] = [u.to_dict() for u in self.unresolved]
+            result["unresolved_count"] = len(self.unresolved)
+        if self.available:
+            result["available"] = [a.to_dict() for a in self.available]
+        return result
+
+
+@dataclass
+class CreateSeedLinksResponse:
+    """Response from creating seed links for a torrent."""
+
+    status: str
+    torrent_subfolder: str | None = None
+    linked_file: str | None = None
+    copied_files: list[str] | None = None
+    copied_count: int = 0
+    skipped: list[str] | None = None
+    error: str | None = None
+    message: str | None = None
+
+    def to_dict(self) -> dict:
+        if self.error:
+            return {"status": self.status, "error": self.error, "message": self.message}
+        return {
+            "status": self.status,
+            "torrent_subfolder": self.torrent_subfolder,
+            "linked_file": self.linked_file,
+            "copied_files": self.copied_files or [],
+            "copied_count": self.copied_count,
+            "skipped": self.skipped or [],
+        }
+
+
 @dataclass
 class ListFolderResponse:
     """Response from listing a folder."""

alfred/application/filesystem/manage_subtitles.py

@@ -0,0 +1,308 @@
+"""ManageSubtitlesUseCase — orchestrates the full subtitle pipeline for a video file."""
+
+import logging
+from pathlib import Path
+
+from alfred.domain.shared.value_objects import ImdbId
+from alfred.domain.subtitles.entities import SubtitleScanResult
+from alfred.domain.subtitles.services.identifier import SubtitleIdentifier
+from alfred.domain.subtitles.services.matcher import SubtitleMatcher
+from alfred.domain.subtitles.services.pattern_detector import PatternDetector
+from alfred.application.subtitles.placer import (
+    PlacedTrack,
+    SubtitlePlacer,
+    _build_dest_name,
+)
+from alfred.domain.subtitles.services.utils import available_subtitles
+from alfred.domain.subtitles.value_objects import ScanStrategy
+from alfred.infrastructure.filesystem.scanner import PathlibFilesystemScanner
+from alfred.infrastructure.knowledge.subtitles.base import SubtitleKnowledgeBase
+from alfred.infrastructure.knowledge.subtitles.loader import KnowledgeLoader
+from alfred.infrastructure.persistence.context import get_memory
+from alfred.infrastructure.probe.ffprobe_prober import FfprobeMediaProber
+from alfred.infrastructure.subtitle.metadata_store import SubtitleMetadataStore
+from alfred.infrastructure.subtitle.rule_repository import RuleSetRepository
+
+from .dto import (
+    AvailableSubtitle,
+    ManageSubtitlesResponse,
+    PlacedSubtitle,
+    UnresolvedTrack,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _infer_library_root(dest_video: Path, media_type: str) -> Path:
+    """
+    Infer the media library root folder from the destination video path.
+
+    TV show:  video → Season 01 → The X-Files   (3 levels up)
+    Movie:    video → Inception (2010)           (1 level up)
+    """
+    if media_type == "tv_show":
+        return dest_video.parent.parent
+    return dest_video.parent
+
+
+def _to_imdb_id(raw: str | None) -> ImdbId | None:
+    if not raw:
+        return None
+    try:
+        return ImdbId(raw)
+    except Exception:
+        return None
+
+
+class ManageSubtitlesUseCase:
+    """
+    Full subtitle pipeline:
+
+    1. Load knowledge base
+    2. Detect (or confirm) the release pattern
+    3. Identify all tracks (ffprobe + filesystem scan)
+    4. Load + resolve rules for this media
+    5. Match tracks against rules
+    6. If any tracks are unresolved → return needs_clarification (don't place yet)
+    7. Place matched tracks via hard-link
+    8. Persist to .alfred/metadata.yaml
+
+    The use case is stateless — all dependencies are instantiated inline.
+    """
+
+    def execute(
+        self,
+        source_video: str,
+        destination_video: str,
+        imdb_id: str | None = None,
+        media_type: str = "tv_show",
+        release_group: str | None = None,
+        season: int | None = None,
+        episode: int | None = None,
+        confirmed_pattern_id: str | None = None,
+        dry_run: bool = False,
+    ) -> ManageSubtitlesResponse:
+        source_path = Path(source_video)
+        dest_path = Path(destination_video)
+
+        if not source_path.exists() and not source_path.parent.exists():
+            return ManageSubtitlesResponse(
+                status="error",
+                error="source_not_found",
+                message=f"Source video not found: {source_video}",
+            )
+
+        kb = SubtitleKnowledgeBase(KnowledgeLoader())
+        prober = FfprobeMediaProber()
+        scanner = PathlibFilesystemScanner()
+        library_root = _infer_library_root(dest_path, media_type)
+        store = SubtitleMetadataStore(library_root)
+        repo = RuleSetRepository(library_root)
+
+        # --- Pattern resolution ---
+        pattern = self._resolve_pattern(
+            kb,
+            prober,
+            scanner,
+            store,
+            source_path,
+            confirmed_pattern_id,
+            release_group,
+        )
+        if pattern is None:
+            return ManageSubtitlesResponse(
+                status="error",
+                error="pattern_not_found",
+                message="Could not determine subtitle pattern for this release.",
+            )
+
+        # --- Identify ---
+        media_id = _to_imdb_id(imdb_id)
+        identifier = SubtitleIdentifier(kb, prober, scanner)
+        metadata = identifier.identify(
+            video_path=source_path,
+            pattern=pattern,
+            media_id=media_id,
+            media_type=media_type,
+            release_group=release_group,
+        )
+
+        if metadata.total_count == 0:
+            logger.info(
+                f"ManageSubtitles: no subtitle tracks found for {source_path.name}"
+            )
+            return ManageSubtitlesResponse(
+                status="ok",
+                video_path=destination_video,
+                placed=[],
+                skipped_count=0,
+            )
+
+        # --- Embedded short-circuit ---
+        if pattern.scan_strategy == ScanStrategy.EMBEDDED:
+            logger.info("ManageSubtitles: embedded pattern — skipping matcher")
+            available = [
+                AvailableSubtitle(
+                    language=t.language.code if t.language else "?",
+                    subtitle_type=t.subtitle_type.value,
+                )
+                for t in available_subtitles(metadata.embedded_tracks)
+            ]
+            return ManageSubtitlesResponse(
+                status="ok",
+                video_path=destination_video,
+                placed=[],
+                skipped_count=0,
+                available=available,
+            )
+
+        # --- Match (external only) ---
+        subtitle_prefs = None
+        try:
+            memory = get_memory()
+            subtitle_prefs = memory.ltm.subtitle_preferences
+        except Exception:
+            pass
+        rules = repo.load(release_group, subtitle_prefs).resolve(kb.default_rules())
+        matcher = SubtitleMatcher()
+        matched, unresolved = matcher.match(metadata.external_tracks, rules)
+
+        if unresolved:
+            logger.info(
+                f"ManageSubtitles: {len(unresolved)} unresolved track(s) — needs clarification"
+            )
+            return ManageSubtitlesResponse(
+                status="needs_clarification",
+                video_path=destination_video,
+                placed=[],
+                unresolved=[_to_unresolved_dto(t) for t in unresolved],
+            )
+
+        if not matched:
+            return ManageSubtitlesResponse(
+                status="ok",
+                video_path=destination_video,
+                placed=[],
+                skipped_count=metadata.total_count,
+            )
+
+        # --- Dry run: skip placement ---
+        if dry_run:
+            placed_dtos = []
+            for t in matched:
+                if not t.file_path:
+                    continue
+                try:
+                    filename = _build_dest_name(t, dest_path.stem)
+                except ValueError:
+                    continue
+                placed_dtos.append(
+                    PlacedSubtitle(
+                        source=str(t.file_path),
+                        destination=str(dest_path.parent / filename),
+                        filename=filename,
+                    )
+                )
+            return ManageSubtitlesResponse(
+                status="ok",
+                video_path=destination_video,
+                placed=placed_dtos,
+                skipped_count=0,
+            )
+
+        # --- Place ---
+        placer = SubtitlePlacer()
+        place_result = placer.place(matched, dest_path)
+
+        # --- Persist ---
+        if place_result.placed:
+            pairs = _pair_placed_with_tracks(place_result.placed, matched)
+            store.append_history(pairs, season, episode, release_group)
+
+        placed_dtos = [
+            PlacedSubtitle(
+                source=str(p.source),
+                destination=str(p.destination),
+                filename=p.filename,
+            )
+            for p in place_result.placed
+        ]
+
+        return ManageSubtitlesResponse(
+            status="ok",
+            video_path=destination_video,
+            placed=placed_dtos,
+            skipped_count=place_result.skipped_count,
+        )
+
+    def _resolve_pattern(
+        self,
+        kb: SubtitleKnowledgeBase,
+        prober: FfprobeMediaProber,
+        scanner: PathlibFilesystemScanner,
+        store: SubtitleMetadataStore,
+        source_path: Path,
+        confirmed_pattern_id: str | None,
+        release_group: str | None,
+    ):
+        # 1. Explicit override from caller
+        if confirmed_pattern_id:
+            p = kb.pattern(confirmed_pattern_id)
+            if p:
+                return p
+            logger.warning(f"ManageSubtitles: unknown pattern '{confirmed_pattern_id}'")
+
+        # 2. Previously confirmed in metadata store
+        stored_id = store.confirmed_pattern()
+        if stored_id:
+            p = kb.pattern(stored_id)
+            if p:
+                logger.debug(f"ManageSubtitles: using confirmed pattern '{stored_id}'")
+                return p
+
+        # 3. Auto-detect
+        release_root = source_path.parent
+        detector = PatternDetector(kb, prober, scanner)
+        result = detector.detect(release_root, source_path)
+
+        if result["detected"] and result["confidence"] >= 0.6:
+            logger.info(
+                f"ManageSubtitles: auto-detected pattern '{result['detected'].id}' "
+                f"(confidence={result['confidence']:.2f})"
+            )
+            return result["detected"]
+
+        # 4. Fallback — adjacent (safest default)
+        logger.info("ManageSubtitles: falling back to 'adjacent' pattern")
+        return kb.pattern("adjacent")
+
+
+def _to_unresolved_dto(
+    track: SubtitleScanResult, min_confidence: float = 0.7
+) -> UnresolvedTrack:
+    reason = "unknown_language" if track.language is None else "low_confidence"
+    return UnresolvedTrack(
+        raw_tokens=track.raw_tokens,
+        file_path=str(track.file_path) if track.file_path else None,
+        file_size_kb=track.file_size_kb,
+        reason=reason,
+    )
+
+
+def _pair_placed_with_tracks(
+    placed: list[PlacedTrack],
+    tracks: list[SubtitleScanResult],
+) -> list[tuple[PlacedTrack, SubtitleScanResult]]:
+    """
+    Pair each PlacedTrack with its originating SubtitleScanResult by source path.
+    Falls back to positional matching if paths don't align.
+    """
+    track_by_path = {t.file_path: t for t in tracks if t.file_path}
+    pairs = []
+    for p in placed:
+        track = track_by_path.get(p.source)
+        if track is None and tracks:
+            track = tracks[0]  # positional fallback
+        if track:
+            pairs.append((p, track))
+    return pairs

alfred/application/filesystem/move_media.py

@@ -0,0 +1,43 @@
+"""Move media use case."""
+
+import logging
+
+from alfred.infrastructure.filesystem import FileManager
+
+from .dto import MoveMediaResponse
+
+logger = logging.getLogger(__name__)
+
+
+class MoveMediaUseCase:
+    """Use case for moving a media file to a destination (copy + delete source)."""
+
+    def __init__(self, file_manager: FileManager):
+        self.file_manager = file_manager
+
+    def execute(self, source: str, destination: str) -> MoveMediaResponse:
+        """
+        Move a media file from source to destination.
+
+        Args:
+            source: Absolute path to the source file.
+            destination: Absolute path to the destination file.
+
+        Returns:
+            MoveMediaResponse with success or error information.
+        """
+        result = self.file_manager.move_file(source, destination)
+
+        if result.get("status") == "ok":
+            return MoveMediaResponse(
+                status="ok",
+                source=result.get("source"),
+                destination=result.get("destination"),
+                filename=result.get("filename"),
+                size=result.get("size"),
+            )
+        return MoveMediaResponse(
+            status="error",
+            error=result.get("error"),
+            message=result.get("message"),
+        )

alfred/application/filesystem/resolve_destination.py

@@ -0,0 +1,464 @@
+"""
+Destination resolution — compute library paths for releases.
+
+Four distinct use cases, one per release type:
+- resolve_season_destination    : season pack (folder move)
+- resolve_episode_destination   : single episode (file move)
+- resolve_movie_destination     : movie (file move)
+- resolve_series_destination    : complete series multi-season pack (folder move)
+
+Each returns a dedicated DTO with only the fields that make sense for that type.
+
+These use cases follow Option B of the snapshot-VO design: ``ParsedRelease``
+arrives with ``title_sanitized`` already computed, and TMDB-supplied strings
+are sanitized **at the use-case boundary** (here) before being passed into
+``ParsedRelease`` builder methods. The builders themselves perform no I/O and
+no sanitization.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from alfred.application.release import inspect_release
+from alfred.domain.release import parse_release
+from alfred.domain.release.ports import ReleaseKnowledge
+from alfred.domain.release.value_objects import ParsedRelease
+from alfred.domain.shared.ports import MediaProber
+from alfred.infrastructure.persistence import get_memory
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_parsed(
+    release_name: str,
+    source_path: str | None,
+    kb: ReleaseKnowledge,
+    prober: MediaProber,
+) -> ParsedRelease:
+    """Pick the right entry point depending on whether we have a path.
+
+    When ``source_path`` is provided and points to something that exists,
+    we run the full inspection pipeline so probe data can refresh tech
+    fields (which feed every filename builder). Otherwise we fall back
+    to a parse-only path — same behavior as before.
+    """
+    if source_path:
+        path = Path(source_path)
+        if path.exists():
+            return inspect_release(release_name, path, kb, prober).parsed
+    parsed, _ = parse_release(release_name, kb)
+    return parsed
+
+
+def _find_existing_tvshow_folders(
+    tv_root: Path, tmdb_title_safe: str, tmdb_year: int
+) -> list[str]:
+    """Return folder names in tv_root that match title + year prefix."""
+    if not tv_root.exists():
+        return []
+    clean_title = tmdb_title_safe.replace(" ", ".")
+    prefix = f"{clean_title}.{tmdb_year}".lower()
+    return sorted(
+        entry.name
+        for entry in tv_root.iterdir()
+        if entry.is_dir() and entry.name.lower().startswith(prefix)
+    )
+
+
+def _get_tv_root() -> Path | None:
+    memory = get_memory()
+    tv_root = memory.ltm.library_paths.get("tv_show")
+    return Path(tv_root) if tv_root else None
+
+
+# ---------------------------------------------------------------------------
+# Internal sentinel + series-folder resolver (shared by the 3 TV use cases)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _Clarification:
+    """Module-private sentinel signalling that user input is needed."""
+
+    question: str
+    options: list[str]
+
+
+def _resolve_series_folder(
+    tv_root: Path,
+    tmdb_title: str,
+    tmdb_title_safe: str,
+    tmdb_year: int,
+    computed_name: str,
+    confirmed_folder: str | None,
+) -> tuple[str, bool] | _Clarification:
+    """
+    Resolve which series folder to use.
+
+    Returns:
+        (folder_name, is_new) if resolved unambiguously,
+        _Clarification(question, options) if the caller must ask the user.
+    """
+    if confirmed_folder:
+        return confirmed_folder, not (tv_root / confirmed_folder).exists()
+
+    existing = _find_existing_tvshow_folders(tv_root, tmdb_title_safe, tmdb_year)
+
+    if not existing:
+        return computed_name, True
+
+    if len(existing) == 1 and existing[0] == computed_name:
+        return existing[0], False
+
+    options = existing + ([computed_name] if computed_name not in existing else [])
+    return _Clarification(
+        question=(
+            f"Un dossier série existe déjà pour '{tmdb_title}' "
+            f"mais son nom diffère du nom calculé ({computed_name}). "
+            f"Lequel utiliser ?"
+        ),
+        options=options,
+    )
+
+
+# ---------------------------------------------------------------------------
+# DTOs
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _ResolvedDestinationBase:
+    """
+    Shared shape across all resolution DTOs.
+
+    Holds the status flag and the fields used in non-ok states
+    (error / needs_clarification). Subclasses add their own ok-state fields
+    and a to_dict() that delegates the non-ok cases via _base_dict().
+    """
+
+    status: str  # "ok" | "needs_clarification" | "error"
+
+    # needs_clarification
+    question: str | None = None
+    options: list[str] | None = None
+
+    # error
+    error: str | None = None
+    message: str | None = None
+
+    def _base_dict(self) -> dict | None:
+        """Return the dict for error/needs_clarification, or None for ok."""
+        if self.status == "error":
+            return {"status": self.status, "error": self.error, "message": self.message}
+        if self.status == "needs_clarification":
+            return {
+                "status": self.status,
+                "question": self.question,
+                "options": self.options or [],
+            }
+        return None
+
+
+@dataclass
+class ResolvedSeasonDestination(_ResolvedDestinationBase):
+    """Paths for a season pack — folder move, no individual file paths."""
+
+    series_folder: str | None = None
+    season_folder: str | None = None
+    series_folder_name: str | None = None
+    season_folder_name: str | None = None
+    is_new_series_folder: bool = False
+
+    def to_dict(self) -> dict:
+        return self._base_dict() or {
+            "status": self.status,
+            "series_folder": self.series_folder,
+            "season_folder": self.season_folder,
+            "series_folder_name": self.series_folder_name,
+            "season_folder_name": self.season_folder_name,
+            "is_new_series_folder": self.is_new_series_folder,
+        }
+
+
+@dataclass
+class ResolvedEpisodeDestination(_ResolvedDestinationBase):
+    """Paths for a single episode — file move."""
+
+    series_folder: str | None = None
+    season_folder: str | None = None
+    library_file: str | None = None  # full path to destination .mkv
+    series_folder_name: str | None = None
+    season_folder_name: str | None = None
+    filename: str | None = None
+    is_new_series_folder: bool = False
+
+    def to_dict(self) -> dict:
+        return self._base_dict() or {
+            "status": self.status,
+            "series_folder": self.series_folder,
+            "season_folder": self.season_folder,
+            "library_file": self.library_file,
+            "series_folder_name": self.series_folder_name,
+            "season_folder_name": self.season_folder_name,
+            "filename": self.filename,
+            "is_new_series_folder": self.is_new_series_folder,
+        }
+
+
+@dataclass
+class ResolvedMovieDestination(_ResolvedDestinationBase):
+    """Paths for a movie — file move."""
+
+    movie_folder: str | None = None
+    library_file: str | None = None
+    movie_folder_name: str | None = None
+    filename: str | None = None
+    is_new_folder: bool = False
+
+    def to_dict(self) -> dict:
+        return self._base_dict() or {
+            "status": self.status,
+            "movie_folder": self.movie_folder,
+            "library_file": self.library_file,
+            "movie_folder_name": self.movie_folder_name,
+            "filename": self.filename,
+            "is_new_folder": self.is_new_folder,
+        }
+
+
+@dataclass
+class ResolvedSeriesDestination(_ResolvedDestinationBase):
+    """Paths for a complete multi-season series pack — folder move."""
+
+    series_folder: str | None = None
+    series_folder_name: str | None = None
+    is_new_series_folder: bool = False
+
+    def to_dict(self) -> dict:
+        return self._base_dict() or {
+            "status": self.status,
+            "series_folder": self.series_folder,
+            "series_folder_name": self.series_folder_name,
+            "is_new_series_folder": self.is_new_series_folder,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Use cases
+# ---------------------------------------------------------------------------
+
+
+def resolve_season_destination(
+    release_name: str,
+    tmdb_title: str,
+    tmdb_year: int,
+    kb: ReleaseKnowledge,
+    prober: MediaProber,
+    confirmed_folder: str | None = None,
+    source_path: str | None = None,
+) -> ResolvedSeasonDestination:
+    """
+    Compute destination paths for a season pack.
+
+    Returns series_folder + season_folder. No file paths — the whole
+    source folder is moved as-is into season_folder.
+
+    When ``source_path`` points to the release on disk, the parser is
+    augmented with ffprobe data so tech tokens missing from the release
+    name (quality / codec) end up in the folder names.
+    """
+    tv_root = _get_tv_root()
+    if not tv_root:
+        return ResolvedSeasonDestination(
+            status="error",
+            error="library_not_set",
+            message="TV show library path is not configured.",
+        )
+
+    parsed = _resolve_parsed(release_name, source_path, kb, prober)
+    tmdb_title_safe = kb.sanitize_for_fs(tmdb_title)
+    computed_name = parsed.show_folder_name(tmdb_title_safe, tmdb_year)
+
+    resolved = _resolve_series_folder(
+        tv_root, tmdb_title, tmdb_title_safe, tmdb_year, computed_name, confirmed_folder
+    )
+    if isinstance(resolved, _Clarification):
+        return ResolvedSeasonDestination(
+            status="needs_clarification",
+            question=resolved.question,
+            options=resolved.options,
+        )
+
+    series_folder_name, is_new = resolved
+    season_folder_name = parsed.season_folder_name()
+    series_path = tv_root / series_folder_name
+    season_path = series_path / season_folder_name
+
+    return ResolvedSeasonDestination(
+        status="ok",
+        series_folder=str(series_path),
+        season_folder=str(season_path),
+        series_folder_name=series_folder_name,
+        season_folder_name=season_folder_name,
+        is_new_series_folder=is_new,
+    )
+
+
+def resolve_episode_destination(
+    release_name: str,
+    source_file: str,
+    tmdb_title: str,
+    tmdb_year: int,
+    kb: ReleaseKnowledge,
+    prober: MediaProber,
+    tmdb_episode_title: str | None = None,
+    confirmed_folder: str | None = None,
+) -> ResolvedEpisodeDestination:
+    """
+    Compute destination paths for a single episode file.
+
+    Returns series_folder + season_folder + library_file (full path to .mkv).
+    ``source_file`` doubles as the inspection target — when it exists,
+    ffprobe enrichment refreshes tech tokens missing from the release name.
+    """
+    tv_root = _get_tv_root()
+    if not tv_root:
+        return ResolvedEpisodeDestination(
+            status="error",
+            error="library_not_set",
+            message="TV show library path is not configured.",
+        )
+
+    parsed = _resolve_parsed(release_name, source_file, kb, prober)
+    ext = Path(source_file).suffix
+    tmdb_title_safe = kb.sanitize_for_fs(tmdb_title)
+    tmdb_episode_title_safe = (
+        kb.sanitize_for_fs(tmdb_episode_title) if tmdb_episode_title else None
+    )
+    computed_name = parsed.show_folder_name(tmdb_title_safe, tmdb_year)
+
+    resolved = _resolve_series_folder(
+        tv_root, tmdb_title, tmdb_title_safe, tmdb_year, computed_name, confirmed_folder
+    )
+    if isinstance(resolved, _Clarification):
+        return ResolvedEpisodeDestination(
+            status="needs_clarification",
+            question=resolved.question,
+            options=resolved.options,
+        )
+
+    series_folder_name, is_new = resolved
+    season_folder_name = parsed.season_folder_name()
+    filename = parsed.episode_filename(tmdb_episode_title_safe, ext)
+
+    series_path = tv_root / series_folder_name
+    season_path = series_path / season_folder_name
+    file_path = season_path / filename
+
+    return ResolvedEpisodeDestination(
+        status="ok",
+        series_folder=str(series_path),
+        season_folder=str(season_path),
+        library_file=str(file_path),
+        series_folder_name=series_folder_name,
+        season_folder_name=season_folder_name,
+        filename=filename,
+        is_new_series_folder=is_new,
+    )
+
+
+def resolve_movie_destination(
+    release_name: str,
+    source_file: str,
+    tmdb_title: str,
+    tmdb_year: int,
+    kb: ReleaseKnowledge,
+    prober: MediaProber,
+) -> ResolvedMovieDestination:
+    """
+    Compute destination paths for a movie file.
+
+    Returns movie_folder + library_file (full path to .mkv).
+    ``source_file`` doubles as the inspection target — when it exists,
+    ffprobe enrichment refreshes tech tokens missing from the release name.
+    """
+    memory = get_memory()
+    movies_root = memory.ltm.library_paths.get("movie")
+    if not movies_root:
+        return ResolvedMovieDestination(
+            status="error",
+            error="library_not_set",
+            message="Movie library path is not configured.",
+        )
+
+    parsed = _resolve_parsed(release_name, source_file, kb, prober)
+    ext = Path(source_file).suffix
+    tmdb_title_safe = kb.sanitize_for_fs(tmdb_title)
+
+    folder_name = parsed.movie_folder_name(tmdb_title_safe, tmdb_year)
+    filename = parsed.movie_filename(tmdb_title_safe, tmdb_year, ext)
+
+    folder_path = Path(movies_root) / folder_name
+    file_path = folder_path / filename
+
+    return ResolvedMovieDestination(
+        status="ok",
+        movie_folder=str(folder_path),
+        library_file=str(file_path),
+        movie_folder_name=folder_name,
+        filename=filename,
+        is_new_folder=not folder_path.exists(),
+    )
+
+
+def resolve_series_destination(
+    release_name: str,
+    tmdb_title: str,
+    tmdb_year: int,
+    kb: ReleaseKnowledge,
+    prober: MediaProber,
+    confirmed_folder: str | None = None,
+    source_path: str | None = None,
+) -> ResolvedSeriesDestination:
+    """
+    Compute destination path for a complete multi-season series pack.
+
+    Returns only series_folder — the whole pack lands directly inside it.
+
+    When ``source_path`` points to the release on disk, ffprobe
+    enrichment refreshes tech tokens missing from the release name.
+    """
+    tv_root = _get_tv_root()
+    if not tv_root:
+        return ResolvedSeriesDestination(
+            status="error",
+            error="library_not_set",
+            message="TV show library path is not configured.",
+        )
+
+    parsed = _resolve_parsed(release_name, source_path, kb, prober)
+    tmdb_title_safe = kb.sanitize_for_fs(tmdb_title)
+    computed_name = parsed.show_folder_name(tmdb_title_safe, tmdb_year)
+
+    resolved = _resolve_series_folder(
+        tv_root, tmdb_title, tmdb_title_safe, tmdb_year, computed_name, confirmed_folder
+    )
+    if isinstance(resolved, _Clarification):
+        return ResolvedSeriesDestination(
+            status="needs_clarification",
+            question=resolved.question,
+            options=resolved.options,
+        )
+
+    series_folder_name, is_new = resolved
+    series_path = tv_root / series_folder_name
+
+    return ResolvedSeriesDestination(
+        status="ok",
+        series_folder=str(series_path),
+        series_folder_name=series_folder_name,
+        is_new_series_folder=is_new,
+    )

alfred/application/release/__init__.py

@@ -0,0 +1,20 @@
+"""Release application layer — orchestrators sitting between domain
+parsing and infrastructure I/O.
+
+Public surface:
+
+- :func:`is_supported_video` / :func:`find_main_video` — pre-pipeline
+  filesystem helpers (extension-only filtering, top-level video pick).
+- :func:`inspect_release` / :class:`InspectedResult` — full inspection
+  pipeline combining parse + filesystem refinement + probe enrichment.
+"""
+
+from .inspect import InspectedResult, inspect_release
+from .supported_media import find_main_video, is_supported_video
+
+__all__ = [
+    "InspectedResult",
+    "find_main_video",
+    "inspect_release",
+    "is_supported_video",
+]

alfred/application/release/detect_media_type.py

@@ -0,0 +1,67 @@
+"""
+detect_media_type — filesystem-based media type refinement.
+
+Enriches a ParsedRelease.media_type with evidence from the actual source path
+(file or folder). Called after parse_release() to produce a final classification.
+
+Classification logic:
+  1. If source_path is a file — check its extension directly.
+  2. If source_path is a folder — collect all extensions inside (non-recursive
+     for the first level, then recursive if nothing conclusive found).
+  3. Decision:
+     - Any non_video extension AND no video extension → "other"
+     - Any video extension → keep parsed media_type ("movie" | "tv_show" | "unknown")
+     - No conclusive extension found → keep parsed media_type as-is
+     - Mixed (video + non_video) → "unknown"
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from alfred.domain.release.ports import ReleaseKnowledge
+from alfred.domain.release.value_objects import ParsedRelease
+
+
+def detect_media_type(
+    parsed: ParsedRelease, source_path: Path, kb: ReleaseKnowledge
+) -> str:
+    """
+    Return a refined media_type string for the given source_path.
+
+    Does not mutate parsed — returns the new media_type value only.
+    The caller is responsible for updating the ParsedRelease if needed.
+    """
+    extensions = _collect_extensions(source_path)
+    # Metadata extensions (.nfo, .srt, …) are always present alongside releases
+    # and must not influence the type decision.
+    conclusive = extensions - kb.metadata_extensions
+
+    has_video = bool(conclusive & kb.video_extensions)
+    has_non_video = bool(conclusive & kb.non_video_extensions)
+
+    if has_video and has_non_video:
+        return "unknown"
+    if has_non_video and not has_video:
+        return "other"
+    if has_video:
+        return parsed.media_type  # trust token-level inference
+    # No conclusive extension — trust token-level inference
+    return parsed.media_type
+
+
+def _collect_extensions(path: Path) -> set[str]:
+    """Return the set of lowercase extensions found at path (file or folder)."""
+    if not path.exists():
+        return set()
+
+    if path.is_file():
+        return {path.suffix.lower()}
+
+    # Folder — scan first level only
+    exts: set[str] = set()
+    for child in path.iterdir():
+        if child.is_file():
+            exts.add(child.suffix.lower())
+
+    return exts

alfred/application/release/enrich_from_probe.py

@@ -0,0 +1,74 @@
+"""enrich_from_probe — fill missing ParsedRelease fields from MediaInfo."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from alfred.domain.release.ports import ReleaseKnowledge
+from alfred.domain.release.value_objects import ParsedRelease
+from alfred.domain.shared.media import MediaInfo
+
+
+def enrich_from_probe(
+    parsed: ParsedRelease, info: MediaInfo, kb: ReleaseKnowledge
+) -> ParsedRelease:
+    """
+    Return a new ParsedRelease with None fields filled from ffprobe MediaInfo.
+
+    Only overwrites fields that are currently None — token-level values
+    from the release name always take priority. ``ParsedRelease`` is
+    frozen; this returns a new instance via :func:`dataclasses.replace`.
+
+    Translation tables (ffprobe codec name → scene token, channel count
+    → layout) live in ``kb.probe_mappings`` (loaded from
+    ``alfred/knowledge/release/probe_mappings.yaml``). When ffprobe
+    reports a value with no mapping entry, the fallback is the uppercase
+    raw value so unknown codecs still surface in a predictable form.
+    """
+    mappings = kb.probe_mappings
+    video_codec_map: dict[str, str] = mappings.get("video_codec", {})
+    audio_codec_map: dict[str, str] = mappings.get("audio_codec", {})
+    channel_map: dict[int, str] = mappings.get("audio_channels", {})
+
+    updates: dict[str, object] = {}
+
+    if parsed.quality is None and info.resolution:
+        updates["quality"] = info.resolution
+
+    if parsed.codec is None and info.video_codec:
+        updates["codec"] = video_codec_map.get(
+            info.video_codec.lower(), info.video_codec.upper()
+        )
+
+    # bit_depth: ffprobe exposes it via pix_fmt — not in MediaInfo yet, skip.
+
+    # Audio — use the default track, fallback to first
+    default_track = next((t for t in info.audio_tracks if t.is_default), None)
+    track = default_track or (info.audio_tracks[0] if info.audio_tracks else None)
+
+    if track:
+        if parsed.audio_codec is None and track.codec:
+            updates["audio_codec"] = audio_codec_map.get(
+                track.codec.lower(), track.codec.upper()
+            )
+
+        if parsed.audio_channels is None and track.channels:
+            updates["audio_channels"] = channel_map.get(
+                track.channels, f"{track.channels}ch"
+            )
+
+    # Languages — merge ffprobe languages with token-level ones
+    # "und" = undetermined, not useful
+    if info.audio_languages:
+        existing_upper = {lang.upper() for lang in parsed.languages}
+        new_languages = list(parsed.languages)
+        for lang in info.audio_languages:
+            if lang.lower() != "und" and lang.upper() not in existing_upper:
+                new_languages.append(lang)
+                existing_upper.add(lang.upper())
+        if len(new_languages) != len(parsed.languages):
+            updates["languages"] = tuple(new_languages)
+
+    if not updates:
+        return parsed
+    return replace(parsed, **updates)

alfred/application/release/inspect.py

@@ -0,0 +1,193 @@
+"""Release inspection orchestrator — the canonical "look at this thing"
+entry point.
+
+``inspect_release`` is the single composition of the four layers we
+care about for a freshly-arrived release:
+
+1. **Parse the name** — :func:`alfred.domain.release.services.parse_release`
+   gives a ``ParsedRelease`` plus a ``ParseReport`` (confidence + road).
+2. **Pick the main video** — :func:`find_main_video` runs a top-level
+   scan over the source path. If nothing qualifies the result still
+   completes; downstream callers decide what to do with a videoless
+   release.
+3. **Refine the media type** — :func:`detect_media_type` uses the
+   on-disk extension mix to override any token-level guess (e.g. a
+   bare ``.iso`` folder becomes ``"other"``). The refined value is
+   patched onto ``parsed`` in place — same convention as
+   ``analyze_release`` had before.
+4. **Probe the video** — the injected :class:`MediaProber` fills in
+   missing technical fields via :func:`enrich_from_probe`. Skipped
+   when there is no main video or when ``media_type`` ended up in
+   ``{"unknown", "other"}`` (the probe would tell us nothing useful).
+
+The return type is :class:`InspectedResult`, a frozen VO that bundles
+everything downstream callers need (``analyze_release`` tool,
+``resolve_destination``, future workflow stages) without forcing them
+to redo the same four calls.
+
+Design notes:
+
+- **Application layer.** This module touches both domain
+  (``parse_release``) and infrastructure (``MediaProber`` port). That
+  is exactly application's job — orchestrate.
+- **Knowledge base is injected.** ``inspect_release`` takes ``kb`` and
+  ``prober`` as parameters; no module-level singletons here. Callers
+  (the tool wrapper, tests) decide what to plug in.
+- **Mutation is contained.** We still mutate ``parsed.media_type`` and
+  let ``enrich_from_probe`` fill its ``None`` fields, because
+  ``ParsedRelease`` is intentionally a mutable dataclass. The outer
+  ``InspectedResult`` is frozen so the *bundle* is immutable from the
+  caller's perspective.
+- **Never raises.** Filesystem / probe errors surface as ``None``
+  fields on the result, never as exceptions — same contract as the
+  underlying adapters.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from alfred.application.release.detect_media_type import detect_media_type
+from alfred.application.release.enrich_from_probe import enrich_from_probe
+from alfred.application.release.supported_media import find_main_video
+from alfred.domain.release.ports import ReleaseKnowledge
+from alfred.domain.release.services import parse_release
+from alfred.domain.release.value_objects import (
+    MediaTypeToken,
+    ParsedRelease,
+    ParseReport,
+)
+from alfred.domain.shared.media import MediaInfo
+from alfred.domain.shared.ports import MediaProber
+
+
+# Media types for which a probe carries no useful information.
+_NON_PROBABLE_MEDIA_TYPES = frozenset({"unknown", "other"})
+
+# Media types for which there's nothing for the organizer to do.
+# ``other`` covers things like games / ISOs / archives sitting on the
+# downloads folder. ``unknown`` does NOT belong here — those need a
+# user decision, not a skip.
+_SKIPPABLE_MEDIA_TYPES = frozenset({"other"})
+
+# Roads that signal the parser couldn't reach a confident answer on its
+# own. ``Road`` values are kept as strings on the report to avoid a
+# cross-package import here.
+_ASK_USER_ROADS = frozenset({"path_of_pain"})
+
+
+@dataclass(frozen=True)
+class InspectedResult:
+    """The full picture of a release: parsed name + filesystem reality.
+
+    Bundles everything the downstream pipeline needs after a single
+    inspection pass:
+
+    - ``parsed`` — :class:`ParsedRelease`, with ``media_type`` already
+      refined by :func:`detect_media_type` and ``None`` tech fields
+      filled in by :func:`enrich_from_probe` when a probe ran.
+    - ``report`` — :class:`ParseReport` from the parser (confidence +
+      road, untouched by inspection).
+    - ``source_path`` — the path the inspector was pointed at (file or
+      folder), as supplied by the caller.
+    - ``main_video`` — the canonical video file inside ``source_path``,
+      or ``None`` if no eligible file was found.
+    - ``media_info`` — the :class:`MediaInfo` snapshot when a probe
+      succeeded; ``None`` when no video was probed (no main video, or
+      ``media_type`` in ``{"unknown", "other"}``) or when ffprobe
+      failed.
+    - ``probe_used`` — ``True`` iff ``media_info`` is non-``None`` and
+      ``enrich_from_probe`` actually ran. Explicit flag so callers
+      don't have to re-derive the condition.
+    - ``recommended_action`` — derived hint for the orchestrator (see
+      property docstring). Encodes the exclusion / clarification /
+      go-ahead decision in one place so downstream callers don't
+      re-implement the same checks.
+    """
+
+    parsed: ParsedRelease
+    report: ParseReport
+    source_path: Path
+    main_video: Path | None
+    media_info: MediaInfo | None
+    probe_used: bool
+
+    @property
+    def recommended_action(self) -> str:
+        """Return one of ``"skip"`` / ``"ask_user"`` / ``"process"``.
+
+        - ``"skip"`` — nothing to organize:
+            * the source has no main video file, **or**
+            * ``media_type`` is ``"other"`` (games / ISOs / archives).
+        - ``"ask_user"`` — a decision is required before any action:
+            * ``media_type`` is ``"unknown"`` (parser couldn't classify), **or**
+            * the parse landed on ``Road.PATH_OF_PAIN``
+              (low-confidence, malformed name, etc.).
+        - ``"process"`` — everything else: a confident parse with a
+          usable media type and a main video on disk. The orchestrator
+          can move straight to the planning step.
+
+        The check ordering matters: ``"skip"`` wins over ``"ask_user"``
+        because if there's no video to organize, no question to the
+        user can change that. ``"ask_user"`` then wins over
+        ``"process"`` because a confident parse alone isn't enough if
+        the type or road still flag uncertainty.
+        """
+        if self.main_video is None:
+            return "skip"
+        if self.parsed.media_type.value in _SKIPPABLE_MEDIA_TYPES:
+            return "skip"
+        if self.parsed.media_type.value == "unknown":
+            return "ask_user"
+        if self.report.road in _ASK_USER_ROADS:
+            return "ask_user"
+        return "process"
+
+
+def inspect_release(
+    release_name: str,
+    source_path: Path,
+    kb: ReleaseKnowledge,
+    prober: MediaProber,
+) -> InspectedResult:
+    """Run the full inspection pipeline on ``release_name`` /
+    ``source_path``.
+
+    See module docstring for the four-step flow. ``kb`` and ``prober``
+    are injected so the caller controls the knowledge base layering
+    and the probe adapter (real ffprobe in production, stubs in tests).
+
+    Never raises. A missing or unreadable ``source_path`` simply
+    results in ``main_video=None`` and ``media_info=None``.
+    """
+    parsed, report = parse_release(release_name, kb)
+
+    # Step 2: refine media_type from the on-disk extension mix.
+    # detect_media_type tolerates non-existent paths (returns parsed.media_type
+    # untouched), so no need to guard here. ParsedRelease is frozen — use
+    # dataclasses.replace to rebind with the refined value.
+    refined_media_type = MediaTypeToken(detect_media_type(parsed, source_path, kb))
+    if refined_media_type != parsed.media_type:
+        parsed = replace(parsed, media_type=refined_media_type)
+
+    # Step 3: pick the canonical main video (top-level scan only).
+    main_video = find_main_video(source_path, kb)
+
+    # Step 4: probe + enrich, when it makes sense.
+    media_info: MediaInfo | None = None
+    probe_used = False
+    if main_video is not None and parsed.media_type not in _NON_PROBABLE_MEDIA_TYPES:
+        media_info = prober.probe(main_video)
+        if media_info is not None:
+            parsed = enrich_from_probe(parsed, media_info, kb)
+            probe_used = True
+
+    return InspectedResult(
+        parsed=parsed,
+        report=report,
+        source_path=source_path,
+        main_video=main_video,
+        media_info=media_info,
+        probe_used=probe_used,
+    )

alfred/application/release/supported_media.py

@@ -0,0 +1,74 @@
+"""Pre-pipeline exclusion — decide which files are worth parsing.
+
+These helpers live one notch above the domain: they touch the
+filesystem (``Path.iterdir``, ``Path.suffix``) but carry no parsing
+logic of their own. The goal is to filter out non-video files and pick
+the canonical "main video" from a release folder *before* anything
+hits :func:`~alfred.domain.release.parse_release`.
+
+Design notes (Phase A bis, 2026-05-20):
+
+- **Extension is the sole eligibility criterion.** A file is supported
+  iff its suffix is in ``kb.video_extensions``. No size threshold, no
+  filename heuristics ("sample", "trailer", …). If a release packs a
+  bloated featurette or names its sample alphabetically before the
+  main feature, that's PATH_OF_PAIN territory — not this layer's job.
+
+- **Top-level scan only.** ``find_main_video`` does not descend into
+  subdirectories. Releases that wrap the main video in ``Sample/`` or
+  similar are non-scene-standard and handled by the orchestrator
+  upstream.
+
+- **Lexicographic tie-break.** When several candidates qualify
+  (legitimate for season packs), we return the first by alphabetical
+  order. Deterministic, no size-based ranking.
+
+- **Direct ``Path`` I/O.** No ``FilesystemScanner`` port — this layer
+  is application, not domain. If isolation becomes necessary for
+  testing scale, we'll introduce a port then.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from alfred.domain.release.ports.knowledge import ReleaseKnowledge
+
+
+def is_supported_video(path: Path, kb: ReleaseKnowledge) -> bool:
+    """Return True when ``path`` is a video file the parser should
+    consider.
+
+    The check is purely extension-based: ``path.suffix.lower()`` must
+    belong to ``kb.video_extensions``. ``path`` must also be a regular
+    file — directories and broken symlinks return False.
+    """
+    if not path.is_file():
+        return False
+    return path.suffix.lower() in kb.video_extensions
+
+
+def find_main_video(folder: Path, kb: ReleaseKnowledge) -> Path | None:
+    """Return the canonical main video file inside ``folder``, or
+    ``None`` if there isn't one.
+
+    Behavior:
+
+    - Top-level scan only — subdirectories are ignored.
+    - Eligibility is :func:`is_supported_video`.
+    - When several files qualify, the lexicographically first one wins.
+    - When ``folder`` itself is a video file, it is returned as-is
+      (single-file releases are valid).
+    - When ``folder`` doesn't exist or isn't a directory (and isn't a
+      video file either), returns ``None``.
+    """
+    if folder.is_file():
+        return folder if is_supported_video(folder, kb) else None
+
+    if not folder.is_dir():
+        return None
+
+    candidates = sorted(
+        child for child in folder.iterdir() if is_supported_video(child, kb)
+    )
+    return candidates[0] if candidates else None

alfred/application/subtitles/placer.py

@@ -0,0 +1,116 @@
+"""SubtitlePlacer — hard-links matched subtitle tracks next to the destination video."""
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from alfred.domain.subtitles.entities import SubtitleScanResult
+from alfred.domain.subtitles.value_objects import SubtitleType
+
+logger = logging.getLogger(__name__)
+
+
+def _build_dest_name(track: SubtitleScanResult, video_stem: str) -> str:
+    """
+    Build the destination filename for a subtitle track.
+
+    Format: {video_stem}.{lang}.{ext}
+            {video_stem}.{lang}.sdh.{ext}
+            {video_stem}.{lang}.forced.{ext}
+    """
+    if not track.language or not track.format:
+        raise ValueError("Cannot compute destination name: language or format missing")
+
+    ext = track.format.extensions[0].lstrip(".")
+    parts = [video_stem, track.language.code]
+    if track.subtitle_type == SubtitleType.SDH:
+        parts.append("sdh")
+    elif track.subtitle_type == SubtitleType.FORCED:
+        parts.append("forced")
+    return ".".join(parts) + "." + ext
+
+
+@dataclass
+class PlacedTrack:
+    source: Path
+    destination: Path
+    filename: str
+
+
+@dataclass
+class PlaceResult:
+    placed: list[PlacedTrack]
+    skipped: list[tuple[SubtitleScanResult, str]]  # (track, reason)
+
+    @property
+    def placed_count(self) -> int:
+        return len(self.placed)
+
+    @property
+    def skipped_count(self) -> int:
+        return len(self.skipped)
+
+
+class SubtitlePlacer:
+    """
+    Hard-links matched SubtitleScanResult files next to a destination video.
+
+    Uses the same hard-link strategy as FileManager.copy_file:
+    instant, no data duplication, qBittorrent keeps seeding.
+
+    Embedded tracks are skipped — nothing to place on disk.
+    """
+
+    def place(
+        self,
+        tracks: list[SubtitleScanResult],
+        destination_video: Path,
+    ) -> PlaceResult:
+        placed: list[PlacedTrack] = []
+        skipped: list[tuple[SubtitleScanResult, str]] = []
+
+        dest_dir = destination_video.parent
+
+        for track in tracks:
+            if track.is_embedded:
+                logger.debug(f"SubtitlePlacer: skip embedded track ({track.language})")
+                skipped.append((track, "embedded — no file to place"))
+                continue
+
+            if not track.file_path:
+                skipped.append((track, "source file not set"))
+                continue
+
+            try:
+                dest_name = _build_dest_name(track, destination_video.stem)
+            except ValueError as e:
+                skipped.append((track, str(e)))
+                continue
+
+            dest_path = dest_dir / dest_name
+
+            try:
+                os.link(track.file_path, dest_path)
+                placed.append(
+                    PlacedTrack(
+                        source=track.file_path,
+                        destination=dest_path,
+                        filename=dest_name,
+                    )
+                )
+                logger.info(f"SubtitlePlacer: placed {dest_name}")
+            except FileNotFoundError:
+                skipped.append((track, "source file not found"))
+            except FileExistsError:
+                logger.debug(f"SubtitlePlacer: skip {dest_name} — already exists")
+                skipped.append((track, "destination already exists"))
+            except OSError as e:
+                logger.warning(f"SubtitlePlacer: failed to place {dest_name}: {e}")
+                skipped.append((track, str(e)))
+
+        logger.info(
+            f"SubtitlePlacer: {len(placed)} placed, {len(skipped)} skipped "
+            f"for {destination_video.name}"
+        )
+        return PlaceResult(placed=placed, skipped=skipped)

alfred/domain/movies/__init__.py

@@ -2,7 +2,6 @@
 
 from .entities import Movie
 from .exceptions import InvalidMovieData, MovieNotFound
-from .services import MovieService
 from .value_objects import MovieTitle, Quality, ReleaseYear
 
 __all__ = [
@@ -12,5 +11,4 @@ __all__ = [
     "Quality",
     "MovieNotFound",
     "InvalidMovieData",
-    "MovieService",
 ]

alfred/domain/movies/entities.py

@@ -3,16 +3,30 @@
 from dataclasses import dataclass, field
 from datetime import datetime
 
+from ..shared.media import AudioTrack, MediaWithTracks, SubtitleTrack
 from ..shared.value_objects import FilePath, FileSize, ImdbId
 from .value_objects import MovieTitle, Quality, ReleaseYear
 
 
-@dataclass
-class Movie:
+@dataclass(frozen=True, eq=False)
+class Movie(MediaWithTracks):
     """
-    Movie entity representing a movie in the media library.
+    Movie aggregate root for the movies domain.
 
-    This is the main aggregate root for the movies domain.
+    Carries file metadata (path, size) and the tracks discovered by the
+    ffprobe + subtitle scan pipeline. The track tuples may be empty when the
+    movie is known but not yet scanned, or when no file is downloaded.
+
+    Track helpers follow the same "C+" contract as ``Episode``: pass a
+    ``Language`` for cross-format matching, or a ``str`` for case-insensitive
+    direct comparison.
+
+    Frozen: rebuild via ``dataclasses.replace`` to project enrichment results
+    (audio/subtitle tracks, file metadata) onto a new instance.
+
+    Equality is identity-based: two ``Movie`` instances are equal iff they
+    share the same ``imdb_id``, regardless of file/track contents. This is
+    the DDD aggregate invariant — the aggregate is identified by its root id.
     """
 
     imdb_id: ImdbId
@@ -23,6 +37,8 @@ class Movie:
     file_size: FileSize | None = None
     tmdb_id: int | None = None
     added_at: datetime = field(default_factory=datetime.now)
+    audio_tracks: tuple[AudioTrack, ...] = field(default_factory=tuple)
+    subtitle_tracks: tuple[SubtitleTrack, ...] = field(default_factory=tuple)
 
     def __post_init__(self):
         """Validate movie entity."""
@@ -44,13 +60,16 @@ class Movie:
                     f"title must be MovieTitle or str, got {type(self.title)}"
                 )
 
-    def has_file(self) -> bool:
-        """Check if the movie has an associated file."""
-        return self.file_path is not None and self.file_path.exists()
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Movie):
+            return NotImplemented
+        return self.imdb_id == other.imdb_id
 
-    def is_downloaded(self) -> bool:
-        """Check if the movie is downloaded (has a file)."""
-        return self.has_file()
+    def __hash__(self) -> int:
+        return hash(self.imdb_id)
+
+    # Track helpers (has_audio_in / audio_languages / has_subtitles_in /
+    # has_forced_subs / subtitle_languages) come from MediaWithTracks.
 
     def get_folder_name(self) -> str:
         """

alfred/domain/movies/services.py

@@ -1,192 +0,0 @@
-"""Movie domain services - Business logic."""
-
-import logging
-import re
-
-from ..shared.value_objects import FilePath, ImdbId
-from .entities import Movie
-from .exceptions import MovieAlreadyExists, MovieNotFound
-from .repositories import MovieRepository
-from .value_objects import Quality
-
-logger = logging.getLogger(__name__)
-
-
-class MovieService:
-    """
-    Domain service for movie-related business logic.
-
-    This service contains business rules that don't naturally fit
-    within a single entity.
-    """
-
-    def __init__(self, repository: MovieRepository):
-        """
-        Initialize movie service.
-
-        Args:
-            repository: Movie repository for persistence
-        """
-        self.repository = repository
-
-    def add_movie(self, movie: Movie) -> None:
-        """
-        Add a new movie to the library.
-
-        Args:
-            movie: Movie entity to add
-
-        Raises:
-            MovieAlreadyExists: If movie with same IMDb ID already exists
-        """
-        if self.repository.exists(movie.imdb_id):
-            raise MovieAlreadyExists(
-                f"Movie with IMDb ID {movie.imdb_id} already exists"
-            )
-
-        self.repository.save(movie)
-        logger.info(f"Added movie: {movie.title.value} ({movie.imdb_id})")
-
-    def get_movie(self, imdb_id: ImdbId) -> Movie:
-        """
-        Get a movie by IMDb ID.
-
-        Args:
-            imdb_id: IMDb ID of the movie
-
-        Returns:
-            Movie entity
-
-        Raises:
-            MovieNotFound: If movie not found
-        """
-        movie = self.repository.find_by_imdb_id(imdb_id)
-        if not movie:
-            raise MovieNotFound(f"Movie with IMDb ID {imdb_id} not found")
-        return movie
-
-    def get_all_movies(self) -> list[Movie]:
-        """
-        Get all movies in the library.
-
-        Returns:
-            List of all movies
-        """
-        return self.repository.find_all()
-
-    def update_movie(self, movie: Movie) -> None:
-        """
-        Update an existing movie.
-
-        Args:
-            movie: Movie entity with updated data
-
-        Raises:
-            MovieNotFound: If movie doesn't exist
-        """
-        if not self.repository.exists(movie.imdb_id):
-            raise MovieNotFound(f"Movie with IMDb ID {movie.imdb_id} not found")
-
-        self.repository.save(movie)
-        logger.info(f"Updated movie: {movie.title.value} ({movie.imdb_id})")
-
-    def remove_movie(self, imdb_id: ImdbId) -> None:
-        """
-        Remove a movie from the library.
-
-        Args:
-            imdb_id: IMDb ID of the movie to remove
-
-        Raises:
-            MovieNotFound: If movie not found
-        """
-        if not self.repository.delete(imdb_id):
-            raise MovieNotFound(f"Movie with IMDb ID {imdb_id} not found")
-
-        logger.info(f"Removed movie with IMDb ID: {imdb_id}")
-
-    def detect_quality_from_filename(self, filename: str) -> Quality:
-        """
-        Detect video quality from filename.
-
-        Args:
-            filename: Filename to analyze
-
-        Returns:
-            Detected quality or UNKNOWN
-        """
-        filename_lower = filename.lower()
-
-        # Check for quality indicators
-        if "2160p" in filename_lower or "4k" in filename_lower:
-            return Quality.UHD_4K
-        elif "1080p" in filename_lower:
-            return Quality.FULL_HD
-        elif "720p" in filename_lower:
-            return Quality.HD
-        elif "480p" in filename_lower:
-            return Quality.SD
-
-        return Quality.UNKNOWN
-
-    def extract_year_from_filename(self, filename: str) -> int | None:
-        """
-        Extract release year from filename.
-
-        Args:
-            filename: Filename to analyze
-
-        Returns:
-            Year if found, None otherwise
-        """
-        # Look for 4-digit year in parentheses or standalone
-        # Examples: "Movie (2010)", "Movie.2010.1080p"
-        patterns = [
-            r"\((\d{4})\)",  # (2010)
-            r"\.(\d{4})\.",  # .2010.
-            r"\s(\d{4})\s",  # 2010
-        ]
-
-        for pattern in patterns:
-            match = re.search(pattern, filename)
-            if match:
-                year = int(match.group(1))
-                # Validate year is reasonable
-                if 1888 <= year <= 2100:
-                    return year
-
-        return None
-
-    def validate_movie_file(self, file_path: FilePath) -> bool:
-        """
-        Validate that a file is a valid movie file.
-
-        Args:
-            file_path: Path to the file
-
-        Returns:
-            True if valid movie file, False otherwise
-        """
-        if not file_path.exists():
-            logger.warning(f"File does not exist: {file_path}")
-            return False
-
-        if not file_path.is_file():
-            logger.warning(f"Path is not a file: {file_path}")
-            return False
-
-        # Check file extension
-        valid_extensions = {".mkv", ".mp4", ".avi", ".mov", ".wmv", ".flv", ".webm"}
-        if file_path.value.suffix.lower() not in valid_extensions:
-            logger.warning(f"Invalid file extension: {file_path.value.suffix}")
-            return False
-
-        # Check file size (should be at least 100 MB for a movie)
-        min_size = 100 * 1024 * 1024  # 100 MB
-        if file_path.value.stat().st_size < min_size:
-            logger.warning(
-                f"File too small to be a movie: {file_path.value.stat().st_size} bytes"
-            )
-            return False
-
-        return True

alfred/domain/movies/value_objects.py

@@ -1,10 +1,10 @@
 """Movie domain value objects."""
 
-import re
 from dataclasses import dataclass
 from enum import Enum
 
 from ..shared.exceptions import ValidationError
+from ..shared.value_objects import to_dot_folder_name
 
 
 class Quality(Enum):
@@ -17,7 +17,7 @@ class Quality(Enum):
     UNKNOWN = "unknown"
 
     @classmethod
-    def from_string(cls, quality_str: str) -> "Quality":
+    def from_string(cls, quality_str: str) -> Quality:
         """
         Parse quality from string.
 
@@ -67,11 +67,7 @@ class MovieTitle:
 
         Removes special characters and replaces spaces with dots.
         """
-        # Remove special characters except spaces, dots, and hyphens
-        cleaned = re.sub(r"[^\w\s\.\-]", "", self.value)
-        # Replace spaces with dots
-        normalized = cleaned.replace(" ", ".")
-        return normalized
+        return to_dot_folder_name(self.value)
 
     def __str__(self) -> str:
         return self.value

alfred/domain/release/__init__.py

@@ -0,0 +1,6 @@
+"""Release domain — release name parsing and naming conventions."""
+
+from .services import parse_release
+from .value_objects import ParsedRelease, ParseReport
+
+__all__ = ["ParsedRelease", "ParseReport", "parse_release"]

alfred/domain/release/parser/__init__.py

@@ -0,0 +1,31 @@
+"""Release parser v2 — annotate-based pipeline.
+
+This package is the future home of ``parse_release``. It restructures the
+parsing logic around a **tokenize → annotate → assemble** pipeline:
+
+1. **tokenize**: split the release name into atomic tokens.
+2. **annotate**: walk tokens left-to-right, assigning each one a
+   :class:`TokenRole` (TITLE, YEAR, SEASON, RESOLUTION, …) using the
+   injected :class:`~alfred.domain.release.ports.knowledge.ReleaseKnowledge`.
+3. **assemble**: fold the annotated tokens into a :class:`ParsedRelease`.
+
+The pipeline has three internal paths driven by the detected release group:
+
+- **EASY**: known group (KONTRAST, RARBG, …) with a schema-driven layout
+  declared in ``knowledge/release/release_groups/<group>.yaml``.
+- **SHITTY**: unknown group, best-effort matching against the global
+  knowledge sets, with a 0-100 confidence score.
+- **PATH OF PAIN**: score below threshold OR critical chunks missing —
+  signaled to the caller, who decides whether to involve the LLM/user.
+
+Today the package exposes scaffolding only (token VOs and a thin pipeline
+stub). The legacy ``parse_release`` in ``release.services`` keeps serving
+production until each piece of the v2 pipeline is wired in.
+"""
+
+from __future__ import annotations
+
+from .schema import GroupSchema, SchemaChunk
+from .tokens import Token, TokenRole
+
+__all__ = ["GroupSchema", "SchemaChunk", "Token", "TokenRole"]

alfred/domain/release/parser/pipeline.py

@@ -0,0 +1,763 @@
+"""Annotate-based pipeline.
+
+Three stages:
+
+1. :func:`tokenize` — release name → ``list[Token]`` (all UNKNOWN), plus
+   a separately-returned site tag (e.g. ``[YTS.MX]``) that is never
+   tokenized.
+2. :func:`annotate` — promote each token's :class:`TokenRole` using the
+   injected knowledge base. Two sub-passes:
+
+     a. **Structural** (schema-driven, EASY only). Detects the group at
+        the right end, looks up its :class:`GroupSchema`, then matches
+        the schema's chunk sequence against the token stream. Between
+        two structural chunks, any number of unmatched tokens may
+        remain — they are left UNKNOWN for the enricher pass to handle.
+     b. **Enrichers** (non-positional). Walks UNKNOWN tokens and tags
+        audio / video-meta / edition / language roles. Multi-token
+        sequences (``DTS.HD.MA``, ``DV.HDR10``, ``DIRECTORS.CUT``) are
+        matched first, single tokens after.
+
+3. :func:`assemble` — fold annotated tokens into a
+   :class:`~alfred.domain.release.value_objects.ParsedRelease`-compatible
+   dict.
+
+The pipeline is **pure**: no I/O, no TMDB, no probe. All knowledge
+arrives through ``kb: ReleaseKnowledge``.
+"""
+
+from __future__ import annotations
+
+from ..ports.knowledge import ReleaseKnowledge
+from ..value_objects import MediaTypeToken
+from .schema import GroupSchema
+from .tokens import Token, TokenRole
+
+
+# ---------------------------------------------------------------------------
+# Stage 1 — tokenize
+# ---------------------------------------------------------------------------
+
+
+def strip_site_tag(name: str) -> tuple[str, str | None]:
+    """Split off a ``[site.tag]`` prefix or suffix.
+
+    Returns ``(clean_name, tag)``. If no tag is found, returns
+    ``(name.strip(), None)``.
+    """
+    s = name.strip()
+
+    if s.startswith("["):
+        close = s.find("]")
+        if close != -1:
+            tag = s[1:close].strip()
+            remainder = s[close + 1 :].strip()
+            if tag and remainder:
+                return remainder, tag
+
+    if s.endswith("]"):
+        open_bracket = s.rfind("[")
+        if open_bracket != -1:
+            tag = s[open_bracket + 1 : -1].strip()
+            remainder = s[:open_bracket].strip()
+            if tag and remainder:
+                return remainder, tag
+
+    return s, None
+
+
+def tokenize(name: str, kb: ReleaseKnowledge) -> tuple[list[Token], str | None]:
+    """Split ``name`` into tokens after stripping any site tag.
+
+    String-ops style: replace every configured separator with a single
+    NUL byte then split. NUL cannot legally appear in a release name, so
+    it's a safe sentinel.
+    """
+    clean, site_tag = strip_site_tag(name)
+
+    DELIM = "\x00"
+    buf = clean
+    for sep in kb.separators:
+        if sep != DELIM:
+            buf = buf.replace(sep, DELIM)
+
+    pieces = [p for p in buf.split(DELIM) if p]
+    tokens = [Token(text=p, index=i) for i, p in enumerate(pieces)]
+    return tokens, site_tag
+
+
+# ---------------------------------------------------------------------------
+# Helpers shared across passes
+# ---------------------------------------------------------------------------
+
+
+def _parse_season_episode(text: str) -> tuple[int, int | None, int | None] | None:
+    """Parse a single token as ``SxxExx`` / ``SxxExxExx`` / ``Sxx`` /
+    ``Sxx-yy`` (season range) / ``NxNN``.
+
+    Returns ``(season, episode, episode_end)`` or ``None`` if the token
+    is not a season/episode marker. For ``Sxx-yy``, returns the first
+    season with no episode info — the caller is expected to detect the
+    range form and promote ``media_type`` to ``tv_complete`` separately.
+    """
+    upper = text.upper()
+
+    # SxxExx form (and Sxx, Sxx-yy)
+    if len(upper) >= 3 and upper[0] == "S" and upper[1:3].isdigit():
+        season = int(upper[1:3])
+        rest = upper[3:]
+
+        if not rest:
+            return season, None, None
+
+        # Sxx-yy season-range form: capture the first season, treat as a
+        # complete-series marker (no episode info).
+        if (
+            len(rest) == 3
+            and rest[0] == "-"
+            and rest[1:3].isdigit()
+        ):
+            return season, None, None
+
+        episodes: list[int] = []
+        while rest.startswith("E") and len(rest) >= 3 and rest[1:3].isdigit():
+            episodes.append(int(rest[1:3]))
+            rest = rest[3:]
+
+        if not episodes:
+            return None
+        # For chained multi-episode markers (E09E10E11), the range is the
+        # first → last episode. Intermediate values are implied.
+        return season, episodes[0], episodes[-1] if len(episodes) >= 2 else None
+
+    # NxNN form
+    if "X" in upper:
+        parts = upper.split("X")
+        if len(parts) >= 2 and all(p.isdigit() and p for p in parts):
+            season = int(parts[0])
+            episode = int(parts[1])
+            episode_end = int(parts[2]) if len(parts) >= 3 else None
+            return season, episode, episode_end
+
+    return None
+
+
+def _is_year(text: str) -> bool:
+    """Return True if ``text`` is a 4-digit year in [1900, 2099]."""
+    return len(text) == 4 and text.isdigit() and 1900 <= int(text) <= 2099
+
+
+def _split_codec_group(text: str, kb: ReleaseKnowledge) -> tuple[str, str] | None:
+    """Split a ``codec-GROUP`` token into ``(codec, group)`` if it fits.
+
+    Returns ``None`` if the token doesn't match the ``codec-GROUP``
+    shape. Handles the empty-group case (``x265-``) as ``(codec, "")``.
+    """
+    if "-" not in text:
+        return None
+    head, _, tail = text.rpartition("-")
+    if head.lower() in kb.codecs:
+        return head, tail
+    return None
+
+
+def _match_role(text: str, role: TokenRole, kb: ReleaseKnowledge) -> TokenRole | None:
+    """Return ``role`` if ``text`` matches it under ``kb``, else ``None``."""
+    lower = text.lower()
+
+    if role is TokenRole.YEAR:
+        return TokenRole.YEAR if _is_year(text) else None
+
+    if role is TokenRole.SEASON_EPISODE:
+        return (
+            TokenRole.SEASON_EPISODE
+            if _parse_season_episode(text) is not None
+            else None
+        )
+
+    if role is TokenRole.RESOLUTION:
+        return TokenRole.RESOLUTION if lower in kb.resolutions else None
+
+    if role is TokenRole.SOURCE:
+        return TokenRole.SOURCE if lower in kb.sources else None
+
+    if role is TokenRole.CODEC:
+        return TokenRole.CODEC if lower in kb.codecs else None
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Stage 2a — group detection
+# ---------------------------------------------------------------------------
+
+
+def _detect_group(tokens: list[Token], kb: ReleaseKnowledge) -> tuple[str, int | None]:
+    """Identify the release group by walking tokens right-to-left.
+
+    Returns ``(group_name, token_index_carrying_group)``. ``index`` is
+    ``None`` when the group is absent (no trailing ``-`` in the stream).
+    """
+    # Priority 1: codec-GROUP shape (clearest signal).
+    for tok in reversed(tokens):
+        split = _split_codec_group(tok.text, kb)
+        if split is not None:
+            _, group = split
+            return (group or "UNKNOWN"), tok.index
+
+    # Priority 2: rightmost dash, excluding dashed sources (Web-DL, etc.).
+    for tok in reversed(tokens):
+        if "-" not in tok.text:
+            continue
+        head, _, tail = tok.text.rpartition("-")
+        if (
+            head.lower() in kb.sources
+            or tok.text.lower().replace("-", "") in kb.sources
+        ):
+            continue
+        if tail:
+            return tail, tok.index
+
+    return "UNKNOWN", None
+
+
+# ---------------------------------------------------------------------------
+# Stage 2b — structural annotation (schema-driven)
+# ---------------------------------------------------------------------------
+
+
+def _annotate_structural(
+    tokens: list[Token],
+    kb: ReleaseKnowledge,
+    schema: GroupSchema,
+    group_token_index: int,
+) -> list[Token] | None:
+    """Annotate structural tokens following a known group schema.
+
+    Walks the schema's chunks against the body (tokens up to the group
+    token). For each chunk, scans forward in the body for a matching
+    token — tokens passed over without match are left UNKNOWN (the
+    enricher pass will handle them).
+
+    Returns ``None`` if any mandatory chunk fails to find a match.
+    """
+    result = list(tokens)
+
+    # The codec-GROUP token carries CODEC + GROUP. Split it now so the
+    # schema walk knows the codec is "pre-consumed" at the end.
+    group_token = result[group_token_index]
+    cg_split = _split_codec_group(group_token.text, kb)
+    codec_pre_consumed = False
+    if cg_split is not None:
+        codec, group = cg_split
+        result[group_token_index] = group_token.with_role(
+            TokenRole.CODEC, codec=codec, group=group or "UNKNOWN"
+        )
+        codec_pre_consumed = True
+    else:
+        head, _, tail = group_token.text.rpartition("-")
+        result[group_token_index] = group_token.with_role(
+            TokenRole.GROUP, group=tail or "UNKNOWN", prefix=head
+        )
+
+    body_end = group_token_index  # exclusive
+    tok_idx = 0
+    chunk_idx = 0
+
+    # 1) TITLE — leftmost contiguous tokens up to the first structural
+    #    boundary. Title is special because it can be multi-token.
+    while (
+        chunk_idx < len(schema.chunks)
+        and schema.chunks[chunk_idx].role is TokenRole.TITLE
+    ):
+        title_end = _find_title_end(result, body_end, kb)
+        for i in range(tok_idx, title_end):
+            result[i] = result[i].with_role(TokenRole.TITLE)
+        tok_idx = title_end
+        chunk_idx += 1
+
+    # 2) Remaining structural chunks. For each, scan forward in the body
+    #    for a matching token; tokens passed over remain UNKNOWN.
+    for chunk in schema.chunks[chunk_idx:]:
+        if chunk.role is TokenRole.GROUP:
+            continue
+        if chunk.role is TokenRole.CODEC and codec_pre_consumed:
+            continue
+
+        match_idx = _find_chunk(result, tok_idx, body_end, chunk.role, kb)
+        if match_idx is None:
+            if chunk.optional:
+                continue
+            return None
+
+        result[match_idx] = result[match_idx].with_role(chunk.role)
+        tok_idx = match_idx + 1
+
+    return result
+
+
+def _find_title_end(
+    tokens: list[Token], body_end: int, kb: ReleaseKnowledge
+) -> int:
+    """Return the exclusive index where the title ends.
+
+    The title is the leftmost run of tokens whose text does not match
+    any structural role (year, season/episode, resolution, source,
+    codec). Enricher tokens (audio, HDR, language) are *not* boundaries
+    because they can appear in the middle of the structural sequence;
+    however, in canonical scene names they don't appear inside the title
+    itself, so this heuristic holds in practice.
+    """
+    for i in range(body_end):
+        text = tokens[i].text
+        if _parse_season_episode(text) is not None:
+            return i
+        if _is_year(text):
+            return i
+        lower = text.lower()
+        if lower in kb.resolutions:
+            return i
+        if lower in kb.sources:
+            return i
+        if lower in kb.codecs:
+            return i
+        # codec-GROUP token (e.g. "x265-KONTRAST") or dashed source (Web-DL).
+        if "-" in text:
+            head, _, _ = text.rpartition("-")
+            if (
+                head.lower() in kb.codecs
+                or head.lower() in kb.sources
+                or text.lower().replace("-", "") in kb.sources
+            ):
+                return i
+    return body_end
+
+
+def _find_chunk(
+    tokens: list[Token],
+    start: int,
+    end: int,
+    role: TokenRole,
+    kb: ReleaseKnowledge,
+) -> int | None:
+    """Return the first index in ``[start, end)`` whose token matches ``role``.
+
+    Returns ``None`` if no token in the range matches. Tokens already
+    annotated (non-UNKNOWN) are skipped — they belong to another chunk.
+    """
+    for i in range(start, end):
+        if tokens[i].role is not TokenRole.UNKNOWN:
+            continue
+        if _match_role(tokens[i].text, role, kb) is not None:
+            return i
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Stage 2b' — SHITTY annotation (schema-less heuristic)
+# ---------------------------------------------------------------------------
+
+
+def _annotate_shitty(
+    tokens: list[Token],
+    kb: ReleaseKnowledge,
+    group_index: int | None,
+) -> list[Token]:
+    """Schema-less, dictionary-driven annotation.
+
+    SHITTY's job is narrow: for releases that *look* like scene names
+    but don't have a registered group schema, tag every token whose text
+    falls into a known YAML bucket (resolutions, codecs, sources, …).
+    Anything we can't classify stays UNKNOWN. The leftmost run of
+    UNKNOWN tokens becomes the title. Done.
+
+    Anything that requires more reasoning (parenthesized tech blocks,
+    bare-dashed title fragments, year-disguised slug suffixes, …) is
+    PATH OF PAIN territory and stays out of here on purpose.
+    """
+    result = list(tokens)
+
+    # 1) Group token — split codec-GROUP or tag GROUP. Same logic as EASY.
+    if group_index is not None:
+        gt = result[group_index]
+        cg_split = _split_codec_group(gt.text, kb)
+        if cg_split is not None:
+            codec, group = cg_split
+            result[group_index] = gt.with_role(
+                TokenRole.CODEC, codec=codec, group=group or "UNKNOWN"
+            )
+        else:
+            _, _, tail = gt.text.rpartition("-")
+            result[group_index] = gt.with_role(
+                TokenRole.GROUP, group=tail or "UNKNOWN"
+            )
+
+    # 2) Enrichers (audio / video-meta / edition / language).
+    result = _annotate_enrichers(result, kb)
+
+    # 3) Single pass: tag each UNKNOWN token by looking it up in the kb
+    #    buckets. First match wins per token, first occurrence wins per
+    #    role (we don't overwrite an already-tagged role).
+    matchers: list[tuple[TokenRole, callable]] = [
+        (TokenRole.SEASON_EPISODE, lambda t: _parse_season_episode(t) is not None),
+        (TokenRole.YEAR, _is_year),
+        (TokenRole.RESOLUTION, lambda t: t.lower() in kb.resolutions),
+        (TokenRole.DISTRIBUTOR, lambda t: t.upper() in kb.distributors),
+        (TokenRole.SOURCE, lambda t: t.lower() in kb.sources),
+        (TokenRole.CODEC, lambda t: t.lower() in kb.codecs),
+    ]
+    seen: set[TokenRole] = set()
+
+    for i, tok in enumerate(result):
+        if tok.role is not TokenRole.UNKNOWN:
+            continue
+        for role, matches in matchers:
+            if role in seen:
+                continue
+            if matches(tok.text):
+                result[i] = tok.with_role(role)
+                seen.add(role)
+                break
+
+    # 4) Title = leftmost contiguous UNKNOWN tokens.
+    for i, tok in enumerate(result):
+        if tok.role is not TokenRole.UNKNOWN:
+            break
+        result[i] = tok.with_role(TokenRole.TITLE)
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Stage 2c — enricher pass (non-positional roles)
+# ---------------------------------------------------------------------------
+
+
+def _annotate_enrichers(tokens: list[Token], kb: ReleaseKnowledge) -> list[Token]:
+    """Tag the remaining UNKNOWN tokens with non-positional roles.
+
+    Multi-token sequences are matched first (so ``DTS.HD.MA`` wins over
+    a single-token ``DTS``). For each sequence match, the first token
+    receives the role + ``extra["sequence"]`` (the canonical joined
+    value), and the trailing members are marked with the same role +
+    ``extra["sequence_member"]=True`` so :func:`assemble` extracts the
+    value only from the primary.
+    """
+    result = list(tokens)
+
+    # Multi-token sequences first.
+    _apply_sequences(
+        result, kb.audio.get("sequences", []), "codec", TokenRole.AUDIO_CODEC
+    )
+    _apply_sequences(
+        result, kb.video_meta.get("sequences", []), "hdr", TokenRole.HDR
+    )
+    _apply_sequences(
+        result, kb.editions.get("sequences", []), "edition", TokenRole.EDITION
+    )
+
+    # Single tokens.
+    known_audio_codecs = {c.upper() for c in kb.audio.get("codecs", [])}
+    known_audio_channels = set(kb.audio.get("channels", []))
+    known_hdr = {h.upper() for h in kb.video_meta.get("hdr", [])} | kb.hdr_extra
+    known_bit_depth = {d.lower() for d in kb.video_meta.get("bit_depth", [])}
+    known_editions = {t.upper() for t in kb.editions.get("tokens", [])}
+
+    # Channel layouts like "5.1" are tokenized as two tokens ("5", "1")
+    # because "." is a separator. Detect consecutive pairs whose joined
+    # value (without any trailing "-GROUP") is in the channel set.
+    _detect_channel_pairs(result, known_audio_channels)
+
+    for i, tok in enumerate(result):
+        if tok.role is not TokenRole.UNKNOWN:
+            continue
+        text = tok.text
+        upper = text.upper()
+        lower = text.lower()
+
+        if upper in known_audio_codecs:
+            result[i] = tok.with_role(TokenRole.AUDIO_CODEC)
+            continue
+        if text in known_audio_channels:
+            result[i] = tok.with_role(TokenRole.AUDIO_CHANNELS)
+            continue
+        if upper in known_hdr:
+            result[i] = tok.with_role(TokenRole.HDR)
+            continue
+        if lower in known_bit_depth:
+            result[i] = tok.with_role(TokenRole.BIT_DEPTH)
+            continue
+        if upper in known_editions:
+            result[i] = tok.with_role(TokenRole.EDITION)
+            continue
+        if upper in kb.language_tokens:
+            result[i] = tok.with_role(TokenRole.LANGUAGE)
+            continue
+        if upper in kb.distributors:
+            result[i] = tok.with_role(TokenRole.DISTRIBUTOR)
+            continue
+
+    return result
+
+
+def _apply_sequences(
+    tokens: list[Token],
+    sequences: list[dict],
+    value_key: str,
+    role: TokenRole,
+) -> None:
+    """Mark the first occurrence of each sequence in place.
+
+    Mutates ``tokens`` (replacing entries with new role-tagged Token
+    instances). Sequences in the YAML must be ordered most-specific
+    first; the first match wins per starting position.
+    """
+    if not sequences:
+        return
+
+    upper_texts = [t.text.upper() for t in tokens]
+    consumed: set[int] = set()
+
+    for seq in sequences:
+        seq_upper = [s.upper() for s in seq["tokens"]]
+        n = len(seq_upper)
+        for start in range(len(tokens) - n + 1):
+            if any(idx in consumed for idx in range(start, start + n)):
+                continue
+            if any(
+                tokens[start + k].role is not TokenRole.UNKNOWN for k in range(n)
+            ):
+                continue
+            if upper_texts[start : start + n] == seq_upper:
+                tokens[start] = tokens[start].with_role(
+                    role, sequence=seq[value_key]
+                )
+                for k in range(1, n):
+                    tokens[start + k] = tokens[start + k].with_role(
+                        role, sequence_member="True"
+                    )
+                consumed.update(range(start, start + n))
+
+
+def _detect_channel_pairs(
+    tokens: list[Token], known_channels: set[str]
+) -> None:
+    """Spot two consecutive numeric tokens that form a channel layout.
+
+    Example: ``["5", "1-KTH"]`` → joined ``"5.1"`` (after stripping the
+    ``-GROUP`` suffix on the second). The second token may be the trailing
+    codec-GROUP token, in which case it's already tagged CODEC and we
+    skip — we'd corrupt its role.
+    """
+    for i in range(len(tokens) - 1):
+        first = tokens[i]
+        second = tokens[i + 1]
+        if first.role is not TokenRole.UNKNOWN:
+            continue
+        # Strip a "-GROUP" suffix on the second token before joining.
+        second_text = second.text.split("-")[0]
+        candidate = f"{first.text}.{second_text}"
+        if candidate not in known_channels:
+            continue
+        # Only tag the first token (carries the channel value). The
+        # second token may legitimately remain UNKNOWN (or be the
+        # codec-GROUP token, already tagged CODEC).
+        tokens[i] = first.with_role(
+            TokenRole.AUDIO_CHANNELS, sequence=candidate
+        )
+        if second.role is TokenRole.UNKNOWN:
+            tokens[i + 1] = second.with_role(
+                TokenRole.AUDIO_CHANNELS, sequence_member="True"
+            )
+
+
+# ---------------------------------------------------------------------------
+# Stage 2 entry point
+# ---------------------------------------------------------------------------
+
+
+def annotate(tokens: list[Token], kb: ReleaseKnowledge) -> list[Token]:
+    """Annotate token roles.
+
+    Dispatch:
+
+    * If a group is detected AND has a known schema, run the EASY
+      structural walk. If the schema walk aborts on a mandatory chunk
+      mismatch, fall through to SHITTY (the heuristic still does better
+      than giving up).
+    * Otherwise run SHITTY — schema-less, best-effort, never aborts.
+
+    The enricher pass runs in both cases. The pipeline always returns a
+    populated token list; downstream callers don't need to distinguish
+    EASY vs SHITTY at this layer (the parse_path is decided in the
+    service based on whether a schema matched).
+    """
+    group_name, group_index = _detect_group(tokens, kb)
+
+    schema = kb.group_schema(group_name) if group_index is not None else None
+    if schema is not None and group_index is not None:
+        structural = _annotate_structural(tokens, kb, schema, group_index)
+        if structural is not None:
+            return _annotate_enrichers(structural, kb)
+
+    # SHITTY fallback — heuristic positional pass. ``_annotate_shitty``
+    # runs its own enricher pass internally (it has to, so the title
+    # scan can skip enricher-tagged tokens).
+    return _annotate_shitty(tokens, kb, group_index)
+
+
+def has_known_schema(tokens: list[Token], kb: ReleaseKnowledge) -> bool:
+    """Return True if ``tokens`` would take the EASY path in :func:`annotate`."""
+    group_name, group_index = _detect_group(tokens, kb)
+    if group_index is None:
+        return False
+    return kb.group_schema(group_name) is not None
+
+
+# ---------------------------------------------------------------------------
+# Stage 3 — assemble
+# ---------------------------------------------------------------------------
+
+
+def assemble(
+    annotated: list[Token],
+    site_tag: str | None,
+    raw_name: str,
+    kb: ReleaseKnowledge,
+) -> dict:
+    """Fold annotated tokens into a ``ParsedRelease``-compatible dict.
+
+    Returns a dict (not a ``ParsedRelease`` instance) so the caller can
+    layer in additional fields (``parse_path``, ``raw``, …) before
+    instantiation.
+    """
+    # Pure-punctuation tokens (e.g. a stray "-" left by ` - ` separators in
+    # human-friendly release names) carry no title content and would leak
+    # into the joined title as ``"Show.-.Episode"``. Drop them here.
+    title_parts = [
+        t.text
+        for t in annotated
+        if t.role is TokenRole.TITLE and any(c.isalnum() for c in t.text)
+    ]
+    title = ".".join(title_parts) if title_parts else (
+        annotated[0].text if annotated else raw_name
+    )
+
+    year: int | None = None
+    season: int | None = None
+    episode: int | None = None
+    episode_end: int | None = None
+    quality: str | None = None
+    source: str | None = None
+    codec: str | None = None
+    group = "UNKNOWN"
+    audio_codec: str | None = None
+    audio_channels: str | None = None
+    bit_depth: str | None = None
+    hdr_format: str | None = None
+    edition: str | None = None
+    distributor: str | None = None
+    languages: list[str] = []
+    is_season_range = False
+
+    for tok in annotated:
+        # Skip non-primary members of a multi-token sequence.
+        if tok.extra.get("sequence_member") == "True":
+            continue
+
+        role = tok.role
+        if role is TokenRole.YEAR:
+            year = int(tok.text)
+        elif role is TokenRole.SEASON_EPISODE:
+            parsed = _parse_season_episode(tok.text)
+            if parsed is not None:
+                season, episode, episode_end = parsed
+                # Detect Sxx-yy range form to flag it as a multi-season pack.
+                upper = tok.text.upper()
+                if (
+                    len(upper) == 6
+                    and upper[0] == "S"
+                    and upper[1:3].isdigit()
+                    and upper[3] == "-"
+                    and upper[4:6].isdigit()
+                ):
+                    is_season_range = True
+        elif role is TokenRole.RESOLUTION:
+            quality = tok.text
+        elif role is TokenRole.SOURCE:
+            source = tok.text
+        elif role is TokenRole.CODEC:
+            codec = tok.extra.get("codec", tok.text)
+            if "group" in tok.extra:
+                group = tok.extra["group"] or "UNKNOWN"
+        elif role is TokenRole.GROUP:
+            group = tok.extra.get("group", tok.text) or "UNKNOWN"
+        elif role is TokenRole.AUDIO_CODEC:
+            if audio_codec is None:
+                audio_codec = tok.extra.get("sequence", tok.text)
+        elif role is TokenRole.AUDIO_CHANNELS:
+            if audio_channels is None:
+                audio_channels = tok.extra.get("sequence", tok.text)
+        elif role is TokenRole.BIT_DEPTH:
+            if bit_depth is None:
+                bit_depth = tok.text.lower()
+        elif role is TokenRole.HDR:
+            if hdr_format is None:
+                hdr_format = tok.extra.get("sequence", tok.text.upper())
+        elif role is TokenRole.EDITION:
+            if edition is None:
+                edition = tok.extra.get("sequence", tok.text.upper())
+        elif role is TokenRole.LANGUAGE:
+            languages.append(tok.text.upper())
+        elif role is TokenRole.DISTRIBUTOR:
+            if distributor is None:
+                distributor = tok.text.upper()
+
+    # Media type heuristic. Doc/concert/integrale tokens win over the
+    # generic tech-based fallback. We look across all tokens (not just
+    # annotated ones) because these markers may be tagged UNKNOWN by the
+    # structural pass — only the assemble step cares about them.
+    upper_tokens = {tok.text.upper() for tok in annotated}
+    doc_tokens = {t.upper() for t in kb.media_type_tokens.get("doc", [])}
+    concert_tokens = {t.upper() for t in kb.media_type_tokens.get("concert", [])}
+    integrale_tokens = {t.upper() for t in kb.media_type_tokens.get("integrale", [])}
+
+    if upper_tokens & doc_tokens:
+        media_type = MediaTypeToken.DOCUMENTARY
+    elif upper_tokens & concert_tokens:
+        media_type = MediaTypeToken.CONCERT
+    elif is_season_range:
+        media_type = MediaTypeToken.TV_COMPLETE
+    elif (
+        edition in {"COMPLETE", "INTEGRALE", "COLLECTION"}
+        or upper_tokens & integrale_tokens
+    ) and season is None:
+        media_type = MediaTypeToken.TV_COMPLETE
+    elif season is not None:
+        media_type = MediaTypeToken.TV_SHOW
+    elif any((quality, source, codec, year)):
+        media_type = MediaTypeToken.MOVIE
+    else:
+        media_type = MediaTypeToken.UNKNOWN
+
+    return {
+        "title": title,
+        "title_sanitized": kb.sanitize_for_fs(title),
+        "year": year,
+        "season": season,
+        "episode": episode,
+        "episode_end": episode_end,
+        "quality": quality,
+        "source": source,
+        "codec": codec,
+        "group": group,
+        "media_type": media_type,
+        "site_tag": site_tag,
+        "languages": tuple(languages),
+        "audio_codec": audio_codec,
+        "audio_channels": audio_channels,
+        "bit_depth": bit_depth,
+        "hdr_format": hdr_format,
+        "edition": edition,
+        "distributor": distributor,
+    }

alfred/domain/release/parser/schema.py

@@ -0,0 +1,47 @@
+"""Group schema value objects.
+
+A :class:`GroupSchema` describes the canonical chunk layout of releases
+from a known group (KONTRAST, RARBG, ELiTE, …). It is the EASY-road
+contract: when a release ends in ``-<GROUP>`` and we know the group,
+the annotator walks the schema instead of running the heuristic SHITTY
+matchers.
+
+Schemas are loaded from ``knowledge/release/release_groups/<group>.yaml``
+by an infrastructure adapter and surfaced via the
+:class:`~alfred.domain.release.ports.knowledge.ReleaseKnowledge` port.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .tokens import TokenRole
+
+
+@dataclass(frozen=True)
+class SchemaChunk:
+    """One entry in a group's chunk order.
+
+    ``role`` is the :class:`TokenRole` the chunk maps to. ``optional``
+    is True for chunks that may be absent (e.g. ``year`` on TV releases,
+    ``source`` on bare ELiTE TV releases).
+    """
+
+    role: TokenRole
+    optional: bool = False
+
+
+@dataclass(frozen=True)
+class GroupSchema:
+    """Schema for a known release group.
+
+    ``chunks`` is the left-to-right canonical order. The annotator walks
+    tokens and chunks in lockstep: an optional chunk that doesn't match
+    the current token is skipped (the chunk index advances, the token
+    index stays), a mandatory chunk that doesn't match aborts the EASY
+    path and falls back to SHITTY.
+    """
+
+    name: str
+    separator: str
+    chunks: tuple[SchemaChunk, ...]

alfred/domain/release/parser/scoring.py

@@ -0,0 +1,139 @@
+"""Parse-confidence scoring.
+
+``parse_release`` returns a :class:`ParseReport` alongside its
+:class:`ParsedRelease`. The report carries:
+
+- ``confidence``: integer 0–100 derived from which structural and
+  technical fields got populated, minus a penalty per UNKNOWN token
+  left in the annotated stream.
+- ``road``: which of the three roads the parse took
+  (:class:`Road.EASY` / :class:`Road.SHITTY` / :class:`Road.PATH_OF_PAIN`).
+- ``unknown_tokens``: textual residue, useful for diagnostics.
+- ``missing_critical``: structural fields the score-tally found absent
+  (e.g. ``("year", "media_type")``) — the caller can use this to drive
+  PoP recovery (questions, LLM call).
+
+All weights, penalties and thresholds come from the injected knowledge
+base (``kb.scoring``), itself loaded from
+``alfred/knowledge/release/scoring.yaml``. No magic numbers here.
+
+The scoring functions are pure — they consume the annotated token list
+and the resulting :class:`ParsedRelease` and return the report. They are
+called by ``services.parse_release`` after ``assemble`` has run.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from ..ports.knowledge import ReleaseKnowledge
+from ..value_objects import ParsedRelease
+from .tokens import Token, TokenRole
+
+
+class Road(str, Enum):
+    """How the parser handled a given release name.
+
+    Distinct from :class:`~alfred.domain.release.value_objects.TokenizationRoute`,
+    which records the tokenization route (DIRECT / SANITIZED / AI). Road
+    is about confidence in the *result*, not the *method*.
+    """
+
+    EASY = "easy"  # group schema matched — structural annotation
+    SHITTY = "shitty"  # no schema, dict-driven annotation, score ≥ threshold
+    PATH_OF_PAIN = "path_of_pain"  # score below threshold, needs help
+
+
+# Critical structural fields — their absence drives the
+# ``missing_critical`` list in the report.
+_CRITICAL_FIELDS: tuple[str, ...] = ("title", "media_type", "year")
+
+
+def _is_tv_shaped(parsed: ParsedRelease) -> bool:
+    """Season/episode weights only count for releases that *look* like TV."""
+    return parsed.season is not None
+
+
+def compute_score(
+    parsed: ParsedRelease,
+    annotated: list[Token],
+    kb: ReleaseKnowledge,
+) -> int:
+    """Compute a 0–100 confidence score for the parse.
+
+    Each populated field contributes its weight from
+    ``kb.scoring["weights"]``. Season/episode only count when the parse
+    looks like TV. ``group == "UNKNOWN"`` is treated as absent.
+
+    Then a penalty is subtracted per residual UNKNOWN token in
+    ``annotated``, capped at ``penalties["max_unknown_penalty"]``.
+
+    Result is clamped to ``[0, 100]``.
+    """
+    weights = kb.scoring["weights"]
+    penalties = kb.scoring["penalties"]
+
+    score = 0
+    if parsed.title:
+        score += weights.get("title", 0)
+    if parsed.media_type and parsed.media_type.value != "unknown":
+        score += weights.get("media_type", 0)
+    if parsed.year is not None:
+        score += weights.get("year", 0)
+    if _is_tv_shaped(parsed):
+        if parsed.season is not None:
+            score += weights.get("season", 0)
+        if parsed.episode is not None:
+            score += weights.get("episode", 0)
+    if parsed.quality:
+        score += weights.get("resolution", 0)
+    if parsed.source:
+        score += weights.get("source", 0)
+    if parsed.codec:
+        score += weights.get("codec", 0)
+    if parsed.group and parsed.group != "UNKNOWN":
+        score += weights.get("group", 0)
+
+    unknown_count = sum(1 for t in annotated if t.role is TokenRole.UNKNOWN)
+    raw_penalty = unknown_count * penalties.get("unknown_token", 0)
+    capped_penalty = min(raw_penalty, penalties.get("max_unknown_penalty", 0))
+    score -= capped_penalty
+
+    return max(0, min(100, score))
+
+
+def collect_unknown_tokens(annotated: list[Token]) -> tuple[str, ...]:
+    """Return the text of every token still tagged UNKNOWN."""
+    return tuple(t.text for t in annotated if t.role is TokenRole.UNKNOWN)
+
+
+def collect_missing_critical(parsed: ParsedRelease) -> tuple[str, ...]:
+    """Return the names of critical structural fields that are absent."""
+    missing: list[str] = []
+    if not parsed.title:
+        missing.append("title")
+    if not parsed.media_type or parsed.media_type.value == "unknown":
+        missing.append("media_type")
+    if parsed.year is None:
+        missing.append("year")
+    return tuple(missing)
+
+
+def decide_road(
+    score: int,
+    has_schema: bool,
+    kb: ReleaseKnowledge,
+) -> Road:
+    """Pick the road the parse took.
+
+    EASY is decided structurally: if a known group schema matched, the
+    annotation walked the schema, and that's enough — the score does not
+    veto EASY. Otherwise the score decides between SHITTY and
+    PATH_OF_PAIN using ``kb.scoring["thresholds"]["shitty_min"]``.
+    """
+    if has_schema:
+        return Road.EASY
+    threshold = kb.scoring["thresholds"].get("shitty_min", 60)
+    if score >= threshold:
+        return Road.SHITTY
+    return Road.PATH_OF_PAIN

alfred/domain/release/parser/tokens.py

@@ -0,0 +1,90 @@
+"""Token value objects for the annotate-based parser.
+
+A :class:`Token` carries both the original substring and its position in
+the original release name's token stream. A :class:`TokenRole` is the
+semantic tag assigned by the annotator.
+
+Why VOs instead of bare ``str``: the annotate step needs to flag tokens
+without consuming them (a token may carry residual info — e.g. a
+``codec-GROUP`` token contributes both a CODEC and a GROUP role). Tracking
+the index also lets later stages reason about *order* (year must come
+after title, group must be rightmost, etc.) without re-scanning the list.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class TokenRole(str, Enum):
+    """Semantic role a token can take after annotation.
+
+    A token starts as ``UNKNOWN`` and may be promoted by the annotator.
+    ``str``-backed for cheap comparisons and YAML/JSON interop.
+
+    Roles split into three families:
+
+    - **structural**: TITLE / YEAR / SEASON_EPISODE / GROUP — drive folder
+      and filename naming.
+    - **technical**: RESOLUTION / SOURCE / CODEC / AUDIO_CODEC /
+      AUDIO_CHANNELS / BIT_DEPTH / HDR / EDITION / LANGUAGE — feed
+      ``tech_string`` and metadata fields.
+    - **meta**: SITE_TAG (stripped pre-tokenize), SEPARATOR (kept for the
+      assemble step if a release uses spaces that need preservation in the
+      title), UNKNOWN (residual, contributes to the SHITTY score penalty).
+    """
+
+    UNKNOWN = "unknown"
+
+    # Structural
+    TITLE = "title"
+    YEAR = "year"
+    SEASON_EPISODE = "season_episode"
+    GROUP = "group"
+
+    # Technical
+    RESOLUTION = "resolution"
+    SOURCE = "source"
+    CODEC = "codec"
+    AUDIO_CODEC = "audio_codec"
+    AUDIO_CHANNELS = "audio_channels"
+    BIT_DEPTH = "bit_depth"
+    HDR = "hdr"
+    EDITION = "edition"
+    LANGUAGE = "language"
+    DISTRIBUTOR = "distributor"
+
+    # Meta
+    SITE_TAG = "site_tag"
+
+
+@dataclass(frozen=True)
+class Token:
+    """An atomic token from a release name.
+
+    ``text`` is the substring exactly as it appeared after tokenization
+    (case preserved — uppercase comparisons happen at match time).
+    ``index`` is the 0-based position in the tokenized stream, used by
+    downstream stages to enforce ordering invariants.
+
+    ``role`` defaults to :attr:`TokenRole.UNKNOWN`. The annotator returns
+    new :class:`Token` instances with the role set rather than mutating
+    (the dataclass is frozen). ``extra`` carries role-specific payload
+    when the token text alone isn't enough (e.g. a ``codec-GROUP`` token
+    annotated as CODEC may record the group name in ``extra["group"]``).
+    """
+
+    text: str
+    index: int
+    role: TokenRole = TokenRole.UNKNOWN
+    extra: dict[str, str] = field(default_factory=dict)
+
+    def with_role(self, role: TokenRole, **extra: str) -> Token:
+        """Return a copy of this token with ``role`` (and optional ``extra``)."""
+        merged = {**self.extra, **extra} if extra else self.extra
+        return Token(text=self.text, index=self.index, role=role, extra=merged)
+
+    @property
+    def is_annotated(self) -> bool:
+        return self.role is not TokenRole.UNKNOWN

alfred/domain/release/ports/__init__.py

@@ -0,0 +1,10 @@
+"""Domain ports for the release domain.
+
+Protocol-based abstractions that decouple ``parse_release`` and
+``ParsedRelease`` from any concrete knowledge-base loader. The
+infrastructure layer provides the adapter that satisfies this contract.
+"""
+
+from .knowledge import ReleaseKnowledge
+
+__all__ = ["ReleaseKnowledge"]

alfred/domain/release/ports/knowledge.py

@@ -0,0 +1,91 @@
+"""ReleaseKnowledge port — the read-only query surface that
+``parse_release`` and ``ParsedRelease`` need from the release knowledge
+base, expressed as a structural Protocol so the domain never imports any
+concrete loader.
+
+The concrete YAML-backed implementation lives in
+``alfred/infrastructure/knowledge/release_kb.py``. Tests can supply any
+object that satisfies this shape (e.g. a simple dataclass).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from ..parser.schema import GroupSchema
+
+
+class ReleaseKnowledge(Protocol):
+    """Read-only snapshot of release-name parsing knowledge."""
+
+    # --- Token sets used by the tokenizer / matchers ---
+
+    resolutions: set[str]
+    sources: set[str]
+    codecs: set[str]
+    distributors: set[str]
+    language_tokens: set[str]
+    forbidden_chars: set[str]
+    hdr_extra: set[str]
+
+    # --- Structured knowledge (loaded from YAML as dicts) ---
+
+    audio: dict
+    video_meta: dict
+    editions: dict
+    media_type_tokens: dict
+
+    # --- Tokenizer separators ---
+
+    separators: list[str]
+
+    # --- Parse scoring (Phase A) ---
+    #
+    # ``scoring`` is a dict with three keys:
+    #   - ``weights``:     dict[field_name, int]   field weight contribution
+    #   - ``penalties``:   {"unknown_token": int, "max_unknown_penalty": int}
+    #   - ``thresholds``:  {"shitty_min": int}     SHITTY vs PATH_OF_PAIN cutoff
+    #
+    # Concrete values come from ``alfred/knowledge/release/scoring.yaml``.
+    # The loader fills in safe defaults so this dict is always populated.
+
+    scoring: dict
+
+    # --- ffprobe → scene-token translation tables (consumed by
+    #     ``application.release.enrich_from_probe``). Domain parsing itself
+    #     doesn't touch these — exposed on the same KB to keep release
+    #     knowledge in a single ownership point.
+    #
+    #     Shape:
+    #       - ``video_codec``:    dict[str, str]   ffprobe lower → scene token
+    #       - ``audio_codec``:    dict[str, str]   ffprobe lower → scene token
+    #       - ``audio_channels``: dict[int, str]   channel count → layout ---
+
+    probe_mappings: dict
+
+    # --- File-extension sets (used by application/infra modules that work
+    #     directly with filesystem paths, e.g. media-type detection, video
+    #     lookup). Domain parsing itself doesn't touch these. ---
+
+    video_extensions: set[str]
+    non_video_extensions: set[str]
+    subtitle_extensions: set[str]
+    metadata_extensions: set[str]
+
+    # --- Filesystem sanitization (Option B: pre-sanitize at parse time) ---
+
+    def sanitize_for_fs(self, text: str) -> str:
+        """Strip filesystem-forbidden characters from ``text``."""
+        ...
+
+    # --- Release group schemas (EASY path) ---
+
+    def group_schema(self, name: str) -> GroupSchema | None:
+        """Return the parsing schema for the named release group, or
+        ``None`` if the group is unknown (caller falls back to SHITTY).
+
+        Lookup is case-insensitive: ``"KONTRAST"``, ``"kontrast"`` and
+        ``"Kontrast"`` all resolve to the same schema.
+        """
+        ...

alfred/domain/release/services.py

@@ -0,0 +1,121 @@
+"""Release domain — parsing service.
+
+Thin orchestrator over the annotate-based pipeline in
+:mod:`alfred.domain.release.parser.pipeline`. Responsibilities:
+
+* Strip a leading/trailing ``[site.tag]`` and decide ``parse_path``.
+* Reject malformed names (forbidden characters) → ``parse_path=AI`` so
+  the LLM can clean them up.
+* Otherwise call the v2 pipeline (tokenize → annotate → assemble) and
+  wrap the result in :class:`ParsedRelease`.
+* Score the result and decide the road (EASY / SHITTY / PATH_OF_PAIN)
+  via :mod:`alfred.domain.release.parser.scoring`.
+
+The public entry point is :func:`parse_release`, which returns
+``(ParsedRelease, ParseReport)``. The report carries the confidence
+score, the road, and diagnostic info for downstream callers.
+"""
+
+from __future__ import annotations
+
+from .parser import pipeline as _v2
+from .parser import scoring as _scoring
+from .ports import ReleaseKnowledge
+from .value_objects import MediaTypeToken, ParsedRelease, ParseReport, TokenizationRoute
+
+
+def parse_release(
+    name: str, kb: ReleaseKnowledge
+) -> tuple[ParsedRelease, ParseReport]:
+    """Parse a release name.
+
+    Returns a tuple ``(ParsedRelease, ParseReport)``. The structural VO
+    is unchanged from the previous single-return contract; the report
+    is new and carries the confidence score + road decision.
+
+    Flow:
+
+    1. Strip a leading/trailing ``[site.tag]`` if present (sets
+       ``parse_path="sanitized"``).
+    2. If the remainder still contains truly forbidden chars (anything
+       not in the configured separators), short-circuit to
+       ``media_type="unknown"`` / ``parse_path="ai"`` and emit a
+       PATH_OF_PAIN report — the LLM handles these.
+    3. Otherwise run the v2 pipeline: tokenize → annotate (EASY when a
+       group schema is known, SHITTY otherwise) → assemble → score.
+    """
+    parse_path = TokenizationRoute.DIRECT
+
+    # Apostrophes inside titles ("Don't", "L'avare") are common and should
+    # not push the release through the AI fallback. Strip them up front so
+    # both strip_site_tag and tokenize see "Dont" / "Lavare", which is good
+    # enough for token-level matching. The raw name is preserved on the VO.
+    working_name = name
+    if "'" in working_name:
+        working_name = working_name.replace("'", "")
+        parse_path = TokenizationRoute.SANITIZED
+
+    clean, site_tag = _v2.strip_site_tag(working_name)
+    if site_tag is not None:
+        parse_path = TokenizationRoute.SANITIZED
+
+    if not _is_well_formed(clean, kb):
+        parsed = ParsedRelease(
+            raw=name,
+            clean=clean,
+            title=clean,
+            title_sanitized=kb.sanitize_for_fs(clean),
+            year=None,
+            season=None,
+            episode=None,
+            episode_end=None,
+            quality=None,
+            source=None,
+            codec=None,
+            group="UNKNOWN",
+            media_type=MediaTypeToken.UNKNOWN,
+            site_tag=site_tag,
+            parse_path=TokenizationRoute.AI,
+        )
+        report = ParseReport(
+            confidence=0,
+            road=_scoring.Road.PATH_OF_PAIN.value,
+            unknown_tokens=(clean,),
+            missing_critical=("title", "media_type", "year"),
+        )
+        return parsed, report
+
+    tokens, v2_tag = _v2.tokenize(working_name, kb)
+    annotated = _v2.annotate(tokens, kb)
+    fields = _v2.assemble(annotated, v2_tag, name, kb)
+
+    parsed = ParsedRelease(
+        raw=name,
+        clean=clean,
+        parse_path=parse_path,
+        **fields,
+    )
+
+    has_schema = _v2.has_known_schema(tokens, kb)
+    score = _scoring.compute_score(parsed, annotated, kb)
+    road = _scoring.decide_road(score, has_schema, kb)
+    report = ParseReport(
+        confidence=score,
+        road=road.value,
+        unknown_tokens=_scoring.collect_unknown_tokens(annotated),
+        missing_critical=_scoring.collect_missing_critical(parsed),
+    )
+    return parsed, report
+
+
+def _is_well_formed(name: str, kb: ReleaseKnowledge) -> bool:
+    """Return True if ``name`` contains no forbidden characters per scene
+    naming rules.
+
+    Characters listed as token separators (spaces, brackets, parens, …)
+    are NOT considered malforming — the tokenizer handles them. Only
+    truly broken chars like ``@``, ``#``, ``!``, ``%`` make a name
+    malformed.
+    """
+    tokenizable = set(kb.separators)
+    return not any(c in name for c in kb.forbidden_chars if c not in tokenizable)

alfred/domain/release/value_objects.py

@@ -0,0 +1,271 @@
+"""Release domain — value objects.
+
+This module is **pure**: no I/O, no YAML loading, no knowledge-base
+imports. All knowledge that the parser consumes is injected at runtime
+via the ``ReleaseKnowledge`` port (see ``ports/knowledge.py``).
+
+``ParsedRelease`` follows Option B of the snapshot-VO design: filesystem
+sanitization is performed once at parse time and stored in
+``title_sanitized``. The builder methods (``show_folder_name``,
+``episode_filename``, etc.) are therefore pure string-formatting and do
+**not** need access to any knowledge base — but they require the caller
+to pass already-sanitized TMDB strings. The use case is responsible for
+calling ``kb.sanitize_for_fs(tmdb_title)`` before invoking the builders.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from ..shared.exceptions import ValidationError
+
+
+class MediaTypeToken(str, Enum):
+    """
+    Canonical values for ``ParsedRelease.media_type``.
+
+    Inherits from ``str`` so existing string-based comparisons (``== "movie"``,
+    JSON serialization, TMDB DTO interop) keep working unchanged. The enum
+    serves both as documentation and as the set of valid values for
+    ``__post_init__`` validation.
+    """
+
+    MOVIE = "movie"
+    TV_SHOW = "tv_show"
+    TV_COMPLETE = "tv_complete"
+    DOCUMENTARY = "documentary"
+    CONCERT = "concert"
+    OTHER = "other"
+    UNKNOWN = "unknown"
+
+
+class TokenizationRoute(str, Enum):
+    """How a ``ParsedRelease`` was produced.
+
+    Records the **tokenization route** — i.e. whether the release name
+    was tokenized as-is (``DIRECT``), after a sanitization pass like
+    site-tag stripping or apostrophe removal (``SANITIZED``), or whether
+    structural parsing failed and an LLM rebuild is needed (``AI``).
+
+    This is **orthogonal** to :class:`~alfred.domain.release.parser.scoring.Road`
+    (EASY / SHITTY / PATH_OF_PAIN), which captures parser confidence and
+    is recorded on :class:`ParseReport`. Both can vary independently —
+    a SANITIZED name can still land on the EASY road if a group schema
+    matches the tokens after stripping.
+
+    ``str``-backed for the same reasons as :class:`MediaTypeToken`."""
+
+    DIRECT = "direct"
+    SANITIZED = "sanitized"
+    AI = "ai"
+
+
+def _strip_episode_from_normalized(normalized: str) -> str:
+    """
+    Remove all episode parts (Exx) from a normalized release name, keeping Sxx.
+
+    Oz.S03E01.1080p...             → Oz.S03.1080p...
+    Archer.S14E09E10E11.1080p...   → Archer.S14.1080p...
+    """
+    tokens = normalized.split(".")
+    result = []
+    for tok in tokens:
+        upper = tok.upper()
+        # Token is SxxExx... — keep only the Sxx part
+        if len(upper) >= 3 and upper[0] == "S" and upper[1:3].isdigit():
+            result.append(tok[:3])  # "S" + two digits
+        else:
+            result.append(tok)
+    return ".".join(result)
+
+
+@dataclass(frozen=True)
+class ParseReport:
+    """Diagnostic report attached to a :class:`ParsedRelease`.
+
+    ``parse_release`` returns ``(ParsedRelease, ParseReport)``. The
+    report describes *how confident* the parser is in the result and
+    *which road* produced it. It is intentionally separate from
+    ``ParsedRelease`` so the structural VO stays free of meta-concerns
+    about its own quality.
+
+    Fields:
+
+    - ``confidence``: integer 0–100 (see :func:`parser.scoring.compute_score`).
+    - ``road``: ``"easy"`` / ``"shitty"`` / ``"path_of_pain"`` — distinct
+      from ``ParsedRelease.parse_path`` (which describes the
+      tokenization route, not the confidence tier).
+    - ``unknown_tokens``: tokens that finished annotation with role
+      UNKNOWN, in order of appearance.
+    - ``missing_critical``: names of critical structural fields the
+      parser couldn't fill (subset of ``{"title", "media_type", "year"}``).
+    """
+
+    confidence: int
+    road: str  # one of parser.scoring.Road values
+    unknown_tokens: tuple[str, ...] = ()
+    missing_critical: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not (0 <= self.confidence <= 100):
+            raise ValidationError(
+                f"ParseReport.confidence out of range: {self.confidence}"
+            )
+
+
+@dataclass(frozen=True)
+class ParsedRelease:
+    """Structured representation of a parsed release name.
+
+    ``title_sanitized`` carries the filesystem-safe form of ``title`` (computed
+    by the parser at construction time using the injected knowledge base).
+    Builder methods rely on it being already-sanitized — see module docstring.
+
+    Frozen: enrichment passes (``detect_media_type``, ``enrich_from_probe``)
+    return a **new** ``ParsedRelease`` via ``dataclasses.replace`` rather
+    than mutating in place. ``languages`` is a tuple for the same reason.
+    """
+
+    raw: str  # original release name (untouched)
+    clean: str  # raw minus site_tag and apostrophes — used by season_folder_name()
+    title: str  # show/movie title (dots, no year/season/tech)
+    title_sanitized: str  # title with filesystem-forbidden chars stripped
+    year: int | None  # movie year or show start year (from TMDB)
+    season: int | None  # season number (None for movies)
+    episode: int | None  # first episode number (None if season-pack)
+    episode_end: int | None  # last episode for multi-ep (None otherwise)
+    quality: str | None  # 1080p, 2160p, …
+    source: str | None  # WEBRip, BluRay, …
+    codec: str | None  # x265, HEVC, …
+    group: str  # release group, "UNKNOWN" if missing
+    media_type: MediaTypeToken = MediaTypeToken.UNKNOWN
+    site_tag: str | None = (
+        None  # site watermark stripped from name, e.g. "TGx", "OxTorrent.vc"
+    )
+    parse_path: TokenizationRoute = TokenizationRoute.DIRECT
+    languages: tuple[str, ...] = ()  # ("MULTI", "VFF"), ("FRENCH",), …
+    audio_codec: str | None = None  # "DTS-HD.MA", "DDP", "EAC3", …
+    audio_channels: str | None = None  # "5.1", "7.1", "2.0", …
+    bit_depth: str | None = None  # "10bit", "8bit", …
+    hdr_format: str | None = None  # "DV", "HDR10", "DV.HDR10", …
+    edition: str | None = None  # "UNRATED", "EXTENDED", "DIRECTORS.CUT", …
+    distributor: str | None = None  # "NF", "AMZN", "DSNP", … (streaming origin)
+
+    def __post_init__(self) -> None:
+        if not self.raw:
+            raise ValidationError("ParsedRelease.raw cannot be empty")
+        if not self.group:
+            raise ValidationError("ParsedRelease.group cannot be empty")
+        if self.year is not None and not (1888 <= self.year <= 2100):
+            raise ValidationError(
+                f"ParsedRelease.year out of range: {self.year}"
+            )
+        if self.season is not None and not (0 <= self.season <= 100):
+            raise ValidationError(
+                f"ParsedRelease.season out of range: {self.season}"
+            )
+        if self.episode is not None and not (0 <= self.episode <= 9999):
+            raise ValidationError(
+                f"ParsedRelease.episode out of range: {self.episode}"
+            )
+        if self.episode_end is not None:
+            if not (0 <= self.episode_end <= 9999):
+                raise ValidationError(
+                    f"ParsedRelease.episode_end out of range: {self.episode_end}"
+                )
+            if self.episode is not None and self.episode_end < self.episode:
+                raise ValidationError(
+                    f"ParsedRelease.episode_end ({self.episode_end}) < "
+                    f"episode ({self.episode})"
+                )
+        if not isinstance(self.media_type, MediaTypeToken):
+            raise ValidationError(
+                f"ParsedRelease.media_type must be a MediaTypeToken, "
+                f"got {type(self.media_type).__name__}: {self.media_type!r}"
+            )
+        if not isinstance(self.parse_path, TokenizationRoute):
+            raise ValidationError(
+                f"ParsedRelease.parse_path must be a TokenizationRoute, "
+                f"got {type(self.parse_path).__name__}: {self.parse_path!r}"
+            )
+
+    @property
+    def is_season_pack(self) -> bool:
+        return self.season is not None and self.episode is None
+
+    @property
+    def tech_string(self) -> str:
+        """``quality.source.codec`` joined by dots, skipping ``None`` parts.
+
+        Derived on every access so it stays in sync with the underlying
+        fields — no manual refresh needed after enrichment.
+        """
+        return ".".join(p for p in (self.quality, self.source, self.codec) if p)
+
+    def show_folder_name(self, tmdb_title_safe: str, tmdb_year: int) -> str:
+        """
+        Build the series root folder name.
+
+        Format: {Title}.{Year}.{Tech}-{Group}
+        Example: Oz.1997.1080p.WEBRip.x265-KONTRAST
+
+        ``tmdb_title_safe`` must already be filesystem-safe (the caller is
+        expected to have run it through ``kb.sanitize_for_fs``).
+        """
+        title_part = tmdb_title_safe.replace(" ", ".")
+        tech = self.tech_string or "Unknown"
+        return f"{title_part}.{tmdb_year}.{tech}-{self.group}"
+
+    def season_folder_name(self) -> str:
+        """
+        Build the season subfolder name = normalized release name (no episode).
+
+        Example: Oz.S03.1080p.WEBRip.x265-KONTRAST
+        For a single-episode release we still strip the episode token so the
+        folder can hold the whole season.
+        """
+        return _strip_episode_from_normalized(self.clean)
+
+    def episode_filename(self, tmdb_episode_title_safe: str | None, ext: str) -> str:
+        """
+        Build the episode filename.
+
+        Format: {Title}.{SxxExx}.{EpisodeTitle}.{Tech}-{Group}.{ext}
+        Example: Oz.S01E01.The.Routine.1080p.WEBRip.x265-KONTRAST.mkv
+
+        ``tmdb_episode_title_safe`` must already be filesystem-safe; pass
+        ``None`` to omit the episode title segment.
+        """
+        title_part = self.title_sanitized
+        s = f"S{self.season:02d}" if self.season is not None else ""
+        e = f"E{self.episode:02d}" if self.episode is not None else ""
+        se = s + e
+
+        ep_title = ""
+        if tmdb_episode_title_safe:
+            ep_title = "." + tmdb_episode_title_safe.replace(" ", ".")
+
+        tech = self.tech_string or "Unknown"
+        ext_clean = ext.lstrip(".")
+        return f"{title_part}.{se}{ep_title}.{tech}-{self.group}.{ext_clean}"
+
+    def movie_folder_name(self, tmdb_title_safe: str, tmdb_year: int) -> str:
+        """
+        Build the movie folder name.
+
+        Format: {Title}.{Year}.{Tech}-{Group}
+        Example: Inception.2010.1080p.BluRay.x265-GROUP
+        """
+        return self.show_folder_name(tmdb_title_safe, tmdb_year)
+
+    def movie_filename(
+        self, tmdb_title_safe: str, tmdb_year: int, ext: str
+    ) -> str:
+        """
+        Build the movie filename (same as folder name + extension).
+
+        Example: Inception.2010.1080p.BluRay.x265-GROUP.mkv
+        """
+        ext_clean = ext.lstrip(".")
+        return f"{self.movie_folder_name(tmdb_title_safe, tmdb_year)}.{ext_clean}"

alfred/domain/shared/__init__.py

@@ -1,7 +1,7 @@
 """Shared kernel - Common domain concepts used across subdomains."""
 
 from .exceptions import DomainException, ValidationError
-from .value_objects import FilePath, FileSize, ImdbId
+from .value_objects import FilePath, FileSize, ImdbId, Language
 
 __all__ = [
     "DomainException",
@@ -9,4 +9,5 @@ __all__ = [
     "ImdbId",
     "FilePath",
     "FileSize",
+    "Language",
 ]

alfred/domain/shared/media.py

@@ -0,0 +1,267 @@
+"""Media — file-level track types (video/audio/subtitle) and MediaInfo container.
+
+These are the **container-view** dataclasses, populated from ffprobe output and
+used across the project to describe the content of a media file.
+
+Not to be confused with ``alfred.domain.subtitles.entities.SubtitleScanResult``
+which models a subtitle being **scanned/matched** (with confidence, raw tokens,
+file path, etc.). The two coexist by design — they describe the same real-world
+concept seen from two different bounded contexts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .value_objects import Language
+
+__all__ = [
+    "AudioTrack",
+    "MediaInfo",
+    "MediaWithTracks",
+    "SubtitleTrack",
+    "VideoTrack",
+    "track_lang_matches",
+]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Track types — one frozen dataclass per stream kind
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class AudioTrack:
+    """A single audio track as reported by ffprobe."""
+
+    index: int
+    codec: str | None  # aac, ac3, eac3, dts, truehd, flac, …
+    channels: int | None  # 2, 6 (5.1), 8 (7.1), …
+    channel_layout: str | None  # stereo, 5.1, 7.1, …
+    language: str | None  # ISO 639-2: fre, eng, und, …
+    is_default: bool = False
+
+
+@dataclass(frozen=True)
+class SubtitleTrack:
+    """A single embedded subtitle track as reported by ffprobe."""
+
+    index: int
+    codec: str | None  # subrip, ass, hdmv_pgs_subtitle, …
+    language: str | None  # ISO 639-2: fre, eng, und, …
+    is_default: bool = False
+    is_forced: bool = False
+
+
+@dataclass(frozen=True)
+class VideoTrack:
+    """A single video track as reported by ffprobe.
+
+    A media file typically has one video track but can have several (alt
+    camera angles, attached thumbnail images reported as still-image streams,
+    etc.), hence the list[VideoTrack] on MediaInfo.
+    """
+
+    index: int
+    codec: str | None  # h264, hevc, av1, …
+    width: int | None
+    height: int | None
+    is_default: bool = False
+
+    @property
+    def resolution(self) -> str | None:
+        """
+        Best-effort resolution string: 2160p, 1080p, 720p, …
+
+        Width takes priority over height to handle widescreen/cinema crops
+        (e.g. 1920×960 scope → 1080p, not 720p). Falls back to height when
+        width is unavailable.
+        """
+        match (self.width, self.height):
+            case (None, None):
+                return None
+            case (w, h) if w is not None:
+                match True:
+                    case _ if w >= 3840:
+                        return "2160p"
+                    case _ if w >= 1920:
+                        return "1080p"
+                    case _ if w >= 1280:
+                        return "720p"
+                    case _ if w >= 720:
+                        return "576p"
+                    case _ if w >= 640:
+                        return "480p"
+                    case _:
+                        return f"{h}p" if h else f"{w}w"
+            case (None, h):
+                match True:
+                    case _ if h >= 2160:
+                        return "2160p"
+                    case _ if h >= 1080:
+                        return "1080p"
+                    case _ if h >= 720:
+                        return "720p"
+                    case _ if h >= 576:
+                        return "576p"
+                    case _ if h >= 480:
+                        return "480p"
+                    case _:
+                        return f"{h}p"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# MediaInfo — assembles video/audio/subtitle tracks for a media file
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class MediaInfo:
+    """
+    File-level media metadata extracted by ffprobe — immutable snapshot.
+
+    Symmetric design: every stream type is a tuple of typed track objects
+    (immutable on purpose — a MediaInfo is a frozen view of one ffprobe run,
+    not a mutable collection to append to).
+    Backwards-compatible flat accessors (``resolution``, ``width``, …) read
+    from the first video track when present.
+    """
+
+    video_tracks: tuple[VideoTrack, ...] = field(default_factory=tuple)
+    audio_tracks: tuple[AudioTrack, ...] = field(default_factory=tuple)
+    subtitle_tracks: tuple[SubtitleTrack, ...] = field(default_factory=tuple)
+
+    # File-level (from ffprobe ``format`` block, not from any single stream)
+    duration_seconds: float | None = None
+    bitrate_kbps: int | None = None
+
+    # ──────────────────────────────────────────────────────────────────────
+    # Video conveniences — read the first video track
+    # ──────────────────────────────────────────────────────────────────────
+
+    @property
+    def primary_video(self) -> VideoTrack | None:
+        return self.video_tracks[0] if self.video_tracks else None
+
+    @property
+    def width(self) -> int | None:
+        v = self.primary_video
+        return v.width if v else None
+
+    @property
+    def height(self) -> int | None:
+        v = self.primary_video
+        return v.height if v else None
+
+    @property
+    def video_codec(self) -> str | None:
+        v = self.primary_video
+        return v.codec if v else None
+
+    @property
+    def resolution(self) -> str | None:
+        v = self.primary_video
+        return v.resolution if v else None
+
+    # ──────────────────────────────────────────────────────────────────────
+    # Audio conveniences
+    # ──────────────────────────────────────────────────────────────────────
+
+    @property
+    def audio_languages(self) -> list[str]:
+        """Unique audio languages across all tracks (ISO 639-2)."""
+        seen: set[str] = set()
+        result: list[str] = []
+        for track in self.audio_tracks:
+            if track.language and track.language not in seen:
+                seen.add(track.language)
+                result.append(track.language)
+        return result
+
+    @property
+    def is_multi_audio(self) -> bool:
+        """True if more than one audio language is present."""
+        return len(self.audio_languages) > 1
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Language matching — shared helper + mixin
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def track_lang_matches(track_lang: str | None, query: str | Language) -> bool:
+    """
+    Match a track's language string against a query (contract "C+").
+
+      * ``Language`` query → matches if the track string is any known
+        representation of that Language (delegates to ``Language.matches``).
+        Powerful, cross-format mode.
+      * ``str`` query → case-insensitive direct comparison against
+        ``track_lang``. Simple, no normalization, no registry lookup.
+
+    Callers needing cross-format resolution (``"fr"`` ↔ ``"fre"`` ↔
+    ``"french"``) should resolve their string through a ``LanguageRegistry``
+    once and pass the resulting ``Language``.
+    """
+    if track_lang is None:
+        return False
+    if isinstance(query, Language):
+        return query.matches(track_lang)
+    if isinstance(query, str):
+        return track_lang.lower().strip() == query.lower().strip()
+    return False
+
+
+class MediaWithTracks:
+    """
+    Mixin providing audio/subtitle helpers for entities with track collections.
+
+    Hosts must expose two attributes:
+
+    * ``audio_tracks: tuple[AudioTrack, ...]``
+    * ``subtitle_tracks: tuple[SubtitleTrack, ...]``
+
+    The helpers follow the "C+" matching contract: pass a :class:`Language`
+    for cross-format matching, or a ``str`` for case-insensitive comparison.
+    """
+
+    # These attributes are provided by the host entity (Movie, Episode, …).
+    # Declared here only for type-checkers and to make the contract explicit.
+    audio_tracks: tuple[AudioTrack, ...]
+    subtitle_tracks: tuple[SubtitleTrack, ...]
+
+    # ── Audio helpers ──────────────────────────────────────────────────────
+
+    def has_audio_in(self, lang: str | Language) -> bool:
+        """True if at least one audio track is in the given language."""
+        return any(track_lang_matches(t.language, lang) for t in self.audio_tracks)
+
+    def audio_languages(self) -> list[str]:
+        """Unique audio languages across all tracks, in track order."""
+        seen: set[str] = set()
+        result: list[str] = []
+        for t in self.audio_tracks:
+            if t.language and t.language not in seen:
+                seen.add(t.language)
+                result.append(t.language)
+        return result
+
+    # ── Subtitle helpers ───────────────────────────────────────────────────
+
+    def has_subtitles_in(self, lang: str | Language) -> bool:
+        """True if at least one subtitle track is in the given language."""
+        return any(track_lang_matches(t.language, lang) for t in self.subtitle_tracks)
+
+    def has_forced_subs(self) -> bool:
+        """True if at least one subtitle track is flagged as forced."""
+        return any(t.is_forced for t in self.subtitle_tracks)
+
+    def subtitle_languages(self) -> list[str]:
+        """Unique subtitle languages across all tracks, in track order."""
+        seen: set[str] = set()
+        result: list[str] = []
+        for t in self.subtitle_tracks:
+            if t.language and t.language not in seen:
+                seen.add(t.language)
+                result.append(t.language)
+        return result

alfred/domain/shared/ports/__init__.py

@@ -0,0 +1,19 @@
+"""Ports — Protocol interfaces the domain depends on.
+
+Adapters live in ``alfred/infrastructure/`` and implement these protocols.
+Domain code never imports infrastructure; it accepts a port via constructor
+injection and calls it. Tests can pass in-memory fakes that satisfy the
+Protocol without going through real I/O.
+"""
+
+from .filesystem_scanner import FileEntry, FilesystemScanner
+from .language_repository import LanguageRepository
+from .media_prober import MediaProber, SubtitleStreamInfo
+
+__all__ = [
+    "FileEntry",
+    "FilesystemScanner",
+    "LanguageRepository",
+    "MediaProber",
+    "SubtitleStreamInfo",
+]

alfred/domain/shared/ports/filesystem_scanner.py

@@ -0,0 +1,59 @@
+"""FilesystemScanner port — abstracts filesystem inspection.
+
+The domain never calls ``Path.iterdir``, ``Path.is_file``, ``Path.stat`` or
+``open()`` directly. It asks the scanner for a ``FileEntry`` snapshot and
+reasons from there. One scan = one I/O round-trip; no callbacks back to disk.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class FileEntry:
+    """Frozen snapshot of one filesystem entry, taken at scan time.
+
+    The entry carries enough metadata for the domain to classify and order
+    files without re-querying the OS. ``size_kb`` is ``None`` for directories
+    and for files whose size could not be read.
+    """
+
+    path: Path
+    is_file: bool
+    is_dir: bool
+    size_kb: float | None
+
+    @property
+    def name(self) -> str:
+        return self.path.name
+
+    @property
+    def stem(self) -> str:
+        return self.path.stem
+
+    @property
+    def suffix(self) -> str:
+        return self.path.suffix
+
+
+class FilesystemScanner(Protocol):
+    """Read-only filesystem inspection."""
+
+    def scan_dir(self, path: Path) -> list[FileEntry]:
+        """Return sorted entries directly inside ``path``.
+
+        Returns an empty list when ``path`` is not a directory or is
+        unreadable. Adapters must not raise.
+        """
+        ...
+
+    def stat(self, path: Path) -> FileEntry | None:
+        """Stat a single path; ``None`` when it doesn't exist or is unreadable."""
+        ...
+
+    def read_text(self, path: Path, encoding: str = "utf-8") -> str | None:
+        """Read a text file in one go; ``None`` on any error."""
+        ...

alfred/domain/shared/ports/language_repository.py

@@ -0,0 +1,36 @@
+"""LanguageRepository port — abstracts canonical language lookup.
+
+The adapter (typically loading from ISO 639 YAML knowledge) maps a wide
+range of raw forms (codes, English/native names, aliases) onto the
+canonical :class:`Language` value object. Domain code accepts the port
+via constructor injection; tests can pass a small in-memory fake.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from alfred.domain.shared.value_objects import Language
+
+
+class LanguageRepository(Protocol):
+    """Canonical language lookup."""
+
+    def from_iso(self, code: str) -> Language | None:
+        """Look up by canonical ISO 639-2/B code (case-insensitive)."""
+        ...
+
+    def from_any(self, raw: str) -> Language | None:
+        """Look up by any known representation: ISO code, name, alias.
+
+        Case-insensitive. Returns ``None`` when the raw form is unknown.
+        """
+        ...
+
+    def all(self) -> list[Language]:
+        """Return all known languages, in a stable order."""
+        ...
+
+    def __contains__(self, raw: str) -> bool: ...
+
+    def __len__(self) -> int: ...

alfred/domain/shared/ports/media_prober.py

@@ -0,0 +1,52 @@
+"""MediaProber port — abstracts media stream inspection (e.g. ffprobe).
+
+The adapter (typically wrapping ffprobe) maps low-level container metadata
+into the small set of stream attributes the domain reasons about. Replacing
+ffprobe with another tool only requires a new adapter — domain stays put.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from alfred.domain.shared.media import MediaInfo
+
+
+@dataclass(frozen=True)
+class SubtitleStreamInfo:
+    """A single embedded subtitle stream, as seen by the prober.
+
+    ``language`` is the raw language tag emitted by the container (typically
+    ISO 639-2 like ``"fre"``, ``"eng"``); may be empty/None when the stream
+    has no language tag. The domain resolves it to a canonical ``Language``
+    via the knowledge base.
+    """
+
+    language: str | None
+    is_hearing_impaired: bool
+    is_forced: bool
+
+
+class MediaProber(Protocol):
+    """Inspect a media file's stream metadata."""
+
+    def list_subtitle_streams(self, video: Path) -> list[SubtitleStreamInfo]:
+        """Return all subtitle streams in ``video``.
+
+        Returns an empty list when the file is missing, unreadable, or has
+        no subtitle streams. Adapters must not raise.
+        """
+        ...
+
+    def probe(self, video: Path) -> MediaInfo | None:
+        """Return the full :class:`MediaInfo` for ``video``, or ``None``.
+
+        Covers all stream families (video, audio, subtitle) plus
+        file-level duration / bitrate. ``None`` signals that ffprobe is
+        unavailable or the file can't be read — adapters must not
+        raise.
+        """
+        ...

alfred/domain/shared/value_objects.py

@@ -1,5 +1,7 @@
 """Shared value objects used across multiple domains."""
 
+from __future__ import annotations
+
 import re
 from dataclasses import dataclass
 from pathlib import Path
@@ -43,41 +45,21 @@ class ImdbId:
 @dataclass(frozen=True)
 class FilePath:
     """
-    Value object representing a file path with validation.
+    Value object representing a file path.
 
-    Ensures the path is valid and optionally checks existence.
+    Accepts either ``str`` or :class:`pathlib.Path` at construction;
+    the value is normalized to ``Path`` in ``__post_init__``.
     """
 
     value: Path
 
-    def __init__(self, path: str | Path):
-        """
-        Initialize FilePath.
-
-        Args:
-            path: String or Path object representing the file path
-        """
-        if isinstance(path, str):
-            path_obj = Path(path)
-        elif isinstance(path, Path):
-            path_obj = path
-        else:
-            raise ValidationError(f"Path must be str or Path, got {type(path)}")
-
-        # Use object.__setattr__ because dataclass is frozen
-        object.__setattr__(self, "value", path_obj)
-
-    def exists(self) -> bool:
-        """Check if the path exists."""
-        return self.value.exists()
-
-    def is_file(self) -> bool:
-        """Check if the path is a file."""
-        return self.value.is_file()
-
-    def is_dir(self) -> bool:
-        """Check if the path is a directory."""
-        return self.value.is_dir()
+    def __post_init__(self) -> None:
+        if isinstance(self.value, Path):
+            return
+        if isinstance(self.value, str):
+            object.__setattr__(self, "value", Path(self.value))
+            return
+        raise ValidationError(f"Path must be str or Path, got {type(self.value)}")
 
     def __str__(self) -> str:
         return str(self.value)
@@ -131,3 +113,127 @@ class FileSize:
 
     def __repr__(self) -> str:
         return f"FileSize({self.bytes})"
+
+
+@dataclass(frozen=True)
+class Language:
+    """
+    Canonical language value object.
+
+    The primary identifier is the ISO 639-2/B code (3 letters, bibliographic form,
+    e.g. "fre", "eng", "ger"). This is what ffprobe emits and the project-wide
+    canonical form. All other representations (ISO 639-1 code, ISO 639-2/T
+    variant, english/native names, common spellings) live in ``aliases`` and are
+    used by ``matches()`` for case-insensitive lookup.
+
+    Equality and hashing are based solely on ``iso`` so two Language objects with
+    the same canonical code are interchangeable regardless of aliases.
+    """
+
+    iso: str
+    english_name: str
+    native_name: str
+    aliases: tuple[str, ...] = ()
+
+    def __post_init__(self):
+        if not isinstance(self.iso, str) or not self.iso:
+            raise ValidationError(
+                f"Language.iso must be a non-empty string, got {self.iso!r}"
+            )
+        if len(self.iso) != 3:
+            raise ValidationError(
+                f"Language.iso must be a 3-letter ISO 639-2/B code, got {self.iso!r}"
+            )
+        if self.iso != self.iso.lower():
+            raise ValidationError(
+                f"Language.iso must be lowercase, got {self.iso!r} — "
+                f"use Language.from_raw() to construct from arbitrary input"
+            )
+        for alias in self.aliases:
+            if not isinstance(alias, str) or alias != alias.lower().strip() or not alias:
+                raise ValidationError(
+                    f"Language.aliases must be lowercase non-empty strings, "
+                    f"got {alias!r} — use Language.from_raw() to normalize"
+                )
+
+    @classmethod
+    def from_raw(
+        cls,
+        iso: str,
+        english_name: str,
+        native_name: str,
+        aliases: tuple[str, ...] | list[str] = (),
+    ) -> Language:
+        """
+        Construct a Language from arbitrary (possibly un-normalized) input.
+
+        Use this factory when loading from external sources (YAML, user input,
+        third-party APIs) — it lowercases the iso code and normalizes/dedups
+        the alias tuple. The direct constructor is strict and rejects
+        un-normalized input.
+        """
+        seen: set[str] = set()
+        normalized: list[str] = []
+        for alias in aliases:
+            if not isinstance(alias, str):
+                continue
+            a = alias.lower().strip()
+            if a and a not in seen:
+                seen.add(a)
+                normalized.append(a)
+        return cls(
+            iso=iso.lower(),
+            english_name=english_name,
+            native_name=native_name,
+            aliases=tuple(normalized),
+        )
+
+    def matches(self, raw: str) -> bool:
+        """
+        True if ``raw`` is any known representation of this language.
+
+        Comparison is case-insensitive and whitespace-trimmed. The match space is
+        the union of the canonical ``iso`` code, the english/native names, and
+        every alias.
+        """
+        if not isinstance(raw, str):
+            return False
+        needle = raw.lower().strip()
+        if not needle:
+            return False
+        if needle == self.iso:
+            return True
+        if needle == self.english_name.lower():
+            return True
+        if needle == self.native_name.lower():
+            return True
+        return needle in self.aliases
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Language):
+            return NotImplemented
+        return self.iso == other.iso
+
+    def __hash__(self) -> int:
+        return hash(self.iso)
+
+    def __str__(self) -> str:
+        return self.iso
+
+    def __repr__(self) -> str:
+        return f"Language({self.iso!r}, {self.english_name!r})"
+
+
+# Characters allowed in dot-separated folder/filename forms:
+# alphanumerics, underscores, spaces (about to be replaced with dots),
+# literal dots, and hyphens. Everything else is stripped.
+_FS_SAFE_CHARS = re.compile(r"[^\w\s\.\-]")
+
+
+def to_dot_folder_name(title: str) -> str:
+    """Sanitize ``title`` for filesystem use and convert spaces to dots.
+
+    Produces e.g. ``Breaking.Bad`` from ``"Breaking Bad"`` or
+    ``Spider.Man`` from ``"Spider-Man: No Way Home"``.
+    """
+    return _FS_SAFE_CHARS.sub("", title).replace(" ", ".")

alfred/domain/subtitles/__init__.py

@@ -1,14 +1,36 @@
-"""Subtitles domain - Business logic for subtitle management (shared across movies and TV shows)."""
+"""Subtitles domain — subtitle identification, classification and placement."""
 
-from .entities import Subtitle
+from .aggregates import SubtitleRuleSet
+from .entities import MediaSubtitleMetadata, SubtitleScanResult
 from .exceptions import SubtitleNotFound
-from .services import SubtitleService
-from .value_objects import Language, SubtitleFormat
+from .services import PatternDetector, SubtitleIdentifier, SubtitleMatcher
+from .value_objects import (
+    RuleScope,
+    RuleScopeLevel,
+    ScanStrategy,
+    SubtitleFormat,
+    SubtitleLanguage,
+    SubtitleMatchingRules,
+    SubtitlePattern,
+    SubtitleType,
+    TypeDetectionMethod,
+)
 
 __all__ = [
-    "Subtitle",
-    "Language",
+    "SubtitleScanResult",
+    "MediaSubtitleMetadata",
+    "SubtitleRuleSet",
+    "SubtitleIdentifier",
+    "SubtitleMatcher",
+    "PatternDetector",
     "SubtitleFormat",
+    "SubtitleLanguage",
+    "SubtitlePattern",
+    "SubtitleType",
+    "ScanStrategy",
+    "TypeDetectionMethod",
+    "SubtitleMatchingRules",
+    "RuleScope",
+    "RuleScopeLevel",
     "SubtitleNotFound",
-    "SubtitleService",
 ]

alfred/domain/subtitles/aggregates.py

@@ -0,0 +1,98 @@
+"""Subtitle domain aggregates."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..shared.value_objects import ImdbId
+from .value_objects import RuleScope, RuleScopeLevel, SubtitleMatchingRules
+
+
+@dataclass
+class SubtitleRuleSet:
+    """
+    Rules for subtitle selection at a given scope level, with inheritance.
+
+    Only delta fields are stored — None means "inherit from parent".
+    Resolution order: global → release_group → show/movie → season → episode.
+
+    A RuleSet can also be pinned to a specific media item (imdb_id),
+    bypassing the scope hierarchy for that item.
+    """
+
+    scope: RuleScope
+    parent: SubtitleRuleSet | None = None
+    pinned_to: ImdbId | None = None
+
+    # Deltas — None = inherit
+    _languages: list[str] | None = field(default=None, repr=False)
+    _formats: list[str] | None = field(default=None, repr=False)
+    _types: list[str] | None = field(default=None, repr=False)
+    _format_priority: list[str] | None = field(default=None, repr=False)
+    _min_confidence: float | None = field(default=None, repr=False)
+
+    def resolve(self, default_rules: SubtitleMatchingRules) -> SubtitleMatchingRules:
+        """
+        Walk the parent chain and merge deltas into effective rules.
+
+        ``default_rules`` seeds the top of the chain — it is the caller's
+        responsibility to load these from the knowledge base (infrastructure).
+        Keeping the default rules as a parameter keeps the domain free of
+        any I/O dependency.
+        """
+        base = (
+            self.parent.resolve(default_rules) if self.parent else default_rules
+        )
+        return SubtitleMatchingRules(
+            preferred_languages=self._languages or base.preferred_languages,
+            preferred_formats=self._formats or base.preferred_formats,
+            allowed_types=self._types or base.allowed_types,
+            format_priority=self._format_priority or base.format_priority,
+            min_confidence=self._min_confidence
+            if self._min_confidence is not None
+            else base.min_confidence,
+        )
+
+    def override(
+        self,
+        languages: list[str] | None = None,
+        formats: list[str] | None = None,
+        types: list[str] | None = None,
+        format_priority: list[str] | None = None,
+        min_confidence: float | None = None,
+    ) -> None:
+        """Set delta overrides at this scope level."""
+        if languages is not None:
+            self._languages = languages
+        if formats is not None:
+            self._formats = formats
+        if types is not None:
+            self._types = types
+        if format_priority is not None:
+            self._format_priority = format_priority
+        if min_confidence is not None:
+            self._min_confidence = min_confidence
+
+    def to_dict(self) -> dict:
+        """Serialize deltas only (for persistence in rules.yaml)."""
+        delta: dict[str, Any] = {}
+        if self._languages is not None:
+            delta["languages"] = self._languages
+        if self._formats is not None:
+            delta["formats"] = self._formats
+        if self._types is not None:
+            delta["types"] = self._types
+        if self._format_priority is not None:
+            delta["format_priority"] = self._format_priority
+        if self._min_confidence is not None:
+            delta["min_confidence"] = self._min_confidence
+        return {
+            "scope": {
+                "level": self.scope.level.value,
+                "identifier": self.scope.identifier,
+            },
+            "override": delta,
+        }
+
+    @classmethod
+    def global_default(cls) -> SubtitleRuleSet:
+        return cls(scope=RuleScope(level=RuleScopeLevel.GLOBAL))

alfred/domain/subtitles/entities.py

@@ -1,96 +1,105 @@
 """Subtitle domain entities."""
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from pathlib import Path
 
-from ..shared.value_objects import FilePath, ImdbId
-from .value_objects import Language, SubtitleFormat, TimingOffset
+from ..shared.value_objects import ImdbId
+from .value_objects import (
+    SubtitleFormat,
+    SubtitleLanguage,
+    SubtitleType,
+)
 
 
 @dataclass
-class Subtitle:
+class SubtitleScanResult:
     """
-    Subtitle entity representing a subtitle file.
+    A subtitle observed during a scan — either an external file or an embedded stream.
 
-    Can be associated with either a movie or a TV show episode.
+    Unlike ``alfred.domain.shared.media.SubtitleTrack`` (the pure container-view
+    populated from ffprobe), a ``SubtitleScanResult`` carries the **flow state**
+    of the subtitle matching pipeline: language/format are typed value objects
+    that may be ``None`` while classification is in progress, ``confidence``
+    reflects how certain we are, and ``raw_tokens`` holds the filename fragments
+    still under analysis. State evolves: unknown → resolved after user
+    clarification. The name reflects this — it's the **output of a scan pass**,
+    not a value object.
     """
 
-    media_imdb_id: ImdbId
-    language: Language
-    format: SubtitleFormat
-    file_path: FilePath
+    # Classification (may be None if not yet resolved)
+    language: SubtitleLanguage | None
+    format: SubtitleFormat | None
+    subtitle_type: SubtitleType = SubtitleType.UNKNOWN
 
-    # Optional: for TV shows
-    season_number: int | None = None
-    episode_number: int | None = None
+    # Source
+    is_embedded: bool = False
+    file_path: Path | None = None  # None if embedded
+    file_size_kb: float | None = None
+    entry_count: int | None = None  # number of subtitle cues in the file
 
-    # Subtitle metadata
-    timing_offset: TimingOffset = TimingOffset(0)
-    hearing_impaired: bool = False
-    forced: bool = False  # Forced subtitles (for foreign language parts)
+    # Matching state
+    confidence: float = 0.0  # 0.0 → 1.0, not applicable for embedded
+    raw_tokens: list[str] = field(
+        default_factory=list
+    )  # tokens extracted from filename
 
-    # Source information
-    source: str | None = None  # e.g., "OpenSubtitles", "Subscene"
-    uploader: str | None = None
-    download_count: int | None = None
-    rating: float | None = None
+    def is_resolved(self) -> bool:
+        return self.language is not None
 
-    def __post_init__(self):
-        """Validate subtitle entity."""
-        # Ensure ImdbId is actually an ImdbId instance
-        if not isinstance(self.media_imdb_id, ImdbId):
-            if isinstance(self.media_imdb_id, str):
-                object.__setattr__(self, "media_imdb_id", ImdbId(self.media_imdb_id))
-
-        # Ensure Language is actually a Language instance
-        if not isinstance(self.language, Language):
-            if isinstance(self.language, str):
-                object.__setattr__(self, "language", Language.from_code(self.language))
-
-        # Ensure SubtitleFormat is actually a SubtitleFormat instance
-        if not isinstance(self.format, SubtitleFormat):
-            if isinstance(self.format, str):
-                object.__setattr__(
-                    self, "format", SubtitleFormat.from_extension(self.format)
+    @property
+    def destination_name(self) -> str:
+        """
+        Compute the output filename per naming convention:
+            {lang}.{ext}
+            {lang}.sdh.{ext}
+            {lang}.forced.{ext}
+        """
+        if not self.language or not self.format:
+            raise ValueError(
+                "Cannot compute destination_name: language or format missing"
             )
-
-        # Ensure FilePath is actually a FilePath instance
-        if not isinstance(self.file_path, FilePath):
-            object.__setattr__(self, "file_path", FilePath(self.file_path))
-
-    def is_for_movie(self) -> bool:
-        """Check if this subtitle is for a movie."""
-        return self.season_number is None and self.episode_number is None
-
-    def is_for_episode(self) -> bool:
-        """Check if this subtitle is for a TV show episode."""
-        return self.season_number is not None and self.episode_number is not None
-
-    def get_filename(self) -> str:
-        """
-        Get the suggested filename for this subtitle.
-
-        Format for movies: "Movie.Title.{lang}.{format}"
-        Format for episodes: "S01E05.{lang}.{format}"
-        """
-        if self.is_for_episode():
-            base = f"S{self.season_number:02d}E{self.episode_number:02d}"
-        else:
-            # For movies, use the file path stem
-            base = self.file_path.value.stem
-
-        parts = [base, self.language.value]
-
-        if self.hearing_impaired:
-            parts.append("hi")
-        if self.forced:
+        ext = self.format.extensions[0].lstrip(".")
+        parts = [self.language.code]
+        if self.subtitle_type == SubtitleType.SDH:
+            parts.append("sdh")
+        elif self.subtitle_type == SubtitleType.FORCED:
             parts.append("forced")
-
-        return f"{'.'.join(parts)}.{self.format.value}"
-
-    def __str__(self) -> str:
-        if self.is_for_episode():
-            return f"Subtitle S{self.season_number:02d}E{self.episode_number:02d} ({self.language.value})"
-        return f"Subtitle ({self.language.value})"
+        return ".".join(parts) + "." + ext
 
     def __repr__(self) -> str:
-        return f"Subtitle(media={self.media_imdb_id}, lang={self.language.value})"
+        lang = self.language.code if self.language else "?"
+        fmt = self.format.id if self.format else "?"
+        src = (
+            "embedded"
+            if self.is_embedded
+            else str(self.file_path.name if self.file_path else "?")
+        )
+        return f"SubtitleScanResult({lang}, {self.subtitle_type.value}, {fmt}, src={src}, conf={self.confidence:.2f})"
+
+
+@dataclass
+class MediaSubtitleMetadata:
+    """
+    Snapshot of all subtitle information known for a given media item.
+    Populated by the identifier service (ffprobe + filesystem scan).
+    """
+
+    media_id: ImdbId | None
+    media_type: str  # "movie" | "tv_show"
+    embedded_tracks: list[SubtitleScanResult] = field(default_factory=list)
+    external_tracks: list[SubtitleScanResult] = field(default_factory=list)
+    release_group: str | None = None
+    detected_pattern_id: str | None = None  # pattern id from knowledge base
+    pattern_confirmed: bool = False
+
+    @property
+    def all_tracks(self) -> list[SubtitleScanResult]:
+        return self.embedded_tracks + self.external_tracks
+
+    @property
+    def total_count(self) -> int:
+        return len(self.embedded_tracks) + len(self.external_tracks)
+
+    @property
+    def unresolved_tracks(self) -> list[SubtitleScanResult]:
+        return [t for t in self.external_tracks if t.language is None]

alfred/domain/subtitles/ports/__init__.py

@@ -0,0 +1,6 @@
+"""Domain ports for the subtitles domain — Protocol-based abstractions
+that decouple domain services from concrete infrastructure adapters."""
+
+from .knowledge import SubtitleKnowledge
+
+__all__ = ["SubtitleKnowledge"]

alfred/domain/subtitles/ports/knowledge.py

@@ -0,0 +1,38 @@
+"""SubtitleKnowledge port — the query surface domain services need from the
+subtitle knowledge base, expressed as a Protocol so the domain never imports
+the infrastructure adapter that backs it.
+
+The concrete implementation lives in
+``alfred/infrastructure/knowledge/subtitles/base.py`` (the YAML-backed
+``SubtitleKnowledgeBase``). Tests can supply any object that satisfies this
+structural contract.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..value_objects import SubtitleFormat, SubtitleLanguage, SubtitlePattern, SubtitleType
+
+
+class SubtitleKnowledge(Protocol):
+    """Read-only query surface for subtitle knowledge consumed by the domain.
+
+    Only the methods that domain services actually call belong here — anything
+    else (defaults loading, reload, pattern groups, raw dicts) stays on the
+    concrete class and is reserved for the application layer.
+    """
+
+    def known_extensions(self) -> set[str]: ...
+
+    def format_for_extension(self, ext: str) -> SubtitleFormat | None: ...
+
+    def language_for_token(self, token: str) -> SubtitleLanguage | None: ...
+
+    def is_known_lang_token(self, token: str) -> bool: ...
+
+    def type_for_token(self, token: str) -> SubtitleType | None: ...
+
+    def is_known_type_token(self, token: str) -> bool: ...
+
+    def patterns(self) -> dict[str, SubtitlePattern]: ...

alfred/domain/subtitles/repositories.py

@@ -1,60 +0,0 @@
-"""Subtitle repository interfaces (abstract)."""
-
-from abc import ABC, abstractmethod
-
-from ..shared.value_objects import ImdbId
-from .entities import Subtitle
-from .value_objects import Language
-
-
-class SubtitleRepository(ABC):
-    """
-    Abstract repository for subtitle persistence.
-
-    This defines the interface that infrastructure implementations must follow.
-    """
-
-    @abstractmethod
-    def save(self, subtitle: Subtitle) -> None:
-        """
-        Save a subtitle to the repository.
-
-        Args:
-            subtitle: Subtitle entity to save
-        """
-        pass
-
-    @abstractmethod
-    def find_by_media(
-        self,
-        media_imdb_id: ImdbId,
-        language: Language | None = None,
-        season: int | None = None,
-        episode: int | None = None,
-    ) -> list[Subtitle]:
-        """
-        Find subtitles for a media item.
-
-        Args:
-            media_imdb_id: IMDb ID of the media
-            language: Optional language filter
-            season: Optional season number (for TV shows)
-            episode: Optional episode number (for TV shows)
-
-        Returns:
-            List of matching subtitles
-        """
-        pass
-
-    @abstractmethod
-    def delete(self, subtitle: Subtitle) -> bool:
-        """
-        Delete a subtitle from the repository.
-
-        Args:
-            subtitle: Subtitle to delete
-
-        Returns:
-            True if deleted, False if not found
-        """
-        pass

alfred/domain/subtitles/services.py

@@ -1,149 +0,0 @@
-"""Subtitle domain services - Business logic."""
-
-import logging
-
-from ..shared.value_objects import FilePath, ImdbId
-from .entities import Subtitle
-from .exceptions import SubtitleNotFound
-from .repositories import SubtitleRepository
-from .value_objects import Language, SubtitleFormat
-
-logger = logging.getLogger(__name__)
-
-
-class SubtitleService:
-    """
-    Domain service for subtitle-related business logic.
-
-    This service is SHARED between movies and TV shows domains.
-    Both can use this service to manage subtitles.
-    """
-
-    def __init__(self, repository: SubtitleRepository):
-        """
-        Initialize subtitle service.
-
-        Args:
-            repository: Subtitle repository for persistence
-        """
-        self.repository = repository
-
-    def add_subtitle(self, subtitle: Subtitle) -> None:
-        """
-        Add a subtitle to the library.
-
-        Args:
-            subtitle: Subtitle entity to add
-        """
-        self.repository.save(subtitle)
-        logger.info(
-            f"Added subtitle: {subtitle.language.value} for {subtitle.media_imdb_id}"
-        )
-
-    def find_subtitles_for_movie(
-        self, imdb_id: ImdbId, languages: list[Language] | None = None
-    ) -> list[Subtitle]:
-        """
-        Find subtitles for a movie.
-
-        Args:
-            imdb_id: IMDb ID of the movie
-            languages: Optional list of languages to filter by
-
-        Returns:
-            List of matching subtitles
-        """
-        if languages:
-            all_subtitles = []
-            for lang in languages:
-                subs = self.repository.find_by_media(imdb_id, language=lang)
-                all_subtitles.extend(subs)
-            return all_subtitles
-        else:
-            return self.repository.find_by_media(imdb_id)
-
-    def find_subtitles_for_episode(
-        self,
-        imdb_id: ImdbId,
-        season: int,
-        episode: int,
-        languages: list[Language] | None = None,
-    ) -> list[Subtitle]:
-        """
-        Find subtitles for a TV show episode.
-
-        Args:
-            imdb_id: IMDb ID of the TV show
-            season: Season number
-            episode: Episode number
-            languages: Optional list of languages to filter by
-
-        Returns:
-            List of matching subtitles
-        """
-        if languages:
-            all_subtitles = []
-            for lang in languages:
-                subs = self.repository.find_by_media(
-                    imdb_id, language=lang, season=season, episode=episode
-                )
-                all_subtitles.extend(subs)
-            return all_subtitles
-        else:
-            return self.repository.find_by_media(
-                imdb_id, season=season, episode=episode
-            )
-
-    def remove_subtitle(self, subtitle: Subtitle) -> None:
-        """
-        Remove a subtitle from the library.
-
-        Args:
-            subtitle: Subtitle to remove
-
-        Raises:
-            SubtitleNotFound: If subtitle not found
-        """
-        if not self.repository.delete(subtitle):
-            raise SubtitleNotFound(f"Subtitle not found: {subtitle}")
-
-        logger.info(f"Removed subtitle: {subtitle}")
-
-    def detect_format_from_file(self, file_path: FilePath) -> SubtitleFormat:
-        """
-        Detect subtitle format from file extension.
-
-        Args:
-            file_path: Path to subtitle file
-
-        Returns:
-            Detected subtitle format
-        """
-        extension = file_path.value.suffix
-        return SubtitleFormat.from_extension(extension)
-
-    def validate_subtitle_file(self, file_path: FilePath) -> bool:
-        """
-        Validate that a file is a valid subtitle file.
-
-        Args:
-            file_path: Path to the file
-
-        Returns:
-            True if valid subtitle file, False otherwise
-        """
-        if not file_path.exists():
-            logger.warning(f"File does not exist: {file_path}")
-            return False
-
-        if not file_path.is_file():
-            logger.warning(f"Path is not a file: {file_path}")
-            return False
-
-        # Check file extension
-        try:
-            self.detect_format_from_file(file_path)
-            return True
-        except Exception as e:
-            logger.warning(f"Invalid subtitle format: {e}")
-            return False

alfred/domain/subtitles/services/__init__.py

@@ -0,0 +1,9 @@
+from .identifier import SubtitleIdentifier
+from .matcher import SubtitleMatcher
+from .pattern_detector import PatternDetector
+
+__all__ = [
+    "SubtitleIdentifier",
+    "SubtitleMatcher",
+    "PatternDetector",
+]

alfred/domain/subtitles/services/identifier.py

@@ -0,0 +1,311 @@
+"""SubtitleIdentifier — finds and classifies all subtitle tracks for a video file."""
+
+import logging
+import re
+from pathlib import Path
+
+from ...shared.ports import FilesystemScanner, MediaProber
+from ..ports import SubtitleKnowledge
+from ...shared.value_objects import ImdbId
+from ..entities import MediaSubtitleMetadata, SubtitleScanResult
+from ..value_objects import ScanStrategy, SubtitlePattern, SubtitleType
+
+logger = logging.getLogger(__name__)
+
+
+def _tokenize(name: str) -> list[str]:
+    """Split a filename stem into lowercase tokens, stripping parentheses."""
+    # Strip parenthesized qualifiers like (simplified), (canada), (brazil)
+    name = re.sub(r"\([^)]*\)", "", name)
+    return [t.lower() for t in re.split(r"[\.\s_\-]+", name) if t]
+
+
+def _tokenize_suffix(stem: str, episode_stem: str) -> list[str]:
+    """
+    For episode_subfolder pattern: the filename is {episode_stem}.{lang_tokens}.
+    Return only the tokens that come after the episode stem portion.
+    Falls back to full tokenization if the stem doesn't start with episode_stem.
+    """
+    stem_lower = stem.lower()
+    prefix = episode_stem.lower()
+    if stem_lower.startswith(prefix):
+        suffix = stem[len(prefix) :]
+        tokens = _tokenize(suffix)
+        if tokens:
+            return tokens
+    return _tokenize(stem)
+
+
+def _count_entries(text: str | None) -> int | None:
+    """Return the entry count of an SRT body by finding the last cue number."""
+    if text is None:
+        return None
+    for line in reversed(text.splitlines()):
+        if line.strip().isdigit():
+            return int(line.strip())
+    return 0
+
+
+class SubtitleIdentifier:
+    """
+    Finds all subtitle tracks for a given video file using a known pattern,
+    then attempts to classify each track (language, type, format).
+
+    Returns a MediaSubtitleMetadata with embedded + external tracks.
+    External tracks with unknown language or low confidence are left as-is —
+    the caller (use case) decides whether to ask the user for clarification.
+    """
+
+    def __init__(
+        self,
+        kb: SubtitleKnowledge,
+        prober: MediaProber,
+        scanner: FilesystemScanner,
+    ):
+        self.kb = kb
+        self.prober = prober
+        self.scanner = scanner
+
+    def identify(
+        self,
+        video_path: Path,
+        pattern: SubtitlePattern,
+        media_id: ImdbId | None,
+        media_type: str,
+        release_group: str | None = None,
+    ) -> MediaSubtitleMetadata:
+        metadata = MediaSubtitleMetadata(
+            media_id=media_id,
+            media_type=media_type,
+            release_group=release_group,
+            detected_pattern_id=pattern.id,
+        )
+
+        if pattern.scan_strategy == ScanStrategy.EMBEDDED:
+            metadata.embedded_tracks = self._scan_embedded(video_path)
+        else:
+            metadata.external_tracks = self._scan_external(video_path, pattern)
+            # Always also check for embedded tracks
+            metadata.embedded_tracks = self._scan_embedded(video_path)
+
+        return metadata
+
+    # ------------------------------------------------------------------
+    # Embedded tracks — via MediaProber
+    # ------------------------------------------------------------------
+
+    def _scan_embedded(self, video_path: Path) -> list[SubtitleScanResult]:
+        streams = self.prober.list_subtitle_streams(video_path)
+
+        tracks = []
+        for stream in streams:
+            lang = (
+                self.kb.language_for_token(stream.language) if stream.language else None
+            )
+
+            if stream.is_hearing_impaired:
+                stype = SubtitleType.SDH
+            elif stream.is_forced:
+                stype = SubtitleType.FORCED
+            else:
+                stype = SubtitleType.STANDARD
+
+            tracks.append(
+                SubtitleScanResult(
+                    language=lang,
+                    format=None,
+                    subtitle_type=stype,
+                    is_embedded=True,
+                    raw_tokens=[stream.language] if stream.language else [],
+                )
+            )
+
+        logger.debug(
+            f"SubtitleIdentifier: {len(tracks)} embedded track(s) in {video_path.name}"
+        )
+        return tracks
+
+    # ------------------------------------------------------------------
+    # External tracks — filesystem scan per pattern strategy
+    # ------------------------------------------------------------------
+
+    def _scan_external(
+        self, video_path: Path, pattern: SubtitlePattern
+    ) -> list[SubtitleScanResult]:
+        strategy = pattern.scan_strategy
+        episode_stem: str | None = None
+
+        if strategy == ScanStrategy.ADJACENT:
+            candidates = self._find_adjacent(video_path)
+        elif strategy == ScanStrategy.FLAT:
+            candidates = self._find_flat(video_path, pattern.root_folder or "Subs")
+        elif strategy == ScanStrategy.EPISODE_SUBFOLDER:
+            candidates, episode_stem = self._find_episode_subfolder(
+                video_path, pattern.root_folder or "Subs"
+            )
+        else:
+            return []
+
+        return self._classify_files(candidates, pattern, episode_stem=episode_stem)
+
+    def _find_adjacent(self, video_path: Path) -> list:
+        known = self.kb.known_extensions()
+        return [
+            entry
+            for entry in self.scanner.scan_dir(video_path.parent)
+            if entry.is_file
+            and entry.suffix.lower() in known
+            and entry.stem != video_path.stem
+        ]
+
+    def _find_flat(self, video_path: Path, root_folder: str) -> list:
+        known = self.kb.known_extensions()
+        # Adjacent first, then release root (one level up)
+        for subs_dir in (
+            video_path.parent / root_folder,
+            video_path.parent.parent / root_folder,
+        ):
+            entries = self.scanner.scan_dir(subs_dir)
+            if entries:
+                return [
+                    e for e in entries if e.is_file and e.suffix.lower() in known
+                ]
+        return []
+
+    def _find_episode_subfolder(
+        self, video_path: Path, root_folder: str
+    ) -> tuple[list, str]:
+        """Look for Subs/{episode_stem}/*.srt — adjacent or one level up."""
+        episode_stem = video_path.stem
+        known = self.kb.known_extensions()
+        for subs_dir in (
+            video_path.parent / root_folder / episode_stem,
+            video_path.parent.parent / root_folder / episode_stem,
+        ):
+            entries = self.scanner.scan_dir(subs_dir)
+            files = [e for e in entries if e.is_file and e.suffix.lower() in known]
+            if files:
+                logger.debug(
+                    f"SubtitleIdentifier: found {len(files)} file(s) in {subs_dir}"
+                )
+                return files, episode_stem
+        return [], episode_stem
+
+    # ------------------------------------------------------------------
+    # Classification
+    # ------------------------------------------------------------------
+
+    def _classify_files(
+        self,
+        entries: list,
+        pattern: SubtitlePattern,
+        episode_stem: str | None = None,
+    ) -> list[SubtitleScanResult]:
+        tracks = [
+            self._classify_single(entry, episode_stem=episode_stem) for entry in entries
+        ]
+
+        # Post-process: if multiple tracks share same language but type is ambiguous,
+        # apply size_and_count disambiguation
+        if pattern.type_detection.value == "size_and_count":
+            tracks = self._disambiguate_by_size(tracks)
+
+        return tracks
+
+    def _classify_single(
+        self, entry, episode_stem: str | None = None
+    ) -> SubtitleScanResult:
+        fmt = self.kb.format_for_extension(entry.suffix)
+        tokens = (
+            _tokenize_suffix(entry.stem, episode_stem)
+            if episode_stem
+            else _tokenize(entry.stem)
+        )
+
+        language = None
+        subtitle_type = SubtitleType.UNKNOWN
+        unknown_tokens = []
+        matched_tokens = 0
+
+        for token in tokens:
+            if self.kb.is_known_lang_token(token):
+                language = self.kb.language_for_token(token)
+                matched_tokens += 1
+            elif self.kb.is_known_type_token(token):
+                subtitle_type = self.kb.type_for_token(token) or subtitle_type
+                matched_tokens += 1
+            elif token.isdigit():
+                pass  # numeric prefix — ignore
+            elif len(token) > 1:
+                unknown_tokens.append(token)
+
+        # Confidence: proportion of meaningful tokens that were recognized
+        meaningful = [t for t in tokens if not t.isdigit() and len(t) > 1]
+        confidence = matched_tokens / max(len(meaningful), 1) if meaningful else 0.5
+
+        if unknown_tokens:
+            logger.debug(
+                f"SubtitleIdentifier: unknown tokens in '{entry.name}': {unknown_tokens}"
+            )
+
+        # Entry count: only meaningful for SRT files; read text on demand.
+        entry_count: int | None = None
+        if entry.suffix.lower() == ".srt":
+            entry_count = _count_entries(self.scanner.read_text(entry.path))
+
+        return SubtitleScanResult(
+            language=language,
+            format=fmt,
+            subtitle_type=subtitle_type,
+            is_embedded=False,
+            file_path=entry.path,
+            file_size_kb=entry.size_kb,
+            entry_count=entry_count,
+            confidence=confidence,
+            raw_tokens=tokens,
+        )
+
+    def _disambiguate_by_size(
+        self, tracks: list[SubtitleScanResult]
+    ) -> list[SubtitleScanResult]:
+        """
+        When multiple tracks share the same language and type is UNKNOWN/STANDARD,
+        the one with the most entries (lines) is SDH, the smallest is FORCED if
+        there are 3+, otherwise the smaller is STANDARD.
+
+        Only applied when type_detection = size_and_count.
+        """
+
+        # Group by language code
+        lang_groups: dict[str, list[SubtitleScanResult]] = {}
+        for track in tracks:
+            key = track.language.code if track.language else "__unknown__"
+            lang_groups.setdefault(key, []).append(track)
+
+        result = []
+        for group in lang_groups.values():
+            if len(group) == 1:
+                result.extend(group)
+                continue
+
+            # Sort by entry_count ascending (None treated as 0)
+            sorted_group = sorted(group, key=lambda t: t.entry_count or 0)
+
+            if len(sorted_group) == 2:
+                # smaller = standard, larger = sdh
+                self._set_type(sorted_group[0], SubtitleType.STANDARD)
+                self._set_type(sorted_group[1], SubtitleType.SDH)
+            elif len(sorted_group) >= 3:
+                # smallest = forced, middle = standard, largest = sdh
+                self._set_type(sorted_group[0], SubtitleType.FORCED)
+                for t in sorted_group[1:-1]:
+                    self._set_type(t, SubtitleType.STANDARD)
+                self._set_type(sorted_group[-1], SubtitleType.SDH)
+
+            result.extend(sorted_group)
+
+        return result
+
+    def _set_type(self, track: SubtitleScanResult, stype: SubtitleType) -> None:
+        """Mutate track type in-place."""
+        track.subtitle_type = stype

alfred/domain/subtitles/services/matcher.py

@@ -0,0 +1,120 @@
+"""SubtitleMatcher — filters tracks against resolved rules."""
+
+import logging
+
+from ..entities import SubtitleScanResult
+from ..value_objects import SubtitleMatchingRules
+
+logger = logging.getLogger(__name__)
+
+
+class SubtitleMatcher:
+    """
+    Filters a list of SubtitleScanResult against effective SubtitleMatchingRules.
+
+    Returns matched tracks (pass all filters, confidence >= min_confidence)
+    and unresolved tracks (need user clarification).
+
+    Conflict resolution: when two tracks share the same language + type,
+    format_priority decides which one to keep.
+    """
+
+    def match(
+        self,
+        tracks: list[SubtitleScanResult],
+        rules: SubtitleMatchingRules,
+    ) -> tuple[list[SubtitleScanResult], list[SubtitleScanResult]]:
+        """
+        Returns (matched, unresolved).
+        """
+        matched: list[SubtitleScanResult] = []
+        unresolved: list[SubtitleScanResult] = []
+
+        for track in tracks:
+            if track.is_embedded:
+                continue
+
+            if track.language is None or track.confidence < rules.min_confidence:
+                unresolved.append(track)
+                continue
+
+            if not self._passes_filters(track, rules):
+                logger.debug(f"SubtitleMatcher: filtered out {track}")
+                continue
+
+            matched.append(track)
+
+        matched = self._resolve_conflicts(matched, rules)
+        logger.info(
+            f"SubtitleMatcher: {len(matched)} matched, {len(unresolved)} unresolved"
+        )
+        return matched, unresolved
+
+    def _passes_filters(
+        self, track: SubtitleScanResult, rules: SubtitleMatchingRules
+    ) -> bool:
+        # Language filter
+        if rules.preferred_languages:
+            if not track.language:
+                return False
+            if track.language.code not in rules.preferred_languages:
+                return False
+
+        # Format filter (only for external files)
+        if rules.preferred_formats and not track.is_embedded:
+            if not track.format:
+                return False
+            if track.format.id not in rules.preferred_formats:
+                return False
+
+        # Type filter
+        if rules.allowed_types:
+            if track.subtitle_type.value not in rules.allowed_types:
+                return False
+
+        return True
+
+    def _resolve_conflicts(
+        self,
+        tracks: list[SubtitleScanResult],
+        rules: SubtitleMatchingRules,
+    ) -> list[SubtitleScanResult]:
+        """
+        When multiple tracks have same language + type, keep only the best one
+        according to format_priority. If no format_priority applies, keep the first.
+        """
+        seen: dict[tuple, SubtitleScanResult] = {}
+
+        for track in tracks:
+            lang = track.language.code if track.language else None
+            stype = track.subtitle_type.value
+            key = (lang, stype)
+
+            if key not in seen:
+                seen[key] = track
+            else:
+                existing = seen[key]
+                if self._prefer(track, existing, rules.format_priority):
+                    logger.debug(
+                        f"SubtitleMatcher: conflict {key} — "
+                        f"preferring {track.format.id if track.format else 'embedded'} "
+                        f"over {existing.format.id if existing.format else 'embedded'}"
+                    )
+                    seen[key] = track
+
+        return list(seen.values())
+
+    def _prefer(
+        self,
+        candidate: SubtitleScanResult,
+        existing: SubtitleScanResult,
+        format_priority: list[str],
+    ) -> bool:
+        """Return True if candidate is preferable to existing."""
+        if not format_priority:
+            return False
+        c_fmt = candidate.format.id if candidate.format else ""
+        e_fmt = existing.format.id if existing.format else ""
+        c_rank = format_priority.index(c_fmt) if c_fmt in format_priority else 999
+        e_rank = format_priority.index(e_fmt) if e_fmt in format_priority else 999
+        return c_rank < e_rank

alfred/domain/subtitles/services/pattern_detector.py

@@ -0,0 +1,208 @@
+"""PatternDetector — discovers the subtitle structure of a release folder."""
+
+import logging
+from pathlib import Path
+
+from ...shared.ports import FilesystemScanner, MediaProber
+from ..ports import SubtitleKnowledge
+from ..value_objects import ScanStrategy, SubtitlePattern
+
+logger = logging.getLogger(__name__)
+
+
+class PatternDetector:
+    """
+    Inspects a release folder and returns the best matching known pattern,
+    plus a confidence score and a description of what was found.
+
+    Used for "pattern discovery" — when we don't yet know which pattern
+    a release follows. The result is proposed to the user for confirmation.
+    """
+
+    def __init__(
+        self,
+        kb: SubtitleKnowledge,
+        prober: MediaProber,
+        scanner: FilesystemScanner,
+    ):
+        self.kb = kb
+        self.prober = prober
+        self.scanner = scanner
+
+    def detect(self, release_root: Path, sample_video: Path) -> dict:
+        """
+        Analyse the release folder and return:
+        {
+            "detected": SubtitlePattern | None,
+            "confidence": float,
+            "description": str,         # human-readable description of what was found
+            "candidate_pattern_ids": list[str],
+        }
+        """
+        findings = self._inspect(release_root, sample_video)
+        best, confidence = self._match_pattern(findings)
+
+        return {
+            "detected": best,
+            "confidence": confidence,
+            "description": self._describe(findings),
+            "candidate_pattern_ids": [best.id] if best else [],
+            "raw_findings": findings,
+        }
+
+    def _has_embedded_subtitles(self, video_path: Path) -> bool:
+        return len(self.prober.list_subtitle_streams(video_path)) > 0
+
+    def _inspect(self, release_root: Path, sample_video: Path) -> dict:
+        """Gather structural facts about the release."""
+        known_exts = self.kb.known_extensions()
+        findings: dict = {
+            "has_subs_folder": False,
+            "subs_strategy": None,  # "flat" | "episode_subfolder"
+            "subs_root": None,
+            "adjacent_subs": False,
+            "has_embedded": self._has_embedded_subtitles(sample_video),
+            "files_per_episode": 0,
+            "has_lang_tokens": False,
+            "has_numeric_prefix": False,
+        }
+
+        # Check for Subs/ folder — adjacent or at release root
+        for subs_candidate in (
+            sample_video.parent / "Subs",
+            release_root / "Subs",
+        ):
+            children = self.scanner.scan_dir(subs_candidate)
+            if not children:
+                continue
+
+            findings["has_subs_folder"] = True
+            findings["subs_root"] = str(subs_candidate)
+
+            # Is it flat or episode_subfolder?
+            sub_files = [
+                c for c in children if c.is_file and c.suffix.lower() in known_exts
+            ]
+            sub_dirs = [c for c in children if c.is_dir]
+
+            if sub_dirs and not sub_files:
+                findings["subs_strategy"] = "episode_subfolder"
+                # Count files in a sample subfolder
+                sample_files = [
+                    f
+                    for f in self.scanner.scan_dir(sub_dirs[0].path)
+                    if f.is_file and f.suffix.lower() in known_exts
+                ]
+                findings["files_per_episode"] = len(sample_files)
+                # Check naming conventions
+                for f in sample_files:
+                    parts = f.stem.split("_")
+                    if parts[0].isdigit():
+                        findings["has_numeric_prefix"] = True
+                    if any(
+                        self.kb.is_known_lang_token(t.lower())
+                        for t in f.stem.replace("_", ".").split(".")
+                    ):
+                        findings["has_lang_tokens"] = True
+            else:
+                findings["subs_strategy"] = "flat"
+                findings["files_per_episode"] = len(sub_files)
+                for f in sub_files:
+                    if any(
+                        self.kb.is_known_lang_token(t.lower())
+                        for t in f.stem.replace("_", ".").split(".")
+                    ):
+                        findings["has_lang_tokens"] = True
+            break
+
+        # Check adjacent subs (next to the video)
+        if not findings["has_subs_folder"]:
+            adjacent = [
+                e
+                for e in self.scanner.scan_dir(sample_video.parent)
+                if e.is_file and e.suffix.lower() in known_exts
+            ]
+            if adjacent:
+                findings["adjacent_subs"] = True
+                findings["files_per_episode"] = len(adjacent)
+
+        return findings
+
+    def _match_pattern(self, findings: dict) -> tuple[SubtitlePattern | None, float]:
+        """Score all known patterns against the findings."""
+        scores: list[tuple[float, SubtitlePattern]] = []
+
+        for pattern in self.kb.patterns().values():
+            score = self._score(pattern, findings)
+            scores.append((score, pattern))
+
+        if not scores:
+            return None, 0.0
+
+        scores.sort(key=lambda x: x[0], reverse=True)
+        best_score, best_pattern = scores[0]
+
+        if best_score < 0.4:
+            return None, best_score
+
+        return best_pattern, best_score
+
+    def _score(self, pattern: SubtitlePattern, findings: dict) -> float:
+        """Return a 0.0–1.0 match score for this pattern against the findings."""
+        score = 0.0
+        total = 0.0
+
+        strategy = pattern.scan_strategy
+
+        if strategy == ScanStrategy.EMBEDDED:
+            total += 1
+            if findings.get("has_embedded"):
+                score += 1.0
+            if not findings.get("has_subs_folder") and not findings.get(
+                "adjacent_subs"
+            ):
+                score += 0.5
+                total += 0.5
+
+        elif strategy == ScanStrategy.EPISODE_SUBFOLDER:
+            total += 3
+            if findings.get("has_subs_folder"):
+                score += 1.0
+            if findings.get("subs_strategy") == "episode_subfolder":
+                score += 2.0
+
+        elif strategy == ScanStrategy.FLAT:
+            total += 2
+            if findings.get("has_subs_folder"):
+                score += 1.0
+            if findings.get("subs_strategy") == "flat":
+                score += 1.0
+
+        elif strategy == ScanStrategy.ADJACENT:
+            total += 2
+            if findings.get("adjacent_subs"):
+                score += 1.0
+            if not findings.get("has_subs_folder"):
+                score += 1.0
+
+        return score / total if total > 0 else 0.0
+
+    def _describe(self, findings: dict) -> str:
+        parts = []
+        if findings.get("has_subs_folder"):
+            strategy = findings.get("subs_strategy", "?")
+            n = findings.get("files_per_episode", 0)
+            parts.append(f"Subs/ folder found ({strategy}), ~{n} file(s) per episode")
+            if findings.get("has_numeric_prefix"):
+                parts.append("files have numeric prefix (e.g. 2_English.srt)")
+            if findings.get("has_lang_tokens"):
+                parts.append("language tokens found in filenames")
+        elif findings.get("adjacent_subs"):
+            parts.append("subtitle files adjacent to video")
+        else:
+            parts.append("no external subtitle files found")
+
+        if findings.get("has_embedded"):
+            parts.append("embedded tracks detected")
+
+        return " — ".join(parts) if parts else "nothing found"

alfred/domain/subtitles/services/utils.py

@@ -0,0 +1,21 @@
+"""Subtitle service utilities."""
+
+from ..entities import SubtitleScanResult
+
+
+def available_subtitles(tracks: list[SubtitleScanResult]) -> list[SubtitleScanResult]:
+    """
+    Return the distinct subtitle tracks available, deduped by (language, type).
+
+    Useful to display what is available for a media item regardless of user
+    preferences — e.g. eng, eng.sdh, fra all show up as separate entries.
+    """
+    seen: set[tuple] = set()
+    result: list[SubtitleScanResult] = []
+    for track in tracks:
+        lang = track.language.code if track.language else None
+        key = (lang, track.subtitle_type)
+        if key not in seen:
+            seen.add(key)
+            result.append(track)
+    return result

alfred/domain/subtitles/value_objects.py

@@ -1,91 +1,102 @@
 """Subtitle domain value objects."""
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from enum import Enum
 
-from ..shared.exceptions import ValidationError
+
+class ScanStrategy(Enum):
+    """How to locate subtitle files for a given release."""
+
+    ADJACENT = "adjacent"  # .srt next to the video
+    FLAT = "flat"  # Subs/*.srt
+    EPISODE_SUBFOLDER = "episode_subfolder"  # Subs/{episode_name}/*.srt
+    EMBEDDED = "embedded"  # tracks inside the video container
 
 
-class Language(Enum):
-    """Supported subtitle languages."""
+class TypeDetectionMethod(Enum):
+    """How to differentiate standard / SDH / forced when tokens are ambiguous."""
 
-    ENGLISH = "en"
-    FRENCH = "fr"
-
-    @classmethod
-    def from_code(cls, code: str) -> "Language":
-        """
-        Get language from ISO 639-1 code.
-
-        Args:
-            code: Two-letter language code
-
-        Returns:
-            Language enum value
-
-        Raises:
-            ValidationError: If code is not supported
-        """
-        code_lower = code.lower()
-        for lang in cls:
-            if lang.value == code_lower:
-                return lang
-        raise ValidationError(f"Unsupported language code: {code}")
+    TOKEN_IN_NAME = "token_in_name"
+    SIZE_AND_COUNT = "size_and_count"
+    FFPROBE_METADATA = "ffprobe_metadata"
 
 
-class SubtitleFormat(Enum):
-    """Supported subtitle formats."""
-
-    SRT = "srt"  # SubRip
-    ASS = "ass"  # Advanced SubStation Alpha
-    SSA = "ssa"  # SubStation Alpha
-    VTT = "vtt"  # WebVTT
-    SUB = "sub"  # MicroDVD
-
-    @classmethod
-    def from_extension(cls, extension: str) -> "SubtitleFormat":
-        """
-        Get format from file extension.
-
-        Args:
-            extension: File extension (with or without dot)
-
-        Returns:
-            SubtitleFormat enum value
-
-        Raises:
-            ValidationError: If extension is not supported
-        """
-        ext = extension.lower().lstrip(".")
-        for fmt in cls:
-            if fmt.value == ext:
-                return fmt
-        raise ValidationError(f"Unsupported subtitle format: {extension}")
+class SubtitleType(Enum):
+    STANDARD = "standard"
+    SDH = "sdh"
+    FORCED = "forced"
+    UNKNOWN = "unknown"
 
 
 @dataclass(frozen=True)
-class TimingOffset:
-    """
-    Value object representing subtitle timing offset in milliseconds.
+class SubtitleFormat:
+    """A known subtitle file format."""
 
-    Used for synchronizing subtitles with video.
+    id: str
+    extensions: list[str]
+    description: str = ""
+
+    def matches_extension(self, ext: str) -> bool:
+        return ext.lower() in [e.lower() for e in self.extensions]
+
+
+@dataclass(frozen=True)
+class SubtitleLanguage:
+    """A known subtitle language with its recognition tokens."""
+
+    code: str  # ISO 639-1
+    tokens: list[str]  # lowercase
+
+    def matches_token(self, token: str) -> bool:
+        return token.lower() in self.tokens
+
+
+@dataclass(frozen=True)
+class SubtitlePattern:
+    """
+    A known structural pattern for how a release group organises subtitle files.
+
+    Patterns are loaded from alfred/knowledge/patterns/*.yaml and are
+    independent of any specific release group — multiple groups can share
+    the same pattern.
     """
 
-    milliseconds: int
+    id: str
+    description: str
+    scan_strategy: ScanStrategy
+    root_folder: str | None  # e.g. "Subs", None for adjacent/embedded
+    type_detection: TypeDetectionMethod
+    version: str = "1.0"
 
-    def __post_init__(self):
-        """Validate timing offset."""
-        if not isinstance(self.milliseconds, int):
-            raise ValidationError(
-                f"Timing offset must be an integer, got {type(self.milliseconds)}"
-            )
 
-    def to_seconds(self) -> float:
-        """Convert to seconds."""
-        return self.milliseconds / 1000.0
+@dataclass(frozen=True)
+class SubtitleMatchingRules:
+    """
+    Effective rules after scope resolution (global → group → show → season → episode).
+    Only stores actual values — None means "inherited, not overridden at this level".
+    """
 
-    def __str__(self) -> str:
-        return f"{self.milliseconds}ms"
+    preferred_languages: list[str] = field(default_factory=list)  # ISO 639-1 codes
+    preferred_formats: list[str] = field(default_factory=list)  # format ids
+    allowed_types: list[str] = field(default_factory=list)  # SubtitleType ids
+    format_priority: list[str] = field(default_factory=list)  # ordered format ids
+    min_confidence: float = 0.7
 
-    def __repr__(self) -> str:
-        return f"TimingOffset({self.milliseconds})"
+
+class RuleScopeLevel(str, Enum):
+    """At which level a subtitle rule set applies."""
+
+    GLOBAL = "global"
+    RELEASE_GROUP = "release_group"
+    MOVIE = "movie"
+    SHOW = "show"
+    SEASON = "season"
+    EPISODE = "episode"
+
+
+@dataclass(frozen=True)
+class RuleScope:
+    """At which level a rule set applies."""
+
+    level: RuleScopeLevel
+    identifier: str | None = None  # imdb_id, group name, "S01", "S01E03"…

alfred/domain/tv_shows/__init__.py

@@ -2,18 +2,22 @@
 
 from .entities import Episode, Season, TVShow
 from .exceptions import InvalidEpisode, SeasonNotFound, TVShowNotFound
-from .services import TVShowService
-from .value_objects import EpisodeNumber, SeasonNumber, ShowStatus
+from .value_objects import (
+    CollectionStatus,
+    EpisodeNumber,
+    SeasonNumber,
+    ShowStatus,
+)
 
 __all__ = [
     "TVShow",
     "Season",
     "Episode",
     "ShowStatus",
+    "CollectionStatus",
     "SeasonNumber",
     "EpisodeNumber",
     "TVShowNotFound",
     "InvalidEpisode",
     "SeasonNotFound",
-    "TVShowService",
 ]