@laitszkin/apollo-toolkit 2.9.0 → 2.10.0

package/AGENTS.md

@@ -31,7 +31,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can run evidence-first application security audits focused on confirmed vulnerabilities.
 - Users can learn new or improved skills from recent Codex conversation history.
 - Users can audit and maintain the skill catalog itself, including dependency classification and shared-skill extraction decisions.
-- Users can summarize mistakes into a learning error book and render it to PDF.
+- Users can summarize mistakes into separate multiple-choice and long-answer error books backed by structured reference files and rendered PDFs.
 - Users can build or review marginfi protocol integrations using official SDK, CLI, protocol, and The Arena documentation.
 - Users can create or maintain `AGENTS.md` so project constraints stay aligned with the repository.
 - Users can turn novel content into a loopable short-form video with generated assets.
@@ -48,6 +48,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can build and maintain Solana programs and Rust clients using official Solana development workflows.
 - Users can add focused observability to opaque workflows through targeted logs, metrics, traces, and tests.
 - Users can build against Jupiter's official Solana swap, token, price, lending, trigger, recurring, and portfolio APIs with an evidence-based development guide.
+- Users can render and embed math formulas with KaTeX using official documentation-backed guidance and reusable rendering scripts.
 - Users can debug software systematically by reproducing causes, validating fixes, and testing outcomes.
 - Users can generate 30-60 second short videos directly from text prompts.
 - Users can prepare and publish versioned releases with changelog and tag workflows.

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.10.0] - 2026-03-21
+
+### Added
+- Add `document-vision-reader` for screenshot-based inspection of rendered documents when visible layout matters more than raw extracted text.
+- Add `katex` for rendering and embedding math formulas with official KaTeX guidance and reusable render scripts.
+
+### Changed
+- Rework `learning-error-book` to generate separate multiple-choice and long-answer reference JSON files plus polished PDFs rendered directly from structured data.
+- Update the repository skill inventory and project capability docs to include the new document-vision and KaTeX workflows.
+
+
 ## [v2.9.0] - 2026-03-21
 
 ### Changed

package/README.md

@@ -14,6 +14,7 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 - develop-new-features
 - discover-edge-cases
 - docs-to-voice
+- document-vision-reader
 - enhance-existing-features
 - feature-propose
 - financial-research
@@ -22,6 +23,7 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 - harden-app-security
 - improve-observability
 - jupiter-development
+- katex
 - learn-skill-from-conversations
 - learning-error-book
 - marginfi-development

package/document-vision-reader/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaiTszKin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/document-vision-reader/README.md

@@ -0,0 +1,66 @@
+# Document Vision Reader
+
+A visual-reading skill for non-plain-text files that should be checked from their rendered appearance instead of raw text extraction.
+
+## What this skill does
+
+- Creates a temporary screenshot workspace for the target file.
+- Converts or captures the requested pages/regions into temporary images.
+- Reads those images as the evidence source.
+- Answers user requests such as summaries, transcription, field lookup, table extraction, comparison, and translation from the visible content.
+- Cleans up temporary screenshots by default after the answer is prepared.
+
+## Best-fit use cases
+
+- scanned PDFs
+- rendered PDF files
+- rendered PPT/PPTX slides
+- receipts, invoices, and forms
+- slide decks with annotations or visual emphasis
+- documents where highlights, layout, handwriting, or stamps matter
+- spreadsheets where merged cells or formatting affect meaning
+- files whose text extraction is unreliable
+- not plain-text files whose meaning depends on visual rendering
+
+## Repository layout
+
+```text
+.
+├── SKILL.md
+├── README.md
+├── LICENSE
+├── agents/
+│   └── openai.yaml
+└── references/
+    ├── legibility-checklist.md
+    └── rendering-guide.md
+```
+
+## Usage
+
+```text
+Use $document-vision-reader to inspect this non-plain-text file by turning its rendered pages into temporary screenshots, reading the screenshots as images, and answering from the visible content only.
+```
+
+Example requests:
+
+```text
+Use $document-vision-reader to inspect pages 3-5 of this scanned PDF, extract the totals table, and flag any handwritten notes.
+```
+
+```text
+Use $document-vision-reader to capture the rendered slides of this PPTX as temporary screenshots, read them visually, and tell me whether the key metrics on slide 7 match slide 12.
+```
+
+## Output expectations
+
+A good result should include:
+
+1. the direct answer to the user's request
+2. which screenshots/pages were used
+3. any visibility limits or unreadable regions
+4. whether the temporary screenshot directory was removed or preserved
+
+## License
+
+MIT. See `LICENSE`.

