coursmith 0.0.0-stage → 0.1.0

package/skill/coursmith-course/references/animation-presets.md

@@ -0,0 +1,143 @@
+# Animation presets
+
+Animations are declared, not coded: you choose a preset and give it parameters, and the portal renders it
+with consistent motion and styling (and shows a static version to learners who prefer reduced motion).
+Use an animation block as a step's `visual` or among its `blocks`:
+
+```json
+{ "type": "animation", "caption": "Optional caption", "animation": { "preset": "…", "…": "…" } }
+```
+
+Pick the preset that matches the idea, not the one that looks busiest:
+
+| Preset | Shows | Use it for |
+|---|---|---|
+| `sequence` | Items appearing one after another | Lists of parts, ingredients, features, principles |
+| `flow` | Nodes connected by arrows with moving particles | Causes and effects, data or energy flowing through a system |
+| `timeline` | Dated events along a line | History, project phases, evolution of an idea |
+| `process` | Numbered stages revealed in order | Procedures and pipelines with a clear order |
+| `compare` | Before/after slider | Contrasting two states, a wrong vs right approach |
+| `counter` | Numbers counting up to a value | Orders of magnitude, key statistics |
+| `highlight-svg` | Your SVG with parts highlighted one by one | Anatomy of an object, parts of a diagram or interface |
+
+All examples below pass `coursmith validate`.
+
+## sequence
+
+- `layout`: `row` (default), `column` or `grid`.
+- `items`: 2–12, each `label` (≤ 80 chars), optional `description` (≤ 240) and `icon` (a single emoji).
+
+```json animation
+{
+  "preset": "sequence",
+  "layout": "grid",
+  "items": [
+    { "label": "Sun", "icon": "☀️", "description": "Solar panels convert light." },
+    { "label": "Wind", "icon": "🌬️", "description": "Turbines convert moving air." },
+    { "label": "Water", "icon": "💧", "description": "Dams convert falling water." }
+  ]
+}
+```
+
+## flow
+
+- `direction`: `LR` (left to right, default) or `TB` (top to bottom).
+- `nodes`: 2–12, each with an `id` (lowercase-dash) and `label` (≤ 60).
+- `edges`: 1–24, each `from` and `to` (node ids) and an optional short `label` (≤ 40).
+
+```json animation
+{
+  "preset": "flow",
+  "direction": "LR",
+  "nodes": [
+    { "id": "sun", "label": "Sunlight" },
+    { "id": "panel", "label": "Solar panel" },
+    { "id": "inverter", "label": "Inverter" },
+    { "id": "home", "label": "Home" }
+  ],
+  "edges": [
+    { "from": "sun", "to": "panel" },
+    { "from": "panel", "to": "inverter", "label": "DC" },
+    { "from": "inverter", "to": "home", "label": "AC" }
+  ]
+}
+```
+
+## timeline
+
+- `events`: 2–16, each `date` (free text ≤ 40, e.g. `1882`, `Q3 2024`, `Day 1`), `title` (≤ 80), optional `description`.
+
+```json animation
+{
+  "preset": "timeline",
+  "events": [
+    { "date": "1831", "title": "Faraday discovers induction" },
+    { "date": "1882", "title": "First public power station", "description": "Pearl Street, New York." },
+    { "date": "1990s", "title": "Grid interconnection across Europe" }
+  ]
+}
+```
+
+## process
+
+- `steps`: 2–10, each `title` (≤ 80) and optional `description` (≤ 240). Stages are numbered automatically.
+
+```json animation
+{
+  "preset": "process",
+  "steps": [
+    { "title": "Measure", "description": "Read the meter at the start of the month." },
+    { "title": "Subtract", "description": "Subtract it from the reading at the end." },
+    { "title": "Multiply", "description": "Multiply the kWh by the price per kWh." }
+  ]
+}
+```
+
+## compare
+
+- `before` and `after`: each a `label` (≤ 60) plus `text` (≤ 400) and/or `asset` (an image or svg asset id).
+  At least one of `text` or `asset` is required on each side.
+
+```json animation
+{
+  "preset": "compare",
+  "before": { "label": "Incandescent bulb", "text": "60 W for 800 lumens; most energy becomes heat." },
+  "after": { "label": "LED bulb", "text": "9 W for the same 800 lumens." }
+}
+```
+
+## counter
+
+- `items`: 1–6, each `label`, `to` (target number), optional `from` (default 0), `unit` (≤ 12 chars) and
+  `decimals` (0–4, default 0).
+
+```json animation
+{
+  "preset": "counter",
+  "items": [
+    { "label": "Transmission line", "to": 380000, "unit": "V" },
+    { "label": "Home socket", "to": 230, "unit": "V" },
+    { "label": "Efficiency", "to": 93.5, "unit": "%", "decimals": 1 }
+  ]
+}
+```
+
+## highlight-svg
+
+- `asset`: an asset of kind `svg`.
+- `highlights`: 1–12, each `elementId` (the `id` attribute of an element in the SVG; letters, digits, `_`
+  and `-`, starting with a letter), `label` and optional `description`. Elements are highlighted in order.
+- Group each highlighted part in a `<g id="...">` so the whole part lights up. The portal removes scripts,
+  event handlers, `<foreignObject>`, `<image>`, `<use>` and external links, but keeps ids; if an id you
+  reference is missing after that cleanup, the submission is sent back with `animation.unknown_element`.
+
+```json animation
+{
+  "preset": "highlight-svg",
+  "asset": "home-panel",
+  "highlights": [
+    { "elementId": "meter", "label": "Meter", "description": "Measures the energy you use." },
+    { "elementId": "breakers", "label": "Circuit breakers", "description": "Protect each circuit." }
+  ]
+}
+```

