@laitszkin/apollo-toolkit 2.9.0 → 2.11.0

package/exam-pdf-workflow/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: exam-pdf-workflow
+description: Create, typeset, and grade exam-style PDF deliverables for study workflows. Use when the user asks to read lecture or exam PDFs, generate mock exams, produce matching solution books, render math-heavy content with KaTeX, or grade completed answer-book PDFs into a scored graded PDF.
+---
+
+# Exam PDF Workflow
+
+## Dependencies
+
+- Required: `pdf` for reading source PDFs, rendering deliverables, and final PDF QA.
+- Conditional: `document-vision-reader` when handwritten answers, scanned pages, or layout-sensitive grading require visual inspection instead of raw text extraction.
+- Conditional: `katex` when the output contains mathematical notation that should be rendered instead of left as raw TeX/plain text.
+- Optional: none.
+- Fallback: If `pdf` is unavailable, stop and report the blocked dependency instead of improvising a text-only workflow.
+
+## Standards
+
+- Evidence: Read the actual source PDFs and answer-book pages first, and verify any referenced file path against the filesystem before acting.
+- Execution: Decide the task mode first, extract the needed source content, produce the full deliverable set for that mode, then inspect rendered PDFs before finishing.
+- Quality: Treat solution books, math rendering, layout cleanup, and graded-PDF output as default completion criteria when the task implies them; do not leave raw TeX, ambiguous scoring, or unverified PDF layout behind.
+- Output: Save only the requested final PDFs in the target folder and report the exact output paths plus grading or coverage notes.
+
+## Overview
+
+Use this skill for study-material workflows where PDFs are both the input and the final deliverable. The skill covers source reading, mock-exam authoring, solution generation, math typesetting, handwritten-answer grading, and graded-PDF production.
+
+## Workflow
+
+### 1) Confirm the real input/output paths
+
+- Verify every user-mentioned PDF path on disk before reading it.
+- If the named file is missing but a clearly matching nearby file exists, switch to the real file and state the exact path used.
+- Confirm the target output folder before rendering; create it only when the task requires writing deliverables.
+
+### 2) Choose the task mode
+
+Pick one primary mode, and combine modes when the user asks for a package:
+
+- `source-summary`: read lecture slides, past papers, or error books and extract study notes.
+- `mock-exam`: create a new exam paper modeled on source material or user weaknesses.
+- `solution-book`: produce worked solutions for an exam paper.
+- `grading`: mark a completed answer book and write scores back into a graded PDF.
+- `typesetting-refresh`: improve layout, rebuild formulas with KaTeX, or clean up an existing PDF package.
+
+### 3) Read source materials first
+
+- Use `pdf` to extract the source exam, lecture slides, marking scheme, error book, or answer book.
+- When the source is handwritten, scanned, or visually complex, use `document-vision-reader` so judgments come from the rendered page rather than noisy OCR alone.
+- Base the output on the actual source artifacts; do not invent syllabus scope, notation, or marking rules when the source does not support them.
+
+### 4) Produce the complete deliverable set for the chosen mode
+
+#### `mock-exam`
+
+- Build the paper around the user's weak topics or the patterns visible in the source materials.
+- Match the source paper's structure, tone, and sectioning closely enough to feel familiar without copying it verbatim.
+- Unless the user explicitly says otherwise, also produce a matching `solution-book` as part of the same task.
+
+#### `solution-book`
+
+- Give full working, not answer-only stubs.
+- Keep notation and variable names aligned with the paired exam paper.
+- Use concise marking-friendly steps so the solution can also act as the grading reference.
+
+#### `grading`
+
+- Establish or derive the answer key before assigning scores.
+- Judge each question from the rendered student pages, not from OCR fragments alone when handwriting matters.
+- Write per-question scores and the total score into a new graded PDF rather than only reporting marks in chat.
+- If any page is unreadable or ambiguous, say so explicitly and grade conservatively with a short note.
+
+#### `typesetting-refresh`
+
+- Improve spacing, pagination, headings, and section breaks so the PDF reads like a clean exam handout.
+- Rebuild all mathematical expressions through `katex` when formulas appear.
+- Do not leave raw TeX, ASCII approximations, or partially rendered formulas in the final PDF.
+
+### 5) Render math correctly
+
+- When the output includes formulas, invoke `katex` and render the expressions before PDF export.
+- Use display math for multi-step derivations and dense formulas; use inline math only for short expressions.
+- After rendering, visually verify representative pages so symbols, superscripts, fractions, and brackets display correctly.
+
+### 6) Run PDF visual QA before finishing
+
+- Open the rendered PDFs and inspect representative pages.
+- Always check:
+  - the first page
+  - one page with dense mathematics
+  - one page with longer prose or worked solutions
+  - any page with grading annotations when in `grading` mode
+- Confirm that layout is readable, formulas are fully rendered, page breaks are sensible, and annotations are visible.
+- Revise and re-render if math, spacing, or score overlays are unclear.
+
+## Default completion rules
+
+- If the user asks for a mock exam, default to delivering both the exam PDF and its solution PDF.
+- If the user asks to improve exam formatting and the paper contains formulas, default to KaTeX-rendered math.
+- If the user asks for grading, default to a new graded PDF with visible marks plus a chat summary of per-question scores.
+- If the task is read-only, do not modify files; provide notes only.
+
+## Output rules
+
+- Keep filenames explicit and stable, for example `... Mock Test.pdf`, `... Solution.pdf`, or `..._graded.pdf`.
+- Store outputs in the user-requested folder when one is given; otherwise reuse the source document's nearby study-material folder.
+- Report the exact final PDF paths and any unresolved ambiguity, such as unreadable handwriting or missing marking guidance.

