# Create an Inside topic pull request

Replace `{{TOPIC}}` with any subject. Give the resulting prompt to an AI coding assistant with access to this repository or the complete creator kit.

---

Create a beginner-friendly Inside topic about **{{TOPIC}}** and open a focused GitHub pull request in `RodimusGPT/learn-inference`. The result must explain the subject through accurate content and informative visuals, with evidence from the rendered experience.

## 1. Open the right source

Inspect contributor instructions, the GitHub remote, and the default branch. Resolve the repository from its GitHub remote or the canonical README URL, `https://github.com/RodimusGPT/learn-inference`. If the creator kit has no Git metadata, clone that repository into an isolated checkout. Fetch the latest GitHub `main` and create an isolated branch or worktree from it. Preserve unrelated changes; do not use a Sites hosting remote as the PR destination or create another Site. Preserve `.openai/hosting.json`, Site identity, and audience.

Work from the project root, where `authoring/`, `scripts/`, and `dist/` are siblings. Read `authoring/DESIGN_LANGUAGE.md`, `authoring/topic.schema.json`, `authoring/topic.template.json`, and the actual rendering, styles, and controls in `dist/assets/`. Inspect existing topics and covers, but do not copy their weaknesses or treat a template's sequence of visual types as a storyboard.

## 2. Define and verify the lesson

State the beginner's question, prerequisites, scope, and what the reader should be able to explain or predict afterward. Make the title honest about that scope: a conceptual overview is not an executable tutorial. Use one concrete example that can recur across the deck. Introduce its setting and necessary vocabulary before depending on them; teach the worked mechanism before a broad taxonomy or infrastructure map.

Research unfamiliar, disputed, health-related, or time-sensitive claims using reliable sources, preferring primary documentation, authoritative public-health sources, and original research. Verify arithmetic independently, including denominators, units, rounding, probability conditioning, and boundary cases. Check causal language, exceptions, architecture/version dependence, and dates. Never invent empirical data, benchmarks, citations, quotations, or evidence. Distinguish observations, established explanations, assumptions, and illustrative values. Qualify or omit unsupported claims; do not infer treatment advice or causation from an association.

Maintain a compact claim/source/assumption record for the PR. Include supported topic metadata `reviewed: "YYYY-MM-DD"` and `sources: [{title, url}]`, using verified absolute HTTP(S) URLs. The reader renders those as named links. Complete HTTP(S) URLs in detail text are also linked safely; raw HTML and Markdown are not executed. Optional `glossary: [{term, definition}]` supplies a position-preserving Vocabulary dialog, but essential first-use definitions still belong in the main explanation. Test the rendered references and do not invent unsupported metadata fields.

## 3. Storyboard before writing JSON

Build a coherent 6–12-slide narrative: question and scope, mechanism, worked example, useful contrast or misconception, transfer check, and visible synthesis. Adapt the sequence to the subject. Explain one idea per slide; summaries must contain at most 26 words.

For each slide, record: the learning question, concrete subject elements, relationship or quantity encoded visually, what stays fixed, what changes, and what the reader can infer from the picture. For a control, also record the prediction it tests and the evidence its result will show. Review the whole storyboard before implementation. One custom figure surrounded by generic prose cards does not establish visual explanation across a deck.

Keep essential definitions, example setup, quantities/denominators, model scope, and caveats needed to interpret the visible claim in the visible summary or supported visual labels/caption/readout. Deeper notes are for derivations, evidence, exceptions, and extensions. A reader who never opens them must still understand the main argument and its necessary qualifications. Do not bury the only worked calculation or the most informative counterexample there. Rewrite or split a slide instead of shrinking text to fit the word limit.

## 4. Show the relationship faithfully

Prefer recognizable subject structures, pathways, boundaries, spatial relationships, or concrete worked quantities. For example, show a gut's lumen and wall when teaching absorption; a genome and host-cell boundary when teaching infection; the relevant population when teaching a probability denominator; and principal plus accumulated interest when teaching compounding. Reuse meaningful elements across states and slides so the reader follows the same example.

Shape, position, connections, enclosure, scale, or changing state must carry information. Prose cards can orient, compare, assess, and recap, but renamed keyword boxes, a large answer number, or numbered paragraphs do not by themselves show a mechanism. Choose each view for its teaching purpose rather than imposing an interaction or visual-type quota. Static diagrams and meaningful part/pathway highlights are valid; movement is needed only when it explains a change.

