Capture the approved Rhythma redesign before implementation

Record the agreed product direction so the upcoming implementation plan and code changes stay aligned on audience, tone, audio depth, and UI intent. This freezes the target experience before execution work begins.

Constraint: The redesign must stay non-clinical for mental health advocate sharing
Rejected: Jump straight into implementation from chat context | too easy to drift on scope and tone
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Preserve the artful wellness companion framing unless product positioning is explicitly reapproved
Tested: Spec self-review for placeholders, contradictions, ambiguity, and scope
Not-tested: No runtime impact; documentation change only

docs/superpowers/specs/2026-04-13-rhythma-ambient-redesign-design.md

@@ -0,0 +1,263 @@
+# Rhythma Ambient Redesign Design
+
+## Goal
+
+Transform Rhythma from a functional modulation demo into a meditative ambient instrument that mental health advocates can share confidently as an artful wellness companion. The redesign should materially improve two areas at once:
+
+- the emotional depth and legibility of the generated audio
+- the warmth, clarity, and perceived intentionality of the UI
+
+The product must stay explicitly non-clinical. It should support reflection, calm, and emotional grounding without implying diagnosis, treatment, or therapeutic efficacy.
+
+## Product Positioning
+
+Rhythma is an artful wellness companion. A user describes a feeling or intention, and the app responds with a crafted listening session made of ambient layers, a named emotional tone, and light reflective guidance.
+
+Approved positioning decisions:
+
+- Present the product as supportive and reflective, not diagnostic.
+- Use grounded language such as "listening path," "session," and "crafted from your input."
+- Keep the note that the app is experimental and not medical advice.
+- Avoid framing the output as a clinical recommendation or measured biometric result.
+
+## Experience Principles
+
+1. Calm first. Every interaction should reduce friction and visual stress.
+2. Emotionally legible output. Sessions should feel intentionally different, not like minor parameter changes.
+3. One primary path. The default experience is describe -> generate -> listen.
+4. Advanced controls remain available, but secondary.
+5. Trust through restraint. No mystical overclaiming, no clinical cosplay, no manipulative language.
+
+## Recommended Approach
+
+Use a session-driven redesign with two coordinated upgrades:
+
+- Audio becomes profile-based and layered rather than single-tone-first.
+- UI becomes session-centric and atmospheric rather than form-centric.
+
+Alternatives considered and not chosen:
+
+- Cinematic emotional soundscape: higher "wow" factor, but too easy to push into melodrama for the target audience.
+- Interactive resonance lab: interesting as a concept, but too clinical or technical for mental health advocates and weak on warmth.
+
+## Architecture Overview
+
+The current modular split should remain intact:
+
+- `app.py`: Gradio interface composition and interaction wiring
+- `rhythma_analysis.py`: input interpretation and session selection
+- `rhythma_engine.py`: sound generation and visualization
+- `rhythma.py`: compatibility facade
+
+The redesign should extend those modules rather than collapse them again.
+
+### Planned responsibility changes
+
+- `rhythma_analysis.py` should evolve from "emotion and rhythm mapper" into "session profile selector."
+- `rhythma_engine.py` should evolve from "single modulated wave generator" into "layered ambient session renderer."
+- `app.py` should evolve from "parameter form with outputs" into "guided session experience with secondary controls."
+
+## Audio Design
+
+### Target outcome
+
+Each generated result should feel like a coherent listening session with motion, depth, and emotional contour.
+
+### Session model
+
+Replace the current single-frequency-centered mapping with a session profile model. A session profile defines:
+
+- emotional tone label
+- tonal center
+- pulse behavior
+- brightness
+- density
+- modulation motion
+- harmonic warmth
+- suggested session duration range
+- short reflective listening guidance
+
+### Audio layering
+
+Each session should be rendered from three layers:
+
+1. Base drone
+   A stable tonal bed that anchors the session.
+
+2. Breath pulse layer
+   A gentle amplitude or filter movement layer that introduces calm rhythmic motion.
+
+3. Air or shimmer layer
+   A quieter upper texture that adds spaciousness and prevents the result from feeling flat.
+
+### Emotional profile examples
+
+- `anxious`
+  - lower brightness
+  - slower pulse
+  - smoother attack
+  - more stable drone
+- `focused`
+  - cleaner harmonic stack
+  - tighter motion
+  - more defined pulse contour
+- `relaxed`
+  - warmer harmonics
+  - slower drift
+  - softer shimmer
+- `active`
+  - more motion and pulse energy
+  - still within a calm ambient palette
+
+### Motion over time
+
+The audio should evolve during playback. A session should not feel fully static after the first second.
+
+Required motion behaviors:
+
+- gentle attack at start
+- soft release at end
+- slow movement across pulse depth, filter brightness, or shimmer density
+- small randomized variation inside safe bounds so repeated sessions are not identical
+
+### Manual controls
+
+Manual controls remain, but their role changes:
+
+- `Tone Center` replaces `Override Frequency`
+- `Session Pattern` replaces `Override Rhythm Pattern`
+- the default path still uses automatic session selection
+
+Manual overrides should shape a session profile, not break the session concept.
+
+## UI Design
+
+### Target outcome
+
+The interface should feel like a calm listening room rather than a settings panel.
+
+### Layout
+
+Top:
+
+- stronger title treatment
+- short trust-building product description
+- visible non-clinical support note
+
+Main area:
+
+- left column: prompt input, examples, and generate action
+- right column: a session card showing the result
+
+Lower area:
+
+- richer visualization
+- "about this session" explanation
+
+### Session card
+
+The output area should be redesigned around a session card containing:
+
+- session name
+- emotional tone
+- listening path text
+- audio player
+- short session reflection
+- visual accent or motion panel
+
+### Copy changes
+
+Rename utility labels to human-centered labels:
+
+- `Rhythma Analysis & Guidance` -> `Your Listening Path`
+- `Symbolic Interpretation` -> `Session Reflection`
+- `Override Frequency (Hz)` -> `Tone Center`
+- `Override Rhythm Pattern` -> `Session Pattern`
+
+### Visual direction
+
+The interface should use:
+
+- warm atmospheric gradients
+- subtle glows and layered background texture
+- restrained contrast
+- more intentional spacing and hierarchy
+- typography that feels designed rather than default
+
+The final look should feel calm, shareable, and emotionally credible.
+
+### Examples
+
+Examples should read like invitations into sessions, not test prompts. They should demonstrate distinct emotional intents and a few intentional non-default session patterns.
+
+## Data Flow
+
+1. User enters text or audio.
+2. Analysis maps input to a session profile.
+3. Session profile is optionally shaped by advanced controls.
+4. Engine renders a layered audio session and supporting visualization.
+5. UI presents the result as a named listening session with guidance and reflection.
+
+## Error Handling
+
+The redesign should preserve graceful fallback behavior:
+
+- If Groq is unavailable, text-only local analysis still works.
+- If embeddings are unavailable, keyword matching still works.
+- If audio export fails, the UI should return a clear user-facing error.
+- If optional features are disabled, the UI should degrade cleanly without broken controls.
+
+User-facing errors should stay calm, specific, and non-technical where possible.
+
+## Testing Strategy
+
+The redesign must keep a regression-tests-first posture.
+
+Required coverage areas:
+
+- session profile selection for representative emotional inputs
+- layered audio render output shape and normalization bounds
+- deterministic behavior for profile construction defaults
+- override behavior for tone center, modulation type, and session pattern
+- app-level wiring for renamed controls and example values
+
+Verification expectations:
+
+- compile checks for edited Python modules
+- targeted regression tests for analysis and engine behavior
+- one real Gradio runtime smoke check in an environment with installed dependencies
+- post-change manual check of the examples table and session output UX
+
+## Scope Boundaries
+
+Included in this redesign:
+
+- stronger ambient audio generation
+- session-based emotional mapping
+- calmer, more intentional interface
+- label and examples rewrite
+- non-clinical positioning polish
+
+Not included in this redesign:
+
+- authentication or user accounts
+- saved session history
+- clinical claims or mental health outcomes tracking
+- biometric sensing or real biofeedback
+- mobile-native app packaging
+
+## Risks
+
+- The UI can become visually nicer without actually improving the listening experience if the audio redesign is shallow.
+- The audio can become more complex without becoming more emotionally legible if profiles are not tightly defined.
+- Mental health advocates may disengage if the language feels either too mystical or too clinical.
+
+## Success Criteria
+
+The redesign is successful when:
+
+- first-time users can understand the main flow immediately
+- generated sessions sound noticeably more immersive and differentiated
+- the app feels emotionally intentional without overclaiming
+- the examples and output card are polished enough to share publicly
+- the app remains stable when optional dependencies are missing