package/exam-pdf-workflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Exam PDF Workflow"
+  short_description: "Create, typeset, and grade exam PDFs with math rendering."
+  default_prompt: "Use $exam-pdf-workflow to read exam PDFs, generate mock exams and worked solutions, render math with KaTeX, or grade completed answer-book PDFs into a graded PDF."

package/generate-spec/SKILL.md

@@ -30,6 +30,9 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Confirm the target workspace root, feature name, and a kebab-case `change_name`.
 - Review only the code, configuration, and external docs needed to understand the requested behavior.
 - Record the references that should appear in `spec.md`.
+- Inspect existing `docs/plans/` directories before deciding whether to edit an existing plan set.
+- Reuse an existing plan set only when it clearly matches the same requested issue/change scope.
+- If the requested work is adjacent to, but not actually covered by, an existing plan set, create a new directory instead of overwriting the neighboring one.
 
 ### 2) Generate the planning files
 
@@ -73,6 +76,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Review whether `spec.md`, `tasks.md`, and `checklist.md` must be updated.
 - After any clarification-driven update, obtain explicit approval on the updated spec set again.
 - Do not modify implementation code before approval.
+- When clarification reveals the work is a different issue or materially different scope than the current plan set, stop editing that plan set and generate a new one with a distinct `change_name`.
 
 ### 7) Backfill after implementation and testing
 
@@ -87,6 +91,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Prefer realistic coverage over boilerplate: add or remove checklist items based on actual risk.
 - Use kebab-case for `change_name`; avoid spaces and special characters.
 - Path rule: `scripts/...` and `references/...` in this file always mean paths under the current skill folder, not the target project root.
+- Never overwrite a nearby issue's plan set just because the technical area overlaps; shared modules are not sufficient evidence that the scope is the same.
 
 ## References
 

