Status: Draft v0.3
Date: 12 August 2026
Product name: explorables
Supported initial hosts: Codex and Claude Code Desktop
Public site: https://explorables.ai
Canonical repository: git@github.com:Doppp/explorables.git
Default branch: master
First course: AI from First Principles
Tagline: See how it works. Build it yourself.
explorablesis styled in lowercase in product copy, package names, and documentation.
explorables is a small, open-source runtime and file format for interactive technical courses that run naturally alongside agentic coding environments. Its initial host integrations target Codex and Claude Code Desktop.
A course is a normal folder containing:
- Plain Markdown lessons
- TypeScript explorable modules
- Optional programming exercises and tests
- Static assets
- An Agent Plugins v1 manifest and portable
start-courseAgent Skill - An
AGENTS.mdfile that tells Codex how to act as the course tutor
A learner clones or downloads the folder, opens it in Codex or Claude Code Desktop, and says:
Start this course.
The coding agent reads the repository guidance, starts the local course runtime, opens the rendered course in its browser or preview pane, and helps the learner work through the material. The browser provides graphics, simulations, visual explanations, and direct manipulation. The host coding environment provides the conversational tutor, repository, editor, terminal, and test runner.
There is no account, login, hosted learner database, central progress system, certificate system, audio system, or learning-management system in the first version. A small public landing page is built from the same repository and deployed as a static GitHub Pages site at explorables.ai.
The architecture is intentionally small:
Course folder
├── Markdown lessons
├── TypeScript explorables
├── Exercises and tests
└── AGENTS.md
│
▼
`explorables` runtime
├── Markdown renderer
├── Explorable sandbox
├── Exercise launcher
└── Local web server
│
▼
Agentic coding desktop
├── Codex or Claude Code tutor and coding workspace
└── Built-in browser or preview-pane course interface
Public web
└── Static landing page at explorables.ai
The first reference course, AI from First Principles, is inspired by the idea that developers should use LLMs as tools while deliberately acquiring the underlying knowledge themselves. It teaches machine learning, neural networks, language models, transformers, open-weight models, evaluation, adaptation, and practical contribution paths.
Technical learning should happen in the same environment where the learner can:
- Inspect a real implementation
- Change a variable and immediately see what happens
- Write code
- Run tests
- Ask questions
- Debug failures
- Build a complete project
Most online courses separate these activities across videos, notebooks, quizzes, browser IDEs, and local repositories. explorables treats them as one continuous experience.
The learner sees and manipulates a concept in the built-in browser, then works with its implementation in the adjacent Codex project.
Understand visually → predict → manipulate → implement → debug → explain
explorables is not intended to be a general-purpose LMS. It is an open course format for hands-on, explorable technical education.
The source repository is the complete distributable course.
It contains all prose, code, assets, exercises, tests, and instructions required to run the course. A course can be forked, reviewed, translated, versioned, and submitted through normal open-source workflows.
Course authors write ordinary Markdown with YAML frontmatter and a very small set of optional directives.
explorables does not use MDX as the canonical course format. Course prose should remain readable on GitHub and usable without the explorables runtime.
Interactive parts are authored as TypeScript modules that compile to browser JavaScript.
The course Markdown imports them declaratively:
:::explorable{src="../explorables/loss-surface/index.ts" height="520"}
A text alternative describing the explorable.
:::Every distributable explorables course conforms to Agent Plugins v1. The course root contains plugin.json, and skills/start-course/SKILL.md provides the portable entry workflow using the Agent Skills format. Agent Plugins is a packaging and discovery layer; it does not replace COURSE.md, the runtime, or the explorable sandbox.
explorables keeps the canonical teaching policy in AGENTS.md. The portable skill reads and follows that policy rather than duplicating it. Codex can still read AGENTS.md directly. Claude Code Desktop reads the thin CLAUDE.md adapter and may also discover the portable skill when its plugin support allows.
The canonical instructions define:
- How to launch the course
- How the coding agent should teach
- Which files contain lesson content
- When the agent may give hints
- Which assignments it must not solve for the learner
- How to run tests
The plugin manifest and portable skill are required distribution adapters for first-party and newly scaffolded courses. Client-specific extensions remain optional and must not fork course content or teaching policy.
The first version has:
- No accounts
- No login
- No learner database
- No analytics
- No remote submissions
- No server-side rendering
- No required cloud service
The local filesystem and Git history already contain meaningful evidence of completed programming work.
Audio is deliberately excluded to keep the runtime, contribution process, and authoring model focused.
It can later be added as an optional asset type without changing the core course format.
The repository contains a small static site under apps/site.
It introduces the project, explains how courses work, features the first course, links to the authoring guide, and directs visitors to the GitHub repository.
The site:
- Is built with the existing TypeScript, React, and Vite stack
- Requires no backend
- Contains no analytics in v1
- Is deployed through GitHub Actions to GitHub Pages
- Uses the custom domain
explorables.ai - Keeps all deployment configuration version controlled
- Remains separate from the local course runtime
GitHub Pages configuration and custom-domain setup must follow current official GitHub documentation. A CNAME asset alone is not treated as sufficient configuration; the repository Pages settings or API must also be configured.
The best initial experiences are in Codex and Claude Code Desktop because both combine a coding workspace with a browser or preview surface.
However, a explorables course is still a normal web project. The same course can later run in:
- A normal browser
- Another coding agent
- A static hosted site
- A classroom environment
- A future ChatGPT app
- Other coding-agent desktops with a local preview surface
The course format must not require private Codex or Claude APIs.
A repository may contain explorables.library.json to present an ordered local learning path across multiple self-contained course packages. The manifest is an explicit allowlist of relative course roots; it is not a hosted catalogue, filesystem scan, marketplace, or remote installer.
The collection interface may also show clearly labelled planned courses so the curriculum path is visible. Planned entries cannot be opened. Every available course remains independently valid and runnable with its own COURSE.md, Agent Plugin manifest, portable skill, host adapters, exercises, and version.
The model-learning collection is structured as a vendor-neutral foundation, a shared frontier-research course, and separately versioned model-family case studies. Foundation lessons may include brief real-model connections in ordinary Markdown; release-specific reconstruction belongs in the appropriate case-study course.
explorables should:
- Let a technical author create a course by writing Markdown and TypeScript.
- Let contributors submit courses and improvements through GitHub pull requests.
- Run a complete course locally with one install command.
- Render interactive visual explanations in the Codex built-in browser.
- Let learners move naturally between the browser and real project code.
- Give Codex enough repository guidance to act as a tutor rather than an answer generator.
- Keep course packages understandable without the runtime.
- Support reusable explorable modules and shared component libraries.
- Validate course structure, links, imports, accessibility, and exercises in CI.
- Make the first course a credible path from ordinary software development into AI and LLM engineering.
- Publish a clear static landing page at
explorables.aifrom the same repository. - Make repository creation, builds, tests, releases, and site deployment reproducible through normal GitHub workflows.
explorables will not initially provide:
- User accounts
- Cross-device progress
- Certificates
- Payments
- Cohort administration
- Instructor dashboards
- Central grading
- Hosted code execution
- Cloud GPUs
- A drag-and-drop course editor
- Arbitrary third-party plugins loaded without review
- Audio generation
- Mobile-first delivery
- Support for every educational subject
- A proprietary course marketplace
- A marketing CMS or dynamic website backend
The initial learner:
- Has basic computer science knowledge
- Can read and modify code
- Has built a small web application or equivalent software project
- Uses coding agents but wants deeper technical ownership
- Is comfortable opening a repository
- Wants to understand systems rather than only use abstractions
The initial course author:
- Is comfortable with Markdown
- Can write or review TypeScript
- Understands the subject being taught
- Wants to publish through GitHub
- Prefers course-as-code over a visual LMS
The explorable contributor:
- Builds reusable visual or interactive components
- May contribute without writing an entire course
- Uses TypeScript, DOM, SVG, Canvas, WebGL, or a supported UI adapter
The exercise contributor:
- Creates starter code, fixtures, tests, and reference solutions
- Can improve course depth without touching the visual runtime
A learner can clone a course repository:
git clone https://github.com/example/ai-from-first-principles.git
cd ai-from-first-principles
pnpm install --frozen-lockfileThey open the folder in Codex or Claude Code Desktop and type:
Start the course.
A conforming Agent Plugins client discovers plugin.json and the portable start-course skill. Codex can also read AGENTS.md directly, while Claude Code Desktop uses CLAUDE.md. The host runs the documented start command and opens the local course URL in its built-in browser or preview pane.
A direct terminal path also exists:
pnpm course
pnpm site:devThe intended desktop experience is:
┌───────────────────────────┬────────────────────────────────────┐
│ Codex or Claude Code │ Browser or preview pane │
│ │ │
│ Tutor conversation │ Course prose │
│ Repository files │ Interactive visualisation │
│ Code changes │ Controls and direct manipulation │
│ Terminal and tests │ Exercise instructions │
│ │ │
└───────────────────────────┴────────────────────────────────────┘
The browser or preview pane is the primary reading and interaction surface. The coding-agent workspace is the primary tutoring and implementation surface.
A lesson should usually follow this sequence:
- Encounter — show a phenomenon before fully explaining it.
- Predict — ask the learner what they think will happen.
- Manipulate — let the learner alter the system.
- Inspect — reveal internal values, state, or execution.
- Explain — introduce the underlying concept.
- Implement — ask the learner to write a focused piece of code.
- Debug — provide a broken system or failed test.
- Transfer — apply the idea in a different situation.
These stages are pedagogical guidance, not mandatory runtime primitives. Most can be written as ordinary Markdown around one or two interactive embeds.
Every course start surface must explain how to leave and return without relying on a learner to know host-specific commands. The runtime and host adapters use these meanings consistently:
- Start this course starts at the beginning when no saved progress exists and otherwise offers to resume it.
- Resume this course opens the saved lesson and, for a guided course, its first incomplete checkpoint.
- Pause this course or End this session preserves progress and lets the host stop the local course process. Direct-terminal learners use
Ctrl+C. - Review lesson name revisits an unlocked lesson without changing guided completion.
- Restart from checkpoint name requires confirmation and clears that checkpoint and all later guided progress.
- Explore lesson name uses Explore mode without moving the saved Guided position.
- Reset this course requires confirmation and clears all local progress.
- Finish the course means completing the final required checkpoint; it is not a synonym for pausing or resetting.
If a learner says the ambiguous phrase End the course, the host asks whether they mean pause the current session or reset progress. It must not erase state or claim completion by inference.
The public site at explorables.ai explains the project before a visitor clones a course.
It is not the hosted course player and it does not track learning. It is a lightweight entry point to the open-source project.
The v1 site may be a single page with anchored sections:
-
Hero
- Product name:
explorables - A concise explanation of the idea
- Primary action: view the first course
- Secondary action: view the GitHub repository
- Product name:
-
How it works
- Read and manipulate lessons in the browser or preview pane
- Work on real exercises in the coding-agent workspace
- Use the agent as a tutor rather than a substitute
-
First course
- AI from First Principles
- Intended audience
- Main topics
- Link to its repository directory or release
-
Create a course
- Markdown lessons
- TypeScript explorables
- Exercises and tests
- Link to
docs/course-authoring.md
-
Open source
- Licence
- Contribution link
- Repository link
-
Footer
- GitHub
- Documentation
- Licence
- No tracking statement
The landing page should be:
- Simple and technical
- Fast to load
- Responsive
- Keyboard accessible
- Usable in light and dark mode
- Free of stock photography
- Free of unnecessary animation
- Free of cookie banners because v1 uses no analytics or tracking
- Visually consistent with the local course runtime
Recommended location:
apps/
└── site/
├── index.html
├── src/
├── public/
│ └── CNAME
└── vite.config.ts
The CNAME file contains:
explorables.ai
The site uses React and Vite already present in the monorepo. It should not introduce another frontend framework solely for the landing page.
A workflow under .github/workflows/pages.yml should:
- Run on pushes to
master. - Install the pinned Node and pnpm versions.
- Install dependencies from the lockfile.
- Run relevant validation and tests.
- Build
apps/site. - Upload the static artifact.
- Deploy it with GitHub Pages.
The workflow must use GitHub's current official Pages actions and least-privilege permissions.
The repository must be configured to publish through GitHub Actions. The custom domain should be configured in GitHub Pages settings or through the GitHub API. DNS changes outside GitHub should be documented when the agent cannot perform them.
pnpm site:devstarts the site locally.pnpm site:buildcreates a static artifact.- The artifact contains the custom-domain file.
- Links to documentation and the repository work.
- The site passes automated accessibility checks.
- The site deploys from
masterthrough GitHub Actions. https://explorables.aiis the intended production URL.- No application backend or tracking service is required.
A minimal course contains:
my-course/
├── README.md
├── AGENTS.md
├── CLAUDE.md
├── COURSE.md
├── plugin.json
├── package.json
├── pnpm-lock.yaml
├── skills/
│ └── start-course/
│ └── SKILL.md
└── lessons/
└── 01-introduction.md
my-course/
├── README.md
├── AGENTS.md
├── CLAUDE.md
├── COURSE.md
├── plugin.json
├── LICENSE
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json
├── explorables.config.ts
│
├── skills/
│ └── start-course/
│ └── SKILL.md
│
├── .claude/
│ └── launch.json
│
├── lessons/
│ ├── 01-introduction.md
│ ├── 02-core-concept.md
│ └── 03-project.md
│
├── explorables/
│ ├── loss-surface/
│ │ ├── index.ts
│ │ ├── styles.css
│ │ ├── index.test.ts
│ │ └── README.md
│ └── attention-map/
│ └── index.ts
│
├── exercises/
│ ├── gradient-descent/
│ │ ├── README.md
│ │ ├── starter/
│ │ ├── tests/
│ │ └── solution/
│ └── attention/
│ └── ...
│
├── assets/
│ ├── images/
│ └── data/
│
├── shared/
│ ├── components/
│ └── utilities/
│
└── .github/
└── workflows/
└── validate-course.yml
README.md is for humans browsing the repository.
It should include:
- Course description
- Intended audience
- Prerequisites
- Installation
- How to start
- Course licence
- Contribution instructions
- Estimated time commitment
AGENTS.md is for Codex and other compatible coding agents.
It should remain concise and operational. It should not contain the entire course.
Example:
# Course repository instructions
This repository contains an interactive course.
## Start the course
1. Run `pnpm install` if dependencies are missing.
2. Run `pnpm course`.
3. Open the printed local URL in the built-in browser.
4. Read `COURSE.md` to understand the course order.
## Tutoring behaviour
- Teach through questions, prediction, inspection, and debugging.
- Do not complete the central exercise implementation for the learner.
- Give the smallest useful hint first.
- Refer to the current lesson and rendered explorable.
- Run tests when the learner asks or after they make an attempt.
- Ask the learner to explain a working solution before moving on.
- Do not modify files under `exercises/**/solution/`.
- Do not reveal hidden or reference solutions.
## Course navigation
- Lessons are ordered in `COURSE.md`.
- When the learner says “continue”, identify the current lesson from
the open browser page and working files.
- When a lesson references an exercise, read that exercise’s README.CLAUDE.md is the thin Claude Code Desktop adapter.
It should import or restate the canonical repository teaching policy from AGENTS.md and add only Claude-specific operational guidance.
Example:
@AGENTS.md
# Claude Code Desktop
- Use the Browser or Preview pane for lessons and explorables.
- Use the file and terminal panes for programming exercises.
- Start the local course using `.claude/launch.json` when available.
- Keep the course preview beside the conversation where practical.If the host does not support importing another instruction file, the generated course template may duplicate the short canonical policy with a generated warning that AGENTS.md remains the source of truth.
Official courses should include a Claude preview configuration:
{
"version": "0.0.1",
"configurations": [
{
"name": "explorables-course",
"runtimeExecutable": "pnpm",
"runtimeArgs": ["course"],
"port": 4173,
"autoPort": true
}
]
}The exact schema must be verified against the current Claude Code Desktop documentation during implementation.
Every course includes:
skills/
└── start-course/
└── SKILL.md
This Agent Skills component is discovered from the fixed Agent Plugins v1 location. It resolves the plugin root, reads AGENTS.md and COURSE.md, starts the runtime, and applies the canonical policy. It must remain concise and must not duplicate lesson content or protected solutions.
COURSE.md is the course entry point.
It uses YAML frontmatter followed by normal Markdown.
Example:
---
id: ai-from-first-principles
title: AI from First Principles
version: 0.1.0
summary: Learn modern AI by seeing, implementing, and debugging its machinery.
audience:
- software developers
- computer science graduates
estimatedHours: 100
license: CC-BY-4.0
---
# AI from First Principles
This course develops practical understanding of machine learning,
language models, and open-weight model systems.
## Outcomes
By the end of the course, you should be able to:
- implement core machine-learning operations
- explain and implement backpropagation
- build a tokenizer and small language model
- implement self-attention and a decoder-only transformer
- evaluate and adapt an open-weight model
- choose a credible route into AI engineering or open-source contribution
## Lessons
1. [How machines learn](lessons/01-how-machines-learn.md)
2. [Gradient descent](lessons/02-gradient-descent.md)
3. [Backpropagation](lessons/03-backpropagation.md)
4. [Tokenisation](lessons/04-tokenisation.md)
5. [Self-attention](lessons/05-self-attention.md)
6. [Open-weight models](lessons/06-open-weight-models.md)
7. [Evaluation](lessons/07-evaluation.md)
8. [What next](lessons/08-what-next.md)| Field | Type | Purpose |
|---|---|---|
id |
string | Stable machine-readable course identifier |
title |
string | Display name |
version |
semver string | Course package version |
summary |
string | Short description |
license |
SPDX or content licence string | Reuse terms |
| Field | Type |
|---|---|
audience |
string array |
prerequisites |
string array |
estimatedHours |
number |
authors |
object array |
repository |
URL |
language |
BCP-47 string |
tags |
string array |
A lesson must be useful as plain Markdown.
The runtime adds interactivity, but the source should still communicate:
- What is being taught
- What the learner should do
- What the fallback explanation is
- Which exercise is associated with the lesson
---
id: gradient-descent
title: Gradient Descent
order: 2
objectives:
- explain what a gradient represents
- predict the effect of changing a learning rate
- implement a gradient update
prerequisites:
- derivatives
- loss-functions
---Only id and title are required.
explorables v1 should support only two course-specific block directives:
explorableexercise
Everything else is ordinary Markdown.
:::explorable{src="../explorables/loss-surface/index.ts" height="520"}
Use the controls to change the learning rate and observe the optimiser.
A text-only alternative should appear here.
:::Supported attributes:
| Attribute | Required | Description |
|---|---|---|
src |
Yes | Relative path to the TypeScript module |
height |
No | Suggested rendered height |
title |
No | Accessible title |
config |
No | Relative JSON configuration file |
id |
No | Stable instance identifier |
:::exercise{path="../exercises/gradient-descent"}
Implement one update step and run the supplied tests.
:::Supported attributes:
| Attribute | Required | Description |
|---|---|---|
path |
Yes | Relative path to the exercise |
command |
No | Override test command |
title |
No | Display title |
Prediction prompts, explanations, reflections, warnings, and checkpoints do not require custom runtime types. Authors can express them with headings, block quotes, lists, and normal prose.
New directives should be introduced only when the runtime must perform behaviour that cannot be represented through Markdown or an explorable module.
Explorables are authored in TypeScript 7.0 and compiled into browser JavaScript.
The runtime shell may use React, but the course module contract is framework-neutral. An author can use:
- Vanilla DOM
- SVG
- Canvas
- D3
- Three.js
- A React adapter
- Another reviewed browser library
export type ExplorableValue =
| null
| boolean
| number
| string
| ExplorableValue[]
| { [key: string]: ExplorableValue };
export interface ExplorableExperimentRecord {
label?: string;
inputs: Record<string, null | boolean | number | string>;
outputs: Record<string, null | boolean | number | string>;
summary?: string;
}
export interface ExplorableContext {
instanceId: string;
lessonId: string;
config: ExplorableValue;
emit(event: ExplorableEvent): void;
recordExperiment(record: ExplorableExperimentRecord): void;
}
export interface ExplorableEvent {
type: string;
payload?: ExplorableValue;
}
export interface ExplorableHandle {
destroy?(): void;
resize?(width: number, height: number): void;
}
export interface ExplorableModule {
mount(
root: HTMLElement,
context: ExplorableContext,
): ExplorableHandle | Promise<ExplorableHandle>;
}An explorable exports a default object:
import type { ExplorableModule } from "@explorables/explorable";
const module: ExplorableModule = {
mount(root, context) {
// Render and attach event listeners.
return {
destroy() {
root.replaceChildren();
},
};
},
};
export default module;import type { ExplorableModule } from "@explorables/explorable";
const explorable: ExplorableModule = {
mount(root, context) {
const wrapper = document.createElement("section");
const label = document.createElement("label");
const slider = document.createElement("input");
const output = document.createElement("output");
label.textContent = "Learning rate";
slider.type = "range";
slider.min = "0.01";
slider.max = "2";
slider.step = "0.01";
slider.value = "0.1";
const render = () => {
const value = Number(slider.value);
output.value = value.toFixed(2);
context.emit({
type: "learning-rate-changed",
payload: { value },
});
};
slider.addEventListener("input", render);
label.append(slider, output);
wrapper.append(label);
root.append(wrapper);
render();
return {
destroy() {
slider.removeEventListener("input", render);
root.replaceChildren();
},
};
},
};
export default explorable;Events are local and ephemeral in v1.
They allow:
- The runtime to update visible state
- One explorable to communicate with its wrapper
- Codex to inspect browser state when useful
- Tests to assert expected behaviour
They are not sent to a remote analytics service.
Recommended event conventions:
prediction-submitted
parameter-changed
simulation-started
simulation-completed
exercise-opened
state-reset
Every explorable must:
- Be operable by keyboard
- Use native controls where practical
- Have a visible title or accessible label
- Provide a text alternative in the Markdown directive body
- Avoid using colour as the only meaning
- Respect reduced-motion preferences
- Expose important dynamic output through
aria-live - Resize down to a narrow desktop panel
- Avoid trapping focus
Each explorable should include:
- Unit tests for the underlying model or calculation
- A mount/unmount smoke test
- At least one interaction test
- An accessibility check
- A browser screenshot or visual regression test for first-party courses
Courses may use @explorables/model-atlas when spatial structure materially helps a learner understand repeated blocks, routing, residual paths, caches, or differences between model families. The Atlas is an explorable module, not a new Markdown directive or lesson language.
Every Atlas descriptor is inert versioned data. Each stage identifies its evidence as executable, configuration-derived, report-derived, conceptual, or undisclosed and references a reviewed source revision. Exact tensor traces are separate and may come only from tested teaching code or committed deterministic fixtures. A convincing scene must never turn a conceptual aggregation, candidate source, or proprietary gap into an architecture claim.
The 3D canvas is progressive enhancement. The same learning task must remain available through native stage controls, a semantic outline, provenance text, comparison tables, and exact tensor tables where a trace exists. WebGL failure or context loss falls back to this representation. Large model counts are aggregated within validated scene budgets; production weights, runtime downloads, remote assets, analytics, and new iframe permissions are not required.
The first reference Atlas covers the deterministic tiny Transformer, published GPT-1/2/3 configurations, GPT-4's explicit disclosure boundary, and source-gated candidate mechanism views for DeepSeek V4, Kimi K3, Qwen 3, MiniMax M1, and GLM 5.2. Candidate family views omit unfrozen numerical topology until their course-local source and licence gates are complete.
Open-source courses can contain executable browser code. explorables must treat course code as untrusted by default.
Each explorable is bundled into a self-contained browser artifact and loaded inside a sandboxed iframe.
Recommended iframe permissions:
<iframe sandbox="allow-scripts"></iframe>Do not grant allow-same-origin by default.
The explorable iframe should use a restrictive CSP resembling:
default-src 'none';
script-src 'unsafe-inline' blob:;
style-src 'unsafe-inline';
img-src data: blob:;
font-src data:;
connect-src 'none';
media-src 'none';
frame-src 'none';
Network access must be opt-in and unavailable for courses accepted into the official catalogue unless explicitly reviewed.
The runtime owns the build configuration. Courses may not provide arbitrary Vite configuration files that execute during startup.
Explorable dependencies are bundled before loading into the iframe. Runtime imports from arbitrary external CDNs are not allowed in official courses.
The reference implementation defaults to pnpm 11 with a committed lockfile and maintains backward compatibility with pnpm 10.26.0 and newer 10.x releases.
Course dependencies must:
- Be pinned through the lockfile
- Avoid unreviewed lifecycle scripts
- Use an explicit build-script allowlist
- Pass dependency audit checks in CI
- Be reviewed when introduced to an official course
Exercises are never automatically executed merely because a lesson is opened.
Codex or the learner must deliberately run the documented command. Exercises that execute untrusted code should use an appropriate container or local sandbox.
explorables should distinguish:
- First-party course — maintained by the core project.
- Reviewed community course — accepted into the official catalogue after review.
- External compatible course — runnable from another repository with a warning.
- Local private course — authored and run locally.
exercises/
└── gradient-descent/
├── README.md
├── exercise.json
├── starter/
│ └── gradient.ts
├── tests/
│ └── gradient.test.ts
└── solution/
└── gradient.ts
solution/ may be omitted from public learner distributions or encrypted/kept in an instructor branch.
{
"id": "gradient-descent-step",
"title": "Implement one gradient descent step",
"language": "typescript",
"starter": "starter",
"testCommand": "pnpm vitest run tests/gradient.test.ts",
"estimatedMinutes": 30,
"centralFiles": ["starter/gradient.ts"],
"protectedPaths": ["solution"]
}A good exercise should:
- Test one or two central ideas
- Have a clear stopping condition
- Provide deterministic tests where possible
- Include edge cases
- Avoid large amounts of unrelated boilerplate
- Make the learner inspect failures
- Require a short explanation after tests pass
The course AGENTS.md should prohibit Codex from filling in the central implementation before the learner attempts it.
Codex may:
- Explain an error
- Point to a relevant function
- Run tests
- Suggest a smaller analogous example
- Provide progressively stronger hints
- Review the learner’s implementation
Codex should not:
- Copy the reference solution
- Replace the learner’s implementation wholesale
- silently complete a central assignment
- claim understanding merely because tests pass
The explorables runtime performs only the following:
- Locate and parse
COURSE.md. - Parse lesson Markdown and frontmatter.
- Render standard Markdown.
- Resolve
explorableandexercisedirectives. - Bundle explorable TypeScript modules.
- Load each explorable in a sandboxed iframe.
- Render course navigation.
- Serve static assets.
- Validate the course package.
- Provide development errors with file and line references.
- For courses that opt in, present guided checkpoints, ordered navigation, explicit skip/Explore controls, and local resume state.
It does not teach the subject itself. The course content and Codex instructions do that.
Course repository
┌────────────────────────┐
│ COURSE.md │
│ lessons/*.md │
│ explorables/*.ts │
│ exercises/* │
│ assets/* │
└────────────┬───────────┘
│
▼
┌────────────────────────┐
│ `explorables` compiler │
│ │
│ Markdown pipeline │
│ Frontmatter validation │
│ Directive resolver │
│ Explorable bundler │
└────────────┬───────────┘
│
▼
┌────────────────────────┐
│ Local course server │
│ │
│ React course shell │
│ Lesson navigation │
│ Sandboxed iframes │
│ Exercise links │
└────────────┬───────────┘
│
▼
Codex or Claude Code Desktop browser/preview
Courses may opt into Guided Course Mode in COURSE.md. A guided lesson declares ordered checkpoints completed either by an explicit learner acknowledgment or by a named event from a named explorable instance. The runtime does not auto-run exercises and does not claim to verify a learner's conversation, understanding, or test result.
Guided mode keeps future lessons visible but locked until the active lesson is completed or explicitly skipped. When enabled by the course, the learner may enter Explore mode after a clear confirmation and access lessons freely. Returning to Guided mode restores the prior guided position.
Optional resume state is stored in the main document's browser localStorage, never inside an explorable iframe. It is:
- Opt-in per course
- Namespaced by course ID, course version, schema version, and browser profile
- Local only, resettable, and resilient to malformed or stale values
- Non-essential to course completion
- Free of accounts, analytics, remote synchronization, and server-side state
All courses may remember the last visited lesson. Guided courses additionally remember checkpoint completion, skips, Guided/Explore mode, and parked questions. On startup the runtime presents a course-session screen that shows whether progress exists, the saved lesson/checkpoint, the last-saved time, and the standard learner phrases for pausing, resuming, reviewing, exploring, restarting, and resetting.
Resume is guaranteed only for the same course version, browser profile, and web origin. The local development command therefore uses a stable strict port by default and reports a conflict instead of silently moving the course to a new origin. A different browser profile, device, explicit port, cleared site data, or course version has a separate progress record. The runtime must state these limits and warn visibly when browser persistence is unavailable.
The local state may contain checkpoint IDs, skips, the active lesson, mode, a learner-authored question parking lot, bounded prediction/reflection responses, and bounded experiment records. It must not contain exercise solutions or hidden assessment data. Learner-authored work remains local, resettable, and ungraded.
A course or individual lesson may opt into a discovery cycle. Discovery lessons declare ordered prediction, experiment, application, and reflection checkpoint phases. Prediction and reflection may capture a bounded local text response. An experiment completes only after a meaningful interaction emits a structured experiment record; initial render never completes it.
The runtime may show saved runs and compare a selected baseline with the latest evidence. Experiment payloads contain bounded scalar input/output fields. The main runtime validates and stores them; explorable iframes receive no browser storage access. These learning artifacts support reflection but are not proof of understanding, assessment results, analytics, or remote submissions.
| Area | Choice |
|---|---|
| Language | TypeScript 7.0 |
| Runtime | Node.js 24 LTS default; Node.js 22.22.2+ compatible |
| Package manager | pnpm 11 default; pnpm 10.26.0+ compatible |
| Monorepo | pnpm workspaces |
| Dev server and bundling | Vite |
| Runtime UI shell | React |
| Markdown | unified, remark, rehype |
| Directives | remark-directive |
| Frontmatter | gray-matter or remark-frontmatter |
| Schema validation | Zod |
| Code highlighting | Shiki |
| Formatting and linting | Biome |
| Unit tests | Vitest |
| Browser tests | Playwright |
| Accessibility tests | axe-core |
| Optional visualisation | D3, SVG, Canvas |
| CI | GitHub Actions |
| Release | npm packages and GitHub releases |
TypeScript 7 is a native compiler and language service. At release, some ecosystems requiring TypeScript language-service plugins, including MDX and Astro, still needed to remain on TypeScript 6 for parts of their editor integration.
Plain Markdown avoids making the course format dependent on those plugin paths. The runtime parses Markdown itself and loads TypeScript explorables through an explicit directive.
This also improves:
- GitHub readability
- Portability
- Security review
- Diff quality
- Separation between prose and executable code
The repository should pin TypeScript 7 in the root package.json and lockfile.
{
"devDependencies": {
"typescript": "^7.0.0"
}
}Use:
pnpm tsc --noEmitfor type checking.
The project should not depend on custom TypeScript language-service plugins in v1.
Use Node.js 24 LTS as the default for production and deployment CI. Also test and support Node.js 22 from 22.22.2 onward while that release line remains LTS. The lower bound follows the strictest dependency in the committed lockfile; older Node.js 22 releases are not supported.
A .node-version file should pin the supported major version:
24
Use pnpm 11 by default and keep the committed lockfile installable with pnpm 10.26.0 and newer 10.x releases. The pnpm 10 lower bound is the first release with the workspace's allowBuilds setting. Both supported majors provide:
- Strong workspace support
- Reproducible lockfiles
- Efficient shared storage
- Safer dependency installation defaults
- Explicit control over dependency build scripts
explorables/
├── README.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── LICENSE
├── package.json
├── pnpm-workspace.yaml
├── pnpm-lock.yaml
├── tsconfig.base.json
├── biome.json
│
├── packages/
│ ├── cli/
│ │ └── src/
│ ├── course-schema/
│ │ └── src/
│ ├── markdown/
│ │ └── src/
│ ├── runtime/
│ │ └── src/
│ ├── explorable-sdk/
│ │ └── src/
│ ├── model-atlas/
│ │ └── src/
│ ├── sandbox/
│ │ └── src/
│ ├── validator/
│ │ └── src/
│ └── create-course/
│ └── src/
│
├── apps/
│ ├── site/
│ ├── dev-preview/
│ └── component-gallery/
│
├── templates/
│ └── basic-course/
│
├── examples/
│ ├── minimal-course/
│ └── ai-from-first-principles/
│
└── .github/
└── workflows/
- Public landing page for
explorables.ai - Static Vite build
- Links to the course, authoring guide, and repository
- GitHub Pages custom-domain asset
- No runtime dependency on the course server
Commands:
explorables start [path]
explorables validate [path]
explorables test [path]
explorables build [path]
explorables new <name>Zod schemas and TypeScript types for:
- Course frontmatter
- Lesson frontmatter
- Directive attributes
- Exercise manifests
- Runtime configuration
- Markdown parsing
- Frontmatter extraction
- Directive transformation
- Link resolution
- Sanitisation
- Course shell
- Lesson navigation
- Error UI
- Exercise launcher
- Browser rendering
- Explorable interfaces
- Event protocol
- Test utilities
- Optional adapters
- Inert architecture-descriptor and deterministic-trace schemas
- Evidence and reviewed-source boundaries
- Bounded Three.js rendering behind the explorable contract
- Semantic stage, tensor, fallback, and comparison representations
- Deterministic WebGL/resource lifecycle
- Bundling
- Iframe creation
- CSP
postMessagebridge- Error isolation
- Structural validation
- Broken links
- Missing files
- Duplicate IDs
- Import validation
- Accessibility linting
- Exercise command validation
Scaffolds a new course from the reference template.
Every course submitted to the official catalogue must include AGENTS.md.
It is the canonical host-neutral teaching and operational policy for the repository.
It defines:
- Start commands
- Tutoring behaviour
- Course routing
- Protected solution paths
- Test instructions
Every course also includes a root Agent Plugins v1 plugin.json and a portable skills/start-course/SKILL.md. The skill delegates teaching policy to AGENTS.md; the manifest supplies portable identity and discovery metadata.
Codex uses AGENTS.md directly.
When asked to start the course, Codex should:
- Read
COURSE.md. - Verify dependencies.
- Run
pnpm course. - Open the local URL in the built-in browser.
- Introduce the first lesson.
- Ask the learner to interact with the page rather than summarising the entire course.
- Move into exercise files only when referenced by the current lesson.
Codex may activate the portable start-course skill or use AGENTS.md directly. Both paths must produce the same course behavior.
Claude Code Desktop uses:
CLAUDE.md
.claude/launch.json
CLAUDE.md should reference the canonical policy in AGENTS.md and add only Claude-specific instructions.
When asked to start the course, Claude Code Desktop should:
- Read
CLAUDE.mdandCOURSE.md. - Start the preview using
.claude/launch.jsonorpnpm course. - Open the local course in the Browser or Preview pane.
- Keep the preview beside the conversation where practical.
- Use file and terminal panes for exercises.
- Apply the same tutoring restrictions as Codex.
Claude may activate the same portable skills/start-course/SKILL.md when its Agent Plugins integration supports it; .claude/launch.json remains a thin preview adapter.
When the learner says “continue”, the host should infer the current location from:
- The page open in the browser or preview pane
- The last discussed lesson
- Modified exercise files
- The course order in
COURSE.md
No remote progress record is needed.
The host must also honor the course-session language in section 6.4. Pausing flushes local browser progress before the host stops the local process. Reviewing does not roll progress back. Restarting from a checkpoint and resetting the course require explicit confirmation. Host conversation history may supplement the runtime state but is never the authoritative progress record.
Host-specific files must remain thin wrappers.
The following remain host-neutral:
COURSE.md
lessons/
explorables/
exercises/
assets/
explorables must not depend on:
- Private Codex browser APIs
- Private Claude browser APIs
- ChatGPT Apps SDK
- Claude-specific DOM bridges
- Provider-managed learner state
- A particular model vendor
The host needs only to:
- Start a local command.
- Open localhost.
- Read repository files.
- Run exercise commands.
- Discuss the learner's work.
The canonical repository is:
git@github.com:Doppp/explorables.git
It is a public open-source repository and uses master as its default branch.
Repository automation and documentation must assume:
owner: Doppp
repository: explorables
default branch: master
remote: git@github.com:Doppp/explorables.git
Do not use main in workflows, examples, or branch filters unless documenting compatibility with forks.
The implementation agent is authorised to create the repository when:
- GitHub CLI is installed
- The active GitHub account has permission to create repositories under
Doppp gh auth statussucceeds- A repository with that name does not already exist
It must never force-push or overwrite unrelated history. If the repository already exists, it must inspect and preserve its history.
Maintained in the main organisation and held to the full review standard.
Hosted in independent repositories and listed in a static official catalogue after review.
Users can run any repository conforming to the format:
pnpm dlx @explorables/cli start ./path-to-courseor:
pnpm dlx @explorables/cli start https://github.com/author/courseRemote repository support should download into an explicit temporary directory and display a trust warning before dependency installation.
A catalogue can be a normal Git repository:
explorables-catalogue/
├── catalogue.json
├── README.md
└── courses/
├── ai-from-first-principles.json
└── coding-agents.json
No catalogue backend is required.
Example entry:
{
"id": "ai-from-first-principles",
"title": "AI from First Principles",
"repository": "https://github.com/explorables-courses/ai-from-first-principles",
"version": "1.0.0",
"authors": ["explorables contributors"],
"license": "CC-BY-4.0",
"reviewed": true
}Contributors can submit:
- A complete course
- A new lesson
- An explorable
- An exercise
- A translation
- A correction
- Accessibility improvements
- Tests
- Documentation
CI should verify:
- Course schema validity
- Lesson IDs are unique
- All lesson links resolve
- All explorable imports build
- No forbidden network access
- Tests pass
- Starter exercises fail the intended tests
- Reference solutions pass
- Accessibility checks pass
- Licence metadata exists
- No solution files are exposed unintentionally
A course can remain in the author’s repository.
Being listed in the catalogue should not require transferring ownership to the core project. The catalogue points to a tagged, immutable release.
Recommended defaults:
| Material | Suggested licence |
|---|---|
| Runtime code | Apache-2.0 |
| Explorable code | Apache-2.0 |
| Course prose | CC-BY-4.0 |
| Exercise starter code | Apache-2.0 |
| Reference solutions | Author’s choice; may remain private |
| Third-party assets | Original licence, documented |
Run:
pnpm dlx create-explorables-course my-course
cd my-course
pnpm install
pnpm courseThe template creates:
my-course/
├── README.md
├── AGENTS.md
├── CLAUDE.md
├── COURSE.md
├── plugin.json
├── package.json
├── explorables.config.ts
├── skills/
│ └── start-course/
│ └── SKILL.md
├── .claude/
│ └── launch.json
├── lessons/
│ └── 01-introduction.md
├── explorables/
│ └── hello-explorable/
│ └── index.ts
└── exercises/
A course author should first answer:
- Who is this for?
- What must the learner already know?
- What can the learner build or explain by the end?
- Which outcomes require interactive representations?
- Which outcomes require programming exercises?
- What does not belong in the course?
Add these answers to COURSE.md.
Keep the ordered lesson list in COURSE.md.
A lesson may link to later optional material, but the main route should be obvious.
Avoid creating a complex prerequisite graph in v1. Authors can express prerequisites in frontmatter and prose.
Create:
lessons/02-gradient-descent.md
Example:
---
id: gradient-descent
title: Gradient Descent
objectives:
- predict how step size affects optimisation
- implement a parameter update
---
# Gradient Descent
A model learns by changing its parameters to reduce a measured error.
Before using the controls, predict what will happen when the learning
rate becomes ten times larger.
:::explorable{src="../explorables/loss-surface/index.ts" height="520" title="Gradient descent explorer"}
Change the learning rate and take repeated optimisation steps. A very
large learning rate may cross the minimum repeatedly instead of settling.
:::
## What changed?
Explain why a larger step can make convergence less reliable.
:::exercise{path="../exercises/gradient-descent"}
Implement one parameter update and run the supplied tests.
:::
## Transfer
How would the update change if the model had two parameters instead of one?Create a directory:
explorables/loss-surface/
├── index.ts
├── model.ts
├── index.test.ts
└── README.md
Separate the mathematical or simulation model from rendering where possible.
// model.ts
export function loss(x: number): number {
return x * x;
}
export function gradient(x: number): number {
return 2 * x;
}
export function step(
parameter: number,
learningRate: number,
): number {
return parameter - learningRate * gradient(parameter);
}Then render it in index.ts.
The calculation can be tested without a browser.
Reusable components belong in the runtime component gallery or a shared package.
A course can import:
import { Slider, OutputPanel } from "@explorables/components";The official component library should remain small and accessible.
Suggested first components:
- Parameter slider
- XY coordinate plot
- Matrix viewer
- Vector viewer
- Execution stepper
- State inspector
- Token strip
- Heat map
- Before-and-after comparison
- Code trace viewer
Run:
explorables new exercise gradient-descentWrite:
README.mdfor the learner- Starter code
- Public tests
- Optional hidden or reference tests
- A reference solution kept out of the learner branch if appropriate
The lesson references the directory, not individual files.
Edit the canonical AGENTS.md, then keep skills/start-course/SKILL.md and CLAUDE.md as thin adapters.
Specify:
- The launch command
- Teaching style
- What Codex may and may not do
- Protected solution paths
- How to run tests
- Subject-specific expectations
Do not put lesson explanations in either instruction file. The coding agent should read the lesson currently being taught.
Run:
pnpm courseOpen the local URL in the Codex built-in browser.
Review:
- Markdown rendering
- Layout at narrow widths
- Keyboard navigation
- Explorable behaviour
- Error messages
- Exercise links
- Text alternatives
Run:
pnpm course:validateValidation should report actionable errors:
lessons/04-attention.md:27
Explorable source does not exist:
../explorables/attention-map/index.ts
Run:
pnpm test
pnpm test:browserFor a course submission, CI must pass from a fresh checkout.
Tag a release:
git tag v1.0.0
git push origin v1.0.0Optionally submit the tagged release to the catalogue repository through a pull request.
Whenever possible, let the learner encounter a surprising behaviour before presenting the formal definition.
The learner should commit to an expectation before running important simulations.
This can be ordinary prose:
Before clicking Run, write down whether you expect the value to rise or fall.
It does not require a tracking system.
Strong explorables connect several views:
- Formula
- Diagram
- Intermediate values
- Code
- Output
Changing one should update the others.
A learner should spend time on the concept, not on unrelated setup.
Every substantial concept should include at least one broken case:
- Excessive learning rate
- Data leakage
- Incorrect tensor axis
- Missing causal mask
- Invalid tool termination
- Quantisation error
After a working implementation, Codex should ask the learner to explain:
- What the code does
- Why it works
- Where it can fail
- How it was verified
Do not create difficulty through:
- Unclear instructions
- Hidden dependencies
- Large boilerplate
- Fragile setup
- Needlessly clever tests
- Arbitrary time limits
For lessons using the discovery profile:
- capture a prediction before revealing the formal claim;
- let the learner generate a meaningful case rather than only select a preset;
- expose inputs, assumptions, intermediate state, and outputs;
- record at least one run that can be compared with another;
- connect the observed invariant to an implementation or learner-authored test;
- finish with evidence-based reflection and a failure mode.
Automated validation checks the declared cycle and event contract. Course review and learner playtesting determine whether the interaction genuinely supports discovery.
AI from First Principles is for software developers and computer science graduates who use modern coding agents but want to develop their own underlying competence.
It is motivated by three principles:
- Use LLMs as tools rather than substitutes for understanding.
- Learn enough of the machinery to inspect, debug, and extend it.
- Build toward meaningful participation in the open-weight ecosystem.
Learners should know:
- Basic programming
- Functions and data structures
- Basic algebra
- How to use a terminal
- How to read a test failure
- Basic Git
Python can be introduced where necessary for model work, even though the explorables runtime itself is TypeScript.
By completion, a learner should be able to:
- Explain the relationship between data, parameters, objectives, and optimisation
- Implement foundational machine-learning algorithms
- Understand and implement automatic differentiation
- Explain tokenisation and next-token prediction
- Implement scaled dot-product attention
- Build and train a small decoder-only transformer
- Inspect and run an open-weight model
- Explain memory, quantisation, KV caching, and inference trade-offs
- Construct a valid evaluation
- Fine-tune a small model with LoRA
- Build a bounded tool-using agent
- Make a credible first open-source contribution
Topics:
- What it means to use an LLM as a tool
- Verification
- Reading generated code
- Debugging without agent transcripts
- Declaring AI assistance
- The learner ownership test
Exercise:
- Ask Codex to generate a small program, then trace, modify, break, and repair it.
Topics:
- Rules versus learned systems
- Features, labels, parameters, and loss
- Training, validation, and test sets
- Baselines
- Leakage
Explorables:
- Convert a rule-based classifier into a learned boundary
- Introduce and remove test leakage
- Compare a demo with an evaluation
Topics:
- Vectors
- Matrix multiplication
- Derivatives
- Gradients
- Probability
- Optimisation
Explorables:
- Vector transformation
- Loss surface
- Gradient stepper
- Learning-rate instability
Exercises:
- Dot product
- Matrix multiplication
- Finite-difference gradient
- Gradient descent
Topics:
- Linear regression
- Logistic regression
- Regularisation
- Trees and ensembles
- Clustering
- PCA
- Bias and variance
Explorables:
- Fit a line manually
- Move a classification threshold
- Overfit a polynomial
- Build a decision tree
- Move cluster centres
Project:
- Implement a small ML library and compare it with reference implementations.
Topics:
- Neurons
- Activations
- Computational graphs
- Backpropagation
- Optimisers
- Initialisation
- Normalisation
Explorables:
- Computation graph builder
- Forward and backward value trace
- Dead ReLU
- Exploding gradient
Project:
- Build a miniature autodiff engine and use it to train a small neural network.
Topics:
- Unicode and bytes
- Character, word, and byte tokenisation
- BPE
- Embeddings
- Next-token prediction
- Softmax
- Cross-entropy
- Sampling
Explorables:
- BPE merge workbench
- Token fertility comparison
- Logit and softmax editor
- Temperature, top-k, and top-p sampler
Project:
- Build a tokenizer and a small language model.
Topics:
- Queries, keys, and values
- Scaled dot-product attention
- Causal masks
- Multi-head attention
- Positional information
- Transformer blocks
- Decoder-only models
Explorables:
- Query-key workbench
- Attention matrix
- Causal-mask toggle
- One-token transformer trace
Project:
- Implement and train a tiny decoder-only transformer.
Topics:
- Model architecture versus checkpoint
- Base versus instruction models
- Model cards and licences
- Weight formats
- Prefill and decoding
- KV cache
- Quantisation
- Batching
- Local versus GPU inference
Explorables:
- Parameter memory calculator
- KV-cache viewer
- Quantisation error explorer
- Concurrency and latency simulator
Project:
- Benchmark the same model across multiple inference backends.
Topics:
- Deterministic scoring
- Model judging
- Multiple trials
- Confidence and variance
- Contamination
- Data provenance
- Dataset quality
- Failure taxonomies
Explorables:
- Benchmark leakage laboratory
- Judge disagreement explorer
- Trial-count uncertainty
- Data deduplication visualisation
Project:
- Create a reproducible evaluation for one narrow capability.
Topics:
- Supervised fine-tuning
- LoRA
- Training and validation loss
- Overfitting
- Ablations
- Regression testing
Explorables:
- Low-rank matrix update
- Rank versus capacity
- Training improvement versus regression
Project:
- Fine-tune a small open-weight model and compare it against an untouched baseline.
Topics:
- Structured output
- Tool schemas
- Agent loops
- Context selection
- Retrieval
- Termination
- Sandboxing
- Prompt injection
- Agent evaluation
Explorables:
- Step-through agent loop
- Infinite-loop failure
- Retrieval chunking
- Tool-selection error
- Prompt-injection attack
Project:
- Build and evaluate a bounded, sandboxed tool-using agent.
Paths:
- Applied AI engineer
- ML or model engineer
- Inference systems engineer
- Evaluation and safety engineer
- Research engineer
- Open-weight contributor
The final module should help the learner choose a concrete next project rather than only list job titles.
The learner should:
- Define a narrow model capability.
- Establish a baseline.
- Build a valid evaluation.
- Improve the capability through code, data, or adaptation.
- Analyse failures and regressions.
- Publish a reproducible repository.
A generic chatbot wrapper does not satisfy the final project.
The course should show several legitimate contribution paths:
- Run a project from source
- Reproduce an issue
- Verify a benchmark result
- Improve documentation
- Add examples
- Improve error messages
- Add a failing test
- Add a model conversion
- Add an evaluation
- Add tokenizer support
- Add a compatibility path
- Improve latency
- Reduce memory
- Add quantisation
- Improve batching or caching
- Review contributions
- Maintain model support
- Curate a benchmark or dataset
- Coordinate releases
The first runtime release should support:
COURSE.md- Lesson Markdown
- YAML frontmatter
explorabledirectiveexercisedirective- TypeScript explorable bundling
- Sandboxed iframe execution
- Lesson navigation
- Local development server
- Structural validation
- Basic accessibility checks
AGENTS.mdandCLAUDE.mdcourse templates- Agent Plugins v1 manifest and portable
start-courseAgent Skill - Claude Code Desktop preview configuration
- Course scaffolding CLI
- Static
apps/sitelanding page - GitHub Pages deployment workflow
- Custom-domain configuration for
explorables.ai
Do not build the entire AI curriculum before validating the format.
Build six lessons:
- Gradient descent
- Backpropagation
- BPE tokenisation
- Self-attention
- Sampling and generation
- Evaluation leakage
Each lesson should include:
- One strong explorable
- One prediction
- One focused coding exercise
- One broken case
- One explanation prompt
The MVP succeeds when:
- A learner can clone the course and start it in under ten minutes.
- Codex and Claude Code Desktop can open the local course in their browser or preview surfaces.
- All six lessons render without a backend.
- Explorables run in sandboxed iframes.
- The learner can move from an explorable to a real exercise directory.
- A new contributor can add a lesson using only the author guide.
- A course PR can be validated entirely in CI.
- The full experience works without login or remote tracking.
- The landing page builds as a static artifact.
- GitHub Actions deploys the landing page from
master. - The public repository is created at
Doppp/explorablesand uses the SSH remote andmasterbranch.
- Canonical public GitHub repository
- Static landing page and GitHub Pages workflow
- Course folder convention
- Markdown parser
- Explorable contract
- Sandbox
- CLI
- Six AI lessons
- Complete foundational AI course
- Guided Course Mode with explicit checkpoint and Explore/skip controls
- Shared visual component library
- More exercise templates
- Contribution documentation
- Static catalogue repository
Build a substantially different course such as:
- Coding Agents from First Principles
- Distributed Systems
- Databases
- Computer Networking
The second course will reveal which abstractions are genuinely reusable.
- Agent Plugin registry or marketplace integration
- Client-specific extensions only where portable components are insufficient
- Static site export
- Normal-browser course player
- Course registry UI
Only after demand is clear:
- Audio assets
- Hosted course previews
- Cloud exercise runners
- Translations
- Visual authoring tools
Risk: Course modules can execute malicious browser code.
Mitigation: Sandboxed iframes, restrictive CSP, no network by default, reviewed dependencies, trust labels, and explicit warnings for external courses.
Risk: Installing a course may install compromised dependencies.
Mitigation: pnpm security defaults, committed lockfiles, build-script allowlists, CI audits, and minimal dependency policies.
Risk: The tutor becomes a replacement rather than a teaching tool.
Mitigation: Strong AGENTS.md policy, protected solution paths, progressive hints, learner explanation requirements, and exercises designed around debugging and transfer.
Risk: Authors spend more time building custom frontends than teaching.
Mitigation: Reusable component library, minimal module contract, strong examples, and a preference for one clear interactive representation per concept.
Risk: explorables becomes another proprietary content language.
Mitigation: Limit v1 to explorable and exercise. Add directives only when actual courses prove the need.
Risk: Open submissions produce shallow or inaccurate material.
Mitigation: Catalogue review, public rubrics, subject reviewers, reproducible exercises, and clear distinction between reviewed and external courses.
Risk: Some tools or language-service plugins lag behind the native TypeScript implementation.
Mitigation: Use standard .ts and .tsx, plain Markdown, no dependency on MDX/Astro/Vue/Svelte language-service plugins, and pin tested versions.
The product, runtime, CLI, public site, and open-source project are called:
explorables
The name is styled in lowercase.
Product: explorables
Website: https://explorables.ai
Repository: git@github.com:Doppp/explorables.git
CLI: explorables
Package scope: @explorables/*
AI from First Principles
See how it works. Build it yourself.
- Use
explorablesin prose and headings. - Use
@explorables/*for npm packages. - Use
explorablesfor the CLI executable. - Use
explorables.aifor the public site. - Avoid legacy working names in code, files, and documentation.
- A course can be represented entirely by a folder.
- The folder is understandable on GitHub without the
explorablesruntime. -
COURSE.mdand lesson frontmatter validate. - Only two custom directives are required.
- A course can contain no explorables and still render correctly.
- TypeScript 7 type checking passes.
- Course starts with one documented command.
- Markdown renders with sanitisation.
- Explorable modules compile without course-owned build config.
- Explorable modules run in sandboxed iframes.
- Explorable failures do not crash the whole course.
- Exercise links open the correct repository directory.
- Development errors include source file and line information.
- A local collection can list and open explicitly configured course roots.
- Planned collection entries are visibly unavailable and cannot be opened.
- Standalone course start and build behavior remains supported.
- The course root contains a valid Agent Plugins v1
plugin.json. - A conforming client can discover a valid
skills/start-course/SKILL.md. - Opening the repository in Codex exposes useful
AGENTS.mdguidance. - Opening the repository in Claude Code Desktop exposes useful
CLAUDE.mdguidance. - “Start the course” launches the runtime in both supported hosts.
- Both hosts can open and inspect the local course page.
- Both hosts respect protected solution paths under normal course instructions.
- Both hosts can run exercise tests and explain failures.
- Host-specific adapters remain thin and do not fork course content.
- The repository exists publicly at
Doppp/explorables. - The default branch is
master. - The
originremote isgit@github.com:Doppp/explorables.git. -
apps/sitebuilds to static files. - GitHub Pages deploys from
masterthrough GitHub Actions. - The site is configured for
explorables.ai. - The landing page has no analytics or backend dependency.
- The landing page passes accessibility checks.
- A contributor can scaffold a course.
- A contributor can add an explorable without changing the core runtime.
- CI validates a course from a clean checkout.
- Course licensing is explicit.
- External courses are clearly marked as unreviewed.
- Six vertical-slice lessons are complete.
- Each includes an explorable, exercise, failure case, and explanation prompt.
- At least five target learners complete two lessons.
- Setup failures and authoring friction are documented.
- Feedback informs the v1 format before the full course is produced.
explorables is:
An open course format and local runtime for learning technical subjects through Markdown, interactive TypeScript modules, real exercises, and a Codex tutor.
A course author writes normal Markdown, imports explorables as TypeScript modules, includes exercises and tests, and submits the folder through ordinary open-source workflows.
A learner clones the course, opens it in Codex or Claude Code Desktop, and says:
Start the course.
The coding-agent host handles guidance, code, files, tests, and discussion. The built-in browser or preview pane handles explanations, graphics, simulations, and interaction. The repository remains the source of truth. The same repository also publishes a basic static landing page at explorables.ai.
The first course, AI from First Principles, takes software developers from basic machine-learning concepts through transformers, open-weight models, evaluation, fine-tuning, agents, and a practical route toward AI engineering or open-source contribution.
These references informed the platform choices current as of July 2026:
-
TypeScript 7.0 announcement: https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/
-
Node.js release status: https://nodejs.org/en/about/previous-releases
-
pnpm 11 release: https://pnpm.io/blog/releases/11.0
-
Codex built-in browser: https://learn.chatgpt.com/docs/browser?surface=app
-
Codex
AGENTS.mdinstructions: https://learn.chatgpt.com/docs/agent-configuration/agents-md -
Codex skills: https://learn.chatgpt.com/docs/build-skills
-
Codex plugins: https://learn.chatgpt.com/docs/plugins
-
Agent Plugins v1 specification: https://agent-plugins.org/specification
-
Agent Skills specification: https://agentskills.io/specification
-
Claude Code overview and Desktop setup: https://docs.anthropic.com/en/docs/claude-code/overview
https://docs.anthropic.com/en/docs/claude-code/setup -
Claude Code memory and
CLAUDE.md: https://docs.anthropic.com/en/docs/claude-code/memory -
Claude Code skills: https://docs.anthropic.com/en/docs/claude-code/skills
-
GitHub Pages overview: https://docs.github.com/en/pages/getting-started-with-github-pages/what-is-github-pages
-
Custom GitHub Pages workflows: https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
-
Configuring a custom domain: https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site
-
GitHub CLI repository creation: https://docs.github.com/en/github-cli/github-cli/quickstart
-
Changing the default branch: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch