coursmith 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "coursmith",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Publish AI-written courses to Coursmith from Claude Code, Codex, Cursor, OpenCode or any agent with a shell.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Uranio/coursmith.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://coursmith.onrender.com/install",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "coursmith": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skill"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "open": "^11.0.4"
+  },
+  "devDependencies": {
+    "@coursmith/course-schema": "0.1.0",
+    "esbuild": "^0.28.2",
+    "@types/node": "^24.0.0",
+    "vitest": "^5.0.5"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "coursmith",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "cursor",
+    "opencode",
+    "courses",
+    "e-learning"
+  ]
+}

package/skill/coursmith-course/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: coursmith-course
+description: Create an interactive course (steps, charts, diagrams, animations, images, a glossary per section and a final quiz) and publish it to the Coursmith catalog with the coursmith CLI. Use when the user asks to create, write, generate, update, publish or submit a course or lesson for Coursmith, or to check a Coursmith review.
+---
+
+# Create and publish a Coursmith course
+
+You write a course as a folder containing `course.json` and an `assets/` directory, check it with the
+`coursmith` CLI, and submit it. A review agent on the portal then approves it, asks for a revision or
+rejects it. Your job ends when the course is approved, or when you have explained the review outcome to the user.
+
+Run the CLI as `coursmith <command> --json`. It is installed from the private repository (the npm package
+`coursmith` is not published yet); if the command is missing, ask the user to follow the installation guide
+at `/install` before continuing. With `--json` every command prints one JSON document; read it instead of guessing.
+
+Reference files in this skill folder (read them when you reach the matching step):
+
+| File | Use it for |
+|---|---|
+| `references/course.schema.json` | The exact structure of `course.json`. Unknown keys are rejected. |
+| `references/block-catalog.md` | Every content block and visual, with valid JSON examples and rules. |
+| `references/animation-presets.md` | The 7 animation presets and when to use each. |
+| `references/writing-guide.md` | How to write steps, glossaries and quizzes that pass review. |
+| `references/content-policy.md` | What is not allowed and how to treat sensitive topics. |
+| `examples/sample-course/` | A complete course that passes validation. Copy its shape. |
+
+## 1. Log in
+
+1. Run `coursmith whoami --json`. If it prints a `username`, continue to step 2.
+2. Otherwise run `coursmith login --no-wait --json`. Show the user the `verificationUri` and the
+   `userCode` and ask them to open the link, check the code and click **Approve**.
+3. When the user confirms, run `coursmith login --resume --json` and check that it prints `logged_in`.
+
+## 2. Agree on the course with the user
+
+Ask, in one message, for anything the user has not already given:
+
+- **Topic** and, if useful, the angle or audience.
+- **Language** of the course (any language; you will need its BCP-47 code such as `it`, `en`, `pt-BR`).
+- **Difficulty**: `beginner`, `intermediate` or `advanced`.
+- Optional: desired length (default about 30 minutes), prerequisites, things to include or avoid.
+
+Check the topic against `references/content-policy.md`. If it is not allowed, say so and stop. If it is a
+sensitive topic (health, law, finance, politics, religion…), plan a neutral treatment and a disclaimer.
+
+## 3. Propose an outline and get it approved
+
+Show the user:
+
+- title, one-line subtitle, 2–6 learning objectives;
+- 3–6 sections, each with a one-line summary and 2–5 step titles;
+- for each step, the visual you plan (chart, diagram, animation preset, image or none);
+- the planned number of quiz questions (at least 10, covering every section).
+
+Revise until the user agrees. Do not write `course.json` before that.
+
+## 4. Write the course
+
+Create a new folder named after the course (kebab-case) with `course.json` and `assets/`. Follow
+`references/course.schema.json` exactly and copy the structure of `examples/sample-course/course.json`.
+
+Rules the validator enforces (details in `references/block-catalog.md`):
+
+- `schemaVersion` is `"1.0"`. Do not write `courseId`: the CLI manages it.
+- All ids are lowercase letters, digits and dashes, unique across the course (sections, steps, assets,
+  quiz questions).
+- Every step has a `title` and at least one block; most steps also have a `visual`.
+- **Glossary**: every section has a `glossary` that defines every concept it introduces and every technical or
+  domain term it uses. In the text, mark each term as `[[term]]`, or `[[term|text shown]]` when the
+  wording differs (use `aliases` for plurals and inflections). A marked term must be defined in the same
+  section or an earlier one. Definitions are self-contained and written in the course language.
+- **Visuals**: charts are Vega-Lite specs with inline `data.values` (no URLs); diagrams are Mermaid without
+  `click` or `%%{init}%%`; animations use one of the 7 presets; images refer to an asset by id.
+- **Markdown**: no raw HTML, no Markdown images (use an image block), links must be `https://`.
+- **Final quiz**: at least 10 questions; every section is tested by at least one question (`sectionRef`);
+  every question has an `explanation`. Types: `single`, `multiple`, `true_false`, `ordering`
+  (ordering items are listed in the correct order; the portal shuffles them).
+- Optional `check` questions at the end of a step give learners quick feedback and are not scored.
+
+Write section by section and keep the language, difficulty and terminology consistent throughout
+(see `references/writing-guide.md`).
+
+## 5. Create the assets
+
+- A **cover image** is required (`meta.coverImage`), ideally 1200×630.
+- If you have an image-generation tool, produce PNG, JPEG or WebP files. Otherwise write clean SVG by hand:
+  simple shapes, a clear palette, `viewBox` set, no scripts, no external links or fonts, no embedded images.
+- For a `highlight-svg` animation, give the elements to highlight an `id` attribute.
+- Put every file directly in `assets/` and declare it in `assets[]` with `kind` (`image` or `svg`), `file`
+  (`assets/<name>`) and a meaningful `alt` text. Fill `generatedBy` for AI-generated images.
+- Each file must be under 3 MB; the whole bundle under 25 MB.
+
+## 6. Validate until clean
+
+Run `coursmith validate <folder> --json`. It prints `{ "ok": ..., "issues": [...] }`; each issue has
+`severity`, `code`, `path` (for example `sections[1].steps[0].blocks[2]`) and `message`.
+
+Fix every `error`, then run it again. Repeat until `ok` is `true`. Fix warnings too when they are cheap
+(for example `glossary.unreferenced`: mark the term with `[[...]]` where it is used).
+
+## 7. Submit and follow the review
+
+1. Run `coursmith submit <folder> --json`. It uploads the course and prints `status: "in_review"`
+   with a `submissionId`. The CLI writes `.coursmith.json` in the folder; keep it, because it links later
+   submissions to the same course.
+2. Run `coursmith status --dir <folder> --wait --json` (it waits up to 10 minutes; run it again if
+   the status is still `in_review`).
+3. Act on the `status`:
+   - `approved`: give the user the `courseUrl`. Mention any optional suggestions in `review.issues`.
+   - `needs_revision`: for each issue in `review.issues`, open the element at `path`, apply the
+     `suggestion` (or fix what `message` describes), then validate and submit again. Tell the user what you
+     changed. Issues with `severity: "warning"` are optional.
+   - `rejected`: explain `review.summary` to the user. Do not resubmit the same content.
+
+If `submit` reports `review_in_progress`, wait for the current review with `status --wait` first.
+
+## Updating a published course
+
+Edit the same folder (keep `.coursmith.json`) and submit again. The new version goes through review while
+the current one stays online; keep step ids stable so learners keep their progress.
+
+## Troubleshooting
+
+| CLI output | What to do |
+|---|---|
+| `not_logged_in` / exit code 3 | Go back to step 1. |
+| `client_outdated` | Ask the user to update the CLI from the repository (`git pull`, rebuild, `npm install -g ./packages/cli`), then retry. |
+| `validation_failed` from `submit` | Run `validate` and fix the issues it lists. |
+| `rate_limited` | The user reached the daily submission limit; try again tomorrow. |
+| `assets.content_type` / `assets.invalid` | The file content does not match its extension, or it is corrupt. Re-export it. |
+| `animation.unknown_element` | The SVG lacks an element with that `id` (ids are kept, scripts and external links are removed). |