package/katex/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: katex
+description: Render and embed math formulas with KaTeX using official documentation-backed patterns. Use when an agent needs inline or display math in HTML, Markdown, MDX, or other text-based outputs, or when it should generate insertion-ready KaTeX snippets from TeX.
+---
+
+# KaTeX
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: If `node`, `npx`, or network package download is unavailable, keep the source TeX unchanged and explain that KaTeX rendering could not be generated locally.
+
+## Standards
+
+- Evidence: Follow the official KaTeX docs in `references/official-docs.md` before choosing render mode, options, or insertion strategy.
+- Execution: Decide between pre-rendering and client-side auto-render first, then use `scripts/render_katex.py` for deterministic output whenever a static rendered snippet is enough.
+- Quality: Default to `htmlAndMathml`, keep `trust` disabled unless the content source is explicitly trusted, and include the KaTeX stylesheet whenever the output will be displayed in HTML.
+- Output: Return insertion-ready content plus the exact CSS or runtime requirements still needed by the target file.
+
+## Goal
+
+Use KaTeX safely and consistently so mathematical formulas can be inserted into documents without the agent re-deriving the rendering workflow each time.
+
+## Workflow
+
+### 1) Confirm the target surface
+
+- Identify the destination file type before rendering: static HTML, Markdown/MDX, generated docs, or an existing HTML page that already contains TeX delimiters.
+- Decide whether the destination can keep raw HTML. If it cannot, keep the TeX source and document the runtime rendering requirement instead of forcing a broken snippet.
+
+### 2) Pick the right rendering strategy
+
+- Use **pre-rendering** when the agent needs a stable snippet to paste into HTML, Markdown, MDX, templates, or generated artifacts.
+- Use **auto-render** only when the document should keep TeX delimiters in source and render in the browser at runtime.
+- Prefer pre-rendering for one-off formulas and exported documents. Prefer auto-render when the file intentionally stores author-friendly TeX like `$...$` and `$$...$$`.
+
+### 3) Render static output with the bundled script
+
+Run the bundled renderer for pre-rendered output:
+
+```bash
+python3 katex/scripts/render_katex.py \
+  --tex '\int_0^1 x^2 \\, dx = \\frac{1}{3}' \
+  --display-mode \
+  --output-format html-fragment
+```
+
+Useful output modes:
+
+- `html-fragment`: paste into HTML, MDX, JSX, or Markdown engines that allow raw HTML.
+- `html-page`: generate a standalone previewable HTML file with the KaTeX stylesheet link included.
+- `markdown-inline`: emit an inline-friendly HTML fragment for Markdown/MDX.
+- `markdown-block`: emit a block-friendly HTML fragment for Markdown/MDX.
+- `json`: emit machine-friendly JSON for downstream automation or templating.
+
+Useful options:
+
+- `--display-mode` for centered display math; omit for inline math.
+- `--katex-format htmlAndMathml` by default for accessibility; switch only when the destination needs HTML-only or MathML-only output.
+- `--macro` / `--macro-file` for reusable custom macros.
+- `--strict`, `--trust`, `--max-size`, `--max-expand`, `--error-color`, and `--no-throw-on-error` when the task needs explicit control from the official options reference.
+
+### 4) Insert output according to file type
+
+- **HTML / template files**: paste `html-fragment` output and ensure the page loads the KaTeX stylesheet.
+- **Standalone HTML exports**: use `html-page` when the user wants a ready-to-open preview file.
+- **Markdown / MDX**: use `markdown-inline` or `markdown-block` only if the target renderer preserves raw HTML; otherwise keep source TeX and document the runtime render requirement.
+- **Existing browser pages with raw delimiters**: keep the original TeX and wire in the official auto-render assets instead of pasting a pre-rendered snippet.
+
+See `references/insertion-patterns.md` for concrete insertion guidance.
+
+### 5) Apply the official runtime requirements
+
+- KaTeX-rendered HTML needs the KaTeX CSS to display correctly.
+- Official docs recommend using the HTML5 doctype so browser quirks mode does not distort layout.
+- For browser auto-render, load `katex.min.js`, `auto-render.min.js`, the stylesheet, then call `renderMathInElement(...)` after the DOM is ready.
+
+### 6) Keep safety and maintainability defaults
+
+- Keep `trust` off unless the input source is trusted and the task explicitly needs trusted commands.
+- On untrusted content, keep size and expansion limits bounded instead of relaxing them blindly.
+- Reuse one macro definition source across the whole document when many formulas share the same commands.
+- When the rendered output is only for preview and the final destination has its own KaTeX pipeline, prefer editing the TeX source instead of freezing rendered HTML too early.
+
+## References
+
+- `references/official-docs.md`: condensed notes from the official KaTeX docs and direct source links.
+- `references/insertion-patterns.md`: insertion patterns for HTML, Markdown/MDX, and auto-rendered pages.
+- `scripts/render_katex.py`: deterministic wrapper around the official KaTeX CLI for insertion-ready output.
+- `scripts/render_katex.sh`: shell wrapper for environments that prefer an executable script entrypoint.

package/katex/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "KaTeX"
+  short_description: "Render and embed math formulas with KaTeX using insertion-ready snippets."
+  default_prompt: "Use $katex to turn TeX math into insertion-ready KaTeX output, choose between pre-rendering and auto-render based on the target file, and use the bundled renderer script when a static snippet or preview file is needed."

package/katex/references/insertion-patterns.md