Use a physical analogy only when its operation maps clearly to the important relationship and helps more than a direct diagram. A generic press, copying bench, drawer rack, or row of stations with subject labels is insufficient. Identify literal diagrams versus analogies in a visible caption; explain what highlights mean and where the mapping stops. A disclaimer cannot rescue a picture whose geometry teaches the wrong relationship. For figures built with the Anatomy skill, follow its applicable filled-solid, depth-order, geometry, line-end, 4× close-up, and mobile audits. Its machinery requirements apply when choosing machinery; they do not require biological or mathematical subjects to become machines. If the skill is unavailable, report that limit and use a supported faithful representation without claiming its audits passed.

For charts, use honest scales, units, baselines, labeled groups and readable values. Distinguish a quantity from its complement, a conditional probability from the reverse condition, and a forecast from an illustration. Show a path, composition, or denominator when that relationship explains the result; endpoint numbers alone may conceal it.

## 5. Make controls and assessment earn their place

Match instruction to affordance. Say “step through” for a fixed walkthrough; say “choose” or “change” only when the reader can do that action. A prediction may be mental before a reveal; it does not require another input control. Clearly label scripted demonstrations and invented probabilities. If teaching actual tokenization, show verified token boundaries rather than passing illustrative phrases off as real tokens.

Drive controls, visible states, highlighted parts, quantities, explanations and readouts from one checked model. Highlights must identify the same relationship the readout describes. If a variable is claimed to change geometry, quantity, or outcome, show that change or explicitly label a selector as comparing preset cases. For a central comparison, visibly distinguish the important difference: identical highlighted parts with different sentences cannot show reversed energy flow, changed probability, or a learned update. Do not present color changes or an unrelated counter as a simulation. Model outputs and selected states must agree at every supported setting, including repeat, reverse, reset, and boundary states.

Use a transfer check that requires applying the lesson to a new case or selecting the right reasoning, not recalling an answer just shown. Keep the answer out of the visible pre-answer summary, title, and diagram. Use plausible misconception-based distractors, exactly one correct choice, and teaching feedback for every option. The renderer already prefixes success/failure messages; avoid duplicated prefixes. Finish with a visible mental model and a deliberate next action using supported navigation. Do not make the only recap optional or invent an unsupported recap type for a new topic.

## 6. Use real schema and renderer contracts

Use a unique lowercase hyphenated topic ID, unique slide IDs, `level: "Beginner"`, a useful category, and search tags. General visuals are `steps`, `comparison`, `number`, `chart`, `check`, `concept`, `anatomy`, and `model`; inspect their exact payloads and behavior. Use inference-specific visuals only where their current behavior accurately fits. The generic bar chart accepts nonnegative values. Do not add an image field, source field, caption, or visual type and assume it renders.

Map every meaningful authored explanation, assumption, caption, item body, figure label, state and feedback message to a reachable rendered surface or accessible description. Schema-valid JSON and a successful build do not prove this. Expand all notes, open nested controls, and compare the actual DOM with the authored content. In particular, inspect specialized item renderers: a `brief` must not silently hide a necessary `text` definition. Use supported fields or make the smallest compatible renderer/schema change needed for this topic, with focused verification; never leave required teaching content in ignored fields.

For a stateful subject diagram or calculated relationship, use `visual: "model"`, `model: {kind, view}`, and a visible `caption`. Inspect existing local model modules before reusing a kind/view. Register new modules with `InsideModels.register(kind, {render(config, slide), mount(host, config, slide)})`; the renderer returns inner HTML and mount returns cleanup when needed. Load local JS/CSS before the app in `src/index.html`; the build embeds them in the offline edition. The edition/model contract check must resolve and render every authored model. Never select a new kind/view without implementing it.

For 2–8 meaningful discrete states, prefer the reusable `visual: "anatomy"` controller:

```text
figure: {asset: "assets/figures/<topic-id>.svg", label,
  states: [{id, label, readout, parts: ["part-id"]}]}
```

SVG groups use matching `id` and `data-anatomy-part` values. Supply a visible slide `caption` identifying the diagram/analogy, highlights, and simplifications. Use the kit's paint variables/classes or topic-scoped SVG styles responding to `.is-hot`; hard-coded fills alone do not react. The controller supplies buttons, keyboard stepping and playback/highlights; it does not move geometry or calculate a new model. Include focused implementation source if those behaviors are essential, and audit the full supported range. Keep all runtime assets local, self-contained, and free of scripts or external dependencies in SVGs.

## 7. Preserve identity and readable access

