Ape Present

Present Skill

Takes a blog post and produces one self-contained HTML file designed for intuitive learning: a clean header, short crisp bullet points, and visual-first explanations. Diagrams take center stage, featuring custom animations that visually demonstrate the underlying mechanics, followed by numbers set large and wire layouts or pseudocode where relevant.

It is a document, not a deck. No full-screen hero sections, no scroll-snapping, and no slide feel. Single file, comfortable reading width (--measure), full theme support, and a fixed section skeleton -- illustration, context, body, sources -- so every document has a coherent shape.

It is not the blog either. The post merely recorded or explained; this document teaches. Write it as an expert engineer explaining the concept to a sharp peer:

• Visuals carry the heavy lifting: Every idea is anchored by a diagram, custom animation, code snippet, or layout.
• Short, crisp bullet points: No verbose paragraphs or walls of text. Use punchy, high-signal bullets that explain the invariant, the causal steps, and the trade-off.
• Custom animations: You are free and encouraged to design custom SVG/CSS animations tailored directly to what the concept needs to make the mechanism click.
• Natural, causal flow: Ideas progress logically, where each section resolves a constraint or trade-off raised by the previous one.

Audience: practicing engineers. Ground explanations in first principles and systems realities (disk seeks, memory hierarchies, network hops).

Design System & Custom Animations

The reference/ directory next to this file holds the design system: base.css, runtime.js, skeleton.html, svg-templates.md, and verify.sh.

• Visual-first presentation: Every idea gets at least one visual figure. Multiple visuals per idea (e.g. animated flow + pseudocode, diagram + trade-off matrix) are welcomed whenever helpful.
• Custom animated diagrams encouraged: While svg-templates.md provides a fast catalogue of standard shapes, do not feel constrained by it. When a concept calls for a specialized layout, data movement, or custom state cycle, design a custom animated SVG.
• Cohesive tokens: Build custom visuals using only the CSS variables defined in base.css (var(--surface), var(--line), var(--accent), var(--accent-soft), var(--muted), var(--err), var(--ok)). Never invent arbitrary hex colors outside :root.
• Motion with purpose: Motion exists to make mechanisms intuitive. Animate data packets moving along paths (animateMotion), pulsing nodes (class="pulse"), flowing channels (class="stream-channel"), or cycling active states (data-cycle). Keep motion purposeful and loops reasonable (1.5s - 3s). Static evidence charts (bars, tables, quotes) stay still.

Input Handling

The user may provide input in any of these forms:

1. File path on disk: a path ending in .md, .txt, .html, or similar. Read the file directly.
2. A URL: fetch using web tools, then strip navigation and sidebars before working on the body.
3. Pasted content: raw text in the message.
4. Ambiguous: if unclear, ask once. Do not guess.

Optional modifiers:

• Audience: e.g., "for execs", "for new grads". Default: software engineers with 5-8 years of experience.
• Length: "short" (4-6 key ideas) or "full" (all core ideas). Default: full.
• Theme: "midnight", "tokyo", "nord", "dracula", "gruvbox", "rosepine", "forest", "neon", "daylight", "arctic", "solarized", "paper", "rosequartz", "swiss" (applied via <html lang="en" data-theme="theme">). Default: OS-following.
• Layout: data-layout="left" for left-aligned body with rightward breakouts. Default: centered.

Step 1: Find the Spine & Natural Flow

Read the source material once. Extract:

1. The one-line claim: The central thesis in one punchy sentence (the dek).
2. The lead visual illustration concept: A simple, iconic visual motif representing the topic (e.g. an append stream entering an active block, a single heartbeat pulse, an index pointer). Keep it simple and focused — never try to map the entire blog post or full architecture into this one visual.
3. The ideas in natural explanatory flow: 4 to 10 progressive milestones. Each milestone represents one logical step in understanding:
   • What fundamental constraint makes this hard?
   • The central intuition / naive attempt breakdown.
   • The core mechanism (how the gears turn).
   • How edge cases, concurrency, or scale are solved.
   • The primary trade-off or production reality. Every idea heading is a clear, read-aloud sentence capturing the insight.
4. The visual & animation concept for each idea: A template from svg-templates.md or a custom animated design that illuminates the specific mechanics.
5. Key numbers & invariants: Exact stats, orders of magnitude, and core formulas.
6. Concrete code / layout: Trimmed code (<= 20 lines) or clean pseudocode; record/wire format diagrams.

Print the spine:

• Lead Illustration: <super-visual description capturing the talk>
• NN. <idea as sentence> -> <visual / custom animation description>.

Step 2: Document Structure & Writing Style

Follow skeleton.html:

