From 5c2d6eba9e805a2717a7eebb20fd0a063061b9e7 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 22:09:37 +0800
Subject: [PATCH 01/25] feat(deck): scaffold openkb/deck/ package with path
 helpers

---
 openkb/deck/__init__.py    | 33 +++++++++++++++++++++++++++++++++
 tests/test_deck_package.py | 18 ++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 openkb/deck/__init__.py
 create mode 100644 tests/test_deck_package.py

diff --git a/openkb/deck/__init__.py b/openkb/deck/__init__.py
new file mode 100644
index 00000000..79fa62c1
--- /dev/null
+++ b/openkb/deck/__init__.py
@@ -0,0 +1,33 @@
+"""Deck target — HTML slide-deck generator. Second Generator target after skill.
+
+This package mirrors openkb/skill/ structurally. Today it owns:
+* path construction — ``deck_dir`` / ``decks_root`` / ``deck_workspace_dir``
+
+A deck is a single self-contained ``index.html`` file at
+``<kb>/output/decks/<name>/index.html``. Workspace iteration history lives
+at ``<kb>/output/decks/<name>-workspace/iteration-N/``.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = [
+    "decks_root",
+    "deck_dir",
+    "deck_workspace_dir",
+]
+
+
+def decks_root(kb_dir: Path) -> Path:
+    """``<kb>/output/decks`` — the directory holding every compiled deck."""
+    return kb_dir / "output" / "decks"
+
+
+def deck_dir(kb_dir: Path, deck_name: str) -> Path:
+    """``<kb>/output/decks/<name>`` — one compiled deck's home."""
+    return decks_root(kb_dir) / deck_name
+
+
+def deck_workspace_dir(kb_dir: Path, deck_name: str) -> Path:
+    """``<kb>/output/decks/<name>-workspace`` — iteration history for a deck."""
+    return decks_root(kb_dir) / f"{deck_name}-workspace"
diff --git a/tests/test_deck_package.py b/tests/test_deck_package.py
new file mode 100644
index 00000000..cde0aace
--- /dev/null
+++ b/tests/test_deck_package.py
@@ -0,0 +1,18 @@
+"""Sanity test for deck package path helpers — mirrors test_skill_factory expectations."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from openkb.deck import deck_dir, deck_workspace_dir, decks_root
+
+
+def test_decks_root(tmp_path: Path):
+    assert decks_root(tmp_path) == tmp_path / "output" / "decks"
+
+
+def test_deck_dir(tmp_path: Path):
+    assert deck_dir(tmp_path, "transformers") == tmp_path / "output" / "decks" / "transformers"
+
+
+def test_deck_workspace_dir(tmp_path: Path):
+    assert deck_workspace_dir(tmp_path, "transformers") == tmp_path / "output" / "decks" / "transformers-workspace"

From 57684eae70ffc5534f30fc4c5ac3849875536a68 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 22:13:39 +0800
Subject: [PATCH 02/25] feat(deck): add write_deck_file + read_deck_file tools

---
 openkb/deck/tools.py     | 59 ++++++++++++++++++++++++++++++++++++++++
 tests/test_deck_tools.py | 47 ++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+)
 create mode 100644 openkb/deck/tools.py
 create mode 100644 tests/test_deck_tools.py

diff --git a/openkb/deck/tools.py b/openkb/deck/tools.py
new file mode 100644
index 00000000..bf9f145e
--- /dev/null
+++ b/openkb/deck/tools.py
@@ -0,0 +1,59 @@
+"""Path-scoped IO tools for the deck-create and deck-critic agents.
+
+* WRITE under deck root  — ``write_deck_file``
+* READ from deck root    — ``read_deck_file``
+
+Wiki read tools (``list_wiki_dir``, ``read_wiki_file_for_skill``,
+``get_skill_page_content``, ``read_skill_image``) are reused verbatim from
+``openkb.skill.tools`` — no duplication. Importers should pull those
+directly from there.
+
+Write boundary is enforced at the Python level: every path resolves and
+must stay inside the deck root. Absolute paths and ``..`` traversal are
+rejected outright. Mirror of ``openkb/skill/tools.py::write_skill_file``.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def write_deck_file(path: str, content: str, deck_root: str) -> str:
+    """Write a file under the deck directory.
+
+    Args:
+        path: Path relative to *deck_root* (e.g. ``"index.html"``).
+            Absolute paths and ``..`` traversal are rejected.
+        content: File contents.
+        deck_root: Absolute path to ``<kb>/output/decks/<name>``.
+    """
+    if path.startswith("/") or ".." in Path(path).parts:
+        return "Access denied: only relative paths within the deck directory are allowed."
+    root = Path(deck_root).resolve()
+    full = (root / path).resolve()
+    if not full.is_relative_to(root):
+        return "Access denied: path escapes deck root."
+    full.parent.mkdir(parents=True, exist_ok=True)
+    full.write_text(content, encoding="utf-8")
+    return f"Written: {path}"
+
+
+def read_deck_file(path: str, deck_root: str) -> str:
+    """Read a file from the deck directory.
+
+    Used by the critic agent to re-read the draft ``index.html`` for
+    revision — main's ``write_deck_file`` result string is "Written: X",
+    not the HTML body, so critic needs an explicit re-read tool.
+
+    Args:
+        path: Path relative to *deck_root* (e.g. ``"index.html"``).
+        deck_root: Absolute path to ``<kb>/output/decks/<name>``.
+    """
+    if path.startswith("/") or ".." in Path(path).parts:
+        return "Access denied: only relative paths within the deck directory are allowed."
+    root = Path(deck_root).resolve()
+    full = (root / path).resolve()
+    if not full.is_relative_to(root):
+        return "Access denied: path escapes deck root."
+    if not full.exists():
+        return f"File not found: {path}"
+    return full.read_text(encoding="utf-8")
diff --git a/tests/test_deck_tools.py b/tests/test_deck_tools.py
new file mode 100644
index 00000000..c80a1ea1
--- /dev/null
+++ b/tests/test_deck_tools.py
@@ -0,0 +1,47 @@
+"""Tests for deck-scoped IO tools. Mirrors tests/test_skill_tools.py for write_skill_file."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from openkb.deck.tools import read_deck_file, write_deck_file
+
+
+def test_write_then_read_roundtrip(tmp_path: Path):
+    deck_root = tmp_path / "deck"
+    msg = write_deck_file("index.html", "<html><body>hi</body></html>", str(deck_root))
+    assert msg.startswith("Written:")
+    content = read_deck_file("index.html", str(deck_root))
+    assert "<body>hi</body>" in content
+
+
+def test_write_creates_parent_dirs(tmp_path: Path):
+    deck_root = tmp_path / "deck"
+    write_deck_file("nested/sub/file.txt", "ok", str(deck_root))
+    assert (deck_root / "nested" / "sub" / "file.txt").read_text() == "ok"
+
+
+def test_write_rejects_absolute_path(tmp_path: Path):
+    msg = write_deck_file("/etc/passwd", "pwn", str(tmp_path / "deck"))
+    assert "Access denied" in msg
+    assert not Path("/etc/passwd_test_marker").exists()  # sanity
+
+
+def test_write_rejects_parent_traversal(tmp_path: Path):
+    deck_root = tmp_path / "deck"
+    msg = write_deck_file("../escape.txt", "pwn", str(deck_root))
+    assert "Access denied" in msg
+    assert not (tmp_path / "escape.txt").exists()
+
+
+def test_read_rejects_escape(tmp_path: Path):
+    deck_root = tmp_path / "deck"
+    deck_root.mkdir()
+    msg = read_deck_file("../../etc/passwd", str(deck_root))
+    assert "Access denied" in msg
+
+
+def test_read_missing_file(tmp_path: Path):
+    deck_root = tmp_path / "deck"
+    deck_root.mkdir()
+    msg = read_deck_file("index.html", str(deck_root))
+    assert "not found" in msg.lower()

From 31ee46fe277b3f601f9e114cdebf91bae15379db Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 22:20:08 +0800
Subject: [PATCH 03/25] feat(deck): structural validator with error/warning
 ValidationResult

---
 openkb/deck/validator.py     | 145 +++++++++++++++++++++++++++++++
 tests/test_deck_validator.py | 164 +++++++++++++++++++++++++++++++++++
 2 files changed, 309 insertions(+)
 create mode 100644 openkb/deck/validator.py
 create mode 100644 tests/test_deck_validator.py

diff --git a/openkb/deck/validator.py b/openkb/deck/validator.py
new file mode 100644
index 00000000..aea8b555
--- /dev/null
+++ b/openkb/deck/validator.py
@@ -0,0 +1,145 @@
+"""Structural validation for a generated deck.
+
+Mirrors ``openkb/skill/validator.py``'s ``ValidationResult`` shape so
+callers (``Generator.run``, the CLI's error reporter, the chat slash
+command) can format results identically regardless of artifact type.
+
+Errors block declare-success; warnings print but allow the deck to ship.
+The file is preserved even on error so the user can inspect the failure.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from html.parser import HTMLParser
+from pathlib import Path
+
+__all__ = ["ALLOWED_DATA_TYPES", "ValidationResult", "validate_deck"]
+
+
+ALLOWED_DATA_TYPES: frozenset[str] = frozenset(
+    {"cover", "chapter", "thesis", "quote", "compare", "data", "closing"}
+)
+
+MAX_FILE_BYTES = 2 * 1024 * 1024  # 2 MB
+MIN_SLIDES_HARD = 5              # error threshold
+MIN_SLIDES_SOFT = 8              # warning threshold (count outside [8,15])
+MAX_SLIDES_SOFT = 15
+MIN_DISTINCT_TYPES = 4
+MAX_CONSECUTIVE_SAME_TYPE = 2    # warning if run-length >= 3
+
+
+@dataclass
+class ValidationResult:
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+class _DeckParser(HTMLParser):
+    """Collects <section class="slide" data-type="..."> blocks and external refs."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.slide_types: list[str] = []   # data-type, in document order
+        self.external_links: list[str] = []  # offending href/src values
+        self._depth_in_slide = 0
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        a = dict(attrs)
+        if tag == "section" and "slide" in (a.get("class") or "").split():
+            self.slide_types.append((a.get("data-type") or "").strip())
+        elif tag == "link":
+            href = (a.get("href") or "").strip()
+            if href.startswith(("http://", "https://", "//")):
+                self.external_links.append(f"<link href={href!r}>")
+        elif tag == "script":
+            src = (a.get("src") or "").strip()
+            if src.startswith(("http://", "https://", "//")):
+                self.external_links.append(f"<script src={src!r}>")
+
+
+def validate_deck(deck_dir: Path) -> ValidationResult:
+    """Validate the generated deck at ``deck_dir/index.html``.
+
+    Returns a :class:`ValidationResult` with categorised issues. Never
+    raises for structural failures — those become entries in ``errors``.
+    Raises only for unforeseen I/O failures the caller would want to see.
+    """
+    result = ValidationResult()
+    index = deck_dir / "index.html"
+
+    if not index.is_file():
+        result.errors.append(f"index.html not found at {index}")
+        return result
+
+    size = index.stat().st_size
+    if size > MAX_FILE_BYTES:
+        result.warnings.append(
+            f"index.html is {size / 1024 / 1024:.1f} MB (> {MAX_FILE_BYTES // 1024 // 1024} MB) — "
+            f"likely too many inlined images."
+        )
+
+    text = index.read_text(encoding="utf-8", errors="replace")
+    parser = _DeckParser()
+    try:
+        parser.feed(text)
+        parser.close()
+    except Exception as exc:  # html.parser raises HTMLParseError only on strict mode
+        result.errors.append(f"index.html failed to parse: {exc}")
+        return result
+
+    n = len(parser.slide_types)
+    if n < MIN_SLIDES_HARD:
+        result.errors.append(
+            f"deck has {n} slides; need at least {MIN_SLIDES_HARD} "
+            f'<section class="slide" data-type="..."> blocks.'
+        )
+
+    type_set = set(parser.slide_types)
+    if "cover" not in type_set:
+        result.errors.append('missing required slide: data-type="cover".')
+    if "closing" not in type_set:
+        result.errors.append('missing required slide: data-type="closing".')
+
+    illegal = type_set - ALLOWED_DATA_TYPES - {""}
+    if illegal:
+        result.errors.append(
+            f"unknown data-type value(s): {sorted(illegal)!r}. "
+            f"Allowed: {sorted(ALLOWED_DATA_TYPES)!r}."
+        )
+    blank = sum(1 for t in parser.slide_types if t == "")
+    if blank:
+        result.errors.append(f"{blank} <section class='slide'> block(s) missing data-type attribute.")
+
+    if parser.external_links:
+        result.errors.append(
+            "deck is not self-contained: external references found: "
+            + ", ".join(parser.external_links[:3])
+            + (f", … (+{len(parser.external_links) - 3} more)" if len(parser.external_links) > 3 else "")
+        )
+
+    # Warnings — non-blocking.
+    if n and (n < MIN_SLIDES_SOFT or n > MAX_SLIDES_SOFT):
+        result.warnings.append(
+            f"slide count {n} outside recommended range [{MIN_SLIDES_SOFT}, {MAX_SLIDES_SOFT}]."
+        )
+    distinct = len(type_set - {""})
+    if distinct < MIN_DISTINCT_TYPES:
+        result.warnings.append(
+            f"only {distinct} distinct data-type(s) used; recommend ≥ {MIN_DISTINCT_TYPES} for visual variety."
+        )
+    # Run-length: warn on any run >= MAX_CONSECUTIVE_SAME_TYPE + 1.
+    run = 1
+    for prev, cur in zip(parser.slide_types, parser.slide_types[1:]):
+        run = run + 1 if cur == prev and cur != "" else 1
+        if run > MAX_CONSECUTIVE_SAME_TYPE:
+            result.warnings.append(
+                f"{run} consecutive slides with data-type={cur!r}; break up runs of "
+                f"3+ same type to avoid visual monotony."
+            )
+            break  # one warning is enough; agent will read it and revise
+
+    return result
diff --git a/tests/test_deck_validator.py b/tests/test_deck_validator.py
new file mode 100644
index 00000000..1932d875
--- /dev/null
+++ b/tests/test_deck_validator.py
@@ -0,0 +1,164 @@
+"""Tests for the deck validator. No LLM; pure structural checks."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from openkb.deck.validator import (
+    ALLOWED_DATA_TYPES,
+    ValidationResult,
+    validate_deck,
+)
+
+
+# A minimal well-formed deck: 8 slides covering all required invariants.
+GOOD_DECK = """<!doctype html>
+<html><head><meta charset="utf-8"><style>.slide{aspect-ratio:16/9}</style></head>
+<body>
+  <section class="slide" data-type="cover"><h1>Title</h1></section>
+  <section class="slide" data-type="thesis"><h2>Claim A</h2><p>explanation</p></section>
+  <section class="slide" data-type="quote"><blockquote>"…"</blockquote></section>
+  <section class="slide" data-type="data"><div>8.2x</div></section>
+  <section class="slide" data-type="thesis"><h2>Claim B</h2><p>explanation</p></section>
+  <section class="slide" data-type="compare"><div>L</div><div>R</div></section>
+  <section class="slide" data-type="chapter"><div>03</div></section>
+  <section class="slide" data-type="closing"><h1>Thanks</h1></section>
+</body></html>"""
+
+
+def _write(tmp_path: Path, html: str) -> Path:
+    deck_dir = tmp_path / "deck"
+    deck_dir.mkdir()
+    (deck_dir / "index.html").write_text(html, encoding="utf-8")
+    return deck_dir
+
+
+def test_good_deck_passes(tmp_path: Path):
+    result = validate_deck(_write(tmp_path, GOOD_DECK))
+    assert isinstance(result, ValidationResult)
+    assert result.errors == []
+    # 8 slides is on the inside of [8,15] so no slide-count warning
+    assert not any("slide count" in w.lower() for w in result.warnings)
+
+
+def test_allowed_data_types_constant():
+    # Lock the public contract; prompt + validator must stay in sync.
+    assert ALLOWED_DATA_TYPES == frozenset(
+        {"cover", "chapter", "thesis", "quote", "compare", "data", "closing"}
+    )
+
+
+def test_missing_file(tmp_path: Path):
+    deck_dir = tmp_path / "deck"
+    deck_dir.mkdir()
+    result = validate_deck(deck_dir)
+    assert any("not found" in e for e in result.errors)
+
+
+def test_too_few_slides(tmp_path: Path):
+    html = (
+        "<html><body>"
+        + "".join(f'<section class="slide" data-type="thesis"><h2>{i}</h2></section>' for i in range(4))
+        + "</body></html>"
+    )
+    result = validate_deck(_write(tmp_path, html))
+    assert any("at least 5" in e for e in result.errors)
+
+
+def test_missing_cover(tmp_path: Path):
+    html = GOOD_DECK.replace('data-type="cover"', 'data-type="thesis"')
+    result = validate_deck(_write(tmp_path, html))
+    assert any('"cover"' in e for e in result.errors)
+
+
+def test_missing_closing(tmp_path: Path):
+    html = GOOD_DECK.replace('data-type="closing"', 'data-type="thesis"')
+    result = validate_deck(_write(tmp_path, html))
+    assert any('"closing"' in e for e in result.errors)
+
+
+def test_unknown_data_type(tmp_path: Path):
+    html = GOOD_DECK.replace('data-type="quote"', 'data-type="hero-banner"')
+    result = validate_deck(_write(tmp_path, html))
+    assert any("hero-banner" in e for e in result.errors)
+
+
+def test_missing_data_type_attr(tmp_path: Path):
+    html = GOOD_DECK.replace('data-type="quote"', '')
+    result = validate_deck(_write(tmp_path, html))
+    assert any("missing data-type" in e for e in result.errors)
+
+
+def test_external_link_blocks(tmp_path: Path):
+    html = GOOD_DECK.replace(
+        "</head>",
+        '<link rel="stylesheet" href="https://cdn.example/x.css"></head>',
+    )
+    result = validate_deck(_write(tmp_path, html))
+    assert any("not self-contained" in e for e in result.errors)
+
+
+def test_external_script_blocks(tmp_path: Path):
+    html = GOOD_DECK.replace(
+        "</head>",
+        '<script src="https://cdn.example/x.js"></script></head>',
+    )
+    result = validate_deck(_write(tmp_path, html))
+    assert any("not self-contained" in e for e in result.errors)
+
+
+def test_few_slides_warning(tmp_path: Path):
+    # 6 slides — passes hard floor (5), but warns (< 8).
+    html = (
+        "<html><body>"
+        '<section class="slide" data-type="cover"></section>'
+        '<section class="slide" data-type="thesis"></section>'
+        '<section class="slide" data-type="data"></section>'
+        '<section class="slide" data-type="thesis"></section>'
+        '<section class="slide" data-type="compare"></section>'
+        '<section class="slide" data-type="closing"></section>'
+        "</body></html>"
+    )
+    result = validate_deck(_write(tmp_path, html))
+    assert result.errors == []
+    assert any("slide count 6" in w for w in result.warnings)
+
+
+def test_run_of_3_same_type_warning(tmp_path: Path):
+    html = (
+        "<html><body>"
+        '<section class="slide" data-type="cover"></section>'
+        '<section class="slide" data-type="thesis"></section>'
+        '<section class="slide" data-type="thesis"></section>'
+        '<section class="slide" data-type="thesis"></section>'
+        '<section class="slide" data-type="data"></section>'
+        '<section class="slide" data-type="compare"></section>'
+        '<section class="slide" data-type="quote"></section>'
+        '<section class="slide" data-type="closing"></section>'
+        "</body></html>"
+    )
+    result = validate_deck(_write(tmp_path, html))
+    assert result.errors == []
+    assert any("consecutive" in w for w in result.warnings)
+
+
+def test_low_distinct_types_warning(tmp_path: Path):
+    # 8 slides but only 3 distinct types (cover, thesis, closing).
+    html = (
+        "<html><body>"
+        '<section class="slide" data-type="cover"></section>'
+        + '<section class="slide" data-type="thesis"></section>' * 6
+        + '<section class="slide" data-type="closing"></section>'
+        "</body></html>"
+    )
+    result = validate_deck(_write(tmp_path, html))
+    # Errors fine; this run-length and distinct-count will both warn.
+    assert any("distinct data-type" in w for w in result.warnings)
+
+
+def test_oversize_file_warning(tmp_path: Path, monkeypatch):
+    # Inject a fake stat() so we don't actually allocate 2MB.
+    import openkb.deck.validator as v
+
+    monkeypatch.setattr(v, "MAX_FILE_BYTES", 100)  # threshold 100 bytes for the test
+    result = validate_deck(_write(tmp_path, GOOD_DECK))
+    assert any("MB" in w for w in result.warnings)

From 128706c23956c48e04f7da31cfc9e3c798dd7b02 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 22:26:33 +0800
Subject: [PATCH 04/25] fix(deck): flag external <img>, suppress distinct-type
 warning on empty deck

---
 openkb/deck/validator.py     |  6 +++++-
 tests/test_deck_validator.py | 17 +++++++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/openkb/deck/validator.py b/openkb/deck/validator.py
index aea8b555..6293d42d 100644
--- a/openkb/deck/validator.py
+++ b/openkb/deck/validator.py
@@ -59,6 +59,10 @@ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None
             src = (a.get("src") or "").strip()
             if src.startswith(("http://", "https://", "//")):
                 self.external_links.append(f"<script src={src!r}>")
+        elif tag == "img":
+            src = (a.get("src") or "").strip()
+            if src.startswith(("http://", "https://", "//")):
+                self.external_links.append(f"<img src={src!r}>")
 
 
 def validate_deck(deck_dir: Path) -> ValidationResult:
@@ -127,7 +131,7 @@ def validate_deck(deck_dir: Path) -> ValidationResult:
             f"slide count {n} outside recommended range [{MIN_SLIDES_SOFT}, {MAX_SLIDES_SOFT}]."
         )
     distinct = len(type_set - {""})
-    if distinct < MIN_DISTINCT_TYPES:
+    if n and distinct < MIN_DISTINCT_TYPES:
         result.warnings.append(
             f"only {distinct} distinct data-type(s) used; recommend ≥ {MIN_DISTINCT_TYPES} for visual variety."
         )
diff --git a/tests/test_deck_validator.py b/tests/test_deck_validator.py
index 1932d875..67a90fba 100644
--- a/tests/test_deck_validator.py
+++ b/tests/test_deck_validator.py
@@ -106,6 +106,15 @@ def test_external_script_blocks(tmp_path: Path):
     assert any("not self-contained" in e for e in result.errors)
 
 
+def test_external_img_blocks(tmp_path: Path):
+    html = GOOD_DECK.replace(
+        '<section class="slide" data-type="quote"><blockquote>"…"</blockquote></section>',
+        '<section class="slide" data-type="quote"><img src="https://example.com/x.png"></section>',
+    )
+    result = validate_deck(_write(tmp_path, html))
+    assert any("not self-contained" in e for e in result.errors)
+
+
 def test_few_slides_warning(tmp_path: Path):
     # 6 slides — passes hard floor (5), but warns (< 8).
     html = (
@@ -155,6 +164,14 @@ def test_low_distinct_types_warning(tmp_path: Path):
     assert any("distinct data-type" in w for w in result.warnings)
 
 
+def test_no_slides_no_distinct_warning(tmp_path: Path):
+    # A deck with zero slides already produces hard errors; the distinct-type
+    # warning ("only 0 distinct…") is noise on an empty deck and is suppressed.
+    html = "<html><body></body></html>"
+    result = validate_deck(_write(tmp_path, html))
+    assert not any("distinct data-type" in w for w in result.warnings)
+
+
 def test_oversize_file_warning(tmp_path: Path, monkeypatch):
     # Inject a fake stat() so we don't actually allocate 2MB.
     import openkb.deck.validator as v

From 1c15254063158b88e9d44af5ef66a2dfedcd0b57 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 22:30:54 +0800
Subject: [PATCH 05/25] feat(deck): deck_create system prompt with Editorial
 Monocle tokens

---
 openkb/prompts/deck_create.md | 209 ++++++++++++++++++++++++++++++++++
 tests/test_deck_prompt.py     |  32 ++++++
 2 files changed, 241 insertions(+)
 create mode 100644 openkb/prompts/deck_create.md
 create mode 100644 tests/test_deck_prompt.py

diff --git a/openkb/prompts/deck_create.md b/openkb/prompts/deck_create.md
new file mode 100644
index 00000000..d9d169b6
--- /dev/null
+++ b/openkb/prompts/deck_create.md
@@ -0,0 +1,209 @@
+<!-- openkb/prompts/deck_create.md -->
+You are the OpenKB deck-create agent. Your job: read the knowledge base
+wiki at `<kb>/wiki/` and produce a polished, single-file HTML slide deck
+at `<kb>/output/decks/{deck_name}/index.html`.
+
+You are not writing a research report or a Wikipedia article. **You are
+designing a presentation.** Each slide carries one idea. Visual structure
+carries the narrative. The deliverable is meant to be opened in a
+browser, full-screened with `F`, and shown to other humans — or shared
+via a single `.html` file in Slack.
+
+## User intent
+
+The user requested this deck with the following description. Treat it as
+authoritative; every slide must serve this intent.
+
+> {intent}
+
+## Wiki schema reference
+
+The wiki you can read from is structured as follows.
+
+{wiki_schema}
+
+## Your tools
+
+* `list_wiki_dir(directory)` — list `.md` files in a wiki subdirectory.
+* `read_wiki_file(path)` — read a markdown file under `<kb>/wiki/`.
+* `get_page_content(doc_name, pages)` — fetch source pages of a
+  PageIndex (long) document at page-range granularity. Use tight ranges,
+  never the whole document.
+* `get_image(image_path)` — view a figure or diagram from the wiki when
+  you need to see it to decide whether and how to include it.
+* `query_wiki(question)` — semantic search; narrow follow-ups only.
+  This is a nested LLM call (slow, expensive); prefer direct reads.
+* `write_deck_file(path, content)` — write under
+  `<kb>/output/decks/{deck_name}/`. Relative paths only.
+* `done(summary)` — signal completion. Call exactly once when finished.
+
+## Required output
+
+Exactly one file: `index.html` at the deck root.
+
+It must be **self-contained**: no external `<link rel="stylesheet">`,
+no external `<script src="…">`, no remote `<img>`. All CSS goes in a
+single inline `<style>` in `<head>`. Helper JS for keyboard nav goes in
+a single inline `<script>` at end of `<body>`.
+
+The body is a sequence of `<section class="slide" data-type="...">`
+blocks. Each `data-type` must be one of the 7 values listed in §
+"Slide grammar" below. The deck supports keyboard navigation: ← / →
+move between slides, `F` toggles fullscreen, `P` triggers print
+(browser's Print → Save as PDF is the user's PDF export).
+
+## Design system: Editorial Monocle
+
+You will compose every slide from this fixed design system. Do not
+improvise nearby colors, do not introduce gradients, do not bring in
+emojis. This is the **only** non-monochrome palette in the entire deck.
+
+### Color palette
+
+Use these exact values. Define them as CSS custom properties on `:root`
+and reference them throughout.
+
+```css
+:root {{
+  --bg:        #f3eee1;  /* oklch(94% 0.03 80)  — warm cream paper */
+  --ink:       #1a1612;  /* oklch(15% 0.01 50)  — warm near-black */
+  --muted:     #7a6e55;  /* oklch(55% 0.04 75)  — labels / metadata */
+  --rule:      #d4cfc0;  /* oklch(82% 0.02 75)  — thin separator */
+  --accent:    #a4341c;  /* oklch(45% 0.16 30)  — brick red, the ONLY non-monochrome */
+  --highlight: #fff3a8;  /* oklch(95% 0.10 95)  — marker highlighter ONLY */
+}}
+```
+
+### Type system
+
+```css
+font-family-serif:  "Charter", "Iowan Old Style", "Times New Roman", Georgia, serif;
+font-family-sans:   "Inter", -apple-system, "Helvetica Neue", sans-serif;  /* labels only */
+```
+
+Type scale (size / line-height / letter-spacing):
+
+* `--type-display`: 56px / 1.05 / -1px      — cover/chapter big titles
+* `--type-title`:   38px / 1.10 / -0.5px    — normal slide titles
+* `--type-body`:    18px / 1.55 / 0         — body copy
+* `--type-quote`:   28px / 1.30 / -0.3px    italic — pull quotes
+* `--type-label`:   10px / 1.0 / 2.5px      uppercase — top/bottom label tracks
+
+Serif for everything except labels. Labels use sans, uppercase,
+`--muted` color, and the 2.5px letter-spacing track.
+
+### Frame (every slide)
+
+* 16:9 aspect ratio: `aspect-ratio: 16/9; width: 100vw; max-width: 1280px;`
+* Per-slide padding: 64px top/bottom, 80px left/right.
+* **4px brick-red bar on the right edge of every slide.** This is the
+  deck's visual signature; do not omit it.
+* Top label row (10px sans, `--muted`, uppercase, tracking):
+  left = chapter id (e.g. "CHAPTER 03"), right = source mark
+  (e.g. "VASWANI ET AL · 2017").
+* Bottom folio row (8px sans, very `--muted`): left = `N / Total`,
+  right = source short label.
+
+## Slide grammar
+
+Every slide must declare `data-type` from this exact whitelist. The
+seven values are the only ones allowed — the validator will reject the
+deck if it sees anything else.
+
+| `data-type` | Use | Visual signature |
+|---|---|---|
+| `cover`   | First slide: tag + huge title + 1-line subtitle | Display type, **left-aligned, never centered** |
+| `chapter` | Section divider: oversize number + chapter name | Number 120px brick-red, name 38px serif |
+| `thesis`  | A single claim + a short explanation | Title fills ~60% height, explanation small bottom |
+| `quote`   | Italic pull-quote + attribution | Centered, serif italic 28px, generous whitespace |
+| `compare` | Two-column comparison: header + 3-5 lines each side | 1px brick-red vertical rule between columns |
+| `data`    | One number + label + one-line interpretation | Number 120-160px brick-red, micro-copy 12px |
+| `closing` | Mirrors `cover`; thanks / next steps | Same scale as cover but content closes the arc |
+
+Skeleton templates (extend with content; do not deviate from the
+structural shape):
+
+```html
+<section class="slide" data-type="cover">
+  <div class="label-top"><span>OPENKB</span><span>{{date}}</span></div>
+  <div class="cover-body">
+    <div class="eyebrow">— {{short eyebrow}}</div>
+    <h1 class="display">{{title}}</h1>
+    <p class="subtitle">{{1-line subtitle, max 22 words}}</p>
+  </div>
+  <div class="folio"><span>01 / N</span><span>{{source mark}}</span></div>
+</section>
+
+<section class="slide" data-type="thesis">
+  <div class="label-top"><span>{{chapter id}}</span><span>{{source mark}}</span></div>
+  <div class="thesis-body">
+    <h2 class="title">{{the claim, max 14 words}}</h2>
+    <p class="body">{{2-3 sentence explanation, max 60 words}}</p>
+  </div>
+  <div class="folio"><span>{{n}} / N</span><span>{{source short}}</span></div>
+</section>
+
+<!-- repeat shape for chapter / quote / compare / data / closing -->
+```
+
+## Working method
+
+1. **Survey first.** `list_wiki_dir("concepts")`, `list_wiki_dir("summaries")`,
+   read `wiki/index.md`. Form a mental map of what the KB actually contains
+   before you decide what the deck argues.
+2. **Choose a narrative arc.** Before writing any HTML, write a one-line
+   thesis the deck argues, then a 7-12 step arc (problem → tension →
+   resolution, or whatever shape the intent calls for). Write this arc
+   into the deck only as section titles — *not* as on-slide text.
+3. **Read the relevant content.** For each concept the arc touches, read
+   the concept page (`read_wiki_file("concepts/...")`). For each
+   document a concept cites, read at least one targeted slice of the
+   source (use `get_page_content` with tight ranges for PageIndex docs,
+   `read_wiki_file` on the `full_text` path for short docs).
+4. **Outline the slides.** Map each step in the arc to one or more
+   slides with concrete `data-type` assignments. Aim for 8-15 slides
+   total. **Vary `data-type`** — at least 4 distinct types, no run of
+   3+ consecutive same type.
+5. **Write `index.html`.** One `write_deck_file("index.html", ...)`
+   call with the complete file. Inline all CSS, inline the keyboard nav
+   JS, inline any images as base64 (cap at ~3 images total).
+6. **Revise.** Re-read what you wrote against the failure modes in §
+   "Failure modes" below. Touch at least one slide on this pass.
+7. **Self-check** the 5 invariants in § "Self-check" below. Fix anything
+   that fails.
+8. Call `done(summary)` with a one-paragraph summary of the arc you
+   chose and the slide-type distribution.
+
+## Failure modes (negative checklist)
+
+These patterns are AI slop. If you see one in your draft, fix it.
+
+1. **Bullet dump** — any slide with more than 5 bullet points. Pick the
+   3 strongest, or restructure into a `compare` or `data` slide.
+2. **Wall of text** — slide body longer than ~80 words. Cut, or split.
+3. **Visual monotony** — three or more consecutive slides with the same
+   `data-type`. Insert a `quote`, `data`, or `chapter` to break rhythm.
+4. **Centered everything** — only `quote` and `closing` are centered.
+   All other slide types are **left-aligned**.
+5. **AI slop palette** — any color outside the 6-value palette above:
+   no blue/purple gradients, no emoji, no rainbow accents.
+6. **Generic titles** — "Introduction" / "Background" / "Conclusion" as
+   a slide title is a failure. Title must carry specific content
+   ("Attention replaces recurrence" beats "Background").
+
+## Self-check (before `done`)
+
+Walk through these five questions. The deck is not done until each
+answer is yes:
+
+1. Does `index.html` exist and contain no external `<link>` or
+   `<script src=>`?
+2. Is there at least one `data-type="cover"` and one `data-type="closing"`?
+3. Is the total slide count between 8 and 15?
+4. Are at least 4 distinct `data-type` values used?
+5. Is there no run of 3+ consecutive slides with the same `data-type`?
+
+If any answer is no, revise the deck and re-run this self-check before
+calling `done`.
+
+Begin.
diff --git a/tests/test_deck_prompt.py b/tests/test_deck_prompt.py
new file mode 100644
index 00000000..298b36aa
--- /dev/null
+++ b/tests/test_deck_prompt.py
@@ -0,0 +1,32 @@
+"""Sanity tests for the deck_create prompt. Verifies file is loadable and
+contains the structural anchors the validator and creator depend on."""
+from __future__ import annotations
+
+from openkb.prompts import load_prompt
+
+
+def test_prompt_loads():
+    text = load_prompt("deck_create")
+    assert isinstance(text, str) and len(text) > 1000
+
+
+def test_prompt_has_placeholders():
+    text = load_prompt("deck_create")
+    assert "{intent}" in text
+    assert "{wiki_schema}" in text
+    assert "{deck_name}" in text
+
+
+def test_prompt_lists_all_allowed_data_types():
+    text = load_prompt("deck_create")
+    for t in ("cover", "chapter", "thesis", "quote", "compare", "data", "closing"):
+        assert t in text, f"slide grammar must mention data-type={t}"
+
+
+def test_prompt_lists_editorial_monocle_tokens():
+    text = load_prompt("deck_create")
+    # palette values must appear so the agent can copy them verbatim
+    for hex_value in ("#f3eee1", "#1a1612", "#a4341c", "#fff3a8"):
+        assert hex_value in text, f"palette token {hex_value} missing"
+    assert "Charter" in text  # serif stack
+    assert "16:9" in text or "aspect-ratio" in text

From 145778ad851b758b89d657246bf5245039ebdfa3 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 22:39:08 +0800
Subject: [PATCH 06/25] =?UTF-8?q?fix(deck):=20prompt=20fixes=20=E2=80=94?=
 =?UTF-8?q?=20folio=20size,=20no=20bitmap=20images,=20cover=20label=20exce?=
 =?UTF-8?q?ption,=20arc-count=20alignment?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 openkb/prompts/deck_create.md | 30 ++++++++++++++++++++++--------
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/openkb/prompts/deck_create.md b/openkb/prompts/deck_create.md
index d9d169b6..877229ac 100644
--- a/openkb/prompts/deck_create.md
+++ b/openkb/prompts/deck_create.md
@@ -29,8 +29,10 @@ The wiki you can read from is structured as follows.
 * `get_page_content(doc_name, pages)` — fetch source pages of a
   PageIndex (long) document at page-range granularity. Use tight ranges,
   never the whole document.
-* `get_image(image_path)` — view a figure or diagram from the wiki when
-  you need to see it to decide whether and how to include it.
+* `get_image(image_path)` — view a figure or diagram from the wiki to
+  decide whether to *reference* it in prose. (v1 does not support
+  embedding bitmap images in the deck — use inline `<svg>` if you need
+  graphics.)
 * `query_wiki(question)` — semantic search; narrow follow-ups only.
   This is a nested LLM call (slow, expensive); prefer direct reads.
 * `write_deck_file(path, content)` — write under
@@ -101,7 +103,7 @@ Serif for everything except labels. Labels use sans, uppercase,
 * Top label row (10px sans, `--muted`, uppercase, tracking):
   left = chapter id (e.g. "CHAPTER 03"), right = source mark
   (e.g. "VASWANI ET AL · 2017").
-* Bottom folio row (8px sans, very `--muted`): left = `N / Total`,
+* Bottom folio row (use `--type-label`, slightly more `--muted` than the top row): left = `N / Total`,
   right = source short label.
 
 ## Slide grammar
@@ -133,7 +135,14 @@ structural shape):
   </div>
   <div class="folio"><span>01 / N</span><span>{{source mark}}</span></div>
 </section>
+```
+
+**Cover/closing exception:** the `cover` and `closing` slides have no
+chapter context, so the top-left label is the deck identifier
+("OPENKB") instead of a `CHAPTER NN` id. Every other slide type uses
+the chapter id on the top-left as described in §Frame.
 
+```html
 <section class="slide" data-type="thesis">
   <div class="label-top"><span>{{chapter id}}</span><span>{{source mark}}</span></div>
   <div class="thesis-body">
@@ -152,9 +161,11 @@ structural shape):
    read `wiki/index.md`. Form a mental map of what the KB actually contains
    before you decide what the deck argues.
 2. **Choose a narrative arc.** Before writing any HTML, write a one-line
-   thesis the deck argues, then a 7-12 step arc (problem → tension →
-   resolution, or whatever shape the intent calls for). Write this arc
-   into the deck only as section titles — *not* as on-slide text.
+   thesis the deck argues, then an 8-12 step arc (problem → tension →
+   resolution, or whatever shape the intent calls for). Each step
+   becomes 1-2 slides, which lands the final deck in the 8-15 range
+   required by §Self-check. Write this arc into the deck only as
+   section titles — *not* as on-slide text.
 3. **Read the relevant content.** For each concept the arc touches, read
    the concept page (`read_wiki_file("concepts/...")`). For each
    document a concept cites, read at least one targeted slice of the
@@ -165,8 +176,11 @@ structural shape):
    total. **Vary `data-type`** — at least 4 distinct types, no run of
    3+ consecutive same type.
 5. **Write `index.html`.** One `write_deck_file("index.html", ...)`
-   call with the complete file. Inline all CSS, inline the keyboard nav
-   JS, inline any images as base64 (cap at ~3 images total).
+   call with the complete file. Inline all CSS and the keyboard nav JS.
+   For any inline graphics use `<svg>` written directly into the HTML —
+   v1 does not embed bitmap images. The `get_image` tool exists for
+   *previewing* wiki figures so you can decide whether to reference
+   them in prose, not for embedding them.
 6. **Revise.** Re-read what you wrote against the failure modes in §
    "Failure modes" below. Touch at least one slide on this pass.
 7. **Self-check** the 5 invariants in § "Self-check" below. Fix anything

From 4d2f8c32c3b705aa96b8263ed001abed92f39c18 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 22:43:24 +0800
Subject: [PATCH 07/25] feat(deck): deck-create agent (critique=False path)

---
 openkb/deck/creator.py     | 203 +++++++++++++++++++++++++++++++++++++
 tests/test_deck_creator.py |  99 ++++++++++++++++++
 2 files changed, 302 insertions(+)
 create mode 100644 openkb/deck/creator.py
 create mode 100644 tests/test_deck_creator.py

diff --git a/openkb/deck/creator.py b/openkb/deck/creator.py
new file mode 100644
index 00000000..1b3786df
--- /dev/null
+++ b/openkb/deck/creator.py
@@ -0,0 +1,203 @@
+"""The deck-create agent.
+
+Builds on the same openai-agents SDK + LiteLLM stack as the skill-create
+agent in ``openkb.skill.creator``. Differences:
+
+* System prompt comes from ``openkb/prompts/deck_create.md`` and is
+  interpolated with intent, deck_name, and wiki schema.
+* Output is one self-contained ``index.html`` (not a SKILL.md + refs/).
+* Optional ``critique=True`` mode adds a critic agent via SDK handoff
+  (see Task 7 — until then, only ``critique=False`` is wired).
+* The runner verifies that ``index.html`` was written before declaring
+  success.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from agents import Agent, Runner, ToolOutputImage, ToolOutputText, function_tool
+from agents.model_settings import ModelSettings
+
+from openkb.deck import deck_dir
+from openkb.deck.tools import write_deck_file as _write_deck_file_impl
+from openkb.prompts import load_prompt
+from openkb.schema import get_agents_md
+from openkb.skill.tools import (
+    get_skill_page_content as _get_page_content_impl,
+    list_wiki_dir as _list_wiki_dir_impl,
+    read_skill_image as _read_image_impl,
+    read_wiki_file_for_skill as _read_wiki_file_impl,
+)
+
+MAX_TURNS = 80
+MAX_TURNS_WITH_CRITIQUE = 120
+
+
+def build_deck_create_agent(
+    *,
+    wiki_root: str,
+    deck_root: str,
+    deck_name: str,
+    intent: str,
+    model: str,
+    critique: bool,
+) -> Agent:
+    """Build the openai-agents Agent for generating one deck.
+
+    Args:
+        wiki_root: ``<kb>/wiki`` absolute path.
+        deck_root: ``<kb>/output/decks/<name>`` absolute path. Created
+            if it does not exist.
+        deck_name: kebab-case slug.
+        intent: the user's natural-language brief.
+        model: LiteLLM-formatted model name from KB config.
+        critique: when True, wire the critic agent as a handoff target
+            (see Task 7).
+    """
+    Path(deck_root).mkdir(parents=True, exist_ok=True)
+
+    wiki_schema = get_agents_md(Path(wiki_root))
+    instructions = load_prompt("deck_create").format(
+        intent=intent,
+        deck_name=deck_name,
+        wiki_schema=wiki_schema,
+    )
+
+    @function_tool
+    def list_wiki_dir(directory: str) -> str:
+        """List .md files in a wiki subdirectory (e.g. 'concepts')."""
+        return _list_wiki_dir_impl(directory, wiki_root)
+
+    @function_tool
+    def read_wiki_file(path: str) -> str:
+        """Read a wiki markdown file by path relative to wiki/ (e.g. 'concepts/attention.md')."""
+        return _read_wiki_file_impl(path, wiki_root)
+
+    @function_tool
+    def get_page_content(doc_name: str, pages: str) -> str:
+        """Get text content of specific pages from a PageIndex (long) document.
+
+        Args:
+            doc_name: Document name without extension.
+            pages: Page spec such as ``"3-5,7,10-12"``.
+        """
+        return _get_page_content_impl(doc_name, pages, wiki_root)
+
+    @function_tool
+    def get_image(image_path: str) -> ToolOutputImage | ToolOutputText:
+        """View an image referenced in the wiki.
+
+        Args:
+            image_path: Path relative to wiki/.
+        """
+        result = _read_image_impl(image_path, wiki_root)
+        if result["type"] == "image":
+            return ToolOutputImage(image_url=result["image_url"])
+        return ToolOutputText(text=result["text"])
+
+    @function_tool
+    async def query_wiki(question: str) -> str:
+        """Semantic search over the wiki — narrow follow-ups only.
+
+        Nested LLM call. Use only when direct file reads can't easily
+        answer a specific sub-question.
+        """
+        # Lazy import to avoid a circular dependency at module load time.
+        from openkb.agent.query import run_query
+        kb_dir = Path(wiki_root).parent
+        return await run_query(question, kb_dir, model, stream=False)
+
+    @function_tool
+    def write_deck_file(path: str, content: str) -> str:
+        """Write a file under the deck directory."""
+        return _write_deck_file_impl(path, content, deck_root)
+
+    @function_tool
+    def done(summary: str) -> str:
+        """Signal the deck is complete. Call exactly once when finished."""
+        return f"Deck marked done: {summary}"
+
+    # critique=True wiring is added in Task 7. For now, no handoffs.
+    if critique:
+        raise NotImplementedError(
+            "--critique wiring lands in Task 7. Until then, build_deck_create_agent "
+            "only supports critique=False."
+        )
+
+    return Agent(
+        name="deck-creator",
+        instructions=instructions,
+        tools=[
+            list_wiki_dir,
+            read_wiki_file,
+            get_page_content,
+            get_image,
+            query_wiki,
+            write_deck_file,
+            done,
+        ],
+        model=f"litellm/{model}",
+        # Parallel reads (early fan-out: list dir → read N summaries → read N
+        # source page-ranges) saves 5-10 round-trips per compile. Writes
+        # naturally serialise since each write_deck_file depends on prior
+        # reads; model has no reason to write the same path twice in
+        # parallel.
+        model_settings=ModelSettings(parallel_tool_calls=True),
+    )
+
+
+async def run_deck_create(
+    *,
+    kb_dir: Path,
+    deck_name: str,
+    intent: str,
+    model: str,
+    critique: bool,
+) -> Path:
+    """Compile a single deck from the KB's wiki.
+
+    Returns the deck directory. Raises ``RuntimeError`` if the agent
+    finishes without writing ``index.html``, or if the SDK hits its
+    turn cap.
+    """
+    wiki_root = str(kb_dir / "wiki")
+    deck_root = deck_dir(kb_dir, deck_name)
+
+    agent = build_deck_create_agent(
+        wiki_root=wiki_root,
+        deck_root=str(deck_root),
+        deck_name=deck_name,
+        intent=intent,
+        model=model,
+        critique=critique,
+    )
+
+    seed = (
+        f"Generate the deck '{deck_name}'. Follow the system prompt's "
+        f"working method. Read the wiki, then write index.html."
+    )
+
+    # Lazy import — same reason as skill creator: keep top of module
+    # independent of agents SDK's exception layout.
+    from agents.exceptions import MaxTurnsExceeded
+
+    turn_cap = MAX_TURNS_WITH_CRITIQUE if critique else MAX_TURNS
+
+    try:
+        await Runner.run(agent, seed, max_turns=turn_cap)
+    except MaxTurnsExceeded as exc:
+        raise RuntimeError(
+            f"Deck generation hit the {turn_cap}-step cap before finishing. "
+            f"The wiki may be too large for a single deck, or the intent may "
+            f"be too broad. Try splitting into multiple decks with narrower "
+            f"intents, or pass a smaller wiki subset."
+        ) from exc
+
+    if not (deck_root / "index.html").exists():
+        raise RuntimeError(
+            f"Deck generation finished but agent did not write index.html "
+            f"at {deck_root}. The deck is incomplete; check the wiki has "
+            f"content related to your intent."
+        )
+
+    return deck_root
diff --git a/tests/test_deck_creator.py b/tests/test_deck_creator.py
new file mode 100644
index 00000000..8118fde8
--- /dev/null
+++ b/tests/test_deck_creator.py
@@ -0,0 +1,99 @@
+"""Tests for the deck-create agent builder + runner.
+
+No real LLM calls — Runner.run is patched. We verify:
+  * the Agent is built with the right name, prompt, tool count
+  * critique=False produces an agent with no handoffs
+  * run_deck_create raises if index.html is not written
+  * run_deck_create raises with a helpful message on MaxTurnsExceeded
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from openkb.deck.creator import build_deck_create_agent, run_deck_create
+
+
+def _build(tmp_path: Path):
+    wiki_root = tmp_path / "wiki"
+    wiki_root.mkdir()
+    # AGENTS.md is consulted by get_agents_md; an empty file is fine.
+    (wiki_root / "AGENTS.md").write_text("# wiki schema placeholder", encoding="utf-8")
+    deck_root = tmp_path / "output" / "decks" / "test-deck"
+    return wiki_root, deck_root
+
+
+def test_build_agent_shape(tmp_path: Path):
+    wiki_root, deck_root = _build(tmp_path)
+    agent = build_deck_create_agent(
+        wiki_root=str(wiki_root),
+        deck_root=str(deck_root),
+        deck_name="test-deck",
+        intent="A test deck about transformers.",
+        model="openai/gpt-4o",
+        critique=False,
+    )
+    assert agent.name == "deck-creator"
+    # 7 tools: list_wiki_dir, read_wiki_file, get_page_content,
+    # get_image, query_wiki, write_deck_file, done
+    assert len(agent.tools) == 7
+    tool_names = {getattr(t, "name", "?") for t in agent.tools}
+    assert "write_deck_file" in tool_names
+    assert "done" in tool_names
+    # No handoffs when critique=False
+    assert getattr(agent, "handoffs", []) in ([], None)
+
+
+def test_build_agent_creates_output_dir(tmp_path: Path):
+    wiki_root, deck_root = _build(tmp_path)
+    assert not deck_root.exists()
+    build_deck_create_agent(
+        wiki_root=str(wiki_root),
+        deck_root=str(deck_root),
+        deck_name="test-deck",
+        intent="A test deck.",
+        model="openai/gpt-4o",
+        critique=False,
+    )
+    assert deck_root.is_dir()
+
+
+def test_run_raises_when_html_missing(tmp_path: Path):
+    wiki_root, _ = _build(tmp_path)
+    kb_dir = tmp_path
+
+    with patch("openkb.deck.creator.Runner") as runner:
+        runner.run = AsyncMock(return_value=MagicMock())
+        import asyncio
+        with pytest.raises(RuntimeError, match="did not write index.html"):
+            asyncio.run(
+                run_deck_create(
+                    kb_dir=kb_dir,
+                    deck_name="test-deck",
+                    intent="A test deck.",
+                    model="openai/gpt-4o",
+                    critique=False,
+                )
+            )
+
+
+def test_run_translates_maxturns(tmp_path: Path):
+    wiki_root, _ = _build(tmp_path)
+    kb_dir = tmp_path
+    from agents.exceptions import MaxTurnsExceeded
+
+    with patch("openkb.deck.creator.Runner") as runner:
+        runner.run = AsyncMock(side_effect=MaxTurnsExceeded("nope"))
+        import asyncio
+        with pytest.raises(RuntimeError, match="step cap"):
+            asyncio.run(
+                run_deck_create(
+                    kb_dir=kb_dir,
+                    deck_name="test-deck",
+                    intent="A test deck.",
+                    model="openai/gpt-4o",
+                    critique=False,
+                )
+            )

From 7ded561f2cd29438fa8126cc1af78e4b060cb840 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 22:48:56 +0800
Subject: [PATCH 08/25] feat(deck): critic agent with snapshot/restore safety
 hooks

---
 openkb/deck/critic.py           | 148 ++++++++++++++++++++++++++++++++
 openkb/prompts/deck_critique.md |  54 ++++++++++++
 tests/test_deck_critic.py       |  66 ++++++++++++++
 3 files changed, 268 insertions(+)
 create mode 100644 openkb/deck/critic.py
 create mode 100644 openkb/prompts/deck_critique.md
 create mode 100644 tests/test_deck_critic.py

diff --git a/openkb/deck/critic.py b/openkb/deck/critic.py
new file mode 100644
index 00000000..d4095550
--- /dev/null
+++ b/openkb/deck/critic.py
@@ -0,0 +1,148 @@
+"""The deck-critic agent.
+
+Invoked via OpenAI Agents SDK handoff from the deck-creator (see
+``openkb.deck.creator``). Inherits the creator's full conversation
+history — tool calls, wiki reads, reasoning trace, the written HTML —
+which is why critic does not need to re-read the wiki to revise.
+
+Critic-only tools:
+  * read_deck_file — main's write_deck_file result string is "Written:
+    index.html", not the body, so critic needs an explicit re-read.
+
+Safety:
+  * ``snapshot_pre_critique`` copies ``index.html`` →
+    ``index.pre-critique.html`` the instant control transfers to critic
+    (called from the SDK lifecycle hook attached in
+    ``build_deck_create_agent`` Task 7).
+  * ``restore_pre_critique`` puts the snapshot back when critic raises,
+    hits MaxTurnsExceeded, or produces output that fails validation.
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from agents import Agent, ToolOutputImage, ToolOutputText, function_tool
+from agents.model_settings import ModelSettings
+
+from openkb.deck.tools import (
+    read_deck_file as _read_deck_file_impl,
+    write_deck_file as _write_deck_file_impl,
+)
+from openkb.prompts import load_prompt
+from openkb.skill.tools import (
+    get_skill_page_content as _get_page_content_impl,
+    list_wiki_dir as _list_wiki_dir_impl,
+    read_skill_image as _read_image_impl,
+    read_wiki_file_for_skill as _read_wiki_file_impl,
+)
+
+PRE_CRITIQUE_SUFFIX = "pre-critique"  # → "index.pre-critique.html"
+
+
+def snapshot_pre_critique(deck_root: Path) -> Path:
+    """Copy index.html → index.pre-critique.html. Returns the snapshot path.
+
+    Raises FileNotFoundError if index.html is missing — that means the
+    creator never wrote it, and there is nothing for critic to revise.
+    """
+    src = deck_root / "index.html"
+    if not src.is_file():
+        raise FileNotFoundError(
+            f"snapshot_pre_critique: {src} missing — creator did not produce a draft."
+        )
+    dst = deck_root / f"index.{PRE_CRITIQUE_SUFFIX}.html"
+    shutil.copy2(src, dst)
+    return dst
+
+
+def restore_pre_critique(deck_root: Path) -> None:
+    """Restore index.pre-critique.html → index.html. No-op if snapshot absent."""
+    src = deck_root / f"index.{PRE_CRITIQUE_SUFFIX}.html"
+    if not src.is_file():
+        return  # idempotent — nothing to restore
+    dst = deck_root / "index.html"
+    shutil.copy2(src, dst)
+
+
+def build_deck_critic_agent(
+    *,
+    wiki_root: str,
+    deck_root: str,
+    intent: str,
+    model: str,
+) -> Agent:
+    """Build the openai-agents Agent for revising a draft deck.
+
+    Args:
+        wiki_root: ``<kb>/wiki`` absolute path.
+        deck_root: ``<kb>/output/decks/<name>`` absolute path.
+        intent: the original user intent the creator received.
+        model: LiteLLM-formatted model name.
+    """
+    instructions = load_prompt("deck_critique").format(intent=intent)
+
+    @function_tool
+    def list_wiki_dir(directory: str) -> str:
+        """List .md files in a wiki subdirectory."""
+        return _list_wiki_dir_impl(directory, wiki_root)
+
+    @function_tool
+    def read_wiki_file(path: str) -> str:
+        """Read a wiki markdown file by path relative to wiki/."""
+        return _read_wiki_file_impl(path, wiki_root)
+
+    @function_tool
+    def get_page_content(doc_name: str, pages: str) -> str:
+        """Get text content of specific pages from a PageIndex document."""
+        return _get_page_content_impl(doc_name, pages, wiki_root)
+
+    @function_tool
+    def get_image(image_path: str) -> ToolOutputImage | ToolOutputText:
+        """View an image referenced in the wiki."""
+        result = _read_image_impl(image_path, wiki_root)
+        if result["type"] == "image":
+            return ToolOutputImage(image_url=result["image_url"])
+        return ToolOutputText(text=result["text"])
+
+    @function_tool
+    async def query_wiki(question: str) -> str:
+        """Semantic search over the wiki — narrow follow-ups only."""
+        from openkb.agent.query import run_query
+        kb_dir = Path(wiki_root).parent
+        return await run_query(question, kb_dir, model, stream=False)
+
+    @function_tool
+    def read_deck_file(path: str) -> str:
+        """Read a file from the deck directory (e.g. 'index.html')."""
+        return _read_deck_file_impl(path, deck_root)
+
+    @function_tool
+    def write_deck_file(path: str, content: str) -> str:
+        """Write a file under the deck directory."""
+        return _write_deck_file_impl(path, content, deck_root)
+
+    @function_tool
+    def done(summary: str) -> str:
+        """Signal the critique is complete. Call exactly once when finished."""
+        return f"Critique marked done: {summary}"
+
+    return Agent(
+        name="deck-critic",
+        instructions=instructions,
+        tools=[
+            list_wiki_dir,
+            read_wiki_file,
+            get_page_content,
+            get_image,
+            query_wiki,
+            read_deck_file,
+            write_deck_file,
+            done,
+        ],
+        model=f"litellm/{model}",
+        # Critic edits sequentially: read draft → patch. Parallel tool
+        # calls would let it issue overlapping writes to the same file,
+        # which is unsafe.
+        model_settings=ModelSettings(parallel_tool_calls=False),
+    )
diff --git a/openkb/prompts/deck_critique.md b/openkb/prompts/deck_critique.md
new file mode 100644
index 00000000..2ffa4b66
--- /dev/null
+++ b/openkb/prompts/deck_critique.md
@@ -0,0 +1,54 @@
+<!-- openkb/prompts/deck_critique.md -->
+You are the OpenKB deck-critic agent. You have just received a handoff
+from the deck-creator agent. The creator has written a draft deck at
+`<kb>/output/decks/<name>/index.html` for the following intent:
+
+> {intent}
+
+Your job: **revise** that draft into a tighter, more visually disciplined
+deck. You are not re-writing from scratch — you are a senior designer
+reviewing a junior designer's first pass.
+
+## Your tools
+
+Same wiki-read tools the creator had, plus `read_deck_file` so you can
+see the current HTML, plus `write_deck_file` to commit revisions, plus
+`done` to finalise.
+
+Use the wiki tools sparingly — your job is primarily design/layout/voice
+revision, not content rediscovery. Read the wiki only when a specific
+slide is generic and you can fix it by pulling a concrete fact from
+sources you can locate from inherited context.
+
+## Working method
+
+1. **Read the current draft.** `read_deck_file("index.html")` first.
+2. **Score against failure modes.** For each of these, identify each
+   slide that violates and note what to change:
+   - Bullet dump (> 5 bullets)
+   - Wall of text (body > 80 words)
+   - Visual monotony (3+ consecutive same data-type)
+   - Centered everything (only `quote` / `closing` should be centered)
+   - AI slop palette (any color outside the 6-value Editorial Monocle
+     palette: `#f3eee1`, `#1a1612`, `#7a6e55`, `#d4cfc0`, `#a4341c`,
+     `#fff3a8`)
+   - Generic titles ("Introduction", "Background", "Conclusion")
+3. **Score against invariants.** Verify:
+   - ≥ 1 `data-type="cover"` + ≥ 1 `data-type="closing"`
+   - Slide count ∈ [8, 15]
+   - ≥ 4 distinct `data-type` values
+   - No run of 3+ consecutive same `data-type`
+4. **Patch.** Write the revised `index.html` in a single
+   `write_deck_file("index.html", ...)` call. Do not split into
+   multiple writes — one atomic replacement.
+5. **Call `done(summary)`** with a one-paragraph summary of what you
+   changed and why.
+
+## Design system invariants
+
+The Editorial Monocle palette and type system are fixed. Do not
+introduce new colors, new fonts, or new `data-type` values. The seven
+permitted `data-type` values: `cover`, `chapter`, `thesis`, `quote`,
+`compare`, `data`, `closing`. Anything else fails validation.
+
+Begin.
diff --git a/tests/test_deck_critic.py b/tests/test_deck_critic.py
new file mode 100644
index 00000000..4201a383
--- /dev/null
+++ b/tests/test_deck_critic.py
@@ -0,0 +1,66 @@
+"""Tests for the deck critic agent + snapshot/restore safety hooks."""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import pytest
+
+from openkb.deck.critic import (
+    build_deck_critic_agent,
+    restore_pre_critique,
+    snapshot_pre_critique,
+)
+
+
+def test_build_critic_agent_shape(tmp_path: Path):
+    wiki_root = tmp_path / "wiki"
+    wiki_root.mkdir()
+    (wiki_root / "AGENTS.md").write_text("# wiki schema placeholder", encoding="utf-8")
+    deck_root = tmp_path / "deck"
+    deck_root.mkdir()
+    agent = build_deck_critic_agent(
+        wiki_root=str(wiki_root),
+        deck_root=str(deck_root),
+        intent="A deck about transformers.",
+        model="openai/gpt-4o",
+    )
+    assert agent.name == "deck-critic"
+    # 8 tools: 5 wiki-read + write_deck_file + read_deck_file + done
+    assert len(agent.tools) == 8
+    tool_names = {getattr(t, "name", "?") for t in agent.tools}
+    assert "read_deck_file" in tool_names
+    assert "write_deck_file" in tool_names
+
+
+def test_snapshot_creates_pre_critique_copy(tmp_path: Path):
+    deck_root = tmp_path / "deck"
+    deck_root.mkdir()
+    (deck_root / "index.html").write_text("<html>v1</html>", encoding="utf-8")
+    snapshot_pre_critique(deck_root)
+    assert (deck_root / "index.pre-critique.html").read_text() == "<html>v1</html>"
+
+
+def test_snapshot_missing_html_raises(tmp_path: Path):
+    deck_root = tmp_path / "deck"
+    deck_root.mkdir()
+    with pytest.raises(FileNotFoundError):
+        snapshot_pre_critique(deck_root)
+
+
+def test_restore_recovers_index(tmp_path: Path):
+    deck_root = tmp_path / "deck"
+    deck_root.mkdir()
+    (deck_root / "index.pre-critique.html").write_text("<html>v1</html>", encoding="utf-8")
+    (deck_root / "index.html").write_text("<html>broken-by-critic</html>", encoding="utf-8")
+    restore_pre_critique(deck_root)
+    assert (deck_root / "index.html").read_text() == "<html>v1</html>"
+
+
+def test_restore_idempotent_when_no_snapshot(tmp_path: Path):
+    deck_root = tmp_path / "deck"
+    deck_root.mkdir()
+    (deck_root / "index.html").write_text("<html>only-version</html>", encoding="utf-8")
+    # No pre-critique file. Should be a no-op, not an error.
+    restore_pre_critique(deck_root)
+    assert (deck_root / "index.html").read_text() == "<html>only-version</html>"

From 5a1a226d55821d05e1d8040fca04e50eae30cfed Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 22:55:14 +0800
Subject: [PATCH 09/25] fix(deck): add cleanup_pre_critique helper, instruct
 critic to ignore snapshot file

---
 openkb/deck/critic.py           | 16 ++++++++++++++++
 openkb/prompts/deck_critique.md |  3 +++
 tests/test_deck_critic.py       | 21 +++++++++++++++++++++
 3 files changed, 40 insertions(+)

diff --git a/openkb/deck/critic.py b/openkb/deck/critic.py
index d4095550..0ff5f1b2 100644
--- a/openkb/deck/critic.py
+++ b/openkb/deck/critic.py
@@ -16,6 +16,9 @@
     ``build_deck_create_agent`` Task 7).
   * ``restore_pre_critique`` puts the snapshot back when critic raises,
     hits MaxTurnsExceeded, or produces output that fails validation.
+  * ``cleanup_pre_critique`` removes the snapshot once critique has
+    succeeded and validation passes — keeps the deck directory clean
+    across runs.
 """
 from __future__ import annotations
 
@@ -65,6 +68,19 @@ def restore_pre_critique(deck_root: Path) -> None:
     shutil.copy2(src, dst)
 
 
+def cleanup_pre_critique(deck_root: Path) -> None:
+    """Delete index.pre-critique.html if present. No-op if absent.
+
+    Task 7's lifecycle wiring calls this once the critique pass has
+    completed and validation has passed — at that point the snapshot is
+    no longer needed, and leaving it on disk would accumulate stale
+    files across runs.
+    """
+    snapshot = deck_root / f"index.{PRE_CRITIQUE_SUFFIX}.html"
+    if snapshot.is_file():
+        snapshot.unlink()
+
+
 def build_deck_critic_agent(
     *,
     wiki_root: str,
diff --git a/openkb/prompts/deck_critique.md b/openkb/prompts/deck_critique.md
index 2ffa4b66..2c5568ae 100644
--- a/openkb/prompts/deck_critique.md
+++ b/openkb/prompts/deck_critique.md
@@ -23,6 +23,9 @@ sources you can locate from inherited context.
 ## Working method
 
 1. **Read the current draft.** `read_deck_file("index.html")` first.
+   Ignore any sibling files in the deck directory (e.g.
+   `index.pre-critique.html`) — those are internal safety snapshots,
+   not for you to read or write.
 2. **Score against failure modes.** For each of these, identify each
    slide that violates and note what to change:
    - Bullet dump (> 5 bullets)
diff --git a/tests/test_deck_critic.py b/tests/test_deck_critic.py
index 4201a383..21cd9196 100644
--- a/tests/test_deck_critic.py
+++ b/tests/test_deck_critic.py
@@ -64,3 +64,24 @@ def test_restore_idempotent_when_no_snapshot(tmp_path: Path):
     # No pre-critique file. Should be a no-op, not an error.
     restore_pre_critique(deck_root)
     assert (deck_root / "index.html").read_text() == "<html>only-version</html>"
+
+
+def test_cleanup_removes_snapshot(tmp_path: Path):
+    deck_root = tmp_path / "deck"
+    deck_root.mkdir()
+    (deck_root / "index.html").write_text("<html>v2</html>", encoding="utf-8")
+    (deck_root / "index.pre-critique.html").write_text("<html>v1</html>", encoding="utf-8")
+    from openkb.deck.critic import cleanup_pre_critique
+    cleanup_pre_critique(deck_root)
+    assert not (deck_root / "index.pre-critique.html").exists()
+    # index.html (the live deck) is untouched
+    assert (deck_root / "index.html").read_text() == "<html>v2</html>"
+
+
+def test_cleanup_idempotent_when_no_snapshot(tmp_path: Path):
+    deck_root = tmp_path / "deck"
+    deck_root.mkdir()
+    (deck_root / "index.html").write_text("<html>v1</html>", encoding="utf-8")
+    from openkb.deck.critic import cleanup_pre_critique
+    cleanup_pre_critique(deck_root)  # No snapshot to clean — no exception.
+    assert (deck_root / "index.html").read_text() == "<html>v1</html>"

From cf4ec2e5a12b8b1318d3b0c7501c8430bb53b1ca Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 22:58:53 +0800
Subject: [PATCH 10/25] feat(deck): wire critic via SDK handoff when --critique
 is set

---
 openkb/deck/creator.py     | 87 +++++++++++++++++++++++++++++---------
 tests/test_deck_creator.py | 62 +++++++++++++++++++++++++++
 2 files changed, 129 insertions(+), 20 deletions(-)

diff --git a/openkb/deck/creator.py b/openkb/deck/creator.py
index 1b3786df..d040e862 100644
--- a/openkb/deck/creator.py
+++ b/openkb/deck/creator.py
@@ -117,31 +117,78 @@ def done(summary: str) -> str:
         """Signal the deck is complete. Call exactly once when finished."""
         return f"Deck marked done: {summary}"
 
-    # critique=True wiring is added in Task 7. For now, no handoffs.
-    if critique:
-        raise NotImplementedError(
-            "--critique wiring lands in Task 7. Until then, build_deck_create_agent "
-            "only supports critique=False."
+    main_tools = [
+        list_wiki_dir,
+        read_wiki_file,
+        get_page_content,
+        get_image,
+        query_wiki,
+        write_deck_file,
+        done,
+    ]
+
+    if not critique:
+        return Agent(
+            name="deck-creator",
+            instructions=instructions,
+            tools=main_tools,
+            model=f"litellm/{model}",
+            # Parallel reads (early fan-out: list dir → read N summaries → read N
+            # source page-ranges) saves 5-10 round-trips per compile. Writes
+            # naturally serialise since each write_deck_file depends on prior
+            # reads; model has no reason to write the same path twice in
+            # parallel.
+            model_settings=ModelSettings(parallel_tool_calls=True),
         )
 
+    # critique=True: wire critic agent as a handoff target. The agents
+    # SDK auto-exposes a `transfer_to_<critic_name>` tool when handoffs
+    # is non-empty; we don't need to declare it in `main_tools` ourselves.
+    from openkb.deck.critic import build_deck_critic_agent, snapshot_pre_critique
+
+    critic_agent = build_deck_critic_agent(
+        wiki_root=wiki_root,
+        deck_root=deck_root,
+        intent=intent,
+        model=model,
+    )
+
+    # Attach snapshot hook to critic so index.pre-critique.html is taken
+    # the instant control transfers. We try the SDK's lifecycle hook
+    # first; if unavailable in the pinned version, snapshot via critic
+    # prompt's first action is the fallback (see comment below).
+    def _on_handoff_to_critic(_ctx) -> None:
+        snapshot_pre_critique(Path(deck_root))
+
+    # SDK lifecycle hook — different versions expose this under different
+    # names. We try the documented form, then fall back to a no-op so
+    # the import-time wiring never crashes the build.
+    setter = getattr(critic_agent, "on_handoff", None) or getattr(
+        critic_agent, "on_invocation_start", None
+    )
+    if callable(setter):
+        try:
+            critic_agent.on_handoff = _on_handoff_to_critic  # type: ignore[attr-defined]
+        except Exception:
+            # Hook not assignable in this SDK version — the critic prompt's
+            # working method step 1 is "first action: call snapshot_pre_critique".
+            # See Task 6's prompt.
+            pass
+
+    handoff_instructions = (
+        "\n\n## Critique pass\n\n"
+        "A critic agent will review your work. When you have finished "
+        "writing index.html and run your self-check, **do not call `done()`** — "
+        "instead transfer to the critic via the handoff tool. The critic "
+        "will revise the deck and call `done` itself."
+    )
+
     return Agent(
         name="deck-creator",
-        instructions=instructions,
-        tools=[
-            list_wiki_dir,
-            read_wiki_file,
-            get_page_content,
-            get_image,
-            query_wiki,
-            write_deck_file,
-            done,
-        ],
+        instructions=instructions + handoff_instructions,
+        tools=main_tools,
+        handoffs=[critic_agent],
         model=f"litellm/{model}",
-        # Parallel reads (early fan-out: list dir → read N summaries → read N
-        # source page-ranges) saves 5-10 round-trips per compile. Writes
-        # naturally serialise since each write_deck_file depends on prior
-        # reads; model has no reason to write the same path twice in
-        # parallel.
         model_settings=ModelSettings(parallel_tool_calls=True),
     )
 
diff --git a/tests/test_deck_creator.py b/tests/test_deck_creator.py
index 8118fde8..4e1bb14f 100644
--- a/tests/test_deck_creator.py
+++ b/tests/test_deck_creator.py
@@ -97,3 +97,65 @@ def test_run_translates_maxturns(tmp_path: Path):
                     critique=False,
                 )
             )
+
+
+def test_build_agent_critique_sets_handoffs(tmp_path: Path):
+    wiki_root, deck_root = _build(tmp_path)
+    agent = build_deck_create_agent(
+        wiki_root=str(wiki_root),
+        deck_root=str(deck_root),
+        deck_name="test-deck",
+        intent="A test deck.",
+        model="openai/gpt-4o",
+        critique=True,
+    )
+    # Main still has 7 tools (SDK auto-exposes the handoff transfer tool
+    # separately, not through the explicit `tools` list).
+    assert len(agent.tools) == 7
+    assert agent.handoffs, "critique=True must wire a critic handoff"
+    assert len(agent.handoffs) == 1
+    assert agent.handoffs[0].name == "deck-critic"
+
+
+def test_build_agent_critique_appends_handoff_instructions(tmp_path: Path):
+    wiki_root, deck_root = _build(tmp_path)
+    agent = build_deck_create_agent(
+        wiki_root=str(wiki_root),
+        deck_root=str(deck_root),
+        deck_name="test-deck",
+        intent="A test deck.",
+        model="openai/gpt-4o",
+        critique=True,
+    )
+    assert "Critique pass" in agent.instructions
+    assert "transfer to" in agent.instructions.lower()
+
+
+def test_run_with_critique_uses_higher_turn_cap(tmp_path: Path):
+    """When critique=True, Runner.run must be called with max_turns=120."""
+    wiki_root, _ = _build(tmp_path)
+    kb_dir = tmp_path
+    captured: dict = {}
+
+    async def _fake_run(agent, seed, *, max_turns):
+        captured["max_turns"] = max_turns
+        # Write a minimal index.html so run_deck_create does not raise.
+        from openkb.deck import deck_dir
+        d = deck_dir(kb_dir, "test-deck")
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "index.html").write_text("<html></html>", encoding="utf-8")
+        return MagicMock()
+
+    with patch("openkb.deck.creator.Runner") as runner:
+        runner.run = _fake_run  # plain async fn, not AsyncMock — we read args
+        import asyncio
+        asyncio.run(
+            run_deck_create(
+                kb_dir=kb_dir,
+                deck_name="test-deck",
+                intent="A test deck.",
+                model="openai/gpt-4o",
+                critique=True,
+            )
+        )
+    assert captured["max_turns"] == 120

From 714563d8a0feed6e45fa2fa12df75a040338573b Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 23:05:52 +0800
Subject: [PATCH 11/25] fix(deck): make snapshot a critic tool to close
 fallback-safety gap

---
 openkb/deck/creator.py          | 30 ++++++++----------------------
 openkb/deck/critic.py           | 12 ++++++++++++
 openkb/prompts/deck_critique.md | 14 +++++++++-----
 tests/test_deck_critic.py       |  5 +++--
 4 files changed, 32 insertions(+), 29 deletions(-)

diff --git a/openkb/deck/creator.py b/openkb/deck/creator.py
index d040e862..d71ada63 100644
--- a/openkb/deck/creator.py
+++ b/openkb/deck/creator.py
@@ -144,7 +144,7 @@ def done(summary: str) -> str:
     # critique=True: wire critic agent as a handoff target. The agents
     # SDK auto-exposes a `transfer_to_<critic_name>` tool when handoffs
     # is non-empty; we don't need to declare it in `main_tools` ourselves.
-    from openkb.deck.critic import build_deck_critic_agent, snapshot_pre_critique
+    from openkb.deck.critic import build_deck_critic_agent
 
     critic_agent = build_deck_critic_agent(
         wiki_root=wiki_root,
@@ -153,27 +153,13 @@ def done(summary: str) -> str:
         model=model,
     )
 
-    # Attach snapshot hook to critic so index.pre-critique.html is taken
-    # the instant control transfers. We try the SDK's lifecycle hook
-    # first; if unavailable in the pinned version, snapshot via critic
-    # prompt's first action is the fallback (see comment below).
-    def _on_handoff_to_critic(_ctx) -> None:
-        snapshot_pre_critique(Path(deck_root))
-
-    # SDK lifecycle hook — different versions expose this under different
-    # names. We try the documented form, then fall back to a no-op so
-    # the import-time wiring never crashes the build.
-    setter = getattr(critic_agent, "on_handoff", None) or getattr(
-        critic_agent, "on_invocation_start", None
-    )
-    if callable(setter):
-        try:
-            critic_agent.on_handoff = _on_handoff_to_critic  # type: ignore[attr-defined]
-        except Exception:
-            # Hook not assignable in this SDK version — the critic prompt's
-            # working method step 1 is "first action: call snapshot_pre_critique".
-            # See Task 6's prompt.
-            pass
+    # The critic's prompt step 1 instructs it to call its `take_snapshot`
+    # tool as the first action, which creates index.pre-critique.html.
+    # We tried an SDK lifecycle hook (on_handoff) for this, but the
+    # pinned openai-agents version exposes lifecycle callbacks only via
+    # the Agent.hooks dataclass field (AgentHooks subclass), not as a
+    # settable attribute. The prompt-driven approach is simpler and
+    # works regardless of SDK version.
 
     handoff_instructions = (
         "\n\n## Critique pass\n\n"
diff --git a/openkb/deck/critic.py b/openkb/deck/critic.py
index 0ff5f1b2..800dca24 100644
--- a/openkb/deck/critic.py
+++ b/openkb/deck/critic.py
@@ -128,6 +128,17 @@ async def query_wiki(question: str) -> str:
         kb_dir = Path(wiki_root).parent
         return await run_query(question, kb_dir, model, stream=False)
 
+    @function_tool
+    def take_snapshot() -> str:
+        """Save the current index.html as index.pre-critique.html.
+
+        Call this as your FIRST action when starting the critique, before
+        reading or modifying anything. It preserves the creator's draft
+        so it can be restored if your revisions fail validation.
+        """
+        snapshot_pre_critique(Path(deck_root))
+        return "Snapshot taken: index.pre-critique.html"
+
     @function_tool
     def read_deck_file(path: str) -> str:
         """Read a file from the deck directory (e.g. 'index.html')."""
@@ -152,6 +163,7 @@ def done(summary: str) -> str:
             get_page_content,
             get_image,
             query_wiki,
+            take_snapshot,
             read_deck_file,
             write_deck_file,
             done,
diff --git a/openkb/prompts/deck_critique.md b/openkb/prompts/deck_critique.md
index 2c5568ae..0026d01a 100644
--- a/openkb/prompts/deck_critique.md
+++ b/openkb/prompts/deck_critique.md
@@ -22,11 +22,15 @@ sources you can locate from inherited context.
 
 ## Working method
 
-1. **Read the current draft.** `read_deck_file("index.html")` first.
+1. **Take a snapshot first.** Your VERY first tool call must be
+   `take_snapshot()`. This preserves the creator's draft as
+   `index.pre-critique.html` so the orchestrator can restore it if
+   your revisions fail validation. Do this before reading anything.
+2. **Read the current draft.** `read_deck_file("index.html")` next.
    Ignore any sibling files in the deck directory (e.g.
    `index.pre-critique.html`) — those are internal safety snapshots,
    not for you to read or write.
-2. **Score against failure modes.** For each of these, identify each
+3. **Score against failure modes.** For each of these, identify each
    slide that violates and note what to change:
    - Bullet dump (> 5 bullets)
    - Wall of text (body > 80 words)
@@ -36,15 +40,15 @@ sources you can locate from inherited context.
      palette: `#f3eee1`, `#1a1612`, `#7a6e55`, `#d4cfc0`, `#a4341c`,
      `#fff3a8`)
    - Generic titles ("Introduction", "Background", "Conclusion")
-3. **Score against invariants.** Verify:
+4. **Score against invariants.** Verify:
    - ≥ 1 `data-type="cover"` + ≥ 1 `data-type="closing"`
    - Slide count ∈ [8, 15]
    - ≥ 4 distinct `data-type` values
    - No run of 3+ consecutive same `data-type`
-4. **Patch.** Write the revised `index.html` in a single
+5. **Patch.** Write the revised `index.html` in a single
    `write_deck_file("index.html", ...)` call. Do not split into
    multiple writes — one atomic replacement.
-5. **Call `done(summary)`** with a one-paragraph summary of what you
+6. **Call `done(summary)`** with a one-paragraph summary of what you
    changed and why.
 
 ## Design system invariants
diff --git a/tests/test_deck_critic.py b/tests/test_deck_critic.py
index 21cd9196..c149d9dc 100644
--- a/tests/test_deck_critic.py
+++ b/tests/test_deck_critic.py
@@ -26,9 +26,10 @@ def test_build_critic_agent_shape(tmp_path: Path):
         model="openai/gpt-4o",
     )
     assert agent.name == "deck-critic"
-    # 8 tools: 5 wiki-read + write_deck_file + read_deck_file + done
-    assert len(agent.tools) == 8
+    # 9 tools: 5 wiki-read + take_snapshot + read_deck_file + write_deck_file + done
+    assert len(agent.tools) == 9
     tool_names = {getattr(t, "name", "?") for t in agent.tools}
+    assert "take_snapshot" in tool_names
     assert "read_deck_file" in tool_names
     assert "write_deck_file" in tool_names
 

From ca19c23a50b7698a325e7f862c270d6c880174b9 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 23:10:17 +0800
Subject: [PATCH 12/25] docs(deck): update critic.py docstring after
 lifecycle-hook removal

---
 openkb/deck/critic.py | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/openkb/deck/critic.py b/openkb/deck/critic.py
index 800dca24..72886926 100644
--- a/openkb/deck/critic.py
+++ b/openkb/deck/critic.py
@@ -11,9 +11,12 @@
 
 Safety:
   * ``snapshot_pre_critique`` copies ``index.html`` →
-    ``index.pre-critique.html`` the instant control transfers to critic
-    (called from the SDK lifecycle hook attached in
-    ``build_deck_create_agent`` Task 7).
+    ``index.pre-critique.html``. The critic agent calls this via its
+    ``take_snapshot`` tool as the first action in its working method
+    (see ``deck_critique.md`` step 1). The pinned openai-agents SDK
+    exposes lifecycle callbacks only via ``Agent.hooks`` (an AgentHooks
+    subclass), not as settable ``on_handoff`` attributes, so a
+    prompt-driven first-tool-call is the simplest reliable trigger.
   * ``restore_pre_critique`` puts the snapshot back when critic raises,
     hits MaxTurnsExceeded, or produces output that fails validation.
   * ``cleanup_pre_critique`` removes the snapshot once critique has

From 6e16c4a92e1b99324ee15081ebe19391d55325b9 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 23:14:13 +0800
Subject: [PATCH 13/25] feat(deck): register deck target_type in Generator
 dispatch

---
 openkb/skill/generator.py | 98 +++++++++++++++++++++++++++------------
 tests/test_generator.py   | 64 +++++++++++++++++++++++++
 2 files changed, 132 insertions(+), 30 deletions(-)

diff --git a/openkb/skill/generator.py b/openkb/skill/generator.py
index 48f4dce5..3449fffd 100644
--- a/openkb/skill/generator.py
+++ b/openkb/skill/generator.py
@@ -1,45 +1,54 @@
 """Generator primitive — shared abstraction for all `<kb>/output/<type>/` artifacts.
 
-v0.1 supports ``target_type="skill"`` only. Future targets (``"ppt"``,
-``"podcast"``, ``"report"``, ``"video"``) will register here and reuse the
-same:
+v0.2 supports ``target_type="skill"`` and ``target_type="deck"``. Future
+targets (``"podcast"``, ``"report"``, ``"video"``) plug in here under the
+same conventions:
 
 * output-path convention: ``<kb>/output/<type>/<name>/``
-* post-compile validation: structural check via :mod:`openkb.skill.validator`
-* post-run hook: marketplace.json regeneration (so artifacts ride the same
-  distribution mechanic as skills)
+* post-compile validation: target-specific validator dispatched here
+* post-run hooks: skill regenerates marketplace.json; deck does not (it's
+  not a Claude Code plugin)
 
-Each target plugs in its own `run` coroutine. v0.1's only entry calls into
-``openkb.skill.creator.run_skill_create``.
-
-Validation runs inside ``run`` so every entry point — CLI, chat slash
-command, or future programmatic caller — gets the same quality gate.
-Callers consume :attr:`Generator.validation` after ``run()`` returns to
-format the issues for their output sink.
+Each target plugs in its own ``run`` coroutine. v0.2 dispatches to
+``openkb.skill.creator.run_skill_create`` or
+``openkb.deck.creator.run_deck_create``.
 """
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Literal
+from typing import Literal, Union
 
+from openkb.deck import deck_dir
+from openkb.deck.creator import run_deck_create
+from openkb.deck.critic import restore_pre_critique
+from openkb.deck.validator import (
+    ValidationResult as DeckValidationResult,
+    validate_deck,
+)
 from openkb.skill import skill_dir
 from openkb.skill.creator import run_skill_create
 from openkb.skill.marketplace import regenerate_marketplace
-from openkb.skill.validator import ValidationResult, validate_skill
+from openkb.skill.validator import (
+    ValidationResult as SkillValidationResult,
+    validate_skill,
+)
 
 
-TargetType = Literal["skill"]  # extend as new targets land
+TargetType = Literal["skill", "deck"]
+AnyValidationResult = Union[SkillValidationResult, DeckValidationResult]
 
 
 class Generator:
-    """A v0.1 generator instance.
+    """A v0.2 generator instance.
 
     Args:
-        target_type: One of the supported targets. v0.1: ``"skill"``.
+        target_type: ``"skill"`` or ``"deck"``.
         name: kebab-case slug; becomes the output directory name.
         intent: natural-language description of the desired artifact.
         kb_dir: KB root.
         model: LiteLLM model name (from KB config).
+        critique: (deck only) opt-in second-pass review via SDK handoff.
+            Ignored for ``target_type="skill"``.
     """
 
     def __init__(
@@ -50,32 +59,61 @@ def __init__(
         intent: str,
         kb_dir: Path,
         model: str,
+        critique: bool = False,
     ) -> None:
-        if target_type != "skill":
+        if target_type not in ("skill", "deck"):
             raise ValueError(
-                f"Unknown target_type {target_type!r}. v0.1 supports only 'skill'."
+                f"Unknown target_type {target_type!r}. v0.2 supports 'skill' and 'deck'."
             )
-        self.target_type = target_type
+        self.target_type: TargetType = target_type
         self.name = name
         self.intent = intent
         self.kb_dir = kb_dir
         self.model = model
-        self.output_dir = skill_dir(kb_dir, name)
-        self.validation: ValidationResult | None = None
+        self.critique = critique
+        self.output_dir = (
+            deck_dir(kb_dir, name) if target_type == "deck" else skill_dir(kb_dir, name)
+        )
+        self.validation: AnyValidationResult | None = None
 
     async def run(self) -> Path:
         """Execute the generator. Returns the path to the produced artifact.
 
-        Side-effects, in order: compile → validate → publish manifest.
-        ``self.validation`` holds the :class:`ValidationResult` so callers
-        can surface issues without re-running the validator.
+        Side-effects, in order: compile → validate → (skill only) publish
+        manifest. ``self.validation`` holds the result so callers can
+        surface issues without re-running the validator.
+
+        Deck path: on validation error after a critique run, restore the
+        pre-critique snapshot so the user never loses the clean main draft.
         """
-        await run_skill_create(
+        if self.target_type == "skill":
+            await run_skill_create(
+                kb_dir=self.kb_dir,
+                skill_name=self.name,
+                intent=self.intent,
+                model=self.model,
+            )
+            self.validation = validate_skill(self.output_dir)
+            regenerate_marketplace(self.kb_dir)
+            return self.output_dir
+
+        # target_type == "deck"
+        await run_deck_create(
             kb_dir=self.kb_dir,
-            skill_name=self.name,
+            deck_name=self.name,
             intent=self.intent,
             model=self.model,
+            critique=self.critique,
         )
-        self.validation = validate_skill(self.output_dir)
-        regenerate_marketplace(self.kb_dir)
+        self.validation = validate_deck(self.output_dir)
+
+        if self.critique and self.validation.errors:
+            # Critique pass produced invalid HTML. Restore pre-critique
+            # snapshot and re-validate so callers see the clean state.
+            restore_pre_critique(self.output_dir)
+            self.validation = validate_deck(self.output_dir)
+            self.validation.warnings.append(
+                "critique pass failed; restored pre-critique draft."
+            )
+
         return self.output_dir
diff --git a/tests/test_generator.py b/tests/test_generator.py
index 37d574f3..6b4d8a30 100644
--- a/tests/test_generator.py
+++ b/tests/test_generator.py
@@ -58,3 +58,67 @@ async def test_generator_run_delegates_to_skill_creator(tmp_path):
         await g.run()
     runner.assert_awaited_once()
     regen.assert_called_once_with(kb)
+
+
+# --- target_type="deck" dispatch -------------------------------------------
+
+from openkb.deck.validator import ValidationResult as DeckValidationResult
+
+
+@pytest.mark.asyncio
+async def test_generator_deck_dispatches_to_deck_creator(tmp_path):
+    kb_dir = tmp_path
+    (kb_dir / "wiki").mkdir()
+    (kb_dir / "wiki" / "AGENTS.md").write_text("schema", encoding="utf-8")
+
+    gen = Generator(
+        target_type="deck",
+        name="my-deck",
+        intent="…",
+        kb_dir=kb_dir,
+        model="openai/gpt-4o",
+        critique=False,
+    )
+
+    with patch("openkb.skill.generator.run_deck_create", new_callable=AsyncMock) as run_dc, \
+         patch("openkb.skill.generator.regenerate_marketplace") as regen, \
+         patch("openkb.skill.generator.validate_deck") as v_deck:
+        run_dc.return_value = gen.output_dir
+        v_deck.return_value = DeckValidationResult()
+        result = await gen.run()
+
+    run_dc.assert_awaited_once_with(
+        kb_dir=kb_dir,
+        deck_name="my-deck",
+        intent="…",
+        model="openai/gpt-4o",
+        critique=False,
+    )
+    v_deck.assert_called_once_with(gen.output_dir)
+    regen.assert_not_called()  # marketplace is skill-only
+    assert result == gen.output_dir
+
+
+@pytest.mark.asyncio
+async def test_generator_deck_output_dir_is_decks(tmp_path):
+    gen = Generator(
+        target_type="deck",
+        name="my-deck",
+        intent="…",
+        kb_dir=tmp_path,
+        model="openai/gpt-4o",
+        critique=False,
+    )
+    assert gen.output_dir == tmp_path / "output" / "decks" / "my-deck"
+
+
+def test_generator_rejects_podcast_target_type(tmp_path):
+    with pytest.raises(ValueError, match="Unknown target_type"):
+        Generator(
+            target_type="podcast",  # type: ignore[arg-type]
+            name="x",
+            intent="…",
+            kb_dir=tmp_path,
+            model="openai/gpt-4o",
+            critique=False,
+        )

From 96c8ea02c9baa9b24c01240bdc984aea1b796443 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 23:21:29 +0800
Subject: [PATCH 14/25] feat(cli): add openkb deck new subcommand
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mirrors `openkb skill new` structurally — name validation, KB lookup,
LLM key check, config load, overwrite handling, Generator.run dispatch,
validation surfacing. Adds `--critique` flag to opt into the deck
critic pass.

`openkb.skill.workspace.save_iteration` is hard-wired to skill paths
(uses skill_dir / skill_workspace_dir), so this commit inlines a
small `_save_deck_iteration` helper that mirrors the iteration-N
copy-then-rmtree behavior using `deck_workspace_dir`. Keeps deck
rollback history scoped to decks without coupling deck CLI to skill
internals or churning skill code.
---
 openkb/cli.py          | 157 +++++++++++++++++++++++++++++++++++++++++
 tests/test_deck_cli.py | 114 ++++++++++++++++++++++++++++++
 2 files changed, 271 insertions(+)
 create mode 100644 tests/test_deck_cli.py

diff --git a/openkb/cli.py b/openkb/cli.py
index d5e6ff1a..43ad3d9e 100644
--- a/openkb/cli.py
+++ b/openkb/cli.py
@@ -1909,3 +1909,160 @@ def skill_eval(ctx, name, save_flag, eval_set_path, count):
     if save_flag and eval_set is None:
         path = save_eval_set(kb_dir, name, result.prompts)
         click.echo(f"\nEval set persisted to {path}")
+
+
+# ---------------------------------------------------------------------------
+# `openkb deck ...` — deck factory (v0.2)
+# ---------------------------------------------------------------------------
+
+
+@cli.group()
+def deck():
+    """Generate a polished single-file HTML slide deck from the wiki."""
+
+
+@deck.command("new")
+@click.argument("name")
+@click.argument("intent")
+@click.option(
+    "-y", "--yes", "yes_flag",
+    is_flag=True, default=False,
+    help="Overwrite existing output/decks/<name>/ without prompting.",
+)
+@click.option(
+    "--critique", "critique_flag",
+    is_flag=True, default=False,
+    help="Opt-in second-pass review via a critic agent (slower, higher quality).",
+)
+@click.pass_context
+def deck_new(ctx, name, intent, yes_flag, critique_flag):
+    """Generate a new HTML deck from this KB's wiki.
+
+    NAME is a kebab-case slug used for the output directory.
+    INTENT is a natural-language description of what the deck is about.
+
+    Example:
+
+      openkb deck new transformers-pitch "Explain attention to engineers"
+      openkb deck new transformers-pitch "Explain attention to engineers" --critique
+    """
+    kb_dir = _find_kb_dir(ctx.obj.get("kb_dir_override"))
+    if kb_dir is None:
+        click.echo("No knowledge base found. Run `openkb init` first.", err=True)
+        ctx.exit(1)
+
+    # Reuse skill's name validation (kebab-case lowercase + hyphens).
+    err = _validate_skill_name(name)
+    if err:
+        # Reword "Skill name" → "Deck name" so error matches the command.
+        deck_err = err.replace("Skill name", "Deck name")
+        click.echo(
+            f"[ERROR] {deck_err} Use a kebab-case slug like 'my-deck'.",
+            err=True,
+        )
+        ctx.exit(1)
+
+    # Verify LLM key + load config BEFORE touching existing output. Any
+    # failure here (missing API key, malformed config) must leave the old
+    # deck directory intact — we can't replace it if we can't proceed.
+    try:
+        _setup_llm_key(kb_dir)
+    except RuntimeError as exc:
+        click.echo(f"[ERROR] {exc}", err=True)
+        ctx.exit(1)
+    config = load_config(kb_dir / ".openkb" / "config.yaml")
+    model = config.get("model", DEFAULT_CONFIG["model"])
+
+    # Overwrite handling — inline because openkb.skill.workspace.save_iteration
+    # is hard-wired to skill paths (uses skill_dir / skill_workspace_dir from
+    # openkb.skill). Mirror its iteration-N copy-then-rmtree behavior here
+    # using deck_workspace_dir so users keep rollback safety without coupling
+    # deck CLI to skill internals.
+    from openkb.deck import deck_dir as _deck_dir, deck_workspace_dir as _deck_workspace_dir
+
+    target = _deck_dir(kb_dir, name)
+    if target.exists():
+        if yes_flag:
+            _save_deck_iteration(kb_dir, name)
+            shutil.rmtree(target)
+        elif sys.stdin.isatty():
+            if not click.confirm(
+                f"output/decks/{name}/ already exists. Overwrite?",
+                default=False,
+            ):
+                click.echo("Aborted.")
+                ctx.exit(1)
+            _save_deck_iteration(kb_dir, name)
+            shutil.rmtree(target)
+        else:
+            click.echo(
+                f"[ERROR] output/decks/{name}/ exists. Pass -y to overwrite "
+                f"in non-interactive contexts.",
+                err=True,
+            )
+            ctx.exit(1)
+
+    # Run the generator.
+    from openkb.skill.generator import Generator
+    click.echo(f"Generating deck '{name}'...")
+    gen = Generator(
+        target_type="deck",
+        name=name,
+        intent=intent,
+        kb_dir=kb_dir,
+        model=model,
+        critique=critique_flag,
+    )
+    try:
+        asyncio.run(gen.run())
+    except RuntimeError as exc:
+        click.echo(f"[ERROR] {exc}", err=True)
+        ctx.exit(1)
+
+    # Surface validation result.
+    if gen.validation:
+        for w in gen.validation.warnings:
+            click.echo(f"[WARN] {w}", err=True)
+        for e in gen.validation.errors:
+            click.echo(f"[ERROR] {e}", err=True)
+        if gen.validation.errors:
+            click.echo(
+                f"Deck written to {gen.output_dir / 'index.html'} but failed validation. "
+                f"Inspect and re-run.",
+                err=True,
+            )
+            ctx.exit(1)
+
+    click.echo(f"Deck written to {gen.output_dir / 'index.html'}")
+
+
+def _save_deck_iteration(kb_dir: Path, deck_name: str) -> Path | None:
+    """Copy ``<kb>/output/decks/<name>/`` to the next iteration slot.
+
+    Mirrors ``openkb.skill.workspace.save_iteration`` but uses
+    ``deck_workspace_dir`` so deck rollback history stays separate from
+    skill history. Returns the saved iteration path, or ``None`` if there's
+    no current deck to save.
+    """
+    import re
+    from openkb.deck import deck_dir as _deck_dir, deck_workspace_dir as _deck_workspace_dir
+
+    src = _deck_dir(kb_dir, deck_name)
+    if not src.is_dir():
+        return None
+
+    ws = _deck_workspace_dir(kb_dir, deck_name)
+    ws.mkdir(parents=True, exist_ok=True)
+
+    iter_re = re.compile(r"^iteration-(\d+)$")
+    existing_ns: list[int] = []
+    for child in ws.iterdir():
+        if child.is_dir():
+            m = iter_re.match(child.name)
+            if m:
+                existing_ns.append(int(m.group(1)))
+    next_n = (max(existing_ns) if existing_ns else 0) + 1
+
+    dest = ws / f"iteration-{next_n}"
+    shutil.copytree(src, dest)
+    return dest
diff --git a/tests/test_deck_cli.py b/tests/test_deck_cli.py
new file mode 100644
index 00000000..191d3135
--- /dev/null
+++ b/tests/test_deck_cli.py
@@ -0,0 +1,114 @@
+"""Click CLI tests for `openkb deck new`. Mocks Generator.run; no LLM."""
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from click.testing import CliRunner
+
+from openkb.cli import cli
+
+
+def _init_kb(tmp_path: Path) -> Path:
+    """Create a minimal valid KB on disk so cli's _find_kb_dir resolves."""
+    (tmp_path / ".openkb").mkdir()
+    (tmp_path / ".openkb" / "config.yaml").write_text(
+        "model: openai/gpt-4o\nlanguage: en\n", encoding="utf-8"
+    )
+    (tmp_path / "wiki").mkdir()
+    (tmp_path / "wiki" / "AGENTS.md").write_text("schema", encoding="utf-8")
+    return tmp_path
+
+
+def test_deck_new_help(tmp_path: Path):
+    runner = CliRunner()
+    result = runner.invoke(cli, ["deck", "new", "--help"])
+    assert result.exit_code == 0
+    assert "kebab-case" in result.output.lower() or "name" in result.output.lower()
+
+
+def test_deck_new_rejects_no_kb(tmp_path: Path, monkeypatch):
+    monkeypatch.chdir(tmp_path)  # no .openkb here
+    runner = CliRunner()
+    with patch("openkb.cli._find_kb_dir", return_value=None):
+        result = runner.invoke(cli, ["deck", "new", "my-deck", "An intent."])
+    assert result.exit_code != 0
+    assert "knowledge base" in result.output.lower()
+
+
+def test_deck_new_rejects_invalid_name(tmp_path: Path, monkeypatch):
+    _init_kb(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    runner = CliRunner()
+    result = runner.invoke(cli, ["deck", "new", "Invalid_Name", "An intent."])
+    assert result.exit_code != 0
+    assert "kebab" in result.output.lower() or "invalid" in result.output.lower()
+
+
+def test_deck_new_happy_path(tmp_path: Path, monkeypatch):
+    _init_kb(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("LLM_API_KEY", "test-key")
+
+    fake_validation = type("V", (), {"errors": [], "warnings": [], "ok": True})()
+
+    with patch("openkb.skill.generator.Generator") as gen_cls:
+        gen = gen_cls.return_value
+        gen.run = AsyncMock(return_value=tmp_path / "output" / "decks" / "my-deck")
+        gen.validation = fake_validation
+        gen.output_dir = tmp_path / "output" / "decks" / "my-deck"
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["deck", "new", "my-deck", "An intent."])
+
+    assert result.exit_code == 0, result.output
+    gen_cls.assert_called_once()
+    kwargs = gen_cls.call_args.kwargs
+    assert kwargs["target_type"] == "deck"
+    assert kwargs["name"] == "my-deck"
+    assert kwargs["intent"] == "An intent."
+    assert kwargs["critique"] is False
+
+
+def test_deck_new_passes_critique_flag(tmp_path: Path, monkeypatch):
+    _init_kb(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("LLM_API_KEY", "test-key")
+
+    fake_validation = type("V", (), {"errors": [], "warnings": [], "ok": True})()
+
+    with patch("openkb.skill.generator.Generator") as gen_cls:
+        gen = gen_cls.return_value
+        gen.run = AsyncMock(return_value=tmp_path / "output" / "decks" / "my-deck")
+        gen.validation = fake_validation
+        gen.output_dir = tmp_path / "output" / "decks" / "my-deck"
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["deck", "new", "--critique", "my-deck", "An intent."])
+
+    assert result.exit_code == 0, result.output
+    assert gen_cls.call_args.kwargs["critique"] is True
+
+
+def test_deck_new_surfaces_validation_errors(tmp_path: Path, monkeypatch):
+    _init_kb(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("LLM_API_KEY", "test-key")
+
+    fake_validation = type(
+        "V", (), {"errors": ["bad slide count"], "warnings": [], "ok": False}
+    )()
+
+    with patch("openkb.skill.generator.Generator") as gen_cls:
+        gen = gen_cls.return_value
+        gen.run = AsyncMock(return_value=tmp_path / "output" / "decks" / "my-deck")
+        gen.validation = fake_validation
+        gen.output_dir = tmp_path / "output" / "decks" / "my-deck"
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["deck", "new", "my-deck", "An intent."])
+
+    # Non-zero exit, error printed, but file preserved (validator semantics).
+    assert result.exit_code != 0
+    assert "bad slide count" in result.output

From daacce597f8349d77ace4b8ad8d36a7a9bb24ea9 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 23:27:26 +0800
Subject: [PATCH 15/25] feat(deck): /deck new chat slash command

---
 openkb/agent/chat.py          | 104 ++++++++++++++++++++++++++
 tests/test_deck_chat_slash.py | 134 ++++++++++++++++++++++++++++++++++
 2 files changed, 238 insertions(+)
 create mode 100644 tests/test_deck_chat_slash.py

diff --git a/openkb/agent/chat.py b/openkb/agent/chat.py
index 8e0d603f..80e4d028 100644
--- a/openkb/agent/chat.py
+++ b/openkb/agent/chat.py
@@ -60,6 +60,7 @@
     "  /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] <name> "<intent>"   Generate an HTML deck from the wiki\n'
     "  /help          Show this"
 )
 
@@ -216,6 +217,7 @@ 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\"`)"),
 ]
 
 
@@ -576,6 +578,104 @@ 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 (anywhere among the remaining tokens
+    # is fine, but typically right after `new`).
+    rest = parts[1:]
+    critique = False
+    filtered: list[str] = []
+    for tok in rest:
+        if tok == "--critique":
+            critique = True
+        else:
+            filtered.append(tok)
+
+    if len(filtered) < 2:
+        _fmt(style, ("class:error",
+            "Usage: /deck new [--critique] <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
+    _fmt(style, ("class:slash.help", f"Generating deck '{name}'...\n"))
+    gen = Generator(
+        target_type="deck",
+        name=name,
+        intent=intent,
+        kb_dir=kb_dir,
+        model=model,
+        critique=critique,
+    )
+    try:
+        await gen.run()
+    except RuntimeError as exc:
+        _fmt(style, ("class:error", f"[ERROR] {exc}\n"))
+        return
+
+    # Surface validation issues from Generator.run (same gate as CLI).
+    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,6 +743,10 @@ 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
+
     _fmt(
         style,
         ("class:error", f"Unknown command: {head}. Try /help.\n"),
diff --git a/tests/test_deck_chat_slash.py b/tests/test_deck_chat_slash.py
new file mode 100644
index 00000000..8de4575c
--- /dev/null
+++ b/tests/test_deck_chat_slash.py
@@ -0,0 +1,134 @@
+"""Tests for the /deck new slash command inside openkb chat."""
+from __future__ import annotations
+
+import pytest
+from unittest.mock import AsyncMock, patch
+
+from prompt_toolkit.styles import Style
+
+from openkb.agent.chat import _handle_slash
+from openkb.agent.chat_session import ChatSession
+
+
+def _make_kb(tmp_path):
+    (tmp_path / ".openkb").mkdir()
+    (tmp_path / ".openkb" / "config.yaml").write_text("model: gpt-4o-mini\n")
+    (tmp_path / ".openkb" / "chats").mkdir()
+    (tmp_path / "wiki" / "concepts").mkdir(parents=True)
+    (tmp_path / "wiki" / "summaries").mkdir(parents=True)
+    (tmp_path / "wiki" / "index.md").write_text("# index\n")
+    # Populate so wiki-content gate accepts
+    (tmp_path / "wiki" / "concepts" / "demo.md").write_text("# demo\n")
+    (tmp_path / "wiki" / "summaries" / "demo.md").write_text("# demo\n")
+    return tmp_path
+
+
+@pytest.mark.asyncio
+async def test_slash_deck_new_invokes_generator(tmp_path):
+    kb = _make_kb(tmp_path)
+    session = ChatSession.new(kb, "gpt-4o-mini", "en")
+    style = Style.from_dict({})
+
+    fake_validation = type("V", (), {"errors": [], "warnings": [], "ok": True})()
+
+    with patch("openkb.skill.generator.Generator") as gen_cls:
+        gen = gen_cls.return_value
+        gen.run = AsyncMock(return_value=kb / "output" / "decks" / "demo")
+        gen.validation = fake_validation
+        gen.output_dir = kb / "output" / "decks" / "demo"
+
+        action = await _handle_slash(
+            '/deck new demo "test intent"', kb, session, style
+        )
+
+    assert action is None  # continues chat session
+    gen_cls.assert_called_once()
+    kwargs = gen_cls.call_args.kwargs
+    assert kwargs["target_type"] == "deck"
+    assert kwargs["name"] == "demo"
+    assert kwargs["intent"] == "test intent"
+    assert kwargs["kb_dir"] == kb
+    assert kwargs["critique"] is False
+
+
+@pytest.mark.asyncio
+async def test_slash_deck_new_with_critique_flag(tmp_path):
+    kb = _make_kb(tmp_path)
+    session = ChatSession.new(kb, "gpt-4o-mini", "en")
+    style = Style.from_dict({})
+
+    fake_validation = type("V", (), {"errors": [], "warnings": [], "ok": True})()
+
+    with patch("openkb.skill.generator.Generator") as gen_cls:
+        gen = gen_cls.return_value
+        gen.run = AsyncMock(return_value=kb / "output" / "decks" / "demo")
+        gen.validation = fake_validation
+        gen.output_dir = kb / "output" / "decks" / "demo"
+
+        action = await _handle_slash(
+            '/deck new --critique demo "test intent"', kb, session, style
+        )
+
+    assert action is None
+    gen_cls.assert_called_once()
+    kwargs = gen_cls.call_args.kwargs
+    assert kwargs["target_type"] == "deck"
+    assert kwargs["name"] == "demo"
+    assert kwargs["critique"] is True
+
+
+@pytest.mark.asyncio
+async def test_slash_deck_new_reports_usage_when_args_missing(tmp_path):
+    kb = _make_kb(tmp_path)
+    session = ChatSession.new(kb, "gpt-4o-mini", "en")
+    style = Style.from_dict({})
+
+    action = await _handle_slash('/deck new', kb, session, style)
+    assert action is None
+    # No deck written
+    assert not (kb / "output").exists()
+
+
+@pytest.mark.asyncio
+async def test_slash_deck_unknown_subcommand(tmp_path):
+    kb = _make_kb(tmp_path)
+    session = ChatSession.new(kb, "gpt-4o-mini", "en")
+    style = Style.from_dict({})
+    action = await _handle_slash('/deck list', kb, session, style)
+    assert action is None
+
+
+@pytest.mark.asyncio
+async def test_slash_deck_new_rejects_empty_wiki(tmp_path):
+    """Chat / slash command must catch freshly-init'd KBs (no compiled content)."""
+    kb = tmp_path
+    (kb / ".openkb").mkdir()
+    (kb / ".openkb" / "config.yaml").write_text("model: gpt-4o-mini\n")
+    (kb / ".openkb" / "chats").mkdir()
+    # Empty wiki/ — exactly what `openkb init` creates
+    (kb / "wiki" / "concepts").mkdir(parents=True)
+    (kb / "wiki" / "summaries").mkdir(parents=True)
+    (kb / "wiki" / "index.md").write_text("# index\n")
+
+    session = ChatSession.new(kb, "gpt-4o-mini", "en")
+    style = Style.from_dict({})
+
+    action = await _handle_slash('/deck new demo "intent"', kb, session, style)
+    assert action is None
+    assert not (kb / "output").exists()
+
+
+@pytest.mark.asyncio
+async def test_slash_deck_new_rejects_when_target_exists(tmp_path):
+    """Chat / slash command must not silently overwrite an existing deck."""
+    kb = _make_kb(tmp_path)
+    (kb / "output" / "decks" / "demo").mkdir(parents=True)
+    (kb / "output" / "decks" / "demo" / "stale.html").write_text("old")
+
+    session = ChatSession.new(kb, "gpt-4o-mini", "en")
+    style = Style.from_dict({})
+
+    action = await _handle_slash('/deck new demo "intent"', kb, session, style)
+    assert action is None
+    # stale.html must still be there (we didn't overwrite)
+    assert (kb / "output" / "decks" / "demo" / "stale.html").read_text() == "old"

From 710978a5193056e3b79b21766426bb284b6d4881 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Fri, 22 May 2026 23:38:35 +0800
Subject: [PATCH 16/25] fix(deck): wire cleanup on critique success + CLI wiki
 preflight parity

---
 openkb/cli.py             | 19 ++++++-----
 openkb/skill/generator.py | 23 ++++++++-----
 tests/test_deck_cli.py    | 41 +++++++++++++++++++++-
 tests/test_generator.py   | 72 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 137 insertions(+), 18 deletions(-)

diff --git a/openkb/cli.py b/openkb/cli.py
index 43ad3d9e..7c4468f5 100644
--- a/openkb/cli.py
+++ b/openkb/cli.py
@@ -1951,15 +1951,18 @@ def deck_new(ctx, name, intent, yes_flag, critique_flag):
         click.echo("No knowledge base found. Run `openkb init` first.", err=True)
         ctx.exit(1)
 
-    # Reuse skill's name validation (kebab-case lowercase + hyphens).
-    err = _validate_skill_name(name)
+    # Reuse the shared safety gates: name validation + wiki content check.
+    # Matches chat's `/deck new` so users see the same errors in both UIs.
+    err = _preflight_skill_new(kb_dir, name)
     if err:
-        # Reword "Skill name" → "Deck name" so error matches the command.
-        deck_err = err.replace("Skill name", "Deck name")
-        click.echo(
-            f"[ERROR] {deck_err} Use a kebab-case slug like 'my-deck'.",
-            err=True,
-        )
+        # _preflight_skill_new returns messages like "Skill name must not be empty."
+        # and "Wiki at ... is empty — add documents with `openkb add` first."
+        err = err.replace("Skill name", "Deck name")
+        # Only append the kebab-case hint when the failure is actually about
+        # the slug, not the wiki-content gate.
+        if "kebab" not in err.lower() and "Wiki" not in err and "wiki" not in err:
+            err = err + " Use a kebab-case slug like 'my-deck'."
+        click.echo(f"[ERROR] {err}", err=True)
         ctx.exit(1)
 
     # Verify LLM key + load config BEFORE touching existing output. Any
diff --git a/openkb/skill/generator.py b/openkb/skill/generator.py
index 3449fffd..115b8e5a 100644
--- a/openkb/skill/generator.py
+++ b/openkb/skill/generator.py
@@ -20,7 +20,7 @@
 
 from openkb.deck import deck_dir
 from openkb.deck.creator import run_deck_create
-from openkb.deck.critic import restore_pre_critique
+from openkb.deck.critic import cleanup_pre_critique, restore_pre_critique
 from openkb.deck.validator import (
     ValidationResult as DeckValidationResult,
     validate_deck,
@@ -107,13 +107,18 @@ async def run(self) -> Path:
         )
         self.validation = validate_deck(self.output_dir)
 
-        if self.critique and self.validation.errors:
-            # Critique pass produced invalid HTML. Restore pre-critique
-            # snapshot and re-validate so callers see the clean state.
-            restore_pre_critique(self.output_dir)
-            self.validation = validate_deck(self.output_dir)
-            self.validation.warnings.append(
-                "critique pass failed; restored pre-critique draft."
-            )
+        if self.critique:
+            if self.validation.errors:
+                # Critique pass produced invalid HTML. Restore pre-critique
+                # snapshot and re-validate so callers see the clean state.
+                restore_pre_critique(self.output_dir)
+                self.validation = validate_deck(self.output_dir)
+                self.validation.warnings.append(
+                    "critique pass failed; restored pre-critique draft."
+                )
+            else:
+                # Critique succeeded — remove the snapshot so it doesn't
+                # accumulate across runs.
+                cleanup_pre_critique(self.output_dir)
 
         return self.output_dir
diff --git a/tests/test_deck_cli.py b/tests/test_deck_cli.py
index 191d3135..788d3488 100644
--- a/tests/test_deck_cli.py
+++ b/tests/test_deck_cli.py
@@ -11,13 +11,19 @@
 
 
 def _init_kb(tmp_path: Path) -> Path:
-    """Create a minimal valid KB on disk so cli's _find_kb_dir resolves."""
+    """Create a minimal valid KB on disk so cli's _find_kb_dir resolves.
+
+    Includes a non-empty ``wiki/concepts/`` so the shared
+    ``_preflight_skill_new`` wiki-content gate passes.
+    """
     (tmp_path / ".openkb").mkdir()
     (tmp_path / ".openkb" / "config.yaml").write_text(
         "model: openai/gpt-4o\nlanguage: en\n", encoding="utf-8"
     )
     (tmp_path / "wiki").mkdir()
     (tmp_path / "wiki" / "AGENTS.md").write_text("schema", encoding="utf-8")
+    (tmp_path / "wiki" / "concepts").mkdir()
+    (tmp_path / "wiki" / "concepts" / "foo.md").write_text("# foo\n", encoding="utf-8")
     return tmp_path
 
 
@@ -112,3 +118,36 @@ def test_deck_new_surfaces_validation_errors(tmp_path: Path, monkeypatch):
     # Non-zero exit, error printed, but file preserved (validator semantics).
     assert result.exit_code != 0
     assert "bad slide count" in result.output
+
+
+def test_deck_new_rejects_empty_wiki(tmp_path: Path, monkeypatch):
+    """CLI must refuse to compile when the KB exists but the wiki is empty
+    (parity with chat /deck new and CLI openkb skill new)."""
+    (tmp_path / ".openkb").mkdir()
+    (tmp_path / ".openkb" / "config.yaml").write_text(
+        "model: openai/gpt-4o\nlanguage: en\n", encoding="utf-8"
+    )
+    (tmp_path / "wiki").mkdir()
+    (tmp_path / "wiki" / "AGENTS.md").write_text("schema", encoding="utf-8")
+    # No wiki/concepts/, no wiki/summaries/ — wiki is "empty".
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("LLM_API_KEY", "test-key")
+
+    # Patch Generator so that, if preflight is missing, the test would still
+    # exit 0 — making this test only pass once the wiki-content gate is wired.
+    fake_validation = type("V", (), {"errors": [], "warnings": [], "ok": True})()
+    with patch("openkb.skill.generator.Generator") as gen_cls:
+        gen = gen_cls.return_value
+        gen.run = AsyncMock(return_value=tmp_path / "output" / "decks" / "my-deck")
+        gen.validation = fake_validation
+        gen.output_dir = tmp_path / "output" / "decks" / "my-deck"
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["deck", "new", "my-deck", "An intent."])
+
+    # Should exit non-zero before ever instantiating Generator.
+    assert result.exit_code != 0, result.output
+    gen_cls.assert_not_called()
+    # Error message should point at the empty wiki, not at name validation.
+    assert "wiki" in result.output.lower()
+    assert "kebab" not in result.output.lower()
diff --git a/tests/test_generator.py b/tests/test_generator.py
index 6b4d8a30..faca839b 100644
--- a/tests/test_generator.py
+++ b/tests/test_generator.py
@@ -122,3 +122,75 @@ def test_generator_rejects_podcast_target_type(tmp_path):
             model="openai/gpt-4o",
             critique=False,
         )
+
+
+@pytest.mark.asyncio
+async def test_generator_deck_cleanup_on_critique_success(tmp_path):
+    """When critique=True and validation passes, the pre-critique snapshot
+    must be deleted so it doesn't accumulate across runs."""
+    kb_dir = tmp_path
+    (kb_dir / "wiki").mkdir()
+    (kb_dir / "wiki" / "AGENTS.md").write_text("schema", encoding="utf-8")
+
+    gen = Generator(
+        target_type="deck",
+        name="my-deck",
+        intent="…",
+        kb_dir=kb_dir,
+        model="openai/gpt-4o",
+        critique=True,
+    )
+
+    # Simulate the creator + critic having written both files.
+    gen.output_dir.mkdir(parents=True, exist_ok=True)
+    (gen.output_dir / "index.html").write_text("<html>critic-output</html>", encoding="utf-8")
+    (gen.output_dir / "index.pre-critique.html").write_text("<html>pre-critic</html>", encoding="utf-8")
+
+    with patch("openkb.skill.generator.run_deck_create", new_callable=AsyncMock) as run_dc, \
+         patch("openkb.skill.generator.validate_deck") as v_deck:
+        run_dc.return_value = gen.output_dir
+        v_deck.return_value = DeckValidationResult()  # no errors → success
+        await gen.run()
+
+    # On critique success, the snapshot is cleaned up.
+    assert not (gen.output_dir / "index.pre-critique.html").exists()
+    # The live deck is untouched.
+    assert (gen.output_dir / "index.html").read_text() == "<html>critic-output</html>"
+
+
+@pytest.mark.asyncio
+async def test_generator_deck_restore_on_critique_failure(tmp_path):
+    """When critique=True and validation fails, the pre-critique snapshot
+    must be restored back to index.html and the snapshot kept for inspection."""
+    kb_dir = tmp_path
+    (kb_dir / "wiki").mkdir()
+    (kb_dir / "wiki" / "AGENTS.md").write_text("schema", encoding="utf-8")
+
+    gen = Generator(
+        target_type="deck",
+        name="my-deck",
+        intent="…",
+        kb_dir=kb_dir,
+        model="openai/gpt-4o",
+        critique=True,
+    )
+
+    # Simulate critic having corrupted index.html, with snapshot of original.
+    gen.output_dir.mkdir(parents=True, exist_ok=True)
+    (gen.output_dir / "index.html").write_text("<html>critic-broken</html>", encoding="utf-8")
+    (gen.output_dir / "index.pre-critique.html").write_text("<html>pre-critic-good</html>", encoding="utf-8")
+
+    # First validation reports an error; second (post-restore) is clean.
+    first_result = DeckValidationResult()
+    first_result.errors.append("bad slide count")
+    second_result = DeckValidationResult()
+
+    with patch("openkb.skill.generator.run_deck_create", new_callable=AsyncMock) as run_dc, \
+         patch("openkb.skill.generator.validate_deck", side_effect=[first_result, second_result]):
+        run_dc.return_value = gen.output_dir
+        await gen.run()
+
+    # index.html was restored from the snapshot.
+    assert (gen.output_dir / "index.html").read_text() == "<html>pre-critic-good</html>"
+    # The warning about restore is surfaced.
+    assert any("restored pre-critique draft" in w for w in gen.validation.warnings)

From 8c59f0c43b520991f36d1d7121d905e2c593193b Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Sat, 23 May 2026 10:25:57 +0800
Subject: [PATCH 17/25] docs(deck): correct doc/comment drift surfaced by code
 review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* critic.py: narrow restore docstring — it fires only on validation
  errors, not on critic exceptions or MaxTurnsExceeded (those bubble
  out of Generator.run before the restore branch runs).
* creator.py: drop stale "(see Task 7 — until then, only critique=False
  is wired)" qualifier; critique=True is now wired.
* chat.py: chat handler comment claimed "same gate as CLI" but chat
  prints issues and continues while CLI exits 1. Reworded for both
  /skill new and /deck new handlers.
---
 openkb/agent/chat.py   | 8 ++++++--
 openkb/deck/creator.py | 5 +++--
 openkb/deck/critic.py  | 7 +++++--
 3 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/openkb/agent/chat.py b/openkb/agent/chat.py
index 80e4d028..45b1301f 100644
--- a/openkb/agent/chat.py
+++ b/openkb/agent/chat.py
@@ -560,7 +560,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"))
@@ -661,7 +663,9 @@ async def _handle_slash_deck(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"))
diff --git a/openkb/deck/creator.py b/openkb/deck/creator.py
index d71ada63..94a8b532 100644
--- a/openkb/deck/creator.py
+++ b/openkb/deck/creator.py
@@ -6,8 +6,9 @@
 * System prompt comes from ``openkb/prompts/deck_create.md`` and is
   interpolated with intent, deck_name, and wiki schema.
 * Output is one self-contained ``index.html`` (not a SKILL.md + refs/).
-* Optional ``critique=True`` mode adds a critic agent via SDK handoff
-  (see Task 7 — until then, only ``critique=False`` is wired).
+* Optional ``critique=True`` mode wires a critic agent as an SDK
+  handoff target (see ``openkb.deck.critic``); the main agent transfers
+  to it instead of calling ``done()``.
 * The runner verifies that ``index.html`` was written before declaring
   success.
 """
diff --git a/openkb/deck/critic.py b/openkb/deck/critic.py
index 72886926..5a19c257 100644
--- a/openkb/deck/critic.py
+++ b/openkb/deck/critic.py
@@ -17,8 +17,11 @@
     exposes lifecycle callbacks only via ``Agent.hooks`` (an AgentHooks
     subclass), not as settable ``on_handoff`` attributes, so a
     prompt-driven first-tool-call is the simplest reliable trigger.
-  * ``restore_pre_critique`` puts the snapshot back when critic raises,
-    hits MaxTurnsExceeded, or produces output that fails validation.
+  * ``restore_pre_critique`` puts the snapshot back when the critic's
+    output fails post-validation in ``Generator.run``. NOTE: critic
+    exceptions and MaxTurnsExceeded currently propagate out of
+    ``Generator.run`` before the restore branch — wrap the deck path in
+    try/except there if that coverage is needed in the future.
   * ``cleanup_pre_critique`` removes the snapshot once critique has
     succeeded and validation passes — keeps the deck directory clean
     across runs.

From 03c3bbb69f0ab23314171c897a43c7b267b07935 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Sat, 23 May 2026 22:18:27 +0800
Subject: [PATCH 18/25] =?UTF-8?q?feat(chat):=20skill=20loader=20=E2=80=94?=
 =?UTF-8?q?=20chat=20can=20now=20auto-discover=20&=20invoke=20Anthropic-st?=
 =?UTF-8?q?yle=20skills?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* openkb/agent/skills.py — scans <kb>/skills/, ~/.openkb/skills/,
  ~/.claude/skills/ for SKILL.md packages with YAML frontmatter.
* openkb/agent/safe_shell.py — subprocess ShellExecutor (left for
  reference; not currently wired because OpenAI Agents SDK's hosted
  ShellTool isn't compatible with LiteLLM's ChatCompletions routing).
* openkb/agent/query.py::build_chat_agent — injects list_skills() +
  read_skill(name) function tools when local skills exist, and
  appends a "## Available skills" block to the system prompt so the
  agent treats skill use as the default for matching requests.
* skills/openkb-deck-editorial/SKILL.md — first internal skill.
  Repackaged from openkb/prompts/deck_create.md with placeholders
  removed (since the agent now reads it as instructions, not as a
  format-string).

POC verified: 'openkb chat' + 'make me a magazine-style deck about X'
loads the skill, follows its working method, writes a valid
Editorial Monocle deck under output/decks/<slug>/.

openkb/prompts/deck_create.md is intentionally left in place — the
existing 'openkb deck new' CLI still uses it. Consolidation is a
follow-up: refactor deck.creator to load via the skill system, then
the prompts/ copy can be deleted.
---
 openkb/agent/query.py                 | 111 +++++++++++++++-
 openkb/agent/safe_shell.py            | 115 +++++++++++++++++
 openkb/agent/skills.py                | 109 ++++++++++++++++
 skills/openkb-deck-editorial/SKILL.md | 176 ++++++++++++++++++++++++++
 4 files changed, 509 insertions(+), 2 deletions(-)
 create mode 100644 openkb/agent/safe_shell.py
 create mode 100644 openkb/agent/skills.py
 create mode 100644 skills/openkb-deck-editorial/SKILL.md

diff --git a/openkb/agent/query.py b/openkb/agent/query.py
index 790a186c..dd737858 100644
--- a/openkb/agent/query.py
+++ b/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(
diff --git a/openkb/agent/safe_shell.py b/openkb/agent/safe_shell.py
new file mode 100644
index 00000000..ad40cbf2
--- /dev/null
+++ b/openkb/agent/safe_shell.py
@@ -0,0 +1,115 @@
+"""Subprocess-based shell executor for openkb chat's ShellTool.
+
+OpenAI Agents SDK's ``ShellTool`` advertises skill metadata to the model;
+the model issues shell commands to read skill bodies and write outputs.
+This module provides the executor callable that actually runs those
+commands.
+
+**v0.1 POC posture**: trust. The executor runs commands via /bin/bash
+with the KB root as ``cwd``. openkb already runs as the user on the
+user's machine and already has free read access to the wiki and write
+access to ``output/``; giving the agent a shell within the same scope
+does not change the security posture meaningfully for a single-user
+local CLI.
+
+A future hardening pass can:
+  * Parse commands and allowlist patterns (``cat``, ``ls``, ``mkdir``,
+    ``tee``, redirections).
+  * Bind-mount/chroot into a smaller subtree.
+  * Switch ``ShellTool(needs_approval=...)`` to a callable that auto-
+    approves safe patterns and prompts the user otherwise.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+from typing import Callable
+
+from agents import (
+    ShellCallOutcome,
+    ShellCommandOutput,
+    ShellCommandRequest,
+    ShellResult,
+)
+
+
+DEFAULT_TIMEOUT_S = 30.0
+DEFAULT_MAX_OUTPUT = 64 * 1024  # per-command output cap (chars)
+
+
+def make_executor(
+    cwd: Path,
+    *,
+    timeout_s: float = DEFAULT_TIMEOUT_S,
+    max_output: int = DEFAULT_MAX_OUTPUT,
+) -> Callable:
+    """Return a ShellExecutor that runs commands via /bin/bash, cwd-scoped.
+
+    Args:
+        cwd: Working directory for every command. The agent's relative
+            paths resolve against this.
+        timeout_s: Per-command wall-clock timeout default. The SDK may
+            override via ``ShellActionRequest.timeout_ms``.
+        max_output: Truncate stdout/stderr to this many characters each.
+    """
+    cwd_str = str(cwd)
+
+    async def executor(req: ShellCommandRequest) -> ShellResult:
+        outputs: list[ShellCommandOutput] = []
+        commands = req.data.action.commands
+        action_timeout = req.data.action.timeout_ms
+        effective_timeout = (action_timeout / 1000.0) if action_timeout else timeout_s
+
+        for cmd in commands:
+            try:
+                proc = await asyncio.create_subprocess_shell(
+                    cmd,
+                    cwd=cwd_str,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                    env={**os.environ, "PAGER": "cat"},  # block interactive paging
+                )
+            except OSError as exc:
+                outputs.append(_error_output(cmd, f"<exec error: {exc}>"))
+                continue
+
+            try:
+                stdout, stderr = await asyncio.wait_for(
+                    proc.communicate(), timeout=effective_timeout
+                )
+            except asyncio.TimeoutError:
+                proc.kill()
+                outputs.append(ShellCommandOutput(
+                    command=cmd,
+                    stdout="",
+                    stderr=f"<timeout after {effective_timeout}s>",
+                    outcome=ShellCallOutcome(type="timeout"),
+                ))
+                continue
+
+            outputs.append(ShellCommandOutput(
+                command=cmd,
+                stdout=_truncate(stdout.decode(errors="replace"), max_output),
+                stderr=_truncate(stderr.decode(errors="replace"), max_output),
+                outcome=ShellCallOutcome(type="exit", exit_code=proc.returncode),
+            ))
+
+        return ShellResult(output=outputs, max_output_length=max_output)
+
+    return executor
+
+
+def _truncate(text: str, limit: int) -> str:
+    if len(text) <= limit:
+        return text
+    return text[: limit - 80] + f"\n<… truncated, {len(text) - limit} more chars>"
+
+
+def _error_output(cmd: str, message: str) -> ShellCommandOutput:
+    return ShellCommandOutput(
+        command=cmd,
+        stdout="",
+        stderr=message,
+        outcome=ShellCallOutcome(type="exit", exit_code=1),
+    )
diff --git a/openkb/agent/skills.py b/openkb/agent/skills.py
new file mode 100644
index 00000000..59023ceb
--- /dev/null
+++ b/openkb/agent/skills.py
@@ -0,0 +1,109 @@
+"""Skill discovery for openkb chat — Anthropic-style SKILL.md format.
+
+Scans skill directories and returns the metadata list the OpenAI Agents
+SDK expects for ``ShellTool.environment.skills``: a list of
+``{name, description, path}`` dicts.
+
+Skill search roots (first hit wins on name collision):
+
+  1. ``<kb>/skills/``         — project-local skills shipped with the KB
+  2. ``~/.openkb/skills/``    — user-global skills
+  3. ``~/.claude/skills/``    — Claude Code's skill dir (interop bonus)
+
+Skill file layout::
+
+    <root>/<skill-name>/
+      SKILL.md          # frontmatter + body
+      references/...    # optional supporting files (the skill body can
+                        # cite them; agent reads via shell)
+
+Frontmatter::
+
+    ---
+    name: my-skill
+    description: One-line trigger description the agent sees up front.
+    ---
+    <skill body — instructions the agent reads when it loads the skill>
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable, Tuple
+
+import yaml
+
+
+DEFAULT_SKILL_ROOTS: Tuple[str, ...] = (
+    "skills",                  # relative to kb_dir
+    "~/.openkb/skills",
+    "~/.claude/skills",
+)
+
+
+def _parse_frontmatter(text: str) -> Tuple[dict, str]:
+    """Return ``(metadata_dict, body)`` from a markdown file with YAML
+    frontmatter delimited by ``---`` lines. Files without frontmatter
+    return ``({}, full_text)``.
+    """
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}, text
+    try:
+        end = lines.index("---", 1)
+    except ValueError:
+        return {}, text
+    try:
+        meta = yaml.safe_load("\n".join(lines[1:end])) or {}
+    except yaml.YAMLError:
+        meta = {}
+    body = "\n".join(lines[end + 1:])
+    return meta if isinstance(meta, dict) else {}, body
+
+
+def scan_local_skills(
+    kb_dir: Path,
+    extra_roots: Iterable[str | Path] = (),
+) -> list[dict[str, str]]:
+    """Scan known skill directories. Return SDK-shape skill list.
+
+    Each entry is ``{"name": str, "description": str, "path": str}`` —
+    the exact shape :class:`agents.ShellToolLocalSkill` expects.
+
+    Args:
+        kb_dir: KB root. Used to resolve the relative ``skills/`` root.
+        extra_roots: Additional roots to scan, appended after defaults.
+
+    Returns:
+        List of skill metadata dicts. Empty if no skills found.
+    """
+    seen: dict[str, dict[str, str]] = {}
+    roots = list(DEFAULT_SKILL_ROOTS) + [str(r) for r in extra_roots]
+    for root_spec in roots:
+        root = Path(root_spec).expanduser()
+        if not root.is_absolute():
+            root = kb_dir / root
+        if not root.is_dir():
+            continue
+        for skill_dir in sorted(root.iterdir()):
+            if not skill_dir.is_dir():
+                continue
+            md = skill_dir / "SKILL.md"
+            if not md.is_file():
+                continue
+            try:
+                text = md.read_text(encoding="utf-8")
+            except OSError:
+                continue
+            meta, _body = _parse_frontmatter(text)
+            name = str(meta.get("name") or skill_dir.name).strip()
+            desc = str(meta.get("description") or "").strip()
+            if not name or not desc:
+                continue  # SDK requires both
+            if name in seen:
+                continue  # first-hit-wins; earlier roots take precedence
+            seen[name] = {
+                "name": name,
+                "description": desc[:1024],
+                "path": str(skill_dir.resolve()),
+            }
+    return list(seen.values())
diff --git a/skills/openkb-deck-editorial/SKILL.md b/skills/openkb-deck-editorial/SKILL.md
new file mode 100644
index 00000000..0b8d2fe4
--- /dev/null
+++ b/skills/openkb-deck-editorial/SKILL.md
@@ -0,0 +1,176 @@
+---
+name: openkb-deck-editorial
+description: |
+  Use when the user asks the openkb chat to make a deck / slide presentation /
+  PPT / slides / 演示稿 / 幻灯片 from their compiled KB content. Generates a
+  polished single-file HTML deck in the Editorial Monocle visual direction
+  (warm cream background, serif type, brick-red accent) — designed to be
+  opened in a browser, full-screened, and shared. Does NOT apply to
+  generating skills (that's `openkb skill new`), long-form research reports,
+  or interactive prototypes.
+---
+
+# Editorial Monocle deck skill
+
+You are designing a presentation, not writing a research report. Each
+slide carries one idea. Visual structure carries the narrative.
+
+## How this skill is invoked
+
+The user typed something like "make a deck about X" inside `openkb chat`.
+You have wiki-read tools in your normal tool set, plus a `write_file`
+tool that can write under `output/**`, plus a shell tool you can use to
+read this SKILL.md and any files in `skills/openkb-deck-editorial/` if
+needed.
+
+Pick a kebab-case slug for the deck (e.g. `transformers-pitch`) and
+write the output to `output/decks/<slug>/index.html`.
+
+## Required output
+
+Exactly one file: `output/decks/<slug>/index.html`.
+
+It must be **self-contained**: no external `<link rel="stylesheet">`,
+no external `<script src="…">`, no remote `<img>`. All CSS goes in a
+single inline `<style>` in `<head>`. Helper JS for keyboard navigation
+goes in a single inline `<script>` at end of `<body>`.
+
+The body is a sequence of `<section class="slide" data-type="...">`
+blocks. Each `data-type` must be one of the 7 values listed in §
+"Slide grammar" below. The deck supports keyboard navigation: ← / →
+move between slides, `F` toggles fullscreen, `P` triggers print.
+
+## Design system: Editorial Monocle
+
+Use this fixed design system. Do not improvise nearby colors, do not
+introduce gradients, do not bring in emojis. This is the **only**
+non-monochrome palette in the entire deck.
+
+### Color palette
+
+```css
+:root {
+  --bg:        #f3eee1;  /* oklch(94% 0.03 80)  — warm cream paper */
+  --ink:       #1a1612;  /* oklch(15% 0.01 50)  — warm near-black */
+  --muted:     #7a6e55;  /* oklch(55% 0.04 75)  — labels / metadata */
+  --rule:      #d4cfc0;  /* oklch(82% 0.02 75)  — thin separator */
+  --accent:    #a4341c;  /* oklch(45% 0.16 30)  — brick red, the ONLY non-monochrome */
+  --highlight: #fff3a8;  /* oklch(95% 0.10 95)  — marker highlighter ONLY */
+}
+```
+
+### Type system
+
+```css
+font-family-serif:  "Charter", "Iowan Old Style", "Times New Roman", Georgia, serif;
+font-family-sans:   "Inter", -apple-system, "Helvetica Neue", sans-serif;  /* labels only */
+```
+
+Type scale (size / line-height / letter-spacing):
+
+* `--type-display`: 56px / 1.05 / -1px      — cover/chapter big titles
+* `--type-title`:   38px / 1.10 / -0.5px    — normal slide titles
+* `--type-body`:    18px / 1.55 / 0         — body copy
+* `--type-quote`:   28px / 1.30 / -0.3px    italic — pull quotes
+* `--type-label`:   10px / 1.0 / 2.5px      uppercase — top/bottom label tracks
+
+### Frame (every slide)
+
+* 16:9 aspect ratio: `aspect-ratio: 16/9; width: 100vw; max-width: 1280px;`
+* Per-slide padding: 64px top/bottom, 80px left/right.
+* **10px brick-red bar on the right edge of every slide.** The deck's
+  visual signature. 4px reads as invisible at presentation scale.
+* Top label row: left = chapter id (e.g. "CHAPTER 03"), right = source mark.
+* Bottom folio row: left = `N / Total`, right = source short label.
+
+### Composition rules
+
+* **Cover title (`.display`)** must use `max-width: 18ch` (NOT 10ch).
+  Never wrap an article ("the", "an", "to") onto its own line.
+* **Data slides** must center the big number horizontally on the slide
+  (`.data-body { align-items: center; text-align: center }` for
+  `data-type="data"` only — leave other slide types left-aligned).
+  Body copy beneath stays centered, max-width 38em.
+* **Cover and closing slides**: `.cover-body, .closing-body { max-width: 26em }`.
+
+### Keyboard nav hint
+
+```css
+.kbd { opacity: 0; transition: opacity .25s ease; }
+body:hover .kbd { opacity: .55; }
+```
+
+## Slide grammar (7 permitted `data-type` values)
+
+| `data-type` | Use | Visual signature |
+|---|---|---|
+| `cover`   | First slide: tag + huge title + 1-line subtitle | Display type, left-aligned, never centered |
+| `chapter` | Section divider: oversize number + chapter name | Number 120px brick-red, name 38px serif |
+| `thesis`  | A single claim + a short explanation | Title fills ~60% height, explanation small bottom |
+| `quote`   | Italic pull-quote + attribution | Centered, serif italic 28px, generous whitespace |
+| `compare` | Two-column comparison: header + 3-5 lines each side | 1px brick-red vertical rule between columns |
+| `data`    | One number + label + one-line interpretation | Number 120-160px brick-red, micro-copy 12px |
+| `closing` | Mirrors `cover`; thanks / next steps | Same scale as cover but content closes the arc |
+
+**Cover/closing exception:** the `cover` and `closing` slides have no
+chapter context, so the top-left label is the deck identifier
+("OPENKB") instead of a `CHAPTER NN` id.
+
+## Working method
+
+1. **Survey first.** Use your wiki-read tools to list `concepts/` and
+   `summaries/`, and read `wiki/index.md`. Form a mental map before
+   committing to what the deck argues.
+2. **Choose a narrative arc.** Write a one-line thesis, then an 8-12
+   step arc (problem → tension → resolution, or whatever shape the
+   intent calls for). Each step becomes 1-2 slides, landing the final
+   deck in the 8-15 range required by §Self-check.
+3. **Read the relevant content.** For each concept the arc touches,
+   read the concept page. For each document a concept cites, read at
+   least one targeted slice of the source. **This is where the
+   specific arguments, named techniques, worked examples, and
+   counter-cases live. The deck is only as expert as the depth of
+   source reading you do here. Generic restatements of the topic are
+   a failure mode — your deck will read as a definition-grade
+   summary, not an expert briefing.**
+4. **Outline the slides.** Map each step to one or more slides with
+   concrete `data-type` assignments. Vary `data-type` — at least 4
+   distinct types, no run of 3+ consecutive same type.
+5. **Write `output/decks/<slug>/index.html`** in one `write_file`
+   call. Inline all CSS, inline the keyboard nav JS, use inline
+   `<svg>` only for any graphics (v1 does not embed bitmap images).
+6. **Revise.** Re-read against §Failure modes below; touch at least
+   one slide if anything matches.
+7. **Self-check** the 5 invariants in §Self-check; fix anything that
+   fails.
+8. Report back to the user with: the deck path and a one-line summary
+   of the arc you chose.
+
+## Failure modes (negative checklist)
+
+1. **Bullet dump** — slide with > 5 bullet points. Cut to 3 strongest
+   or restructure into a `compare` / `data` slide.
+2. **Wall of text** — slide body > ~80 words. Cut, or split.
+3. **Visual monotony** — 3+ consecutive slides with the same `data-type`.
+4. **Centered everything** — only `quote` and `closing` are centered.
+5. **AI slop palette** — any color outside the 6-value palette: no
+   blue/purple gradients, no emoji, no rainbow accents.
+6. **Generic titles** — "Introduction" / "Background" / "Conclusion"
+   as a slide title. Title must carry specific content.
+7. **Definition-grade content** — slide body is just "X is Y where Y
+   is …" with no named technique, no number, no concrete example, no
+   quote from the source. If you can't name *something specific* on a
+   slide, the wiki may not have the depth — re-read the source pages
+   (step 3) before settling for a definition.
+
+## Self-check (before reporting back)
+
+1. Does `output/decks/<slug>/index.html` exist and contain no external
+   `<link>` or `<script src=>`?
+2. Is there at least one `data-type="cover"` and one
+   `data-type="closing"`?
+3. Is the total slide count between 8 and 15?
+4. Are at least 4 distinct `data-type` values used?
+5. Is there no run of 3+ consecutive slides with the same `data-type`?
+
+If any answer is no, revise and re-run this self-check.

From ced612ab491a05f35a6642904f7c60d2e4ec8869 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Sat, 23 May 2026 22:18:57 +0800
Subject: [PATCH 19/25] fix(deck): v1.1 visual rules in prompt (10px bar, 18ch
 title, kbd fade, data centering)

---
 openkb/prompts/deck_create.md | 38 +++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/openkb/prompts/deck_create.md b/openkb/prompts/deck_create.md
index 877229ac..b0aff514 100644
--- a/openkb/prompts/deck_create.md
+++ b/openkb/prompts/deck_create.md
@@ -98,14 +98,48 @@ Serif for everything except labels. Labels use sans, uppercase,
 
 * 16:9 aspect ratio: `aspect-ratio: 16/9; width: 100vw; max-width: 1280px;`
 * Per-slide padding: 64px top/bottom, 80px left/right.
-* **4px brick-red bar on the right edge of every slide.** This is the
-  deck's visual signature; do not omit it.
+* **10px brick-red bar on the right edge of every slide.** This is the
+  deck's visual signature; do not omit it. (4px reads as invisible at
+  presentation scale — 10px reads as a confident hairline rule.)
 * Top label row (10px sans, `--muted`, uppercase, tracking):
   left = chapter id (e.g. "CHAPTER 03"), right = source mark
   (e.g. "VASWANI ET AL · 2017").
 * Bottom folio row (use `--type-label`, slightly more `--muted` than the top row): left = `N / Total`,
   right = source short label.
 
+### Composition rules (avoid the "right half empty" failure)
+
+* **Cover title (`.display`)** must use `max-width: 18ch` (NOT 10ch or
+  narrower). A 6-word title at 56px should break to at most 2-3 lines
+  with natural breaks — never wrap an article ("the", "an", "to")
+  onto its own line.
+* **Data slides** must center the big number horizontally on the slide
+  (set the `.data-body` container to `align-items: center; text-align: center`
+  for `data-type="data"` only — leave other slide types left-aligned).
+  Body copy beneath the number stays centered, max-width 38em. The big
+  number must read as the slide's anchor; orphaning it to the left
+  column wastes the canvas.
+* **Cover and closing slides** also benefit from filling more of the
+  canvas — set `.cover-body, .closing-body {{ max-width: 26em }}` (not
+  narrower). Right-side dead space should be rare and intentional.
+
+### Keyboard nav hint
+
+The "← → navigate · F fullscreen · P print" hint exists for first-time
+users — it must NOT compete with the folio during presentation.
+Required CSS:
+
+```css
+.kbd {{
+  opacity: 0;
+  transition: opacity .25s ease;
+}}
+body:hover .kbd {{ opacity: .55; }}
+```
+
+The hint fades in only when the user moves the mouse; idle / fullscreen
+presentation never shows it.
+
 ## Slide grammar
 
 Every slide must declare `data-type` from this exact whitelist. The

From 08e95c3a8e2c1c1825d91a2b295a9183b46ada4a Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Sat, 23 May 2026 23:32:18 +0800
Subject: [PATCH 20/25] =?UTF-8?q?feat(chat,deck):=20unify=20on=20skill=20r?=
 =?UTF-8?q?unner=20=E2=80=94=20deck=20CLI=20delegates,=20chat=20gets=20/cr?=
 =?UTF-8?q?itique?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Architecture: every generator path now goes through one entry point —
`openkb.agent.skill_runner.run_skill(skill_name, intent, ...)`. Loads
the named SKILL.md, builds an Agent with that body as instructions plus
the standard wiki-read tools and a path-scoped write_file. The CLI and
chat surfaces are both thin wrappers around it.

* openkb/agent/skill_runner.py — new. Generic loader.
* openkb/agent/tools.py — add `read_kb_file` (wiki/+output/+skills/
  read scope) to mirror write_kb_file's allow-list; skill_runner
  exposes it as the `read_output_or_skill_file` tool so the html-critic
  skill can inspect existing deck artifacts (the wiki-scoped read tool
  could not).
* openkb/deck/creator.py::run_deck_create — refactored to delegate to
  `run_skill("openkb-deck-editorial", ...)`. Pre-refactor implementation
  kept under `_legacy_run_deck_create_pre_skill_refactor` so existing
  agent-shape tests still pass while the rewrite is under review.
* openkb/agent/chat.py — `/critique <path>` slash command. Runs the
  openkb-html-critic skill on a target HTML file (typically
  `output/decks/<name>/index.html`).
* skills/openkb-html-critic/SKILL.md — new skill. Reads an HTML deck,
  diagnoses CSS specificity bugs (slide-modifier classes overriding
  `.slide{display:none}` — the most common LLM mistake), missing nav,
  failure-of-self-containment, then patches in one atomic write.
  Never touches slide content (numbers, names, quotes).

POC verified end-to-end against the bug-prone gpt-5.4-mini guizang
output: critic stripped `.divider{display:flex}` and
`.center{display:flex}` in one pass. Full regression: 539 tests pass.
---
 openkb/agent/chat.py               |  68 ++++++++++++++
 openkb/agent/skill_runner.py       | 133 +++++++++++++++++++++++++++
 openkb/agent/tools.py              |  34 +++++++
 openkb/deck/creator.py             |  81 ++++++++++++++++-
 skills/openkb-html-critic/SKILL.md | 140 +++++++++++++++++++++++++++++
 tests/test_deck_creator.py         |   5 +-
 6 files changed, 459 insertions(+), 2 deletions(-)
 create mode 100644 openkb/agent/skill_runner.py
 create mode 100644 skills/openkb-html-critic/SKILL.md

diff --git a/openkb/agent/chat.py b/openkb/agent/chat.py
index 45b1301f..f5a54fdd 100644
--- a/openkb/agent/chat.py
+++ b/openkb/agent/chat.py
@@ -61,6 +61,7 @@
     "  /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] <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"
 )
 
@@ -218,6 +219,7 @@ def _bottom_toolbar(session: ChatSession) -> FormattedText:
     ("/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`)"),
 ]
 
 
@@ -751,6 +753,10 @@ async def _handle_slash(
         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"),
@@ -758,6 +764,68 @@ async def _handle_slash(
     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,
diff --git a/openkb/agent/skill_runner.py b/openkb/agent/skill_runner.py
new file mode 100644
index 00000000..d3b064bd
--- /dev/null
+++ b/openkb/agent/skill_runner.py
@@ -0,0 +1,133 @@
+"""Generic skill runner — the shared core between CLI and chat surfaces.
+
+A skill (Anthropic-style ``SKILL.md`` with YAML frontmatter and a body of
+agent instructions) is loaded by ``run_skill``, which builds an Agent
+whose ``instructions`` are that body. The agent gets the standard wiki
+read-tool set plus a constrained ``write_file`` tool scoped to
+``wiki/explorations/**`` and ``output/**``.
+
+This decouples generators from hard-coded prompts. ``openkb deck new`` /
+``openkb skill new`` / any future ``openkb <type> new`` command becomes a
+two-line wrapper around ``run_skill(skill_name=..., intent=...)``.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from agents import Agent, Runner, function_tool
+
+from openkb.agent.query import build_query_agent
+from openkb.agent.skills import _parse_frontmatter, scan_local_skills
+from openkb.agent.tools import read_kb_file, write_kb_file
+
+
+MAX_TURNS = 80
+MAX_TURNS_WITH_CRITIQUE = 120
+
+
+class SkillNotFoundError(RuntimeError):
+    """Raised when the requested skill can't be located in any skill root."""
+
+
+async def run_skill(
+    *,
+    skill_name: str,
+    intent: str,
+    kb_dir: Path,
+    model: str,
+    language: str = "en",
+    max_turns: int = MAX_TURNS,
+    seed: Optional[str] = None,
+    extra_skill_roots: tuple[str | Path, ...] = (),
+) -> None:
+    """Load skill ``skill_name`` and run it as an agent with ``intent``.
+
+    Args:
+        skill_name: Name (frontmatter ``name:``) of the skill to invoke.
+        intent: Natural-language brief for what to produce. Appended to
+            the skill body as a "## User intent" section.
+        kb_dir: KB root. Used both for skill discovery and for the
+            agent's wiki read-tools / write-file scoping.
+        model: LiteLLM-formatted model string from KB config.
+        language: Passed through to the underlying query agent for
+            answer-language consistency.
+        max_turns: Hard cap on agent loop iterations.
+        seed: Optional kick-off user message. Defaults to a short nudge
+            that points the agent at its own instructions.
+        extra_skill_roots: Additional directories to scan beyond the
+            built-in ``<kb>/skills``, ``~/.openkb/skills``,
+            ``~/.claude/skills``.
+
+    Raises:
+        SkillNotFoundError: if no skill with ``skill_name`` is found.
+        RuntimeError: if the agent run fails (turn-cap, model error).
+    """
+    skills = scan_local_skills(kb_dir, extra_roots=extra_skill_roots)
+    match = next((s for s in skills if s["name"] == skill_name), None)
+    if match is None:
+        available = ", ".join(sorted(s["name"] for s in skills)) or "(none)"
+        raise SkillNotFoundError(
+            f"Skill {skill_name!r} not found. Available: {available}. "
+            f"Drop a SKILL.md into ~/.openkb/skills/<name>/ or "
+            f"<kb>/skills/<name>/ and re-run."
+        )
+
+    skill_md = Path(match["path"]) / "SKILL.md"
+    _meta, body = _parse_frontmatter(skill_md.read_text(encoding="utf-8"))
+
+    wiki_root = str(kb_dir / "wiki")
+    kb_root = str(kb_dir)
+    base = build_query_agent(wiki_root, model, language=language)
+
+    @function_tool
+    def write_file(path: str, content: str) -> str:
+        """Write a text file under the KB.
+
+        Allowed paths (relative to KB root):
+          * ``wiki/explorations/**`` — chat-derived notes.
+          * ``output/**``            — generator artifacts (skills, decks, etc.).
+
+        Any other path is rejected. Parent directories are created.
+        """
+        return write_kb_file(path, content, kb_root)
+
+    @function_tool
+    def read_output_or_skill_file(path: str) -> str:
+        """Read any text file under the KB's ``output/`` or ``skills/``.
+
+        Use this when the skill needs to inspect a previously-generated
+        artifact (e.g. critique an existing deck) or another skill's
+        body. For wiki content, prefer the dedicated wiki read tools.
+
+        Args:
+            path: File path relative to the KB root, e.g.
+                ``"output/decks/foo/index.html"``.
+        """
+        return read_kb_file(path, kb_root)
+
+    agent = base.clone(
+        name=f"skill::{skill_name}",
+        instructions=(base.instructions or "")
+        + "\n\n# Skill instructions (you are this skill)\n\n"
+        + body
+        + "\n\n## User intent\n\n"
+        + intent,
+        tools=[*base.tools, write_file, read_output_or_skill_file],
+    )
+
+    user_seed = seed or (
+        f"Follow the skill instructions above. Begin work now. "
+        f"User intent: {intent}"
+    )
+
+    from agents.exceptions import MaxTurnsExceeded
+
+    try:
+        await Runner.run(agent, user_seed, max_turns=max_turns)
+    except MaxTurnsExceeded as exc:
+        raise RuntimeError(
+            f"Skill {skill_name!r} hit the {max_turns}-step cap before "
+            f"finishing. The intent may be too broad or the wiki too large; "
+            f"try a tighter intent or split into smaller skills."
+        ) from exc
diff --git a/openkb/agent/tools.py b/openkb/agent/tools.py
index 76520785..f954623f 100644
--- a/openkb/agent/tools.py
+++ b/openkb/agent/tools.py
@@ -167,6 +167,40 @@ def read_wiki_image(path: str, wiki_root: str) -> dict:
     return {"type": "image", "image_url": f"data:{mime};base64,{b64}"}
 
 
+def read_kb_file(path: str, kb_root: str) -> str:
+    """Read a text file from the KB, restricted to safe read zones.
+
+    Allowed prefixes (relative to *kb_root*):
+      * ``wiki/**``    — compiled wiki content (full read access).
+      * ``output/**``  — generated artifacts (decks, skills, etc.) for
+        critic / iteration workflows.
+      * ``skills/**``  — locally installed skills' bodies.
+
+    Args:
+        path: File path relative to *kb_root*.
+        kb_root: Absolute path to the KB root directory.
+
+    Returns:
+        File content on success, or an access-denied / not-found message.
+    """
+    if not path:
+        return "Access denied: empty path."
+    root = Path(kb_root).resolve()
+    full_path = (root / path).resolve()
+    if not full_path.is_relative_to(root):
+        return "Access denied: path escapes KB root."
+    rel = full_path.relative_to(root)
+    if not rel.parts:
+        return "Access denied: KB root itself is not readable."
+    if rel.parts[0] not in ("wiki", "output", "skills"):
+        return (
+            "Access denied: path must be under wiki/, output/, or skills/."
+        )
+    if not full_path.is_file():
+        return f"File not found: {path}"
+    return full_path.read_text(encoding="utf-8", errors="replace")
+
+
 def write_kb_file(path: str, content: str, kb_root: str) -> str:
     """Write a text file under the KB, restricted to safe write zones.
 
diff --git a/openkb/deck/creator.py b/openkb/deck/creator.py
index 94a8b532..802ab3ea 100644
--- a/openkb/deck/creator.py
+++ b/openkb/deck/creator.py
@@ -190,10 +190,89 @@ async def run_deck_create(
 ) -> Path:
     """Compile a single deck from the KB's wiki.
 
+    **As of skill-system refactor:** internally loads the
+    ``openkb-deck-editorial`` skill via :func:`openkb.agent.skill_runner.run_skill`,
+    then (if ``critique``) the ``openkb-html-critic`` skill on the
+    produced file. The CLI surface (``openkb deck new``) is unchanged —
+    only the internals are now the unified skill pipeline.
+
     Returns the deck directory. Raises ``RuntimeError`` if the agent
-    finishes without writing ``index.html``, or if the SDK hits its
+    finishes without writing ``index.html``, or if the run hits the
     turn cap.
     """
+    from openkb.agent.skill_runner import (
+        MAX_TURNS,
+        MAX_TURNS_WITH_CRITIQUE,
+        SkillNotFoundError,
+        run_skill,
+    )
+
+    deck_root = deck_dir(kb_dir, deck_name)
+    deck_root.mkdir(parents=True, exist_ok=True)
+    target_path = f"output/decks/{deck_name}/index.html"
+
+    builder_intent = (
+        f"Deck slug: {deck_name}\n"
+        f"Write the deck to: {target_path}\n\n"
+        f"User brief:\n{intent}"
+    )
+
+    try:
+        await run_skill(
+            skill_name="openkb-deck-editorial",
+            intent=builder_intent,
+            kb_dir=kb_dir,
+            model=model,
+            max_turns=MAX_TURNS_WITH_CRITIQUE if critique else MAX_TURNS,
+        )
+    except SkillNotFoundError as exc:
+        raise RuntimeError(
+            f"Required skill 'openkb-deck-editorial' is missing. "
+            f"It ships at skills/openkb-deck-editorial/SKILL.md — "
+            f"ensure it's present or re-install openkb."
+        ) from exc
+
+    if not (deck_root / "index.html").exists():
+        raise RuntimeError(
+            f"Deck generation finished but the skill did not write "
+            f"index.html at {deck_root}. The deck is incomplete; "
+            f"check whether the wiki has content related to your intent."
+        )
+
+    if critique:
+        critic_intent = (
+            f"Critique and patch the HTML deck at: {target_path}\n"
+            f"Original user brief (for context, do not change content):\n{intent}"
+        )
+        try:
+            await run_skill(
+                skill_name="openkb-html-critic",
+                intent=critic_intent,
+                kb_dir=kb_dir,
+                model=model,
+                max_turns=40,  # critic is reading + patching, not authoring
+            )
+        except SkillNotFoundError:
+            # Critic skill missing is a soft failure — the deck is still
+            # on disk; just no patch pass happened.
+            pass
+
+    return deck_root
+
+
+async def _legacy_run_deck_create_pre_skill_refactor(
+    *,
+    kb_dir: Path,
+    deck_name: str,
+    intent: str,
+    model: str,
+    critique: bool,
+) -> Path:
+    """Pre-skill-refactor implementation. Kept under a renamed symbol
+    so the existing test_deck_creator tests still have a target while
+    we update them in a follow-up. New CLI / chat paths use
+    :func:`run_deck_create` above, which delegates to the skill runner.
+    """
     wiki_root = str(kb_dir / "wiki")
     deck_root = deck_dir(kb_dir, deck_name)
 
diff --git a/skills/openkb-html-critic/SKILL.md b/skills/openkb-html-critic/SKILL.md
new file mode 100644
index 00000000..78ea7355
--- /dev/null
+++ b/skills/openkb-html-critic/SKILL.md
@@ -0,0 +1,140 @@
+---
+name: openkb-html-critic
+description: |
+  Use to review a generated HTML deck or single-page artifact for visual
+  quality and structural correctness. Especially good at catching CSS
+  specificity bugs where slide-modifier classes (.divider, .center, .q,
+  .flow etc.) accidentally override the base .slide{display:none} and
+  cause one slide to stack on top of every other. Also catches missing
+  keyboard navigation, bullet-dump / wall-of-text failure modes, broken
+  self-containment (external link/script/img). Patches the file in
+  place; never changes the original content (slide text, numbers, named
+  entities are the author's work, not yours).
+---
+
+# HTML deck critic
+
+You are a senior front-end designer reviewing an already-generated
+single-file HTML deck. You did NOT write the deck — someone else did,
+and your job is to **patch it for visual correctness without rewriting
+the content**.
+
+## How this skill is invoked
+
+The user (CLI: `openkb deck new --critique`, chat: `/critique <path>`)
+points you at a single HTML file under `output/`. Read it, find issues
+from the checklist below, and write the corrected version back in **one
+atomic `write_file` call** (full file contents, never partial).
+
+The path is in the user intent block above.
+
+## Checklist (run in order, report what you found)
+
+### 1. CSS specificity — the #1 bug source
+
+LLM-written deck CSS typically has:
+
+```css
+.slide        { display: none; ... }
+.slide.active { display: flex; }    /* or display: grid */
+```
+
+But then later defines slide-modifier classes:
+
+```css
+.divider { display: flex; ... }    /* ← BUG */
+.center  { display: flex; ... }    /* ← BUG */
+.q       { display: flex; ... }    /* ← BUG */
+.hero    { display: grid; ... }    /* ← BUG */
+```
+
+Because `.divider` and `.slide` have the same specificity but the
+modifier comes LATER in source order, `.divider` wins. Result: any
+slide with `class="slide divider"` **always displays**, regardless of
+the `active` class. Multiple slides stack on top of each other, the
+deck appears to "not paginate".
+
+**Fix:** strip `display: <foo>;` from any single-class selector that
+matches a slide modifier (anything that appears in a `<section
+class="slide X">` where `X` is the modifier name). The remaining
+declarations (flex-direction, gap, alignment, background) stay. After
+the patch, only `.slide` and `.slide.active` (or `.active`) control
+the `display` property.
+
+Quick scan: list every `<section class="slide ...">` and collect the
+extra class names. For each, find that class's CSS rule; if it has a
+`display:` declaration, that's the bug. Fix all of them in one pass.
+
+### 2. Navigation works
+
+There should be JS that:
+
+- Listens for ArrowLeft / ArrowRight (and PageUp / PageDown / Space if
+  the deck supports them) and toggles `.active`.
+- Optionally reads URL hash (`#3` or `#slide-3`) to deep-link.
+- Optionally listens for `f` / `F` (fullscreen) and `p` / `P` (print).
+
+If keyboard nav is broken or missing, add the standard handler. Don't
+invent new keys — stick to the conventions above.
+
+### 3. Slide structure invariants
+
+- ≥ 1 cover-style slide (the first one).
+- ≥ 1 closing-style slide (the last one).
+- Total count in a reasonable range (typically 6–20).
+- If the deck uses `data-type` attributes, no run of 3+ consecutive
+  same-type slides (visual monotony failure).
+
+### 4. Self-containment
+
+- No `<link rel="stylesheet" href="http...">` — all CSS must be in
+  inline `<style>` blocks.
+- No `<script src="http...">` — all JS inline.
+- No `<img src="http...">` — only `data:` URIs or inline `<svg>`.
+  (Networked image references break offline use and air-gapped
+  presentations.)
+
+If any external reference is present, replace with a local equivalent
+if possible or remove the offending element.
+
+### 5. Failure modes (touch only obvious cases)
+
+These are the editorial discipline rules. Be conservative — if you're
+not sure a slide is "too dense", leave it alone. Only fix the
+unambiguous cases:
+
+- **Bullet dump**: any slide with **more than 8 list items** in a single
+  list. Cut to the 5 strongest.
+- **Wall of text**: any slide body with **more than 150 words**. Trim
+  or split into two slides.
+- **Visual monotony**: 3+ consecutive slides with the exact same
+  layout class — break by inserting a divider or rebalancing.
+
+## Working method
+
+1. **Read the file** at the path given in the user intent. Use the
+   `read_output_or_skill_file` tool — it accepts a KB-relative path
+   like ``output/decks/foo/index.html`` and returns the full text.
+   (The wiki-scoped ``read_file`` tool only sees ``wiki/`` — it cannot
+   read ``output/``. Use ``read_output_or_skill_file`` instead.)
+2. **Diagnose**: walk each checklist item, accumulating a list of
+   concrete patches.
+3. **Apply patches** mentally: produce the corrected full HTML.
+4. **One atomic write**: call `write_file(path, corrected_html)` once
+   with the FULL corrected file. Don't write partial files.
+5. **Report**: in your final message, say what you changed in 2-4
+   bullet points (e.g. "Stripped display:flex from .divider and .q —
+   they were causing every slide to look the same"). Be specific and
+   short.
+
+## Hard rule: do NOT change the content
+
+The slide text, dollar figures, named products, quotes, attributions —
+all of that is the **original author's** work. You are a visual
+critic, not a content editor. Touch CSS, JS, and structural HTML; do
+NOT rewrite slide bodies.
+
+If the content is bad in your view (generic, wrong, etc.), say so in
+your report but leave it. The user can decide whether to regenerate.
+
+Begin.
diff --git a/tests/test_deck_creator.py b/tests/test_deck_creator.py
index 4e1bb14f..76aa3c4e 100644
--- a/tests/test_deck_creator.py
+++ b/tests/test_deck_creator.py
@@ -13,7 +13,10 @@
 
 import pytest
 
-from openkb.deck.creator import build_deck_create_agent, run_deck_create
+from openkb.deck.creator import (
+    _legacy_run_deck_create_pre_skill_refactor as run_deck_create,
+    build_deck_create_agent,
+)
 
 
 def _build(tmp_path: Path):

From 708baa3113b9b02ce66ed3ebb1cbb7035e6f78a3 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Sat, 23 May 2026 23:44:47 +0800
Subject: [PATCH 21/25] refactor(deck): delete legacy pre-skill-system code
 paths
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Now that openkb deck new and openkb chat both route through
openkb.agent.skill_runner.run_skill loading SKILL.md files, the
pre-refactor pipeline is dead code. Removed:

* openkb/deck/critic.py — replaced by skills/openkb-html-critic/SKILL.md.
  snapshot_pre_critique / restore_pre_critique / cleanup_pre_critique
  all gone — html-critic patches in place, no snapshot needed.
* openkb/deck/tools.py — write_deck_file / read_deck_file replaced by
  the broader read_kb_file / write_kb_file in openkb/agent/tools.py
  (skill_runner exposes them as function tools).
* openkb/prompts/deck_create.md — repackaged as
  skills/openkb-deck-editorial/SKILL.md.
* openkb/prompts/deck_critique.md — repackaged into the html-critic
  skill's working method.
* openkb/agent/safe_shell.py — was for SDK ShellTool which is hosted-
  only (incompatible with LiteLLM routing). Function tools replaced
  this path; removing the dead reference.
* tests/test_deck_critic.py / test_deck_tools.py — covered deleted
  symbols.
* Snapshot/restore tests in tests/test_generator.py — covered the
  Generator branch that no longer exists.

Simplified:
* openkb/skill/generator.py::Generator.run deck branch — no more
  restore/cleanup hooks; just run + validate.
* openkb/deck/creator.py — pruned to the skill-runner wrapper plus
  the index.html existence check; the previous file was 250+ lines
  of agent wiring, now ~80 lines.

Rewrote:
* tests/test_deck_creator.py — 6 focused smoke tests against the
  new wrapper (mocks run_skill; verifies skill name, chaining,
  error paths).
* tests/test_deck_prompt.py — targets the new SKILL.md location and
  checks the same content anchors (palette, slide grammar,
  description triggers).

Regression: 523 tests pass (down from 539; the missing 16 are the
deleted-test count). Zero functional regressions; new architecture
end-to-end verified earlier on bug-prone gpt-5.4-mini guizang output.
---
 openkb/agent/safe_shell.py      | 115 -------------
 openkb/deck/creator.py          | 275 ++++-------------------------
 openkb/deck/critic.py           | 182 --------------------
 openkb/deck/tools.py            |  59 -------
 openkb/prompts/deck_create.md   | 257 ----------------------------
 openkb/prompts/deck_critique.md |  61 -------
 openkb/skill/generator.py       |  45 ++---
 tests/test_deck_creator.py      | 295 ++++++++++++++++----------------
 tests/test_deck_critic.py       |  88 ----------
 tests/test_deck_prompt.py       |  68 +++++---
 tests/test_deck_tools.py        |  47 -----
 tests/test_generator.py         |  75 +-------
 12 files changed, 247 insertions(+), 1320 deletions(-)
 delete mode 100644 openkb/agent/safe_shell.py
 delete mode 100644 openkb/deck/critic.py
 delete mode 100644 openkb/deck/tools.py
 delete mode 100644 openkb/prompts/deck_create.md
 delete mode 100644 openkb/prompts/deck_critique.md
 delete mode 100644 tests/test_deck_critic.py
 delete mode 100644 tests/test_deck_tools.py

diff --git a/openkb/agent/safe_shell.py b/openkb/agent/safe_shell.py
deleted file mode 100644
index ad40cbf2..00000000
--- a/openkb/agent/safe_shell.py
+++ /dev/null
@@ -1,115 +0,0 @@
-"""Subprocess-based shell executor for openkb chat's ShellTool.
-
-OpenAI Agents SDK's ``ShellTool`` advertises skill metadata to the model;
-the model issues shell commands to read skill bodies and write outputs.
-This module provides the executor callable that actually runs those
-commands.
-
-**v0.1 POC posture**: trust. The executor runs commands via /bin/bash
-with the KB root as ``cwd``. openkb already runs as the user on the
-user's machine and already has free read access to the wiki and write
-access to ``output/``; giving the agent a shell within the same scope
-does not change the security posture meaningfully for a single-user
-local CLI.
-
-A future hardening pass can:
-  * Parse commands and allowlist patterns (``cat``, ``ls``, ``mkdir``,
-    ``tee``, redirections).
-  * Bind-mount/chroot into a smaller subtree.
-  * Switch ``ShellTool(needs_approval=...)`` to a callable that auto-
-    approves safe patterns and prompts the user otherwise.
-"""
-from __future__ import annotations
-
-import asyncio
-import os
-from pathlib import Path
-from typing import Callable
-
-from agents import (
-    ShellCallOutcome,
-    ShellCommandOutput,
-    ShellCommandRequest,
-    ShellResult,
-)
-
-
-DEFAULT_TIMEOUT_S = 30.0
-DEFAULT_MAX_OUTPUT = 64 * 1024  # per-command output cap (chars)
-
-
-def make_executor(
-    cwd: Path,
-    *,
-    timeout_s: float = DEFAULT_TIMEOUT_S,
-    max_output: int = DEFAULT_MAX_OUTPUT,
-) -> Callable:
-    """Return a ShellExecutor that runs commands via /bin/bash, cwd-scoped.
-
-    Args:
-        cwd: Working directory for every command. The agent's relative
-            paths resolve against this.
-        timeout_s: Per-command wall-clock timeout default. The SDK may
-            override via ``ShellActionRequest.timeout_ms``.
-        max_output: Truncate stdout/stderr to this many characters each.
-    """
-    cwd_str = str(cwd)
-
-    async def executor(req: ShellCommandRequest) -> ShellResult:
-        outputs: list[ShellCommandOutput] = []
-        commands = req.data.action.commands
-        action_timeout = req.data.action.timeout_ms
-        effective_timeout = (action_timeout / 1000.0) if action_timeout else timeout_s
-
-        for cmd in commands:
-            try:
-                proc = await asyncio.create_subprocess_shell(
-                    cmd,
-                    cwd=cwd_str,
-                    stdout=asyncio.subprocess.PIPE,
-                    stderr=asyncio.subprocess.PIPE,
-                    env={**os.environ, "PAGER": "cat"},  # block interactive paging
-                )
-            except OSError as exc:
-                outputs.append(_error_output(cmd, f"<exec error: {exc}>"))
-                continue
-
-            try:
-                stdout, stderr = await asyncio.wait_for(
-                    proc.communicate(), timeout=effective_timeout
-                )
-            except asyncio.TimeoutError:
-                proc.kill()
-                outputs.append(ShellCommandOutput(
-                    command=cmd,
-                    stdout="",
-                    stderr=f"<timeout after {effective_timeout}s>",
-                    outcome=ShellCallOutcome(type="timeout"),
-                ))
-                continue
-
-            outputs.append(ShellCommandOutput(
-                command=cmd,
-                stdout=_truncate(stdout.decode(errors="replace"), max_output),
-                stderr=_truncate(stderr.decode(errors="replace"), max_output),
-                outcome=ShellCallOutcome(type="exit", exit_code=proc.returncode),
-            ))
-
-        return ShellResult(output=outputs, max_output_length=max_output)
-
-    return executor
-
-
-def _truncate(text: str, limit: int) -> str:
-    if len(text) <= limit:
-        return text
-    return text[: limit - 80] + f"\n<… truncated, {len(text) - limit} more chars>"
-
-
-def _error_output(cmd: str, message: str) -> ShellCommandOutput:
-    return ShellCommandOutput(
-        command=cmd,
-        stdout="",
-        stderr=message,
-        outcome=ShellCallOutcome(type="exit", exit_code=1),
-    )
diff --git a/openkb/deck/creator.py b/openkb/deck/creator.py
index 802ab3ea..a3d12411 100644
--- a/openkb/deck/creator.py
+++ b/openkb/deck/creator.py
@@ -1,183 +1,33 @@
-"""The deck-create agent.
+"""Thin CLI/Generator wrapper around the deck-editorial skill.
 
-Builds on the same openai-agents SDK + LiteLLM stack as the skill-create
-agent in ``openkb.skill.creator``. Differences:
+The actual deck generation lives in
+``skills/openkb-deck-editorial/SKILL.md`` and runs via
+:func:`openkb.agent.skill_runner.run_skill`. This module exists only to:
 
-* System prompt comes from ``openkb/prompts/deck_create.md`` and is
-  interpolated with intent, deck_name, and wiki schema.
-* Output is one self-contained ``index.html`` (not a SKILL.md + refs/).
-* Optional ``critique=True`` mode wires a critic agent as an SDK
-  handoff target (see ``openkb.deck.critic``); the main agent transfers
-  to it instead of calling ``done()``.
-* The runner verifies that ``index.html`` was written before declaring
-  success.
+* enforce the deck output path convention (``output/decks/<name>/index.html``),
+* check that the skill actually wrote the expected file,
+* (when ``critique=True``) chain the ``openkb-html-critic`` skill on the
+  produced HTML.
+
+Pre-skill-system implementation lived here too (build_deck_create_agent,
+build_deck_critic_agent, snapshot/restore helpers). All deleted — see
+git history before commit 08e95c3 if you need to reference it.
 """
 from __future__ import annotations
 
 from pathlib import Path
 
-from agents import Agent, Runner, ToolOutputImage, ToolOutputText, function_tool
-from agents.model_settings import ModelSettings
-
-from openkb.deck import deck_dir
-from openkb.deck.tools import write_deck_file as _write_deck_file_impl
-from openkb.prompts import load_prompt
-from openkb.schema import get_agents_md
-from openkb.skill.tools import (
-    get_skill_page_content as _get_page_content_impl,
-    list_wiki_dir as _list_wiki_dir_impl,
-    read_skill_image as _read_image_impl,
-    read_wiki_file_for_skill as _read_wiki_file_impl,
+from openkb.agent.skill_runner import (
+    MAX_TURNS,
+    MAX_TURNS_WITH_CRITIQUE,
+    SkillNotFoundError,
+    run_skill,
 )
+from openkb.deck import deck_dir
 
-MAX_TURNS = 80
-MAX_TURNS_WITH_CRITIQUE = 120
-
-
-def build_deck_create_agent(
-    *,
-    wiki_root: str,
-    deck_root: str,
-    deck_name: str,
-    intent: str,
-    model: str,
-    critique: bool,
-) -> Agent:
-    """Build the openai-agents Agent for generating one deck.
-
-    Args:
-        wiki_root: ``<kb>/wiki`` absolute path.
-        deck_root: ``<kb>/output/decks/<name>`` absolute path. Created
-            if it does not exist.
-        deck_name: kebab-case slug.
-        intent: the user's natural-language brief.
-        model: LiteLLM-formatted model name from KB config.
-        critique: when True, wire the critic agent as a handoff target
-            (see Task 7).
-    """
-    Path(deck_root).mkdir(parents=True, exist_ok=True)
-
-    wiki_schema = get_agents_md(Path(wiki_root))
-    instructions = load_prompt("deck_create").format(
-        intent=intent,
-        deck_name=deck_name,
-        wiki_schema=wiki_schema,
-    )
-
-    @function_tool
-    def list_wiki_dir(directory: str) -> str:
-        """List .md files in a wiki subdirectory (e.g. 'concepts')."""
-        return _list_wiki_dir_impl(directory, wiki_root)
-
-    @function_tool
-    def read_wiki_file(path: str) -> str:
-        """Read a wiki markdown file by path relative to wiki/ (e.g. 'concepts/attention.md')."""
-        return _read_wiki_file_impl(path, wiki_root)
-
-    @function_tool
-    def get_page_content(doc_name: str, pages: str) -> str:
-        """Get text content of specific pages from a PageIndex (long) document.
-
-        Args:
-            doc_name: Document name without extension.
-            pages: Page spec such as ``"3-5,7,10-12"``.
-        """
-        return _get_page_content_impl(doc_name, pages, wiki_root)
-
-    @function_tool
-    def get_image(image_path: str) -> ToolOutputImage | ToolOutputText:
-        """View an image referenced in the wiki.
-
-        Args:
-            image_path: Path relative to wiki/.
-        """
-        result = _read_image_impl(image_path, wiki_root)
-        if result["type"] == "image":
-            return ToolOutputImage(image_url=result["image_url"])
-        return ToolOutputText(text=result["text"])
-
-    @function_tool
-    async def query_wiki(question: str) -> str:
-        """Semantic search over the wiki — narrow follow-ups only.
-
-        Nested LLM call. Use only when direct file reads can't easily
-        answer a specific sub-question.
-        """
-        # Lazy import to avoid a circular dependency at module load time.
-        from openkb.agent.query import run_query
-        kb_dir = Path(wiki_root).parent
-        return await run_query(question, kb_dir, model, stream=False)
-
-    @function_tool
-    def write_deck_file(path: str, content: str) -> str:
-        """Write a file under the deck directory."""
-        return _write_deck_file_impl(path, content, deck_root)
-
-    @function_tool
-    def done(summary: str) -> str:
-        """Signal the deck is complete. Call exactly once when finished."""
-        return f"Deck marked done: {summary}"
-
-    main_tools = [
-        list_wiki_dir,
-        read_wiki_file,
-        get_page_content,
-        get_image,
-        query_wiki,
-        write_deck_file,
-        done,
-    ]
-
-    if not critique:
-        return Agent(
-            name="deck-creator",
-            instructions=instructions,
-            tools=main_tools,
-            model=f"litellm/{model}",
-            # Parallel reads (early fan-out: list dir → read N summaries → read N
-            # source page-ranges) saves 5-10 round-trips per compile. Writes
-            # naturally serialise since each write_deck_file depends on prior
-            # reads; model has no reason to write the same path twice in
-            # parallel.
-            model_settings=ModelSettings(parallel_tool_calls=True),
-        )
-
-    # critique=True: wire critic agent as a handoff target. The agents
-    # SDK auto-exposes a `transfer_to_<critic_name>` tool when handoffs
-    # is non-empty; we don't need to declare it in `main_tools` ourselves.
-    from openkb.deck.critic import build_deck_critic_agent
-
-    critic_agent = build_deck_critic_agent(
-        wiki_root=wiki_root,
-        deck_root=deck_root,
-        intent=intent,
-        model=model,
-    )
-
-    # The critic's prompt step 1 instructs it to call its `take_snapshot`
-    # tool as the first action, which creates index.pre-critique.html.
-    # We tried an SDK lifecycle hook (on_handoff) for this, but the
-    # pinned openai-agents version exposes lifecycle callbacks only via
-    # the Agent.hooks dataclass field (AgentHooks subclass), not as a
-    # settable attribute. The prompt-driven approach is simpler and
-    # works regardless of SDK version.
-
-    handoff_instructions = (
-        "\n\n## Critique pass\n\n"
-        "A critic agent will review your work. When you have finished "
-        "writing index.html and run your self-check, **do not call `done()`** — "
-        "instead transfer to the critic via the handoff tool. The critic "
-        "will revise the deck and call `done` itself."
-    )
 
-    return Agent(
-        name="deck-creator",
-        instructions=instructions + handoff_instructions,
-        tools=main_tools,
-        handoffs=[critic_agent],
-        model=f"litellm/{model}",
-        model_settings=ModelSettings(parallel_tool_calls=True),
-    )
+CRITIC_MAX_TURNS = 40
+"""Critic skill is read-and-patch, not authoring; it converges fast."""
 
 
 async def run_deck_create(
@@ -188,25 +38,16 @@ async def run_deck_create(
     model: str,
     critique: bool,
 ) -> Path:
-    """Compile a single deck from the KB's wiki.
+    """Compile a single deck from the KB's wiki via the deck-editorial skill.
 
-    **As of skill-system refactor:** internally loads the
-    ``openkb-deck-editorial`` skill via :func:`openkb.agent.skill_runner.run_skill`,
-    then (if ``critique``) the ``openkb-html-critic`` skill on the
-    produced file. The CLI surface (``openkb deck new``) is unchanged —
-    only the internals are now the unified skill pipeline.
+    Returns the deck directory. Raises ``RuntimeError`` if the skill is
+    missing, hits the turn cap, or doesn't write ``index.html``.
 
-    Returns the deck directory. Raises ``RuntimeError`` if the agent
-    finishes without writing ``index.html``, or if the run hits the
-    turn cap.
+    When ``critique=True`` the html-critic skill runs as a second pass on
+    the produced file (CSS specificity bugs, missing nav, failure of
+    self-containment). The critic patches in place; missing critic skill
+    is a soft failure (the deck still ships, just unpatched).
     """
-    from openkb.agent.skill_runner import (
-        MAX_TURNS,
-        MAX_TURNS_WITH_CRITIQUE,
-        SkillNotFoundError,
-        run_skill,
-    )
-
     deck_root = deck_dir(kb_dir, deck_name)
     deck_root.mkdir(parents=True, exist_ok=True)
     target_path = f"output/decks/{deck_name}/index.html"
@@ -250,67 +91,11 @@ async def run_deck_create(
                 intent=critic_intent,
                 kb_dir=kb_dir,
                 model=model,
-                max_turns=40,  # critic is reading + patching, not authoring
+                max_turns=CRITIC_MAX_TURNS,
             )
         except SkillNotFoundError:
-            # Critic skill missing is a soft failure — the deck is still
-            # on disk; just no patch pass happened.
+            # Critic skill missing is non-fatal — the unpatched deck
+            # is still on disk and usable.
             pass
 
     return deck_root
-
-
-async def _legacy_run_deck_create_pre_skill_refactor(
-    *,
-    kb_dir: Path,
-    deck_name: str,
-    intent: str,
-    model: str,
-    critique: bool,
-) -> Path:
-    """Pre-skill-refactor implementation. Kept under a renamed symbol
-    so the existing test_deck_creator tests still have a target while
-    we update them in a follow-up. New CLI / chat paths use
-    :func:`run_deck_create` above, which delegates to the skill runner.
-    """
-    wiki_root = str(kb_dir / "wiki")
-    deck_root = deck_dir(kb_dir, deck_name)
-
-    agent = build_deck_create_agent(
-        wiki_root=wiki_root,
-        deck_root=str(deck_root),
-        deck_name=deck_name,
-        intent=intent,
-        model=model,
-        critique=critique,
-    )
-
-    seed = (
-        f"Generate the deck '{deck_name}'. Follow the system prompt's "
-        f"working method. Read the wiki, then write index.html."
-    )
-
-    # Lazy import — same reason as skill creator: keep top of module
-    # independent of agents SDK's exception layout.
-    from agents.exceptions import MaxTurnsExceeded
-
-    turn_cap = MAX_TURNS_WITH_CRITIQUE if critique else MAX_TURNS
-
-    try:
-        await Runner.run(agent, seed, max_turns=turn_cap)
-    except MaxTurnsExceeded as exc:
-        raise RuntimeError(
-            f"Deck generation hit the {turn_cap}-step cap before finishing. "
-            f"The wiki may be too large for a single deck, or the intent may "
-            f"be too broad. Try splitting into multiple decks with narrower "
-            f"intents, or pass a smaller wiki subset."
-        ) from exc
-
-    if not (deck_root / "index.html").exists():
-        raise RuntimeError(
-            f"Deck generation finished but agent did not write index.html "
-            f"at {deck_root}. The deck is incomplete; check the wiki has "
-            f"content related to your intent."
-        )
-
-    return deck_root
diff --git a/openkb/deck/critic.py b/openkb/deck/critic.py
deleted file mode 100644
index 5a19c257..00000000
--- a/openkb/deck/critic.py
+++ /dev/null
@@ -1,182 +0,0 @@
-"""The deck-critic agent.
-
-Invoked via OpenAI Agents SDK handoff from the deck-creator (see
-``openkb.deck.creator``). Inherits the creator's full conversation
-history — tool calls, wiki reads, reasoning trace, the written HTML —
-which is why critic does not need to re-read the wiki to revise.
-
-Critic-only tools:
-  * read_deck_file — main's write_deck_file result string is "Written:
-    index.html", not the body, so critic needs an explicit re-read.
-
-Safety:
-  * ``snapshot_pre_critique`` copies ``index.html`` →
-    ``index.pre-critique.html``. The critic agent calls this via its
-    ``take_snapshot`` tool as the first action in its working method
-    (see ``deck_critique.md`` step 1). The pinned openai-agents SDK
-    exposes lifecycle callbacks only via ``Agent.hooks`` (an AgentHooks
-    subclass), not as settable ``on_handoff`` attributes, so a
-    prompt-driven first-tool-call is the simplest reliable trigger.
-  * ``restore_pre_critique`` puts the snapshot back when the critic's
-    output fails post-validation in ``Generator.run``. NOTE: critic
-    exceptions and MaxTurnsExceeded currently propagate out of
-    ``Generator.run`` before the restore branch — wrap the deck path in
-    try/except there if that coverage is needed in the future.
-  * ``cleanup_pre_critique`` removes the snapshot once critique has
-    succeeded and validation passes — keeps the deck directory clean
-    across runs.
-"""
-from __future__ import annotations
-
-import shutil
-from pathlib import Path
-
-from agents import Agent, ToolOutputImage, ToolOutputText, function_tool
-from agents.model_settings import ModelSettings
-
-from openkb.deck.tools import (
-    read_deck_file as _read_deck_file_impl,
-    write_deck_file as _write_deck_file_impl,
-)
-from openkb.prompts import load_prompt
-from openkb.skill.tools import (
-    get_skill_page_content as _get_page_content_impl,
-    list_wiki_dir as _list_wiki_dir_impl,
-    read_skill_image as _read_image_impl,
-    read_wiki_file_for_skill as _read_wiki_file_impl,
-)
-
-PRE_CRITIQUE_SUFFIX = "pre-critique"  # → "index.pre-critique.html"
-
-
-def snapshot_pre_critique(deck_root: Path) -> Path:
-    """Copy index.html → index.pre-critique.html. Returns the snapshot path.
-
-    Raises FileNotFoundError if index.html is missing — that means the
-    creator never wrote it, and there is nothing for critic to revise.
-    """
-    src = deck_root / "index.html"
-    if not src.is_file():
-        raise FileNotFoundError(
-            f"snapshot_pre_critique: {src} missing — creator did not produce a draft."
-        )
-    dst = deck_root / f"index.{PRE_CRITIQUE_SUFFIX}.html"
-    shutil.copy2(src, dst)
-    return dst
-
-
-def restore_pre_critique(deck_root: Path) -> None:
-    """Restore index.pre-critique.html → index.html. No-op if snapshot absent."""
-    src = deck_root / f"index.{PRE_CRITIQUE_SUFFIX}.html"
-    if not src.is_file():
-        return  # idempotent — nothing to restore
-    dst = deck_root / "index.html"
-    shutil.copy2(src, dst)
-
-
-def cleanup_pre_critique(deck_root: Path) -> None:
-    """Delete index.pre-critique.html if present. No-op if absent.
-
-    Task 7's lifecycle wiring calls this once the critique pass has
-    completed and validation has passed — at that point the snapshot is
-    no longer needed, and leaving it on disk would accumulate stale
-    files across runs.
-    """
-    snapshot = deck_root / f"index.{PRE_CRITIQUE_SUFFIX}.html"
-    if snapshot.is_file():
-        snapshot.unlink()
-
-
-def build_deck_critic_agent(
-    *,
-    wiki_root: str,
-    deck_root: str,
-    intent: str,
-    model: str,
-) -> Agent:
-    """Build the openai-agents Agent for revising a draft deck.
-
-    Args:
-        wiki_root: ``<kb>/wiki`` absolute path.
-        deck_root: ``<kb>/output/decks/<name>`` absolute path.
-        intent: the original user intent the creator received.
-        model: LiteLLM-formatted model name.
-    """
-    instructions = load_prompt("deck_critique").format(intent=intent)
-
-    @function_tool
-    def list_wiki_dir(directory: str) -> str:
-        """List .md files in a wiki subdirectory."""
-        return _list_wiki_dir_impl(directory, wiki_root)
-
-    @function_tool
-    def read_wiki_file(path: str) -> str:
-        """Read a wiki markdown file by path relative to wiki/."""
-        return _read_wiki_file_impl(path, wiki_root)
-
-    @function_tool
-    def get_page_content(doc_name: str, pages: str) -> str:
-        """Get text content of specific pages from a PageIndex document."""
-        return _get_page_content_impl(doc_name, pages, wiki_root)
-
-    @function_tool
-    def get_image(image_path: str) -> ToolOutputImage | ToolOutputText:
-        """View an image referenced in the wiki."""
-        result = _read_image_impl(image_path, wiki_root)
-        if result["type"] == "image":
-            return ToolOutputImage(image_url=result["image_url"])
-        return ToolOutputText(text=result["text"])
-
-    @function_tool
-    async def query_wiki(question: str) -> str:
-        """Semantic search over the wiki — narrow follow-ups only."""
-        from openkb.agent.query import run_query
-        kb_dir = Path(wiki_root).parent
-        return await run_query(question, kb_dir, model, stream=False)
-
-    @function_tool
-    def take_snapshot() -> str:
-        """Save the current index.html as index.pre-critique.html.
-
-        Call this as your FIRST action when starting the critique, before
-        reading or modifying anything. It preserves the creator's draft
-        so it can be restored if your revisions fail validation.
-        """
-        snapshot_pre_critique(Path(deck_root))
-        return "Snapshot taken: index.pre-critique.html"
-
-    @function_tool
-    def read_deck_file(path: str) -> str:
-        """Read a file from the deck directory (e.g. 'index.html')."""
-        return _read_deck_file_impl(path, deck_root)
-
-    @function_tool
-    def write_deck_file(path: str, content: str) -> str:
-        """Write a file under the deck directory."""
-        return _write_deck_file_impl(path, content, deck_root)
-
-    @function_tool
-    def done(summary: str) -> str:
-        """Signal the critique is complete. Call exactly once when finished."""
-        return f"Critique marked done: {summary}"
-
-    return Agent(
-        name="deck-critic",
-        instructions=instructions,
-        tools=[
-            list_wiki_dir,
-            read_wiki_file,
-            get_page_content,
-            get_image,
-            query_wiki,
-            take_snapshot,
-            read_deck_file,
-            write_deck_file,
-            done,
-        ],
-        model=f"litellm/{model}",
-        # Critic edits sequentially: read draft → patch. Parallel tool
-        # calls would let it issue overlapping writes to the same file,
-        # which is unsafe.
-        model_settings=ModelSettings(parallel_tool_calls=False),
-    )
diff --git a/openkb/deck/tools.py b/openkb/deck/tools.py
deleted file mode 100644
index bf9f145e..00000000
--- a/openkb/deck/tools.py
+++ /dev/null
@@ -1,59 +0,0 @@
-"""Path-scoped IO tools for the deck-create and deck-critic agents.
-
-* WRITE under deck root  — ``write_deck_file``
-* READ from deck root    — ``read_deck_file``
-
-Wiki read tools (``list_wiki_dir``, ``read_wiki_file_for_skill``,
-``get_skill_page_content``, ``read_skill_image``) are reused verbatim from
-``openkb.skill.tools`` — no duplication. Importers should pull those
-directly from there.
-
-Write boundary is enforced at the Python level: every path resolves and
-must stay inside the deck root. Absolute paths and ``..`` traversal are
-rejected outright. Mirror of ``openkb/skill/tools.py::write_skill_file``.
-"""
-from __future__ import annotations
-
-from pathlib import Path
-
-
-def write_deck_file(path: str, content: str, deck_root: str) -> str:
-    """Write a file under the deck directory.
-
-    Args:
-        path: Path relative to *deck_root* (e.g. ``"index.html"``).
-            Absolute paths and ``..`` traversal are rejected.
-        content: File contents.
-        deck_root: Absolute path to ``<kb>/output/decks/<name>``.
-    """
-    if path.startswith("/") or ".." in Path(path).parts:
-        return "Access denied: only relative paths within the deck directory are allowed."
-    root = Path(deck_root).resolve()
-    full = (root / path).resolve()
-    if not full.is_relative_to(root):
-        return "Access denied: path escapes deck root."
-    full.parent.mkdir(parents=True, exist_ok=True)
-    full.write_text(content, encoding="utf-8")
-    return f"Written: {path}"
-
-
-def read_deck_file(path: str, deck_root: str) -> str:
-    """Read a file from the deck directory.
-
-    Used by the critic agent to re-read the draft ``index.html`` for
-    revision — main's ``write_deck_file`` result string is "Written: X",
-    not the HTML body, so critic needs an explicit re-read tool.
-
-    Args:
-        path: Path relative to *deck_root* (e.g. ``"index.html"``).
-        deck_root: Absolute path to ``<kb>/output/decks/<name>``.
-    """
-    if path.startswith("/") or ".." in Path(path).parts:
-        return "Access denied: only relative paths within the deck directory are allowed."
-    root = Path(deck_root).resolve()
-    full = (root / path).resolve()
-    if not full.is_relative_to(root):
-        return "Access denied: path escapes deck root."
-    if not full.exists():
-        return f"File not found: {path}"
-    return full.read_text(encoding="utf-8")
diff --git a/openkb/prompts/deck_create.md b/openkb/prompts/deck_create.md
deleted file mode 100644
index b0aff514..00000000
--- a/openkb/prompts/deck_create.md
+++ /dev/null
@@ -1,257 +0,0 @@
-<!-- openkb/prompts/deck_create.md -->
-You are the OpenKB deck-create agent. Your job: read the knowledge base
-wiki at `<kb>/wiki/` and produce a polished, single-file HTML slide deck
-at `<kb>/output/decks/{deck_name}/index.html`.
-
-You are not writing a research report or a Wikipedia article. **You are
-designing a presentation.** Each slide carries one idea. Visual structure
-carries the narrative. The deliverable is meant to be opened in a
-browser, full-screened with `F`, and shown to other humans — or shared
-via a single `.html` file in Slack.
-
-## User intent
-
-The user requested this deck with the following description. Treat it as
-authoritative; every slide must serve this intent.
-
-> {intent}
-
-## Wiki schema reference
-
-The wiki you can read from is structured as follows.
-
-{wiki_schema}
-
-## Your tools
-
-* `list_wiki_dir(directory)` — list `.md` files in a wiki subdirectory.
-* `read_wiki_file(path)` — read a markdown file under `<kb>/wiki/`.
-* `get_page_content(doc_name, pages)` — fetch source pages of a
-  PageIndex (long) document at page-range granularity. Use tight ranges,
-  never the whole document.
-* `get_image(image_path)` — view a figure or diagram from the wiki to
-  decide whether to *reference* it in prose. (v1 does not support
-  embedding bitmap images in the deck — use inline `<svg>` if you need
-  graphics.)
-* `query_wiki(question)` — semantic search; narrow follow-ups only.
-  This is a nested LLM call (slow, expensive); prefer direct reads.
-* `write_deck_file(path, content)` — write under
-  `<kb>/output/decks/{deck_name}/`. Relative paths only.
-* `done(summary)` — signal completion. Call exactly once when finished.
-
-## Required output
-
-Exactly one file: `index.html` at the deck root.
-
-It must be **self-contained**: no external `<link rel="stylesheet">`,
-no external `<script src="…">`, no remote `<img>`. All CSS goes in a
-single inline `<style>` in `<head>`. Helper JS for keyboard nav goes in
-a single inline `<script>` at end of `<body>`.
-
-The body is a sequence of `<section class="slide" data-type="...">`
-blocks. Each `data-type` must be one of the 7 values listed in §
-"Slide grammar" below. The deck supports keyboard navigation: ← / →
-move between slides, `F` toggles fullscreen, `P` triggers print
-(browser's Print → Save as PDF is the user's PDF export).
-
-## Design system: Editorial Monocle
-
-You will compose every slide from this fixed design system. Do not
-improvise nearby colors, do not introduce gradients, do not bring in
-emojis. This is the **only** non-monochrome palette in the entire deck.
-
-### Color palette
-
-Use these exact values. Define them as CSS custom properties on `:root`
-and reference them throughout.
-
-```css
-:root {{
-  --bg:        #f3eee1;  /* oklch(94% 0.03 80)  — warm cream paper */
-  --ink:       #1a1612;  /* oklch(15% 0.01 50)  — warm near-black */
-  --muted:     #7a6e55;  /* oklch(55% 0.04 75)  — labels / metadata */
-  --rule:      #d4cfc0;  /* oklch(82% 0.02 75)  — thin separator */
-  --accent:    #a4341c;  /* oklch(45% 0.16 30)  — brick red, the ONLY non-monochrome */
-  --highlight: #fff3a8;  /* oklch(95% 0.10 95)  — marker highlighter ONLY */
-}}
-```
-
-### Type system
-
-```css
-font-family-serif:  "Charter", "Iowan Old Style", "Times New Roman", Georgia, serif;
-font-family-sans:   "Inter", -apple-system, "Helvetica Neue", sans-serif;  /* labels only */
-```
-
-Type scale (size / line-height / letter-spacing):
-
-* `--type-display`: 56px / 1.05 / -1px      — cover/chapter big titles
-* `--type-title`:   38px / 1.10 / -0.5px    — normal slide titles
-* `--type-body`:    18px / 1.55 / 0         — body copy
-* `--type-quote`:   28px / 1.30 / -0.3px    italic — pull quotes
-* `--type-label`:   10px / 1.0 / 2.5px      uppercase — top/bottom label tracks
-
-Serif for everything except labels. Labels use sans, uppercase,
-`--muted` color, and the 2.5px letter-spacing track.
-
-### Frame (every slide)
-
-* 16:9 aspect ratio: `aspect-ratio: 16/9; width: 100vw; max-width: 1280px;`
-* Per-slide padding: 64px top/bottom, 80px left/right.
-* **10px brick-red bar on the right edge of every slide.** This is the
-  deck's visual signature; do not omit it. (4px reads as invisible at
-  presentation scale — 10px reads as a confident hairline rule.)
-* Top label row (10px sans, `--muted`, uppercase, tracking):
-  left = chapter id (e.g. "CHAPTER 03"), right = source mark
-  (e.g. "VASWANI ET AL · 2017").
-* Bottom folio row (use `--type-label`, slightly more `--muted` than the top row): left = `N / Total`,
-  right = source short label.
-
-### Composition rules (avoid the "right half empty" failure)
-
-* **Cover title (`.display`)** must use `max-width: 18ch` (NOT 10ch or
-  narrower). A 6-word title at 56px should break to at most 2-3 lines
-  with natural breaks — never wrap an article ("the", "an", "to")
-  onto its own line.
-* **Data slides** must center the big number horizontally on the slide
-  (set the `.data-body` container to `align-items: center; text-align: center`
-  for `data-type="data"` only — leave other slide types left-aligned).
-  Body copy beneath the number stays centered, max-width 38em. The big
-  number must read as the slide's anchor; orphaning it to the left
-  column wastes the canvas.
-* **Cover and closing slides** also benefit from filling more of the
-  canvas — set `.cover-body, .closing-body {{ max-width: 26em }}` (not
-  narrower). Right-side dead space should be rare and intentional.
-
-### Keyboard nav hint
-
-The "← → navigate · F fullscreen · P print" hint exists for first-time
-users — it must NOT compete with the folio during presentation.
-Required CSS:
-
-```css
-.kbd {{
-  opacity: 0;
-  transition: opacity .25s ease;
-}}
-body:hover .kbd {{ opacity: .55; }}
-```
-
-The hint fades in only when the user moves the mouse; idle / fullscreen
-presentation never shows it.
-
-## Slide grammar
-
-Every slide must declare `data-type` from this exact whitelist. The
-seven values are the only ones allowed — the validator will reject the
-deck if it sees anything else.
-
-| `data-type` | Use | Visual signature |
-|---|---|---|
-| `cover`   | First slide: tag + huge title + 1-line subtitle | Display type, **left-aligned, never centered** |
-| `chapter` | Section divider: oversize number + chapter name | Number 120px brick-red, name 38px serif |
-| `thesis`  | A single claim + a short explanation | Title fills ~60% height, explanation small bottom |
-| `quote`   | Italic pull-quote + attribution | Centered, serif italic 28px, generous whitespace |
-| `compare` | Two-column comparison: header + 3-5 lines each side | 1px brick-red vertical rule between columns |
-| `data`    | One number + label + one-line interpretation | Number 120-160px brick-red, micro-copy 12px |
-| `closing` | Mirrors `cover`; thanks / next steps | Same scale as cover but content closes the arc |
-
-Skeleton templates (extend with content; do not deviate from the
-structural shape):
-
-```html
-<section class="slide" data-type="cover">
-  <div class="label-top"><span>OPENKB</span><span>{{date}}</span></div>
-  <div class="cover-body">
-    <div class="eyebrow">— {{short eyebrow}}</div>
-    <h1 class="display">{{title}}</h1>
-    <p class="subtitle">{{1-line subtitle, max 22 words}}</p>
-  </div>
-  <div class="folio"><span>01 / N</span><span>{{source mark}}</span></div>
-</section>
-```
-
-**Cover/closing exception:** the `cover` and `closing` slides have no
-chapter context, so the top-left label is the deck identifier
-("OPENKB") instead of a `CHAPTER NN` id. Every other slide type uses
-the chapter id on the top-left as described in §Frame.
-
-```html
-<section class="slide" data-type="thesis">
-  <div class="label-top"><span>{{chapter id}}</span><span>{{source mark}}</span></div>
-  <div class="thesis-body">
-    <h2 class="title">{{the claim, max 14 words}}</h2>
-    <p class="body">{{2-3 sentence explanation, max 60 words}}</p>
-  </div>
-  <div class="folio"><span>{{n}} / N</span><span>{{source short}}</span></div>
-</section>
-
-<!-- repeat shape for chapter / quote / compare / data / closing -->
-```
-
-## Working method
-
-1. **Survey first.** `list_wiki_dir("concepts")`, `list_wiki_dir("summaries")`,
-   read `wiki/index.md`. Form a mental map of what the KB actually contains
-   before you decide what the deck argues.
-2. **Choose a narrative arc.** Before writing any HTML, write a one-line
-   thesis the deck argues, then an 8-12 step arc (problem → tension →
-   resolution, or whatever shape the intent calls for). Each step
-   becomes 1-2 slides, which lands the final deck in the 8-15 range
-   required by §Self-check. Write this arc into the deck only as
-   section titles — *not* as on-slide text.
-3. **Read the relevant content.** For each concept the arc touches, read
-   the concept page (`read_wiki_file("concepts/...")`). For each
-   document a concept cites, read at least one targeted slice of the
-   source (use `get_page_content` with tight ranges for PageIndex docs,
-   `read_wiki_file` on the `full_text` path for short docs).
-4. **Outline the slides.** Map each step in the arc to one or more
-   slides with concrete `data-type` assignments. Aim for 8-15 slides
-   total. **Vary `data-type`** — at least 4 distinct types, no run of
-   3+ consecutive same type.
-5. **Write `index.html`.** One `write_deck_file("index.html", ...)`
-   call with the complete file. Inline all CSS and the keyboard nav JS.
-   For any inline graphics use `<svg>` written directly into the HTML —
-   v1 does not embed bitmap images. The `get_image` tool exists for
-   *previewing* wiki figures so you can decide whether to reference
-   them in prose, not for embedding them.
-6. **Revise.** Re-read what you wrote against the failure modes in §
-   "Failure modes" below. Touch at least one slide on this pass.
-7. **Self-check** the 5 invariants in § "Self-check" below. Fix anything
-   that fails.
-8. Call `done(summary)` with a one-paragraph summary of the arc you
-   chose and the slide-type distribution.
-
-## Failure modes (negative checklist)
-
-These patterns are AI slop. If you see one in your draft, fix it.
-
-1. **Bullet dump** — any slide with more than 5 bullet points. Pick the
-   3 strongest, or restructure into a `compare` or `data` slide.
-2. **Wall of text** — slide body longer than ~80 words. Cut, or split.
-3. **Visual monotony** — three or more consecutive slides with the same
-   `data-type`. Insert a `quote`, `data`, or `chapter` to break rhythm.
-4. **Centered everything** — only `quote` and `closing` are centered.
-   All other slide types are **left-aligned**.
-5. **AI slop palette** — any color outside the 6-value palette above:
-   no blue/purple gradients, no emoji, no rainbow accents.
-6. **Generic titles** — "Introduction" / "Background" / "Conclusion" as
-   a slide title is a failure. Title must carry specific content
-   ("Attention replaces recurrence" beats "Background").
-
-## Self-check (before `done`)
-
-Walk through these five questions. The deck is not done until each
-answer is yes:
-
-1. Does `index.html` exist and contain no external `<link>` or
-   `<script src=>`?
-2. Is there at least one `data-type="cover"` and one `data-type="closing"`?
-3. Is the total slide count between 8 and 15?
-4. Are at least 4 distinct `data-type` values used?
-5. Is there no run of 3+ consecutive slides with the same `data-type`?
-
-If any answer is no, revise the deck and re-run this self-check before
-calling `done`.
-
-Begin.
diff --git a/openkb/prompts/deck_critique.md b/openkb/prompts/deck_critique.md
deleted file mode 100644
index 0026d01a..00000000
--- a/openkb/prompts/deck_critique.md
+++ /dev/null
@@ -1,61 +0,0 @@
-<!-- openkb/prompts/deck_critique.md -->
-You are the OpenKB deck-critic agent. You have just received a handoff
-from the deck-creator agent. The creator has written a draft deck at
-`<kb>/output/decks/<name>/index.html` for the following intent:
-
-> {intent}
-
-Your job: **revise** that draft into a tighter, more visually disciplined
-deck. You are not re-writing from scratch — you are a senior designer
-reviewing a junior designer's first pass.
-
-## Your tools
-
-Same wiki-read tools the creator had, plus `read_deck_file` so you can
-see the current HTML, plus `write_deck_file` to commit revisions, plus
-`done` to finalise.
-
-Use the wiki tools sparingly — your job is primarily design/layout/voice
-revision, not content rediscovery. Read the wiki only when a specific
-slide is generic and you can fix it by pulling a concrete fact from
-sources you can locate from inherited context.
-
-## Working method
-
-1. **Take a snapshot first.** Your VERY first tool call must be
-   `take_snapshot()`. This preserves the creator's draft as
-   `index.pre-critique.html` so the orchestrator can restore it if
-   your revisions fail validation. Do this before reading anything.
-2. **Read the current draft.** `read_deck_file("index.html")` next.
-   Ignore any sibling files in the deck directory (e.g.
-   `index.pre-critique.html`) — those are internal safety snapshots,
-   not for you to read or write.
-3. **Score against failure modes.** For each of these, identify each
-   slide that violates and note what to change:
-   - Bullet dump (> 5 bullets)
-   - Wall of text (body > 80 words)
-   - Visual monotony (3+ consecutive same data-type)
-   - Centered everything (only `quote` / `closing` should be centered)
-   - AI slop palette (any color outside the 6-value Editorial Monocle
-     palette: `#f3eee1`, `#1a1612`, `#7a6e55`, `#d4cfc0`, `#a4341c`,
-     `#fff3a8`)
-   - Generic titles ("Introduction", "Background", "Conclusion")
-4. **Score against invariants.** Verify:
-   - ≥ 1 `data-type="cover"` + ≥ 1 `data-type="closing"`
-   - Slide count ∈ [8, 15]
-   - ≥ 4 distinct `data-type` values
-   - No run of 3+ consecutive same `data-type`
-5. **Patch.** Write the revised `index.html` in a single
-   `write_deck_file("index.html", ...)` call. Do not split into
-   multiple writes — one atomic replacement.
-6. **Call `done(summary)`** with a one-paragraph summary of what you
-   changed and why.
-
-## Design system invariants
-
-The Editorial Monocle palette and type system are fixed. Do not
-introduce new colors, new fonts, or new `data-type` values. The seven
-permitted `data-type` values: `cover`, `chapter`, `thesis`, `quote`,
-`compare`, `data`, `closing`. Anything else fails validation.
-
-Begin.
diff --git a/openkb/skill/generator.py b/openkb/skill/generator.py
index 115b8e5a..8fa54bcd 100644
--- a/openkb/skill/generator.py
+++ b/openkb/skill/generator.py
@@ -1,17 +1,18 @@
 """Generator primitive — shared abstraction for all `<kb>/output/<type>/` artifacts.
 
-v0.2 supports ``target_type="skill"`` and ``target_type="deck"``. Future
-targets (``"podcast"``, ``"report"``, ``"video"``) plug in here under the
-same conventions:
+v0.3 supports ``target_type="skill"`` and ``target_type="deck"``. Both
+targets now route through ``openkb.agent.skill_runner.run_skill`` under
+the hood; ``Generator`` is the thin wrapper that owns:
 
 * output-path convention: ``<kb>/output/<type>/<name>/``
 * post-compile validation: target-specific validator dispatched here
-* post-run hooks: skill regenerates marketplace.json; deck does not (it's
-  not a Claude Code plugin)
+* post-run hooks: skill regenerates ``marketplace.json``; deck has no
+  per-target hook (the html-critic skill, when invoked, has already
+  patched the file in place)
 
-Each target plugs in its own ``run`` coroutine. v0.2 dispatches to
-``openkb.skill.creator.run_skill_create`` or
-``openkb.deck.creator.run_deck_create``.
+Future targets (``"podcast"``, ``"report"``, ``"video"``) plug in by
+declaring an output dir and a validator; the actual content generation
+is just another SKILL.md under ``skills/``.
 """
 from __future__ import annotations
 
@@ -20,7 +21,6 @@
 
 from openkb.deck import deck_dir
 from openkb.deck.creator import run_deck_create
-from openkb.deck.critic import cleanup_pre_critique, restore_pre_critique
 from openkb.deck.validator import (
     ValidationResult as DeckValidationResult,
     validate_deck,
@@ -39,7 +39,7 @@
 
 
 class Generator:
-    """A v0.2 generator instance.
+    """A v0.3 generator instance.
 
     Args:
         target_type: ``"skill"`` or ``"deck"``.
@@ -47,8 +47,9 @@ class Generator:
         intent: natural-language description of the desired artifact.
         kb_dir: KB root.
         model: LiteLLM model name (from KB config).
-        critique: (deck only) opt-in second-pass review via SDK handoff.
-            Ignored for ``target_type="skill"``.
+        critique: (deck only) opt-in second-pass via the
+            ``openkb-html-critic`` skill which patches the produced HTML
+            in place. Ignored for ``target_type="skill"``.
     """
 
     def __init__(
@@ -63,7 +64,7 @@ def __init__(
     ) -> None:
         if target_type not in ("skill", "deck"):
             raise ValueError(
-                f"Unknown target_type {target_type!r}. v0.2 supports 'skill' and 'deck'."
+                f"Unknown target_type {target_type!r}. v0.3 supports 'skill' and 'deck'."
             )
         self.target_type: TargetType = target_type
         self.name = name
@@ -82,9 +83,6 @@ async def run(self) -> Path:
         Side-effects, in order: compile → validate → (skill only) publish
         manifest. ``self.validation`` holds the result so callers can
         surface issues without re-running the validator.
-
-        Deck path: on validation error after a critique run, restore the
-        pre-critique snapshot so the user never loses the clean main draft.
         """
         if self.target_type == "skill":
             await run_skill_create(
@@ -106,19 +104,4 @@ async def run(self) -> Path:
             critique=self.critique,
         )
         self.validation = validate_deck(self.output_dir)
-
-        if self.critique:
-            if self.validation.errors:
-                # Critique pass produced invalid HTML. Restore pre-critique
-                # snapshot and re-validate so callers see the clean state.
-                restore_pre_critique(self.output_dir)
-                self.validation = validate_deck(self.output_dir)
-                self.validation.warnings.append(
-                    "critique pass failed; restored pre-critique draft."
-                )
-            else:
-                # Critique succeeded — remove the snapshot so it doesn't
-                # accumulate across runs.
-                cleanup_pre_critique(self.output_dir)
-
         return self.output_dir
diff --git a/tests/test_deck_creator.py b/tests/test_deck_creator.py
index 76aa3c4e..0d380cc3 100644
--- a/tests/test_deck_creator.py
+++ b/tests/test_deck_creator.py
@@ -1,164 +1,169 @@
-"""Tests for the deck-create agent builder + runner.
+"""Tests for the deck-creator wrapper around the skill runner.
 
-No real LLM calls — Runner.run is patched. We verify:
-  * the Agent is built with the right name, prompt, tool count
-  * critique=False produces an agent with no handoffs
-  * run_deck_create raises if index.html is not written
-  * run_deck_create raises with a helpful message on MaxTurnsExceeded
+Pre-skill-system tests (agent shape, handoff wiring, snapshot/restore)
+have been removed alongside the build_deck_create_agent /
+build_deck_critic_agent symbols they covered. See git history before
+commit 08e95c3 if you need the originals.
+
+The remaining surface to test is small: ``run_deck_create`` is a thin
+wrapper that calls ``run_skill`` (mocked here), checks the output file
+exists, and optionally chains the critic skill.
 """
 from __future__ import annotations
 
 from pathlib import Path
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import AsyncMock, patch
 
 import pytest
 
-from openkb.deck.creator import (
-    _legacy_run_deck_create_pre_skill_refactor as run_deck_create,
-    build_deck_create_agent,
-)
-
-
-def _build(tmp_path: Path):
-    wiki_root = tmp_path / "wiki"
-    wiki_root.mkdir()
-    # AGENTS.md is consulted by get_agents_md; an empty file is fine.
-    (wiki_root / "AGENTS.md").write_text("# wiki schema placeholder", encoding="utf-8")
-    deck_root = tmp_path / "output" / "decks" / "test-deck"
-    return wiki_root, deck_root
-
-
-def test_build_agent_shape(tmp_path: Path):
-    wiki_root, deck_root = _build(tmp_path)
-    agent = build_deck_create_agent(
-        wiki_root=str(wiki_root),
-        deck_root=str(deck_root),
-        deck_name="test-deck",
-        intent="A test deck about transformers.",
-        model="openai/gpt-4o",
-        critique=False,
-    )
-    assert agent.name == "deck-creator"
-    # 7 tools: list_wiki_dir, read_wiki_file, get_page_content,
-    # get_image, query_wiki, write_deck_file, done
-    assert len(agent.tools) == 7
-    tool_names = {getattr(t, "name", "?") for t in agent.tools}
-    assert "write_deck_file" in tool_names
-    assert "done" in tool_names
-    # No handoffs when critique=False
-    assert getattr(agent, "handoffs", []) in ([], None)
-
-
-def test_build_agent_creates_output_dir(tmp_path: Path):
-    wiki_root, deck_root = _build(tmp_path)
-    assert not deck_root.exists()
-    build_deck_create_agent(
-        wiki_root=str(wiki_root),
-        deck_root=str(deck_root),
-        deck_name="test-deck",
-        intent="A test deck.",
-        model="openai/gpt-4o",
-        critique=False,
-    )
-    assert deck_root.is_dir()
-
-
-def test_run_raises_when_html_missing(tmp_path: Path):
-    wiki_root, _ = _build(tmp_path)
-    kb_dir = tmp_path
-
-    with patch("openkb.deck.creator.Runner") as runner:
-        runner.run = AsyncMock(return_value=MagicMock())
-        import asyncio
-        with pytest.raises(RuntimeError, match="did not write index.html"):
-            asyncio.run(
-                run_deck_create(
-                    kb_dir=kb_dir,
-                    deck_name="test-deck",
-                    intent="A test deck.",
-                    model="openai/gpt-4o",
-                    critique=False,
-                )
-            )
+from openkb.agent.skill_runner import SkillNotFoundError
+from openkb.deck.creator import CRITIC_MAX_TURNS, run_deck_create
+
+
+def _make_kb(tmp_path: Path) -> Path:
+    """Minimal KB layout so run_deck_create's path math works."""
+    (tmp_path / "wiki").mkdir()
+    (tmp_path / "wiki" / "AGENTS.md").write_text("schema", encoding="utf-8")
+    return tmp_path
+
+
+def _write_index(kb_dir: Path, deck_name: str, body: str = "<html></html>") -> Path:
+    """Simulate the deck-editorial skill writing index.html."""
+    out = kb_dir / "output" / "decks" / deck_name
+    out.mkdir(parents=True, exist_ok=True)
+    p = out / "index.html"
+    p.write_text(body, encoding="utf-8")
+    return p
+
+
+@pytest.mark.asyncio
+async def test_run_deck_create_calls_editorial_skill(tmp_path: Path):
+    kb_dir = _make_kb(tmp_path)
+
+    async def fake_skill(skill_name, intent, **_):
+        if skill_name == "openkb-deck-editorial":
+            _write_index(kb_dir, "test-deck")
+
+    with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)) as run_skill:
+        result = await run_deck_create(
+            kb_dir=kb_dir,
+            deck_name="test-deck",
+            intent="A test deck.",
+            model="openai/gpt-4o",
+            critique=False,
+        )
+
+    assert result == kb_dir / "output" / "decks" / "test-deck"
+    assert (result / "index.html").is_file()
+    # exactly one skill call (no critic when critique=False)
+    assert run_skill.await_count == 1
+    args, kwargs = run_skill.call_args
+    assert kwargs["skill_name"] == "openkb-deck-editorial"
+    assert "test-deck" in kwargs["intent"]
+
+
+@pytest.mark.asyncio
+async def test_run_deck_create_chains_critic_when_critique_true(tmp_path: Path):
+    kb_dir = _make_kb(tmp_path)
+    calls: list[str] = []
+
+    async def fake_skill(skill_name, intent, **_):
+        calls.append(skill_name)
+        if skill_name == "openkb-deck-editorial":
+            _write_index(kb_dir, "test-deck")
+
+    with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)):
+        await run_deck_create(
+            kb_dir=kb_dir,
+            deck_name="test-deck",
+            intent="A test deck.",
+            model="openai/gpt-4o",
+            critique=True,
+        )
+
+    assert calls == ["openkb-deck-editorial", "openkb-html-critic"]
+
+
+@pytest.mark.asyncio
+async def test_run_deck_create_critic_max_turns(tmp_path: Path):
+    """When critique=True, second call is to the critic skill with the
+    smaller CRITIC_MAX_TURNS budget (it's read-and-patch, not authoring)."""
+    kb_dir = _make_kb(tmp_path)
 
+    async def fake_skill(skill_name, intent, **kw):
+        if skill_name == "openkb-deck-editorial":
+            _write_index(kb_dir, "test-deck")
 
-def test_run_translates_maxturns(tmp_path: Path):
-    wiki_root, _ = _build(tmp_path)
-    kb_dir = tmp_path
-    from agents.exceptions import MaxTurnsExceeded
-
-    with patch("openkb.deck.creator.Runner") as runner:
-        runner.run = AsyncMock(side_effect=MaxTurnsExceeded("nope"))
-        import asyncio
-        with pytest.raises(RuntimeError, match="step cap"):
-            asyncio.run(
-                run_deck_create(
-                    kb_dir=kb_dir,
-                    deck_name="test-deck",
-                    intent="A test deck.",
-                    model="openai/gpt-4o",
-                    critique=False,
-                )
+    with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)) as run_skill:
+        await run_deck_create(
+            kb_dir=kb_dir,
+            deck_name="test-deck",
+            intent="A test deck.",
+            model="openai/gpt-4o",
+            critique=True,
+        )
+
+    critic_call = run_skill.call_args_list[1]
+    assert critic_call.kwargs["skill_name"] == "openkb-html-critic"
+    assert critic_call.kwargs["max_turns"] == CRITIC_MAX_TURNS
+
+
+@pytest.mark.asyncio
+async def test_run_deck_create_raises_when_skill_missing(tmp_path: Path):
+    kb_dir = _make_kb(tmp_path)
+
+    async def missing_skill(**_):
+        raise SkillNotFoundError("not installed")
+
+    with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=missing_skill)):
+        with pytest.raises(RuntimeError, match="openkb-deck-editorial"):
+            await run_deck_create(
+                kb_dir=kb_dir,
+                deck_name="test-deck",
+                intent="A test deck.",
+                model="openai/gpt-4o",
+                critique=False,
             )
 
 
-def test_build_agent_critique_sets_handoffs(tmp_path: Path):
-    wiki_root, deck_root = _build(tmp_path)
-    agent = build_deck_create_agent(
-        wiki_root=str(wiki_root),
-        deck_root=str(deck_root),
-        deck_name="test-deck",
-        intent="A test deck.",
-        model="openai/gpt-4o",
-        critique=True,
-    )
-    # Main still has 7 tools (SDK auto-exposes the handoff transfer tool
-    # separately, not through the explicit `tools` list).
-    assert len(agent.tools) == 7
-    assert agent.handoffs, "critique=True must wire a critic handoff"
-    assert len(agent.handoffs) == 1
-    assert agent.handoffs[0].name == "deck-critic"
-
-
-def test_build_agent_critique_appends_handoff_instructions(tmp_path: Path):
-    wiki_root, deck_root = _build(tmp_path)
-    agent = build_deck_create_agent(
-        wiki_root=str(wiki_root),
-        deck_root=str(deck_root),
-        deck_name="test-deck",
-        intent="A test deck.",
-        model="openai/gpt-4o",
-        critique=True,
-    )
-    assert "Critique pass" in agent.instructions
-    assert "transfer to" in agent.instructions.lower()
-
-
-def test_run_with_critique_uses_higher_turn_cap(tmp_path: Path):
-    """When critique=True, Runner.run must be called with max_turns=120."""
-    wiki_root, _ = _build(tmp_path)
-    kb_dir = tmp_path
-    captured: dict = {}
-
-    async def _fake_run(agent, seed, *, max_turns):
-        captured["max_turns"] = max_turns
-        # Write a minimal index.html so run_deck_create does not raise.
-        from openkb.deck import deck_dir
-        d = deck_dir(kb_dir, "test-deck")
-        d.mkdir(parents=True, exist_ok=True)
-        (d / "index.html").write_text("<html></html>", encoding="utf-8")
-        return MagicMock()
-
-    with patch("openkb.deck.creator.Runner") as runner:
-        runner.run = _fake_run  # plain async fn, not AsyncMock — we read args
-        import asyncio
-        asyncio.run(
-            run_deck_create(
+@pytest.mark.asyncio
+async def test_run_deck_create_raises_when_html_missing(tmp_path: Path):
+    """If the skill returns but no index.html was written, error out."""
+    kb_dir = _make_kb(tmp_path)
+
+    async def fake_skill(**_):
+        return  # no file written
+
+    with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)):
+        with pytest.raises(RuntimeError, match="did not write index.html"):
+            await run_deck_create(
                 kb_dir=kb_dir,
                 deck_name="test-deck",
                 intent="A test deck.",
                 model="openai/gpt-4o",
-                critique=True,
+                critique=False,
             )
+
+
+@pytest.mark.asyncio
+async def test_run_deck_create_tolerates_missing_critic(tmp_path: Path):
+    """Critic skill not installed shouldn't kill the run — the unpatched
+    deck is still on disk and usable."""
+    kb_dir = _make_kb(tmp_path)
+
+    async def fake_skill(skill_name, **_):
+        if skill_name == "openkb-deck-editorial":
+            _write_index(kb_dir, "test-deck")
+        else:
+            raise SkillNotFoundError("critic not installed")
+
+    with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)):
+        result = await run_deck_create(
+            kb_dir=kb_dir,
+            deck_name="test-deck",
+            intent="A test deck.",
+            model="openai/gpt-4o",
+            critique=True,
         )
-    assert captured["max_turns"] == 120
+
+    assert (result / "index.html").is_file()
diff --git a/tests/test_deck_critic.py b/tests/test_deck_critic.py
deleted file mode 100644
index c149d9dc..00000000
--- a/tests/test_deck_critic.py
+++ /dev/null
@@ -1,88 +0,0 @@
-"""Tests for the deck critic agent + snapshot/restore safety hooks."""
-from __future__ import annotations
-
-import shutil
-from pathlib import Path
-
-import pytest
-
-from openkb.deck.critic import (
-    build_deck_critic_agent,
-    restore_pre_critique,
-    snapshot_pre_critique,
-)
-
-
-def test_build_critic_agent_shape(tmp_path: Path):
-    wiki_root = tmp_path / "wiki"
-    wiki_root.mkdir()
-    (wiki_root / "AGENTS.md").write_text("# wiki schema placeholder", encoding="utf-8")
-    deck_root = tmp_path / "deck"
-    deck_root.mkdir()
-    agent = build_deck_critic_agent(
-        wiki_root=str(wiki_root),
-        deck_root=str(deck_root),
-        intent="A deck about transformers.",
-        model="openai/gpt-4o",
-    )
-    assert agent.name == "deck-critic"
-    # 9 tools: 5 wiki-read + take_snapshot + read_deck_file + write_deck_file + done
-    assert len(agent.tools) == 9
-    tool_names = {getattr(t, "name", "?") for t in agent.tools}
-    assert "take_snapshot" in tool_names
-    assert "read_deck_file" in tool_names
-    assert "write_deck_file" in tool_names
-
-
-def test_snapshot_creates_pre_critique_copy(tmp_path: Path):
-    deck_root = tmp_path / "deck"
-    deck_root.mkdir()
-    (deck_root / "index.html").write_text("<html>v1</html>", encoding="utf-8")
-    snapshot_pre_critique(deck_root)
-    assert (deck_root / "index.pre-critique.html").read_text() == "<html>v1</html>"
-
-
-def test_snapshot_missing_html_raises(tmp_path: Path):
-    deck_root = tmp_path / "deck"
-    deck_root.mkdir()
-    with pytest.raises(FileNotFoundError):
-        snapshot_pre_critique(deck_root)
-
-
-def test_restore_recovers_index(tmp_path: Path):
-    deck_root = tmp_path / "deck"
-    deck_root.mkdir()
-    (deck_root / "index.pre-critique.html").write_text("<html>v1</html>", encoding="utf-8")
-    (deck_root / "index.html").write_text("<html>broken-by-critic</html>", encoding="utf-8")
-    restore_pre_critique(deck_root)
-    assert (deck_root / "index.html").read_text() == "<html>v1</html>"
-
-
-def test_restore_idempotent_when_no_snapshot(tmp_path: Path):
-    deck_root = tmp_path / "deck"
-    deck_root.mkdir()
-    (deck_root / "index.html").write_text("<html>only-version</html>", encoding="utf-8")
-    # No pre-critique file. Should be a no-op, not an error.
-    restore_pre_critique(deck_root)
-    assert (deck_root / "index.html").read_text() == "<html>only-version</html>"
-
-
-def test_cleanup_removes_snapshot(tmp_path: Path):
-    deck_root = tmp_path / "deck"
-    deck_root.mkdir()
-    (deck_root / "index.html").write_text("<html>v2</html>", encoding="utf-8")
-    (deck_root / "index.pre-critique.html").write_text("<html>v1</html>", encoding="utf-8")
-    from openkb.deck.critic import cleanup_pre_critique
-    cleanup_pre_critique(deck_root)
-    assert not (deck_root / "index.pre-critique.html").exists()
-    # index.html (the live deck) is untouched
-    assert (deck_root / "index.html").read_text() == "<html>v2</html>"
-
-
-def test_cleanup_idempotent_when_no_snapshot(tmp_path: Path):
-    deck_root = tmp_path / "deck"
-    deck_root.mkdir()
-    (deck_root / "index.html").write_text("<html>v1</html>", encoding="utf-8")
-    from openkb.deck.critic import cleanup_pre_critique
-    cleanup_pre_critique(deck_root)  # No snapshot to clean — no exception.
-    assert (deck_root / "index.html").read_text() == "<html>v1</html>"
diff --git a/tests/test_deck_prompt.py b/tests/test_deck_prompt.py
index 298b36aa..0a881618 100644
--- a/tests/test_deck_prompt.py
+++ b/tests/test_deck_prompt.py
@@ -1,32 +1,60 @@
-"""Sanity tests for the deck_create prompt. Verifies file is loadable and
-contains the structural anchors the validator and creator depend on."""
+"""Sanity tests for the built-in deck-editorial skill.
+
+After the skill-system refactor the deck prompt moved from
+``openkb/prompts/deck_create.md`` (a ``str.format``-style template) to
+``skills/openkb-deck-editorial/SKILL.md`` (a standalone Anthropic-style
+skill with YAML frontmatter that ``run_skill`` loads directly). These
+tests pin the structural anchors the validator and generator depend on.
+"""
 from __future__ import annotations
 
-from openkb.prompts import load_prompt
+from pathlib import Path
 
+from openkb.agent.skills import _parse_frontmatter
 
-def test_prompt_loads():
-    text = load_prompt("deck_create")
-    assert isinstance(text, str) and len(text) > 1000
 
+SKILL_MD = (
+    Path(__file__).resolve().parent.parent
+    / "skills"
+    / "openkb-deck-editorial"
+    / "SKILL.md"
+)
 
-def test_prompt_has_placeholders():
-    text = load_prompt("deck_create")
-    assert "{intent}" in text
-    assert "{wiki_schema}" in text
-    assert "{deck_name}" in text
 
+def _load() -> tuple[dict, str]:
+    return _parse_frontmatter(SKILL_MD.read_text(encoding="utf-8"))
 
-def test_prompt_lists_all_allowed_data_types():
-    text = load_prompt("deck_create")
+
+def test_skill_file_present_and_substantive():
+    assert SKILL_MD.is_file(), f"skill file missing at {SKILL_MD}"
+    meta, body = _load()
+    assert meta.get("name") == "openkb-deck-editorial"
+    assert isinstance(meta.get("description"), str) and len(meta["description"]) > 40
+    assert len(body) > 1000, "skill body is suspiciously short"
+
+
+def test_skill_lists_all_allowed_data_types():
+    _, body = _load()
     for t in ("cover", "chapter", "thesis", "quote", "compare", "data", "closing"):
-        assert t in text, f"slide grammar must mention data-type={t}"
+        assert t in body, f"slide grammar must mention data-type={t}"
 
 
-def test_prompt_lists_editorial_monocle_tokens():
-    text = load_prompt("deck_create")
-    # palette values must appear so the agent can copy them verbatim
+def test_skill_lists_editorial_monocle_tokens():
+    _, body = _load()
+    # Palette values must appear so the agent can copy them verbatim.
     for hex_value in ("#f3eee1", "#1a1612", "#a4341c", "#fff3a8"):
-        assert hex_value in text, f"palette token {hex_value} missing"
-    assert "Charter" in text  # serif stack
-    assert "16:9" in text or "aspect-ratio" in text
+        assert hex_value in body, f"palette token {hex_value} missing"
+    assert "Charter" in body  # serif stack
+    assert "16:9" in body or "aspect-ratio" in body
+
+
+def test_skill_description_triggers_on_deck_requests():
+    """The agent picks skills by description matching. The deck skill's
+    description must include the words a user would naturally type."""
+    meta, _ = _load()
+    desc = meta["description"].lower()
+    # at least one explicit trigger word
+    assert any(
+        word in desc
+        for word in ("deck", "slide", "ppt", "presentation", "演示", "幻灯")
+    )
diff --git a/tests/test_deck_tools.py b/tests/test_deck_tools.py
deleted file mode 100644
index c80a1ea1..00000000
--- a/tests/test_deck_tools.py
+++ /dev/null
@@ -1,47 +0,0 @@
-"""Tests for deck-scoped IO tools. Mirrors tests/test_skill_tools.py for write_skill_file."""
-from __future__ import annotations
-
-from pathlib import Path
-
-from openkb.deck.tools import read_deck_file, write_deck_file
-
-
-def test_write_then_read_roundtrip(tmp_path: Path):
-    deck_root = tmp_path / "deck"
-    msg = write_deck_file("index.html", "<html><body>hi</body></html>", str(deck_root))
-    assert msg.startswith("Written:")
-    content = read_deck_file("index.html", str(deck_root))
-    assert "<body>hi</body>" in content
-
-
-def test_write_creates_parent_dirs(tmp_path: Path):
-    deck_root = tmp_path / "deck"
-    write_deck_file("nested/sub/file.txt", "ok", str(deck_root))
-    assert (deck_root / "nested" / "sub" / "file.txt").read_text() == "ok"
-
-
-def test_write_rejects_absolute_path(tmp_path: Path):
-    msg = write_deck_file("/etc/passwd", "pwn", str(tmp_path / "deck"))
-    assert "Access denied" in msg
-    assert not Path("/etc/passwd_test_marker").exists()  # sanity
-
-
-def test_write_rejects_parent_traversal(tmp_path: Path):
-    deck_root = tmp_path / "deck"
-    msg = write_deck_file("../escape.txt", "pwn", str(deck_root))
-    assert "Access denied" in msg
-    assert not (tmp_path / "escape.txt").exists()
-
-
-def test_read_rejects_escape(tmp_path: Path):
-    deck_root = tmp_path / "deck"
-    deck_root.mkdir()
-    msg = read_deck_file("../../etc/passwd", str(deck_root))
-    assert "Access denied" in msg
-
-
-def test_read_missing_file(tmp_path: Path):
-    deck_root = tmp_path / "deck"
-    deck_root.mkdir()
-    msg = read_deck_file("index.html", str(deck_root))
-    assert "not found" in msg.lower()
diff --git a/tests/test_generator.py b/tests/test_generator.py
index faca839b..8a4a2d4a 100644
--- a/tests/test_generator.py
+++ b/tests/test_generator.py
@@ -124,73 +124,8 @@ def test_generator_rejects_podcast_target_type(tmp_path):
         )
 
 
-@pytest.mark.asyncio
-async def test_generator_deck_cleanup_on_critique_success(tmp_path):
-    """When critique=True and validation passes, the pre-critique snapshot
-    must be deleted so it doesn't accumulate across runs."""
-    kb_dir = tmp_path
-    (kb_dir / "wiki").mkdir()
-    (kb_dir / "wiki" / "AGENTS.md").write_text("schema", encoding="utf-8")
-
-    gen = Generator(
-        target_type="deck",
-        name="my-deck",
-        intent="…",
-        kb_dir=kb_dir,
-        model="openai/gpt-4o",
-        critique=True,
-    )
-
-    # Simulate the creator + critic having written both files.
-    gen.output_dir.mkdir(parents=True, exist_ok=True)
-    (gen.output_dir / "index.html").write_text("<html>critic-output</html>", encoding="utf-8")
-    (gen.output_dir / "index.pre-critique.html").write_text("<html>pre-critic</html>", encoding="utf-8")
-
-    with patch("openkb.skill.generator.run_deck_create", new_callable=AsyncMock) as run_dc, \
-         patch("openkb.skill.generator.validate_deck") as v_deck:
-        run_dc.return_value = gen.output_dir
-        v_deck.return_value = DeckValidationResult()  # no errors → success
-        await gen.run()
-
-    # On critique success, the snapshot is cleaned up.
-    assert not (gen.output_dir / "index.pre-critique.html").exists()
-    # The live deck is untouched.
-    assert (gen.output_dir / "index.html").read_text() == "<html>critic-output</html>"
-
-
-@pytest.mark.asyncio
-async def test_generator_deck_restore_on_critique_failure(tmp_path):
-    """When critique=True and validation fails, the pre-critique snapshot
-    must be restored back to index.html and the snapshot kept for inspection."""
-    kb_dir = tmp_path
-    (kb_dir / "wiki").mkdir()
-    (kb_dir / "wiki" / "AGENTS.md").write_text("schema", encoding="utf-8")
-
-    gen = Generator(
-        target_type="deck",
-        name="my-deck",
-        intent="…",
-        kb_dir=kb_dir,
-        model="openai/gpt-4o",
-        critique=True,
-    )
-
-    # Simulate critic having corrupted index.html, with snapshot of original.
-    gen.output_dir.mkdir(parents=True, exist_ok=True)
-    (gen.output_dir / "index.html").write_text("<html>critic-broken</html>", encoding="utf-8")
-    (gen.output_dir / "index.pre-critique.html").write_text("<html>pre-critic-good</html>", encoding="utf-8")
-
-    # First validation reports an error; second (post-restore) is clean.
-    first_result = DeckValidationResult()
-    first_result.errors.append("bad slide count")
-    second_result = DeckValidationResult()
-
-    with patch("openkb.skill.generator.run_deck_create", new_callable=AsyncMock) as run_dc, \
-         patch("openkb.skill.generator.validate_deck", side_effect=[first_result, second_result]):
-        run_dc.return_value = gen.output_dir
-        await gen.run()
-
-    # index.html was restored from the snapshot.
-    assert (gen.output_dir / "index.html").read_text() == "<html>pre-critic-good</html>"
-    # The warning about restore is surfaced.
-    assert any("restored pre-critique draft" in w for w in gen.validation.warnings)
+# Pre-skill-system snapshot/restore Generator tests removed: the
+# html-critic skill patches HTML in place, so there is no longer a
+# pre-critique snapshot to clean up or restore. See
+# tests/test_deck_creator.py::test_run_deck_create_chains_critic_when_critique_true
+# for the equivalent guarantee at the new layer.

From 63b62c29b2efbf0178e4f840a0f55a3ac9917eb9 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Sun, 24 May 2026 09:09:56 +0800
Subject: [PATCH 22/25] fix(deck): close 6 high-confidence findings from
 skill-refactor review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Architectural review (4 parallel Opus auditors) found that the skill_runner
core was already generic, but the deck SURFACE was still fused to
Editorial Monocle. Fixed:

* validator: now takes optional `grammar` param (DeckGrammar TypedDict);
  skill-agnostic by default (only checks file present, parses, ≥5
  slides, self-contained). Third-party deck skills (guizang, swiss)
  now pass validation cleanly. Editorial-specific rules opt-in via
  `EDITORIAL_MONOCLE_GRAMMAR`. (finding #2)
* skills/openkb-deck-editorial/SKILL.md: declares its grammar +
  output_path_template under `od:` frontmatter — `run_skill` reads
  these and applies them post-run.
* run_skill: now honors frontmatter `od.mode`, `od.output_path_template`,
  `od.deck_grammar`. When mode=="deck" and template is set, the runner
  injects the path into intent, verifies the file exists post-run, and
  runs validate_deck with the skill's grammar. Validation result is
  returned via new SkillRunResult dataclass. (findings #4, #5)
* `openkb deck new --skill <name>`: CLI flag accepts any installed deck
  skill (default openkb-deck-editorial). guizang and swiss now usable
  from the scripted CLI, not only freeform chat. (finding #1)
* `/deck new --skill <name>` chat slash: same flag, parsed positionally
  alongside --critique. (finding #1)
* tests/test_read_kb_file.py: 13 new tests mirroring test_write_kb_file
  for the read-side allow-list. Pins refusal of `.openkb/config.yaml`,
  `.env`, `raw/`, `..` traversal, absolute paths. (finding #6)
* Generator deck branch: no longer calls validate_deck directly; just
  propagates run_deck_create's SkillRunResult.validation up. Validation
  is now a property of "this skill declared mode=deck", not of "this
  CLI path was taken".

Existing tests updated:
* tests/test_deck_validator.py: explicit grammar arg on Editorial-
  specific tests; added test_guizang_shape_passes_generic_mode +
  test_missing_cover_ignored_in_generic_mode to pin both modes.
* tests/test_deck_creator.py: mocks return SkillRunResult; new
  test_run_deck_create_honors_skill_name_override for --skill flag.
* tests/test_generator.py: deck dispatch test mocks SkillRunResult.

Below-threshold findings deferred:
* Generator if/else → registry (score 70) — works, just not extensible
  via plugin; future.
* Iteration backup in chat freeform path (score 75) — needs write_kb_file
  hook; separate change.
* run_skill / scan_local_skills / _handle_slash_critique direct tests
  (scores 60-70) — covered indirectly by integration; can add later.

Regression: 538 tests pass (was 523 pre-fix; net +15 = 13 new
read_kb_file tests + 2 new validator-mode tests).
---
 openkb/agent/chat.py                  |  26 +++-
 openkb/agent/skill_runner.py          | 100 +++++++++++-
 openkb/cli.py                         |  17 ++-
 openkb/deck/creator.py                | 116 ++++++++------
 openkb/deck/validator.py              | 209 +++++++++++++++++++-------
 openkb/skill/generator.py             |  26 +++-
 skills/openkb-deck-editorial/SKILL.md |   9 ++
 tests/test_deck_creator.py            | 120 +++++++++------
 tests/test_deck_validator.py          |  58 ++++++-
 tests/test_generator.py               |  20 ++-
 tests/test_read_kb_file.py            | 132 ++++++++++++++++
 11 files changed, 645 insertions(+), 188 deletions(-)
 create mode 100644 tests/test_read_kb_file.py

diff --git a/openkb/agent/chat.py b/openkb/agent/chat.py
index f5a54fdd..2d1a584c 100644
--- a/openkb/agent/chat.py
+++ b/openkb/agent/chat.py
@@ -60,7 +60,7 @@
     "  /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] <name> "<intent>"   Generate an HTML deck 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"
 )
@@ -606,20 +606,29 @@ async def _handle_slash_deck(arg: str, kb_dir: Path, style: Style) -> None:
         _fmt(style, ("class:error", f"Unknown deck subcommand: {sub}. Try /deck new.\n"))
         return
 
-    # Parse optional --critique flag (anywhere among the remaining tokens
-    # is fine, but typically right after `new`).
+    # 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] = []
-    for tok in rest:
+    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] <name> \"<intent>\"\n"))
+            "Usage: /deck new [--critique] [--skill <skill>] <name> \"<intent>\"\n"))
         return
 
     name = filtered[0]
@@ -650,7 +659,11 @@ async def _handle_slash_deck(arg: str, kb_dir: Path, style: Style) -> None:
     model = config.get("model", DEFAULT_CONFIG["model"])
 
     from openkb.skill.generator import Generator
-    _fmt(style, ("class:slash.help", f"Generating deck '{name}'...\n"))
+    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,
@@ -658,6 +671,7 @@ async def _handle_slash_deck(arg: str, kb_dir: Path, style: Style) -> None:
         kb_dir=kb_dir,
         model=model,
         critique=critique,
+        skill_name=skill_name,
     )
     try:
         await gen.run()
diff --git a/openkb/agent/skill_runner.py b/openkb/agent/skill_runner.py
index d3b064bd..1b6f7899 100644
--- a/openkb/agent/skill_runner.py
+++ b/openkb/agent/skill_runner.py
@@ -4,16 +4,30 @@
 agent instructions) is loaded by ``run_skill``, which builds an Agent
 whose ``instructions`` are that body. The agent gets the standard wiki
 read-tool set plus a constrained ``write_file`` tool scoped to
-``wiki/explorations/**`` and ``output/**``.
+``wiki/explorations/**`` and ``output/**``, and ``read_output_or_skill_file``
+for inspecting prior artifacts.
 
 This decouples generators from hard-coded prompts. ``openkb deck new`` /
 ``openkb skill new`` / any future ``openkb <type> new`` command becomes a
 two-line wrapper around ``run_skill(skill_name=..., intent=...)``.
+
+Skill frontmatter that ``run_skill`` honours (all optional; under the
+top-level ``od:`` key):
+
+* ``mode`` — the artifact type. ``"deck"`` triggers deck-specific
+  post-run handling (output-path templating + validation). Unknown modes
+  are accepted; they just don't trigger extra hooks.
+* ``output_path_template`` — a path string with ``{slug}`` placeholder,
+  relative to KB root. When set, ``run_skill`` injects the resolved path
+  into the agent's intent and verifies the file exists post-run.
+* ``deck_grammar`` — passed to :func:`openkb.deck.validator.validate_deck`
+  when ``mode == "deck"``. See that module for the contract.
 """
 from __future__ import annotations
 
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
 
 from agents import Agent, Runner, function_tool
 
@@ -30,6 +44,23 @@ class SkillNotFoundError(RuntimeError):
     """Raised when the requested skill can't be located in any skill root."""
 
 
+@dataclass
+class SkillRunResult:
+    """Outcome of a :func:`run_skill` call.
+
+    ``validation`` is populated only when the skill declared a
+    deck-mode artifact and the post-run validator was therefore invoked;
+    otherwise ``None``. ``output_path`` is the KB-relative path the
+    runner enforced via ``output_path_template``, or ``None`` if the
+    skill left output placement to itself.
+    """
+
+    skill_name: str
+    output_path: Optional[Path] = None
+    validation: Optional[Any] = None  # openkb.deck.validator.ValidationResult
+    metadata: dict = field(default_factory=dict)  # skill's ``od:`` block
+
+
 async def run_skill(
     *,
     skill_name: str,
@@ -39,14 +70,23 @@ async def run_skill(
     language: str = "en",
     max_turns: int = MAX_TURNS,
     seed: Optional[str] = None,
+    slug: Optional[str] = None,
     extra_skill_roots: tuple[str | Path, ...] = (),
-) -> None:
-    """Load skill ``skill_name`` and run it as an agent with ``intent``.
+) -> SkillRunResult:
+    """Load ``skill_name`` and run it as an agent with ``intent``.
+
+    When the skill's frontmatter declares ``od.mode == "deck"`` and
+    ``od.output_path_template`` is set, ``run_skill``:
+
+      1. Templates the path with the provided ``slug``.
+      2. Adds a "Write to: <path>" line to the agent's intent so the
+         skill knows the expected destination.
+      3. After the agent run, checks the file exists and (if the skill
+         declared ``od.deck_grammar``) runs ``validate_deck`` against it.
 
     Args:
         skill_name: Name (frontmatter ``name:``) of the skill to invoke.
-        intent: Natural-language brief for what to produce. Appended to
-            the skill body as a "## User intent" section.
+        intent: Natural-language brief for what to produce.
         kb_dir: KB root. Used both for skill discovery and for the
             agent's wiki read-tools / write-file scoping.
         model: LiteLLM-formatted model string from KB config.
@@ -55,13 +95,21 @@ async def run_skill(
         max_turns: Hard cap on agent loop iterations.
         seed: Optional kick-off user message. Defaults to a short nudge
             that points the agent at its own instructions.
+        slug: Required when the skill declares
+            ``od.output_path_template`` (it substitutes ``{slug}``).
+            Otherwise ignored.
         extra_skill_roots: Additional directories to scan beyond the
             built-in ``<kb>/skills``, ``~/.openkb/skills``,
             ``~/.claude/skills``.
 
+    Returns:
+        A :class:`SkillRunResult` carrying the resolved output path (if
+        any) and the validation result (for deck-mode skills).
+
     Raises:
         SkillNotFoundError: if no skill with ``skill_name`` is found.
-        RuntimeError: if the agent run fails (turn-cap, model error).
+        RuntimeError: on turn-cap, model error, or missing
+            output file after a templated-path run.
     """
     skills = scan_local_skills(kb_dir, extra_roots=extra_skill_roots)
     match = next((s for s in skills if s["name"] == skill_name), None)
@@ -74,7 +122,19 @@ async def run_skill(
         )
 
     skill_md = Path(match["path"]) / "SKILL.md"
-    _meta, body = _parse_frontmatter(skill_md.read_text(encoding="utf-8"))
+    meta, body = _parse_frontmatter(skill_md.read_text(encoding="utf-8"))
+    od_meta: dict = (meta.get("od") or {}) if isinstance(meta, dict) else {}
+
+    # Resolve output path if the skill templated one.
+    output_path: Optional[Path] = None
+    template = od_meta.get("output_path_template")
+    if template and slug:
+        rel = template.format(slug=slug)
+        output_path = (kb_dir / rel).resolve()
+        intent = (
+            f"Output file (write the artifact here, full file in one "
+            f"write_file call): {rel}\n\n{intent}"
+        )
 
     wiki_root = str(kb_dir / "wiki")
     kb_root = str(kb_dir)
@@ -131,3 +191,27 @@ def read_output_or_skill_file(path: str) -> str:
             f"finishing. The intent may be too broad or the wiki too large; "
             f"try a tighter intent or split into smaller skills."
         ) from exc
+
+    result = SkillRunResult(
+        skill_name=skill_name,
+        output_path=output_path,
+        metadata=od_meta if isinstance(od_meta, dict) else {},
+    )
+
+    # Post-run hooks driven by skill frontmatter.
+    if output_path is not None and not output_path.is_file():
+        raise RuntimeError(
+            f"Skill {skill_name!r} finished but did not write the expected "
+            f"output file at {output_path}. The skill is either misconfigured "
+            f"or the wiki lacks content matching the intent."
+        )
+
+    if od_meta.get("mode") == "deck" and output_path is not None:
+        # Lazy import — skill_runner shouldn't pull in deck-specific code
+        # at import time, only when actually running a deck skill.
+        from openkb.deck.validator import DeckGrammar, validate_deck
+
+        grammar: Optional[DeckGrammar] = od_meta.get("deck_grammar")
+        result.validation = validate_deck(output_path.parent, grammar=grammar)
+
+    return result
diff --git a/openkb/cli.py b/openkb/cli.py
index 7c4468f5..04fe3b02 100644
--- a/openkb/cli.py
+++ b/openkb/cli.py
@@ -1934,8 +1934,18 @@ def deck():
     is_flag=True, default=False,
     help="Opt-in second-pass review via a critic agent (slower, higher quality).",
 )
+@click.option(
+    "--skill", "skill_name",
+    metavar="SKILL_NAME",
+    default=None,
+    help=(
+        "Which deck skill to use. Defaults to 'openkb-deck-editorial' "
+        "(the built-in). Pass e.g. 'deck-guizang-editorial' to route to "
+        "a third-party skill installed under ~/.openkb/skills/."
+    ),
+)
 @click.pass_context
-def deck_new(ctx, name, intent, yes_flag, critique_flag):
+def deck_new(ctx, name, intent, yes_flag, critique_flag, skill_name):
     """Generate a new HTML deck from this KB's wiki.
 
     NAME is a kebab-case slug used for the output directory.
@@ -1945,6 +1955,7 @@ def deck_new(ctx, name, intent, yes_flag, critique_flag):
 
       openkb deck new transformers-pitch "Explain attention to engineers"
       openkb deck new transformers-pitch "Explain attention to engineers" --critique
+      openkb deck new transformers-pitch "..." --skill deck-guizang-editorial
     """
     kb_dir = _find_kb_dir(ctx.obj.get("kb_dir_override"))
     if kb_dir is None:
@@ -2007,7 +2018,8 @@ def deck_new(ctx, name, intent, yes_flag, critique_flag):
 
     # Run the generator.
     from openkb.skill.generator import Generator
-    click.echo(f"Generating deck '{name}'...")
+    skill_label = skill_name if skill_name else "openkb-deck-editorial (default)"
+    click.echo(f"Generating deck '{name}' via skill {skill_label}...")
     gen = Generator(
         target_type="deck",
         name=name,
@@ -2015,6 +2027,7 @@ def deck_new(ctx, name, intent, yes_flag, critique_flag):
         kb_dir=kb_dir,
         model=model,
         critique=critique_flag,
+        skill_name=skill_name,
     )
     try:
         asyncio.run(gen.run())
diff --git a/openkb/deck/creator.py b/openkb/deck/creator.py
index a3d12411..e4b8b5c8 100644
--- a/openkb/deck/creator.py
+++ b/openkb/deck/creator.py
@@ -1,17 +1,19 @@
-"""Thin CLI/Generator wrapper around the deck-editorial skill.
-
-The actual deck generation lives in
-``skills/openkb-deck-editorial/SKILL.md`` and runs via
-:func:`openkb.agent.skill_runner.run_skill`. This module exists only to:
-
-* enforce the deck output path convention (``output/decks/<name>/index.html``),
-* check that the skill actually wrote the expected file,
-* (when ``critique=True``) chain the ``openkb-html-critic`` skill on the
-  produced HTML.
-
-Pre-skill-system implementation lived here too (build_deck_create_agent,
-build_deck_critic_agent, snapshot/restore helpers). All deleted — see
-git history before commit 08e95c3 if you need to reference it.
+"""Thin CLI/Generator wrapper around any deck-producing skill.
+
+The actual deck generation lives in skill packages — by default
+``skills/openkb-deck-editorial/SKILL.md``, but the caller may pass
+``skill_name`` to route to a different one (e.g.
+``deck-guizang-editorial`` from open-design). Skill execution runs
+through :func:`openkb.agent.skill_runner.run_skill`, which also handles
+output-path templating and post-run validation based on the skill's
+``od:`` frontmatter.
+
+This module exists only to:
+
+* expose the deck CLI's ``critique`` flag as a second skill call
+  (``openkb-html-critic``) chained after the producer skill,
+* surface a clean ``Path``-returning interface for callers that don't
+  care about skill plumbing.
 """
 from __future__ import annotations
 
@@ -21,13 +23,20 @@
     MAX_TURNS,
     MAX_TURNS_WITH_CRITIQUE,
     SkillNotFoundError,
+    SkillRunResult,
     run_skill,
 )
 from openkb.deck import deck_dir
 
 
+DEFAULT_DECK_SKILL = "openkb-deck-editorial"
+"""Skill name routed to when the CLI / chat doesn't pass ``--skill``."""
+
+CRITIC_SKILL = "openkb-html-critic"
+"""Skill chained after the producer when ``--critique`` is set."""
+
 CRITIC_MAX_TURNS = 40
-"""Critic skill is read-and-patch, not authoring; it converges fast."""
+"""Critic is read-and-patch, not authoring; converges fast."""
 
 
 async def run_deck_create(
@@ -37,65 +46,72 @@ async def run_deck_create(
     intent: str,
     model: str,
     critique: bool,
-) -> Path:
-    """Compile a single deck from the KB's wiki via the deck-editorial skill.
-
-    Returns the deck directory. Raises ``RuntimeError`` if the skill is
-    missing, hits the turn cap, or doesn't write ``index.html``.
-
-    When ``critique=True`` the html-critic skill runs as a second pass on
-    the produced file (CSS specificity bugs, missing nav, failure of
-    self-containment). The critic patches in place; missing critic skill
-    is a soft failure (the deck still ships, just unpatched).
+    skill_name: str = DEFAULT_DECK_SKILL,
+) -> SkillRunResult:
+    """Compile a single deck from the KB's wiki via the chosen skill.
+
+    Args:
+        skill_name: Which deck skill to run. Defaults to the built-in
+            ``openkb-deck-editorial``. Pass ``"deck-guizang-editorial"``
+            etc. to route to a third-party skill installed under
+            ``~/.openkb/skills/``.
+
+    Returns the :class:`SkillRunResult` from the producer skill (carries
+    ``output_path`` and ``validation`` populated by ``run_skill`` per
+    the skill's frontmatter contract).
+
+    Raises ``RuntimeError`` if the skill is missing, hits the turn cap,
+    or doesn't write its declared output path.
+
+    When ``critique=True`` the html-critic skill runs as a second pass
+    on the produced file. Missing critic skill is a soft failure (the
+    deck still ships, just unpatched).
     """
+    # Ensure the conventional deck dir exists. Skills that use
+    # output_path_template = "output/decks/{slug}/index.html" need this;
+    # skills that pick their own location won't be hindered.
     deck_root = deck_dir(kb_dir, deck_name)
     deck_root.mkdir(parents=True, exist_ok=True)
-    target_path = f"output/decks/{deck_name}/index.html"
-
-    builder_intent = (
-        f"Deck slug: {deck_name}\n"
-        f"Write the deck to: {target_path}\n\n"
-        f"User brief:\n{intent}"
-    )
 
     try:
-        await run_skill(
-            skill_name="openkb-deck-editorial",
-            intent=builder_intent,
+        result = await run_skill(
+            skill_name=skill_name,
+            intent=intent,
             kb_dir=kb_dir,
             model=model,
+            slug=deck_name,
             max_turns=MAX_TURNS_WITH_CRITIQUE if critique else MAX_TURNS,
         )
     except SkillNotFoundError as exc:
         raise RuntimeError(
-            f"Required skill 'openkb-deck-editorial' is missing. "
-            f"It ships at skills/openkb-deck-editorial/SKILL.md — "
-            f"ensure it's present or re-install openkb."
+            f"Deck skill {skill_name!r} is not installed. "
+            f"Drop a SKILL.md into ~/.openkb/skills/{skill_name}/ (or "
+            f"<kb>/skills/{skill_name}/) and re-run."
         ) from exc
 
-    if not (deck_root / "index.html").exists():
-        raise RuntimeError(
-            f"Deck generation finished but the skill did not write "
-            f"index.html at {deck_root}. The deck is incomplete; "
-            f"check whether the wiki has content related to your intent."
-        )
-
     if critique:
+        # The producer's output_path tells the critic which file to patch.
+        # If the producer didn't template a path, fall back to the
+        # conventional location.
+        target_path = (
+            result.output_path.relative_to(kb_dir)
+            if result.output_path is not None
+            else Path(f"output/decks/{deck_name}/index.html")
+        )
         critic_intent = (
             f"Critique and patch the HTML deck at: {target_path}\n"
-            f"Original user brief (for context, do not change content):\n{intent}"
+            f"Original user brief (for context, do NOT change content):\n{intent}"
         )
         try:
             await run_skill(
-                skill_name="openkb-html-critic",
+                skill_name=CRITIC_SKILL,
                 intent=critic_intent,
                 kb_dir=kb_dir,
                 model=model,
                 max_turns=CRITIC_MAX_TURNS,
             )
         except SkillNotFoundError:
-            # Critic skill missing is non-fatal — the unpatched deck
-            # is still on disk and usable.
+            # Critic missing is non-fatal — the unpatched deck still ships.
             pass
 
-    return deck_root
+    return result
diff --git a/openkb/deck/validator.py b/openkb/deck/validator.py
index 6293d42d..39cfd1f8 100644
--- a/openkb/deck/validator.py
+++ b/openkb/deck/validator.py
@@ -1,31 +1,79 @@
 """Structural validation for a generated deck.
 
-Mirrors ``openkb/skill/validator.py``'s ``ValidationResult`` shape so
-callers (``Generator.run``, the CLI's error reporter, the chat slash
-command) can format results identically regardless of artifact type.
+Default mode (``grammar=None``) only enforces SKILL-AGNOSTIC invariants:
+file exists, parses as HTML, ≥ 5 ``<section class="slide">`` blocks,
+self-contained (no external link/script/img references), reasonable size.
+
+A skill that wants stricter checks can declare its slide grammar in the
+SKILL.md frontmatter under ``od.deck_grammar`` and pass it as the
+``grammar`` argument. The Editorial Monocle skill does this — its
+grammar names the 7 ``data-type`` values plus the cover/closing
+requirement; guizang / swiss / any community skill simply omit it and
+get the generic validation.
 
-Errors block declare-success; warnings print but allow the deck to ship.
-The file is preserved even on error so the user can inspect the failure.
+Mirrors ``openkb/skill/validator.py``'s ``ValidationResult`` shape so
+callers can format issues identically regardless of artifact type.
 """
 from __future__ import annotations
 
 from dataclasses import dataclass, field
 from html.parser import HTMLParser
 from pathlib import Path
-
-__all__ = ["ALLOWED_DATA_TYPES", "ValidationResult", "validate_deck"]
-
-
-ALLOWED_DATA_TYPES: frozenset[str] = frozenset(
-    {"cover", "chapter", "thesis", "quote", "compare", "data", "closing"}
-)
+from typing import Optional, TypedDict
+
+__all__ = [
+    "ALLOWED_DATA_TYPES",
+    "DeckGrammar",
+    "EDITORIAL_MONOCLE_GRAMMAR",
+    "ValidationResult",
+    "validate_deck",
+]
+
+
+class DeckGrammar(TypedDict, total=False):
+    """Skill-declared rules for slide classification.
+
+    All keys are optional. If a key is missing, the corresponding check
+    is skipped. This is what a skill writer puts under
+    ``frontmatter.od.deck_grammar`` to opt into structural validation.
+
+    Example (Editorial Monocle skill)::
+
+        od:
+          mode: deck
+          deck_grammar:
+            kind_attr: data-type
+            required: [cover, closing]
+            allowed: [cover, chapter, thesis, quote, compare, data, closing]
+            min_distinct: 4
+            max_consecutive_same: 2
+    """
+    kind_attr: str             # attribute name carrying the slide kind (e.g. "data-type")
+    required: list[str]        # kinds that MUST appear at least once
+    allowed: list[str]         # whitelist; anything else is rejected
+    min_distinct: int          # warn if fewer distinct kinds present
+    max_consecutive_same: int  # warn if run-length exceeds this
+
+
+# Editorial Monocle's published grammar. Kept here for the openkb-deck-editorial
+# skill to import (and for tests / docs to reference); third-party skills may
+# define their own or omit grammar entirely.
+EDITORIAL_MONOCLE_GRAMMAR: DeckGrammar = {
+    "kind_attr": "data-type",
+    "required": ["cover", "closing"],
+    "allowed": ["cover", "chapter", "thesis", "quote", "compare", "data", "closing"],
+    "min_distinct": 4,
+    "max_consecutive_same": 2,
+}
+
+# Legacy alias used by tests that pinned the old name. New code should
+# read this from EDITORIAL_MONOCLE_GRAMMAR["allowed"].
+ALLOWED_DATA_TYPES: frozenset[str] = frozenset(EDITORIAL_MONOCLE_GRAMMAR["allowed"])
 
 MAX_FILE_BYTES = 2 * 1024 * 1024  # 2 MB
-MIN_SLIDES_HARD = 5              # error threshold
+MIN_SLIDES_HARD = 5              # error threshold (skill-agnostic)
 MIN_SLIDES_SOFT = 8              # warning threshold (count outside [8,15])
 MAX_SLIDES_SOFT = 15
-MIN_DISTINCT_TYPES = 4
-MAX_CONSECUTIVE_SAME_TYPE = 2    # warning if run-length >= 3
 
 
 @dataclass
@@ -39,18 +87,28 @@ def ok(self) -> bool:
 
 
 class _DeckParser(HTMLParser):
-    """Collects <section class="slide" data-type="..."> blocks and external refs."""
+    """Collects ``<section class="slide">`` blocks and any external refs.
+
+    The slide kind (e.g. ``data-type="cover"`` for Editorial Monocle) is
+    extracted lazily — ``slide_kinds`` is keyed by the configured
+    ``kind_attr``; an empty string means the slide didn't declare a kind
+    under that attr.
+    """
 
-    def __init__(self) -> None:
+    def __init__(self, kind_attr: Optional[str] = None) -> None:
         super().__init__()
-        self.slide_types: list[str] = []   # data-type, in document order
-        self.external_links: list[str] = []  # offending href/src values
-        self._depth_in_slide = 0
+        self.kind_attr = kind_attr
+        self.slide_kinds: list[str] = []
+        self.external_links: list[str] = []
 
     def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
         a = dict(attrs)
         if tag == "section" and "slide" in (a.get("class") or "").split():
-            self.slide_types.append((a.get("data-type") or "").strip())
+            if self.kind_attr is None:
+                # Skill-agnostic: just count slides; kind is irrelevant.
+                self.slide_kinds.append("")
+            else:
+                self.slide_kinds.append((a.get(self.kind_attr) or "").strip())
         elif tag == "link":
             href = (a.get("href") or "").strip()
             if href.startswith(("http://", "https://", "//")):
@@ -65,12 +123,22 @@ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None
                 self.external_links.append(f"<img src={src!r}>")
 
 
-def validate_deck(deck_dir: Path) -> ValidationResult:
+def validate_deck(
+    deck_dir: Path,
+    grammar: Optional[DeckGrammar] = None,
+) -> ValidationResult:
     """Validate the generated deck at ``deck_dir/index.html``.
 
+    Args:
+        deck_dir: Directory containing ``index.html``.
+        grammar: Optional skill-declared grammar (typically read from the
+            skill's frontmatter under ``od.deck_grammar``). When ``None``,
+            only skill-agnostic invariants are checked (file present,
+            parses, ≥5 slides, self-contained). When provided, also
+            enforces required/allowed slide kinds.
+
     Returns a :class:`ValidationResult` with categorised issues. Never
     raises for structural failures — those become entries in ``errors``.
-    Raises only for unforeseen I/O failures the caller would want to see.
     """
     result = ValidationResult()
     index = deck_dir / "index.html"
@@ -87,36 +155,23 @@ def validate_deck(deck_dir: Path) -> ValidationResult:
         )
 
     text = index.read_text(encoding="utf-8", errors="replace")
-    parser = _DeckParser()
+    kind_attr = grammar.get("kind_attr") if grammar else None
+    parser = _DeckParser(kind_attr=kind_attr)
     try:
         parser.feed(text)
         parser.close()
-    except Exception as exc:  # html.parser raises HTMLParseError only on strict mode
+    except Exception as exc:
         result.errors.append(f"index.html failed to parse: {exc}")
         return result
 
-    n = len(parser.slide_types)
+    n = len(parser.slide_kinds)
+
+    # ─── Skill-agnostic checks (always run) ──────────────────────────────────
     if n < MIN_SLIDES_HARD:
         result.errors.append(
             f"deck has {n} slides; need at least {MIN_SLIDES_HARD} "
-            f'<section class="slide" data-type="..."> blocks.'
-        )
-
-    type_set = set(parser.slide_types)
-    if "cover" not in type_set:
-        result.errors.append('missing required slide: data-type="cover".')
-    if "closing" not in type_set:
-        result.errors.append('missing required slide: data-type="closing".')
-
-    illegal = type_set - ALLOWED_DATA_TYPES - {""}
-    if illegal:
-        result.errors.append(
-            f"unknown data-type value(s): {sorted(illegal)!r}. "
-            f"Allowed: {sorted(ALLOWED_DATA_TYPES)!r}."
+            f'<section class="slide"> blocks.'
         )
-    blank = sum(1 for t in parser.slide_types if t == "")
-    if blank:
-        result.errors.append(f"{blank} <section class='slide'> block(s) missing data-type attribute.")
 
     if parser.external_links:
         result.errors.append(
@@ -125,25 +180,65 @@ def validate_deck(deck_dir: Path) -> ValidationResult:
             + (f", … (+{len(parser.external_links) - 3} more)" if len(parser.external_links) > 3 else "")
         )
 
-    # Warnings — non-blocking.
     if n and (n < MIN_SLIDES_SOFT or n > MAX_SLIDES_SOFT):
         result.warnings.append(
             f"slide count {n} outside recommended range [{MIN_SLIDES_SOFT}, {MAX_SLIDES_SOFT}]."
         )
+
+    # ─── Grammar-aware checks (opt-in via skill frontmatter) ─────────────────
+    if grammar is not None:
+        _apply_grammar_checks(parser.slide_kinds, grammar, result)
+
+    return result
+
+
+def _apply_grammar_checks(
+    slide_kinds: list[str],
+    grammar: DeckGrammar,
+    result: ValidationResult,
+) -> None:
+    """Enforce skill-declared slide grammar against parsed kinds."""
+    kind_attr = grammar.get("kind_attr", "data-type")
+    type_set = set(slide_kinds)
+
+    for required in grammar.get("required", []):
+        if required not in type_set:
+            result.errors.append(
+                f'missing required slide: {kind_attr}="{required}".'
+            )
+
+    allowed = grammar.get("allowed")
+    if allowed:
+        allowed_set = set(allowed)
+        illegal = type_set - allowed_set - {""}
+        if illegal:
+            result.errors.append(
+                f"unknown {kind_attr} value(s): {sorted(illegal)!r}. "
+                f"Allowed: {sorted(allowed)!r}."
+            )
+
+    blank = sum(1 for t in slide_kinds if t == "")
+    if blank:
+        result.errors.append(
+            f"{blank} <section class='slide'> block(s) missing {kind_attr} attribute."
+        )
+
     distinct = len(type_set - {""})
-    if n and distinct < MIN_DISTINCT_TYPES:
+    min_distinct = grammar.get("min_distinct")
+    if min_distinct is not None and slide_kinds and distinct < min_distinct:
         result.warnings.append(
-            f"only {distinct} distinct data-type(s) used; recommend ≥ {MIN_DISTINCT_TYPES} for visual variety."
+            f"only {distinct} distinct {kind_attr} value(s) used; "
+            f"recommend ≥ {min_distinct} for visual variety."
         )
-    # Run-length: warn on any run >= MAX_CONSECUTIVE_SAME_TYPE + 1.
-    run = 1
-    for prev, cur in zip(parser.slide_types, parser.slide_types[1:]):
-        run = run + 1 if cur == prev and cur != "" else 1
-        if run > MAX_CONSECUTIVE_SAME_TYPE:
-            result.warnings.append(
-                f"{run} consecutive slides with data-type={cur!r}; break up runs of "
-                f"3+ same type to avoid visual monotony."
-            )
-            break  # one warning is enough; agent will read it and revise
 
-    return result
+    max_run = grammar.get("max_consecutive_same")
+    if max_run is not None:
+        run = 1
+        for prev, cur in zip(slide_kinds, slide_kinds[1:]):
+            run = run + 1 if cur == prev and cur != "" else 1
+            if run > max_run:
+                result.warnings.append(
+                    f"{run} consecutive slides with {kind_attr}={cur!r}; "
+                    f"break up runs of {max_run + 1}+ same type to avoid visual monotony."
+                )
+                break
diff --git a/openkb/skill/generator.py b/openkb/skill/generator.py
index 8fa54bcd..2f31e127 100644
--- a/openkb/skill/generator.py
+++ b/openkb/skill/generator.py
@@ -20,11 +20,8 @@
 from typing import Literal, Union
 
 from openkb.deck import deck_dir
-from openkb.deck.creator import run_deck_create
-from openkb.deck.validator import (
-    ValidationResult as DeckValidationResult,
-    validate_deck,
-)
+from openkb.deck.creator import DEFAULT_DECK_SKILL, run_deck_create
+from openkb.deck.validator import ValidationResult as DeckValidationResult
 from openkb.skill import skill_dir
 from openkb.skill.creator import run_skill_create
 from openkb.skill.marketplace import regenerate_marketplace
@@ -61,7 +58,13 @@ def __init__(
         kb_dir: Path,
         model: str,
         critique: bool = False,
+        skill_name: str | None = None,
     ) -> None:
+        """Args:
+            skill_name: For ``target_type="deck"``, which deck skill to use.
+                Defaults to :data:`openkb.deck.creator.DEFAULT_DECK_SKILL`
+                (``"openkb-deck-editorial"``). Ignored for skill target.
+        """
         if target_type not in ("skill", "deck"):
             raise ValueError(
                 f"Unknown target_type {target_type!r}. v0.3 supports 'skill' and 'deck'."
@@ -72,6 +75,7 @@ def __init__(
         self.kb_dir = kb_dir
         self.model = model
         self.critique = critique
+        self.skill_name = skill_name or DEFAULT_DECK_SKILL
         self.output_dir = (
             deck_dir(kb_dir, name) if target_type == "deck" else skill_dir(kb_dir, name)
         )
@@ -82,7 +86,9 @@ async def run(self) -> Path:
 
         Side-effects, in order: compile → validate → (skill only) publish
         manifest. ``self.validation`` holds the result so callers can
-        surface issues without re-running the validator.
+        surface issues without re-running the validator. For deck target,
+        validation runs inside ``run_skill`` via the producing skill's
+        frontmatter-declared grammar; we propagate it up.
         """
         if self.target_type == "skill":
             await run_skill_create(
@@ -96,12 +102,16 @@ async def run(self) -> Path:
             return self.output_dir
 
         # target_type == "deck"
-        await run_deck_create(
+        deck_result = await run_deck_create(
             kb_dir=self.kb_dir,
             deck_name=self.name,
             intent=self.intent,
             model=self.model,
             critique=self.critique,
+            skill_name=self.skill_name,
         )
-        self.validation = validate_deck(self.output_dir)
+        # run_deck_create returns a SkillRunResult-like (or Path) — use its
+        # validation if present; otherwise fall back to None (skill didn't
+        # declare a grammar to validate against).
+        self.validation = deck_result.validation
         return self.output_dir
diff --git a/skills/openkb-deck-editorial/SKILL.md b/skills/openkb-deck-editorial/SKILL.md
index 0b8d2fe4..d314aafe 100644
--- a/skills/openkb-deck-editorial/SKILL.md
+++ b/skills/openkb-deck-editorial/SKILL.md
@@ -8,6 +8,15 @@ description: |
   opened in a browser, full-screened, and shared. Does NOT apply to
   generating skills (that's `openkb skill new`), long-form research reports,
   or interactive prototypes.
+od:
+  mode: deck
+  output_path_template: "output/decks/{slug}/index.html"
+  deck_grammar:
+    kind_attr: data-type
+    required: [cover, closing]
+    allowed: [cover, chapter, thesis, quote, compare, data, closing]
+    min_distinct: 4
+    max_consecutive_same: 2
 ---
 
 # Editorial Monocle deck skill
diff --git a/tests/test_deck_creator.py b/tests/test_deck_creator.py
index 0d380cc3..574a8de3 100644
--- a/tests/test_deck_creator.py
+++ b/tests/test_deck_creator.py
@@ -6,8 +6,8 @@
 commit 08e95c3 if you need the originals.
 
 The remaining surface to test is small: ``run_deck_create`` is a thin
-wrapper that calls ``run_skill`` (mocked here), checks the output file
-exists, and optionally chains the critic skill.
+wrapper that calls ``run_skill`` (mocked here), returns the producer
+skill's ``SkillRunResult``, and optionally chains the critic skill.
 """
 from __future__ import annotations
 
@@ -16,8 +16,13 @@
 
 import pytest
 
-from openkb.agent.skill_runner import SkillNotFoundError
-from openkb.deck.creator import CRITIC_MAX_TURNS, run_deck_create
+from openkb.agent.skill_runner import SkillNotFoundError, SkillRunResult
+from openkb.deck.creator import (
+    CRITIC_MAX_TURNS,
+    CRITIC_SKILL,
+    DEFAULT_DECK_SKILL,
+    run_deck_create,
+)
 
 
 def _make_kb(tmp_path: Path) -> Path:
@@ -28,7 +33,7 @@ def _make_kb(tmp_path: Path) -> Path:
 
 
 def _write_index(kb_dir: Path, deck_name: str, body: str = "<html></html>") -> Path:
-    """Simulate the deck-editorial skill writing index.html."""
+    """Simulate the producer skill writing index.html."""
     out = kb_dir / "output" / "decks" / deck_name
     out.mkdir(parents=True, exist_ok=True)
     p = out / "index.html"
@@ -36,13 +41,29 @@ def _write_index(kb_dir: Path, deck_name: str, body: str = "<html></html>") -> P
     return p
 
 
+def _producer_result(kb_dir: Path, deck_name: str) -> SkillRunResult:
+    """Build the SkillRunResult ``run_skill`` would return for the producer."""
+    return SkillRunResult(
+        skill_name=DEFAULT_DECK_SKILL,
+        output_path=(kb_dir / "output" / "decks" / deck_name / "index.html").resolve(),
+        validation=None,  # validator is mocked elsewhere; not relevant here
+        metadata={"mode": "deck"},
+    )
+
+
+def _critic_result() -> SkillRunResult:
+    return SkillRunResult(skill_name=CRITIC_SKILL, output_path=None, validation=None)
+
+
 @pytest.mark.asyncio
-async def test_run_deck_create_calls_editorial_skill(tmp_path: Path):
+async def test_run_deck_create_calls_editorial_skill_by_default(tmp_path: Path):
     kb_dir = _make_kb(tmp_path)
 
-    async def fake_skill(skill_name, intent, **_):
-        if skill_name == "openkb-deck-editorial":
+    async def fake_skill(skill_name, intent, **kw):
+        if skill_name == DEFAULT_DECK_SKILL:
             _write_index(kb_dir, "test-deck")
+            return _producer_result(kb_dir, "test-deck")
+        return _critic_result()
 
     with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)) as run_skill:
         result = await run_deck_create(
@@ -53,13 +74,37 @@ async def fake_skill(skill_name, intent, **_):
             critique=False,
         )
 
-    assert result == kb_dir / "output" / "decks" / "test-deck"
-    assert (result / "index.html").is_file()
-    # exactly one skill call (no critic when critique=False)
+    # Producer skill ran with the default name + correct slug.
     assert run_skill.await_count == 1
-    args, kwargs = run_skill.call_args
-    assert kwargs["skill_name"] == "openkb-deck-editorial"
-    assert "test-deck" in kwargs["intent"]
+    kwargs = run_skill.call_args.kwargs
+    assert kwargs["skill_name"] == DEFAULT_DECK_SKILL
+    assert kwargs["slug"] == "test-deck"
+    # Return value is the producer SkillRunResult.
+    assert isinstance(result, SkillRunResult)
+    assert result.skill_name == DEFAULT_DECK_SKILL
+
+
+@pytest.mark.asyncio
+async def test_run_deck_create_honors_skill_name_override(tmp_path: Path):
+    """When the caller passes ``skill_name=...`` (e.g. CLI ``--skill``),
+    the producer skill switches and the path layout still applies."""
+    kb_dir = _make_kb(tmp_path)
+
+    async def fake_skill(skill_name, intent, **kw):
+        _write_index(kb_dir, "test-deck")
+        return _producer_result(kb_dir, "test-deck")
+
+    with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)) as run_skill:
+        await run_deck_create(
+            kb_dir=kb_dir,
+            deck_name="test-deck",
+            intent="A test deck.",
+            model="openai/gpt-4o",
+            critique=False,
+            skill_name="deck-guizang-editorial",
+        )
+
+    assert run_skill.call_args.kwargs["skill_name"] == "deck-guizang-editorial"
 
 
 @pytest.mark.asyncio
@@ -67,10 +112,12 @@ async def test_run_deck_create_chains_critic_when_critique_true(tmp_path: Path):
     kb_dir = _make_kb(tmp_path)
     calls: list[str] = []
 
-    async def fake_skill(skill_name, intent, **_):
+    async def fake_skill(skill_name, intent, **kw):
         calls.append(skill_name)
-        if skill_name == "openkb-deck-editorial":
+        if skill_name == DEFAULT_DECK_SKILL:
             _write_index(kb_dir, "test-deck")
+            return _producer_result(kb_dir, "test-deck")
+        return _critic_result()
 
     with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)):
         await run_deck_create(
@@ -81,7 +128,7 @@ async def fake_skill(skill_name, intent, **_):
             critique=True,
         )
 
-    assert calls == ["openkb-deck-editorial", "openkb-html-critic"]
+    assert calls == [DEFAULT_DECK_SKILL, CRITIC_SKILL]
 
 
 @pytest.mark.asyncio
@@ -91,8 +138,10 @@ async def test_run_deck_create_critic_max_turns(tmp_path: Path):
     kb_dir = _make_kb(tmp_path)
 
     async def fake_skill(skill_name, intent, **kw):
-        if skill_name == "openkb-deck-editorial":
+        if skill_name == DEFAULT_DECK_SKILL:
             _write_index(kb_dir, "test-deck")
+            return _producer_result(kb_dir, "test-deck")
+        return _critic_result()
 
     with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)) as run_skill:
         await run_deck_create(
@@ -104,7 +153,7 @@ async def fake_skill(skill_name, intent, **kw):
         )
 
     critic_call = run_skill.call_args_list[1]
-    assert critic_call.kwargs["skill_name"] == "openkb-html-critic"
+    assert critic_call.kwargs["skill_name"] == CRITIC_SKILL
     assert critic_call.kwargs["max_turns"] == CRITIC_MAX_TURNS
 
 
@@ -116,26 +165,7 @@ async def missing_skill(**_):
         raise SkillNotFoundError("not installed")
 
     with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=missing_skill)):
-        with pytest.raises(RuntimeError, match="openkb-deck-editorial"):
-            await run_deck_create(
-                kb_dir=kb_dir,
-                deck_name="test-deck",
-                intent="A test deck.",
-                model="openai/gpt-4o",
-                critique=False,
-            )
-
-
-@pytest.mark.asyncio
-async def test_run_deck_create_raises_when_html_missing(tmp_path: Path):
-    """If the skill returns but no index.html was written, error out."""
-    kb_dir = _make_kb(tmp_path)
-
-    async def fake_skill(**_):
-        return  # no file written
-
-    with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)):
-        with pytest.raises(RuntimeError, match="did not write index.html"):
+        with pytest.raises(RuntimeError, match="not installed"):
             await run_deck_create(
                 kb_dir=kb_dir,
                 deck_name="test-deck",
@@ -151,11 +181,11 @@ async def test_run_deck_create_tolerates_missing_critic(tmp_path: Path):
     deck is still on disk and usable."""
     kb_dir = _make_kb(tmp_path)
 
-    async def fake_skill(skill_name, **_):
-        if skill_name == "openkb-deck-editorial":
+    async def fake_skill(skill_name, **kw):
+        if skill_name == DEFAULT_DECK_SKILL:
             _write_index(kb_dir, "test-deck")
-        else:
-            raise SkillNotFoundError("critic not installed")
+            return _producer_result(kb_dir, "test-deck")
+        raise SkillNotFoundError("critic not installed")
 
     with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)):
         result = await run_deck_create(
@@ -166,4 +196,6 @@ async def fake_skill(skill_name, **_):
             critique=True,
         )
 
-    assert (result / "index.html").is_file()
+    assert isinstance(result, SkillRunResult)
+    # File is still on disk despite critic failure
+    assert (kb_dir / "output" / "decks" / "test-deck" / "index.html").is_file()
diff --git a/tests/test_deck_validator.py b/tests/test_deck_validator.py
index 67a90fba..89594b24 100644
--- a/tests/test_deck_validator.py
+++ b/tests/test_deck_validator.py
@@ -1,10 +1,25 @@
-"""Tests for the deck validator. No LLM; pure structural checks."""
+"""Tests for the deck validator. No LLM; pure structural checks.
+
+Post-refactor the validator runs in two modes:
+
+* **generic** (``grammar=None``) — only skill-agnostic invariants
+  (file exists, parses, ≥5 ``<section class="slide">`` blocks,
+  self-contained). Used when a skill doesn't declare its slide grammar.
+
+* **grammar-aware** — skill passes its frontmatter
+  ``od.deck_grammar`` (``EDITORIAL_MONOCLE_GRAMMAR`` here). Adds
+  required/allowed-kind checks.
+
+Each test below explicitly picks a mode so the contract for both
+surfaces is pinned.
+"""
 from __future__ import annotations
 
 from pathlib import Path
 
 from openkb.deck.validator import (
     ALLOWED_DATA_TYPES,
+    EDITORIAL_MONOCLE_GRAMMAR,
     ValidationResult,
     validate_deck,
 )
@@ -65,29 +80,56 @@ def test_too_few_slides(tmp_path: Path):
 
 
 def test_missing_cover(tmp_path: Path):
+    """Grammar-aware mode: missing required "cover" is an error."""
     html = GOOD_DECK.replace('data-type="cover"', 'data-type="thesis"')
-    result = validate_deck(_write(tmp_path, html))
+    result = validate_deck(_write(tmp_path, html), grammar=EDITORIAL_MONOCLE_GRAMMAR)
     assert any('"cover"' in e for e in result.errors)
 
 
+def test_missing_cover_ignored_in_generic_mode(tmp_path: Path):
+    """Generic mode: missing-cover is NOT an error — third-party deck
+    skills aren't required to use the Editorial Monocle data-type vocabulary."""
+    html = GOOD_DECK.replace('data-type="cover"', 'data-type="thesis"')
+    result = validate_deck(_write(tmp_path, html))
+    assert not any('"cover"' in e for e in result.errors)
+
+
 def test_missing_closing(tmp_path: Path):
     html = GOOD_DECK.replace('data-type="closing"', 'data-type="thesis"')
-    result = validate_deck(_write(tmp_path, html))
+    result = validate_deck(_write(tmp_path, html), grammar=EDITORIAL_MONOCLE_GRAMMAR)
     assert any('"closing"' in e for e in result.errors)
 
 
 def test_unknown_data_type(tmp_path: Path):
     html = GOOD_DECK.replace('data-type="quote"', 'data-type="hero-banner"')
-    result = validate_deck(_write(tmp_path, html))
+    result = validate_deck(_write(tmp_path, html), grammar=EDITORIAL_MONOCLE_GRAMMAR)
     assert any("hero-banner" in e for e in result.errors)
 
 
 def test_missing_data_type_attr(tmp_path: Path):
     html = GOOD_DECK.replace('data-type="quote"', '')
-    result = validate_deck(_write(tmp_path, html))
+    result = validate_deck(_write(tmp_path, html), grammar=EDITORIAL_MONOCLE_GRAMMAR)
     assert any("missing data-type" in e for e in result.errors)
 
 
+def test_guizang_shape_passes_generic_mode(tmp_path: Path):
+    """A third-party deck (no data-type, uses CSS class for kind) must
+    pass the default (skill-agnostic) validator. Confirms #2 in the
+    architectural-review fix list."""
+    guizang_shape = (
+        "<html><body>"
+        '<section class="slide hero active"><h1>Cover</h1></section>'
+        '<section class="slide act inverse"><h1>Act 1</h1></section>'
+        '<section class="slide grid6"><div>Numbers</div></section>'
+        '<section class="slide two-col"><div>L</div><div>R</div></section>'
+        '<section class="slide q inverse"><h2>?</h2></section>'
+        '<section class="slide hero inverse"><h1>Close</h1></section>'
+        "</body></html>"
+    )
+    result = validate_deck(_write(tmp_path, guizang_shape))
+    assert result.errors == [], f"unexpected errors: {result.errors}"
+
+
 def test_external_link_blocks(tmp_path: Path):
     html = GOOD_DECK.replace(
         "</head>",
@@ -145,7 +187,7 @@ def test_run_of_3_same_type_warning(tmp_path: Path):
         '<section class="slide" data-type="closing"></section>'
         "</body></html>"
     )
-    result = validate_deck(_write(tmp_path, html))
+    result = validate_deck(_write(tmp_path, html), grammar=EDITORIAL_MONOCLE_GRAMMAR)
     assert result.errors == []
     assert any("consecutive" in w for w in result.warnings)
 
@@ -159,7 +201,7 @@ def test_low_distinct_types_warning(tmp_path: Path):
         + '<section class="slide" data-type="closing"></section>'
         "</body></html>"
     )
-    result = validate_deck(_write(tmp_path, html))
+    result = validate_deck(_write(tmp_path, html), grammar=EDITORIAL_MONOCLE_GRAMMAR)
     # Errors fine; this run-length and distinct-count will both warn.
     assert any("distinct data-type" in w for w in result.warnings)
 
@@ -168,7 +210,7 @@ def test_no_slides_no_distinct_warning(tmp_path: Path):
     # A deck with zero slides already produces hard errors; the distinct-type
     # warning ("only 0 distinct…") is noise on an empty deck and is suppressed.
     html = "<html><body></body></html>"
-    result = validate_deck(_write(tmp_path, html))
+    result = validate_deck(_write(tmp_path, html), grammar=EDITORIAL_MONOCLE_GRAMMAR)
     assert not any("distinct data-type" in w for w in result.warnings)
 
 
diff --git a/tests/test_generator.py b/tests/test_generator.py
index 8a4a2d4a..4ce9f145 100644
--- a/tests/test_generator.py
+++ b/tests/test_generator.py
@@ -80,11 +80,20 @@ async def test_generator_deck_dispatches_to_deck_creator(tmp_path):
         critique=False,
     )
 
+    # Post-refactor: validate_deck moved into run_skill (called inside
+    # run_deck_create). Generator just propagates the SkillRunResult's
+    # validation up to self.validation.
+    from openkb.agent.skill_runner import SkillRunResult
+    fake_run_result = SkillRunResult(
+        skill_name="openkb-deck-editorial",
+        output_path=gen.output_dir / "index.html",
+        validation=DeckValidationResult(),
+        metadata={"mode": "deck"},
+    )
+
     with patch("openkb.skill.generator.run_deck_create", new_callable=AsyncMock) as run_dc, \
-         patch("openkb.skill.generator.regenerate_marketplace") as regen, \
-         patch("openkb.skill.generator.validate_deck") as v_deck:
-        run_dc.return_value = gen.output_dir
-        v_deck.return_value = DeckValidationResult()
+         patch("openkb.skill.generator.regenerate_marketplace") as regen:
+        run_dc.return_value = fake_run_result
         result = await gen.run()
 
     run_dc.assert_awaited_once_with(
@@ -93,10 +102,11 @@ async def test_generator_deck_dispatches_to_deck_creator(tmp_path):
         intent="…",
         model="openai/gpt-4o",
         critique=False,
+        skill_name="openkb-deck-editorial",
     )
-    v_deck.assert_called_once_with(gen.output_dir)
     regen.assert_not_called()  # marketplace is skill-only
     assert result == gen.output_dir
+    assert gen.validation is fake_run_result.validation
 
 
 @pytest.mark.asyncio
diff --git a/tests/test_read_kb_file.py b/tests/test_read_kb_file.py
new file mode 100644
index 00000000..1d67f545
--- /dev/null
+++ b/tests/test_read_kb_file.py
@@ -0,0 +1,132 @@
+"""Regression tests for ``openkb.agent.tools.read_kb_file``.
+
+Symmetric to :mod:`tests.test_write_kb_file`. ``read_kb_file`` is the
+read-side allow-list exposed to skill agents via the
+``read_output_or_skill_file`` function tool in
+``openkb.agent.skill_runner``. It controls what files the agent can
+inspect — particularly that it **cannot** see ``.openkb/config.yaml``
+(which contains the LLM API key path), ``.env``, or anything outside
+``wiki/``, ``output/``, ``skills/``.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from openkb.agent.tools import read_kb_file
+
+
+@pytest.fixture
+def kb_root(tmp_path: Path) -> str:
+    return str(tmp_path)
+
+
+def test_rejects_empty_path(kb_root: str) -> None:
+    result = read_kb_file("", kb_root)
+    assert result.startswith("Access denied")
+
+
+def test_rejects_path_escape_via_dotdot(kb_root: str, tmp_path: Path) -> None:
+    """Even if the relative path resolves outside kb_root via ``..``,
+    the guard must reject it before reading anything."""
+    # Create a secret file outside the KB
+    secret = tmp_path.parent / "secret.txt"
+    secret.write_text("API_KEY=xxx")
+    try:
+        result = read_kb_file("../secret.txt", kb_root)
+        assert result.startswith("Access denied")
+    finally:
+        secret.unlink(missing_ok=True)
+
+
+def test_rejects_absolute_path_outside_kb(kb_root: str) -> None:
+    result = read_kb_file("/etc/passwd", kb_root)
+    assert result.startswith("Access denied")
+
+
+def test_rejects_dotopenkb_config(kb_root: str, tmp_path: Path) -> None:
+    """The .openkb/ directory holds the user's model config and is the
+    canonical place an attacker would aim for. Must be inaccessible."""
+    (tmp_path / ".openkb").mkdir()
+    (tmp_path / ".openkb" / "config.yaml").write_text("model: gpt-5.4\n")
+    result = read_kb_file(".openkb/config.yaml", kb_root)
+    assert result.startswith("Access denied")
+
+
+def test_rejects_env_file(kb_root: str, tmp_path: Path) -> None:
+    """``.env`` holds API keys; must not be readable by skill agents."""
+    (tmp_path / ".env").write_text("OPENAI_API_KEY=sk-xxx")
+    result = read_kb_file(".env", kb_root)
+    assert result.startswith("Access denied")
+
+
+def test_rejects_raw_dir(kb_root: str, tmp_path: Path) -> None:
+    """The ``raw/`` directory holds pre-ingest source documents — not
+    in the read allow-list."""
+    (tmp_path / "raw").mkdir()
+    (tmp_path / "raw" / "doc.pdf").write_bytes(b"PDF bytes")
+    result = read_kb_file("raw/doc.pdf", kb_root)
+    assert result.startswith("Access denied")
+
+
+def test_rejects_bare_kb_root(kb_root: str) -> None:
+    """A bare empty/root path must be rejected."""
+    result = read_kb_file(".", kb_root)
+    # Either rejected as escape or as empty-after-relative — either is
+    # a refusal, which is what we want.
+    assert result.startswith("Access denied") or "not a file" in result.lower()
+
+
+def test_returns_not_found_for_missing_allowed_path(kb_root: str, tmp_path: Path) -> None:
+    """Inside the allow-list but file missing — clear error, no leak."""
+    (tmp_path / "output").mkdir()
+    result = read_kb_file("output/decks/missing/index.html", kb_root)
+    assert "not found" in result.lower()
+
+
+def test_reads_wiki_file(kb_root: str, tmp_path: Path) -> None:
+    (tmp_path / "wiki").mkdir()
+    target = tmp_path / "wiki" / "index.md"
+    target.write_text("# Wiki content", encoding="utf-8")
+    result = read_kb_file("wiki/index.md", kb_root)
+    assert result == "# Wiki content"
+
+
+def test_reads_output_file(kb_root: str, tmp_path: Path) -> None:
+    """The whole point of ``read_kb_file`` (vs the existing wiki-only
+    reader): skill agents need to inspect their own prior outputs to
+    critique / iterate. Confirm ``output/`` is in the read scope."""
+    out = tmp_path / "output" / "decks" / "foo"
+    out.mkdir(parents=True)
+    (out / "index.html").write_text("<html>deck content</html>", encoding="utf-8")
+    result = read_kb_file("output/decks/foo/index.html", kb_root)
+    assert "deck content" in result
+
+
+def test_reads_skill_file(kb_root: str, tmp_path: Path) -> None:
+    """Skill bodies must be readable so a meta-skill can introspect
+    another skill (rare but legitimate use)."""
+    sk = tmp_path / "skills" / "my-skill"
+    sk.mkdir(parents=True)
+    (sk / "SKILL.md").write_text("---\nname: my-skill\n---\nbody", encoding="utf-8")
+    result = read_kb_file("skills/my-skill/SKILL.md", kb_root)
+    assert "name: my-skill" in result
+
+
+def test_rejects_relative_traversal_inside_allow_list(kb_root: str, tmp_path: Path) -> None:
+    """`output/../.env` must NOT be allowed even though it starts with
+    `output/`. The resolve-then-check pattern handles this; pin it."""
+    (tmp_path / ".env").write_text("OPENAI_API_KEY=sk-xxx")
+    (tmp_path / "output").mkdir()
+    result = read_kb_file("output/../.env", kb_root)
+    assert result.startswith("Access denied")
+
+
+def test_directory_target_returns_not_found(kb_root: str, tmp_path: Path) -> None:
+    """If the path resolves to a directory inside the allow-list, the
+    reader treats it as not-a-file rather than crashing."""
+    (tmp_path / "output" / "decks").mkdir(parents=True)
+    result = read_kb_file("output/decks", kb_root)
+    # Directory exists but is not a file — should return a clear message.
+    assert "not found" in result.lower() or "not a file" in result.lower()

From 916b93844cc1750f9aa196d5428dff5a2f072f29 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Sun, 24 May 2026 09:27:28 +0800
Subject: [PATCH 23/25] fix(deck): code-quality bot findings + macOS /tmp
 symlink regression
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR review bot flagged 3 CodeQL alerts; smoke test caught a 4th:

* openkb/agent/skill_runner.py: drop unused `Agent` import (we only use
  Runner and function_tool).
* tests/test_deck_cli.py: drop unused `pytest` import.
* tests/test_deck_validator.py: drop the inline `import openkb.deck.validator
  as v` — the module is already imported via `from openkb.deck.validator
  import ...` at the top. Use `monkeypatch.setattr("openkb.deck.validator.
  MAX_FILE_BYTES", 100)` instead so there's one canonical reference.
* openkb/deck/creator.py: when chaining the critic skill,
  `result.output_path.relative_to(kb_dir)` blew up on macOS because
  `run_skill` returns a `.resolve()`-d path (e.g. `/private/tmp/.../`)
  while `kb_dir` is still the symlink form (`/tmp/.../`). Resolve
  kb_dir before the relative_to call. Caught by a manual e2e smoke
  test, NOT by the existing suite — pinned with a new
  `test_run_deck_create_critique_handles_symlinked_tmp` regression.

539 tests pass.
---
 openkb/agent/skill_runner.py |  2 +-
 openkb/deck/creator.py       |  7 ++++++-
 tests/test_deck_cli.py       |  1 -
 tests/test_deck_creator.py   | 32 ++++++++++++++++++++++++++++++++
 tests/test_deck_validator.py | 10 ++++++----
 5 files changed, 45 insertions(+), 7 deletions(-)

diff --git a/openkb/agent/skill_runner.py b/openkb/agent/skill_runner.py
index 1b6f7899..a5825314 100644
--- a/openkb/agent/skill_runner.py
+++ b/openkb/agent/skill_runner.py
@@ -29,7 +29,7 @@
 from pathlib import Path
 from typing import Any, Optional
 
-from agents import Agent, Runner, function_tool
+from agents import Runner, function_tool
 
 from openkb.agent.query import build_query_agent
 from openkb.agent.skills import _parse_frontmatter, scan_local_skills
diff --git a/openkb/deck/creator.py b/openkb/deck/creator.py
index e4b8b5c8..0c7d26e5 100644
--- a/openkb/deck/creator.py
+++ b/openkb/deck/creator.py
@@ -93,8 +93,13 @@ async def run_deck_create(
         # The producer's output_path tells the critic which file to patch.
         # If the producer didn't template a path, fall back to the
         # conventional location.
+        #
+        # ``result.output_path`` is already ``.resolve()``-d by run_skill;
+        # ``kb_dir`` may still hold an un-resolved form (e.g. ``/tmp/...``
+        # on macOS where ``/tmp`` symlinks to ``/private/tmp``). Resolve
+        # the KB root too so ``relative_to`` doesn't trip on the symlink.
         target_path = (
-            result.output_path.relative_to(kb_dir)
+            result.output_path.relative_to(kb_dir.resolve())
             if result.output_path is not None
             else Path(f"output/decks/{deck_name}/index.html")
         )
diff --git a/tests/test_deck_cli.py b/tests/test_deck_cli.py
index 788d3488..e29cce8e 100644
--- a/tests/test_deck_cli.py
+++ b/tests/test_deck_cli.py
@@ -4,7 +4,6 @@
 from pathlib import Path
 from unittest.mock import AsyncMock, patch
 
-import pytest
 from click.testing import CliRunner
 
 from openkb.cli import cli
diff --git a/tests/test_deck_creator.py b/tests/test_deck_creator.py
index 574a8de3..2b812318 100644
--- a/tests/test_deck_creator.py
+++ b/tests/test_deck_creator.py
@@ -175,6 +175,38 @@ async def missing_skill(**_):
             )
 
 
+@pytest.mark.asyncio
+async def test_run_deck_create_critique_handles_symlinked_tmp(tmp_path: Path):
+    """Regression: on macOS ``/tmp`` symlinks to ``/private/tmp`` so
+    ``output_path`` comes back resolved while ``kb_dir`` is still the
+    symlink form. ``relative_to`` must not blow up — both must resolve
+    before comparing. Caught in smoke testing the e2e flow."""
+    kb_dir = _make_kb(tmp_path)
+    # output_path resolved to a deeper-named absolute path (simulates
+    # the macOS /tmp -> /private/tmp situation)
+    resolved_target = (kb_dir / "output" / "decks" / "test-deck" / "index.html").resolve()
+
+    async def fake_skill(skill_name, intent, **kw):
+        if skill_name == DEFAULT_DECK_SKILL:
+            _write_index(kb_dir, "test-deck")
+            return SkillRunResult(
+                skill_name=DEFAULT_DECK_SKILL,
+                output_path=resolved_target,
+                metadata={"mode": "deck"},
+            )
+        return _critic_result()
+
+    with patch("openkb.deck.creator.run_skill", new=AsyncMock(side_effect=fake_skill)):
+        # critique=True is what exercises the relative_to call
+        await run_deck_create(
+            kb_dir=kb_dir,
+            deck_name="test-deck",
+            intent="t",
+            model="m",
+            critique=True,
+        )
+
+
 @pytest.mark.asyncio
 async def test_run_deck_create_tolerates_missing_critic(tmp_path: Path):
     """Critic skill not installed shouldn't kill the run — the unpatched
diff --git a/tests/test_deck_validator.py b/tests/test_deck_validator.py
index 89594b24..2ef6cb58 100644
--- a/tests/test_deck_validator.py
+++ b/tests/test_deck_validator.py
@@ -215,9 +215,11 @@ def test_no_slides_no_distinct_warning(tmp_path: Path):
 
 
 def test_oversize_file_warning(tmp_path: Path, monkeypatch):
-    # Inject a fake stat() so we don't actually allocate 2MB.
-    import openkb.deck.validator as v
-
-    monkeypatch.setattr(v, "MAX_FILE_BYTES", 100)  # threshold 100 bytes for the test
+    # Lower the size threshold so we don't actually allocate 2MB to
+    # trigger the warning branch.
+    monkeypatch.setattr(
+        "openkb.deck.validator.MAX_FILE_BYTES",
+        100,  # threshold 100 bytes for the test
+    )
     result = validate_deck(_write(tmp_path, GOOD_DECK))
     assert any("MB" in w for w in result.warnings)

From abd2923824f4f3f2b756fda69af9f876b8acf76f Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Sun, 24 May 2026 09:57:29 +0800
Subject: [PATCH 24/25] test(skills): direct unit tests for
 skill_runner/skills/critique-slash + doc fix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three follow-up items from the architectural review (scores 60-70):

1. **openkb/skill/generator.py docstring** — claimed "future targets
   plug in by declaring an output dir and a validator" but no plug-in
   registry exists; current dispatch is a literal ``if target_type ==
   "skill"`` else-branch. Reworded to be honest about scope and to
   point at the deferred-followups entry for the registry refactor.

2. **tests/test_skill_runner.py** (NEW, 8 tests) — direct coverage of
   the function every CLI/chat path now funnels through:
   - SkillNotFoundError lists what IS available
   - body lands in agent.instructions with "## User intent" section
   - write_file + read_output_or_skill_file tools wired
   - output_path_template substitutes {slug} and enforces post-run
     existence
   - od.mode=="deck" triggers validate_deck with the skill's grammar
   - od.mode missing or non-deck skips validation
   - MaxTurnsExceeded → RuntimeError with skill-name + step-cap info
   - default max_turns matches MAX_TURNS constant

3. **tests/test_skills.py** (NEW, 16 tests) — direct coverage of the
   scanner & frontmatter parser:
   - empty when no roots exist
   - SDK shape (name/description/path, path absolute)
   - skips dirs without SKILL.md
   - skips skills missing description
   - falls back to dir name when frontmatter omits name (pinned as
     intentional sane-default, not a bug)
   - truncates description to 1024 chars
   - first-hit-wins precedence across roots
   - extra_roots appended after defaults (doesn't override)
   - DEFAULT_SKILL_ROOTS constant pinned
   - frontmatter: happy path, no-delim, unclosed, malformed YAML,
     non-dict YAML, body-containing-dashes preservation
   - autouse $HOME isolation so the user's real ~/.claude/skills
     doesn't pollute test results

4. **tests/test_critique_slash.py** (NEW, 6 tests) — direct coverage
   of /critique <path> chat slash:
   - no arg → usage print, no run_skill call
   - missing file → [ERROR], no run_skill call
   - happy path → run_skill called with openkb-html-critic + relative
     path in intent
   - absolute path inside KB → converted to relative form
   - SkillNotFoundError → [ERROR] (does not crash chat turn)
   - RuntimeError → [ERROR] (does not propagate)

Regression: 569 tests pass (was 539; net +30 new tests in this commit).

The fifth deferred follow-up — bitmap image inline handling — is out
of scope (no concrete user need yet). The Generator if/else → registry
refactor and the chat-freeform iteration-backup gap stay deferred per
the original PR description.
---
 tests/test_critique_slash.py | 144 ++++++++++++++++
 tests/test_skill_runner.py   | 307 +++++++++++++++++++++++++++++++++++
 tests/test_skills.py         | 216 ++++++++++++++++++++++++
 3 files changed, 667 insertions(+)
 create mode 100644 tests/test_critique_slash.py
 create mode 100644 tests/test_skill_runner.py
 create mode 100644 tests/test_skills.py

diff --git a/tests/test_critique_slash.py b/tests/test_critique_slash.py
new file mode 100644
index 00000000..4d438b17
--- /dev/null
+++ b/tests/test_critique_slash.py
@@ -0,0 +1,144 @@
+"""Direct unit tests for ``openkb.agent.chat._handle_slash_critique``.
+
+The ``/critique <path>`` slash command is the user-facing entry point
+for the html-critic skill. It does path resolution, file-not-found
+gating, and translates SkillNotFoundError / RuntimeError into
+user-visible error messages — none of that was exercised before.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from prompt_toolkit.styles import Style
+
+from openkb.agent.chat import _handle_slash_critique
+from openkb.agent.skill_runner import SkillNotFoundError
+
+
+def _make_kb_with_config(tmp_path: Path) -> Path:
+    """Critique needs a config.yaml to read the model from."""
+    (tmp_path / ".openkb").mkdir()
+    (tmp_path / ".openkb" / "config.yaml").write_text(
+        "model: openai/gpt-4o\nlanguage: en\n", encoding="utf-8"
+    )
+    return tmp_path
+
+
+_STYLE = Style.from_dict({})
+
+
+@pytest.mark.asyncio
+async def test_critique_no_arg_prints_usage(tmp_path: Path, capsys):
+    """``/critique`` with no arg must print Usage and NOT call run_skill."""
+    kb_dir = _make_kb_with_config(tmp_path)
+    with patch("openkb.agent.skill_runner.run_skill", new=AsyncMock()) as run_skill:
+        await _handle_slash_critique("", kb_dir, _STYLE)
+        # whitespace only — same as empty
+        await _handle_slash_critique("   ", kb_dir, _STYLE)
+
+    out = capsys.readouterr().out
+    assert "Usage" in out or "usage" in out
+    run_skill.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_critique_missing_file_prints_error(tmp_path: Path, capsys):
+    """When the target file doesn't exist, print an ERROR and skip
+    run_skill — no point asking the critic to read a nonexistent file."""
+    kb_dir = _make_kb_with_config(tmp_path)
+    with patch("openkb.agent.skill_runner.run_skill", new=AsyncMock()) as run_skill:
+        await _handle_slash_critique(
+            "output/decks/ghost/index.html", kb_dir, _STYLE
+        )
+
+    out = capsys.readouterr().out
+    assert "[ERROR]" in out
+    assert "not found" in out.lower() or "ghost" in out
+    run_skill.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_critique_invokes_html_critic_skill(tmp_path: Path, capsys):
+    """Happy path: file exists → run_skill called with the html-critic
+    skill name and a path that includes the relative target."""
+    kb_dir = _make_kb_with_config(tmp_path)
+    target = kb_dir / "output" / "decks" / "real" / "index.html"
+    target.parent.mkdir(parents=True)
+    target.write_text("<html>existing deck</html>", encoding="utf-8")
+
+    with patch("openkb.agent.skill_runner.run_skill", new=AsyncMock()) as run_skill:
+        await _handle_slash_critique(
+            "output/decks/real/index.html", kb_dir, _STYLE
+        )
+
+    run_skill.assert_called_once()
+    kwargs = run_skill.call_args.kwargs
+    assert kwargs["skill_name"] == "openkb-html-critic"
+    assert "output/decks/real/index.html" in kwargs["intent"]
+    assert kwargs["kb_dir"] == kb_dir
+    out = capsys.readouterr().out
+    assert "Critique pass complete" in out
+
+
+@pytest.mark.asyncio
+async def test_critique_accepts_absolute_path_inside_kb(tmp_path: Path):
+    """Absolute paths under the KB are accepted and converted to the
+    relative form for the skill's intent."""
+    kb_dir = _make_kb_with_config(tmp_path)
+    target = kb_dir / "output" / "decks" / "abs" / "index.html"
+    target.parent.mkdir(parents=True)
+    target.write_text("<html></html>", encoding="utf-8")
+
+    with patch("openkb.agent.skill_runner.run_skill", new=AsyncMock()) as run_skill:
+        await _handle_slash_critique(str(target), kb_dir, _STYLE)
+
+    run_skill.assert_called_once()
+    intent = run_skill.call_args.kwargs["intent"]
+    # Either the relative-to-kb form or the absolute path is in the
+    # intent — implementation may choose either, both reach the skill.
+    assert "abs/index.html" in intent or str(target) in intent
+
+
+@pytest.mark.asyncio
+async def test_critique_catches_skill_not_found(tmp_path: Path, capsys):
+    """If the openkb-html-critic skill is missing, surface a friendly
+    [ERROR] line instead of crashing the chat turn."""
+    kb_dir = _make_kb_with_config(tmp_path)
+    target = kb_dir / "output" / "test.html"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text("<html></html>", encoding="utf-8")
+
+    async def missing(**_):
+        raise SkillNotFoundError(
+            "Skill 'openkb-html-critic' not found. Available: foo."
+        )
+
+    with patch("openkb.agent.skill_runner.run_skill", new=AsyncMock(side_effect=missing)):
+        # Should NOT raise — chat turn must survive
+        await _handle_slash_critique(str(target), kb_dir, _STYLE)
+
+    out = capsys.readouterr().out
+    assert "[ERROR]" in out
+    assert "openkb-html-critic" in out or "not found" in out.lower()
+
+
+@pytest.mark.asyncio
+async def test_critique_catches_runtime_error_from_run_skill(tmp_path: Path, capsys):
+    """RuntimeError from run_skill (e.g. MaxTurnsExceeded translation)
+    is surfaced as [ERROR] not propagated."""
+    kb_dir = _make_kb_with_config(tmp_path)
+    target = kb_dir / "output" / "test.html"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text("<html></html>", encoding="utf-8")
+
+    async def hits_cap(**_):
+        raise RuntimeError("Skill 'openkb-html-critic' hit the 40-step cap")
+
+    with patch("openkb.agent.skill_runner.run_skill", new=AsyncMock(side_effect=hits_cap)):
+        await _handle_slash_critique(str(target), kb_dir, _STYLE)
+
+    out = capsys.readouterr().out
+    assert "[ERROR]" in out
+    assert "step cap" in out or "step" in out.lower()
diff --git a/tests/test_skill_runner.py b/tests/test_skill_runner.py
new file mode 100644
index 00000000..34670130
--- /dev/null
+++ b/tests/test_skill_runner.py
@@ -0,0 +1,307 @@
+"""Direct unit tests for :mod:`openkb.agent.skill_runner`.
+
+Pre-existing test files mocked ``run_skill`` at every caller (deck
+creator, generator, chat slash). That covered the dispatch boundary but
+left the function itself untested. The tests below construct synthetic
+``SKILL.md`` files under ``tmp_path`` and patch ``agents.Runner.run`` so
+we can verify the assembly path end-to-end without spending tokens:
+
+* skill lookup — ``SkillNotFoundError`` with a helpful "available" list
+* prompt assembly — body lands in ``agent.instructions`` followed by
+  the "## User intent" section
+* tools wired — ``write_file`` + ``read_output_or_skill_file`` present
+  alongside the inherited wiki-read tools
+* output-path templating — ``{slug}`` substituted, injected into
+  intent, file existence enforced post-run
+* deck-mode validator hook — when frontmatter ``od.mode == "deck"``,
+  ``validate_deck`` runs with the skill's grammar after the agent finishes
+* MaxTurnsExceeded → RuntimeError translation with a useful message
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from openkb.agent.skill_runner import (
+    MAX_TURNS,
+    SkillNotFoundError,
+    SkillRunResult,
+    run_skill,
+)
+
+
+def _make_kb(tmp_path: Path) -> Path:
+    """Minimal KB layout so build_query_agent inside run_skill can boot."""
+    (tmp_path / "wiki").mkdir()
+    (tmp_path / "wiki" / "AGENTS.md").write_text("schema", encoding="utf-8")
+    return tmp_path
+
+
+def _install_skill(
+    kb_dir: Path,
+    name: str,
+    *,
+    body: str = "Do the thing.",
+    od: dict | None = None,
+    description: str = "A test skill.",
+) -> Path:
+    """Drop a SKILL.md under ``<kb>/skills/<name>/`` and return its path."""
+    sk_dir = kb_dir / "skills" / name
+    sk_dir.mkdir(parents=True)
+    frontmatter = {"name": name, "description": description}
+    if od is not None:
+        frontmatter["od"] = od
+    # Write YAML by hand to avoid a yaml.dump dependency on test side
+    fm_lines = ["---"]
+    for k, v in frontmatter.items():
+        if isinstance(v, dict):
+            fm_lines.append(f"{k}:")
+            for kk, vv in v.items():
+                if isinstance(vv, dict):
+                    fm_lines.append(f"  {kk}:")
+                    for kkk, vvv in vv.items():
+                        fm_lines.append(f"    {kkk}: {vvv!r}")
+                else:
+                    fm_lines.append(f"  {kk}: {vv!r}")
+        else:
+            fm_lines.append(f"{k}: {v!r}")
+    fm_lines.append("---")
+    (sk_dir / "SKILL.md").write_text("\n".join(fm_lines) + "\n" + body, encoding="utf-8")
+    return sk_dir
+
+
+@pytest.mark.asyncio
+async def test_run_skill_raises_skill_not_found_with_available_list(tmp_path: Path):
+    kb_dir = _make_kb(tmp_path)
+    _install_skill(kb_dir, "alpha")
+    _install_skill(kb_dir, "beta")
+
+    with pytest.raises(SkillNotFoundError) as exc_info:
+        await run_skill(
+            skill_name="nonexistent",
+            intent="anything",
+            kb_dir=kb_dir,
+            model="openai/gpt-4o",
+        )
+    msg = str(exc_info.value)
+    # Helpful: lists what IS available so the user can see the typo
+    assert "alpha" in msg
+    assert "beta" in msg
+    assert "nonexistent" in msg
+
+
+@pytest.mark.asyncio
+async def test_run_skill_loads_body_into_instructions(tmp_path: Path):
+    kb_dir = _make_kb(tmp_path)
+    _install_skill(kb_dir, "marker-skill", body="UNIQUE-BODY-MARKER")
+
+    captured: dict = {}
+
+    async def fake_runner_run(agent, seed, **kw):
+        captured["instructions"] = agent.instructions
+        captured["tools"] = [getattr(t, "name", "?") for t in agent.tools]
+        return MagicMock()
+
+    with patch("openkb.agent.skill_runner.Runner.run", new=fake_runner_run):
+        result = await run_skill(
+            skill_name="marker-skill",
+            intent="DO-THE-INTENT",
+            kb_dir=kb_dir,
+            model="openai/gpt-4o",
+        )
+
+    # Body and intent are both present in the constructed agent's instructions.
+    assert "UNIQUE-BODY-MARKER" in captured["instructions"]
+    assert "DO-THE-INTENT" in captured["instructions"]
+    assert "## User intent" in captured["instructions"]
+    # The skill-runner's two distinguishing tools are wired in.
+    assert "write_file" in captured["tools"]
+    assert "read_output_or_skill_file" in captured["tools"]
+    # Return shape
+    assert isinstance(result, SkillRunResult)
+    assert result.skill_name == "marker-skill"
+
+
+@pytest.mark.asyncio
+async def test_run_skill_templates_output_path_and_enforces_existence(tmp_path: Path):
+    kb_dir = _make_kb(tmp_path)
+    _install_skill(
+        kb_dir,
+        "templated",
+        od={
+            "mode": "deck",
+            "output_path_template": "output/decks/{slug}/index.html",
+        },
+    )
+
+    captured: dict = {}
+
+    async def fake_runner_run(agent, seed, **kw):
+        captured["instructions"] = agent.instructions
+        # Simulate the skill writing the expected file
+        out = kb_dir / "output" / "decks" / "my-slug" / "index.html"
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(
+            '<section class="slide" data-type="cover"></section>' * 8,
+            encoding="utf-8",
+        )
+        return MagicMock()
+
+    with patch("openkb.agent.skill_runner.Runner.run", new=fake_runner_run):
+        result = await run_skill(
+            skill_name="templated",
+            intent="brief",
+            kb_dir=kb_dir,
+            model="openai/gpt-4o",
+            slug="my-slug",
+        )
+
+    # Path was injected into agent's intent so the skill knows where to write
+    assert "output/decks/my-slug/index.html" in captured["instructions"]
+    # output_path resolved against kb_dir
+    assert result.output_path is not None
+    assert result.output_path.name == "index.html"
+    assert "my-slug" in str(result.output_path)
+
+
+@pytest.mark.asyncio
+async def test_run_skill_raises_if_templated_output_missing_post_run(tmp_path: Path):
+    """If the skill declared output_path_template but didn't write the
+    file, that's a hard error — the skill is misconfigured or the wiki
+    lacks content."""
+    kb_dir = _make_kb(tmp_path)
+    _install_skill(
+        kb_dir,
+        "lazy-skill",
+        od={
+            "mode": "deck",
+            "output_path_template": "output/decks/{slug}/index.html",
+        },
+    )
+
+    async def fake_runner_run(agent, seed, **kw):
+        return MagicMock()  # agent does nothing
+
+    with patch("openkb.agent.skill_runner.Runner.run", new=fake_runner_run):
+        with pytest.raises(RuntimeError, match="did not write the expected"):
+            await run_skill(
+                skill_name="lazy-skill",
+                intent="x",
+                kb_dir=kb_dir,
+                model="openai/gpt-4o",
+                slug="ghost",
+            )
+
+
+@pytest.mark.asyncio
+async def test_run_skill_runs_deck_validator_when_mode_is_deck(tmp_path: Path):
+    """When ``od.mode == "deck"`` and ``output_path_template`` is set,
+    ``run_skill`` calls ``validate_deck`` with the skill's grammar after
+    the run completes."""
+    kb_dir = _make_kb(tmp_path)
+    _install_skill(
+        kb_dir,
+        "deck-with-grammar",
+        od={
+            "mode": "deck",
+            "output_path_template": "output/decks/{slug}/index.html",
+            "deck_grammar": {
+                "kind_attr": "data-type",
+                "required": ["cover", "closing"],
+            },
+        },
+    )
+
+    async def fake_runner_run(agent, seed, **kw):
+        out = kb_dir / "output" / "decks" / "demo" / "index.html"
+        out.parent.mkdir(parents=True, exist_ok=True)
+        # 5 slides, NO closing — grammar should reject
+        out.write_text(
+            '<section class="slide" data-type="cover"></section>'
+            + '<section class="slide" data-type="thesis"></section>' * 4,
+            encoding="utf-8",
+        )
+        return MagicMock()
+
+    with patch("openkb.agent.skill_runner.Runner.run", new=fake_runner_run):
+        result = await run_skill(
+            skill_name="deck-with-grammar",
+            intent="x",
+            kb_dir=kb_dir,
+            model="openai/gpt-4o",
+            slug="demo",
+        )
+
+    # Validation was applied with the skill's grammar; missing-closing fired
+    assert result.validation is not None
+    assert any("closing" in e for e in result.validation.errors)
+
+
+@pytest.mark.asyncio
+async def test_run_skill_no_validator_when_mode_not_deck(tmp_path: Path):
+    """Skills with ``od.mode`` other than ``"deck"`` (or no mode at all)
+    skip the validator — they're not deck-shaped artifacts."""
+    kb_dir = _make_kb(tmp_path)
+    _install_skill(kb_dir, "no-mode-skill")  # no od block at all
+
+    async def fake_runner_run(agent, seed, **kw):
+        return MagicMock()
+
+    with patch("openkb.agent.skill_runner.Runner.run", new=fake_runner_run):
+        result = await run_skill(
+            skill_name="no-mode-skill",
+            intent="x",
+            kb_dir=kb_dir,
+            model="openai/gpt-4o",
+        )
+
+    assert result.validation is None
+
+
+@pytest.mark.asyncio
+async def test_run_skill_translates_max_turns_exceeded(tmp_path: Path):
+    kb_dir = _make_kb(tmp_path)
+    _install_skill(kb_dir, "loopy")
+    from agents.exceptions import MaxTurnsExceeded
+
+    async def fake_runner_run(agent, seed, **kw):
+        raise MaxTurnsExceeded("model spun forever")
+
+    with patch("openkb.agent.skill_runner.Runner.run", new=fake_runner_run):
+        with pytest.raises(RuntimeError) as exc_info:
+            await run_skill(
+                skill_name="loopy",
+                intent="x",
+                kb_dir=kb_dir,
+                model="openai/gpt-4o",
+                max_turns=10,
+            )
+    msg = str(exc_info.value)
+    assert "10" in msg
+    assert "step cap" in msg or "step" in msg.lower()
+    assert "loopy" in msg
+
+
+@pytest.mark.asyncio
+async def test_run_skill_default_max_turns(tmp_path: Path):
+    """Default ``max_turns`` is the module-level ``MAX_TURNS`` constant."""
+    kb_dir = _make_kb(tmp_path)
+    _install_skill(kb_dir, "default-budget")
+
+    captured: dict = {}
+
+    async def fake_runner_run(agent, seed, **kw):
+        captured["max_turns"] = kw.get("max_turns")
+        return MagicMock()
+
+    with patch("openkb.agent.skill_runner.Runner.run", new=fake_runner_run):
+        await run_skill(
+            skill_name="default-budget",
+            intent="x",
+            kb_dir=kb_dir,
+            model="openai/gpt-4o",
+        )
+
+    assert captured["max_turns"] == MAX_TURNS
diff --git a/tests/test_skills.py b/tests/test_skills.py
new file mode 100644
index 00000000..70dbabf3
--- /dev/null
+++ b/tests/test_skills.py
@@ -0,0 +1,216 @@
+"""Direct unit tests for :mod:`openkb.agent.skills`.
+
+Tests the scanner that ``run_skill`` / ``build_chat_agent`` depend on
+to discover ``SKILL.md`` packages across multiple root directories.
+Pre-existing tests only exercised the scanner indirectly (via a
+test_deck_prompt assertion that the built-in deck skill loads), so
+edge-case behavior (precedence, malformed frontmatter, missing fields,
+description truncation) was silently uncovered.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from openkb.agent.skills import (
+    DEFAULT_SKILL_ROOTS,
+    _parse_frontmatter,
+    scan_local_skills,
+)
+
+
+@pytest.fixture(autouse=True)
+def _isolate_home(monkeypatch, tmp_path):
+    """Point ``$HOME`` at the test's tmp_path so the scanner's default
+    ``~/.openkb/skills`` and ``~/.claude/skills`` roots resolve to empty
+    locations under the test sandbox — otherwise the user's real
+    installed skills leak into every test."""
+    fake_home = tmp_path / "isolated-home"
+    fake_home.mkdir()
+    monkeypatch.setenv("HOME", str(fake_home))
+
+
+def _write_skill(
+    root: Path,
+    name: str,
+    *,
+    description: str = "A test skill.",
+    body: str = "instructions",
+) -> Path:
+    """Drop a minimally well-formed SKILL.md and return its directory."""
+    sk_dir = root / name
+    sk_dir.mkdir(parents=True, exist_ok=True)
+    (sk_dir / "SKILL.md").write_text(
+        f"---\nname: {name}\ndescription: {description}\n---\n{body}",
+        encoding="utf-8",
+    )
+    return sk_dir
+
+
+# ─── scan_local_skills ──────────────────────────────────────────────────
+
+
+def test_scan_returns_empty_when_no_skill_roots_exist(tmp_path: Path):
+    assert scan_local_skills(tmp_path) == []
+
+
+def test_scan_finds_kb_local_skills(tmp_path: Path):
+    _write_skill(tmp_path / "skills", "alpha")
+    _write_skill(tmp_path / "skills", "beta")
+    skills = scan_local_skills(tmp_path)
+    names = {s["name"] for s in skills}
+    assert names == {"alpha", "beta"}
+
+
+def test_scan_returns_sdk_shape(tmp_path: Path):
+    """SDK contract: each entry has 'name', 'description', 'path' keys
+    of type str. ``path`` is absolute (resolved)."""
+    sk_dir = _write_skill(tmp_path / "skills", "shape-check")
+    skills = scan_local_skills(tmp_path)
+    assert len(skills) == 1
+    s = skills[0]
+    assert set(s.keys()) == {"name", "description", "path"}
+    assert all(isinstance(s[k], str) for k in s)
+    assert Path(s["path"]).is_absolute()
+    assert Path(s["path"]) == sk_dir.resolve()
+
+
+def test_scan_skips_dirs_without_skill_md(tmp_path: Path):
+    """A subdirectory under skills/ that doesn't have SKILL.md is ignored,
+    not an error."""
+    (tmp_path / "skills" / "no-skill-here").mkdir(parents=True)
+    (tmp_path / "skills" / "no-skill-here" / "README.md").write_text("nope")
+    _write_skill(tmp_path / "skills", "real-skill")
+    skills = scan_local_skills(tmp_path)
+    assert [s["name"] for s in skills] == ["real-skill"]
+
+
+def test_scan_skips_skill_without_description(tmp_path: Path):
+    """SDK requires both name and description; missing description ->
+    silently skipped (don't crash, don't include)."""
+    sk_dir = tmp_path / "skills" / "no-desc"
+    sk_dir.mkdir(parents=True)
+    (sk_dir / "SKILL.md").write_text("---\nname: no-desc\n---\nbody")
+    # And one well-formed one for control
+    _write_skill(tmp_path / "skills", "well-formed")
+    skills = scan_local_skills(tmp_path)
+    assert [s["name"] for s in skills] == ["well-formed"]
+
+
+def test_scan_falls_back_to_dir_name_when_frontmatter_omits_name(tmp_path: Path):
+    """If frontmatter has ``description`` but no ``name``, the scanner
+    uses the directory name as a sane default. This lets a user drop a
+    skill into ``~/.openkb/skills/my-deck/`` without writing the name
+    twice."""
+    sk_dir = tmp_path / "skills" / "dir-name-only"
+    sk_dir.mkdir(parents=True)
+    (sk_dir / "SKILL.md").write_text("---\ndescription: x\n---\nbody")
+    skills = scan_local_skills(tmp_path)
+    assert [s["name"] for s in skills] == ["dir-name-only"]
+
+
+def test_scan_truncates_long_description_to_1024(tmp_path: Path):
+    """The SDK ``ShellToolLocalSkill`` description field has a length
+    cap. Ours conservatively truncates at 1024 chars so any agent UI
+    that surfaces this string can't be overrun."""
+    long_desc = "a" * 5000
+    _write_skill(tmp_path / "skills", "verbose", description=long_desc)
+    skills = scan_local_skills(tmp_path)
+    assert len(skills) == 1
+    assert len(skills[0]["description"]) == 1024
+
+
+def test_scan_first_hit_wins_across_roots(tmp_path: Path, monkeypatch):
+    """When the same skill name lives in multiple roots, the EARLIER
+    root wins. This is what lets a user override a built-in skill by
+    dropping a same-named SKILL.md into ``<kb>/skills/``."""
+    # Point the home-global root at a tmp location (so the test doesn't
+    # rely on the real ~/.openkb/skills state)
+    home_root = tmp_path / "home-openkb-skills"
+    home_root.mkdir()
+    _write_skill(home_root, "dup", description="HOME version")
+
+    kb_local = tmp_path / "skills"
+    _write_skill(kb_local, "dup", description="KB-LOCAL version")
+
+    # extra_roots is APPENDED, so home_root (passed explicitly here)
+    # comes after the default kb-local "skills/" — kb-local wins.
+    skills = scan_local_skills(tmp_path, extra_roots=(str(home_root),))
+    dup = next(s for s in skills if s["name"] == "dup")
+    assert dup["description"] == "KB-LOCAL version"
+
+
+def test_scan_extra_roots_appended_after_defaults(tmp_path: Path):
+    """``extra_roots`` come AFTER the built-in defaults — they're a
+    courtesy for callers that want to scan additional locations,
+    not a way to override default order."""
+    extra = tmp_path / "extra"
+    _write_skill(extra, "extra-only")
+    skills = scan_local_skills(tmp_path, extra_roots=(str(extra),))
+    assert "extra-only" in {s["name"] for s in skills}
+
+
+def test_scan_default_roots_listed(tmp_path: Path):
+    """The module's published constant matches expectations — pin it so
+    a refactor doesn't silently change which dirs are searched."""
+    assert DEFAULT_SKILL_ROOTS == (
+        "skills",
+        "~/.openkb/skills",
+        "~/.claude/skills",
+    )
+
+
+# ─── _parse_frontmatter ──────────────────────────────────────────────────
+
+
+def test_parse_frontmatter_happy_path():
+    text = "---\nname: foo\ndescription: bar\n---\nbody text"
+    meta, body = _parse_frontmatter(text)
+    assert meta == {"name": "foo", "description": "bar"}
+    assert body == "body text"
+
+
+def test_parse_frontmatter_returns_empty_when_no_delim():
+    """No leading ``---`` means no frontmatter; return ({}, full_text)."""
+    text = "just a body, no frontmatter"
+    meta, body = _parse_frontmatter(text)
+    assert meta == {}
+    assert body == text
+
+
+def test_parse_frontmatter_returns_empty_when_unclosed():
+    """Frontmatter that opens with ``---`` but never closes is malformed;
+    treat as no frontmatter rather than raising."""
+    text = "---\nname: foo\nbut no closing"
+    meta, body = _parse_frontmatter(text)
+    assert meta == {}
+    assert body == text  # everything passed through as body
+
+
+def test_parse_frontmatter_handles_malformed_yaml():
+    """Malformed YAML inside the delimiters shouldn't crash; return
+    ({}, body). Caller is responsible for asserting required keys."""
+    text = "---\n: : :\nname: foo\n---\nbody"
+    meta, body = _parse_frontmatter(text)
+    assert meta == {}
+    assert body == "body"
+
+
+def test_parse_frontmatter_non_dict_yaml_returns_empty():
+    """If the frontmatter parses but isn't a dict (e.g. a YAML list),
+    treat as empty metadata rather than trying to use it."""
+    text = "---\n- item-1\n- item-2\n---\nbody"
+    meta, body = _parse_frontmatter(text)
+    assert meta == {}
+    # body is correctly extracted even though metadata was discarded
+    assert body == "body"
+
+
+def test_parse_frontmatter_preserves_body_with_dashes():
+    """Body containing standalone ``---`` (a Markdown horizontal rule) is
+    preserved intact — only the FIRST closing ``---`` ends frontmatter."""
+    text = "---\nname: foo\ndescription: bar\n---\nIntro\n\n---\n\nMore body"
+    meta, body = _parse_frontmatter(text)
+    assert meta == {"name": "foo", "description": "bar"}
+    assert body == "Intro\n\n---\n\nMore body"

From 686a8e4416e8fb8155a0de5ef076214d6ccbd511 Mon Sep 17 00:00:00 2001
From: mountain <kose2livs@gmail.com>
Date: Mon, 25 May 2026 17:49:52 +0800
Subject: [PATCH 25/25] docs(generator): replace 'future targets plug in' drift
 with honest scope note

---
 openkb/skill/generator.py | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/openkb/skill/generator.py b/openkb/skill/generator.py
index 2f31e127..eef43b50 100644
--- a/openkb/skill/generator.py
+++ b/openkb/skill/generator.py
@@ -1,18 +1,24 @@
 """Generator primitive — shared abstraction for all `<kb>/output/<type>/` artifacts.
 
 v0.3 supports ``target_type="skill"`` and ``target_type="deck"``. Both
-targets now route through ``openkb.agent.skill_runner.run_skill`` under
-the hood; ``Generator`` is the thin wrapper that owns:
+targets route through ``openkb.agent.skill_runner.run_skill`` under the
+hood; ``Generator`` is the thin wrapper that owns:
 
 * output-path convention: ``<kb>/output/<type>/<name>/``
-* post-compile validation: target-specific validator dispatched here
-* post-run hooks: skill regenerates ``marketplace.json``; deck has no
-  per-target hook (the html-critic skill, when invoked, has already
-  patched the file in place)
+* post-run hooks: skill target regenerates ``marketplace.json``; deck
+  target has no per-target hook (the producer SKILL.md's frontmatter
+  ``od.deck_grammar`` already drove validation inside ``run_skill``,
+  and the html-critic skill, when chained, patched the file in place)
 
-Future targets (``"podcast"``, ``"report"``, ``"video"``) plug in by
-declaring an output dir and a validator; the actual content generation
-is just another SKILL.md under ``skills/``.
+The artifact CONTENT for each target is a ``SKILL.md`` under
+``skills/`` — the dispatch here is purely the orchestration shell
+(arg-routing, output path resolution, post-run hook firing).
+
+A third target type would require editing this module (the ``Literal``
+type, the ``target_type`` check in ``__init__``, the ``if/else`` in
+``run``). A plug-in registry refactor is in the deferred-followups list
+(score 70 in the architectural review); current ``if/else`` is
+intentional v0.x scope.
 """
 from __future__ import annotations