package/skill/coursmith-course/examples/sample-course/assets/cover.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 630" role="img" aria-labelledby="t">
+  <title id="t">Power line crossing hills toward a house</title>
+  <defs>
+    <linearGradient id="sky" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#1e3a8a"/>
+      <stop offset="1" stop-color="#3b82f6"/>
+    </linearGradient>
+  </defs>
+  <rect width="1200" height="630" fill="url(#sky)"/>
+  <circle cx="980" cy="140" r="60" fill="#fde68a"/>
+  <path d="M0 470 Q300 380 600 450 T1200 430 V630 H0Z" fill="#1e40af"/>
+  <path d="M0 520 Q350 450 700 520 T1200 500 V630 H0Z" fill="#172554"/>
+  <g stroke="#e0e7ff" stroke-width="6" fill="none" stroke-linecap="round">
+    <path d="M140 470 L180 250 L220 470 M150 320 H210 M160 280 H200"/>
+    <path d="M520 470 L560 250 L600 470 M530 320 H590 M540 280 H580"/>
+    <path d="M180 260 Q370 330 560 260" stroke-width="3"/>
+    <path d="M560 260 Q760 330 880 400" stroke-width="3"/>
+  </g>
+  <g transform="translate(860 400)">
+    <path d="M0 60 L60 10 L120 60 V140 H0Z" fill="#f8fafc"/>
+    <rect x="45" y="80" width="30" height="30" fill="#facc15"/>
+  </g>
+</svg>

