# Learning Hub — Conventions This file is the single source of truth. Everything you need to build a blueprint is below — the template skeleton, the five patterns, the quiz protocol, the filing checklist. **Do not attempt to fetch any other URL from this repo** (recipes, template.html). If a fetch fails, you already have what you need. If you cannot fetch this file at all, ask the user to paste it. ## Who the user is A visual learner building understanding with AI assistance. The goal is *understanding*, not artifacts. AI makes it too easy to skip the learning; this system keeps learning in the loop. Teach intuition-up: basic concepts → examples → intuition → precise terms. Simple English where it works, but *correct technical vocabulary* — simple ≠ dumbed-down. The user wants to grow their vocabulary of precise terms. **Diagrams matter — the user is a visual learner.** Use them for relationships, spatial structures, transformations. Don't use them for definitions or linear prose. One per section unless the section is fundamentally visual. Every diagram uses the visual grammar established in the blueprint's legend. ## The hub - **`learning-hub`** (private) — `topics/*.html` (the blueprints), `assets/blueprint.css` (shared styling), `log.md`, `index.html` (generated). Deployed to Cloudflare Pages at `https://learning-hub-3qh.pages.dev/`. - **`learning-hub-rules`** (public, this repo) — this file. (recipes/ and template.html also exist for human readers; agents don't need them.) A blueprint is a self-contained HTML file at `topics/.html`. Each teaches one topic, intuition-up, and links to its prerequisites and dependents. The substance is HTML — visuals, diagrams, worked examples — not markdown notes. ## How to build a blueprint ### Intuition-up ordering Teach in this order, adapted to what the topic needs: 1. **The intuition first** — plain English, the metaphor or mental model, no jargon. The "why this exists" — what problem does the concept solve? 2. **Examples** — concrete before abstract. The most familiar case first, then a second from a different angle if the concept has multiple modes. 3. **The precise terms** — technical vocabulary, anchored to the intuition above. 4. **Why it's shaped this way** — the structural insight, the trade-off the shape embodies. Not every section needs all four. The order is a default, not a law. ### The visual-learning constraint **Use a diagram for:** how parts relate (dependency graph, data flow), spatial structures (trees, hierarchies, overlapping distributions), transformations (one state becoming another), comparisons where shape matters (two distributions, before/after). **Don't use a diagram for:** definitions (a sentence is sharper), linear prose (a diagram of "step 1 → step 2" is decoration), anything you could explain equally well in one sentence. One per section unless the section is fundamentally visual. Every diagram uses the visual grammar established in the blueprint's legend (see pattern 1 below). ### The five template patterns Every blueprint follows these. They are the load-bearing structure. **1. Visual grammar legend** — one line in the header, establishes the colors and symbols every diagram in the page will use: ```html

visual grammar {{concept A}} {{concept B}} {{counterfactual / imputed}}

``` The legend is taught once, used N times. A reader who has learned the grammar can scan every diagram without re-reading captions. Pick colors that carry meaning — `treated` vs `control`, `observed` vs `counterfactual` — not arbitrary decoration. **2. Modular sections** — each section opens with a chapter label and a title that is a *claim*, not a label: - ✅ "Why the average difference between groups lies" - ✅ "Compare like with like" - ❌ "Introduction to matching" - ❌ "Background" The title tells the reader what they'll understand by the end of the section. Sections are modular — no fixed order. Each picks from available blocks (prose, diagram, formula+where, key) as the topic needs. **3. Formula + "reading it"** — every formula is immediately followed by a plain-English breakdown that defines **every symbol, every time**. Vocabulary is re-stated, never assumed from earlier sections: ```html

reading it

{{symbol}} — {{plain-English definition, one sentence}}
{{symbol}} — {{plain-English definition, one sentence}}
{{whole expression}} — {{what it says in words}}

``` This is the single highest-value pattern — the anti-false-aha mechanism. A reader who skips the formula can still read the breakdown; a reader who reads both actually understands the formula. **4. Per-section "Remember"** — at the end of each section, a one-sentence distillation of the load-bearing insight. Often encodes the corrected misconception: ```html

Remember

``` "I thought X, but actually Y" lives here when the section is about a misconception the user held. **5. "In one breath" closing** — a single-paragraph synthesis of the whole topic. Each section's load-bearing insight strung together into one coherent statement: ```html

In one breath

``` This is the "do I actually understand this?" test. If you can write it, you understand it. If you can't, the blueprint isn't done. ### HTML template skeleton Copy this structure. CSS uses an absolute URL so it renders in artifact preview AND when deployed: ```html {{TOPIC}} — intuition blueprint

Intuition Blueprint

created: {{DATE}} last-updated: {{DATE}} {{tags}}

visual grammar {{concept A}} {{concept B}} {{counterfactual}}

{{Plain-English intuition. The metaphor. The "why this exists".}}

reading it

{{symbol}} — {{plain-English definition}}

Remember

In one breath

