devcouncil 0.1.1 → 0.3.0

package/src/devcouncil/reporting/okf_bundle_writer.py

@@ -0,0 +1,364 @@
+"""Export DevCouncil's artifact graph as an Open Knowledge Format (OKF) bundle.
+
+DevCouncil already keeps a durable Requirement→Task→Evidence→Gap graph; OKF is the natural
+portable wire format for it. This writer renders that graph as a cross-linked directory of
+markdown+frontmatter documents (an :class:`devcouncil.knowledge.okf.OKFBundle`) that any
+OKF-aware agent — or the upstream OKF HTML visualizer — can consume, with the relationships
+expressed as real markdown links so the "linked graph" property holds.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from devcouncil.artifacts.graph import ArtifactGraph
+from devcouncil.indexing.repo_mapper import RepoMap
+from devcouncil.knowledge.okf import OKFBundle, OKFDocument, write_bundle
+
+_SLUG_RE = re.compile(r"[^a-zA-Z0-9._-]+")
+
+
+def _slug(value: str) -> str:
+    return _SLUG_RE.sub("-", value).strip("-") or "item"
+
+
+def _link(rel_from: str, rel_to: str, text: str) -> str:
+    """A markdown link from one bundle document to another, as a relative path."""
+    from_parts = rel_from.split("/")[:-1]
+    to_parts = rel_to.split("/")
+    # Compute a relative path (both live under the same bundle root).
+    i = 0
+    while i < len(from_parts) and i < len(to_parts) - 1 and from_parts[i] == to_parts[i]:
+        i += 1
+    up = [".."] * (len(from_parts) - i)
+    down = to_parts[i:]
+    rel = "/".join(up + down) or rel_to.split("/")[-1]
+    return f"[{text}]({rel})"
+
+
+class OKFBundleWriter:
+    """Builds an OKF bundle from an :class:`ArtifactGraph` and writes it to disk."""
+
+    @staticmethod
+    def build(
+        graph: ArtifactGraph,
+        repo_map: RepoMap | None = None,
+        project_name: str = "DevCouncil Project",
+        timestamp: str = "",
+        include_skills: bool = False,
+        skills: "list | None" = None,
+        include_design: bool = False,
+        design=None,
+    ) -> OKFBundle:
+        """Build the in-memory :class:`OKFBundle` (no filesystem writes).
+
+        When ``include_skills`` is set and ``skills`` are supplied, each engineering skill
+        is rendered as an OKF document (via the shared :mod:`skill_bridge`) under
+        ``skills/`` and indexed by a ``skills/index.md`` node so the bundle stays a single
+        connected, link-valid graph. Default behavior (no skills) is unchanged.
+
+        Symmetrically, when ``include_design`` is set and a ``design`` (a
+        :class:`devcouncil.knowledge.design.DesignSystem`) is supplied, it is rendered as a
+        ``Design System`` OKF document under ``design/`` and indexed by ``design/index.md``,
+        which the root index links. Default behavior (no design) is unchanged.
+        """
+        docs: list[OKFDocument] = []
+
+        # Pre-compute task ids covering each requirement, for cross-linking.
+        tasks_for_req: dict[str, list[str]] = {}
+        for task in graph.tasks.values():
+            for rid in task.requirement_ids:
+                tasks_for_req.setdefault(rid, []).append(task.id)
+
+        # --- Requirements ---
+        for req in graph.requirements.values():
+            rel = f"requirements/{_slug(req.id)}.md"
+            lines = [req.description.strip(), ""]
+            if req.acceptance_criteria:
+                lines.append("### Acceptance criteria")
+                for ac in req.acceptance_criteria:
+                    flag = "required" if ac.required else "optional"
+                    lines.append(f"- `{ac.id}` ({ac.verification_method}, {flag}): {ac.description}")
+                lines.append("")
+            covering = tasks_for_req.get(req.id, [])
+            if covering:
+                lines.append("### Covered by")
+                for tid in covering:
+                    lines.append(f"- {_link(rel, f'tasks/{_slug(tid)}.md', tid)}")
+            docs.append(OKFDocument(
+                type="DevCouncil Requirement",
+                title=f"{req.id}: {req.title}",
+                description=req.description.strip()[:280],
+                tags=["requirement", req.priority, req.source],
+                timestamp=timestamp,
+                body="\n".join(lines).strip(),
+                rel_path=rel,
+            ))
+
+        # --- Tasks ---
+        diffs_by_task: dict[str, list] = {}
+        for de in graph.diff_evidence:
+            diffs_by_task.setdefault(de.task_id, []).append(de)
+        gaps_by_task: dict[str, list] = {}
+        for gap in graph.gaps.values():
+            if gap.task_id:
+                gaps_by_task.setdefault(gap.task_id, []).append(gap)
+
+        for task in graph.tasks.values():
+            rel = f"tasks/{_slug(task.id)}.md"
+            lines = [task.description.strip(), ""]
+            if task.requirement_ids:
+                lines.append("### Implements")
+                for rid in task.requirement_ids:
+                    label = rid
+                    if rid in graph.requirements:
+                        lines.append(f"- {_link(rel, f'requirements/{_slug(rid)}.md', label)}")
+                    else:
+                        lines.append(f"- {label}")
+                lines.append("")
+            if task.planned_files:
+                lines.append("### Planned files")
+                for pf in task.planned_files:
+                    lines.append(f"- `{pf.path}` ({pf.allowed_change}): {pf.reason}")
+                lines.append("")
+            if task.id in diffs_by_task:
+                lines.append("### Evidence")
+                for idx, _de in enumerate(diffs_by_task[task.id]):
+                    ev_rel = f"evidence/{_slug(task.id)}-diff-{idx}.md"
+                    lines.append(f"- {_link(rel, ev_rel, 'diff evidence')}")
+                lines.append("")
+            if task.id in gaps_by_task:
+                lines.append("### Open gaps")
+                for gap in gaps_by_task[task.id]:
+                    lines.append(f"- {_link(rel, f'gaps/{_slug(gap.id)}.md', gap.id)}")
+            docs.append(OKFDocument(
+                type="DevCouncil Task",
+                title=f"{task.id}: {task.title}",
+                description=task.description.strip()[:280],
+                tags=["task", task.status],
+                timestamp=timestamp,
+                body="\n".join(lines).strip(),
+                rel_path=rel,
+            ))
+
+        # --- Evidence (diff evidence as documents; resource points at the diff summary) ---
+        for task_id, evs in diffs_by_task.items():
+            for idx, de in enumerate(evs):
+                rel = f"evidence/{_slug(task_id)}-diff-{idx}.md"
+                body_lines = [de.diff_summary.strip(), ""]
+                if de.changed_files:
+                    body_lines.append("**Changed files:**")
+                    body_lines.extend(f"- `{f}`" for f in de.changed_files)
+                if task_id in graph.tasks:
+                    body_lines.append("")
+                    body_lines.append(f"Produced by {_link(rel, f'tasks/{_slug(task_id)}.md', task_id)}.")
+                docs.append(OKFDocument(
+                    type="DevCouncil Evidence",
+                    title=f"Diff evidence for {task_id}",
+                    description=de.diff_summary.strip()[:280],
+                    tags=["evidence", "diff"],
+                    timestamp=timestamp,
+                    body="\n".join(body_lines).strip(),
+                    rel_path=rel,
+                ))
+
+        # --- Gaps ---
+        for gap in graph.gaps.values():
+            rel = f"gaps/{_slug(gap.id)}.md"
+            lines = [gap.description.strip(), ""]
+            lines.append(f"**Recommended fix:** {gap.recommended_fix.strip()}")
+            lines.append("")
+            related = []
+            if gap.requirement_id and gap.requirement_id in graph.requirements:
+                related.append(_link(rel, f"requirements/{_slug(gap.requirement_id)}.md", gap.requirement_id))
+            if gap.task_id and gap.task_id in graph.tasks:
+                related.append(_link(rel, f"tasks/{_slug(gap.task_id)}.md", gap.task_id))
+            if related:
+                lines.append("**Related:** " + ", ".join(related))
+            docs.append(OKFDocument(
+                type="DevCouncil Gap",
+                title=f"{gap.id}: {gap.gap_type}",
+                description=gap.description.strip()[:280],
+                tags=["gap", gap.severity, "blocking" if gap.blocking else "non-blocking"],
+                timestamp=timestamp,
+                body="\n".join(lines).strip(),
+                rel_path=rel,
+            ))
+
+        # --- Engineering skills (optional) ---
+        skill_docs = (
+            OKFBundleWriter._build_skill_docs(skills, timestamp)
+            if include_skills and skills
+            else []
+        )
+        docs.extend(skill_docs)
+
+        # --- Design system (optional) ---
+        design_doc = (
+            OKFBundleWriter._build_design_doc(design, timestamp)
+            if include_design and design is not None
+            else None
+        )
+        if design_doc is not None:
+            docs.append(design_doc)
+
+        # --- index.md hierarchy ---
+        docs.extend(
+            OKFBundleWriter._build_indexes(graph, project_name, timestamp, skill_docs, design_doc)
+        )
+
+        return OKFBundle(documents=docs)
+
+    @staticmethod
+    def _build_design_doc(design, timestamp: str) -> OKFDocument:
+        """Render a design system as an OKF document under ``design/``.
+
+        Conversion goes through :func:`design.design_system_to_okf_document` so the bundle
+        and any future design ingest share one DesignSystem<->OKF mapping. The bundle-level
+        ``timestamp`` is stamped on (the renderer itself leaves it empty as library content).
+        """
+        from devcouncil.knowledge.design import design_system_to_okf_document
+
+        doc = design_system_to_okf_document(design)
+        if timestamp:
+            doc = doc.model_copy(update={"timestamp": timestamp})
+        return doc
+
+    @staticmethod
+    def _build_skill_docs(skills: "list", timestamp: str) -> list[OKFDocument]:
+        """Render engineering skills as OKF documents under ``skills/``.
+
+        Conversion goes through :func:`skill_bridge.skill_to_okf_document` so the export
+        side and the ingest side share one Skill<->OKF mapping and can't drift. The
+        bundle-level ``timestamp`` is stamped on so skill nodes carry the same export time
+        as the rest of the bundle (the bridge itself leaves it empty as library content).
+        """
+        from devcouncil.knowledge.skill_bridge import skill_to_okf_document
+
+        out: list[OKFDocument] = []
+        for skill in skills:
+            doc = skill_to_okf_document(skill)
+            if timestamp:
+                doc = doc.model_copy(update={"timestamp": timestamp})
+            out.append(doc)
+        return out
+
+    @staticmethod
+    def _build_indexes(
+        graph: ArtifactGraph,
+        project_name: str,
+        timestamp: str,
+        skill_docs: "list[OKFDocument] | None" = None,
+        design_doc: "OKFDocument | None" = None,
+    ) -> list[OKFDocument]:
+        indexes: list[OKFDocument] = []
+        summary = graph.coverage_summary()
+        skill_docs = skill_docs or []
+
+        def section_index(folder: str, title: str, items: list[tuple[str, str]]) -> None:
+            rel = f"{folder}/index.md"
+            lines = [f"{len(items)} {title.lower()}.", ""]
+            for item_id, item_title in items:
+                lines.append(f"- {_link(rel, f'{folder}/{_slug(item_id)}.md', item_title)}")
+            indexes.append(OKFDocument(
+                type="OKF Index",
+                title=title,
+                description=f"{len(items)} {title.lower()} exported from DevCouncil.",
+                timestamp=timestamp,
+                body="\n".join(lines).strip(),
+                rel_path=rel,
+            ))
+
+        section_index("requirements", "Requirements",
+                      [(r.id, f"{r.id}: {r.title}") for r in graph.requirements.values()])
+        section_index("tasks", "Tasks",
+                      [(t.id, f"{t.id}: {t.title}") for t in graph.tasks.values()])
+        section_index("gaps", "Gaps",
+                      [(g.id, f"{g.id}: {g.gap_type}") for g in graph.gaps.values()])
+
+        # Skills index — links to each skill document so they join the connected graph.
+        if skill_docs:
+            rel = "skills/index.md"
+            lines = [f"{len(skill_docs)} engineering skills.", ""]
+            for doc in skill_docs:
+                lines.append(f"- {_link(rel, doc.rel_path, doc.title or doc.rel_path)}")
+            indexes.append(OKFDocument(
+                type="OKF Index",
+                title="Skills",
+                description=f"{len(skill_docs)} engineering skills exported from DevCouncil.",
+                timestamp=timestamp,
+                body="\n".join(lines).strip(),
+                rel_path=rel,
+            ))
+
+        # Design index — links to the single design document so it joins the graph.
+        if design_doc is not None:
+            rel = "design/index.md"
+            lines = [
+                "1 design system.",
+                "",
+                f"- {_link(rel, design_doc.rel_path, design_doc.title or design_doc.rel_path)}",
+            ]
+            indexes.append(OKFDocument(
+                type="OKF Index",
+                title="Design System",
+                description="Design system exported from DevCouncil.",
+                timestamp=timestamp,
+                body="\n".join(lines).strip(),
+                rel_path=rel,
+            ))
+
+        # Root index links to each section index.
+        root_lines = [
+            f"Knowledge bundle exported from **{project_name}** in Open Knowledge Format.",
+            "",
+            "### Coverage",
+            f"- Requirements: {summary['total_requirements']}",
+            f"- Tasks: {summary['total_tasks']}",
+            f"- Acceptance criteria: {summary['total_ac']} ({summary['ac_without_evidence']} without evidence)",
+            f"- Gaps: {summary['total_gaps']} ({summary['blocking_gaps']} blocking)",
+            "",
+            "### Sections",
+            "- [Requirements](requirements/index.md)",
+            "- [Tasks](tasks/index.md)",
+            "- [Gaps](gaps/index.md)",
+        ]
+        if skill_docs:
+            root_lines.append("- [Skills](skills/index.md)")
+        if design_doc is not None:
+            root_lines.append("- [Design System](design/index.md)")
+        indexes.append(OKFDocument(
+            type="OKF Index",
+            title=project_name,
+            description="DevCouncil artifact graph exported as an OKF knowledge bundle.",
+            timestamp=timestamp,
+            body="\n".join(root_lines).strip(),
+            rel_path="index.md",
+        ))
+        return indexes
+
+    @staticmethod
+    def generate(
+        graph: ArtifactGraph,
+        output_dir: Path,
+        repo_map: RepoMap | None = None,
+        project_name: str = "DevCouncil Project",
+        timestamp: str = "",
+        include_skills: bool = False,
+        skills: "list | None" = None,
+        include_design: bool = False,
+        design=None,
+    ) -> list[Path]:
+        """Build the bundle and write it under ``output_dir``; returns written paths."""
+        bundle = OKFBundleWriter.build(
+            graph,
+            repo_map,
+            project_name,
+            timestamp,
+            include_skills=include_skills,
+            skills=skills,
+            include_design=include_design,
+            design=design,
+        )
+        return write_bundle(bundle, output_dir)

package/src/devcouncil/reporting/okf_html.py

@@ -0,0 +1,323 @@
+"""Render an OKF bundle as a self-contained, browsable static HTML site.
+
+Parity with the upstream OKF HTML visualizer: a directory of markdown nodes becomes a
+directory of HTML pages — one ``index.html`` listing every document grouped by OKF
+``type``, plus one page per document showing its frontmatter header and rendered body.
+Intra-bundle markdown links (the relative ``*.md`` targets that
+:func:`devcouncil.knowledge.okf.read_bundle` resolves into :attr:`OKFDocument.links`) are
+rewritten to point at the generated ``*.html`` pages so navigation works offline; external
+URLs and the ``resource`` field are preserved as-is.
+
+Security: every string taken from the bundle — titles, descriptions, tags, body text,
+code, link labels, and link targets — is HTML-escaped, and link hrefs are scheme-checked
+so a hostile or malformed bundle cannot inject markup or a ``javascript:`` href. Only the
+structural HTML this module emits is literal. The output is one inlined ``<style>`` block
+with no external assets, no network calls, and no JavaScript.
+"""
+
+from __future__ import annotations
+
+import html
+import posixpath
+import re
+from pathlib import Path
+
+from devcouncil.knowledge.okf import OKFBundle, OKFDocument, _resolve_link
+
+# Inline markdown constructs. Applied in a deliberate order (code, then links, then
+# bold/italic on already-escaped text) via placeholder stashing so escaping never mangles
+# generated tags and generated tags never get re-parsed.
+_CODE_RE = re.compile(r"`([^`]+)`")
+_LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+_BOLD_RE = re.compile(r"\*\*([^*]+)\*\*")
+_ITALIC_RE = re.compile(r"(?<!\*)\*(?!\*)([^*]+)\*(?!\*)")
+_PLACEHOLDER_RE = re.compile(r"__PH_(\d+)__")
+_TABLE_SEP_RE = re.compile(r"\s*\|?[\s:|-]*-[\s:|-]*\|?\s*")
+
+_URL_SCHEME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9+.-]*://")
+_BAD_SCHEME_RE = re.compile(r"^(?:javascript|data|vbscript):", re.IGNORECASE)
+# Whitespace + C0 control chars. Browsers strip these from a URL before resolving its
+# scheme, so they must be removed before the scheme check — otherwise "java&#9;script:"
+# or " javascript:" slips past the guard yet still executes once the browser reassembles it.
+_SCHEME_NOISE_RE = re.compile(r"[\x00-\x20]+")
+
+
+def _is_dangerous_scheme(target: str) -> bool:
+    """True if ``target`` carries a dangerous URL scheme, even when obfuscated with leading
+    or interior whitespace / control characters (e.g. ``java\\tscript:``, `` javascript:``)."""
+    return bool(_BAD_SCHEME_RE.match(_SCHEME_NOISE_RE.sub("", target)))
+
+_STYLE = """
+body{font:16px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;
+max-width:52rem;margin:2rem auto;padding:0 1rem;color:#1a1a1a;background:#fff}
+h1,h2,h3,h4{line-height:1.25}a{color:#0b66c3}code{background:#f3f3f3;padding:.1em .3em;
+border-radius:3px;font-size:.9em}pre{background:#f6f8fa;padding:1rem;border-radius:6px;
+overflow:auto}pre code{background:none;padding:0}table{border-collapse:collapse;width:100%}
+th,td{border:1px solid #ddd;padding:.4rem .6rem;text-align:left}
+.meta{color:#555;font-size:.9em}.tag{display:inline-block;background:#eef3fb;color:#0b66c3;
+border-radius:10px;padding:.05em .6em;margin:.1em .2em .1em 0;font-size:.8em}
+.doc-list{list-style:none;padding:0}.doc-list li{margin:.4rem 0}
+.type-group{margin:1.4rem 0}.crumb{font-size:.9em;margin-bottom:1rem}
+""".strip()
+
+
+def _md_to_html_rel(rel_md: str) -> str:
+    """Map a bundle-relative ``*.md`` path to its generated ``*.html`` page path."""
+    return rel_md[:-3] + ".html" if rel_md.endswith(".md") else rel_md + ".html"
+
+
+def _rel_href(src_html: str, dst_html: str) -> str:
+    """Relative href from one generated page to another (POSIX, URL-style)."""
+    src_dir = posixpath.dirname(src_html)
+    return posixpath.relpath(dst_html, src_dir or ".")
+
+
+def _safe_external(target: str) -> str:
+    """Escape an external/anchor link target, neutralizing dangerous schemes to ``#``."""
+    if _is_dangerous_scheme(target):
+        return "#"
+    return html.escape(target.strip(), quote=True)
+
+
+def _rewrite_link(target: str, current_md_rel: str, present: set[str]) -> str:
+    """Resolve a markdown link target into an escaped, safe href for the current page.
+
+    Intra-bundle ``*.md`` targets that resolve to a document present in the bundle become a
+    relative link to the generated ``*.html`` page (anchors preserved); everything else
+    (external URLs, mailto, in-page anchors, unresolved targets) is escaped and scheme-
+    checked but otherwise left to behave as a normal link.
+    """
+    t = target.strip()
+    if not t or _is_dangerous_scheme(t):
+        return "#"
+    if t.startswith("#") or t.startswith("mailto:") or _URL_SCHEME_RE.match(t):
+        return _safe_external(t)
+    base, sep, anchor = t.partition("#")
+    resolved = _resolve_link(current_md_rel, base)
+    if resolved and resolved in present:
+        dst = _md_to_html_rel(resolved)
+        href = _rel_href(_md_to_html_rel(current_md_rel), dst)
+        if sep:
+            href = f"{href}#{anchor}"
+        return html.escape(href, quote=True)
+    return _safe_external(t)
+
+
+def _render_inline(text: str, current_md_rel: str, present: set[str]) -> str:
+    """Render inline markdown (code, links, bold, italic) with everything escaped."""
+    stash: list[str] = []
+
+    def _stash(fragment: str) -> str:
+        stash.append(fragment)
+        return f"__PH_{len(stash) - 1}__"
+
+    text = _CODE_RE.sub(lambda m: _stash(f"<code>{html.escape(m.group(1))}</code>"), text)
+    text = _LINK_RE.sub(
+        lambda m: _stash(
+            f'<a href="{_rewrite_link(m.group(2), current_md_rel, present)}">'
+            f"{html.escape(m.group(1))}</a>"
+        ),
+        text,
+    )
+    text = html.escape(text)
+    text = _BOLD_RE.sub(r"<strong>\1</strong>", text)
+    text = _ITALIC_RE.sub(r"<em>\1</em>", text)
+    return _PLACEHOLDER_RE.sub(lambda m: stash[int(m.group(1))], text)
+
+
+def _render_table(rows: list[str], current_md_rel: str, present: set[str]) -> str:
+    """Render a GitHub-style pipe table (header row + ``---`` separator + body rows)."""
+    def cells(line: str) -> list[str]:
+        return [c.strip() for c in line.strip().strip("|").split("|")]
+
+    header = cells(rows[0])
+    body = [cells(r) for r in rows[2:]]
+    head_html = "".join(f"<th>{_render_inline(c, current_md_rel, present)}</th>" for c in header)
+    body_html = "".join(
+        "<tr>" + "".join(f"<td>{_render_inline(c, current_md_rel, present)}</td>" for c in r) + "</tr>"
+        for r in body
+    )
+    return f"<table><thead><tr>{head_html}</tr></thead><tbody>{body_html}</tbody></table>"
+
+
+def _is_table_sep(line: str) -> bool:
+    return bool(_TABLE_SEP_RE.fullmatch(line)) and "-" in line
+
+
+def render_markdown(body: str, current_md_rel: str, present: set[str]) -> str:
+    """Convert an OKF document body to HTML (minimal, dependency-free, fully escaped)."""
+    lines = body.splitlines()
+    out: list[str] = []
+    i, n = 0, len(lines)
+    para: list[str] = []
+    list_items: list[str] = []
+    list_tag = ""
+
+    def flush_para() -> None:
+        if para:
+            out.append(f"<p>{_render_inline(' '.join(para), current_md_rel, present)}</p>")
+            para.clear()
+
+    def flush_list() -> None:
+        nonlocal list_tag
+        if list_items:
+            inner = "".join(f"<li>{it}</li>" for it in list_items)
+            out.append(f"<{list_tag}>{inner}</{list_tag}>")
+            list_items.clear()
+            list_tag = ""
+
+    while i < n:
+        line = lines[i]
+        stripped = line.strip()
+
+        if stripped.startswith("```"):  # fenced code block
+            flush_para()
+            flush_list()
+            i += 1
+            code: list[str] = []
+            while i < n and not lines[i].strip().startswith("```"):
+                code.append(lines[i])
+                i += 1
+            i += 1  # consume closing fence
+            out.append(f"<pre><code>{html.escape(chr(10).join(code))}</code></pre>")
+            continue
+
+        if not stripped:  # blank line
+            flush_para()
+            flush_list()
+            i += 1
+            continue
+
+        heading = re.match(r"^(#{1,6})\s+(.*)$", stripped)
+        if heading:
+            flush_para()
+            flush_list()
+            level = len(heading.group(1))
+            out.append(f"<h{level}>{_render_inline(heading.group(2), current_md_rel, present)}</h{level}>")
+            i += 1
+            continue
+
+        if re.fullmatch(r"(?:-\s*){3,}|(?:\*\s*){3,}|(?:_\s*){3,}", stripped):
+            flush_para()
+            flush_list()
+            out.append("<hr>")
+            i += 1
+            continue
+
+        if "|" in line and i + 1 < n and _is_table_sep(lines[i + 1]):
+            flush_para()
+            flush_list()
+            table_rows = [line, lines[i + 1]]
+            i += 2
+            while i < n and "|" in lines[i] and lines[i].strip():
+                table_rows.append(lines[i])
+                i += 1
+            out.append(_render_table(table_rows, current_md_rel, present))
+            continue
+
+        ul = re.match(r"^[-*+]\s+(.*)$", stripped)
+        ol = re.match(r"^\d+[.)]\s+(.*)$", stripped)
+        if ul or ol:
+            flush_para()
+            tag = "ul" if ul else "ol"
+            if list_tag and list_tag != tag:
+                flush_list()
+            list_tag = tag
+            match = ul or ol  # one is non-None inside this branch
+            content = match.group(1) if match else ""
+            list_items.append(_render_inline(content, current_md_rel, present))
+            i += 1
+            continue
+
+        flush_list()
+        para.append(stripped)
+        i += 1
+
+    flush_para()
+    flush_list()
+    return "\n".join(out)
+
+
+def _page(title: str, breadcrumb: str, content: str) -> str:
+    """Wrap rendered content in a complete, self-contained HTML document."""
+    return (
+        "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n"
+        "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n"
+        f"<title>{html.escape(title)}</title>\n<style>{_STYLE}</style>\n</head>\n<body>\n"
+        f"{breadcrumb}{content}\n</body>\n</html>\n"
+    )
+
+
+def _doc_header(doc: OKFDocument) -> str:
+    """The frontmatter block (type, title, description, resource, tags, timestamp)."""
+    parts = [f"<h1>{html.escape(doc.title or doc.rel_path or doc.type)}</h1>"]
+    meta: list[str] = []
+    if doc.type:
+        meta.append(f"<strong>{html.escape(doc.type)}</strong>")
+    if doc.timestamp:
+        meta.append(html.escape(doc.timestamp))
+    if meta:
+        parts.append(f'<p class="meta">{" · ".join(meta)}</p>')
+    if doc.description:
+        parts.append(f"<p>{html.escape(doc.description)}</p>")
+    if doc.resource:
+        href = _safe_external(doc.resource)
+        parts.append(f'<p class="meta">Resource: <a href="{href}">{html.escape(doc.resource)}</a></p>')
+    if doc.tags:
+        tags = "".join(f'<span class="tag">{html.escape(str(t))}</span>' for t in doc.tags)
+        parts.append(f"<p>{tags}</p>")
+    return "\n".join(parts)
+
+
+def render_bundle_html(bundle: OKFBundle) -> dict[str, str]:
+    """Render ``bundle`` into a map of ``{relative_html_path: html_string}``.
+
+    Always includes ``index.html``; documents with a ``rel_path`` each get a page at the
+    same path with a ``.html`` extension. Documents without a ``rel_path`` are skipped
+    (they have no stable node identity to link to), matching :func:`write_bundle`.
+    """
+    present = set(bundle.by_path().keys())
+    pages: dict[str, str] = {}
+
+    # Per-document pages.
+    by_type: dict[str, list[OKFDocument]] = {}
+    for doc in bundle.documents:
+        if not doc.rel_path:
+            continue
+        by_type.setdefault(doc.type or "Untyped", []).append(doc)
+        page_rel = _md_to_html_rel(doc.rel_path)
+        depth = page_rel.count("/")
+        crumb = f'<p class="crumb"><a href="{"../" * depth}index.html">← Index</a></p>'
+        content = _doc_header(doc) + "\n" + render_markdown(doc.body, doc.rel_path, present)
+        pages[page_rel] = _page(doc.title or doc.rel_path, crumb, content)
+
+    # Index, grouped by type.
+    groups: list[str] = []
+    for type_name in sorted(by_type):
+        docs = sorted(by_type[type_name], key=lambda d: (d.title or d.rel_path).lower())
+        items: list[str] = []
+        for doc in docs:
+            href = html.escape(_rel_href("index.html", _md_to_html_rel(doc.rel_path)), quote=True)
+            label = html.escape(doc.title or doc.rel_path)
+            desc = f" — {html.escape(doc.description)}" if doc.description else ""
+            items.append(f'<li><a href="{href}">{label}</a><span class="meta">{desc}</span></li>')
+        groups.append(
+            f'<div class="type-group"><h2>{html.escape(type_name)} '
+            f'<span class="meta">({len(docs)})</span></h2>'
+            f'<ul class="doc-list">{"".join(items)}</ul></div>'
+        )
+    body = f"<h1>OKF Bundle</h1><p class=\"meta\">{len(present)} document(s)</p>" + "".join(groups)
+    pages["index.html"] = _page("OKF Bundle", "", body)
+    return pages
+
+
+def write_bundle_html(bundle: OKFBundle, out_dir: Path) -> list[Path]:
+    """Render ``bundle`` and write the static site under ``out_dir``; return written paths."""
+    out_dir = out_dir.expanduser().resolve()
+    written: list[Path] = []
+    for rel, content in render_bundle_html(bundle).items():
+        target = out_dir / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+        written.append(target)
+    return written