@@ -0,0 +1,54 @@
+# KaTeX Insertion Patterns
+
+## HTML or template files
+
+- Use:
+
+```bash
+python3 katex/scripts/render_katex.py \
+  --tex 'E = mc^2' \
+  --output-format html-fragment
+```
+
+- Paste the output where the formula should appear.
+- Ensure the destination page loads a KaTeX stylesheet such as the official CDN link.
+
+## Standalone preview page
+
+- Use:
+
+```bash
+python3 katex/scripts/render_katex.py \
+  --tex '\\sum_{i=1}^{n} i = \\frac{n(n+1)}{2}' \
+  --display-mode \
+  --output-format html-page \
+  --output-file /absolute/path/preview.html
+```
+
+- Open the generated file in a browser to visually confirm spacing and line breaking.
+
+## Markdown or MDX that preserves raw HTML
+
+- Use `markdown-inline` for inline formulas and `markdown-block` for display formulas.
+- The result is still HTML. It works only when the downstream renderer keeps raw HTML intact.
+- If the renderer sanitizes or escapes HTML, keep the source TeX instead of pasting the rendered fragment.
+
+## Existing HTML page that stores raw TeX delimiters
+
+- Keep the source TeX in the document.
+- Load the official assets:
+  - `katex.min.css`
+  - `katex.min.js`
+  - `contrib/auto-render.min.js`
+- Call `renderMathInElement(container, options)` after the DOM is ready.
+- Restrict the container instead of rendering the whole page when only one section contains math.
+
+## Shared macros across a document
+
+- Put macros in a JSON file and pass `--macro-file`.
+- Reuse the same macro definitions for every formula generated into the same document.
+
+## Error-handling defaults
+
+- Keep `throwOnError` enabled unless the task explicitly prefers graceful fallback rendering.
+- When previewing user-supplied formulas that may be invalid, use `--no-throw-on-error` and keep the original TeX nearby for debugging.

package/katex/references/official-docs.md

