From 31ee19561be6edce9a438bff215824a53f602bfe Mon Sep 17 00:00:00 2001
From: sky <skyzhangbinghua@gmail.com>
Date: Mon, 24 Aug 2026 10:37:11 +0800
Subject: [PATCH] fix(web): restore styling under CSP, and give KB articles a
 page (#12)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two defects made the web UI unusable for its Knowledge Base.

First, every page rendered with no styling. All CSS is one inline <style>
emitted by layout(), and the response carried `default-src 'self'` — a policy
that drops inline styles unless they are allowed by 'unsafe-inline' or matched
by a nonce. Measured: 0 CSS rules applied under the shipped header, 36 under
either 'unsafe-inline' or no header at all. The same HTML opened over file://
was always fine, which is why this never showed up outside a browser hitting
the server. Each response now carries a fresh nonce and a matching
style-src 'nonce-...'. Reaching for 'unsafe-inline' would have fixed the symptom
while admitting any injected style — the opposite of what the header is there for.

Second, KB articles had no detail page. /kb listed them, the titles were not
links, and no /kb/<topic> route existed, so a reader could see a row and nothing
else — while TASKS lists T-119 (KB Article page) as done. There is now a detail
route rendering chapters, a table of contents built from the headings, and a
metadata panel, plus web/markdown.py: a small renderer covering the constructs
the chapter guide asks for. It escapes before emitting on every branch, keeps
code spans out of the emphasis pass, and refuses link targets that are not
same-document or http(s).

Chapter names from `chapters:` and the topic from the URL are both
author-controlled, so both are constrained to the article directory.

21 tests added (nonce/CSP pairing, detail rendering, traversal refusal,
escaping, markdown blocks and inline). Full unit run: same 36 pre-existing
failures before and after, 1355 -> 1376 passed.
---
 cli/engram/web/markdown.py | 245 +++++++++++++++++++++++++++++++++++++
 cli/engram/web/pages.py    |  99 ++++++++++++++-
 cli/engram/web/render.py   |  71 ++++++++++-
 cli/engram/web/server.py   |  28 ++++-
 tests/unit/cli/test_web.py | 154 +++++++++++++++++++++++
 5 files changed, 590 insertions(+), 7 deletions(-)
 create mode 100644 cli/engram/web/markdown.py

diff --git a/cli/engram/web/markdown.py b/cli/engram/web/markdown.py
new file mode 100644
index 0000000..2cb8c1c
--- /dev/null
+++ b/cli/engram/web/markdown.py
@@ -0,0 +1,245 @@
+"""A small Markdown-to-HTML renderer for KB chapters (SPEC §6.3).
+
+Deliberately not a full CommonMark implementation. It covers exactly the
+constructs the KB chapter guide asks authors to use — headings, paragraphs,
+fenced code, tables, lists, block quotes, rules, and the inline set — and
+renders everything else as plain text rather than guessing.
+
+Why hand-rolled: the project keeps its core dependency-free, and a
+server-rendered read-only view does not justify pulling a parser in. The
+trade-off is accepted scope, not accepted sloppiness — every branch escapes
+its text before emitting, so a chapter can never inject markup.
+"""
+
+from __future__ import annotations
+
+import re
+
+from engram.web.render import esc
+
+__all__ = ["render_markdown", "extract_headings", "strip_frontmatter"]
+
+_FENCE_RE = re.compile(r"^(?:```|~~~)\s*([A-Za-z0-9_+-]*)\s*$")
+_HEADING_RE = re.compile(r"^(#{1,6})\s+(.*)$")
+_ULIST_RE = re.compile(r"^[-*+]\s+(.*)$")
+_OLIST_RE = re.compile(r"^\d+[.)]\s+(.*)$")
+_RULE_RE = re.compile(r"^(?:-{3,}|\*{3,}|_{3,})\s*$")
+_TABLE_SEP_RE = re.compile(r"^\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$")
+
+# Inline: code first so its content is never re-scanned for emphasis.
+_CODE_RE = re.compile(r"`([^`]+)`")
+_LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)\s]+)\)")
+_BOLD_RE = re.compile(r"\*\*([^*]+)\*\*")
+_ITALIC_RE = re.compile(r"(?<![*\w])\*([^*\n]+)\*(?![*\w])")
+_WIKILINK_RE = re.compile(r"\[\[([^\]|]+)(?:\|([^\]]+))?\]\]")
+
+_SAFE_HREF_RE = re.compile(r"^(?:https?://|/|\./|\.\./|#)[^\s\"'<>]*$|^[A-Za-z0-9._/-]+$")
+
+
+def strip_frontmatter(text: str) -> tuple[dict[str, str], str]:
+    """Split a leading ``---`` YAML block off. Values are kept as raw strings —
+    this view only displays them, so a full YAML parse would buy nothing."""
+    if not text.startswith("---"):
+        return {}, text
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}, text
+    head = text[3:end]
+    body = text[end + 4 :].lstrip("\n")
+    meta: dict[str, str] = {}
+    for line in head.splitlines():
+        if ":" in line and not line.startswith((" ", "\t", "-")):
+            k, _, v = line.partition(":")
+            meta[k.strip()] = v.strip().strip("\"'")
+    return meta, body
+
+
+def extract_headings(text: str) -> list[tuple[int, str, str]]:
+    """Return ``(level, text, anchor)`` for each ATX heading outside code fences."""
+    out: list[tuple[int, str, str]] = []
+    in_fence = False
+    seen: dict[str, int] = {}
+    for line in text.splitlines():
+        if _FENCE_RE.match(line):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        m = _HEADING_RE.match(line)
+        if not m:
+            continue
+        level, raw = len(m.group(1)), m.group(2).strip()
+        plain = _strip_inline_markup(raw)
+        anchor = _slug(plain, seen)
+        out.append((level, plain, anchor))
+    return out
+
+
+def render_markdown(text: str) -> str:
+    """Render ``text`` to an HTML fragment. Never raises on malformed input."""
+    lines = text.splitlines()
+    out: list[str] = []
+    i = 0
+    seen: dict[str, int] = {}
+    n = len(lines)
+
+    while i < n:
+        line = lines[i]
+
+        fence = _FENCE_RE.match(line)
+        if fence:
+            lang = fence.group(1)
+            i += 1
+            buf: list[str] = []
+            while i < n and not _FENCE_RE.match(lines[i]):
+                buf.append(lines[i])
+                i += 1
+            i += 1  # closing fence (or EOF — unterminated fences still render)
+            cls = f' class="lang-{esc(lang)}"' if lang else ""
+            out.append(f"<pre><code{cls}>{esc(chr(10).join(buf))}</code></pre>")
+            continue
+
+        if not line.strip():
+            i += 1
+            continue
+
+        if _RULE_RE.match(line):
+            out.append("<hr>")
+            i += 1
+            continue
+
+        h = _HEADING_RE.match(line)
+        if h:
+            level, raw = len(h.group(1)), h.group(2).strip()
+            anchor = _slug(_strip_inline_markup(raw), seen)
+            out.append(f'<h{level} id="{anchor}">{_inline(raw)}</h{level}>')
+            i += 1
+            continue
+
+        # Table: a header row followed by a delimiter row.
+        if line.lstrip().startswith("|") and i + 1 < n and _TABLE_SEP_RE.match(lines[i + 1].strip()):
+            header = _split_row(line)
+            i += 2
+            rows: list[list[str]] = []
+            while i < n and lines[i].lstrip().startswith("|"):
+                rows.append(_split_row(lines[i]))
+                i += 1
+            out.append(_table(header, rows))
+            continue
+
+        if line.lstrip().startswith(">"):
+            buf = []
+            while i < n and lines[i].lstrip().startswith(">"):
+                buf.append(lines[i].lstrip()[1:].lstrip())
+                i += 1
+            inner = render_markdown("\n".join(buf))
+            out.append(f"<blockquote>{inner}</blockquote>")
+            continue
+
+        lm = _ULIST_RE.match(line.lstrip()) or _OLIST_RE.match(line.lstrip())
+        if lm:
+            ordered = _OLIST_RE.match(line.lstrip()) is not None
+            items: list[str] = []
+            while i < n:
+                stripped = lines[i].lstrip()
+                m2 = _OLIST_RE.match(stripped) if ordered else _ULIST_RE.match(stripped)
+                if not m2:
+                    break
+                items.append(f"<li>{_inline(m2.group(1))}</li>")
+                i += 1
+            tag = "ol" if ordered else "ul"
+            out.append(f"<{tag}>{''.join(items)}</{tag}>")
+            continue
+
+        # Paragraph: consume until a blank line or the start of another block.
+        buf = []
+        while i < n and lines[i].strip() and not _starts_block(lines[i]):
+            buf.append(lines[i].strip())
+            i += 1
+        if buf:
+            out.append(f"<p>{_inline(' '.join(buf))}</p>")
+        else:  # a block-starter we did not consume above; emit it verbatim
+            out.append(f"<p>{_inline(lines[i].strip())}</p>")
+            i += 1
+
+    return "\n".join(out)
+
+
+def _starts_block(line: str) -> bool:
+    s = line.lstrip()
+    return bool(
+        _FENCE_RE.match(line)
+        or _HEADING_RE.match(line)
+        or _RULE_RE.match(line)
+        or s.startswith(">")
+        or s.startswith("|")
+        or _ULIST_RE.match(s)
+        or _OLIST_RE.match(s)
+    )
+
+
+def _split_row(line: str) -> list[str]:
+    s = line.strip()
+    if s.startswith("|"):
+        s = s[1:]
+    if s.endswith("|"):
+        s = s[:-1]
+    return [c.strip() for c in s.split("|")]
+
+
+def _table(header: list[str], rows: list[list[str]]) -> str:
+    width = len(header)
+    head = "".join(f"<th>{_inline(c)}</th>" for c in header)
+    body = []
+    for r in rows:
+        cells = (r + [""] * width)[:width]
+        body.append("<tr>" + "".join(f"<td>{_inline(c)}</td>" for c in cells) + "</tr>")
+    return f"<table><thead><tr>{head}</tr></thead><tbody>{''.join(body)}</tbody></table>"
+
+
+def _inline(text: str) -> str:
+    """Escape, then re-introduce the inline constructs. Code spans are pulled
+    out first so their contents never pick up emphasis or link syntax."""
+    spans: list[str] = []
+
+    def _stash(m: re.Match[str]) -> str:
+        spans.append(f"<code>{esc(m.group(1))}</code>")
+        return f"\x00{len(spans) - 1}\x00"
+
+    staged = _CODE_RE.sub(_stash, text)
+    html = esc(staged)
+
+    def _link(m: re.Match[str]) -> str:
+        label, href = m.group(1), m.group(2)
+        if not _SAFE_HREF_RE.match(href):
+            return esc(label)
+        return f'<a href="{esc(href)}">{esc(label)}</a>'
+
+    # esc() has already run, so match against the escaped forms.
+    html = re.sub(r"\[\[([^\]|]+)(?:\|([^\]]+))?\]\]", lambda m: esc(m.group(2) or m.group(1)), html)
+    html = re.sub(r"\[([^\]]+)\]\(([^)\s]+)\)", _link, html)
+    html = _BOLD_RE.sub(r"<strong>\1</strong>", html)
+    html = _ITALIC_RE.sub(r"<em>\1</em>", html)
+
+    for idx, span in enumerate(spans):
+        html = html.replace(f"\x00{idx}\x00", span)
+    return html
+
+
+def _strip_inline_markup(text: str) -> str:
+    text = _CODE_RE.sub(r"\1", text)
+    text = _LINK_RE.sub(r"\1", text)
+    text = _WIKILINK_RE.sub(lambda m: m.group(2) or m.group(1), text)
+    text = _BOLD_RE.sub(r"\1", text)
+    text = _ITALIC_RE.sub(r"\1", text)
+    return text.strip()
+
+
+def _slug(text: str, seen: dict[str, int]) -> str:
+    """Stable, collision-free anchor. Non-ASCII is kept — the KB is bilingual and
+    browsers handle percent-encoded fragments fine."""
+    base = re.sub(r"[^\w一-鿿-]+", "-", text.strip().lower()).strip("-")
+    base = base or "section"
+    count = seen.get(base, 0)
+    seen[base] = count + 1
+    return base if count == 0 else f"{base}-{count}"
diff --git a/cli/engram/web/pages.py b/cli/engram/web/pages.py
index 2964d73..3b30291 100644
--- a/cli/engram/web/pages.py
+++ b/cli/engram/web/pages.py
@@ -15,6 +15,7 @@
 from contextlib import contextmanager
 from datetime import date
 from pathlib import Path
