Godstrument/ZERO_OMNI_BRIEF.md

ZERO MODE · VIBES · DIMENSIONS · the OMNI panel

Build brief for the implementing model (Opus). Read fully before writing code.

John's ask, verbatim spirit: the full UI is an intense sensory assault. Give people a zero mode — 7 sources left, 7 right, click a slot to see the feeds in that grouping (same colors/chakra energy as the main UI), pick one or more, route them by hand to an output, right-click to assign it (synth role / MIDI / …). They build everything from zero. Save the whole thing as a dimension (a full hardcore scene save); save a specific source→route→output combo as a vibe — "build a vibe, save a vibe, share a vibe". And give OMNI a NICE UI panel.

---

0. Ground rules (unchanged from every Godstrument session)

• Canon: viz/index.html is truth; the grimoire prose inside it must be updated to match whatever ships (never the other way). Regenerate GODSTRUMENT_MANUAL_SOURCE.md with the builder afterwards (build_grimoire.py pattern — carry-forward + dedupe).
• Honesty rule: nothing decorative. Every slot, knob, and control maps to a real feed/dest/tweak. If a thing isn't wired, it doesn't render.
• Verify with your own eyes: preview server + login (invite + /api/signup recipe — see memory godstrument-local-verify), console clean, then screenshot proof.
• Deploy: rsync git-tracked files to botchat (humanjing@100.71.119.27, app dir /home/humanjing/godstrument), never --delete, never push godstrument_users.db / auth_secret / patches/; sudo -n systemctl restart godstrument; curl-verify cache-busted. First load post-deploy is slow (cold start).
• auth.py changes must be additive (new table / new column with default) — the server's SQLite holds real user accounts. Never a destructive migration.
• Commit per milestone with the Co-Authored-By line. Adversarially review at the end (a Workflow, as in previous sessions) and fix confirmed findings before deploy.

1. What already exists — build on it, don't reinvent

Thing	Where (verify at build time)	Use it for
14 concept groups with label, orbit, members	config.json:31-46 ("groups"); grimoire "The vibes — grouping by feeling" (~line 848-900, has the emojis: 💰 wealth, 💧 water, …)	The 7+7 zero slots. They are ALREADY called vibes in canon.
MOODS + applyMood	viz/index.html:2275-2322	The pattern for entering/leaving a named state; zero joins this family
First-visit flow (gs_seen, gs_mood)	viz/index.html:2841-2842	Zero as the new-user front door
serializePatch / loadPatch	viz/index.html:2532-2567	Dimensions ARE this; a blank dimension = {routes:[], …}
addRouteLocal / registerRoute / removeRouteLocal	viz/index.html:2452-2468, 2921	Zero-mode routing + vibe apply/remove
"patch to →" context submenu	viz/index.html:5521	Reuse for assigning a node to an output
Node tweaks (mute/gain/offset), setParamLocal	viz/index.html:2036+, 2451	OMNI panel knobs = views over these
MY PATCHES (account presets, one JSON blob)	auth.py:46 (presets table), :249+ (endpoints); ⚙ panel UI	Rename surface to Dimensions; vibes get a sibling store
CHAKRAS (colors)	viz/index.html:3427	The zero-slot color language
Arranger panel (arrbtn, resizable, tabbed)	viz/index.html:1497+, 2325-2330	The UI pattern for the OMNI panel
KEY_ACTIONS + remappable keys	viz/index.html:~6060-6110	Key bindings for zero + OMNI panel
quantize option on routes	viz/index.html:1398, 2415	The "assign like a synth roll" — note outputs get scale/root/octaves

Extraction discipline: before each milestone, re-verify the exact lines above (they drift) and extract any formula/shape you depend on into code comments citing viz/index.html:LINE.

2. ZERO MODE — dimension zero

Concept: a fourth entry in the mood family, but deeper: not muted — empty. No cables, no voices sounding, the field silent and almost blank. The user builds the entire instrument by hand, one cable at a time. Leaving zero (to any mood / the storm) restores the full factory experience.

Entry & exit

• Right-click sky → 0 zero — build from nothing (top of the mood submenu), plus a key (suggest F11 or a free slot in DEFAULT_KEYS; check collisions).
• First-visit choice card (replaces the current silent default into first light): three big options — 🌱 start from zero (build it yourself) · 🌅 first light (a gentle song) · ⛈ the full storm (everything at once). Persist choice like gs_mood. Returning users keep whatever they last used.
• Entering zero: snapshot the current patch to a holding slot (localStorage gs_prezero) so exiting zero can offer "restore what you had" vs "keep my build". Implementation: loadPatch({routes: [], tweaks: {}, seqs: {}, …}) + a zeroMode UI flag. Do NOT touch the hub or other users — this is all client-local, like moods.

