# Instructor Studio (POC) — Implementation Guide

Instructor Studio is the proof-of-concept authoring application for
Codermerlin Academy lesson content. Instructors edit lesson panels as MyST
Markdown in a live source/preview editor, build a glossary, author missions
and challenges — including programs students write and run in a workbench —
then publish lessons through the platform's content pipeline and assign them
to sections.

**This is implementation material.** It documents how the Studio is built,
what its components expose, and what contracts other software must agree
with. If you are an instructor looking for how to *use* the Studio, start
with [Getting to Know Instructor Studio](../../instructor-tutorials/getting-to-know-instructor-studio.md)
instead — it covers every feature in this guide from the author's side of
the screen, and assumes nothing about software.

## Verified against

**Build 213 · `20260910T123348`** (`codermerlin.academy-pocs` @ `45b2925`).

The POC moves quickly — twenty-four builds in the sixty-one days before this
revision. Every document in this set names the build it was verified against
in its own opening lines, and `--poc-version` in
`instructor-studio/css/styles.css` is bumped on every change, so a reader can
always tell whether the page in front of them is current. Per the POC's
change discipline, bumping that version obliges reviewing this set and the
instructor tutorials against the change.

## Where the code is

A plain-file application with no build step, in the
`codermerlin.academy-pocs` repository under `instructor-studio/`:
`index.html` plus hand-written ES modules under `js/`, one stylesheet, and
two component assemblies under `component-assemblies/`. The repository's own
[`instructor-studio/README.md`](https://github.com/ayode-institute/codermerlin.academy-pocs/blob/main/instructor-studio/README.md)
is the canonical source for the POC's methodology, its architecture diagram,
how to serve it locally, and its change discipline. This guide does not
restate those; it documents the feature surface and the contracts in detail.

## The three rendering surfaces

The Studio's editing surface is the **Merlin MyST Editor**, a published
platform component (`orange/assembly-components`,
`merlin/content/myst-editor/`). The Studio, the Student Lab POC and published
lessons all resolve it from the published-components catalog, so authoring
preview and student rendering are the same renderer — which is why a feature
documented in [Editor Component](editor-features.md) behaves identically in
all three.

That holds **on the catalog path only.** Each POC also keeps a local copy of
the assembly under its own `component-assemblies/`, mounted when the
local-component override is active (append
`?useLocalComponentForTesting=1`, or right-click the version badge), and
those copies drift: at build 213 the Studio's copy is 2,529 lines and Student
Lab's is 2,238, with no Merlin Terminal support in Student Lab's at all.
Under a local override the three surfaces do **not** render identically —
worth knowing, because local override is the mode a developer reproducing a
rendering bug is most likely to be in. Component drift is tracked in backend
#2484.

A second published assembly, **Merlin Challenge Config**, hosts the challenge
options pane; a third, **Merlin Terminal**, is mounted *inside* the editor's
preview by `{merlin-terminal}` directives.

## Documents

* [Editor Component](editor-features.md) — the complete feature inventory of
  the Merlin MyST Editor: editing surface and history, the full context-menu
  tree, keyboard shortcuts, Find & Replace, whitespace and embedded-HTML
  markers, glossary, call outs and boxes, insert/format operations, terminal
  embeds, preview rendering, the component's public API, and student mode.

* [Studio Shell](studio-shell.md) — the application around the editor: the
  menubar and its shortcuts, the canonical **Menus and labels** table, panel
  navigation and the lesson model, typed panels, view modes, identity and
  realm assertion, the target-silo selector, the source-normalization
  pipeline, and the diagnostics surface.

* [Challenges and Grading](challenges-and-grading.md) — the Merlin Challenge
  Config component, the four evaluation strategies, question types and
  modifiers, answer keys, structured choice pools, AI grading rubrics, and
  challenge variant versioning.

* [ĀYŌDÈ Intelligence Operations](ai-operations.md) — the `aitunerequest`
  contract and host routing, synchronous versus RAG/async paths, the
  whole-lesson context payload, whole-lesson panel generation, assessment
  generation and its review-before-hydrate flow, and the reference library.

* [Programs and Workbench](programs-and-workbench.md) — orchestrated
  (`jobAsync`) program challenges: generator bundles, runtimes, comparator
  modes and scoring, authored comparators, workbench bundles and their
  authoring-time refusals, Test in Workbench, and challenge-shell startup
  scripts.

* [Publish and Assign](publish-and-assign.md) — the publish wizard and its
  pre-publish checks, media internalization, the staged publish pipeline,
  component mirroring and version pinning, conflict resolution, and the
  assign wizard.

* [Formats and Contracts](formats-and-contracts.md) — everything another
  program must agree with: the component public API and its events, the
  Studio SDK, the `callout-*` class token, panel manifests and sidecars,
  content normalization and hashing, and the published-lesson asset shape.

## Related documentation

* [Instructor Tutorials](../../instructor-tutorials/index.md) — the same
  features from the instructor's side, in tutorial form.
* [Courses and Lessons](../../institutional-administration/courses-and-lessons/index.html)
  — how courses, lessons, sections, assignments and grades relate.