feat(onboarding,familiars): enhance first-run and familiar management - #126
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
This PR improves first-run onboarding and familiar roster management across the TUI, core familiar storage APIs, and slash commands, and adds Codex rate-limit handling that respects Retry-After.
Changes:
- TUI onboarding now reflects user-configured keybindings for shortcut hints and persists “Esc = skip” so onboarding doesn’t reappear every launch.
- Familiar UX improvements: startup roster warnings for malformed/non-fatal roster issues, F2 switcher filtering + “clear active familiar” row, and first-run standalone bootstrap of
~/.coven/familiars.toml. - Standalone roster write support (create/rename/remove/upsert + daemon-owned refusal) and Codex
429errors now threadRetry-Afterinto rate-limit errors.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src-rust/crates/tui/src/render.rs | Updates welcome empty-state messaging and enhances the F2 familiar switcher UI (filter footer + clear row). |
| src-rust/crates/tui/src/onboarding_dialog.rs | Uses keybindings.json-derived labels for onboarding shortcut hints. |
| src-rust/crates/tui/src/familiar_theme.rs | Threads the new per-familiar model field through theme defaults/tests. |
| src-rust/crates/tui/src/app.rs | Adds switcher filter state, roster warning surfacing, switcher behavior changes, and onboarding completion persistence on Esc. |
| src-rust/crates/tui/src/agents_view.rs | Enables deleting coven familiars from the agents menu in standalone mode; refuses when daemon-owned. |
| src-rust/crates/core/src/keybindings.rs | Adds display helpers to surface the active binding for an action (user override or default). |
| src-rust/crates/core/src/coven_shared.rs | Adds per-familiar model, distinguishes absent vs malformed roster loads, and implements standalone roster write APIs + bootstrap roster. |
| src-rust/crates/commands/src/lib.rs | Adds `/familiar new |
| src-rust/crates/api/src/providers/codex.rs | Extracts Retry-After header and threads it into provider errors for non-2xx responses. |
| src-rust/crates/api/src/error_handling.rs | Adds Retry-After parsing and extends rate-limit errors to carry an optional delay. |
| docs/familiars.md | Documents the new model field, standalone write behavior, new commands, and wipe/clear semantics. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+514
to
+516
| return Err(FamiliarWriteError::Duplicate( | ||
| "roster already exists".to_string(), | ||
| )); |
Comment on lines
+1563
to
+1567
| if !present { | ||
| self.status_message = Some(format!( | ||
| "Selected familiar '{active}' is not in the roster — using none.", | ||
| )); | ||
| } |
Comment on lines
+1575
to
+1579
| if let Some(active) = self.config.familiar.as_deref() { | ||
| self.status_message = Some(format!( | ||
| "Selected familiar '{active}' has no roster (~/.coven/familiars.toml) — using none.", | ||
| )); | ||
| } |
Comment on lines
+393
to
+397
| let user_kb = claurst_core::keybindings::UserKeybindings::load( | ||
| &claurst_core::config::Settings::config_dir(), | ||
| ); | ||
| let submit_key = claurst_core::keybindings::display_binding_for(&user_kb, "submit") | ||
| .unwrap_or_else(|| "Enter".to_string()); |
Comment on lines
+3379
to
3381
| let pink = Color::Rgb(139, 92, 246); | ||
| let daemon_familiars = claurst_core::coven_shared::load_familiars().unwrap_or_default(); | ||
| let interior_w = popup_w.saturating_sub(2); |
Onboarding: - Persist onboarding completion on Esc (skip) so it doesn't re-nag - Derive submit/openHelp keybinding hints from real keybindings.json - Lead the no-credential welcome box with a prominent /connect CTA - Honor Retry-After on Codex 429s Familiars: - Surface malformed familiars.toml + roster warnings at startup instead of the roster silently vanishing (load_familiars_result / warnings) - F2 empty-state bootstraps a starter ~/.coven/familiars.toml (standalone) - F2 switcher: incremental filter + "none" clear row - Disambiguate /familiar clear vs wipe-roster (destructive, needs confirm) - Standalone-only roster writes: create/upsert/remove/rename core API, /familiar new|rename|remove commands, and menu deletion; all refuse when the Coven daemon owns the file - Per-familiar model override (model field in familiars.toml) All crates green: core 96, api 35, commands 96, tui 645. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
BunsDev
force-pushed
the
feat/onboarding-familiars
branch
from
July 3, 2026 10:35
95f3562 to
5ffebc5
Compare
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.
Summary
Enhancements to the onboarding and familiar management experience, spanning a first-run pass and standalone familiar administration. Grew out of an
/ultraplanopportunity scan; implemented across all identified items.Onboarding
submit/openHelpkeys from the user's actualkeybindings.jsoninstead of hardcoded labels that could drift./connectcall-to-action when no provider is configured.429responses now honor the server'sRetry-Afterheader.Familiars
~/.coven/familiars.toml(and non-fatal issues like unknown access tiers or duplicate/reserved ids) surface as a startup status message instead of the whole roster vanishing. Stale explicitly-selected familiars are flagged too.familiars.toml(a read-only guide + a full-access builder) and opens the switcher.— none —row to clear the active familiar without/familiar reset./familiar clear(aliasreset) steps back to no active familiar; the destructive/familiar wipe-roster(aliasreset-roster) now requiresconfirm.create/upsert/remove/rename),/familiar new|rename|removecommands, and visual-menu deletion. All refuse when the Coven daemon owns the file (daemon socket present).modelfield infamiliars.toml.Docs:
docs/familiars.mdupdated with the new fields, commands, and standalone-write behavior.Testing
cargo testgreen across touched crates:New coverage: roster write API (create/remove/rename/upsert, daemon-owned refusal), roster load/warnings (malformed vs empty vs absent), F2 switcher entries + filter,
Retry-Afterparsing, and both standalone-removal and daemon-owned-refusal deletion paths.Notes
6178c13(v0.2.2) — clean of the unrelatedfeat/steer-commandwork.~/.coven/coven.socksocket; the daemon remains the source of truth whenever it's running.🤖 Generated with Claude Code