"""Locate and read the framework's agent instructions.

`read_instructions` returns AGENTS.md and AGENT_QUERY_GUIDE.md so an agent
whose only access is MCP still gets the operating rules. In a source checkout
the documents live next to this package (the framework root); in an installed
wheel they are bundled under `kb_framework/_docs/`. Both lookups are explicit —
there is never a fallback to files inside the data vault.
"""

from __future__ import annotations

from pathlib import Path
from typing import Any, Dict

DOCUMENT_NAMES = ("AGENTS.md", "AGENT_QUERY_GUIDE.md")
_PACKAGE_DIR = Path(__file__).resolve().parent
# Source checkout: the framework repository root (parent of this package).
FRAMEWORK_ROOT = _PACKAGE_DIR.parent
_BUNDLED_DOCS = _PACKAGE_DIR / "_docs"


def instructions_root() -> Path:
    """Directory holding the instruction documents for this installation."""
    if (FRAMEWORK_ROOT / DOCUMENT_NAMES[0]).is_file():
        return FRAMEWORK_ROOT
    return _BUNDLED_DOCS


def read_instructions() -> Dict[str, Any]:
    root = instructions_root()
    documents = [
        {"path": name, "content": (root / name).read_text(encoding="utf-8")}
        for name in DOCUMENT_NAMES
    ]
    return {"framework_root": str(root), "documents": documents}