Enforce Birch skill staging and normalize CSS marker

research/agent-cards/birch-html.md

@@ -6,6 +6,8 @@ servers:
   - hf
 skills:
   - skills/birch-html
+function_tools:
+  - ../birch_renderer.py:read_birch_skill_file
 use_history: false
 model: $system.html
 tool_hooks:
@@ -17,6 +19,14 @@ Use the Birch HTML skill for polished, shareable, source-grounded HTML reports,
 briefings, dashboards, explainers, visual summaries, and presentation-style
 deliverables.
 
+Before calling any Hugging Face tool or drafting HTML:
+
+1. Call `read_birch_skill_file(path="SKILL.md")`.
+2. Call `read_birch_skill_file(path="resources/template.html")`.
+3. Read the one or two recipes most relevant to the report.
+4. Follow the canonical template and primitives exactly. Do not recreate Birch
+   typography, shells, cards, grids, tables, badges, or colors in local CSS.
+
 You receive researched content, source notes, and an output path from the
 research agent. Produce a complete Birch HTML artifact and save it under the
 provided `output/` bucket path. Use `scratch/` only for temporary drafts or
@@ -36,10 +46,12 @@ Preserve evidence:
   and not-applicable artifacts.
 
 Write the complete draft to `scratch/report.html` with the exact
-`__BIRCH_SYSTEM_CSS__` placeholder, verify that the draft was written, and
-return the draft path. Do not call Hugging Face Jobs, sandboxes, or a remote
-finalizer. The host application deterministically injects the trusted bundled
-stylesheet and publishes `output/report.html` after the research agent returns.
+`<style data-birch-system>__BIRCH_SYSTEM_CSS__</style>` element, verify that the
+draft was written, and return only the draft path and a concise staging note.
+Do not call Hugging Face Jobs, sandboxes, or a remote finalizer. Do not write
+`output/report.html`. The host application deterministically injects the trusted
+bundled stylesheet and publishes `output/report.html` after the research agent
+returns.
 
 {{env}}
 {{currentDate}}

research/agent-cards/research.md

@@ -52,6 +52,11 @@ only after it verifies a self-contained file with substantive embedded
 report the exact failure and the usable Markdown path. Never manually upload
 placeholder HTML and describe it as polished.
 
+After the `birch-html` subagent returns, do not inspect, copy, rewrite, validate,
+or publish its draft. Do not call another tool and never write
+`output/report.html`. End the turn with the staged draft path; host finalization
+is the only publisher.
+
 {{env}}
 {{currentDate}}
 {{serverInstructions}}

research/app_artifacts.py

@@ -19,6 +19,10 @@ STYLE_RE = re.compile(
     r"<style\b(?=[^>]*\bdata-birch-system\b)[^>]*>.*?</style>",
     re.I | re.S,
 )
+MARKER_STYLE_RE = re.compile(
+    rf"<style\b[^>]*>\s*{re.escape(MARKER)}\s*</style>",
+    re.I | re.S,
+)
 
 
 def finalize_bucket_html(
@@ -58,7 +62,7 @@ def finalize_bucket_html(
             return _artifact_urls(username, job.id)
 
         css = _birch_css_path(home).read_text()
-        finalized = html.replace(MARKER, css.strip())
+        finalized = _inject_birch_css(html, css)
         _validate_html(finalized)
         api.batch_bucket_files(
             bucket_id,
@@ -98,6 +102,14 @@ def read_bucket_markdown(
         return local.read_text()
 
 
+def _inject_birch_css(html: str, css: str) -> str:
+    """Normalize a marker-only style element and inject trusted Birch CSS."""
+    replacement = f"<style data-birch-system>{css.strip()}</style>"
+    if MARKER_STYLE_RE.search(html):
+        return MARKER_STYLE_RE.sub(replacement, html, count=1)
+    return html.replace(MARKER, css.strip())
+
+
 def _download_first(
     api: Any,
     bucket_id: str,