Search all entries in a Norton Guide for a query string anywhere in the body.

This is similar to line_search_guide but returns the entire entry content for any entry that contains a match, rather than just the matching lines.

The search is also done on the whole body, with lines joined using a space.

Args: path: Absolute path to the .ng file. query: The text string to search for. case_sensitive: When True, the search is case-sensitive. Defaults to False.

Returns: A list of match dictionaries. Each dictionary contains:

- ``offset`` (int): Byte offset of the matching entry.
- ``type`` (str): ``"short"`` or ``"long"``.
- ``lines`` (list[str]): Plain-text lines of the entry.

Raises: FileNotFoundError: If path does not point to an existing file.

Follow a link in a short entry and return the target long entry.

Short entries in a Norton Guide are index-style pages where each line links to a long entry. This tool loads the short entry at offset, reads the link on line, and returns the plain-text content of the target long entry.

Args: path: Absolute path to the .ng file. offset: Byte offset of the short entry within the guide. line: Zero-based line index within the short entry whose link to follow.

Returns: A dictionary containing:

- ``source_offset`` (int): Offset of the short (source) entry.
- ``source_line`` (int): Line index that was followed.
- ``link_text`` (str): The text of the link line.
- ``target_offset`` (int): Offset of the target long entry.
- ``lines`` (list[str]): Plain-text lines of the target long entry.
- ``see_also`` (list[dict]): See-also items of the target entry, each
  with ``text`` and ``offset`` keys.

Raises: FileNotFoundError: If path does not point to an existing file. ValueError: If the offset does not point to a short entry, if line is out of range, or if the link has no associated target offset.

Return metadata for a Norton Guide database file.

Args: path: Absolute path to the .ng file.

Returns: A dictionary with the following keys:

- ``path`` (str): Resolved path to the guide.
- ``title`` (str): Guide title.
- ``credits`` (list[str]): Up to five credit lines.
- ``magic`` (str): Two-character magic marker (``"NG"`` or ``"EH"``).
- ``made_with`` (str): Tool used to build the guide.
- ``menu_count`` (int): Number of menus in the guide.
- ``file_size`` (int): File size in bytes.
- ``is_valid`` (bool): Whether the file is a recognised Norton Guide.

Raises: FileNotFoundError: If path does not point to an existing file.

Search all entries in a Norton Guide for lines matching a query string.

The search is performed on plain text (markup stripped) and returns all entries that contain at least one matching line.

Args: path: Absolute path to the .ng file. query: The text string to search for. case_sensitive: When True, the search is case-sensitive. Defaults to False.

Returns: A list of match dictionaries. Each dictionary contains:

- ``offset`` (int): Byte offset of the matching entry.
- ``type`` (str): ``"short"`` or ``"long"``.
- ``matching_lines`` (list[dict]): Each item has:

  - ``line_index`` (int): Zero-based line number within the entry.
  - ``text`` (str): Plain-text content of the matching line.

Raises: FileNotFoundError: If path does not point to an existing file.

List all entries in a Norton Guide database file.

Args: path: Absolute path to the .ng file.

Returns: A list of entry summary dictionaries. Each dictionary contains:

- ``offset`` (int): Byte offset of the entry within the guide.
- ``type`` (str): Entry type — ``"short"`` or ``"long"``.
- ``line_count`` (int): Number of lines in the entry.
- ``first_line`` (str): Plain-text content of the first line, or an
  empty string if the entry contains no lines.

Raises: FileNotFoundError: If path does not point to an existing file.

List Norton Guide (.ng) files available to the server.

Args: directory: Optional directory path to restrict the listing to. When omitted all configured guide directories are searched.

Returns: A sorted list of file-info dictionaries, each containing:

- ``path`` (str): Absolute path to the .ng file.
- ``name`` (str): Filename (without directory).
- ``size`` (int): File size in bytes.

Raises: FileNotFoundError: If directory is provided but does not exist. PermissionError: If directory is outside the configured guide dirs and allow_absolute_paths is False.

Return the menu structure of a Norton Guide database file.

Each menu in the guide is returned as a dictionary describing its title, the list of prompt strings, and the guide offsets associated with each prompt.

Args: path: Absolute path to the .ng file.

Returns: A list of menu dictionaries. Each dictionary contains:

- ``title`` (str): The menu title.
- ``prompts`` (list[str]): The menu prompt strings.
- ``offsets`` (list[int]): The guide offset for each prompt.

Raises: FileNotFoundError: If path does not point to an existing file.

Return the full plain-text content of the entry at a given offset.

Args: path: Absolute path to the .ng file. offset: Byte offset of the entry within the guide, as returned by list_entries or list_menus.

Returns: A dictionary containing:

- ``offset`` (int): The entry's offset.
- ``type`` (str): ``"short"`` or ``"long"``.
- ``lines`` (list[str]): Plain-text lines of the entry.
- ``see_also`` (list[dict]): For long entries only — each item has
  ``text`` (str) and ``offset`` (int) keys.  Empty list for short
  entries.

Raises: FileNotFoundError: If path does not point to an existing file. ValueError: If the offset does not point to a valid entry.

Return the raw source lines of the entry at a given offset.

Args: path: Absolute path to the .ng file. offset: Byte offset of the entry within the guide, as returned by list_entries or list_menus.

Returns: A dictionary containing:

- ``offset`` (int): The entry's offset.
- ``type`` (str): ``"short"`` or ``"long"``.
- ``lines`` (list[str]): Raw source lines of the entry, as strings.
- ``see_also`` (list[dict]): For long entries only — each item has
  ``text`` (str) and ``offset`` (int) keys.  Empty list for short
  entries.