feat(deck): HTML slide-deck generator + universal skill loader

openkb/agent/chat.py

@@ -60,6 +60,8 @@
     "  /lint          Lint the knowledge base\n"
     "  /add <path>    Add a document or directory to the knowledge base\n"
     '  /skill new <name> "<intent>"   Compile a skill from the wiki\n'
+    '  /deck new [--critique] [--skill <name>] <name> "<intent>"   Generate an HTML deck from the wiki\n'
+    "  /critique <path-to-html>   Run html-critic skill on a file (CSS bugs, layout, self-containment)\n"
     "  /help          Show this"
 )
 
@@ -216,6 +218,8 @@ def _bottom_toolbar(session: ChatSession) -> FormattedText:
     ("/lint",   "Lint the knowledge base"),
     ("/add",    "Add a document or directory"),
     ("/skill",  "Compile a skill (try `/skill new <name> \"intent\"`)"),
+    ("/deck",   "Generate a deck (try `/deck new <name> \"intent\"`)"),
+    ("/critique", "Run html-critic skill on a file (e.g. `/critique output/decks/foo/index.html`)"),
 ]
 
 
@@ -558,7 +562,9 @@ async def _handle_slash_skill(arg: str, kb_dir: Path, style: Style) -> None:
         _fmt(style, ("class:error", f"[ERROR] {exc}\n"))
         return
 
-    # Surface validation issues from Generator.run (same gate as CLI).
+    # Surface validation issues from Generator.run. Unlike the CLI
+    # (which exits 1 on validation errors), chat is interactive — print
+    # issues inline and continue so the user can inspect and iterate.
     result = gen.validation
     if result is not None and (result.errors or result.warnings):
         _fmt(style, ("class:error", "[WARN] Validation found issues:\n"))
@@ -576,6 +582,120 @@ async def _handle_slash_skill(arg: str, kb_dir: Path, style: Style) -> None:
         f"edit files under output/skills/{name}/ directly.\n"))
 
 