@@ -0,0 +1,35 @@
+# Official KaTeX Docs Notes
+
+These notes condense the official KaTeX documentation that was checked on 2026-03-21. Re-open the linked pages when exact behavior matters.
+
+## Core pages
+
+- [API](https://katex.org/docs/api.html)
+  - Browser rendering uses `katex.render`.
+  - String generation uses `katex.renderToString`.
+  - The docs recommend reusing the same `macros` object when multiple formulas should share macro definitions.
+- [Options](https://katex.org/docs/options.html)
+  - `displayMode`, `output`, `throwOnError`, `errorColor`, `macros`, `minRuleThickness`, `colorIsTextColor`, `strict`, `trust`, `maxSize`, and `maxExpand` are the main rendering controls.
+  - `htmlAndMathml` is the default output mode and is the accessibility-friendly default.
+- [Node.js](https://katex.org/docs/node)
+  - Include the KaTeX stylesheet when rendering HTML generated by `renderToString`.
+  - Use the HTML5 doctype to avoid browser quirks mode.
+  - Browser-side `katex.render` and server-side `renderToString` can share the same options.
+- [CLI](https://katex.org/docs/cli)
+  - The official CLI accepts TeX from stdin or `--input`.
+  - Useful flags include `--display-mode`, `--format`, `--macro`, `--macro-file`, `--error-color`, `--no-throw-on-error`, `--leqno`, `--fleqn`, `--min-rule-thickness`, `--color-is-text-color`, `--strict`, `--trust`, `--max-size`, and `--max-expand`.
+- [Auto-render extension](https://katex.org/docs/autorender.html)
+  - Load `auto-render.min.js` after `katex.min.js`.
+  - Call `renderMathInElement(document.body)` or scope it to a narrower container.
+  - The docs show default delimiters for block math and right-associative delimiter ordering.
+  - Ignored tags include `script`, `noscript`, `style`, `textarea`, `pre`, `code`, and `option`.
+- [Supported Functions](https://katex.org/docs/supported)
+  - Use this page to confirm whether a command is supported before promising a render.
+
+## Practical guidance extracted from the official docs
+
+1. Prefer pre-rendered output when the agent is generating a static artifact.
+2. Prefer auto-render only when the source document should remain human-editable TeX with delimiters.
+3. Keep `trust` disabled by default.
+4. Include the stylesheet for every HTML destination.
+5. Keep one shared macro map across formulas when macro definitions are expected to persist.

package/katex/scripts/render_katex.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""Render TeX formulas with the official KaTeX CLI and wrap the output for reuse."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import subprocess
+import sys
+import tempfile
+from typing import Iterable
+
+
+DEFAULT_CSS_HREF = "https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css"
+
+
+class KatexRenderError(Exception):
+    """User-facing error for rendering failures."""
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="render_katex.py",
+        description="Render TeX with KaTeX and emit insertion-ready output.",
+    )
+
+    input_group = parser.add_mutually_exclusive_group(required=True)
+    input_group.add_argument("--tex", help="Raw TeX expression without delimiters.")
+    input_group.add_argument("--input-file", help="Path to a UTF-8 text file containing raw TeX.")
+
+    parser.add_argument(
+        "--output-format",
+        choices=("html-fragment", "html-page", "markdown-inline", "markdown-block", "json"),
+        default="html-fragment",
+        help="How to wrap the rendered KaTeX output.",
+    )
+    parser.add_argument(
+        "--katex-format",
+        choices=("html", "mathml", "htmlAndMathml"),
+        default="htmlAndMathml",
+        help="KaTeX internal output format.",
+    )
+    parser.add_argument("--display-mode", action="store_true", help="Render in display mode.")
+    parser.add_argument("--output-file", help="Write the wrapped output to a file.")
+    parser.add_argument("--css-href", default=DEFAULT_CSS_HREF, help="Stylesheet href for html-page/json output.")
+    parser.add_argument("--title", default="KaTeX Render", help="Document title for html-page output.")
+    parser.add_argument("--lang", default="en", help="HTML lang attribute for html-page output.")
+
+    parser.add_argument("--macro", action="append", default=[], help="Macro definition in NAME:VALUE form.")
+    parser.add_argument("--macro-file", help="Path to a JSON file mapping macro names to expansion strings.")
+    parser.add_argument("--error-color", help="Hex color or CSS color name for parse errors.")
+    parser.add_argument("--strict", help="KaTeX strict mode setting.")
+    parser.add_argument("--trust", help="KaTeX trust mode setting.")
+    parser.add_argument("--max-size", type=float, help="Maximum user-specified size in em.")
+    parser.add_argument("--max-expand", type=int, help="Maximum macro expansion count.")
+    parser.add_argument("--min-rule-thickness", type=float, help="Minimum rule thickness in em.")
+    parser.add_argument("--leqno", action="store_true", help="Render display equations with left equation numbers.")
+    parser.add_argument("--fleqn", action="store_true", help="Render display equations flush left.")
+    parser.add_argument(
+        "--color-is-text-color",
+        action="store_true",
+        help="Interpret \\\\color like legacy text color behavior.",
+    )
+    parser.add_argument(
+        "--no-throw-on-error",
+        action="store_true",
+        help="Render invalid input with colored source text instead of failing.",
+    )
+
+    return parser.parse_args(argv)
+
+
+def normalize_path(raw_path: str) -> pathlib.Path:
+    path = pathlib.Path(raw_path).expanduser()
+    if not path.is_absolute():
+        path = pathlib.Path.cwd() / path
+    return path.resolve()
+
+
+def load_tex(args: argparse.Namespace) -> str:
+    if args.input_file:
+        path = normalize_path(args.input_file)
+        if not path.is_file():
+            raise KatexRenderError(f"Input file not found: {path}")
+        return path.read_text(encoding="utf-8").strip()
+    return (args.tex or "").strip()
+
+
+def load_macro_pairs(values: Iterable[str]) -> list[tuple[str, str]]:
+    pairs: list[tuple[str, str]] = []
+    for raw_value in values:
+        if ":" not in raw_value:
+            raise KatexRenderError(f"Invalid --macro value '{raw_value}'. Use NAME:VALUE.")
+        name, expansion = raw_value.split(":", 1)
+        name = name.strip()
+        expansion = expansion.strip()
+        if not name or not expansion:
+            raise KatexRenderError(f"Invalid --macro value '{raw_value}'. Use NAME:VALUE.")
+        pairs.append((name, expansion))
+    return pairs
+
+
+def run_katex_cli(tex: str, args: argparse.Namespace) -> str:
+    command = [
+        "npx",
+        "--yes",
+        "--package",
+        "katex",
+        "katex",
+        "--format",
+        args.katex_format,
+    ]
+
+    if args.display_mode:
+        command.append("--display-mode")
+    if args.leqno:
+        command.append("--leqno")
+    if args.fleqn:
+        command.append("--fleqn")
+    if args.color_is_text_color:
+        command.append("--color-is-text-color")
+    if args.no_throw_on_error:
+        command.append("--no-throw-on-error")
+
+    if args.error_color:
+        command.extend(["--error-color", args.error_color])
+    if args.strict:
+        command.extend(["--strict", args.strict])
+    if args.trust:
+        command.extend(["--trust", args.trust])
+    if args.max_size is not None:
+        command.extend(["--max-size", str(args.max_size)])
+    if args.max_expand is not None:
+        command.extend(["--max-expand", str(args.max_expand)])
+    if args.min_rule_thickness is not None:
+        command.extend(["--min-rule-thickness", str(args.min_rule_thickness)])
+
+    for name, expansion in load_macro_pairs(args.macro):
+        command.extend(["--macro", f"{name}:{expansion}"])
+
+    if args.macro_file:
+        macro_file = normalize_path(args.macro_file)
+        if not macro_file.is_file():
+            raise KatexRenderError(f"Macro file not found: {macro_file}")
+        command.extend(["--macro-file", str(macro_file)])
+
+    with tempfile.NamedTemporaryFile("w", suffix=".tex", encoding="utf-8", delete=False) as handle:
+        handle.write(tex)
+        handle.write("\n")
+        temp_path = pathlib.Path(handle.name)
+
+    try:
+        command.extend(["--input", str(temp_path)])
+        result = subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+        )
+    finally:
+        temp_path.unlink(missing_ok=True)
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or "KaTeX CLI failed."
+        raise KatexRenderError(stderr)
+
+    return result.stdout.strip()
+
+
+def build_html_page(rendered_html: str, args: argparse.Namespace) -> str:
+    css_link = ""
+    if args.css_href.strip():
+        css_link = f'  <link rel="stylesheet" href="{args.css_href.strip()}">\n'
+
+    return (
+        "<!DOCTYPE html>\n"
+        f'<html lang="{args.lang}">\n'
+        "<head>\n"
+        '  <meta charset="utf-8">\n'
+        f"  <title>{args.title}</title>\n"
+        f"{css_link}"
+        "</head>\n"
+        "<body>\n"
+        f"{rendered_html}\n"
+        "</body>\n"
+        "</html>\n"
+    )
+
+
+def wrap_output(rendered_html: str, tex: str, args: argparse.Namespace) -> str:
+    if args.output_format == "html-fragment":
+        return f"{rendered_html}\n"
+    if args.output_format == "html-page":
+        return build_html_page(rendered_html, args)
+    if args.output_format == "markdown-inline":
+        return f"{rendered_html}\n"
+    if args.output_format == "markdown-block":
+        return f"\n{rendered_html}\n"
+    if args.output_format == "json":
+        payload = {
+            "tex": tex,
+            "displayMode": args.display_mode,
+            "katexFormat": args.katex_format,
+            "cssHref": args.css_href,
+            "content": rendered_html,
+        }
+        return json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
+    raise KatexRenderError(f"Unsupported output format: {args.output_format}")
+
+
+def write_output(content: str, output_file: str | None) -> None:
+    if not output_file:
+        sys.stdout.write(content)
+        return
+
+    path = normalize_path(output_file)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    sys.stdout.write(str(path) + "\n")
+
+
+def main(argv: list[str]) -> int:
+    try:
+        args = parse_args(argv)
+        tex = load_tex(args)
+        if not tex:
+            raise KatexRenderError("Input TeX is empty.")
+        rendered_html = run_katex_cli(tex, args)
+        wrapped = wrap_output(rendered_html, tex, args)
+        write_output(wrapped, args.output_file)
+        return 0
+    except KatexRenderError as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        return 1
+    except FileNotFoundError as exc:
+        missing = exc.filename or "required executable"
+        if os.path.basename(missing) in {"npx", "node"}:
+            print("[ERROR] node and npx are required to render KaTeX.", file=sys.stderr)
+            return 1
+        raise
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/katex/scripts/render_katex.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "[ERROR] python3 is required." >&2
+  exit 1
+fi
+
+exec python3 "$script_dir/render_katex.py" "$@"