package/document-vision-reader/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: document-vision-reader
+description: Convert rendered non-plain-text files into temporary screenshots, inspect those screenshots as images, and answer the user's request from the visible visual output. Use when an agent needs to inspect PDFs, PPT/PPTX decks, scanned documents, forms, spreadsheets, or other files whose rendered appearance matters more than raw text extraction.
+---
+
+# Document Vision Reader
+
+## Dependencies
+
+- Required: none.
+- Conditional: `screenshot` when the host needs OS-level captures; `pdf`, `doc`, `pptx`, or `spreadsheet` when the source file needs format-specific rendering before screenshot capture.
+- Optional: none.
+- Fallback: If the file cannot be rendered or captured safely, ask the user for the relevant screenshots/pages instead of guessing from inaccessible content.
+
+## Standards
+
+- Evidence: Base every conclusion on visible screenshot content only; call out blur, clipping, hidden areas, and unreadable regions explicitly.
+- Execution: Create a temporary screenshot workspace, capture only the pages/regions needed, inspect the images, answer the request, and remove temporary artifacts unless the user asked to keep them.
+- Quality: Prefer legible crops over full-page miniatures, keep screenshot naming deterministic, and verify that every requested page or region was actually reviewed.
+- Output: Return the user-facing answer plus the screenshot coverage used, any visibility limits, and whether temporary files were cleaned up.
+
+## Goal
+
+Use visual reading as the source of truth when the target file is not a plain-text artifact and the rendered appearance matters more than extractable text.
+
+Typical cases:
+
+- scanned PDFs or image-only files
+- PDF reports, statements, and forms
+- PPT/PPTX slides that must be checked as rendered pages
+- forms, receipts, invoices, and reports with layout cues
+- slides or documents where comments, highlights, colors, callouts, or alignment matter
+- spreadsheets where merged cells, visual grouping, or formatting affects interpretation
+- cases where raw text extraction is incomplete, broken, or misleading
+
+Do not use this skill for plain-text files when normal text reading is sufficient.
+
+## Workflow
+
+### 1) Confirm scope and output target
+
+Before capturing anything, determine:
+
+- which file or files must be inspected
+- what the user actually needs (summary, transcription, table extraction, comparison, QA, translation, field lookup, etc.)
+- which pages, slides, sheets, or regions matter most
+- whether the user needs the temporary screenshots returned or only used internally
+
+If the file is long, capture only the requested pages or the smallest range needed to answer correctly.
+
+### 2) Create a temporary screenshot workspace
+
+Create a dedicated temporary directory, for example:
+
+```bash
+TMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/document-vision-reader.XXXXXX")"
+```
+
+Inside that directory, keep deterministic names such as:
+
+- `page-001.png`
+- `page-002-top.png`
+- `slide-004-notes.png`
+- `sheet-budget-row-01.png`
+
+Do not write temporary screenshots into the user's project unless they explicitly ask for that.
+
+### 3) Render the document into screenshots
+
+Use the most reliable renderer available for the source format.
+
+- PDFs or scans: render requested pages to images first, then inspect those images.
+- DOCX/PPTX/XLSX and similar office files: open a rendered view and capture screenshots from the visual output rather than trusting raw XML/text extraction.
+- Existing images: copy or convert into a readable PNG/JPEG only when needed.
+- Large pages or dense tables: use multiple crops instead of shrinking the entire page until text becomes unreadable.
+
+Prefer format-specific helper skills when they improve rendering fidelity:
+
+- `pdf` for PDF page handling
+- `doc` for Word-like documents
+- `pptx` for slides
+- `spreadsheet` for sheets/tables
+- `screenshot` for OS-level capture when no direct renderer is available
+
+If rendering tooling is missing, stop and ask for the minimal set of screenshots or pages needed.
+
+### 4) Verify screenshot legibility before reading
+
+Check every capture before extracting facts.
+
+- Zoom or recapture if body text is not comfortably readable.
+- Split one dense page into multiple overlapping crops when needed.
+- Keep labels, units, headers, and nearby notes in frame so interpretation stays grounded.
+- If a section is truncated or hidden, do not infer the missing content.
+
+Use `references/legibility-checklist.md` when a page is crowded or the answer depends on small details.
+
+### 5) Read screenshots as images
+
+Read the screenshots with image-capable tools only after the captures are ready.
+
+- Inspect the actual rendered content, not an assumed underlying text layer.
+- Treat handwriting, highlights, annotations, stamps, signatures, and color coding as first-class evidence when visible.
+- For tables, verify row/column alignment from the image before extracting values.
+- For multi-page answers, track which screenshot supports each claim.
+
+When the answer depends on multiple screenshots, reconcile them explicitly instead of paraphrasing from memory.
+
+### 6) Answer the user's request
+
+In the response:
+
+- answer the requested task directly
+- note which screenshots/pages were used
+- call out any uncertain or unreadable sections
+- distinguish visible facts from interpretation
+
+If the user asked for extraction, structure the output so it can be checked against the screenshots.
+
+### 7) Clean up temporary files
+
+After the answer is prepared:
+
+- delete the temporary screenshot directory by default
+- keep it only when the user explicitly wants the screenshots, a reusable artifact, or a debugging trail
+- if cleanup fails, report the leftover path so it can be removed later
+
+## Decision Rules
+
+- Prefer screenshot reading whenever visual layout changes meaning.
+- Prefer this skill for rendered non-plain-text files such as PDF and PPT/PPTX.
+- Do not use this skill when a plain-text source can be read directly without losing meaning.
+- Prefer the smallest sufficient capture set; avoid screenshotting an entire long document when the user only asked about one section.
+- Prefer multiple readable crops over one unreadable full-page image.
+- Never invent text hidden outside the visible capture.
+- If screenshots and extracted text disagree, trust the visible screenshot and mention the mismatch.
+
+## Output Checklist
+
+Before finishing, confirm all of the following:
+
+- the requested pages/regions were actually captured
+- the screenshots were legible enough for the requested task
+- the final answer is grounded in visible content
+- uncertainty or occlusion is disclosed
+- temporary artifacts were deleted or intentionally preserved
+
+## Resources
+
+- `references/rendering-guide.md`: format-by-format screenshot staging guidance.
+- `references/legibility-checklist.md`: quick quality gate for readable visual extraction.