+async def _handle_slash_deck(arg: str, kb_dir: Path, style: Style) -> None:
+    """Dispatch ``/deck new [--critique] <name> "<intent>"``.
+
+    Mirrors :func:`_handle_slash_skill`: validates the name, runs the
+    same wiki preflight gate, refuses to overwrite an existing deck
+    (chat has no ``-y`` flag), then invokes ``Generator(target_type="deck")``.
+    """
+    import shlex
+
+    try:
+        parts = shlex.split(arg) if arg else []
+    except ValueError as exc:
+        _fmt(style, ("class:error", f"[ERROR] Could not parse: {exc}\n"))
+        return
+    if not parts:
+        _fmt(style, ("class:error",
+            "Usage: /deck new [--critique] <name> \"<intent>\"\n"))
+        return
+
+    sub = parts[0].lower()
+    if sub != "new":
+        _fmt(style, ("class:error", f"Unknown deck subcommand: {sub}. Try /deck new.\n"))
+        return
+
+    # Parse optional --critique flag and --skill <name> option. Both can
+    # appear anywhere among the remaining tokens.
+    rest = parts[1:]
+    critique = False
+    skill_name: str | None = None
+    filtered: list[str] = []
+    i = 0
+    while i < len(rest):
+        tok = rest[i]
+        if tok == "--critique":
+            critique = True
+        elif tok == "--skill" and i + 1 < len(rest):
+            skill_name = rest[i + 1]
+            i += 1
+        elif tok.startswith("--skill="):
+            skill_name = tok.split("=", 1)[1]
+        else:
+            filtered.append(tok)
+        i += 1
+
+    if len(filtered) < 2:
+        _fmt(style, ("class:error",
+            "Usage: /deck new [--critique] [--skill <skill>] <name> \"<intent>\"\n"))
+        return
+
+    name = filtered[0]
+    intent = " ".join(filtered[1:])
+
+    # Reuse the shared safety gates from the CLI (name validation,
+    # wiki dir, wiki content). Chat has no -y flag, so existing decks
+    # block with a clear instruction to delete first.
+    from openkb.cli import _preflight_skill_new
+    err = _preflight_skill_new(kb_dir, name)
+    if err:
+        # Reword "Skill name" → "Deck name" so error matches the command.
+        err = err.replace("Skill name", "Deck name")
+        _fmt(style, ("class:error", f"[ERROR] {err}\n"))
+        return
+
+    from openkb.deck import deck_dir
+    target = deck_dir(kb_dir, name)
+    if target.exists():
+        _fmt(style, ("class:error",
+            f"[ERROR] output/decks/{name}/ already exists. Remove it first "
+            f"with `rm -rf output/decks/{name}` and re-run.\n"))
+        return
+
+    # Load model from KB config
+    from openkb.config import load_config, DEFAULT_CONFIG
+    config = load_config(kb_dir / ".openkb" / "config.yaml")
+    model = config.get("model", DEFAULT_CONFIG["model"])
+
+    from openkb.skill.generator import Generator
+    skill_label = skill_name if skill_name else "openkb-deck-editorial (default)"
+    _fmt(
+        style,
+        ("class:slash.help", f"Generating deck '{name}' via skill {skill_label}...\n"),
+    )
+    gen = Generator(
+        target_type="deck",
+        name=name,
+        intent=intent,
+        kb_dir=kb_dir,
+        model=model,
+        critique=critique,
+        skill_name=skill_name,
+    )
+    try:
+        await gen.run()
+    except RuntimeError as exc:
+        _fmt(style, ("class:error", f"[ERROR] {exc}\n"))
+        return
+
+    # Surface validation issues from Generator.run. Unlike the CLI
+    # (which exits 1 on validation errors), chat is interactive — print
+    # issues inline and continue so the user can inspect and iterate.
+    result = gen.validation
+    if result is not None and (result.errors or result.warnings):
+        _fmt(style, ("class:error", "[WARN] Validation found issues:\n"))
+        for err in result.errors:
+            _fmt(style, ("class:error", f"  ERROR:   {err}\n"))
+        for warn in result.warnings:
+            _fmt(style, ("class:error", f"  WARN:    {warn}\n"))
+
+    _fmt(style, ("class:slash.ok", f"Saved: output/decks/{name}/index.html\n"))
+    _fmt(style, ("class:slash.help",
+        f"Iterate: ask follow-up questions in this chat and the agent can "
+        f"edit files under output/decks/{name}/ directly.\n"))
+
+
 async def _handle_slash(
     cmd: str,
     kb_dir: Path,
@@ -643,13 +763,83 @@ async def _handle_slash(
         await _handle_slash_skill(arg, kb_dir, style)
         return None
 
+    if head == "/deck":
+        await _handle_slash_deck(arg, kb_dir, style)
+        return None
+
+    if head == "/critique":
+        await _handle_slash_critique(arg, kb_dir, style)
+        return None
+
     _fmt(
         style,
         ("class:error", f"Unknown command: {head}. Try /help.\n"),
     )
     return None
 
 
+async def _handle_slash_critique(arg: str, kb_dir: Path, style: Style) -> None:
+    """``/critique <path>`` — run the openkb-html-critic skill on a file.
+
+    The skill reads the HTML, fixes CSS specificity bugs / missing nav /
+    self-containment violations, and writes the corrected file back. It
+    will not touch slide content (numbers, names, quotes).
+    """
+    path = arg.strip()
+    if not path:
+        _fmt(
+            style,
+            ("class:slash.help", "Usage: /critique <path-to-html>\n"),
+        )
+        return
+
+    target = (kb_dir / path).resolve() if not Path(path).is_absolute() else Path(path)
+    if not target.is_file():
+        _fmt(style, ("class:error", f"[ERROR] File not found: {path}\n"))
+        return
+
+    from openkb.agent.skill_runner import (
+        MAX_TURNS_WITH_CRITIQUE,
+        SkillNotFoundError,
+        run_skill,
+    )
+    from openkb.config import DEFAULT_CONFIG, load_config
+
+    config = load_config(kb_dir / ".openkb" / "config.yaml")
+    model = config.get("model", DEFAULT_CONFIG["model"])
+
+    # Path passed to the skill is relative to kb_dir (the agent's cwd
+    # conceptually). The skill's read_file/write_file tools operate
+    # under wiki/ and output/ scopes — give it the relative form so
+    # write_kb_file resolves correctly.
+    try:
+        rel = target.relative_to(kb_dir)
+        rel_str = str(rel)
+    except ValueError:
+        # Outside KB — pass absolute, write tool will reject, but read
+        # may still work for a critique-only diagnostic.
+        rel_str = str(target)
+
+    _fmt(style, ("class:slash.ok", f"Critiquing {rel_str}...\n"))
+
+    try:
+        await run_skill(
+            skill_name="openkb-html-critic",
+            intent=f"Critique and patch the HTML file at: {rel_str}",
+            kb_dir=kb_dir,
+            model=model,
+            max_turns=40,
+        )
+    except SkillNotFoundError as exc:
+        _fmt(style, ("class:error", f"[ERROR] {exc}\n"))
+        return
+    except RuntimeError as exc:
+        _fmt(style, ("class:error", f"[ERROR] {exc}\n"))
+        return
+
+    _fmt(style, ("class:slash.ok", f"Critique pass complete: {rel_str}\n"))
+
+
 async def run_chat(
     kb_dir: Path,
     session: ChatSession,

openkb/agent/query.py

@@ -102,12 +102,19 @@ def build_chat_agent(
     language: str = "en",
 ) -> Agent:
     """Build the chat agent: query agent + a write tool restricted to
-    ``<kb>/wiki/explorations/**`` and ``<kb>/output/**``.
+    ``<kb>/wiki/explorations/**`` and ``<kb>/output/**`` + a ``ShellTool``
+    advertising locally-installed Anthropic-style skills.
 
     This is the variant used by the interactive ``openkb chat`` REPL so users
     can iterate on generated artifacts (e.g. ``output/skills/<name>/``) via
     natural-language follow-ups without giving the agent unrestricted write
     access to the wiki.
+
+    Skill discovery: ``openkb/agent/skills.scan_local_skills`` looks in
+    ``<kb>/skills/``, ``~/.openkb/skills/``, ``~/.claude/skills/`` for
+    ``SKILL.md`` files. Any found skill is exposed to the agent via
+    ``ShellTool.environment.skills`` so the model can ``cat`` the skill body
+    and follow its instructions when the user's request matches.
     """
     wiki_root = str(kb_dir / "wiki")
     kb_root = str(kb_dir)
@@ -130,7 +137,107 @@ def write_file(path: str, content: str) -> str:
         """
         return write_kb_file(path, content, kb_root)
 
-    return base.clone(tools=[*base.tools, write_file])
+    extra_tools: list = [write_file]
+    skill_instructions_addendum = ""
+
+    # Skill discovery via function tools. The agents SDK has a richer
+    # ``ShellTool``+``ShellToolLocalSkill`` mechanism for this, but those
+    # are OpenAI Responses-API hosted tools; LiteLLM routes through
+    # ChatCompletions which rejects hosted tools. So we use plain
+    # ``function_tool`` primitives that work with any LiteLLM-routed model.
+    from openkb.agent.skills import scan_local_skills
+
+    skills = scan_local_skills(kb_dir)
+    skill_index = {s["name"]: s for s in skills}
+
+    if skill_index:
+        skill_list_text = _format_skill_list(skills)
+
+        @function_tool
+        def list_skills() -> str:
+            """List skills available in this environment.
+
+            Returns a text catalog of installed Anthropic-style skills.
+            Each entry has a name and a one-line description; use the
+            description to decide whether the skill matches the user's
+            request, then call ``read_skill(name)`` to load its body.
+            """
+            return skill_list_text
+
+        @function_tool
+        def read_skill(name: str) -> str:
+            """Read a skill's ``SKILL.md`` body.
+
+            Call this once you've decided a skill matches the user's
+            request. The returned text is the full skill instructions
+            (frontmatter stripped). Follow it as your working method
+            and write outputs via the ``write_file`` tool.
+
+            Args:
+                name: skill name as listed by ``list_skills``.
+            """
+            entry = skill_index.get(name)
+            if entry is None:
+                return (
+                    f"Unknown skill: {name!r}. Call list_skills() to see "
+                    f"available skills."
+                )
+            md_path = Path(entry["path"]) / "SKILL.md"
+            try:
+                text = md_path.read_text(encoding="utf-8")
+            except OSError as exc:
+                return f"Could not read {md_path}: {exc}"
+            # Strip frontmatter, return body only.
+            from openkb.agent.skills import _parse_frontmatter
+            _, body = _parse_frontmatter(text)
+            return body
+
+        extra_tools.extend([list_skills, read_skill])
+
+        # Build the prompt addendum listing skill names + descriptions
+        # right inside the system prompt so the model sees them up front
+        # and knows what to look for, even before deciding to call
+        # list_skills(). This is the difference between "agent
+        # eventually discovers skills" and "agent treats skill use as
+        # the default for matching requests".
+        skill_lines = []
+        for s in skills:
+            desc_one_line = " ".join(s["description"].split())
+            skill_lines.append(f"- **{s['name']}** — {desc_one_line}")
+        skill_instructions_addendum = (
+            "\n\n## Available skills\n\n"
+            "The following Anthropic-style skill packages are installed in "
+            "this environment. **When a user request matches a skill's "
+            "description (e.g. 'make a deck', 'generate slides', 'draft a "
+            "report'), you MUST call `read_skill(name)` to load that "
+            "skill's full instructions and follow them strictly** — do not "
+            "freestyle the output format if a skill covers it.\n\n"
+            + "\n".join(skill_lines)
+            + "\n\nIf no listed skill matches the request, proceed with "
+            "your default tools."
+        )
+
+    new_instructions = (base.instructions or "") + skill_instructions_addendum
+    return base.clone(
+        tools=[*base.tools, *extra_tools],
+        instructions=new_instructions,
+    )
+
+
+def _format_skill_list(skills: list[dict[str, str]]) -> str:
+    """Render the skill catalog as a compact text block for the agent."""
+    if not skills:
+        return "No skills installed."
+    lines = [f"{len(skills)} skill(s) available:\n"]
+    for s in skills:
+        lines.append(f"- {s['name']}")
+        # Indent description; keep it one paragraph so the agent reads it fast.
+        desc = " ".join(s["description"].split())
+        lines.append(f"    {desc}")
+    lines.append(
+        "\nTo use a skill, call read_skill(name) and follow its instructions."
+    )
+    return "\n".join(lines)
 
 
 async def run_query(