package/skill/coursmith-course/references/block-catalog.md

@@ -0,0 +1,277 @@
+# Block catalog
+
+Every step has `blocks` (the text and media the learner reads, in order) and an optional `visual` (the
+step's main illustration). The portal shows the visual pinned beside the text in scrollytelling, split
+screen in the stepper and slides, and inline in document mode.
+
+- `blocks` accepts: `markdown`, `callout`, `image`, `code`, `math`, `table`, `quote`, `chart`, `diagram`, `animation`.
+- `visual` accepts: `chart`, `diagram`, `animation`, `image`.
+- Unknown keys are rejected everywhere. Optional `caption` fields are shown under the element.
+
+All examples below pass `coursmith validate`.
+
+## Step skeleton
+
+```json step
+{
+  "id": "why-high-voltage",
+  "title": "Why high voltage?",
+  "visual": { "type": "diagram", "syntax": "mermaid", "code": "flowchart LR\n  A[Plant] --> B[Lines] --> C[Homes]" },
+  "blocks": [
+    { "type": "markdown", "text": "Wires waste energy as heat, so the grid raises the [[voltage]]." }
+  ]
+}
+```
+
+## Text blocks
+
+### markdown
+
+Paragraphs, lists, **bold**, *italic*, `inline code` and links. Rules:
+
+- No raw HTML (`<br>`, `<b>`, `<script>`…). No Markdown images: use an `image` block.
+- Links must start with `https://`.
+- Mark glossary terms as `[[term]]` or `[[term|text shown]]`. The term must be defined in the glossary of
+  this section or an earlier one (its `term` or one of its `aliases`, case-insensitive).
+- Keep one idea per block; prefer several short blocks to one long one.
+
+```json block
+{
+  "type": "markdown",
+  "text": "A [[transformer]] changes the [[voltage|voltage level]] of alternating current.\n\n- Step-up: raises it for transmission\n- Step-down: lowers it for homes\n\nMore on [Wikipedia](https://en.wikipedia.org/wiki/Transformer)."
+}
+```
+
+### callout
+
+`variant` is one of `info`, `tip`, `warning`, `example`. `title` is optional.
+
+```json block
+{ "type": "callout", "variant": "warning", "title": "Safety first", "text": "Never open an electrical panel yourself." }
+```
+
+### quote
+
+```json block
+{ "type": "quote", "text": "Nothing in life is to be feared, it is only to be understood.", "cite": "Marie Curie" }
+```
+
+### code
+
+`language` is a lowercase highlighter name such as `python`, `ts`, `js`, `bash`, `sql`, `json`, `c++`, `c#`.
+
+```json block
+{ "type": "code", "language": "python", "code": "power_kw = 2\nhours = 1.5\nprint(power_kw * hours)  # 3.0 kWh", "caption": "Energy = power × time" }
+```
+
+### math
+
+LaTeX rendered with KaTeX. Escape backslashes in JSON (`\\frac`).
+
+```json block
+{ "type": "math", "tex": "E = P \\times t", "caption": "Energy equals power times time." }
+```
+
+### table
+
+`headers` has 1–10 columns; every row must have exactly as many cells as `headers`. Up to 50 rows.
+
+```json block
+{
+  "type": "table",
+  "headers": ["Device", "Power", "Energy in 2 h"],
+  "rows": [["Oven", "2 kW", "4 kWh"], ["LED bulb", "10 W", "0.02 kWh"]],
+  "caption": "Typical household devices"
+}
+```
+
+## Media blocks and visuals
+
+### image
+
+Refers to an entry of `assets` by id. Raster images (`png`, `jpg`, `webp`) and `svg` are accepted.
+
+```json visual
+{ "type": "image", "asset": "home-panel", "caption": "A typical home electrical panel" }
+```
+
+The matching asset entry:
+
+```json asset
+{ "id": "home-panel", "kind": "svg", "file": "assets/home-panel.svg", "alt": "Electrical panel with meter, main switch and four breakers", "generatedBy": "hand-written SVG" }
+```
+
+### chart (Vega-Lite)
+
+A [Vega-Lite v6](https://vega.github.io/vega-lite/) spec. Rules:
+
+- Data must be inline in `data.values`. Any `url` (data or images) and any `href` are rejected.
+- Keep it small (well under 200 KB): aggregate before charting.
+- Give axes readable titles in the course language; label illustrative numbers as such in the `caption`.
+- Leave size and colors to the portal's theme (light and dark) unless a color carries meaning.
+
+```json visual
+{
+  "type": "chart",
+  "title": "Share of household consumption",
+  "caption": "Illustrative figures.",
+  "spec": {
+    "data": { "values": [
+      { "use": "Heating", "share": 45 },
+      { "use": "Appliances", "share": 30 },
+      { "use": "Lighting", "share": 10 },
+      { "use": "Other", "share": 15 }
+    ] },
+    "mark": { "type": "arc", "innerRadius": 50 },
+    "encoding": {
+      "theta": { "field": "share", "type": "quantitative" },
+      "color": { "field": "use", "type": "nominal", "title": "Use" }
+    }
+  }
+}
+```
+
+Line and bar charts follow the usual Vega-Lite shape (`mark: "line"` / `"bar"`, `x` and `y` encodings).
+
+### diagram (Mermaid)
+
+`syntax` is always `"mermaid"`. The first line must be one of these diagram types: `flowchart`, `graph`,
+`sequenceDiagram`, `classDiagram`, `stateDiagram`, `stateDiagram-v2`, `erDiagram`, `gantt`, `pie`,
+`journey`, `mindmap`, `timeline`, `quadrantChart`, `xychart-beta`.
+Not allowed: `click` handlers, links (`href`) and `%%{init: ...}%%` directives.
+
+```json visual
+{
+  "type": "diagram",
+  "syntax": "mermaid",
+  "code": "sequenceDiagram\n  participant P as Plant\n  participant G as Grid operator\n  P->>G: Produces 500 MW\n  G-->>P: Reduce output",
+  "caption": "The operator keeps supply and demand balanced."
+}
+```
+
+### animation
+
+An animation is a preset rendered by the portal from parameters. See `animation-presets.md` for all seven.
+
+```json visual
+{
+  "type": "animation",
+  "caption": "From the plant to your home",
+  "animation": {
+    "preset": "process",
+    "steps": [
+      { "title": "Generation", "description": "A turbine spins a generator." },
+      { "title": "Transmission", "description": "High-voltage lines carry the power." },
+      { "title": "Distribution", "description": "Local lines deliver 230 V." }
+    ]
+  }
+}
+```
+
+## Questions
+
+### check (end of a step, not scored)
+
+Types `single`, `multiple`, `true_false`. Option ids are short lowercase strings such as `a`, `b`, `c`.
+
+```json check
+{
+  "id": "check-transformer",
+  "type": "single",
+  "prompt": "What does a transformer change?",
+  "options": [
+    { "id": "a", "text": "The voltage" },
+    { "id": "b", "text": "The frequency" },
+    { "id": "c", "text": "The colour of the wires" }
+  ],
+  "correct": "a",
+  "explanation": "Transformers raise or lower voltage; frequency stays the same."
+}
+```
+
+### final quiz questions
+
+Same as checks plus `sectionRef` (the id of the section the question tests) and the `ordering` type.
+
+```json question
+{
+  "id": "q-multiple-renewables",
+  "sectionRef": "generation",
+  "type": "multiple",
+  "prompt": "Which of these sources are renewable?",
+  "options": [
+    { "id": "a", "text": "Wind" },
+    { "id": "b", "text": "Coal" },
+    { "id": "c", "text": "Sunlight" }
+  ],
+  "correct": ["a", "c"],
+  "explanation": "Wind and sunlight replenish naturally; coal is a fossil fuel."
+}
+```
+
+```json question
+{
+  "id": "q-true-false-frequency",
+  "sectionRef": "generation",
+  "type": "true_false",
+  "prompt": "The European grid runs at 50 Hz.",
+  "correct": true,
+  "explanation": "European grids use 50 Hz; North America uses 60 Hz."
+}
+```
+
+```json question
+{
+  "id": "q-ordering-journey",
+  "sectionRef": "generation",
+  "type": "ordering",
+  "prompt": "Put the journey of electricity in order.",
+  "items": [
+    { "id": "plant", "text": "Power plant" },
+    { "id": "lines", "text": "Transmission lines" },
+    { "id": "home", "text": "Home" }
+  ],
+  "explanation": "Electricity is generated, transmitted at high voltage, then distributed to homes."
+}
+```
+
+## Glossary entries
+
+```json glossary
+{ "term": "kilowatt-hour", "aliases": ["kilowatt-hours", "kWh"], "definition": "The energy used by a 1 kW device running for one hour; the unit on electricity bills." }
+```
+
+## Course metadata
+
+`category` is one of: `technology`, `programming`, `data-ai`, `science`, `mathematics`, `engineering`,
+`business`, `finance`, `marketing`, `design`, `arts-music`, `languages`, `history`, `humanities`,
+`health-wellness`, `environment`, `law-policy`, `personal-development`, `education`, `other`.
+
+```json meta
+{
+  "title": "Come arriva l'elettricità a casa tua",
+  "subtitle": "Dalla centrale alla presa, passo dopo passo",
+  "description": "Segui il viaggio dell'energia elettrica: produzione, trasmissione ad alta tensione, rete di distribuzione e quadro elettrico di casa.",
+  "language": "it",
+  "difficulty": "beginner",
+  "category": "engineering",
+  "tags": ["energia", "rete elettrica"],
+  "estimatedMinutes": 30,
+  "learningObjectives": ["Spiegare come funziona un generatore", "Descrivere il ruolo dei trasformatori"],
+  "prerequisites": [],
+  "coverImage": "cover",
+  "accentColor": "#2563eb"
+}
+```
+
+## Limits
+
+| Item | Limit |
+|---|---|
+| `course.json` | 2 MB |
+| One asset file | 3 MB; all assets 25 MB |
+| Sections | 1–12, each 1–15 steps, 80 steps in total |
+| Blocks per step | 1–20 |
+| Glossary per section | 1–40 entries |
+| Final quiz | 10–40 questions |
+| Markdown block | 20,000 characters |

package/skill/coursmith-course/references/content-policy.md

@@ -0,0 +1,47 @@
+# Coursmith content policy
+
+Courses must be educational, accurate and respectful. The review agent applies these rules to all text,
+charts, diagrams, animations and images in a course.
+
+## Not allowed (the course is rejected)
+
+- **Hate and harassment**: content that demeans or attacks people for ethnicity, nationality, religion,
+  gender, sexual orientation, disability, age or similar traits; slurs; targeted harassment of real people.
+- **Blasphemy and mockery of beliefs**: content meant to insult, ridicule or desecrate religions, their
+  figures, symbols or believers. Neutral, factual teaching about religions, their history and critiques
+  presented with respect is allowed.
+- **Sexual content**: explicit sexual material, sexualization of anyone, any sexual content involving minors.
+- **Graphic violence or gore** presented for shock value; glorification of violence, terrorism or extremism;
+  extremist propaganda or recruitment.
+- **Dangerous instructions**: weapons, explosives or drug synthesis; malware or intrusion techniques aimed at
+  real systems; self-harm or suicide methods; dangerous challenges.
+- **Illegal activity**: fraud, scams, evading law enforcement, piracy guides, trafficking.
+- **Deception**: deliberate disinformation, conspiracy theories presented as fact, impersonation of real
+  people or organizations, plagiarism of copyrighted works.
+- **Spam**: advertising, affiliate links, courses whose purpose is to sell something rather than to teach.
+
+## Sensitive topics (allowed with care; otherwise revision is required)
+
+Health and medicine, mental health, law, personal finance and investing, politics, religion, history of
+conflicts and atrocities, sexuality education, drugs and addiction (prevention and awareness).
+
+Courses on these topics must:
+- stay factual, balanced and neutral, presenting established consensus and noting where experts disagree;
+- avoid giving individual medical, legal or financial advice, and include a short disclaimer pointing
+  learners to qualified professionals;
+- describe difficult events without graphic detail and with respect for victims.
+
+## Quality requirements (revision is required when not met)
+
+- **Accuracy**: no factual errors, outdated claims presented as current, or invented data. Example figures
+  must be labelled as illustrative.
+- **Clarity**: each step explains one idea in plain language suited to the declared difficulty; no
+  unexplained jumps.
+- **Language**: all learner-facing text is written in the course's declared language.
+- **Difficulty**: content depth matches the declared level (beginner, intermediate, advanced).
+- **Glossary**: every concept introduced and every technical or domain-specific term used in a section is
+  defined in that section's glossary (or an earlier one), with a correct, self-contained definition.
+- **Quiz**: every question has exactly the declared correct answer, unambiguous wording, plausible
+  distractors, and an explanation consistent with the course content.
+- **Visuals**: charts, diagrams, animations and images must be relevant, correctly labelled and consistent
+  with the text.