+from urllib.parse import quote
 from typing import Any
 
 from engram.web.render import card, esc, table
@@ -252,7 +253,7 @@ def render_kb(root: Path) -> str:
             )
             rows.append(
                 [
-                    esc(child.name),
+                    f'<a href="/kb/{quote(child.name)}">{esc(child.name)}</a>',
                     f'<span class="pill">{esc(fm.lifecycle_state)}</span>',
                     esc(len(fm.chapters)),
                     stale_pill,
@@ -267,6 +268,102 @@ def render_kb(root: Path) -> str:
     return f"<h1>Knowledge Base</h1><p class='sub'>{len(rows)} article(s)</p>{body}"
 
 
+def render_kb_detail(root: Path, topic: str) -> str | None:
+    """One KB article: chapter body, table of contents, and metadata.
+
+    Returns ``None`` when the topic does not resolve to a readable article so
+    the caller can answer 404 — an unreadable article and a missing one are the
+    same thing to a reader, and distinguishing them would leak directory shape.
+    """
+    from engram.kb import check_staleness, kb_root, parse_readme
+    from engram.kb.format import KbFormatError
+
+    from engram.web.markdown import extract_headings, render_markdown, strip_frontmatter
+
+    if not _safe_topic(topic):
+        return None
+    art = kb_root(root) / topic
+    readme = art / "README.md"
+    if art.is_symlink() or not readme.is_file():
+        return None
+    try:
+        fm, readme_body = parse_readme(readme)
+    except KbFormatError:
+        return None
+
+    chapters: list[tuple[str, str, str]] = []  # (file, title, html)
+    toc: list[str] = []
+    words = 0
+    for name in fm.chapters:
+        # `chapters:` is author-controlled; keep it inside the article dir.
+        if "/" in name or "\\" in name or name.startswith("."):
+            continue
+        f = art / name
+        if not f.is_file():
+            toc.append(f'<li class="miss">{esc(name)} — missing</li>')
+            continue
+        raw = f.read_text(encoding="utf-8", errors="replace")
+        meta, body = strip_frontmatter(raw)
+        words += len(body.split())
+        title = meta.get("title") or name
+        anchor_id = f"ch-{len(chapters)}"
+        chapters.append((name, title, render_markdown(body)))
+        subs = "".join(
+            f'<li class="lvl{lv}"><a href="#{esc(a)}">{esc(t)}</a></li>'
+            for lv, t, a in extract_headings(body)
+            # h1 duplicates the chapter title rendered just above it
+            if 2 <= lv <= 3
+        )
+        toc.append(
+            f'<li><a href="#{anchor_id}"><b>{esc(title)}</b></a>'
+            f'<ul class="sub">{subs}</ul></li>'
+        )
+
+    stale = check_staleness(art).is_stale if (art / "_compile_state.toml").is_file() else None
+    if stale is True:
+        badge = '<span class="pill warn">digest stale</span>'
+    elif stale is False:
+        badge = '<span class="pill ok">digest fresh</span>'
+    else:
+        badge = '<span class="pill">not compiled</span>'
+
+    meta_rows = [
+        ("Lifecycle", esc(fm.lifecycle_state)),
+        ("Scope", esc(getattr(fm, "scope", "") or "—")),
+        ("Author", esc(getattr(fm, "primary_author", "") or "—")),
+        ("Chapters", str(len(fm.chapters))),
+        ("Words", f"{words:,}"),
+    ]
+    meta_html = "".join(
+        f'<div class="kv"><span class="k">{k}</span><span class="v">{v}</span></div>'
+        for k, v in meta_rows
+    )
+
+    bodies = "".join(
+        f'<section class="chapter" id="ch-{n}">'
+        f'<h2 class="chapter-title">{esc(title)}</h2>{html}</section>'
+        for n, (_f, title, html) in enumerate(chapters)
+    )
+    abstract = render_markdown(readme_body) if readme_body.strip() else ""
+
+    return (
+        f'<p class="crumb"><a href="/kb">Knowledge Base</a> › {esc(topic)}</p>'
+        f"<h1>{esc(fm.name)}</h1>"
+        f'<p class="sub">{esc(fm.description)}</p>'
+        f'<p class="sub">{badge} · {len(chapters)} chapter(s) · {words:,} words</p>'
+        f'<div class="kb-grid">'
+        f'<nav class="kb-toc"><div class="toc-head">Contents</div><ul>{"".join(toc)}</ul></nav>'
+        f'<article class="kb-body">{abstract}{bodies}</article>'
+        f'<aside class="kb-meta"><div class="toc-head">Metadata</div>{meta_html}</aside>'
+        f"</div>"
+    )
+
+
+def _safe_topic(topic: str) -> bool:
+    """Reject anything that is not a plain directory name."""
+    return bool(topic) and "/" not in topic and "\\" not in topic and not topic.startswith(".")
+
+
 # ----------------------------------------------------------------------
 # Inbox
 # ----------------------------------------------------------------------
diff --git a/cli/engram/web/render.py b/cli/engram/web/render.py
index 989790e..03ddeaa 100644
--- a/cli/engram/web/render.py
+++ b/cli/engram/web/render.py
@@ -9,6 +9,8 @@
 
 from __future__ import annotations
 
+import re
+
 from html import escape
 
 __all__ = ["card", "esc", "layout", "table"]
@@ -58,6 +60,49 @@
 th{background:var(--bg-subtle);color:var(--muted);font-weight:600;
   text-transform:uppercase;font-size:11px;letter-spacing:.5px}
 tr:last-child td{border-bottom:none}
+.crumb{color:var(--muted);margin:0 0 6px;font-size:13px}
+.kb-grid{display:grid;grid-template-columns:220px minmax(0,1fr) 200px;gap:22px;
+ align-items:start;margin-top:20px}
+/* An article needs more line length than the dashboard tables do. */
+main:has(.kb-grid){max-width:1460px}
+.kb-toc,.kb-meta{background:var(--card);border-radius:var(--radius);padding:14px 16px;
+ box-shadow:var(--shadow);position:sticky;top:18px;max-height:calc(100vh - 40px);overflow:auto}
+.toc-head{font-weight:700;font-size:12px;letter-spacing:.06em;text-transform:uppercase;
+ color:var(--muted);margin-bottom:8px}
+.kb-toc ul{list-style:none;margin:0;padding:0;font-size:13px}
+.kb-toc ul.sub{margin:2px 0 8px 10px;border-left:2px solid #eee7d9;padding-left:8px}
+.kb-toc li{margin:3px 0;line-height:1.35}
+.kb-toc li.miss{color:var(--danger)}
+.kb-toc .lvl3{margin-left:9px;font-size:12px;color:var(--muted)}
+.kb-body{min-width:0}
+.kb-body .chapter{margin:0 0 34px}
+.kb-body .chapter-title{font-size:21px;margin:26px 0 10px;padding-bottom:6px;
+ border-bottom:2px solid var(--orange)}
+.kb-body h1{font-size:22px;margin:22px 0 8px}
+.kb-body h2{font-size:18px;margin:20px 0 8px}
+.kb-body h3{font-size:15px;margin:16px 0 6px;color:var(--muted)}
+.kb-body p{margin:9px 0}
+.kb-body table{width:100%;border-collapse:collapse;margin:12px 0;font-size:14px;display:block;
+ overflow-x:auto}
+.kb-body th,.kb-body td{border:1px solid #e6e2d6;padding:6px 9px;text-align:left;vertical-align:top}
+.kb-body th{background:var(--bg-subtle);font-weight:600}
+.kb-body pre{background:#f7f5ee;border:1px solid #e6e2d6;border-radius:8px;padding:11px 13px;
+ overflow-x:auto;margin:11px 0}
+.kb-body pre code{font-family:var(--mono);font-size:12.5px;line-height:1.5;background:none;padding:0}
+.kb-body code{font-family:var(--mono);font-size:12.5px;background:var(--bg-subtle);
+ padding:1px 4px;border-radius:4px}
+.kb-body blockquote{margin:11px 0;padding:2px 14px;border-left:3px solid var(--orange);
+ background:#fdf8f4;color:#4a4842}
+.kb-body hr{border:0;border-top:1px solid #e6e2d6;margin:20px 0}
+.kb-body ul,.kb-body ol{margin:9px 0;padding-left:22px}
+.kb-body li{margin:3px 0}
+.kb-meta .kv{display:flex;justify-content:space-between;gap:8px;font-size:12.5px;
+ padding:5px 0;border-bottom:1px solid #f0ede3}
+.kb-meta .kv:last-child{border-bottom:0}
+.kb-meta .k{color:var(--muted)}
+.kb-meta .v{font-weight:600;text-align:right;word-break:break-word}
+@media(max-width:1100px){.kb-grid{grid-template-columns:1fr}
+ .kb-toc,.kb-meta{position:static;max-height:none}}
 .pill{display:inline-block;padding:2px 9px;border-radius:9999px;font-size:12px;
   background:var(--bg-subtle);color:var(--muted)}
 .pill.mandatory{background:#f6dfd6;color:var(--danger)}
@@ -84,8 +129,27 @@ def esc(value: object) -> str:
     return escape(str(value), quote=True)
 
 
-def layout(title: str, body_html: str, *, active: str = "/") -> str:
-    """Wrap page body in the full HTML shell + sidebar nav."""
+def _nonce_attr(nonce: str | None) -> str:
+    """Render ``nonce="..."`` or nothing. Rejects anything not base64url-safe
+    so a caller cannot break out of the attribute."""
+    if not nonce:
+        return ""
+    if not re.fullmatch(r"[A-Za-z0-9_-]{8,128}", nonce):
+        raise ValueError("style_nonce must be 8-128 chars of [A-Za-z0-9_-]")
+    return f' nonce="{nonce}"'
+
+
+def layout(
+    title: str, body_html: str, *, active: str = "/", style_nonce: str | None = None
+) -> str:
+    """Wrap page body in the full HTML shell + sidebar nav.
+
+    ``style_nonce`` is stamped on the inline ``<style>`` block so the page
+    survives a CSP that does not allow ``'unsafe-inline'``. The caller is
+    responsible for emitting a matching ``style-src 'nonce-...'`` header —
+    a nonce here without the header is inert, and the header without this
+    attribute drops every rule.
+    """
     link_parts = []
     for href, label in _NAV:
         cls = ' class="active"' if href == active else ""
@@ -94,7 +158,8 @@ def layout(title: str, body_html: str, *, active: str = "/") -> str:
     return (
         "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\">"
         '<meta name="viewport" content="width=device-width,initial-scale=1">'
-        f"<title>{esc(title)} · engram</title><style>{_CSS}</style></head>"
+        f"<title>{esc(title)} · engram</title>"
+        f"<style{_nonce_attr(style_nonce)}>{_CSS}</style></head>"
         '<body><div class="wrap">'
         f'<nav class="side" aria-label="Primary"><div class="brand">engram</div>{links}</nav>'
         f"<main>{body_html}</main>"
diff --git a/cli/engram/web/server.py b/cli/engram/web/server.py
index c3a071b..17e98d2 100644
--- a/cli/engram/web/server.py
+++ b/cli/engram/web/server.py
@@ -27,6 +27,7 @@
 DEFAULT_HOST = "127.0.0.1"
 DEFAULT_PORT = 8787
 _LOOPBACK = {"127.0.0.1", "::1", "localhost"}
+_CSP_BASE = "default-src 'self'"
 
 
 @dataclass(frozen=True, slots=True)
@@ -34,10 +35,24 @@ class Response:
     status: int
     body: str
     content_type: str = "text/html; charset=utf-8"
+    csp: str = _CSP_BASE
 
 
 def _page(title: str, body: str, active: str, status: int = 200) -> Response:
-    return Response(status=status, body=layout(title, body, active=active))
+    """Render a page and pair it with a CSP that admits exactly its own style block.
+
+    All styling is a single inline ``<style>``. A bare ``default-src 'self'``
+    drops it — the browser then renders the app with no CSS at all, which reads
+    as a broken deploy rather than as a blocked resource. Rather than opening the
+    policy with ``'unsafe-inline'`` (which would admit *any* injected style), each
+    response carries a fresh nonce matching only this one block.
+    """
+    nonce = secrets.token_urlsafe(16)
+    return Response(
+        status=status,
+        body=layout(title, body, active=active, style_nonce=nonce),
+        csp=f"{_CSP_BASE}; style-src 'nonce-{nonce}'",
+    )
 
 
 def route(path: str, query: dict[str, str], root: Path) -> Response:
@@ -57,6 +72,12 @@ def route(path: str, query: dict[str, str], root: Path) -> Response:
             return _page("Workflows", pages.render_workflows(root), "/workflows")
         if path == "/kb":
             return _page("Knowledge Base", pages.render_kb(root), "/kb")
+        if path.startswith("/kb/"):
+            topic = urllib.parse.unquote(path[len("/kb/") :]).rstrip("/")
+            body = pages.render_kb_detail(root, topic)
+            if body is None:
+                return _page("Not found", _not_found(f"KB article {topic!r}"), "/kb", 404)
+            return _page("Knowledge Base", body, "/kb")
         if path == "/inbox":
             return _page("Inbox", pages.render_inbox(root), "/inbox")
         if path == "/context":
@@ -132,8 +153,9 @@ def do_GET(self) -> None:
             self.send_response(resp.status)
             self.send_header("Content-Type", resp.content_type)
             self.send_header("Content-Length", str(len(payload)))
-            # Defense-in-depth on top of uniform output escaping.
-            self.send_header("Content-Security-Policy", "default-src 'self'")
+            # Defense-in-depth on top of uniform output escaping. The policy
+            # travels with the response so the per-page style nonce matches.
+            self.send_header("Content-Security-Policy", resp.csp)
             self.send_header("X-Content-Type-Options", "nosniff")
             self.end_headers()
             self.wfile.write(payload)
diff --git a/tests/unit/cli/test_web.py b/tests/unit/cli/test_web.py
index 0a8ba2d..72abd9f 100644
--- a/tests/unit/cli/test_web.py
+++ b/tests/unit/cli/test_web.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import base64
+import re
 import threading
 import urllib.error
 import urllib.request
@@ -12,6 +13,7 @@
 from click.testing import CliRunner
 
 from engram.cli import cli
+from engram.web.markdown import extract_headings, render_markdown
 from engram.web.render import esc, layout
 from engram.web.server import route, serve
 
@@ -280,3 +282,155 @@ def boom() -> object:
     second = route("/context", {"task": "confirm before pushing", "budget": "4000"}, project)
     assert second.status == 200
     assert attempts == [1]
+
+
+# ----------------------------------------------------------------------
+# CSP nonce — the inline <style> must survive the policy
+# ----------------------------------------------------------------------
+
+
+def test_style_nonce_matches_csp_header(project: Path) -> None:
+    """The nonce on the style block and the one in the policy must be the same
+    string, or the browser drops every rule and the page renders unstyled."""
+    resp = route("/", {}, project)
+    style = re.search(r'<style nonce="([A-Za-z0-9_-]+)">', resp.body)
+    policy = re.search(r"style-src 'nonce-([A-Za-z0-9_-]+)'", resp.csp)
+    assert style is not None, "style block carries no nonce"
+    assert policy is not None, "CSP names no style nonce"
+    assert style.group(1) == policy.group(1)
+
+
+def test_style_nonce_is_per_response(project: Path) -> None:
+    a = re.search(r'<style nonce="([A-Za-z0-9_-]+)">', route("/", {}, project).body)
+    b = re.search(r'<style nonce="([A-Za-z0-9_-]+)">', route("/kb", {}, project).body)
+    assert a and b and a.group(1) != b.group(1)
+
+
+def test_csp_does_not_allow_unsafe_inline(project: Path) -> None:
+    """A nonce is the point — falling back to 'unsafe-inline' would admit any
+    injected style, which is what the nonce exists to prevent."""
+    assert "unsafe-inline" not in route("/", {}, project).csp
+
+
+def test_layout_rejects_malformed_nonce() -> None:
+    with pytest.raises(ValueError):
+        layout("t", "<p>x</p>", style_nonce='" onload="alert(1)')
+
+
+# ----------------------------------------------------------------------
+# KB article detail
+# ----------------------------------------------------------------------
+
+
+def _make_kb(project: Path, topic: str = "demo") -> Path:
+    art = project / ".memory" / "kb" / topic
+    art.mkdir(parents=True)
+    (art / "README.md").write_text(
+        "---\nname: Demo Article\ndescription: a demo\ntype: kb\nscope: project\n"
+        "chapters:\n  - 01-intro.md\nlifecycle_state: draft\n---\n\n## Abstract\n\nHello.\n",
+        encoding="utf-8",
+    )
+    (art / "01-intro.md").write_text(
+        "---\ntitle: Intro\n---\n\n# Intro\n\nBody text.\n\n"
+        "| a | b |\n|---|---|\n| 1 | 2 |\n\n```c\nint x = 1;\n```\n",
+        encoding="utf-8",
+    )
+    return art
+
+
+def test_kb_detail_renders_chapters(project: Path) -> None:
+    _make_kb(project)
+    resp = route("/kb/demo", {}, project)
+    assert resp.status == 200
+    assert "Demo Article" in resp.body
+    assert "<table>" in resp.body and "<pre><code" in resp.body
+    assert 'class="kb-toc"' in resp.body
+
+
+def test_kb_list_links_to_detail(project: Path) -> None:
+    _make_kb(project)
+    assert 'href="/kb/demo"' in route("/kb", {}, project).body
+
+
+def test_kb_detail_unknown_topic_is_404(project: Path) -> None:
+    assert route("/kb/nope", {}, project).status == 404
+
+
+@pytest.mark.parametrize("topic", ["../etc", "a/b", ".hidden", ""])
+def test_kb_detail_rejects_path_traversal(project: Path, topic: str) -> None:
+    """`topic` comes straight off the URL; it must never escape the kb root."""
+    assert route(f"/kb/{topic}", {}, project).status == 404
+
+
+def test_kb_detail_escapes_chapter_content(project: Path) -> None:
+    art = _make_kb(project)
+    (art / "01-intro.md").write_text("# T\n\n<script>alert(1)</script>\n", encoding="utf-8")
+    body = route("/kb/demo", {}, project).body
+    assert "<script>alert(1)</script>" not in body
+    assert "&lt;script&gt;" in body
+
+
+def test_kb_detail_skips_chapter_outside_article_dir(project: Path) -> None:
+    """A `chapters:` entry is author-controlled and must not reach outside."""
+    art = _make_kb(project)
+    (art / "README.md").write_text(
+        "---\nname: Demo\ndescription: d\ntype: kb\nscope: project\n"
+        "chapters:\n  - ../../../etc/passwd\nlifecycle_state: draft\n---\n",
+        encoding="utf-8",
+    )
+    resp = route("/kb/demo", {}, project)
+    assert resp.status == 200
+    assert "root:" not in resp.body
+
+
+# ----------------------------------------------------------------------
+# Markdown renderer
+# ----------------------------------------------------------------------
+
+
+def test_markdown_blocks() -> None:
+    html = render_markdown(
+        "# H1\n\npara\n\n- one\n- two\n\n| a | b |\n|---|---|\n| 1 | 2 |\n\n"
+        "```py\nx=1\n```\n\n> quote\n\n---\n"
+    )
+    for frag in ("<h1", "<p>para</p>", "<ul>", "<table>", "<pre><code", "<blockquote>", "<hr>"):
+        assert frag in html, frag
+
+
+def test_markdown_inline() -> None:
+    html = render_markdown("**b** and `c` and [x](/y) and *i*")
+    assert "<strong>b</strong>" in html
+    assert "<code>c</code>" in html
+    assert '<a href="/y">x</a>' in html
+    assert "<em>i</em>" in html
+
+
+def test_markdown_escapes_html() -> None:
+    assert "<script>" not in render_markdown("<script>alert(1)</script>")
+
+
+def test_markdown_rejects_javascript_href() -> None:
+    """A link target is author text; only same-document and http(s) targets render
+    as links, everything else degrades to its label."""
+    html = render_markdown("[click](javascript:alert(1))")
+    assert "href=\"javascript" not in html
+    assert "click" in html
+
+
+def test_markdown_code_span_is_not_reparsed() -> None:
+    html = render_markdown("`**not bold**`")
+    assert "<strong>" not in html
+
+
+def test_markdown_unterminated_fence_does_not_hang() -> None:
+    assert "<pre><code" in render_markdown("```\nunclosed\n")
+
+
+def test_extract_headings_skips_fenced_code() -> None:
+    heads = extract_headings("# real\n\n```\n# not a heading\n```\n")
+    assert [t for _lv, t, _a in heads] == ["real"]
+
+
+def test_heading_anchors_are_unique() -> None:
+    anchors = [a for _lv, _t, a in extract_headings("## dup\n\n## dup\n")]
+    assert len(set(anchors)) == 2