seedbox/docs/superpowers/specs/2026-10-11-scale-root-design.md

Scale and root selection

2026-10-11. Status: draft for review.

Goal

Let Gee lock the line (bass, melody, pad) to a chosen root and scale, so Seedbox can play along with an existing musical idea. The seed still makes everything else.

Decisions

Question	Answer
Scope	Global and sticky. SEED, ROLL and loading a slot don't change it. Slots don't store it.
Pages	Two: ROOT and SCALE, each with AUTO.
AUTO	The seed picks from all 21 scales and 12 roots. Every existing seed changes scale (an intended music change).
Old data	None kept. It's a prototype, so the flash record starts fresh.

Scales

The menu order is also the table index.

#	Screen name	Steps
0	MAJOR	0 2 4 5 7 9 11
1	MINOR	0 2 3 5 7 8 10
2	DORIAN	0 2 3 5 7 9 10
3	MIXOLYDIAN	0 2 4 5 7 9 10
4	LYDIAN	0 2 4 6 7 9 11
5	PHRYGIAN	0 1 3 5 7 8 10
6	HARM MINOR	0 2 3 5 7 8 11
7	MINOR PENT	0 3 5 7 10
8	MAJOR PENT	0 2 4 7 9
9	PHRYG DOM	0 1 4 5 7 8 10
10	DBL HARM	0 1 4 5 7 8 11
11	HUNG MINOR	0 2 3 6 7 8 11
12	UKR DORIAN	0 2 3 6 7 9 10
13	LYD DOM	0 2 4 6 7 9 10
14	HIRAJOSHI	0 2 3 7 8
15	IN SEN	0 1 5 7 10
16	IWATO	0 1 5 6 10
17	PROMETHEUS	0 2 4 6 9 10
18	WHOLE TONE	0 2 4 6 8 10
19	OCTATONIC	0 1 3 4 6 7 9 10
20	LOCRIAN	0 1 3 5 6 8 10

Scales have 5 to 8 notes. Chords stay "every other scale note" (0, 2, 4 from the chord degree), so:

• 5-note scales give open chords;
• the 6-note whole tone gives augmented chords;
• the 8-note octatonic gives diminished chords.

Engine (sim/engine.js, then firmware/engine/engine.c)

• SCALES and SCALE_NAMES become the 21-entry table above. In C, SCALES[21][8] and SCALE_LEN[21].
• genome(): g.scale = r.below(21). It's still one draw, so every later draw in the genome is unchanged.
• The params get scale (-1 = AUTO, 0..20) and root (-1 = AUTO, 0..11). renderBar overrides g.scale and g.root when they're ≥ 0, right after genome(), the same way AMENIZER overrides steps. In C this is sb_params.scale and sb_params.root.
• describe() and the simulator's "Key" fact show the effective scale and root.
• Integer-only and deterministic, as before.

Vectors

• Run npm run vectors (an intended music change; the commit message says so).
• Add cases to test/cases.js with a fixed scale and root, so the C port is tested on overrides. Cover at least:
  • a 5-note scale;
  • the 8-note OCTATONIC;
  • a root that isn't C;
  • AUTO.

Panel (firmware app/main.c, simulator app.js)

• Pages: SEED · GEN · ROOT · SCALE · BPM · SLOT · ROLL · LEARN.
• ROOT turns through AUTO, C, C#, …, B. SCALE turns through AUTO, MAJOR, …, LOCRIAN. Edit them like GEN: push, turn, push.
• Screen when set: label ROOT / SCALE, value D / HIRAJOSHI.
• Screen on AUTO: label ROOT AUTO / SCALE AUTO, value is what the seed picked.
• A change is heard from the next rendered bar, the same as GEN.

Storage

• live_t gains scale and root, saved in flash. The record version goes to 2. Old records are ignored and defaults load.
• The leftovers from BANK go: the unused record field and pad_t.spare.
• Defaults: both AUTO.
• The simulator keeps them in localStorage next to gen.

Docs

• docs/controls.md: add ROOT and SCALE to the pages table.
• docs/concept.md: the scale list.
• docs/decisions.md: add one line on global sticky key, AUTO over all 21.

Testing

1. npm test passes with the new vectors.
2. cd firmware/test && make test passes.
3. Bench checks:
   • set ROOT D and SCALE HIRAJOSHI, and check the MiniFreak notes stay in D Hirajoshi across several SEEDs;
   • check that AUTO shows the seed's own pick.