# Concept Teacher

Generate a comprehensive first-principles overview of the requested topic and deliver it as a single HTML file. The content is what matters — the HTML is just the delivery format.

## Reference Files

Before generating anything, read both files in this directory:

| File | Purpose |
|------|---------|
| `EXAMPLE.html` | Complete finished example. Study for both **content quality** (tone, depth, structure, diagrams) and **HTML code** (exact tags, classes, wrappers, Mermaid syntax). Match both. |
| `TEMPLATE.html` | Blank skeleton with all placeholders. Copy it with a topic-relevant name and fill in your content. |

Copy the template before editing:

```bash
cp TEMPLATE.html your-topic-name.html
```

Use a short, lowercase, hyphenated name (e.g. `ai-prompting.html`, `color-theory.html`, `distributed-systems.html`).

## Content: What to Write

Structure the response as a progressive thinking process — not a catalog of facts, but a sequence of mental steps that build on each other, where each step naturally raises the question that the next step answers.

### Structure
- Open by reframing the surface-level question into its more fundamental form — identify what the reader actually needs to understand before they can answer the original question effectively.
- Organize the body as numbered Steps (Paso 0, 1, 2...), where each step represents a stage in the reasoning process. Each step must end with a bridge — either a "Para reflexionar" question or a natural transition that motivates the next step.
- Include diagrams as primary explanatory tools. Every core concept must have at least one visual representation. These are Mermaid flowcharts — see the Diagrams section below for exact rules.
- Include CHECKPOINT blocks after each major step. Checkpoints are concise, actionable self-checks — not summaries. They tell the reader what to verify before moving forward.
- Include comparison tables where two or more options, approaches, or properties need to be contrasted.
- Close with a "principio unificador" section with a diagram that distills the entire overview into one causal chain.
- End with a "Seguir explorando" section containing exactly 10 follow-up questions. Each question must: target a deeper layer than the overview covered, contain an implicit tension or trade-off, and be formulated as a genuine research question — never "tell me more about X".

### Tone and language
- Direct, precise, and warm. The voice is that of an expert who respects the reader's intelligence.
- Use technical terminology appropriate to the domain. Simplify structure, not vocabulary.
- Never use casual analogies or metaphors to unrelated domains (no "it's like cooking", "think of it as a car", etc.). Explain concepts in their own terms.
- Never use aggressive or confrontational phrasing ("You need to stop doing X", "Most people get this wrong"). Frame constructively ("A more effective approach is...", "What tends to produce better results is...").
- "Para reflexionar" questions must invite the reader to connect the concept to their own context — never to simply recall what was said.
- LANGUAGE: Always write in the same language the user uses for their query. If Spanish, everything in Spanish. If English, everything in English.

### Content depth
- Derive concepts from first principles. Start from the fundamental properties or constraints of the domain and build upward. Techniques, tools, and recommendations must be presented as logical consequences of those fundamentals — not as standalone tips.
- When presenting multiple options or approaches, include a decision flow (as a diagram) that derives the correct choice from observable conditions — not from preference.
- When presenting techniques or tools, always pair them with the specific problem they solve. Never list techniques in isolation.
- Include concrete examples that show the before/after or the application of a concept. Examples must be specific and domain-relevant, not abstract.
- No padding. Every sentence introduces a concept, provides evidence, shows an example, or bridges to the next idea. Remove any sentence that exists only for transition or emphasis without adding information.

### Diagrams

Diagrams are the primary visual tool. They are Mermaid.js flowcharts that auto-switch between light and dark mode. Design them for the topic at hand — the diagrams in `EXAMPLE.html` are specific to that example topic. Your diagrams must be original and relevant to YOUR topic.

**Node shapes:** Use ONLY rectangles (square brackets `["..."]`) for all nodes. No circles, no diamonds, no other shapes.

```
A["Label text"]
A["Line 1 <br/>Line 2"]
```

**Style palette** — every node MUST have an explicit `style` line using ONLY these colors. Dark mode is handled automatically — never write dark-mode colors.

| Role | Style |
|------|-------|
| **Standard** | `fill:#f0f0f0,stroke:#888,color:#333,stroke-width:1.5px,rx:10,ry:10` |
| **Secondary** | `fill:#fff,stroke:#d0d0d0,color:#555,stroke-width:1px,rx:10,ry:10` |
| **Muted** | `fill:#fff,stroke:#d0d0d0,color:#999,stroke-width:1px,rx:10,ry:10` |
| **Accent (green)** | `fill:#eef7ee,stroke:#8cb88c,color:#333,stroke-width:1px,rx:10,ry:10` |
| **Pill** | `fill:#f9f9f9,stroke:#bbb,color:#555,stroke-width:1px,rx:20,ry:20` |

