feat: generic MetadataStore + read_release_metadata + query_library

- Extract MetadataStore from SubtitleMetadataStore (alfred/infrastructure/metadata/).
  Generic load/save + typed update helpers (update_parse, update_probe, update_tmdb)
  for the per-release .alfred/metadata.yaml.
- SubtitleMetadataStore becomes a thin facade — owns subtitle_history shape,
  delegates I/O to MetadataStore.
- Agent._execute_tool_call auto-persists successful analyze_release / probe_media /
  find_media_imdb_id results to the release's .alfred file. find_media_imdb_id
  follows release_focus when it has no path argument.
- New tools:
  · read_release_metadata(release_path) — cacheable, key=release_path.
    Returns the .alfred content or has_metadata=false.
  · query_library(name) — substring scan across configured library roots.
- Both new tools added to CORE_TOOLS (always visible).

alfred/agent/agent.py

@@ -3,8 +3,10 @@
 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
 
@@ -243,6 +245,7 @@ class Agent:
 
         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.
         """
@@ -255,6 +258,11 @@ class Agent:
             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 []
@@ -263,6 +271,62 @@ class Agent:
                 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]]:

alfred/agent/prompt.py

@@ -17,6 +17,8 @@ CORE_TOOLS: tuple[str, ...] = (
     "set_language",
     "set_path_for_folder",
     "list_folder",
+    "read_release_metadata",
+    "query_library",
     "start_workflow",
     "end_workflow",
 )

alfred/agent/registry.py

@@ -138,6 +138,8 @@ def make_tools(settings) -> dict[str, Tool]:
     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,

alfred/agent/tools/filesystem.py

@@ -30,6 +30,8 @@ from alfred.application.filesystem.resolve_destination import (
 from alfred.infrastructure.filesystem import FileManager, create_folder, move
 from alfred.infrastructure.filesystem.ffprobe import probe
 from alfred.infrastructure.filesystem.find_video import find_video_file
+from alfred.infrastructure.metadata import MetadataStore
+from alfred.infrastructure.persistence import get_memory
 
 _LEARNED_ROOT = Path(_alfred_pkg.__file__).parent.parent / "data" / "knowledge"
 
@@ -288,3 +290,76 @@ def list_folder(folder_type: str, path: str = ".") -> dict[str, Any]:
     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/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.