Preserve cream `#f2f0e6`, moss `#2d4939`, sage `#93a585`, Georgia headings, system sans body, and monospace utility text. Color identity does not require low-contrast text: normal text needs at least 4.5:1 contrast on every actual surface; large text needs 3:1. Keep sage for suitable illustration/accent roles. Essential control/state indicators and informative graphical boundaries need at least 3:1 contrast against adjacent colors. Decorative fills need not meet that target. Do not encode selection or correctness with color alone.

Use comfortably readable explanatory text: aim for 16px body text and at least 14px necessary captions/readouts at mobile size. These are readability targets, not WCAG font-size rules. Do not solve layout by hiding a needed caveat in 7–10px utility text. Keep controls labeled and keyboard accessible, with visible focus, useful announcements, and sufficient target size and spacing. Keep the figure close to its explanation and avoid pushing it behind a long mobile outline or expanded appendix.

Under reduced motion, update settled state and readout immediately without travel, pulsing, or autoplay. Stop activity offscreen and clean up timers, frames and listeners on slide disposal. Verify route entry/exit focus, arrow-key behavior inside controls, mobile outline selection, and reachability after scrolling past sticky navigation. Inspect actual computed styles and behavior rather than assuming the existing reader satisfies these requirements. Distinguish new regressions from inherited shared-reader issues; document unresolved ones with reproduction steps and do not claim they were fixed by topic JSON. Keep unrelated site-wide redesign out of this PR.

## 8. Create a recognizable cover

Save original subject-specific artwork at `dist/assets/covers/<id>.svg` (local PNG, WebP, JPG or JPEG also works). Declare `cover: {"src": "assets/covers/<id>.svg", "alt": "A useful description of the subject and meaningful parts"}`. Paths are relative to `dist/`; cover metadata is independent of the slide visual type. Do not reuse generic bars, another topic's image, or renamed copies. Validation/builds reject missing files, blank alt text and exact duplicate artwork; only visual review can judge relevance and near-duplicates. Compare the new cover beside every library card at desktop and 390px, including crop and alt text, and verify it in the offline edition and creator kit.

## 9. Validate the rendered lesson and packages

Write the topic to `dist/data/topics/<topic-id>.json` and include only needed local assets/implementation source. From the project root run:

```sh
node scripts/add-topic.mjs --validate dist/data/topics/<topic-id>.json
node --check dist/assets/app.js
python build.py
node --test scripts/explainer-contract.test.mjs
```

Render every slide at desktop and 390px, plus a representative narrow 320px view and 200% zoom. Wait for figure loading and entry transitions to settle before judging screenshots. Critique and revise the picture in the reader, not just its isolated SVG. Check subject recognition, causal meaning, focal point, legible labels, contrast, cropping, overlap, control/readout space, horizontal overflow, and reachability at maximum scroll. A sticky bar crossing a full-page screenshot is not proof that content is inaccessible; test scrolling and focus.

Verify library discovery, direct routes, slide count/navigation, every figure state and named part, every quiz answer/feedback, expanded and nested details, keyboard controls, reduced motion, repeated use/reset, route focus, and offscreen cleanup. Check browser errors and model/readout agreement. Geometry and line-end passes establish construction quality, not teaching value. Record each check as passed, failed or unverified with concise evidence; unavailable browser/screenshots are unverified, never a visual pass.

`build.py` derives the catalog and all downloads. Check generated cover metadata and inspect the standalone library, website ZIP and complete creator kit for the new topic/assets. When authoring instructions change, edit canonical `authoring/TOPIC_PROMPT.md` and aligned guidance, then verify the build propagates the same prompt to `dist/assets/topic-prompt.txt`, `dist/downloads/inside-topic-prompt.md`, the offline payload, website ZIP, and creator kit. Do not hand-edit only a generated copy.

## 10. Open a reviewable PR

Create a focused commit and push to GitHub; open a PR against `main`. Normally commit the topic JSON, needed cover/figure/implementation source, and focused checks. Omit generated `dist/data/catalog.json`, download bundles, and output archives unless explicitly requested. Do not overwrite an existing topic without authorization, expose credentials, or include unrelated changes.

Use a clear title and concise description of the question, resulting reader experience, preview route, sources/calculation checks, visual critique, and validation evidence. Identify which observation each key visual/control teaches; include desktop/mobile evidence, applicable Anatomy audit results, and unresolved shared-reader limitations. A build pass does not waive a failed acceptance check: keep material failures explicit and use a draft PR when the lesson is not ready for review as complete. CI attaches a static preview artifact.

**Finish by reporting the PR link. Do not merge the PR or deploy to production.** This PR boundary overrides any Sites publishing default. Preserve `.openai/hosting.json`; publication is a separate maintainer action. If the user explicitly requests only a local draft or JSON, stop at that boundary.