{{one-paragraph synthesis — each section's insight strung together}}

prereqs {{prerequisite}} leads to {{dependent}}

``` ### The metas Fill all of these in ``: - `source-chat` — URL of the chat that produced the blueprint (for reopening the session) - `last-quizzed` — date of last Socratic quiz, empty if never - `prerequisites` — comma-separated filenames of blueprints this one builds on - `tags` — comma-separated cross-cutting labels - `created`, `last-updated` — dates ### Cross-references (Karpathy model) The graph is the structure. Before filing a new or edited blueprint: 1. If you can see existing blueprints, link to related ones in the body AND in the `cross-refs` block. Edit those blueprints to link back. One write touches multiple files. 2. Categories emerge as clusters of cross-links. There is no `taxonomy.md` and no enforced hierarchy. 3. **If you can't see existing blueprints** (phone session, private repo unreachable): produce a standalone blueprint. **Do not create `` links to blueprints you cannot verify exist** — a link to a non-existent file is a dangling reference that breaks the graph. Instead, list related concepts as HTML comments (``) for the user to wire up from laptop. The user maintains the graph from laptop. **Manifest (best-effort):** `https://learning-hub-3qh.pages.dev/manifest.json` lists all blueprints with metadata (filename, title, tags, prerequisites, last-quizzed). If you can fetch it, use it for cross-referencing. If your environment blocks it, skip — the blueprint works standalone. ### What one blueprint covers A blueprint mirrors what one learning session produced. A focused session on DNS → one focused blueprint. A weeks-long session on causal inference → one field-through-line with multiple sections. The blueprint mirrors the session; the graph handles connections to the rest of the hub. Don't split a session's output artificially; don't merge unrelated sessions. ### Filing checklist - [ ] Template used, all `` filled - [ ] Visual grammar legend present - [ ] Each section has a claim-title, not a label-title - [ ] Every formula has a "reading it" block defining every symbol - [ ] Each section has a "Remember" callout - [ ] "In one breath" closing written (the understanding test) - [ ] Diagrams used only where they earn their place (visual-learning constraint) - [ ] Cross-references added (or noted as needed for laptop follow-up) ## How to quiz The Socratic protocol probes the *model*, not fact recall. Reading a blueprint produces a feeling of understanding that may be false; the quiz forces the user to do the connecting themselves. 1. **Read the blueprint** the user names. The "Remember" callouts and "In one breath" are the densest source of load-bearing insights. 2. **Ask one question at a time.** Wait for the answer before asking the next. Don't dump a list. 3. **Probe the model, not recall.** Good questions: - "Predict what happens if {{X is changed}}." — forces the user to use the model forward - "Explain why {{Y}} is the case, in your own words." — forces synthesis - "Generalize: would this still hold if {{Z}}?" — tests the boundaries - "Here's a scenario: {{...}}. What would you expect, and why?" — applies to a new case - "Compare {{A}} and {{B}} — what's the actual difference, and when does it matter?" — forces distinction Bad questions (avoid): "What is the definition of X?", "True or false: ...", "List the steps in ..." — these test recall, not understanding. 4. **After each answer:** say *what specifically* was right or wrong (not just "correct" / "incorrect"), then build the next question on what they showed they understood. 5. **Use the blueprint's diagrams.** If the user is shaky, point them at a specific diagram and ask them to explain what it shows in their own words. Visual learners consolidate through the visuals. 6. **End with a synthesis question** — "Sum up the whole topic in a paragraph, as if explaining to someone who hasn't read this." Their answer tells both of you whether the model is integrated or fragmentary. After the quiz: update `` in the blueprint and push. The index resets the spaced-retrieval nudge. If you can't push (phone session), tell the user the date to update. **Calibration:** if the user gets everything right, the next quiz should push toward edge cases and generalizations. If they struggle, anchor back to the intuition and diagrams before pushing to precise terms. The quiz is a learning tool, not an exam. ## Filing from a phone (claude.ai) Phone sessions can generate blueprints but can't push to the private repo. The flow: 1. Build the blueprint HTML following this file. 2. Output the complete HTML for the user to copy. 3. User goes to github.com mobile → `ArturGR3/learning-hub` repo → `topics/` → Add file → Create new file → name it `.html` → paste → commit. 4. The GitHub Action rebuilds `index.html` and deploys to Cloudflare Pages. 5. Cross-reference maintenance, `log.md` append, and `` updates happen on the next laptop session. The artifact preview should show correct styling via the absolute CSS URL. If it doesn't render, the deployed version will — the stylesheet loads from the hub's Pages URL. ## Filing from a laptop (opencode, Claude Code) 1. Build the blueprint following this file. 2. Save to `topics/.html` in the `learning-hub` repo. 3. Maintain cross-references: scan `topics/`, link related blueprints both directions. Edit linked blueprints to add back-links. 4. Run `scripts/file-blueprint.sh topics/.html "{{topic}} — {{one-line summary}}"` from the repo root. This validates the blueprint, appends `log.md`, stages source files, commits, and pushes. Don't run `build-index.py` locally — the GitHub Action regenerates `index.html` and `manifest.json` on push. 5. The Action rebuilds and deploys (~30s).

{{central question}}{{topic}}

{{claim-title — what they'll understand by the end}}