htmlCopy code
<article class="doc">
  <header class="doc-header">
    <h1>{{TITLE}}</h1>
    <p class="dek">{{ONE-LINE CLAIM}}</p>
  </header>

  <section id="illustration">
    <figure class="wide lead-art">
      <!-- High-impact visual illustration that conceptually represents the talk/article.
           Not a text summary, but an evocative, animated visual scene capturing the topic. -->
      {{LEAD SVG ILLUSTRATION}}
      <figcaption><strong>{{Illustration Title, 3-6 words.}}</strong> {{One crisp sentence capturing what the visual represents about the talk.}}</figcaption>
    </figure>
  </section>

  <section id="context">
    <h2>{{CONTEXT HEADING as a sentence}}</h2>
    <div class="context-body">
      <!-- 2-4 crisp bullets grounding the problem in first principles -->
      <ul class="rules">
        <li><strong>The Fundamental Invariant</strong>: ...</li>
        <li><strong>Why Naive Approaches Fail</strong>: ...</li>
      </ul>
    </div>
  </section>

  <section id="body">
    <!-- One section per idea, numbered data-n="01", data-n="02", etc. -->
    <h2 data-n="01">{{IDEA AS A READ-ALOUD SENTENCE}}</h2>
    
    <!-- Short, crisp bullet points explaining the concept -->
    <ul class="rules">
      <li><strong>Core Intuition</strong>: [The immediate mental model or physics constraint]</li>
      <li><strong>Mechanism</strong>: [Causal step-by-step: what happens, in what order]</li>
      <li><strong>Trade-off / Invariant</strong>: [What is gained vs. what is sacrificed]</li>
    </ul>

    <!-- Visual: Animated SVG (custom or template), Code, Layout, or Matrix -->
    <figure class="wide">
      {{ANIMATED SVG OR VISUAL}}
      <figcaption><strong>{{Label, 3-6 words.}}</strong> {{One sentence explaining what the visual demonstrates.}}</figcaption>
    </figure>

    <!-- Optional: Second visual element if helpful (pseudocode, stat row, trade-off matrix, wire format) -->
    <!-- Optional: Caveat aside if the source had one -->
    <div class="aside"><p>{{The caveat or boundary condition}}</p></div>
  </section>

  <section id="sources">
    <h2>Sources & References</h2>
    <ul>
      <li cite="...">...</li>
    </ul>
  </section>
</article>

Writing Rules: Short, Crisp, Intuitive

• No walls of prose: Never write dense multi-paragraph text. Explain ideas through tight, bulleted points (.rules or .steps).
• Focus heavily on explanation: Frame every concept from first principles. What invariant makes this hard? What naive assumption broke? How does this design restore the guarantee?
• Natural progression: Section N+1 should naturally answer the challenge or trade-off left open by Section N.
• Cross-link text to visuals: Use <span class="inspect-node" tabindex="0" data-target="node-id"> to connect bullet points directly to highlighted diagram elements.
• Truthful to the source: Use the post's exact numbers, benchmarks, and claims. Never fabricate facts or benchmarks.

Step 3: Crafting Visuals & Custom Animations

• Crafting the Lead Visual Illustration (Simplicity First):
  • The talk opens with a simple, iconic visual anchor, never a text summary or TL;DR box.
  • Do NOT map the whole blog post into one complex diagram: Do not attempt to fit multiple systems, stages, or edge cases into this illustration. Body sections will explain mechanisms one step at a time.
  • Aim for simplicity & elegance: 2 to 3 clean elements max. A focused visual motif that sets the mood/theme of the talk (e.g., an append stream entering an active block, a clean pulse between two nodes, or a pointer to an index cell).
  • Subtle, purposeful motion: A single moving packet or gentle pulse. Keep it calm, clean, and fast to parse visually.
• Use the templates or invent custom designs: Standard templates in reference/svg-templates.md work well for basic pipelines, tables, and trees. When the idea has a distinct spatial or mechanical dynamic, write a custom animated SVG.
• Animation primitives:
  • animateMotion: Move packets, offsets, or requests along SVG paths (<mpath href="#path-id"/>).
  • class="pulse" or class="pulse-glow": Highlight active buffers, locks, or workers.
  • data-cycle="ms": Step sequentially through state machines, ring tokens, or phased protocols.
  • class="flowing": Show continuous streams or data pipes.
• Keep diagrams clean and legible:
  • 8px grid alignment, viewBox="0 0 960 H" (or 640 for narrow).
  • Clear typography: labels inside elements at font-size 16-18, annotations at 14.
  • Accessible: every <svg> must have role="img" and a descriptive aria-label.
  • Captioned: every visual sits in a <figure> with a <figcaption>.

Step 4: Assemble and Verify

1. Write content file: Start with skeleton.html, write headers, bullets, and figures. Leave {{BASE_CSS}} and {{RUNTIME_JS}} in place. Remove skeleton data-example blocks.
2. Inject CSS & JS mechanically:

   bashCopy code
   python3 - <<'EOF'
   from pathlib import Path
   ref = Path("REF") # path to reference/
   doc = Path("out.html")
   html = doc.read_text()
   html = html.replace("{{BASE_CSS}}", (ref/"base.css").read_text())
   html = html.replace("{{RUNTIME_JS}}", (ref/"runtime.js").read_text())
   doc.write_text(html)
   EOF
   

3. Verify with script:

   bashCopy code
   bash <skill-dir>/reference/verify.sh out.html source.md
   

   Fix any structural issues (missing sections, unclosed tags, leftover {{ markers, or ungrounded numbers).
4. Factual review: Confirm that all numbers, algorithmic steps, and trade-offs faithfully reflect the source material without hallucinations.

Checklist

• Visual-heavy presentation: at least one visual figure per idea; custom animated designs used where helpful to show mechanism.
• Simple, iconic lead visual illustration under the header (not an overloaded architectural diagram summarizing the whole blog post).
• Short, crisp bullets instead of dense prose paragraphs.
• Natural explanatory flow: ideas progress logically from problem to mechanism to edge cases and trade-offs.
• Visuals built cleanly using design system CSS variables (--surface, --line, --accent, etc.).
• Mechanism diagrams move purposefully; static evidence figures remain still.
• Every figure has a <figcaption> with a bold label and clear takeaway.
• Four required sections present (illustration, context, body, sources), exactly one h1.
• Design system (base.css and runtime.js) injected cleanly with zero leftover {{ markers.
• Numbers, benchmarks, and claims grounded in the source material.

Output Structure

1. Print one punchy flavour line starting with "Ape is": e.g., "Ape is turning this post into a visual-heavy walkthrough with custom animations."
2. Print the spine showing the natural flow of ideas and their visual/animated forms.
3. Build the self-contained HTML file and run verification.
4. Print a concise summary with:
   • Output file path
   • Key ideas and the animated/visual forms used
   • Confirmation of factual alignment and verification status