{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "schema_version": "1.0.0",
  "app": {
    "name": "Follia",
    "vendor": "ForgeBoro",
    "version": "1.0.0",
    "website": "https://follia.forgeboro.com",
    "support_email": "support@forgeboro.com",
    "documentation_url": "https://follia.forgeboro.com/help.html",
    "description": "Distraction-free classic ePub reader and synchronized text-to-speech audio companion."
  },
  "runtime_bridge": {
    "window_attachment": "window.__FOLLIA_AGENT_SPEC__",
    "methods": [
      {
        "name": "getSpec",
        "description": "Returns this full machine-readable agent specification."
      },
      {
        "name": "listActions",
        "description": "Returns array of currently supported DOM actions and selectors."
      },
      {
        "name": "triggerAction",
        "description": "Dispatches a synthetic click or event targeting a data-action attribute.",
        "parameters": {
          "action": "string (e.g. 'open-help', 'play-tts', 'next-page')",
          "details": "optional object with action-specific payload"
        }
      },
      {
        "name": "getShortcuts",
        "description": "Returns list of keyboard shortcuts supported in the visual reader."
      }
    ]
  },
  "dom_hooks": {
    "tools": [
      {
        "selector": "[data-tool=\"library-filter\"]",
        "description": "Search input for filtering local ePub catalog by title or author."
      },
      {
        "selector": "[data-tool=\"gutenberg-search\"]",
        "description": "Search input for querying Project Gutenberg remote catalog."
      },
      {
        "selector": "[data-tool=\"tts-controller\"]",
        "description": "Floating media player dock with audio controls and page indicators."
      },
      {
        "selector": "[data-tool=\"help-modal\"]",
        "description": "Interactive Help and Documentation dialog."
      }
    ],
    "actions": [
      {
        "action": "open-help",
        "selector": "[data-action=\"open-help\"]",
        "description": "Opens the in-app HelpModal with searchable guide and shortcut cheat sheet."
      },
      {
        "action": "open-drawer",
        "selector": "[data-action=\"open-drawer\"]",
        "description": "Opens the navigation drawer with library, store, and compliance links."
      },
      {
        "action": "import-epub",
        "selector": "[data-action=\"import-epub\"]",
        "description": "Invokes the native file picker to import local DRM-free ePub files."
      },
      {
        "action": "open-gutenberg",
        "selector": "[data-action=\"open-gutenberg\"]",
        "description": "Navigates to the Project Gutenberg discovery and download screen."
      },
      {
        "action": "play-tts",
        "selector": "[data-action=\"play-tts\"]",
        "description": "Starts or resumes Text-to-Speech audio narration."
      },
      {
        "action": "pause-tts",
        "selector": "[data-action=\"pause-tts\"]",
        "description": "Pauses active Text-to-Speech audio narration."
      },
      {
        "action": "prev-page",
        "selector": "[data-action=\"prev-page\"]",
        "description": "Scrolls back 1 visual page."
      },
      {
        "action": "next-page",
        "selector": "[data-action=\"next-page\"]",
        "description": "Scrolls forward 1 visual page."
      },
      {
        "action": "prev-10-pages",
        "selector": "[data-action=\"prev-10-pages\"]",
        "description": "Fast rewinds 10 visual pages."
      },
      {
        "action": "next-10-pages",
        "selector": "[data-action=\"next-10-pages\"]",
        "description": "Fast forwards 10 visual pages."
      },
      {
        "action": "jump-sentence",
        "selector": "[data-action=\"jump-sentence\"]",
        "description": "Clicks a paragraph or sentence to jump speech synthesis position directly."
      }
    ]
  },
  "keyboard_shortcuts": [
    {
      "key": "Space",
      "description": "Toggle TTS playback (Play / Pause audio)"
    },
    {
      "key": "ArrowRight",
      "description": "Turn forward 1 page"
    },
    {
      "key": "ArrowLeft",
      "description": "Turn backward 1 page"
    },
    {
      "key": "Shift + ArrowRight",
      "description": "Skip forward 10 pages"
    },
    {
      "key": "Shift + ArrowLeft",
      "description": "Skip backward 10 pages"
    },
    {
      "key": "?",
      "description": "Open Help & Keyboard Shortcuts Modal"
    },
    {
      "key": "F1",
      "description": "Open Help & Documentation Modal"
    },
    {
      "key": "Escape",
      "description": "Close HelpModal, Dialogs, or Drawer"
    }
  ],
  "agent_tools": [
    {
      "name": "open_book",
      "description": "Opens a book from the local library into the visual reader.",
      "parameters": {
        "type": "object",
        "properties": {
          "book_id": {
            "type": "integer",
            "description": "The unique integer ID of the book in local storage."
          }
        },
        "required": ["book_id"]
      }
    },
    {
      "name": "navigate_pages",
      "description": "Navigates forward or backward by a specific page delta.",
      "parameters": {
        "type": "object",
        "properties": {
          "delta": {
            "type": "integer",
            "enum": [-10, -1, 1, 10],
            "description": "The number of pages to move (+1, -1, +10, -10)."
          }
        },
        "required": ["delta"]
      }
    },
    {
      "name": "toggle_tts",
      "description": "Toggles playback state of the Text-to-Speech audio engine.",
      "parameters": {
        "type": "object",
        "properties": {
          "desired_state": {
            "type": "string",
            "enum": ["play", "pause", "toggle"],
            "default": "toggle"
          }
        }
      }
    },
    {
      "name": "search_gutenberg",
      "description": "Queries the Gutenberg public domain catalog for books.",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Title, author, or genre search keywords."
          }
        },
        "required": ["query"]
      }
    }
  ]
}
