"""Registry of help documentation files for this plugin.

Tools and extensions reference help topics by name; the registry returns
the absolute file path that build-skill should inject into the agent's
system prompt as agent.system.tool.<tool_name>.md content.

Per a0-plugin-router SKILL.md: help/<topic>/help.md is NOT auto-loaded.
Tools must reference the path explicitly.
"""
import os
from typing import Optional

_PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
_HELP_DIR = os.path.join(_PLUGIN_ROOT, "help")

_TOPICS = {
    "context_budgeting": "management/context-budgeting.md",
    "errors": "management/errors.md",
    "tool_governance": "management/tool-governance.md",
    "library_query": "library/query.md",
    "library_extract": "library/extract.md",
    "runtime": "operations/runtime.md",
    "deployment": "operations/deployment.md",
    "git": "operations/git.md",
    "validation": "testing/validation.md",
}

def list_topics() -> list[str]:
    return sorted(_TOPICS.keys())

def get_path(topic: str) -> Optional[str]:
    rel = _TOPICS.get(topic)
    if not rel: return None
    p = os.path.join(_HELP_DIR, rel)
    return p if os.path.exists(p) else None

def get_relative_path(topic: str) -> Optional[str]:
    rel = _TOPICS.get(topic)
    return f"help/{rel}" if rel else None

def get_content(topic: str) -> Optional[str]:
    p = get_path(topic)
    if not p: return None
    with open(p) as f: return f.read()