Repository navigation
v0.2.0: guided onboarding experience - #49
Merged
Merged
Conversation
aboullaite
force-pushed
the
release/v0.2.0
branch
from
July 17, 2026 16:00
6a410c4 to
54d578f
Compare
A ground-up rework of the first-run experience, plus the platform and
reliability work QA surfaced along the way.
Onboarding & skill
- Guided six-step onboarding flow (references/onboarding.md): welcome +
privacy intro, recipe picker, chapter-overview approval gate, voice
preview player page, local episode preview, save with next steps
- Curated recipes with per-recipe defaults and Kokoro voices (af_heart;
af_nicole for sleep content); Deep dive asks for its topic with
personalized suggestions; Sleep story and Language practice added
- Ask-before-install for Kokoro with its Apache-2.0 license linked;
cover image asked as "Generate one for me" vs "I have an image"
- Local preview pages: blob-loaded seekable player, event-driven
play/pause state, serve-first lifecycle
- User-centred strings ("your episode is ready"), UX-reviewed wording
throughout; Spotify API reference simplified to search-only
CLI
- setup, doctor (platform + python checks), info, and tts command
family (status/setup/test/voices/default/add/remove)
- Kokoro setup downloads the model weights (~340 MB) from the newest
upstream model-files release (env-overridable, pinned fallback);
ready requires models present, not just the pip package
- Python 3.10+ discovery across versioned binaries, python3, and the
Windows py launcher, cached per invocation
- Windows support end to end: Scripts venv layout, cmd /C custom
engines, self-update via rename-aside, SAVE_TO_SPOTIFY_PREVIEW_DIR
for virtualized cache folders, ffplay-first preview playback
- Voice preview via tts test with player-page flow; kokoro_python
exposed in tts status --json
Install
- install.sh: interactive PATH fix, Windows via Git Bash to
~/.local/bin, per-shell guidance
aboullaite
force-pushed
the
release/v0.2.0
branch
from
July 17, 2026 16:25
54d578f to
59502c6
Compare
added 3 commits
July 17, 2026 18:30
- elevenlabsBaseURL gets a comment stating it is scheme+host only, unlike OPENAI_BASE_URL which includes /v1 (SDK conventions differ); prevents a future "alignment" that would double the prefix - audio-providers.md OpenAI snippet uses write_to_file, matching the ElevenLabs modernization in the previous commit (stream_to_file is deprecated in openai-python v1+)
Addresses the remaining P2 from the PR re-review: - macOS requires an interactive session marker (TERM or TERM_PROGRAM) before claiming browser capability: launchd daemons/agents get a minimal environment without either and have no WindowServer access, so `open` being on PATH proves nothing - CI is interpreted as a boolean: CI=false / CI=0 opts out; true, 1, or unparseable non-empty values mean a CI environment - The platform/environment decision is factored into canOpenBrowserWith(goos, getenv, lookPath) and covered by a table-driven test across darwin/windows/linux session shapes - auth.OpenBrowser uses Run for the prompt-exit dispatchers (open, rundll32) so a launch failure surfaces before WaitForCallback instead of a silent five-minute wait; Linux keeps Start because some openers exec the browser directly
Addresses the remaining P2 from the PR re-review:
- Linux openers are started and watched through a one-second grace
window: a quick non-zero exit (xdg-open exits 3/4 when no handler or
tool exists) surfaces as an error before OAuth waits on a callback,
while a still-running process is treated as the launched browser and
reaped by a background Wait whenever it exits; covered by a focused
test (fast failure, fast clean exit, long-running process)
Review cleanups in the same area:
- Linux opener list consolidated to auth.LinuxOpeners (was duplicated
in cmd/detect.go)
- Dead lookPath("open") dropped from the darwin capability check
- X-forwarded SSH sessions (DISPLAY set) no longer short-circuit to
headless; they fall through to the real capability check
- Intent comments: two-tier isHeadless/canOpenBrowserWith design, the
TERM-heuristic safety contract, and OpenBrowser's expectation that
callers gate on capability or handle the error
kallepersson
approved these changes
Jul 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A ground-up rework of the first-run experience, taking a new user from "never heard of this" to a private episode in their Spotify Library in six guided steps, plus the platform and reliability work that three rounds of QA surfaced along the way.
Onboarding & skill
references/onboarding.md): welcome and privacy intro (episodes are private, not shareable), recipe picker, chapter-overview approval before any script or audio is generated, voice preview via a local player page, seekable local episode preview, save with clear next stepsreferences/recipes.md) with per-recipe defaults and Kokoro voices (af_heart, withaf_nicolefor sleep content). Deep dive asks for its topic with 3 personalized suggestions instead of inventing one silently: the topic is the user's intent. Sleep story and Language practice addedreferences/local-preview.md): blob-loaded audio so seeking works without HTTP Range support, event-driven play/pause state, serve-first lifecycleCLI
setup(auth + TTS in one pass),doctor(now reportsplatformand apythoncheck),info, and thettsfamily (status/setup/test/voices/default/add/remove)tts setupfrom the newest upstreammodel-files-*release (env-overridable, pinned fallback, progress bar).doctor/tts statusonly report Kokoro ready when the models actually exist, fixing the false-ready that broke fresh installspython3, and the Windowspylauncher (skips the Microsoft Store stub), cached per invocationScripts\venv layout,cmd /Cfor custom engine checks, self-update via rename-aside (a running.execan't be replaced in place),SAVE_TO_SPOTIFY_PREVIEW_DIRfor virtualized cache folders,ffplay-first preview playbacktts status --jsonexposeskokoro_pythonso agents read the venv interpreter path instead of hardcoding platform layoutsInstall
install.sh: interactive PATH fix with per-shell guidance; Windows installs via Git Bash to~/.local/binTesting
go test ./...green; darwin/linux/windows on amd64/arm64 all buildLC_UUIDrelease gate