diff --git a/Cargo.lock b/Cargo.lock
index 0f1f88d..6b5ff91 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -552,7 +552,7 @@ dependencies = [
 
 [[package]]
 name = "scorekit"
-version = "0.7.0"
+version = "0.7.1"
 dependencies = [
  "assert_cmd",
  "clap",
diff --git a/Cargo.toml b/Cargo.toml
index 7f35812..4e59802 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "scorekit"
-version = "0.7.0"
+version = "0.7.1"
 edition = "2024"
 
 [dependencies]
diff --git a/README.md b/README.md
index f0b87cc..d700c76 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,7 @@ Because the score is plain text, it lives in git next to your code: diff it, rev
 - **Scene suites** — intro / explore / combat / victory sections that share the same musical motifs, compiled from a single file.
 - **Exact event clips** — stable-ID pitched/percussion events, section variants, and deterministic step/linear automation for arrangements that need authored syncopation, fills, filter sweeps, or talking-bass motion.
 - **Sound textures** — layer field recordings, ambience, and SFX (water, birds, engines…) as deterministic loops or beat-scheduled one-shots without baking local paths into the scene.
+- **MakeCode songs** — `scorekit makecode` compiles the same scene into ``music.createSong(hex`…`)`` TypeScript for MakeCode Arcade and micro:bit V2, one song per section, with a manifest of every voice mapping.
 - **`meta.json`** — exact loop points and sample counts, ready for your engine to consume.
 
 ## Install
diff --git a/docs-site/src/agent-skill.md b/docs-site/src/agent-skill.md
index c5d9434..d42914e 100644
--- a/docs-site/src/agent-skill.md
+++ b/docs-site/src/agent-skill.md
@@ -1,6 +1,6 @@
 # Agent Skill
 
-The release archive and source repository include an Agent skill under `skills/scorekit`. It teaches a skill-capable coding Agent how to query the schema, write scenes, validate musical structure, apply grammar profiles, and build assets.
+The release archive and source repository include an Agent skill under `skills/scorekit`. It teaches a skill-capable coding Agent how to query the schema, write scenes, validate musical structure, apply grammar profiles, build audio assets, and compile MakeCode `music.createSong` TypeScript.
 
 Install it together with the local binary:
 
diff --git a/docs-site/src/architecture.md b/docs-site/src/architecture.md
index 52f16f3..c6ec7b4 100644
--- a/docs-site/src/architecture.md
+++ b/docs-site/src/architecture.md
@@ -6,15 +6,16 @@ scorekit is a thin compiler and orchestration layer.
 YAML scene
   -> semantic validation
   -> Score IR
-  -> deterministic MIDI
-  -> external renderer
-  -> PCM audio
-  -> external FFmpeg export
+      -> deterministic MIDI
+          -> external renderer
+          -> PCM audio
+          -> external FFmpeg export
+      -> MakeCode song bytes (`scorekit makecode`)
 ```
 
 ## Guarantees
 
-- The same DSL and compiler inputs produce byte-identical MIDI.
+- The same DSL and compiler inputs produce byte-identical MIDI, and the same scene produces byte-identical MakeCode song encoding.
 - Loop and stem lengths are derived from quantized musical time.
 - File-writing commands stage output and publish it atomically.
 - JSON Schema and structured errors expose the same contract used by the CLI.
diff --git a/docs-site/src/commands.md b/docs-site/src/commands.md
index bbb19e6..1040cbf 100644
--- a/docs-site/src/commands.md
+++ b/docs-site/src/commands.md
@@ -14,6 +14,7 @@ All commands accept the global `--json` flag. Successful diagnostic commands wri
 | `schema --resolver` | Print the instrument-resolver config schema |
 | `lint <scene> --grammar <file>` | Check compiled music against measurable style rules |
 | `midi <scene> -o <file>` | Compile deterministic Standard MIDI |
+| `makecode <scene> -o <file>` | Compile MakeCode `music.createSong` TypeScript (plus a `.meta.json` manifest) |
 | `render <midi> -o <wav>` | Render one MIDI file through a selected backend |
 | `export <audio> -o <file>` | Convert or trim audio through FFmpeg |
 | `build <scene> -o <file>` | Run the complete asset pipeline |
@@ -43,6 +44,21 @@ writing the output: the command has no renderer-profile input, and omitting a
 program change would make a generic GM player select piano. Use
 `build --renderer sfizz --orchestration <file>` to render those identities.
 
+`makecode` compiles a scene to Microsoft MakeCode's synth-song format (song
+encoding v0, played by MakeCode Arcade and micro:bit V2): a paste-ready `.ts`
+snippet with one ``let <name> = music.createSong(hex`…`)`` statement per song
+— one song per section for a suite — plus a `.meta.json` manifest reporting
+the tick grid and each track's mapped MakeCode chip or drum voice. Synthesis
+happens entirely in the MakeCode runtime. Chip and drum amplitudes are scaled
+from track `intensity` against a ~1.2 full-scale mix budget so stacked voices
+stay near the MakeCode editor's own 220–384 / 1024 range; tiny PWM speakers
+clip if every voice is written at full scale. Features the format cannot
+express fail with structured exit-2 errors (pitch bends/`glide`, clip CC
+automation, `textures`, timing finer than 255 ticks per beat such as
+`humanize`); `pan`/`reverb` are dropped with a WARN line and a manifest
+record. Keep bass in a chip-safe register — sub-bass square waves distort on
+Arcade and micro:bit speakers.
+
 ## Instrument resolution
 
 `build` and `batch` resolve every track's instrument against what the
diff --git a/docs-site/src/introduction.md b/docs-site/src/introduction.md
index 22f771f..b03c77f 100644
--- a/docs-site/src/introduction.md
+++ b/docs-site/src/introduction.md
@@ -1,11 +1,12 @@
 # Introduction
 
-scorekit is an Agent-oriented music compiler for game and film-style scoring workflows. It compiles a reviewable YAML scene into deterministic MIDI, then delegates audio rendering and export to established external tools.
+scorekit is an Agent-oriented music compiler for game and film-style scoring workflows. It compiles a reviewable YAML scene into deterministic MIDI, then delegates audio rendering and export to established external tools. The same scene can also compile to a MakeCode synth-song for Arcade and micro:bit V2.
 
-The compiler produces seamless loops, sample-aligned instrument/texture stems, suite sections, metadata, and OGG or WAV assets. Texture tracks bring deterministic field recordings, ambience, and SFX into the score timeline. Creative decisions stay in the upstream Agent and the text scene; scorekit does not contain a generative model.
+The compiler produces seamless loops, sample-aligned instrument/texture stems, suite sections, metadata, OGG or WAV assets, and optional MakeCode `music.createSong` TypeScript. Texture tracks bring deterministic field recordings, ambience, and SFX into the score timeline. Creative decisions stay in the upstream Agent and the text scene; scorekit does not contain a generative model.
 
 ```text
 scene.yaml -> Score IR -> MIDI -> renderer -> WAV -> FFmpeg -> game assets
+                     \-> MakeCode song TypeScript
 ```
 
 The supported render backends are FluidSynth and TiMidity++ for SF2 SoundFonts, and sfizz for SFZ sample libraries.
diff --git a/docs-site/src/machine-interface.md b/docs-site/src/machine-interface.md
index 708a3fe..5509a34 100644
--- a/docs-site/src/machine-interface.md
+++ b/docs-site/src/machine-interface.md
@@ -11,7 +11,8 @@ The machine interface follows semantic versioning. Within a major version, the f
 - Exit codes: `0` success · `1` I/O failure · `2` invalid input · `3` missing dependency · `4` external tool failure.
 - The `--json` error object shape on stderr (below).
 - The JSON Schemas exported by `scorekit schema`, `schema --grammar`, `schema --profile`, `schema --orchestration`, `schema --texture-profile`, and `schema --resolver` (fields are added, not removed or repurposed).
-- The `meta.json` / `report.json` artifact fields.
+- The `meta.json` / `report.json` artifact fields, including the MakeCode
+  manifest (`target: makecode-song-v0`, per-song header and voice mapping).
 
 Determinism boundary: the same scene + same sound source + same tool versions produces byte-identical MIDI, and audio identical within documented tolerances. Reproducibility across *different* FluidSynth/FFmpeg versions is explicitly **not** promised — pin your toolchain (e.g. in a container image) if you need cross-machine identical audio.
 
diff --git a/docs-site/src/scene-protocol.md b/docs-site/src/scene-protocol.md
index 0ac7cd3..8e9a09d 100644
--- a/docs-site/src/scene-protocol.md
+++ b/docs-site/src/scene-protocol.md
@@ -28,7 +28,7 @@ The scene protocol is versioned by the scorekit binary's semantic version. There
 
 Within a major version:
 
-- **Additive only.** New fields are optional with defaults that preserve prior output — a scene that does not use a new field compiles to *byte-identical MIDI* before and after the addition. (Precedent: when `pan`/`reverb`/`glide` landed in 0.2.0, the golden SMF byte-comparison test did not change.)
+- **Additive only.** New fields are optional with defaults that preserve prior output — a scene that does not use a new field compiles to *byte-identical MIDI* before and after the addition. (Precedent: when `pan`/`reverb`/`glide` landed in 0.2.0, the golden SMF byte-comparison test did not change.) Additional compile targets such as `scorekit makecode` must not add schema fields that only that target can fulfill.
 - **No repurposing.** An existing field's name, type, range, default, or compile semantic does not change. The normative transform order (below) is part of the semantic and is equally frozen.
 - **Old scene, new binary:** always valid, same MIDI bytes.
 - **New scene, old binary:** rejected with exit 2 and the offending field path — a readable upgrade signal, not a corrupted asset.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index a33efe3..7df7c29 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -14,6 +14,8 @@ scene.yaml ──(single source of truth, versioned directly by git)
     │  scorekit validate / schema
     ▼
 Score IR ──► scorekit midi ──► scene.mid (byte-exact deterministic)
+    │
+    └──► scorekit makecode ──► music.createSong TypeScript (MakeCode Arcade / micro:bit)
     │
     ▼  scorekit render          ┌─ render backend boundary (swappable) ─┐
 FluidSynth/TiMidity + SF2,      │ fluidsynth | timidity | sfizz (SFZ)    │
@@ -38,6 +40,7 @@ Once finished, it is a **deterministic composition compiler**:
 
 - **Scene DSL and validation**: YAML scenes (tempo/key/time signature/bars/loop/tracks), unknown fields rejected, semantic validation with field paths, parse errors with line numbers; `scorekit validate`, `scorekit schema` (JSON Schema export). The scene format is specified as a **protocol-level contract** — normative field semantics, semver-bound stability rules (additive-only, no repurposing, byte-identical output for existing scenes), extension gates, and the error contract — in `docs-site/src/scene-protocol.md`. Evidence: `src/schema.rs`, `tests/cli.rs`.
 - **Deterministic MIDI compilation**: `scorekit midi` outputs a byte-stable SMF (format 1, PPQ 480), with sustain/arpeggio/bass/drums/melody/tabla patterns plus exact event clips (below), locked against golden baselines. Profile-only melodic identities are rejected before output because standalone MIDI has no renderer-profile binding and a programless channel would become piano in a generic player; channel-10 Tabla remains valid. Evidence: `src/composer.rs`, `src/midi.rs`, `tests/golden/forest.mid`, `tests/cli.rs`.
+- **MakeCode song export**: `scorekit makecode` compiles a scene to Microsoft MakeCode's synth-song byte format (``music.createSong(hex`…`)``, encoding v0, as consumed by MakeCode Arcade and micro:bit V2) — one deterministic `.ts` snippet per scene, or one song per section for a suite, plus a `.meta.json` manifest reporting each track's chip-voice/drum-voice mapping and every dropped field. All synthesis happens in the MakeCode runtime; scorekit only serializes note events and the platform's own curated synth presets. Features the format cannot express fail structurally (pitch bends/glide, CC automation, textures, sub-tick timing such as `humanize`) rather than degrade silently; `pan`/`reverb` are dropped with a manifest-recorded WARN. Interoperability is pinned by byte-exact roundtrips of real MakeCode-editor songs. Evidence: `src/makecode.rs`, `tests/golden/forest.makecode.ts`, `tests/cli.rs`.
 - **Exact event clips and deterministic automation**: root `clips` hold stable-ID pitched or GM-percussion events in quarter-note beats, tracks select them with `pattern: clip`, and sections can replace a track's clip by stable track ID. `once`/`loop` length rules, absolute scientific pitch, no-overlap boundaries, and fixed PPQ-480 quantization make authored syncopation and fills exact; nested maps are order-insensitive, so declaration reordering changes neither MIDI nor semantic diff. Pitched clips carry CC1/CC11/CC74/pitch-bend lanes with `step` (default) or deterministic `linear` interpolation sampled every 60 ticks; loop state must seal, generated samples count against the event budget, and same-tick MIDI order is frozen. Clip timing is insulated from swing/legato/humanize while intensity/dynamics still scale velocity. Evidence: `src/schema.rs`, `src/composer.rs`, `src/midi.rs`, `tests/cli.rs`, `examples/scenes/heavy_dubstep.yaml`.
 - **Disco composition primitives**: several percussion tracks may share General MIDI channel 10 while remaining separate SMF tracks and stems; percussion clips expose standard GM tambourine/cowbell/bongo/conga/timbale/agogo/cabasa/maracas voices; additive exact-GM `clavinet` and `synth_brass` identities leave the 60-instrument core and world extension unchanged. These are portable score semantics, not style presets or renderer parameters. Evidence: `src/schema.rs`, `src/instrument.rs`, `src/composer.rs`, `tests/cli.rs`.
 - **Spatial performance fields**: per-track `pan`/`reverb`/`glide` compile to MIDI CC10/CC91/pitch-bend deterministically; `glide` is a melody-only tail portamento whose ramps stay loop-seam continuous; absent fields leave output byte-identical. Evidence: `src/composer.rs::glide_bends`, `src/midi.rs`, `tests/cli.rs`.
@@ -443,6 +446,42 @@ Evidence: `src/schema.rs`, `src/instrument.rs`, `src/composer.rs`,
 `manifests/libraries/scoredata-{clavinet,drum-machine-*,house-stab,synth-brass}.yaml`;
 scoredata-forge `recipes/{clavinet,drum-machine-*,house-stab,synth-brass}.toml`.
 
+### M17 — MakeCode song target (`scorekit makecode`) (status: complete)
+
+Scenes compile to a fourth output target: Microsoft MakeCode's synth-song byte
+format (``music.createSong(hex`…`)``, song encoding v0), so the same DSL that
+drives MIDI/WAV/OGG assets also drives MakeCode Arcade and micro:bit V2 game
+music. This is a serialization target, not a renderer: the MakeCode runtime
+owns all synthesis, and scorekit emits only note events plus the platform's
+own curated instrument parameters, keeping the no-in-house-DSP and
+schema-neutrality iron rules intact.
+
+- **One command, two artifacts**: `scorekit makecode scene.yaml -o out.ts`
+  writes a paste-ready TypeScript snippet (one ``let <name> = music.createSong(hex`…`)``
+  per song) and `out.meta.json` (target `makecode-song-v0`, per-song
+  BPM/measure/tick-grid header, per-track voice mapping, warnings). A suite
+  emits one song per section with the section's tempo/mute/loop applied.
+- **Curated voice identities**: melodic instruments map onto the nine MakeCode
+  editor chip voices (dog/duck/cat/fish/car/computer/burger/cherry/lemon) via
+  an exhaustive compiler-enforced table; GM percussion keys map onto the
+  editor's 24 drum synth definitions. Every choice is reported in the
+  manifest — visible, reviewable, never silent.
+- **Exact-representation gate**: pitch bends (`glide`, clip bends), CC
+  automation lanes, `textures`, out-of-range pitch/tempo/length, and timing
+  finer than the format's ≤255-ticks-per-beat grid (e.g. `humanize`) are
+  structured exit-2 errors naming the field and the fix; only `pan`/`reverb`
+  degrade, each with a WARN line and a manifest record. The tick grid is
+  solved per song as the coarsest exact grid (gcd of onsets/durations), and
+  same-tick notes merge into one polyphonic event because the MakeCode
+  sequencer fires each tick's event exactly once.
+- **Interoperability proven, not assumed**: a decoder lives beside the encoder
+  and four real MakeCode-editor songs roundtrip byte-exactly as unit golden
+  vectors; the forest scene's `.ts` output is locked as an E2E golden file and
+  double-run determinism is asserted.
+
+Evidence: `src/makecode.rs`, `src/main.rs::compile_makecode`,
+`tests/golden/forest.makecode.ts`, `tests/cli.rs`.
+
 ## Sound library & orchestration program (standing direction)
 
 > Adopted 2026-07, after the external sound corpus was reorganized into versioned, manifested libraries. Unlike M0–M12 this is not a finishable milestone but a **standing program** with measurable acceptance: the repo owns the portable vocabulary, resolution semantics, and certification tooling; the sample corpus lives outside the repo under `SCOREKIT_SOUND_LIBRARY_DIR` as versioned, license-tracked libraries with checksummed archives, a rebuildable catalog, and certified renderer/texture profiles.
@@ -581,5 +620,6 @@ Permissions note: scorekit is a local single-user CLI with no role/permission sy
 | Texture source discovery & certification (`texture inspect`, `texture check`, M14) | High (the discovery contract agents author against; a wrong or unverifiable source silently ships as an absent or mis-cast layer, and `texture check` shells out to FFmpeg over untrusted recordings) | ✅ (the additive published schema accepts legacy path strings plus structured sources, with every discovery field required on the structured variant, `additionalProperties: false`, and the closed category vocabulary documented per value, while measured physics is deliberately absent; a 1200-source structured inventory enumerates completely and byte-identically across runs with full metadata per entry; filters are exact and conjunctive across category/tag/mode/use-case and repeated `--tag` intersects; `texture check` reports `sha256`/`duration_seconds`/`frames`/`peak_abs`/`rms` deterministically and carries declared intent alongside the measurement; both commands are reachable over MCP) | ✅ (an unsatisfiable query returns a truthful `no_match` at exit 0 rather than a nearest match, but an unknown `--category` is a typo → exit 2 naming the valid vocabulary; legacy path-only profiles remain build-compatible but `inspect`/`check` reject them instead of fabricating metadata; incomplete structured sources — missing description/tags/provenance, unknown category, non-token use case, `default_mode` outside `modes`, empty path — and unsupported `schema_version` fail with the exact field, while an omitted version defaults to 1; `texture check` reports `missing` and `silent` sources as failures with exit 2) | N/A (local CLI) | ✅ (`texture check` scratch renders honor `SCOREKIT_TMPDIR` and are swept on the failure path, verified by exact directory listing; a structured source's undeclared mode aborts `build` before the staging directory is created, so no output directory exists at all) | `tests/cli.rs::texture_profile_schema_publishes_required_discovery_metadata` / `texture_inspect_enumerates_large_inventory_deterministically` / `texture_inspect_filters_exactly_and_admits_no_match` / `legacy_texture_profile_builds_but_discovery_requires_metadata` / `texture_profile_rejects_incomplete_discovery_metadata` / `texture_check_measures_physics_of_declared_sources` / `texture_check_rejects_missing_and_silent_sources_without_residue` / `build_rejects_texture_mode_the_profile_does_not_declare` / `mcp_exposes_texture_inspect_and_check` / `src/texture.rs::tests` |
 | Exact event clips, step automation, and section-scoped structural lint (M15) | High (authored rhythm/controller state is byte-level score intent; an ignored SFZ control or unstable event order silently changes the drop) | ✅ (stable-ID pitched/percussion clips validate and compile to exact byte-identical MIDI independent of map declaration order; authored timing is isolated from swing/legato/humanize; section clip overrides equal standalone compilation; suite capability checks follow only clips selected by unmuted sections; CC1/CC11/CC74/pitch-bend use frozen same-tick ordering; semantic diff addresses event IDs; compiled percussion/onset/automation rules work per section; the shipped heavy-Dubstep scene/grammar pair validates, lints, and compiles deterministically) | ✅ (missing/wrong-kind references, extreme/out-of-range pitches, overlap/boundary/loop ambiguity, malformed automation values/initial state/seal, per-track expansions above 65,536 events in either scenes or sections, and unsupported SFZ controls on active clips fail with precise field paths; renderer mappings remain backward-compatible strings but must opt into each automated target) | N/A (local CLI) | ✅ (invalid clip/automation MIDI writes leave no partial artifact; an sfizz build whose effective patch lacks a required control aborts before staging and leaves no WAV/stems/meta residue) | `tests/cli.rs::clip_scene_validates_and_schema_exposes_stable_clip_maps` / `clip_events_compile_to_exact_deterministic_midi_independent_of_map_order` / `explicit_clip_timing_and_velocity_ignore_generative_performance_transforms` / `section_clip_override_compiles_as_the_equivalent_standalone_scene` / `invalid_clip_semantics_fail_with_precise_paths_and_no_midi_artifact` / `validate_rejects_clip_expansion_beyond_the_per_track_event_budget` / `validate_applies_clip_expansion_budget_to_suite_sections` / `clip_step_automation_emits_canonical_deterministic_midi_events` / `invalid_clip_automation_fails_before_writing_midi` / `sfizz_orchestration_requires_declared_clip_automation_controls` / `sfizz_suite_ignores_controls_from_an_inactive_base_clip` / `diff_matches_clip_events_by_stable_identity` / `lint_measures_section_clip_percussion_and_automation_rules` / `heavy_dubstep_reference_scene_is_valid_linted_and_deterministic` |
 | Five independent Disco identities and composition primitives (M16) | High (shared-channel routing, generated controller density, a false instrument identity, or copied profile would silently homogenize every Disco render) | ✅ (two percussion tracks validate, compile deterministically on channel 10 without program changes, and render as independent aligned stems whose sum reconstructs the mix; all auxiliary voices appear in schema and emit unique fixed GM keys; Clavinet/Synth Brass appear additively and emit programs 7/62; linear CC/bend curves use the fixed 60-tick grid while omitted interpolation remains byte-identical to explicit `step`; all five shipped scene/grammar pairs validate, lint, and explicitly select one of the unified `disco` orchestration's five palettes; the five additive renderer identities pass profile/orchestration checks, strict exact inspection, audible stem builds, and byte-identical repeat builds) | ✅ (conflicting percussion pan/reverb channel state and generated linear samples above 65,536 are rejected with exact fields before composition; malformed automation and unsupported patch controls retain the M15 structured failure paths; explicit reference palettes prevent non-Nu-Disco scenes from silently inheriting the `nu-disco` default; strict resolution refuses a missing identity rather than borrowing another profile) | N/A (local CLI) | ✅ (invalid automation leaves no MIDI artifact; Forge builds and scorekit stem builds use atomic staging/replacement and tested failure recovery) | `tests/cli.rs::disco_family_reference_scenes_are_valid_linted_and_palette_explicit` / `multiple_percussion_tracks_share_channel_ten_deterministically` / `validate_rejects_conflicting_channel_controls_across_percussion_tracks` / `build_multiple_percussion_stems_are_independent_aligned_and_sum_to_mix` / `disco_auxiliary_percussion_voices_are_public_and_emit_standard_gm_keys` / `src/schema.rs::tests::percussion_voice_midi_keys_are_unique` / `disco_instruments_are_public_and_emit_exact_gm_programs` / `clip_linear_automation_uses_a_fixed_grid_and_preserves_the_step_default` / `validate_counts_generated_linear_samples_against_the_event_budget` / `invalid_clip_automation_fails_before_writing_midi` |
+| MakeCode song export (`makecode`, M17) | Medium (file writes; a wrong byte would silently corrupt playback on-device, and a silent capability degradation would falsify authored intent) | ✅ (forest scene compiles to `.ts` + `.meta.json` with correct header/track/voice reporting; output is byte-identical to a golden file and across double runs; a suite emits one song per section honoring tempo overrides and loop flags; four real MakeCode-editor songs roundtrip decode→encode byte-exactly as unit golden vectors) | ✅ (glide/pitch bends → exit 2 + `tracks[i]`; `textures` → exit 2 + `textures`; sub-grid `humanize` timing → exit 2 naming the tick-per-beat cap and the fix) | N/A (local CLI) | ✅ (all failure paths verified to leave no partial `.ts` or `.meta.json` via exact directory listing; both artifacts go through temp-file + atomic rename) | `tests/cli.rs::makecode_happy_path_writes_song_and_manifest` / `makecode_matches_golden_source` / `makecode_is_deterministic_across_runs` / `makecode_suite_emits_one_song_per_section` / `makecode_glide_scene_fails_with_no_partial_artifacts` / `makecode_texture_scene_fails_with_no_partial_artifacts` / `makecode_humanized_scene_fails_with_grid_error` / `src/makecode.rs::tests::roundtrips_makecode_editor_songs_byte_exactly` |
 
 The matrix currently has no known gaps; when adding a new tier-1 feature, register it per coverage-baseline rule 5.
diff --git a/skills/scorekit/SKILL.md b/skills/scorekit/SKILL.md
index 14e66af..4865238 100644
--- a/skills/scorekit/SKILL.md
+++ b/skills/scorekit/SKILL.md
@@ -2,14 +2,15 @@
 name: scorekit
 description: >
   Compose and render game music with scorekit, an agent-oriented music
-  compiler: write a YAML scene DSL, compile it deterministically to MIDI,
-  render seamless loops, stems, and OGG/WAV assets, and lint compositions
-  against aesthetic grammar profiles. Use when the user asks for game BGM,
-  background music, a music loop, adaptive-music stems, film-style scoring,
-  a scene.yaml, or scorekit itself (game score, background music, looping
-  music, stems, generated music, composing a piece). Also use it to audit,
-  review, or critique an existing arrangement/scene (arrangement audit,
-  编曲审计) — standalone or as the post-build self-check.
+  compiler: write a YAML scene DSL, compile it deterministically to MIDI
+  or MakeCode `music.createSong` TypeScript, render seamless loops, stems,
+  and OGG/WAV assets, and lint compositions against aesthetic grammar
+  profiles. Use when the user asks for game BGM, background music, a music
+  loop, adaptive-music stems, film-style scoring, MakeCode Arcade / micro:bit
+  songs, a scene.yaml, or scorekit itself (game score, background music,
+  looping music, stems, generated music, composing a piece). Also use it to
+  audit, review, or critique an existing arrangement/scene (arrangement
+  audit, 编曲审计) — standalone or as the post-build self-check.
   Not for singing with lyrics, audio analysis, or editing existing recordings.
 ---
 
@@ -17,10 +18,12 @@ description: >
 
 scorekit is a **music compiler, not a music generator**: you (the agent) do
 all the composing in a YAML scene file; scorekit deterministically turns it
-into MIDI and rendered audio. Same input → byte-identical MIDI, sample-exact
-audio. There is no AI inside the tool — the creativity is yours.
+into MIDI, MakeCode songs, and rendered audio. Same input → byte-identical
+MIDI / MakeCode hex, sample-exact audio. There is no AI inside the tool —
+the creativity is yours.
 
 Pipeline: `scene.yaml → validate → (lint) → build → .ogg/.wav + meta.json (+ stems/)`
+MakeCode: `scorekit makecode scene.yaml -o song.ts` → `.ts` + `.meta.json`
 
 ## Setup check
 
@@ -74,7 +77,11 @@ or pass an explicit file to override it.
    Add `--stems` for per-track files in `out/scene.ogg.stems/` (adaptive
    game audio), `--renderer timidity` for the alternate backend. Non-loop
    scenes get a reverb tail (`--tail`, default 4s). A scene declaring
-   `textures` also needs `--texture-profile <file>`.
+   `textures` also needs `--texture-profile <file>`. For MakeCode Arcade
+   or micro:bit V2, compile instead with
+   `scorekit makecode scene.yaml -o song.ts` (no renderer; do not use
+   `humanize`, `glide`, clip CC/`pitch_bend`, or `textures`; keep bass
+   out of the sub-bass register so PWM speakers do not fold).
 7. **Self-audit:** run the arrangement audit ([audit.md](audit.md)) —
    deterministic gates (G1–G5) plus the craft rubric — and fix or justify
    every finding before reporting completion.
diff --git a/skills/scorekit/reference.md b/skills/scorekit/reference.md
index c0adb1c..0e6bb89 100644
--- a/skills/scorekit/reference.md
+++ b/skills/scorekit/reference.md
@@ -1,6 +1,6 @@
 # scorekit reference
 
-Verified against scorekit v0.6. When in doubt, trust the binary:
+Verified against scorekit v0.7.1. When in doubt, trust the binary:
 `scorekit schema` / `scorekit schema --grammar` /
 `scorekit schema --texture-profile` are the live source of truth.
 The normative spec (protocol stance, stability rules, compile semantics)
@@ -25,6 +25,7 @@ Exit codes: `0` ok · `1` io · `2` invalid input / lint violations · `3` missi
 | `texture check <profile>` | certify every declared source exists, decodes, and is audible | `--sample-rate` (44100); reports `sha256`/`duration_seconds`/`frames`/`peak_abs`/`rms` per source; exit 4 if undecodable, 2 for `missing`/`silent`; global `--json` emits the full report |
 | `lint <scene> --grammar <file>` | check scene against aesthetic grammar | — |
 | `midi <scene> -o <out.mid>` | compile to SMF (format 1, PPQ 480) | `--passes` 1..=8 (1), `--solo <track id>`, `--section <name>`; profile-only melodic identities are rejected before writing because no renderer profile is available |
+| `makecode <scene> -o <out.ts>` | compile MakeCode `music.createSong` TypeScript + `.meta.json` | one song per suite section; chip/drum amplitudes follow `intensity` against a 1.2-scale mix budget; rejects `glide`/pitch bends, clip CC automation, `textures`, and sub-255-tick grids (`humanize`); `pan`/`reverb` dropped with WARN |
 | `render <mid> -o <out.wav>` | synthesize WAV | `--soundfont <sf2>` (defaults to `$SCOREKIT_SOUND_LIBRARY_DIR/sf2/MuseScore_General.sf2`) **or** `--sfz <file>` (sfizz, single instrument); `--renderer fluidsynth\|timidity\|sfizz` (fluidsynth), `--sample-rate` 8000..=384000 (44100), `--gain` 0.0..=8.0 (0.8, ignored by sfizz) |
 | `export <in> -o <out>` | FFmpeg convert (.ogg Vorbis / .wav PCM) | `--quality` 0..=10 (5), `--seek-samples` (0), `--take-samples` |
 | `build <scene> -o <out.ogg\|wav>` | full chain + meta.json | default MuseScore General, explicit `--soundfont <sf2>`, **or** `--orchestration <file>` (sfizz only; routes each track's `palette` to a certified leaf renderer profile); `--texture-profile <file>` when `textures` are declared; `--renderer fluidsynth\|timidity\|sfizz`; `--fallback-mode strict\|conservative\|flexible` + `--resolver <config>` (instrument substitution); plus `--stems`, `--tail` 0.0..=3600.0 secs (4.0, non-loop), `--crossfade-ms` 0..=60000 (50, loop seal), `--keep-intermediates` |
diff --git a/src/main.rs b/src/main.rs
index eed0ec6..1096d9c 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -5,6 +5,7 @@ mod doctor;
 mod error;
 mod grammar;
 mod instrument;
+mod makecode;
 mod mcp;
 mod midi;
 mod orchestration;
@@ -99,6 +100,13 @@ enum Command {
         #[arg(long)]
         section: Option<String>,
     },
+    /// Compile a scene to MakeCode `music.createSong` TypeScript source
+    Makecode {
+        scene: PathBuf,
+        /// Output .ts file; a build manifest is written next to it as `<name>.meta.json`
+        #[arg(short, long)]
+        output: PathBuf,
+    },
     /// Render a MIDI file to WAV via a synthesizer backend + SoundFont (or `--sfz` for sfizz)
     Render {
         midi: PathBuf,
@@ -355,6 +363,106 @@ fn compile_midi(
     tools::write_atomic(output, &bytes)
 }
 
+/// Keep a MakeCode/TypeScript-safe identifier: `[a-z0-9_]`, non-leading digit.
+fn makecode_ident(raw: &str) -> String {
+    let mut ident = String::with_capacity(raw.len());
+    for c in raw.chars() {
+        if c.is_ascii_alphanumeric() {
+            ident.push(c.to_ascii_lowercase());
+        } else {
+            ident.push('_');
+        }
+    }
+    if ident.chars().next().is_none_or(|c| c.is_ascii_digit()) {
+        ident.insert(0, '_');
+    }
+    ident
+}
+
+fn compile_makecode(scene_path: &Path, output: &Path) -> Result<String> {
+    let scene = schema::load_scene(scene_path)?;
+    let units = makecode::compile_scene(&scene)?;
+    let stem = output
+        .file_stem()
+        .and_then(|s| s.to_str())
+        .unwrap_or("song");
+    let scene_name = scene_path
+        .file_name()
+        .map(|n| n.to_string_lossy().into_owned())
+        .unwrap_or_default();
+
+    let mut ts = format!(
+        "// Generated by scorekit from {scene_name} — do not edit.\n\
+         // Song format: MakeCode song encoding v0 (music.createSong).\n"
+    );
+    let mut songs = Vec::with_capacity(units.len());
+    for unit in &units {
+        let name = match &unit.section {
+            Some(section) => makecode_ident(&format!("{stem}_{section}")),
+            None => makecode_ident(stem),
+        };
+        ts.push_str(&format!(
+            "let {name} = music.createSong(hex`{}`)\n",
+            unit.song.hex()
+        ));
+        for warning in &unit.song.warnings {
+            eprintln!("WARN makecode: song={name}: {warning}");
+        }
+        let tracks: Vec<serde_json::Value> = unit
+            .song
+            .tracks
+            .iter()
+            .map(|t| {
+                serde_json::json!({
+                    "scene_track": t.scene_track_id,
+                    "instrument": t.instrument,
+                    "makecode_track": t.makecode_track,
+                    "kind": t.kind,
+                    "chip_preset": t.chip_preset,
+                    "octave": t.octave,
+                    "drum_voices": t
+                        .voices
+                        .iter()
+                        .map(|(key, voice)| serde_json::json!({ "key": key, "voice": voice }))
+                        .collect::<Vec<_>>(),
+                    "note_events": t.note_events,
+                })
+            })
+            .collect();
+        songs.push(serde_json::json!({
+            "name": name,
+            "section": unit.section,
+            "loop": unit.looping,
+            "bpm": unit.song.bpm,
+            "beats_per_measure": unit.song.beats_per_measure,
+            "ticks_per_beat": unit.song.ticks_per_beat,
+            "measures": unit.song.measures,
+            "bytes": unit.song.bytes.len(),
+            "tracks": tracks,
+            "warnings": unit.song.warnings,
+        }));
+    }
+    let manifest = serde_json::json!({
+        "schema_version": 1,
+        "target": "makecode-song-v0",
+        "scene": scene_name,
+        "songs": songs,
+    });
+    let mut manifest_bytes = serde_json::to_vec_pretty(&manifest).expect("valid JSON model");
+    manifest_bytes.push(b'\n');
+
+    let meta = output.with_extension("meta.json");
+    tools::write_atomic(output, ts.as_bytes())?;
+    tools::write_atomic(&meta, &manifest_bytes)?;
+    Ok(format!(
+        "wrote {} ({} song{}) and {}",
+        output.display(),
+        units.len(),
+        if units.len() == 1 { "" } else { "s" },
+        meta.display()
+    ))
+}
+
 fn invalid_option(path: &str, message: impl Into<String>) -> error::Error {
     error::Error::Validation {
         path: path.to_owned(),
@@ -653,6 +761,7 @@ fn run(command: &Command, json: bool) -> Result<String> {
             compile_midi(scene, output, *passes, solo.as_deref(), section.as_deref())?;
             Ok(format!("wrote {}", output.display()))
         }
+        Command::Makecode { scene, output } => compile_makecode(scene, output),
         Command::Render {
             midi,
             soundfont,
diff --git a/src/makecode.rs b/src/makecode.rs
new file mode 100644
index 0000000..de1f49b
--- /dev/null
+++ b/src/makecode.rs
@@ -0,0 +1,1305 @@
+//! Score IR → MakeCode song assets (`music.createSong(hex`…`)`).
+//!
+//! The byte layout is pxt's song encoding **version 0**, defined by
+//! `encodeSong`/`decodeSong` in `microsoft/pxt` `pxtlib/music.ts` (MIT) and
+//! played back by the MakeCode `music.sequencer` runtime (micro:bit V2,
+//! Arcade). scorekit only *serializes* synthesizer parameters into that
+//! layout — every sound is synthesized by the MakeCode runtime, so this
+//! module is pure byte assembly, not DSP.
+//!
+//! Pitch model: the runtime's frequency table starts at B0 (≈31 Hz, MIDI 23)
+//! and ends at B8 (≈7902 Hz, MIDI 119), so a MakeCode note number is
+//! `midi_key - 23`. A note byte stores the low six bits of
+//! `note - (octave - 2) * 12`, so each track's pitch window spans 64
+//! semitones positioned by its instrument `octave` field, which this encoder
+//! solves per track from the compiled note range.
+//!
+//! Unrepresentable scene features fail with a structured validation error
+//! (pitch bends / CC automation / textures) or are dropped with an explicit
+//! warning recorded in the build manifest (`pan` / `reverb`).
+
+use crate::composer::{NoteEvent, ScoreIr};
+use crate::error::{Error, Result};
+use crate::schema::{Instrument, Scene, instrument_key};
+
+/// MIDI key of MakeCode note 0 (B0, first entry of the runtime frequency table).
+const MIDI_BASE: u8 = 23;
+/// Highest MIDI key in the runtime frequency table (B8, table index 96).
+const MIDI_MAX: u8 = 119;
+/// Size of one encoded melodic instrument block.
+const INSTRUMENT_BYTES: usize = 28;
+
+// ---------------------------------------------------------------------------
+// Raw song model — a byte-faithful mirror of the version-0 encoding.
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Envelope {
+    pub attack: u16,
+    pub decay: u16,
+    pub sustain: u16,
+    pub release: u16,
+    pub amplitude: u16,
+}
+
+const SILENT_ENVELOPE: Envelope = Envelope {
+    attack: 0,
+    decay: 0,
+    sustain: 0,
+    release: 0,
+    amplitude: 0,
+};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Lfo {
+    pub frequency: u8,
+    pub amplitude: u16,
+}
+
+const NO_LFO: Lfo = Lfo {
+    frequency: 0,
+    amplitude: 0,
+};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct MelodicInstrument {
+    pub waveform: u8,
+    pub amp: Envelope,
+    pub pitch: Envelope,
+    pub amp_lfo: Lfo,
+    pub pitch_lfo: Lfo,
+    pub octave: u8,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct DrumStep {
+    pub waveform: u8,
+    pub frequency: u16,
+    pub volume: u16,
+    pub duration: u16,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DrumInstrument {
+    pub start_frequency: u16,
+    pub start_volume: u16,
+    pub steps: Vec<DrumStep>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RawEvent {
+    pub start_tick: u16,
+    pub end_tick: u16,
+    /// Encoded note bytes (melodic: windowed pitch + enharmonic flags;
+    /// drums: index into the track's drum list).
+    pub notes: Vec<u8>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RawTrackKind {
+    Melodic(MelodicInstrument),
+    Drums(Vec<DrumInstrument>),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RawTrack {
+    pub id: u8,
+    pub kind: RawTrackKind,
+    pub events: Vec<RawEvent>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RawSong {
+    pub bpm: u16,
+    pub beats_per_measure: u8,
+    pub ticks_per_beat: u8,
+    pub measures: u8,
+    pub tracks: Vec<RawTrack>,
+    /// Optional per-note-event velocity blocks: (track id, one byte per event).
+    pub velocities: Vec<(u8, Vec<u8>)>,
+}
+
+fn push_u16(out: &mut Vec<u8>, value: u16) {
+    out.extend_from_slice(&value.to_le_bytes());
+}
+
+fn encode_instrument(out: &mut Vec<u8>, i: &MelodicInstrument) {
+    out.push(i.waveform);
+    for env in [&i.amp, &i.pitch] {
+        push_u16(out, env.attack);
+        push_u16(out, env.decay);
+        push_u16(out, env.sustain);
+        push_u16(out, env.release);
+        push_u16(out, env.amplitude);
+    }
+    out.push(i.amp_lfo.frequency);
+    push_u16(out, i.amp_lfo.amplitude);
+    out.push(i.pitch_lfo.frequency);
+    push_u16(out, i.pitch_lfo.amplitude);
+    out.push(i.octave);
+}
+
+fn encode_drum(out: &mut Vec<u8>, d: &DrumInstrument) {
+    out.push(d.steps.len() as u8);
+    push_u16(out, d.start_frequency);
+    push_u16(out, d.start_volume);
+    for step in &d.steps {
+        out.push(step.waveform);
+        push_u16(out, step.frequency);
+        push_u16(out, step.volume);
+        push_u16(out, step.duration);
+    }
+}
+
+/// Serialize to the version-0 byte encoding. Pure function of the model;
+/// identical input yields identical bytes.
+pub fn encode_raw(song: &RawSong) -> Vec<u8> {
+    let mut out = Vec::new();
+    out.push(0); // encoding version
+    push_u16(&mut out, song.bpm);
+    out.push(song.beats_per_measure);
+    out.push(song.ticks_per_beat);
+    out.push(song.measures);
+    out.push(song.tracks.len() as u8);
+    for track in &song.tracks {
+        out.push(track.id);
+        match &track.kind {
+            RawTrackKind::Melodic(instrument) => {
+                out.push(0);
+                push_u16(&mut out, INSTRUMENT_BYTES as u16);
+                encode_instrument(&mut out, instrument);
+            }
+            RawTrackKind::Drums(drums) => {
+                out.push(1);
+                let len: usize = drums.iter().map(|d| 5 + 7 * d.steps.len()).sum();
+                push_u16(&mut out, len as u16);
+                for drum in drums {
+                    encode_drum(&mut out, drum);
+                }
+            }
+        }
+        let note_len: usize = track.events.iter().map(|e| 5 + e.notes.len()).sum();
+        push_u16(&mut out, note_len as u16);
+        for event in &track.events {
+            push_u16(&mut out, event.start_tick);
+            push_u16(&mut out, event.end_tick);
+            out.push(event.notes.len() as u8);
+            out.extend_from_slice(&event.notes);
+        }
+    }
+    for (id, velocities) in &song.velocities {
+        out.push(*id);
+        out.extend_from_slice(velocities);
+    }
+    out
+}
+
+pub fn to_hex(bytes: &[u8]) -> String {
+    let mut s = String::with_capacity(bytes.len() * 2);
+    for b in bytes {
+        s.push_str(&format!("{b:02x}"));
+    }
+    s
+}
+
+// ---------------------------------------------------------------------------
+// Decoder — used by tests to prove interoperability with pxt's encoder and
+// by nothing at runtime. Kept next to the encoder so the two cannot drift.
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+struct Reader<'a> {
+    buf: &'a [u8],
+    pos: usize,
+}
+
+#[cfg(test)]
+impl<'a> Reader<'a> {
+    fn u8(&mut self) -> std::result::Result<u8, String> {
+        let v = *self
+            .buf
+            .get(self.pos)
+            .ok_or_else(|| format!("truncated song buffer at byte {}", self.pos))?;
+        self.pos += 1;
+        Ok(v)
+    }
+
+    fn u16(&mut self) -> std::result::Result<u16, String> {
+        let lo = self.u8()?;
+        let hi = self.u8()?;
+        Ok(u16::from_le_bytes([lo, hi]))
+    }
+}
+
+/// Parse version-0 song bytes back into the raw model. Returns a plain
+/// `String` error: this is a test/verification helper, not a CLI surface.
+#[cfg(test)]
+pub fn decode_raw(bytes: &[u8]) -> std::result::Result<RawSong, String> {
+    let mut r = Reader { buf: bytes, pos: 0 };
+    let version = r.u8()?;
+    if version != 0 {
+        return Err(format!("unsupported song encoding version {version}"));
+    }
+    let bpm = r.u16()?;
+    let beats_per_measure = r.u8()?;
+    let ticks_per_beat = r.u8()?;
+    let measures = r.u8()?;
+    let track_count = r.u8()?;
+    let mut tracks = Vec::with_capacity(usize::from(track_count));
+    for _ in 0..track_count {
+        let id = r.u8()?;
+        let flags = r.u8()?;
+        let block_len = usize::from(r.u16()?);
+        let kind = if flags & 1 == 1 {
+            let end = r.pos + block_len;
+            let mut drums = Vec::new();
+            while r.pos < end {
+                let steps = usize::from(r.u8()?);
+                let start_frequency = r.u16()?;
+                let start_volume = r.u16()?;
+                let mut list = Vec::with_capacity(steps);
+                for _ in 0..steps {
+                    list.push(DrumStep {
+                        waveform: r.u8()?,
+                        frequency: r.u16()?,
+                        volume: r.u16()?,
+                        duration: r.u16()?,
+                    });
+                }
+                drums.push(DrumInstrument {
+                    start_frequency,
+                    start_volume,
+                    steps: list,
+                });
+            }
+            if r.pos != end {
+                return Err("drum block length does not match its contents".to_owned());
+            }
+            RawTrackKind::Drums(drums)
+        } else {
+            if block_len != INSTRUMENT_BYTES {
+                return Err(format!(
+                    "melodic instrument block is {block_len} bytes, expected {INSTRUMENT_BYTES}"
+                ));
+            }
+            let waveform = r.u8()?;
+            let mut envs = [SILENT_ENVELOPE; 2];
+            for env in &mut envs {
+                *env = Envelope {
+                    attack: r.u16()?,
+                    decay: r.u16()?,
+                    sustain: r.u16()?,
+                    release: r.u16()?,
+                    amplitude: r.u16()?,
+                };
+            }
+            let amp_lfo = Lfo {
+                frequency: r.u8()?,
+                amplitude: r.u16()?,
+            };
+            let pitch_lfo = Lfo {
+                frequency: r.u8()?,
+                amplitude: r.u16()?,
+            };
+            let octave = r.u8()?;
+            RawTrackKind::Melodic(MelodicInstrument {
+                waveform,
+                amp: envs[0],
+                pitch: envs[1],
+                amp_lfo,
+                pitch_lfo,
+                octave,
+            })
+        };
+        let note_len = usize::from(r.u16()?);
+        let end = r.pos + note_len;
+        let mut events = Vec::new();
+        while r.pos < end {
+            let start_tick = r.u16()?;
+            let end_tick = r.u16()?;
+            let polyphony = usize::from(r.u8()?);
+            let mut notes = Vec::with_capacity(polyphony);
+            for _ in 0..polyphony {
+                notes.push(r.u8()?);
+            }
+            events.push(RawEvent {
+                start_tick,
+                end_tick,
+                notes,
+            });
+        }
+        if r.pos != end {
+            return Err("note block length does not match its contents".to_owned());
+        }
+        tracks.push(RawTrack { id, kind, events });
+    }
+    let mut velocities = Vec::new();
+    while r.pos < bytes.len() {
+        let id = r.u8()?;
+        let track = tracks
+            .iter()
+            .find(|t| t.id == id)
+            .ok_or_else(|| format!("velocity block references unknown track id {id}"))?;
+        let mut vels = Vec::with_capacity(track.events.len());
+        for _ in 0..track.events.len() {
+            vels.push(r.u8()?);
+        }
+        velocities.push((id, vels));
+    }
+    Ok(RawSong {
+        bpm,
+        beats_per_measure,
+        ticks_per_beat,
+        measures,
+        tracks,
+        velocities,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Chip identities — the MakeCode song editor's built-in synth presets
+// (`getEmptySong` in `microsoft/pxt` `pxtlib/music.ts`, MIT). These are the
+// target platform's own curated voices; scorekit maps its portable
+// instrument vocabulary onto them and reports the choice per track.
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Chip {
+    Dog,
+    Duck,
+    Cat,
+    Fish,
+    Car,
+    Computer,
+    Burger,
+    Cherry,
+    Lemon,
+}
+
+impl Chip {
+    fn name(self) -> &'static str {
+        match self {
+            Chip::Dog => "dog",
+            Chip::Duck => "duck",
+            Chip::Cat => "cat",
+            Chip::Fish => "fish",
+            Chip::Car => "car",
+            Chip::Computer => "computer",
+            Chip::Burger => "burger",
+            Chip::Cherry => "cherry",
+            Chip::Lemon => "lemon",
+        }
+    }
+
+    /// Editor preset parameters; `octave` is a placeholder the encoder
+    /// re-solves per track from the compiled note range.
+    fn params(self) -> MelodicInstrument {
+        let env = |attack, decay, sustain, release| Envelope {
+            attack,
+            decay,
+            sustain,
+            release,
+            amplitude: 1024,
+        };
+        let penv = |attack, decay, sustain, release, amplitude| Envelope {
+            attack,
+            decay,
+            sustain,
+            release,
+            amplitude,
+        };
+        let lfo = |frequency, amplitude| Lfo {
+            frequency,
+            amplitude,
+        };
+        let base = MelodicInstrument {
+            waveform: 0,
+            amp: SILENT_ENVELOPE,
+            pitch: SILENT_ENVELOPE,
+            amp_lfo: NO_LFO,
+            pitch_lfo: NO_LFO,
+            octave: 4,
+        };
+        match self {
+            Chip::Dog => MelodicInstrument {
+                waveform: 1,
+                amp: env(10, 100, 500, 100),
+                pitch_lfo: lfo(5, 0),
+                ..base
+            },
+            Chip::Duck => MelodicInstrument {
+                waveform: 15,
+                amp: env(5, 530, 705, 450),
+                pitch: penv(5, 40, 0, 100, 40),
+                amp_lfo: lfo(3, 20),
+                pitch_lfo: lfo(6, 2),
+                ..base
+            },
+            Chip::Cat => MelodicInstrument {
+                waveform: 12,
+                amp: env(150, 100, 365, 400),
+                pitch: penv(120, 300, 0, 100, 50),
+                pitch_lfo: lfo(10, 6),
+                ..base
+            },
+            Chip::Fish => MelodicInstrument {
+                waveform: 1,
+                amp: env(220, 105, 1024, 350),
+                amp_lfo: lfo(5, 100),
+                pitch_lfo: lfo(1, 4),
+                ..base
+            },
+            Chip::Car => MelodicInstrument {
+                waveform: 16,
+                amp: env(5, 100, 1024, 30),
+                pitch_lfo: lfo(10, 4),
+                ..base
+            },
+            Chip::Computer => MelodicInstrument {
+                waveform: 15,
+                amp: env(10, 100, 500, 10),
+                ..base
+            },
+            Chip::Burger => MelodicInstrument {
+                waveform: 1,
+                amp: env(10, 100, 500, 100),
+                ..base
+            },
+            Chip::Cherry => MelodicInstrument {
+                waveform: 2,
+                amp: env(10, 100, 500, 100),
+                ..base
+            },
+            Chip::Lemon => MelodicInstrument {
+                waveform: 14,
+                amp: env(5, 70, 870, 50),
+                pitch: penv(10, 45, 0, 100, 20),
+                amp_lfo: lfo(1, 50),
+                pitch_lfo: lfo(2, 1),
+                ..base
+            },
+        }
+    }
+}
+
+/// Curated identity mapping: portable instrument vocabulary → the closest of
+/// the nine MakeCode chip voices. Percussion identities return `None` and
+/// route through the drum-kit mapping instead. Every choice is reported in
+/// the build manifest, so a substitution is always visible, never silent.
+fn chip_for(instrument: Instrument) -> Option<Chip> {
+    use Instrument::*;
+    Some(match instrument {
+        // Plain triangle, balanced envelope: keyboards and pure-tone winds.
+        Piano | BrightPiano | Epiano | Celesta | Recorder | Whistle | Ocarina => Chip::Dog,
+        // Bright square with pitch attack: brass and square leads.
+        Trumpet | Trombone | Horn | Brass | SynthBrass | Sax | SquareLead => Chip::Duck,
+        // Soft square, slow attack, vibrato: bowed strings and expressive winds.
+        Flute | Piccolo | PanFlute | Oboe | EnglishHorn | Clarinet | Bassoon | Violin | Viola
+        | Erhu | Dizi | Ney | Duduk | Shakuhachi => Chip::Cat,
+        // Full-sustain triangle with slow tremolo: sections, pads and voices.
+        Strings | SlowStrings | SynthStrings | TremoloStrings | Cello | Contrabass | Choir
+        | Voice | Pad | WarmPad | ChoirPad | BowedPad | HaloPad | SweepPad => Chip::Fish,
+        // Instant attack, full sustain: organ-family sustain.
+        Organ | Accordion => Chip::Car,
+        // Short low square: bass family.
+        Bass | PickedBass | FretlessBass | SlapBass | SynthBass => Chip::Computer,
+        // Plain low triangle: dark, round low voices.
+        Tuba | Timpani => Chip::Burger,
+        // Sawtooth: bright, buzzy sustain.
+        SawLead | Harpsichord | Clavinet => Chip::Cherry,
+        // Plucked square with a pitch blip: plucked strings and mallets.
+        Guitar | SteelGuitar | ElectricGuitar | MutedGuitar | Harp | Pizzicato | MusicBox
+        | Glockenspiel | Vibraphone | Marimba | Xylophone | TubularBells | Pipa | Guzheng
+        | Shamisen | Sitar | Oud => Chip::Lemon,
+        Drums | Tabla => return None,
+    })
+}
+
+/// The MakeCode song editor's built-in drum synth definitions
+/// (`getEmptySong` in `microsoft/pxt` `pxtlib/music.ts`, MIT).
+struct DrumPreset {
+    name: &'static str,
+    start_frequency: u16,
+    start_volume: u16,
+    steps: &'static [DrumStep],
+}
+
+macro_rules! steps {
+    ($(($w:expr, $f:expr, $v:expr, $d:expr)),* $(,)?) => {
+        &[$(DrumStep { waveform: $w, frequency: $f, volume: $v, duration: $d }),*]
+    };
+}
+
+const NEUTRAL_KICK: DrumPreset = DrumPreset {
+    name: "neutral kick",
+    start_frequency: 100,
+    start_volume: 1024,
+    steps: steps![(3, 120, 1024, 10), (3, 1, 0, 100)],
+};
+const THUMP_1: DrumPreset = DrumPreset {
+    name: "thump 1",
+    start_frequency: 200,
+    start_volume: 1024,
+    steps: steps![(4, 200, 15, 100), (4, 150, 0, 200)],
+};
+const THUMP_2: DrumPreset = DrumPreset {
+    name: "thump 2",
+    start_frequency: 450,
+    start_volume: 1024,
+    steps: steps![(4, 350, 15, 100), (4, 300, 0, 100)],
+};
+const SNARE_1: DrumPreset = DrumPreset {
+    name: "snare 1",
+    start_frequency: 175,
+    start_volume: 1024,
+    steps: steps![
+        (1, 200, 1024, 10),
+        (1, 150, 1024, 20),
+        (5, 1, 100, 20),
+        (5, 1, 0, 300),
+    ],
+};
+const SNARE_2: DrumPreset = DrumPreset {
+    name: "snare 2",
+    start_frequency: 220,
+    start_volume: 1024,
+    steps: steps![
+        (1, 250, 1024, 10),
+        (1, 200, 1024, 20),
+        (5, 2000, 100, 20),
+        (5, 2000, 0, 200),
+    ],
+};
+const HAT_1: DrumPreset = DrumPreset {
+    name: "hat 1",
+    start_frequency: 400,
+    start_volume: 500,
+    steps: steps![(5, 450, 500, 10), (5, 400, 20, 20)],
+};
+const HAT_2: DrumPreset = DrumPreset {
+    name: "hat 2",
+    start_frequency: 400,
+    start_volume: 0,
+    steps: steps![(5, 450, 500, 5), (5, 900, 5, 50), (5, 900, 0, 250)],
+};
+const HAT_4: DrumPreset = DrumPreset {
+    name: "hat 4",
+    start_frequency: 400,
+    start_volume: 0,
+    steps: steps![
+        (5, 450, 500, 5),
+        (5, 900, 200, 100),
+        (5, 900, 5, 200),
+        (5, 900, 0, 500),
+    ],
+};
+const DOUBLE_HAT: DrumPreset = DrumPreset {
+    name: "double hat",
+    start_frequency: 3500,
+    start_volume: 1024,
+    steps: steps![
+        (4, 4000, 0, 10),
+        (4, 3500, 800, 1),
+        (4, 4000, 0, 40),
+        (4, 3500, 400, 1),
+        (4, 4000, 0, 40),
+    ],
+};
+const METALLIC: DrumPreset = DrumPreset {
+    name: "metallic",
+    start_frequency: 2000,
+    start_volume: 1024,
+    steps: steps![(4, 1800, 15, 100), (4, 1800, 0, 200)],
+};
+const LOW_TOM: DrumPreset = DrumPreset {
+    name: "low tom",
+    start_frequency: 200,
+    start_volume: 200,
+    steps: steps![(14, 125, 200, 25), (14, 100, 15, 50), (14, 120, 0, 250)],
+};
+const MID_TOM: DrumPreset = DrumPreset {
+    name: "mid tom",
+    start_frequency: 300,
+    start_volume: 200,
+    steps: steps![(14, 225, 200, 25), (14, 200, 15, 50), (14, 220, 0, 250)],
+};
+const HI_TOM: DrumPreset = DrumPreset {
+    name: "hi tom",
+    start_frequency: 500,
+    start_volume: 200,
+    steps: steps![(14, 425, 200, 25), (14, 400, 15, 50), (14, 420, 0, 250)],
+};
+const LO_TOM_2: DrumPreset = DrumPreset {
+    name: "lo tom 2",
+    start_frequency: 200,
+    start_volume: 1024,
+    steps: steps![(1, 75, 0, 200)],
+};
+const MID_TOM_2: DrumPreset = DrumPreset {
+    name: "mid tom 2",
+    start_frequency: 300,
+    start_volume: 1024,
+    steps: steps![(1, 200, 0, 200)],
+};
+const HI_TOM_2: DrumPreset = DrumPreset {
+    name: "hi tom 2",
+    start_frequency: 400,
+    start_volume: 1024,
+    steps: steps![(1, 300, 0, 200)],
+};
+const CYMBAL: DrumPreset = DrumPreset {
+    name: "cymbal",
+    start_frequency: 2500,
+    start_volume: 1024,
+    steps: steps![(4, 2500, 100, 150), (4, 2550, 0, 500)],
+};
+const CRASH_1: DrumPreset = DrumPreset {
+    name: "crash 1",
+    start_frequency: 3000,
+    start_volume: 1024,
+    steps: steps![(4, 3000, 100, 300), (4, 3060, 0, 500)],
+};
+const BUZZER: DrumPreset = DrumPreset {
+    name: "buzzer",
+    start_frequency: 2000,
+    start_volume: 1024,
+    steps: steps![(16, 2000, 100, 150), (16, 2000, 0, 200)],
+};
+
+/// Curated GM-percussion-key → MakeCode drum voice mapping. Covers every key
+/// the composer and the percussion clip vocabulary can emit; an unknown key
+/// is a structured error, never a silent substitution.
+fn drum_for(gm_key: u8) -> Option<&'static DrumPreset> {
+    Some(match gm_key {
+        36 => &NEUTRAL_KICK, // kick / tabla dha
+        37 => &THUMP_1,      // tabla dhin (GM side stick)
+        38 => &SNARE_1,      // snare / tabla tin
+        39 => &SNARE_2,      // clap / tabla ta
+        42 => &HAT_1,        // closed hat
+        44 => &HAT_2,        // pedal hat
+        45 => &LOW_TOM,      // low tom
+        46 => &HAT_4,        // open hat
+        47 => &MID_TOM,      // mid tom
+        49 => &CRASH_1,      // crash
+        50 => &HI_TOM,       // high tom
+        51 => &CYMBAL,       // ride
+        54 => &DOUBLE_HAT,   // tambourine
+        56 => &METALLIC,     // cowbell
+        60 => &HI_TOM_2,     // high bongo
+        61 => &MID_TOM_2,    // low bongo
+        62 => &THUMP_2,      // mute high conga
+        63 => &HI_TOM_2,     // open high conga
+        64 => &LO_TOM_2,     // low conga
+        65 => &HI_TOM,       // high timbale
+        66 => &LOW_TOM,      // low timbale
+        67 => &METALLIC,     // high agogo
+        68 => &BUZZER,       // low agogo
+        69 => &HAT_2,        // cabasa
+        70 => &HAT_1,        // maracas
+        _ => return None,
+    })
+}
+
+impl From<&DrumPreset> for DrumInstrument {
+    fn from(preset: &DrumPreset) -> Self {
+        DrumInstrument {
+            start_frequency: preset.start_frequency,
+            start_volume: preset.start_volume,
+            steps: preset.steps.to_vec(),
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Compilation: Score IR → RawSong + per-track report.
+// ---------------------------------------------------------------------------
+
+#[derive(Debug)]
+pub struct TrackReport {
+    pub scene_track_id: String,
+    pub instrument: String,
+    pub makecode_track: u8,
+    /// "melodic" or "drums".
+    pub kind: &'static str,
+    pub chip_preset: Option<&'static str>,
+    pub octave: Option<u8>,
+    /// GM key → MakeCode drum voice name, in drum-list order.
+    pub voices: Vec<(u8, &'static str)>,
+    pub note_events: usize,
+}
+
+#[derive(Debug)]
+pub struct EncodedSong {
+    pub bytes: Vec<u8>,
+    pub bpm: u16,
+    pub beats_per_measure: u8,
+    pub ticks_per_beat: u8,
+    pub measures: u8,
+    pub tracks: Vec<TrackReport>,
+    pub warnings: Vec<String>,
+}
+
+impl EncodedSong {
+    pub fn hex(&self) -> String {
+        to_hex(&self.bytes)
+    }
+}
+
+fn gcd(mut a: u32, mut b: u32) -> u32 {
+    while b != 0 {
+        (a, b) = (b, a % b);
+    }
+    a
+}
+
+/// MakeCode Arcade / micro:bit speakers clip hard when several full-scale
+/// chip voices stack. The song editor's own 4-track songs sit around
+/// 220–384 / 1024 per voice; we budget ~1.2 full-scale across the mix and
+/// then apply the scene track's intensity.
+fn mix_amplitude(preset: u16, intensity: f32, active_tracks: usize) -> u16 {
+    let n = active_tracks.max(1) as f32;
+    let budget = 1200.0 / n;
+    let scaled = f32::from(preset) / 1024.0 * budget * intensity.clamp(0.05, 1.0);
+    scaled.round().clamp(48.0, 1024.0) as u16
+}
+
+fn scale_instrument(instrument: &mut MelodicInstrument, intensity: f32, active_tracks: usize) {
+    instrument.amp.amplitude = mix_amplitude(instrument.amp.amplitude, intensity, active_tracks);
+}
+
+fn scale_drum(drum: &mut DrumInstrument, intensity: f32, active_tracks: usize) {
+    let gain = f32::from(mix_amplitude(1024, intensity, active_tracks)) / 1024.0;
+    let scale = |v: u16| ((f32::from(v) * gain).round() as u16).clamp(0, 1024);
+    drum.start_volume = scale(drum.start_volume);
+    for step in &mut drum.steps {
+        step.volume = scale(step.volume);
+    }
+}
+
+fn validation(path: impl Into<String>, message: impl Into<String>) -> Error {
+    Error::Validation {
+        path: path.into(),
+        message: message.into(),
+    }
+}
+
+/// Notes sorted and deduplicated on (tick, key): simultaneous duplicates keep
+/// the longest duration and loudest velocity so the merge is deterministic.
+fn normalized_notes(notes: &[NoteEvent]) -> Vec<NoteEvent> {
+    let mut sorted: Vec<NoteEvent> = notes.to_vec();
+    sorted.sort_by_key(|n| {
+        (
+            n.tick,
+            n.key,
+            std::cmp::Reverse(n.dur),
+            std::cmp::Reverse(n.vel),
+        )
+    });
+    sorted.dedup_by(|next, kept| {
+        if next.tick == kept.tick && next.key == kept.key {
+            kept.dur = kept.dur.max(next.dur);
+            kept.vel = kept.vel.max(next.vel);
+            true
+        } else {
+            false
+        }
+    });
+    sorted
+}
+
+/// Compile one composed scene into MakeCode song bytes.
+pub fn encode_song(scene: &Scene, ir: &ScoreIr) -> Result<EncodedSong> {
+    // 1. Reject features the format has no representation for.
+    for (index, (track, spec)) in ir.tracks.iter().zip(&scene.tracks).enumerate() {
+        if !track.bends.is_empty() {
+            let source = if spec.glide.is_some_and(|g| g > 0.0) {
+                "`glide`"
+            } else {
+                "clip `pitch_bend` automation"
+            };
+            return Err(validation(
+                format!("tracks[{index}]"),
+                format!(
+                    "track `{}` uses {source}; the MakeCode song format has no pitch bends. \
+                     Remove it or target `scorekit build` instead",
+                    spec.id
+                ),
+            ));
+        }
+        if !track.controls.is_empty() {
+            return Err(validation(
+                format!("tracks[{index}]"),
+                format!(
+                    "track `{}` uses clip CC automation lanes; the MakeCode song format has no \
+                     controllers. Remove the automation or target `scorekit build` instead",
+                    spec.id
+                ),
+            ));
+        }
+    }
+
+    // 2. Header fields, with explicit format-limit checks.
+    let beat_ticks = crate::composer::PPQ * 4 / u32::from(ir.ts.den);
+    let bar_ticks = beat_ticks * u32::from(ir.ts.num);
+    let bpm_x4 = u32::from(ir.tempo) * u32::from(ir.ts.den);
+    if !bpm_x4.is_multiple_of(4) {
+        return Err(validation(
+            "tempo",
+            format!(
+                "tempo {} in {}/{} time maps to a fractional MakeCode beats-per-minute; \
+                 use a tempo where tempo*{}/4 is an integer",
+                ir.tempo, ir.ts.num, ir.ts.den, ir.ts.den
+            ),
+        ));
+    }
+    let bpm = bpm_x4 / 4;
+    let bpm: u16 = bpm.try_into().map_err(|_| {
+        validation(
+            "tempo",
+            format!("MakeCode beats-per-minute {bpm} exceeds 65535"),
+        )
+    })?;
+    let measures = ir.total_ticks / bar_ticks;
+    let measures: u8 = measures.try_into().map_err(|_| {
+        validation(
+            "bars",
+            format!("{measures} measures exceed the MakeCode song format cap of 255"),
+        )
+    })?;
+
+    // 3. Solve the coarsest tick grid that represents every onset exactly
+    //    (and every melodic duration; drum voices are one-shots, so their
+    //    IR durations do not constrain the grid).
+    let mut step = beat_ticks;
+    for (track, spec) in ir.tracks.iter().zip(&scene.tracks) {
+        let percussion = spec.instrument.is_percussion();
+        for n in &track.notes {
+            step = gcd(step, n.tick);
+            if !percussion {
+                step = gcd(step, n.dur);
+            }
+        }
+    }
+    if step == 0 {
+        step = beat_ticks;
+    }
+    let ticks_per_beat = beat_ticks / step;
+    let ticks_per_beat: u8 = ticks_per_beat.try_into().map_err(|_| {
+        validation(
+            "tracks",
+            format!(
+                "note timing requires {ticks_per_beat} ticks per beat; the MakeCode song format \
+                 caps at 255. Quantize the material (e.g. remove `performance.humanize`) and retry"
+            ),
+        )
+    })?;
+    let total_mc_ticks = ir.total_ticks / step;
+    if total_mc_ticks > u32::from(u16::MAX) {
+        return Err(validation(
+            "bars",
+            format!("song spans {total_mc_ticks} MakeCode ticks, exceeding the u16 tick range"),
+        ));
+    }
+
+    // 4. Per-track events.
+    let active_tracks = ir
+        .tracks
+        .iter()
+        .filter(|track| !track.notes.is_empty())
+        .count();
+    let mut warnings = Vec::new();
+    let mut tracks = Vec::new();
+    let mut reports = Vec::new();
+    let mut velocities = Vec::new();
+    for (index, (track, spec)) in ir.tracks.iter().zip(&scene.tracks).enumerate() {
+        for (field, set) in [
+            ("pan", spec.pan.is_some()),
+            ("reverb", spec.reverb.is_some()),
+        ] {
+            if set {
+                warnings.push(format!(
+                    "tracks[{index}] (`{}`): `{field}` has no MakeCode representation and was \
+                     dropped from this target",
+                    spec.id
+                ));
+            }
+        }
+        if track.notes.is_empty() {
+            warnings.push(format!(
+                "tracks[{index}] (`{}`): compiled to no notes and was omitted",
+                spec.id
+            ));
+            continue;
+        }
+        let notes = normalized_notes(&track.notes);
+        if notes.len() != track.notes.len() {
+            warnings.push(format!(
+                "tracks[{index}] (`{}`): {} duplicate same-tick note(s) merged",
+                spec.id,
+                track.notes.len() - notes.len()
+            ));
+        }
+        let id = tracks.len() as u8;
+        let percussion = spec.instrument.is_percussion();
+        let (kind, report) = if percussion {
+            build_drum_track(&notes, spec, index, active_tracks)?
+        } else {
+            build_melodic_track(&notes, spec, index, active_tracks)?
+        };
+        let (events, event_velocities) = build_events(&notes, percussion, step, &kind);
+        velocities.push((id, event_velocities));
+        reports.push(TrackReport {
+            makecode_track: id,
+            note_events: events.len(),
+            ..report
+        });
+        tracks.push(RawTrack { id, kind, events });
+    }
+    if tracks.is_empty() {
+        warnings.push("scene compiled to an empty song (no notes on any track)".to_owned());
+    }
+
+    let raw = RawSong {
+        bpm,
+        beats_per_measure: ir.ts.num,
+        ticks_per_beat,
+        measures,
+        tracks,
+        velocities,
+    };
+    Ok(EncodedSong {
+        bytes: encode_raw(&raw),
+        bpm,
+        beats_per_measure: ir.ts.num,
+        ticks_per_beat,
+        measures,
+        tracks: reports,
+        warnings,
+    })
+}
+
+fn build_melodic_track(
+    notes: &[NoteEvent],
+    spec: &crate::schema::Track,
+    index: usize,
+    active_tracks: usize,
+) -> Result<(RawTrackKind, TrackReport)> {
+    let chip = chip_for(spec.instrument).expect("caller checked percussion");
+    let mut min = u8::MAX;
+    let mut max = u8::MIN;
+    for n in notes {
+        if n.key < MIDI_BASE || n.key > MIDI_MAX {
+            return Err(validation(
+                format!("tracks[{index}]"),
+                format!(
+                    "track `{}` plays MIDI key {} at tick {}, outside the MakeCode pitch range \
+                     B0..=B8 (MIDI {MIDI_BASE}..={MIDI_MAX})",
+                    spec.id, n.key, n.tick
+                ),
+            ));
+        }
+        min = min.min(n.key);
+        max = max.max(n.key);
+    }
+    // Position the 64-semitone note window: octave field is defined as
+    // window_base = (octave - 2) * 12 in MakeCode note numbers (MIDI - 23).
+    let base = (min - MIDI_BASE) / 12 * 12;
+    if max - MIDI_BASE - base > 63 {
+        return Err(validation(
+            format!("tracks[{index}]"),
+            format!(
+                "track `{}` spans MIDI keys {min}..={max}; the MakeCode note window covers at \
+                 most 64 semitones per track",
+                spec.id
+            ),
+        ));
+    }
+    let octave = base / 12 + 2;
+    let mut instrument = chip.params();
+    instrument.octave = octave;
+    scale_instrument(&mut instrument, spec.intensity, active_tracks);
+    Ok((
+        RawTrackKind::Melodic(instrument),
+        TrackReport {
+            scene_track_id: spec.id.clone(),
+            instrument: instrument_key(spec.instrument),
+            makecode_track: 0,
+            kind: "melodic",
+            chip_preset: Some(chip.name()),
+            octave: Some(octave),
+            voices: Vec::new(),
+            note_events: 0,
+        },
+    ))
+}
+
+fn build_drum_track(
+    notes: &[NoteEvent],
+    spec: &crate::schema::Track,
+    index: usize,
+    active_tracks: usize,
+) -> Result<(RawTrackKind, TrackReport)> {
+    let mut keys: Vec<u8> = notes.iter().map(|n| n.key).collect();
+    keys.sort_unstable();
+    keys.dedup();
+    let mut drums = Vec::with_capacity(keys.len());
+    let mut voices = Vec::with_capacity(keys.len());
+    for key in &keys {
+        let preset = drum_for(*key).ok_or_else(|| {
+            validation(
+                format!("tracks[{index}]"),
+                format!(
+                    "track `{}` plays GM percussion key {key}, which has no curated MakeCode \
+                     drum voice",
+                    spec.id
+                ),
+            )
+        })?;
+        let mut drum = DrumInstrument::from(preset);
+        scale_drum(&mut drum, spec.intensity, active_tracks);
+        drums.push(drum);
+        voices.push((*key, preset.name));
+    }
+    Ok((
+        RawTrackKind::Drums(drums),
+        TrackReport {
+            scene_track_id: spec.id.clone(),
+            instrument: instrument_key(spec.instrument),
+            makecode_track: 0,
+            kind: "drums",
+            chip_preset: None,
+            octave: None,
+            voices,
+            note_events: 0,
+        },
+    ))
+}
+
+/// Group normalized notes into polyphonic note events on the solved grid.
+/// Chord tones share one event; its end is the longest member's end (drum
+/// events span one grid step — MakeCode drums are one-shots).
+fn build_events(
+    notes: &[NoteEvent],
+    percussion: bool,
+    step: u32,
+    kind: &RawTrackKind,
+) -> (Vec<RawEvent>, Vec<u8>) {
+    let octave = match kind {
+        RawTrackKind::Melodic(instrument) => instrument.octave,
+        RawTrackKind::Drums(_) => 0,
+    };
+    let drum_keys: Vec<u8> = match kind {
+        RawTrackKind::Drums(_) => {
+            let mut keys: Vec<u8> = notes.iter().map(|n| n.key).collect();
+            keys.sort_unstable();
+            keys.dedup();
+            keys
+        }
+        RawTrackKind::Melodic(_) => Vec::new(),
+    };
+    let mut events = Vec::new();
+    let mut velocities = Vec::new();
+    let mut i = 0;
+    while i < notes.len() {
+        let tick = notes[i].tick;
+        let mut j = i;
+        let mut end = 0u32;
+        let mut vel = 0u8;
+        let mut bytes = Vec::new();
+        while j < notes.len() && notes[j].tick == tick {
+            let n = &notes[j];
+            end = end.max(n.tick + n.dur);
+            vel = vel.max(n.vel);
+            let byte = if percussion {
+                drum_keys
+                    .iter()
+                    .position(|k| *k == n.key)
+                    .expect("key collected above") as u8
+            } else {
+                (n.key - MIDI_BASE) - (octave - 2) * 12
+            };
+            bytes.push(byte);
+            j += 1;
+        }
+        let start_tick = (tick / step) as u16;
+        let end_tick = if percussion {
+            start_tick + 1
+        } else {
+            (end / step) as u16
+        };
+        events.push(RawEvent {
+            start_tick,
+            end_tick,
+            notes: bytes,
+        });
+        velocities.push(vel);
+        i = j;
+    }
+    (events, velocities)
+}
+
+// ---------------------------------------------------------------------------
+// Scene-level compilation: one song per suite section (or one for the scene).
+// ---------------------------------------------------------------------------
+
+#[derive(Debug)]
+pub struct SongUnit {
+    /// Section name for suite scenes; `None` for a single-scene song.
+    pub section: Option<String>,
+    pub looping: bool,
+    pub song: EncodedSong,
+}
+
+/// Compile a validated scene into MakeCode songs — one per section for a
+/// suite, otherwise a single song.
+pub fn compile_scene(scene: &Scene) -> Result<Vec<SongUnit>> {
+    if !scene.textures.is_empty() {
+        return Err(validation(
+            "textures",
+            "texture layers are rendered audio and cannot be represented in the MakeCode \
+             synth-song format; remove `textures` or target `scorekit build` instead",
+        ));
+    }
+    let mut units = Vec::new();
+    if scene.sections.is_empty() {
+        units.push(SongUnit {
+            section: None,
+            looping: scene.r#loop,
+            song: encode_song(scene, &crate::composer::compose(scene))?,
+        });
+    } else {
+        for section in &scene.sections {
+            let section_scene = scene.for_section(section);
+            units.push(SongUnit {
+                section: Some(section.name.clone()),
+                looping: section_scene.r#loop,
+                song: encode_song(&section_scene, &crate::composer::compose(&section_scene))?,
+            });
+        }
+    }
+    Ok(units)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn from_hex(hex: &str) -> Vec<u8> {
+        let clean: String = hex.chars().filter(|c| !c.is_whitespace()).collect();
+        (0..clean.len())
+            .step_by(2)
+            .map(|i| u8::from_str_radix(&clean[i..i + 2], 16).expect("valid hex"))
+            .collect()
+    }
+
+    /// Real songs produced by the MakeCode song editor must decode and
+    /// re-encode byte-identically: proof of interoperability with pxt's
+    /// encoder, pinned as golden vectors against upstream format drift.
+    #[test]
+    fn roundtrips_makecode_editor_songs_byte_exactly() {
+        for (name, hex) in [
+            ("patrol", PATROL_BGM),
+            ("combat", COMBAT_BGM),
+            ("boss", BOSS_BGM),
+            ("victory", VICTORY_BGM),
+        ] {
+            let bytes = from_hex(hex);
+            let song = decode_raw(&bytes).unwrap_or_else(|e| panic!("{name}: {e}"));
+            assert_eq!(encode_raw(&song), bytes, "{name} did not roundtrip");
+        }
+    }
+
+    #[test]
+    fn decodes_editor_header_fields() {
+        let song = decode_raw(&from_hex(PATROL_BGM)).unwrap();
+        assert_eq!(song.bpm, 120);
+        assert_eq!(song.beats_per_measure, 4);
+        assert_eq!(song.ticks_per_beat, 8);
+        assert_eq!(song.measures, 4);
+        assert_eq!(song.tracks.len(), 4);
+        let victory = decode_raw(&from_hex(VICTORY_BGM)).unwrap();
+        assert_eq!(victory.bpm, 148);
+        assert_eq!(victory.measures, 2);
+        assert_eq!(victory.tracks.len(), 3);
+    }
+
+    #[test]
+    fn drum_map_covers_every_composer_and_clip_percussion_key() {
+        // Composer patterns: kick 36, snare 38, hat 42, tabla theka 36..=39.
+        for key in [36u8, 37, 38, 39, 42] {
+            assert!(drum_for(key).is_some(), "missing composer key {key}");
+        }
+        // Every percussion-clip voice in the schema vocabulary.
+        use crate::schema::PercussionVoice::*;
+        for voice in [
+            Kick,
+            Snare,
+            Clap,
+            ClosedHat,
+            PedalHat,
+            OpenHat,
+            LowTom,
+            MidTom,
+            HighTom,
+            Crash,
+            Ride,
+            Tambourine,
+            Cowbell,
+            HighBongo,
+            LowBongo,
+            MuteHighConga,
+            OpenHighConga,
+            LowConga,
+            HighTimbale,
+            LowTimbale,
+            HighAgogo,
+            LowAgogo,
+            Cabasa,
+            Maracas,
+        ] {
+            assert!(
+                drum_for(voice.midi_key()).is_some(),
+                "missing clip voice key {}",
+                voice.midi_key()
+            );
+        }
+    }
+
+    #[test]
+    fn mix_amplitude_keeps_four_track_chip_songs_in_editor_range() {
+        let amp = mix_amplitude(1024, 0.75, 4);
+        assert!(
+            (220..=384).contains(&amp),
+            "4-track intensity 0.75 should match MakeCode editor volumes, got {amp}"
+        );
+    }
+
+    #[test]
+    fn octave_window_positions_the_six_bit_note() {
+        // A note at MIDI 60 (C4): MakeCode note 37, window base 36, octave 5.
+        let notes = [NoteEvent {
+            tick: 0,
+            dur: 480,
+            key: 60,
+            vel: 100,
+        }];
+        let kind = RawTrackKind::Melodic(MelodicInstrument {
+            octave: 5,
+            ..Chip::Dog.params()
+        });
+        let (events, velocities) = build_events(&notes, false, 240, &kind);
+        assert_eq!(events.len(), 1);
+        assert_eq!(events[0].start_tick, 0);
+        assert_eq!(events[0].end_tick, 2);
+        assert_eq!(events[0].notes, vec![(60 - 23) - 36]);
+        assert_eq!(velocities, vec![100]);
+    }
+
+    const PATROL_BGM: &str = "0078000408040400001c00010a006400f401640080010000000000000000000000000005000004420000000600012e1000160001311c002000011d20002600013528002e00013830003600013540004600012e50005600012c60006600012968006e00012c70007600012e01001c000f05001202c102c20104010500280000006400280003140006020004c00000000300011204000700011608000b0001190c000f00011d10001300011214001700011618001b0001191c001f00011d20002300011024002700011428002b0001172c002f00011b30003300011034003700011438003b0001173c003f00011b40004300010f44004700011348004b0001174c004f00011a50005300010f54005700011358005b0001175c005f00011a60006300011064006700011468006b0001176c006f00011b70007300011074007700011478007b0001177c007f00011b02001c000c960064006d019001540178002c010000640032000000000a060005300000000e0001f510001e0001f520002e0001fa30003e0001fa40004e0001f350005e0001f360006e0001f870007e0001f403001c0001dc00690000045e01dc00000000000000000000000564000104000360000000010001fc0800090001fc1000110001fc1800190001fc2000210001fc2800290001fc3000310001fc3800390001fc4000410001fc4800490001fc5000510001fc5800590001fc6000610001fc6800690001fc7000710001fc7800790001fc";
+
+    const COMBAT_BGM: &str = "00a0000408040400001c00010a006400f40164008001000000000000000000000000000500000496000000030001250400070001250c000f00012910001300012c14001700012918001b0001251c00200001192000230001272400270001272c002f00012c30003300013034003700012c38003b0001274000430001254400470001254c004f00012950005300012c54005700012958005b0001256000630001276400670001276c006f00012c70007300013074007700012c78007b00012701001c000f05001202c102c20104010500280000006400280003140006020004c00000000300011104000700011508000b0001180c000f00011c10001300011314001700011718001b00011a1c001f00011e20002300011124002700011528002b0001182c002f00011c30003300011334003700011738003b00011a3c003f00011e40004300011144004700011548004b0001184c004f00011c50005300011354005700011758005b00011a5c005f00011e60006300011164006700011568006b0001186c006f00011c70007300011374007700011778007b00011a7c007f00011e02001c000c960064006d019001540178002c010000640032000000000a06000560000000070001f508000f0001f51000170001f818001f0001f82000270001fa28002f0001fa3000370001f838003f0001f44000470001f548004f0001f55000570001f858005f0001f86000670001fa68006f0001fa7000770001f878007f0001f403001c0001dc00690000045e01dc00000000000000000000000564000104000390000000010001fc0800090001fc0c000d0001fc1000110001fc1800190001fc1c001d0001fc2000210001fc2800290001fc2c002d0001fc3000310001fc3800390001fc3c003d0001fc4000410001fc4800490001fc4c004d0001fc5000510001fc5800590001fc5c005d0001fc6000610001fc6800690001fc6c006d0001fc7000710001fc7800790001fc7c007d0001fc";
+
+    const BOSS_BGM: &str = "0068000408040400001c00010a006400f4016400800100000000000000000000000000050000043c0000000700012410001700012418001f00013020002700012e30003700012940004700012448004f00012750005700012960006700012370007700012401001c000f05001202c102c20104010500280000006400280003140006020004c00000000300010c04000700010f08000b0001130c000f00011810001300010b14001700010f18001b0001121c001f00011720002300010c24002700010f28002b0001132c002f00011830003300010b34003700010f38003b0001123c003f00011740004300010c44004700010f48004b0001134c004f00011850005300010b54005700010f58005b0001125c005f00011760006300010c64006700010f68006b0001136c006f00011870007300010b74007700010f78007b0001127c007f00011702001c000c960064006d019001540178002c010000640032000000000a060005300000000f0001f010001f0001f020002f0001f330003f0001f340004f0001ee50005f0001ee60006f0001ef70007f0001ef03001c0001dc00690000045e01dc00000000000000000000000564000104000360000000020001fc0c000e0001fc1000120001fc1c001e0001fc2000220001fc2c002e0001fc3000320001fc3c003e0001fc4000420001fc4c004e0001fc5000520001fc5c005e0001fc6000620001fc6c006e0001fc7000720001fc7c007e0001fc";
+
+    const VICTORY_BGM: &str = "0094000408020300001c00010a006400f401640080010000000000000000000000000005000004300000000700012408000f00012810001700012c18001f00013020002700012c28002f00012830003700012738003f00012401001c000f05001202c102c20104010500280000006400280003140006020004600000000300011004000700011408000b0001170c000f00011c10001300011014001700011418001b0001171c001f00011c20002300011024002700011428002b0001172c002f00011c30003300011034003700011438003b0001173c003f00011c02001c000c960064006d019001540178002c010000640032000000000a060005180000000e0001f410001e0001f820002e0001fa30003e0001f4";
+}
diff --git a/tests/cli.rs b/tests/cli.rs
index cd5e918..3bc7395 100644
--- a/tests/cli.rs
+++ b/tests/cli.rs
@@ -1562,6 +1562,194 @@ fn midi_invalid_scene_leaves_no_partial_file() {
     assert_dir_contains_exactly(dir.path(), &["bad.yaml"]);
 }
 
+// ---- makecode ----
+
+#[test]
+fn makecode_happy_path_writes_song_and_manifest() {
+    let dir = tempfile::tempdir().unwrap();
+    let out = dir.path().join("forest.ts");
+    bin()
+        .arg("makecode")
+        .arg(forest())
+        .arg("-o")
+        .arg(&out)
+        .assert()
+        .success();
+    assert_dir_contains_exactly(dir.path(), &["forest.ts", "forest.meta.json"]);
+
+    let ts = fs::read_to_string(&out).unwrap();
+    assert!(
+        ts.contains("let forest = music.createSong(hex`"),
+        "generated TypeScript declares the song: {ts}"
+    );
+
+    let meta: serde_json::Value =
+        serde_json::from_slice(&fs::read(dir.path().join("forest.meta.json")).unwrap()).unwrap();
+    assert_eq!(meta["target"], "makecode-song-v0");
+    let song = &meta["songs"][0];
+    assert_eq!(song["name"], "forest");
+    assert_eq!(song["bpm"], 92);
+    assert_eq!(song["beats_per_measure"], 4);
+    assert_eq!(song["measures"], 8);
+    assert_eq!(song["loop"], true);
+    let tracks = song["tracks"].as_array().unwrap();
+    assert_eq!(tracks.len(), 4, "all four scene tracks are reported");
+    assert_eq!(tracks[0]["scene_track"], "harmony");
+    assert_eq!(tracks[0]["kind"], "melodic");
+    assert_eq!(tracks[0]["chip_preset"], "fish");
+    let drums = &tracks[3];
+    assert_eq!(drums["kind"], "drums");
+    assert_eq!(drums["drum_voices"][0]["key"], 36);
+    assert_eq!(drums["drum_voices"][0]["voice"], "neutral kick");
+}
+
+#[test]
+fn makecode_matches_golden_source() {
+    let dir = tempfile::tempdir().unwrap();
+    let out = dir.path().join("forest.ts");
+    bin()
+        .arg("makecode")
+        .arg(forest())
+        .arg("-o")
+        .arg(&out)
+        .assert()
+        .success();
+    let produced = fs::read(&out).unwrap();
+    let golden = fs::read(repo("tests/golden/forest.makecode.ts")).unwrap();
+    assert_eq!(
+        produced, golden,
+        "MakeCode source must be identical to the golden file"
+    );
+}
+
+#[test]
+fn makecode_is_deterministic_across_runs() {
+    let dir = tempfile::tempdir().unwrap();
+    for sub in ["a", "b"] {
+        fs::create_dir(dir.path().join(sub)).unwrap();
+        bin()
+            .arg("makecode")
+            .arg(forest())
+            .arg("-o")
+            .arg(dir.path().join(sub).join("forest.ts"))
+            .assert()
+            .success();
+    }
+    for name in ["forest.ts", "forest.meta.json"] {
+        assert_eq!(
+            fs::read(dir.path().join("a").join(name)).unwrap(),
+            fs::read(dir.path().join("b").join(name)).unwrap(),
+            "{name} differs between identical runs"
+        );
+    }
+}
+
+#[test]
+fn makecode_suite_emits_one_song_per_section() {
+    let dir = tempfile::tempdir().unwrap();
+    let out = dir.path().join("suite.ts");
+    bin()
+        .arg("makecode")
+        .arg(repo("examples/scenes/forest_suite.yaml"))
+        .arg("-o")
+        .arg(&out)
+        .assert()
+        .success();
+    let ts = fs::read_to_string(&out).unwrap();
+    for name in [
+        "suite_intro",
+        "suite_explore",
+        "suite_combat",
+        "suite_victory",
+    ] {
+        assert!(
+            ts.contains(&format!("let {name} = music.createSong(hex`")),
+            "missing section song `{name}`: {ts}"
+        );
+    }
+    let meta: serde_json::Value =
+        serde_json::from_slice(&fs::read(dir.path().join("suite.meta.json")).unwrap()).unwrap();
+    let songs = meta["songs"].as_array().unwrap();
+    assert_eq!(songs.len(), 4);
+    assert_eq!(songs[1]["section"], "explore");
+    assert_eq!(songs[1]["loop"], true);
+    assert_eq!(songs[2]["section"], "combat");
+    assert_eq!(songs[2]["bpm"], 132, "section tempo override is honored");
+    assert_eq!(songs[3]["loop"], false);
+}
+
+#[test]
+fn makecode_glide_scene_fails_with_no_partial_artifacts() {
+    let dir = tempfile::tempdir().unwrap();
+    let scene = dir.path().join("glide.yaml");
+    fs::write(
+        &scene,
+        "tempo: 100\nkey: C_major\nbars: 2\nmotifs:\n  m:\n    - { degree: 1, beats: 2 }\n    - { degree: 5, beats: 2 }\ntracks:\n  - id: lead\n    instrument: flute\n    pattern: melody\n    motif: m\n    glide: 0.5\n",
+    )
+    .unwrap();
+    let out = bin()
+        .args(["--json", "makecode"])
+        .arg(&scene)
+        .arg("-o")
+        .arg(dir.path().join("glide.ts"))
+        .assert()
+        .code(2);
+    let error: serde_json::Value =
+        serde_json::from_slice(&out.get_output().stderr).expect("validation error is JSON");
+    assert_eq!(error["field"], "tracks[0]");
+    assert!(
+        error["message"].as_str().unwrap().contains("pitch bends"),
+        "error explains the missing capability: {error}"
+    );
+    assert_dir_contains_exactly(dir.path(), &["glide.yaml"]);
+}
+
+#[test]
+fn makecode_texture_scene_fails_with_no_partial_artifacts() {
+    let dir = tempfile::tempdir().unwrap();
+    let scene = dir.path().join("tex.yaml");
+    fs::write(
+        &scene,
+        "tempo: 100\nkey: C_major\nbars: 2\ntextures:\n  - source: wind\n    mode: loop\ntracks:\n  - id: lead\n    instrument: flute\n    pattern: sustain\n",
+    )
+    .unwrap();
+    let out = bin()
+        .args(["--json", "makecode"])
+        .arg(&scene)
+        .arg("-o")
+        .arg(dir.path().join("tex.ts"))
+        .assert()
+        .code(2);
+    let error: serde_json::Value =
+        serde_json::from_slice(&out.get_output().stderr).expect("validation error is JSON");
+    assert_eq!(error["field"], "textures");
+    assert_dir_contains_exactly(dir.path(), &["tex.yaml"]);
+}
+
+#[test]
+fn makecode_humanized_scene_fails_with_grid_error() {
+    let dir = tempfile::tempdir().unwrap();
+    let scene = dir.path().join("human.yaml");
+    fs::write(
+        &scene,
+        "tempo: 100\nkey: C_major\nbars: 2\nperformance:\n  humanize:\n    timing_ms: 7\n    seed: 42\ntracks:\n  - id: lead\n    instrument: flute\n    pattern: sustain\n",
+    )
+    .unwrap();
+    let out = bin()
+        .arg("makecode")
+        .arg(&scene)
+        .arg("-o")
+        .arg(dir.path().join("human.ts"))
+        .assert()
+        .code(2);
+    let stderr = String::from_utf8_lossy(&out.get_output().stderr).into_owned();
+    assert!(
+        stderr.contains("ticks per beat") && stderr.contains("humanize"),
+        "error names the grid limit and the fix: {stderr}"
+    );
+    assert_dir_contains_exactly(dir.path(), &["human.yaml"]);
+}
+
 // ---- render ----
 
 fn make_midi(dir: &Path) -> PathBuf {
diff --git a/tests/golden/forest.makecode.ts b/tests/golden/forest.makecode.ts
new file mode 100644
index 0000000..9f3627c
--- /dev/null
+++ b/tests/golden/forest.makecode.ts
@@ -0,0 +1,3 @@
+// Generated by scorekit from forest.yaml — do not edit.
+// Song format: MakeCode song encoding v0 (music.createSong).
+let forest = music.createSong(hex`005c000402080400001c0001dc00690000045e01780000000000000000000000056400010400054000000008000303060a08001000030b0f121000180003060a0d18002000030d1114200028000303060a28003000030b0f123000380003060a0d38004000030d111401001c00010a006400f4016400a5000000000000000000000000000005000005800100000100010301000200010602000300010a03000400010604000500010305000600010606000700010a07000800010608000900010b09000a00010f0a000b0001120b000c00010f0c000d00010b0d000e00010f0e000f0001120f001000010f10001100010611001200010a12001300010d13001400010a14001500010615001600010a16001700010d17001800010a18001900010d19001a0001111a001b0001141b001c0001111c001d00010d1d001e0001111e001f0001141f002000011120002100010321002200010622002300010a23002400010624002500010325002600010626002700010a27002800010628002900010b29002a00010f2a002b0001122b002c00010f2c002d00010b2d002e00010f2e002f0001122f003000010f30003100010631003200010a32003300010d33003400010a34003500010635003600010a36003700010d37003800010a38003900010d39003a0001113a003b0001143b003c0001113c003d00010d3d003e0001113e003f0001143f004000011102001c000f0a006400f4010a0087000000000000000000000000000000000003600000000400010304000800010308000c00010b0c001000010b10001400010614001800010618001c00010d1c002000010d20002400010324002800010328002c00010b2c003000010b30003400010634003800010638003c00010d3c004000010d030147000264005a000378005a000a000301000000640004af005a0001c8005a000a000196005a0014000501000900140005010000002c010290012c0005c2012c000a0005900102001400a001000001000200020100020001020200030002010203000400010204000500020002050006000102060007000201020700080001020800090002000209000a0001020a000b000201020b000c0001020c000d000200020d000e0001020e000f000201020f0010000102100011000200021100120001021200130002010213001400010214001500020002150016000102160017000201021700180001021800190002000219001a0001021a001b000201021b001c0001021c001d000200021d001e0001021e001f000201021f0020000102200021000200022100220001022200230002010223002400010224002500020002250026000102260027000201022700280001022800290002000229002a0001022a002b000201022b002c0001022c002d000200022d002e0001022e002f000201022f0030000102300031000200023100320001023200330002010233003400010234003500020002350036000102360037000201023700380001023800390002000239003a0001023a003b000201023b003c0001023c003d000200023d003e0001023e003f000201023f0040000102003a3a3a3a3a3a3a3a0145454545454545454545454545454545454545454545454545454545454545454545454545454545454545454545454545454545454545454545454545454545023e3e3e3e3e3e3e3e3e3e3e3e3e3e3e3e03331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a331a2e1a`)