package/skill/coursmith-course/examples/sample-course/assets/home-panel.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 520" role="img" aria-labelledby="t">
+  <title id="t">Home electrical panel</title>
+  <rect x="10" y="10" width="380" height="500" rx="16" fill="#f1f5f9" stroke="#334155" stroke-width="4"/>
+  <g id="meter">
+    <rect x="130" y="40" width="140" height="90" rx="8" fill="#e2e8f0" stroke="#334155" stroke-width="3"/>
+    <rect x="150" y="60" width="100" height="30" rx="4" fill="#0f172a"/>
+    <text x="200" y="82" font-family="monospace" font-size="18" fill="#4ade80" text-anchor="middle">01234</text>
+    <text x="200" y="118" font-family="sans-serif" font-size="14" fill="#334155" text-anchor="middle">kWh</text>
+  </g>
+  <path d="M200 130 V170" stroke="#334155" stroke-width="4"/>
+  <g id="main-switch">
+    <rect x="160" y="170" width="80" height="70" rx="6" fill="#fecaca" stroke="#b91c1c" stroke-width="3"/>
+    <rect x="190" y="185" width="20" height="40" rx="3" fill="#b91c1c"/>
+  </g>
+  <path d="M200 240 V280" stroke="#334155" stroke-width="4"/>
+  <g id="rcd">
+    <rect x="140" y="280" width="120" height="70" rx="6" fill="#bfdbfe" stroke="#1d4ed8" stroke-width="3"/>
+    <circle cx="230" cy="315" r="10" fill="#1d4ed8"/>
+    <rect x="160" y="295" width="20" height="40" rx="3" fill="#1d4ed8"/>
+  </g>
+  <path d="M200 350 V380 M80 380 H320 M80 380 V400 M160 380 V400 M240 380 V400 M320 380 V400" stroke="#334155" stroke-width="4" fill="none"/>
+  <g id="breakers">
+    <rect x="55" y="400" width="50" height="80" rx="5" fill="#e2e8f0" stroke="#334155" stroke-width="3"/>
+    <rect x="135" y="400" width="50" height="80" rx="5" fill="#e2e8f0" stroke="#334155" stroke-width="3"/>
+    <rect x="215" y="400" width="50" height="80" rx="5" fill="#e2e8f0" stroke="#334155" stroke-width="3"/>
+    <rect x="295" y="400" width="50" height="80" rx="5" fill="#e2e8f0" stroke="#334155" stroke-width="3"/>
+  </g>
+</svg>