The zero UI (the whole point: calm)

• Hide the full node field. Render instead:
  • 7 slots down the left, 7 down the right — the 14 groups from config.json in a fixed, curated order (suggest: left = the elements/feelings: light, dark, fire, water, earth, air, spirit · right = the domains: planet, cosmos, heavens, human, market, wealth, summer). Each slot: a colored ring (its chakra/vibe hue — extract or define a GROUP_HUES map; the grimoire's vibe emojis are the seed), the label, and a live "breathing" glow driven by the group's average member value (already computed for group nodes) — alive but quiet.
  • A center stage — empty at first. Nodes the user builds land here.
  • An output rack along the bottom (or right-center column): the destinations, grouped and labeled in plain language:
    • OMNI voices: lead (sings) · bass (roots) · pad (glows) · drone (hums) · perc (taps)
    • OMNI space & grit: reverb.size · delay.feedback · saturation · glitch · granular.density · crush · wavetable.morph · lfo.rate · master.space · filter.cutoff
    • 🌀 earth echo knobs (echo.*) — shown only when earth echo is on
    • MIDI (when an out port is enabled): the CC map + lead/bass note channels Each output is a small labeled socket, dark until something is patched into it.
• Slot → picker drawer: clicking a slot slides open a drawer listing that group's member feeds: name, one-line plain-English description (extract from the grimoire source blurbs / signals labels), live value bar, chakra color. Each row has ⊕. Picking 1+ feeds creates a node on the stage (or adds to the slot's existing node). The node renders like a mini group-node: the slot's color, member count badge.
• Routing: drag from a node to an output socket → lays a cable per member feed to that dest at a sensible default amount (0.5, curve lin) — reusing addRouteLocal. Alternatively right-click node → the existing "patch to →" submenu filtered to the rack outputs. Cables render exactly like the main UI (same renderer — don't fork it).
• Right-click assign (the "synth roll" ask): right-click an output socket or a cable →
  • note outputs (lead.note/bass.note): quantize picker — scale (the 11 SCALES), root (note name picker), octaves (1-3); presets "minor pent @C4" etc.
  • CC/level outputs: amount slider + curve picker (lin/exp/exp3/log/scurve/inv) — the existing route controls, surfaced.
  • MIDI: choose CC number / channel (when midi enabled).
• Guidance, not tutorial: use the existing eventTicker for 3-4 contextual nudges ("pick a source from a ring", "now drag it onto a voice", "press ♪ — that's YOUR instrument"). No modal tutorial. The calm IS the feature.
• Graduation: a small "⛈ enter the storm" affordance; leaving zero shows the full field with everything the user built still wired (their routes persist — zero is not a sandbox, it's the same matrix).

Acceptance criteria (Z-AC)

From a fresh account in zero mode, with no instructions beyond the ticker nudges, this sequence works in under a minute and makes sound: click a ring → pick sun.speed → drag node to filter.cutoff; click another → pick crypto.price → drag to lead → right-click lead → minor pent @ 60 → press ♪ → bitcoin sings through a sun-opened filter. Verified in the preview with a screenshot; console clean; leaving zero → first light works; re-entering zero offers restore.

3. VIBES — build a vibe, save a vibe, share a vibe

A vibe = a small, additive, shareable bundle of wiring:

{ "v": 1, "name": "sun filter", "emoji": "☀️",
  "routes": [{"source": "sun.speed", "dest": "filter.cutoff", "amount": 0.85, "curve": "exp"},
             {"source": "crypto.price", "dest": "lead.note", "amount": 1.0,
              "quantize": {"scale": "minor_pent", "root": 60, "octaves": 2}}] }

• Apply = additive (registerRoute upserts; nothing else touched). Tag applied routes with viaVibe: "<name>" so a vibe can be toggled off (remove exactly the routes it added — removeRouteLocal). Multiple vibes stack; a route present in two stays until both are off.
• Save a vibe: in zero mode, "💾 save as vibe" on the stage selection (or the whole current zero build); in the full UI, right-click a node → "save these cables as a vibe". Named + emoji.
• Store: account-side, in auth.py — additive migration: either a new vibes table mirroring presets, or a kind column on presets defaulting 'dimension'. Endpoints mirror the preset ones (list/save/delete). Local fallback to localStorage when signed out.
• Share: two mechanisms, both v1:
  1. Vibe code: compact string GSV1.<base64url(json)> — "copy vibe code" puts it on the clipboard; an "import vibe" box (⚙ panel + zero mode) accepts a pasted code.
  2. URL fragment: godstrument.pro/#vibe=GSV1.... — on load (post-login), offer "apply the vibe you were sent?" Never auto-apply; show its name + route count first. (Fragment never reaches the server — clean with the invite-only model.)
• Validation: parse defensively — unknown sources/dests in an imported vibe are listed and skipped, not errors. Cap: 32 routes per vibe.

Vibes AC

Save a 2-route vibe, toggle it off/on, copy its code, hard-reload, import the code, apply — identical wiring returns. A vibe code from another account applies cleanly.

4. DIMENSIONS — the full scene save

• Rename the user-facing surface: ⚙ "MY PATCHES" → "DIMENSIONS" ("a dimension is the whole world you built — every cable, mix, groove, tempo, key"). Same serializePatch blob, same endpoints — this is a naming + framing change; do NOT break existing saved presets (they simply appear as dimensions).
• Zero mode ships with the blank state as "dimension zero" (a virtual, always- available entry at the top of the list — not stored, generated).
• Grimoire: rewrite the "Saving your instrument" section for the dimension/vibe split: a dimension is everything; a vibe is a feeling you can hand to a friend.

5. The OMNI panel

A dedicated synth panel, sibling to the tracks panel (same open/close/resize pattern — arrbtn precedent). Button: 🎹 OMNI bottom-right next to 🎛 tracks; key-bindable.

• Layout — a synth, not a mixer: module strips:
  • VOICE: the pluck voice selector — FM tine · 🎸 string · 🎛 GODSONIQ (with a "sample 3s" button + sampling state) — wired to Synth.stringVoice() / Synth.godsoniq() / Synth.sampling(); plus 🌐 tab feed toggle.
  • LEAD (wavetable.morph knob) · BASS · PAD (pad.brightness) · DRONE (drone.voices; a small "7.83 Hz" schumann lamp when earth echo is on) · PERC (perc.density).
  • FX RACK: filter.cutoff · reverb.size · delay.feedback · saturation · glitch · granular.density · crush · lfo.rate · master.space (+ chorus shown as a fixed, labeled, non-decorative indicator — it IS always on; label it honestly).
  • 🌀 EARTH ECHO: on/off + the six echo.* knobs (only enabled when on).
  • TRANSPORT: ♪ toggle, mood selector, the current scale (from gScale, click → scale picker), BPM readout linked to godtime.
• Knob semantics (the crucial design): every knob shows the live world-driven value as an animated arc (from the dest's current value — the world's hand). Dragging a knob adjusts the dest's tweak gain/offset (existing setParamLocal machinery) — you're riding a fader the world is also pushing. Double-click resets the tweak to neutral (the ⌘⇧-click semantic). A small dot shows when a knob has a user tweak. Right-click a knob = the node's existing context menu (mute/solo/level/ cables/patch to). No new audio paths — the panel is a view over dests + tweaks.
• Muted dests render dim; a grooved/p-locked dest shows a tiny grid icon.
• Works inside zero mode too (it doubles as zero's output rack detail view — if this is cleanly achievable, the rack and the panel share components; if not, keep them separate and simple).

OMNI AC

Open the panel: every knob's arc moves with live data; drag reverb.size up — audibly more reverb and the dest tweak persists in the saved dimension; voice selector swaps FM→string→GODSONIQ and plucks confirm; screenshot for the session log; console clean.

6. Milestones (each: build → verify in preview → commit)

• Z0 — blank dimension + zero entry/exit + first-visit choice card + prezero restore.
• Z1 — 7+7 slots + picker drawer + stage nodes (no routing yet). Colors/labels/live glow.
• Z2 — routing to the output rack + right-click assign (quantize/curve/amount) + ticker nudges. Z-AC passes.
• Z3 — vibes: tag/apply/toggle, save to account (additive auth.py migration), vibe code export/import + #vibe= fragment. Vibes AC passes.
• Z4 — dimensions rename + dimension-zero entry + grimoire "Saving" rewrite.
• Z5 — OMNI panel. OMNI AC passes.
• Z6 — grimoire sections (zero mode gets its own tech-manual section in the style of OMNI/Earth Echo/GODSONIQ: numbered how-to + spec table), regenerate the manual, adversarial review workflow over the whole feature set, fix confirmed findings, deploy to botchat, curl-verify live, update memory.

7. Risks & taste notes

• viz/index.html is ~7.5k lines of interlocking IIFE — add new sections as their own IIFEs near their dependencies; do not restructure existing code to "make room".
• The 14-group order and hues are a taste call — propose them, note them as one-line consts John can retune by ear/eye (the skins pattern).
• Zero mode must never fork the matrix/renderer: same routes, same cables, same synth. If zero starts needing its own compute path, stop — the design has gone wrong.
• Don't gate existing users into zero — it's a door, not a wall. gs_mood returning users land where they left off.
• Keep the first-visit card copy short and Godstrument-voiced. No onboarding-speak.

---

STATUS + CONTINUATION (Fable review, 2026-07-10)

Z0–Z2 verified and approved (commits 2a705e3, d30cea4, 4e44533, 9a7f947): the three-door card, the calm 7+7 ring field, spinning orbs, drag-to-route, the synth-roll assign menu — all live-verified, Z-AC met (bitcoin sang through a sun-opened filter from zero), console clean, syntax clean, field-draw correctly guarded. Genuinely good work.

Continue from here, in this order:

C1. Fix: leaving zero silently DISCARDS the user's build (real bug)

exitZeroToMood always restores gs_prezero, replacing routesArr — so a user who built cables in zero and clicks "first light" loses their build with no warning. The brief's intent (§2 graduation): "leaving zero shows the full field with everything the user built still wired." Fix: on exit, if the current (zero-built) patch has ≥1 route, offer a small three-way choice (same visual language as the door card, but compact):

• keep my build — don't restore prezero; just drop the overlay + apply the mood's mutes/gains only (the build stays as the whole patch);
• bring the old world back — current behavior (restore prezero);
• weave them together — restore prezero THEN re-registerRoute the zero-built routes on top (registerRoute dedups by source|dest). If the zero build has 0 routes, skip the prompt entirely (current behavior is right).

C2. Zero build must survive a reload

Routes persist via the matrix, but zeroUI.nodes (picked feeds / stage orbs) don't — a returning zero-user (gs_mood="0 zero") reloads into an empty stage even though their cables exist. Persist the picks to localStorage (gs_zeronodes: {group: [srcKeys]}) on every pick/route; restore in zeroUI.open(). Also reconstruct socket lit-state (already done via refreshSockets) — verify with a reload test.

C3. Orb interactions beyond drag (touch + depth)

HTML5 drag doesn't exist on touch, and orbs currently have no menu:

• Tap-to-patch fallback: click/tap an orb → it "arms" (glow ring, cursor hint); click a socket → routeGroup(armed, dest); click elsewhere → disarm. Keep drag working.
• Right-click an orb → small menu: member list with × to remove a feed, "unpatch everything from this orb", and (stub for Z3) "💾 save as vibe". Removing the last member removes the orb.
• ⛈ graduation affordance: a small fixed "⛈ enter the storm" pill inside the zero UI (bottom-right above the rack) → runs the C1 exit flow with mood "the full storm".

C4 = Z3 (vibes), Z5 (OMNI panel), Z4 (dimensions), Z6 (ship) — per the brief above

Follow the brief sections 3, 4, 5, 6 as written, with these additions learned since:

• The orb right-click "save as vibe" (C3) is the natural zero-mode entry to Z3 — a vibe is exactly one orb's members + the routes they carry.
• auth.py vibes store: use the existing CREATE TABLE IF NOT EXISTS idiom (auth.py:44-46 style) so the server migrates itself on restart — additive only. Test locally against a COPY of godstrument_users.db, never the live file, and remember the deploy never ships the db.
• Vibe import parses user-pasted data → validate hard (source/dest against known sets, numeric clamps, 32-route cap, try/catch the base64/JSON). This is a trust boundary.
• Before the Z6 deploy, run the /ship-check skill (pre-deploy security sweep) — this feature set touches auth.py and user-pasted input, which is exactly its territory.
• Nit (low): while in zero, the chakra-view key (F3/C) flips chakraMode with nothing drawn — make it a no-op in zero (or have it exit zero first via the C1 flow).

Keep the cadence: extraction-check → build → verify in the logged-in preview (z0test / zeropass123 account exists) → screenshot → commit per milestone. Deploy only at Z6 after the adversarial review. The grimoire is truth — Z6 writes zero/vibes/dimensions/OMNI-panel sections in the tech-manual style (numbered how-to + spec table) and regenerates the manual.