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.