**Layout:** Prefer `flowchart LR` (left-right) or `flowchart TD` (top-down). Keep labels short. Use `<br/>` for line breaks, `<b>` for bold, `<i>` for italic. **Always place a space before `<br/>`** (e.g. `"Word <br/>next line"` not `"Word<br/>next line"`) — this ensures readable fallback if the line break doesn't render.

---

## Delivery: HTML Format

The output is a single `.html` file. See `EXAMPLE.html` for the exact structure — match it precisely.

The HTML uses external CSS, JS, and Mermaid hosted on CDNs. You only write the HTML — never modify CSS or JS.

### HTML Skeleton

Every generated file MUST use this exact structure. Only the placeholders change.

```html
<!DOCTYPE html>
<html lang="es" data-theme="light">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="description" content="YOUR_DESCRIPTION_HERE">
  <meta name="robots" content="noindex, nofollow">

  <!-- Open Graph -->
  <meta property="og:title" content="YOUR_TITLE_HERE">
  <meta property="og:description" content="YOUR_SHORT_DESCRIPTION_HERE">
  <meta property="og:image" content="https://tonki.dev/concept-teacher/featured-image.png">
  <meta property="og:type" content="article">

  <!-- Twitter Card -->
  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:title" content="YOUR_TITLE_HERE">
  <meta name="twitter:description" content="YOUR_SHORT_DESCRIPTION_HERE">
  <meta name="twitter:image" content="https://tonki.dev/concept-teacher/featured-image.png">

  <title>YOUR_TITLE_HERE</title>
  <link rel="icon" type="image/svg+xml" href="https://tonki.dev/concept-teacher/favicon.svg">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link href="https://fonts.googleapis.com/css2?family=Source+Serif+4:ital,opsz,wght@0,8..60,300;0,8..60,400;0,8..60,600;0,8..60,700;1,8..60,400&family=Inter:wght@400;500;600&display=swap" rel="stylesheet">
  <link rel="stylesheet" href="https://tonki.dev/concept-teacher/styles.css">
  <script>
    (function() {
      var saved = localStorage.getItem('theme');
      if (saved) {
        document.documentElement.dataset.theme = saved;
      } else if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
        document.documentElement.dataset.theme = 'dark';
      }
    })();
  </script>
</head>
<body>

  <div class="header-row">
    <div class="header-top">
      <h1>YOUR_TITLE_HERE</h1>
      <button class="theme-toggle" aria-label="Toggle theme"></button>
    </div>
    <button class="copy-btn copy-btn--full" data-copy="main">Copy all</button>
  </div>

  <article id="main-content">
    <!-- ═══ ALL YOUR CONTENT GOES HERE ═══ -->
  </article>

  <hr>
  <h2>Seguir explorando</h2>
  <div id="follow-ups">
    <!-- ═══ FOLLOW-UP QUESTIONS GO HERE ═══ -->
  </div>

  <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
  <script src="https://tonki.dev/concept-teacher/script.js"></script>
</body>
</html>
```

### What changes per topic
- `<title>`, `<h1>`, `og:title`, `twitter:title` — the topic title
- `meta description`, `og:description`, `twitter:description` — a one-sentence summary
- Everything inside `<article id="main-content">` — the full content
- Everything inside `<div id="follow-ups">` — the 10 follow-up questions

### What NEVER changes
- The CSS, JS, favicon, and featured image URLs (all from `tonki.dev/concept-teacher/`)
- The Mermaid CDN script
- The flash-prevention inline script in `<head>`
- The header structure (theme toggle + copy-all button — SVG icons are injected by JS, buttons stay empty)

### HTML element reference

| Element | HTML |
|---------|------|
| Diagram | `<div class="diagram-container scrollable-x"><pre class="mermaid">...</pre></div>` |
| Side-by-side diagrams | `<div class="compare-grid"><section>...<div class="diagram-container scrollable-x">...</div></section><section>...</section></div>` |
| Diagram label | `<p class="diagram-label">LABEL TEXT</p>` |
| Checkpoint | `<div class="checkpoint"><strong>CHECKPOINT</strong> Your text here.</div>` |
| Reflection | `<blockquote><p><strong>Para reflexionar:</strong> ...</p></blockquote>` |
| Table | `<div class="table-wrap scrollable-x"><table>...</table></div>` |
| Follow-up item | `<div class="follow-up-item"><p><span class="follow-up-number">1.</span> Question text.</p><button class="copy-btn copy-btn--full"></button></div>` |

---

## After Generating the HTML

Upload the file to the server:

```bash
scp <local-file.html> agents:/home/openclaw/webapps/OpenClaw/concept-teacher/<filename>.html
```

The file will be available at `https://agents.maurosicard.com/concept-teacher/<filename>.html`

Server details:
- **Host alias:** `agents`
- **Path:** `/home/openclaw/webapps/OpenClaw/concept-teacher/`
- **Auth:** Already configured via SSH key — no password needed.