package/document-vision-reader/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Document Vision Reader"
+  short_description: "Read rendered PDF/PPT-like files through temporary screenshots"
+  default_prompt: "Use $document-vision-reader when I need to inspect a non-plain-text rendered file such as PDF or PPT/PPTX, create temporary screenshots for the relevant pages or regions, inspect those screenshots as images instead of trusting raw text extraction, answer from visible content only, and clean up the temporary screenshot workspace unless I ask to keep it."

package/document-vision-reader/references/legibility-checklist.md

@@ -0,0 +1,13 @@
+# Legibility Checklist
+
+Before answering from screenshots, confirm:
+
+- text is readable without guessing
+- important numbers and decimal places are visible
+- row and column boundaries are clear for tables
+- annotations, highlights, stamps, and signatures are not clipped
+- the capture includes enough surrounding context to interpret the target content
+- overlapping crops cover any area split across captures
+- page or slide identity is trackable from the filename or nearby context
+
+If any item fails, recapture before answering.

package/document-vision-reader/references/rendering-guide.md

@@ -0,0 +1,37 @@
+# Rendering Guide
+
+Use the smallest reliable rendering path that preserves what the user needs to inspect.
+
+## PDF or scanned document
+
+- Capture only the requested pages first.
+- If a full page becomes unreadable when scaled down, split it into overlapping crops.
+- Preserve headers, footers, totals, and marginal notes when they affect interpretation.
+
+## DOCX or rich-text document
+
+- Read from a rendered page view, not raw XML text.
+- Preserve comments, highlights, tracked-style decorations, and side notes when visible.
+- Capture section-by-section when the page is text dense.
+
+## PPTX or slide deck
+
+- Capture slide canvases at a readable scale.
+- Include presenter notes only if the user asks for them or they are needed to answer.
+- When diagrams are dense, take one full-slide capture plus zoomed crops for detailed regions.
+
+## Spreadsheet
+
+- Keep row labels, column headers, and units visible in the same capture.
+- Use overlapping viewport captures for wide tables.
+- If color coding or conditional formatting matters, mention it explicitly in the answer.
+
+## Existing image file
+
+- Reuse the original image when it is already readable.
+- Convert only when the target tool requires a different format.
+
+## General fallback
+
+- If no reliable renderer is available, ask the user for the specific screenshots needed.
+- Do not claim coverage for pages or regions that were never captured.

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.