Skip to content

Onboarding guidance: FROST/share explanations + first-run sign-policy choice #295

Description

@kwsantiago

Context

Follow-up from the UI/UX overhaul (#293). New users currently get sparse guidance in the create/import flows (CreateAccountScreen.kt, ImportShareScreen.kt, ImportNsecScreen.kt, SeedWordsScreen.kt, PinSetupScreen.kt): no explanation of what a FROST share is, threshold/recovery mechanics, nsec-vs-share tradeoffs, or what "backup confirmed" means. Amber also presents a sign-policy choice (auto-approve "Basic" vs "Manual") and optional Tor setup during first-run; keep-android only surfaces sign policy later, buried in Settings.

The overhaul was presentation-only and didn't add onboarding flow/logic. This issue covers the guidance + first-run policy choice.

Architecture constraint (RMP — we rely on ../keep)

Per the RMP architecture bible (rmp-architecture-bible.md, §1.2/§1.5), split the work by ownership:

  • Native (presentation only): explanatory copy, illustrations, step labeling, and layout for FROST/share/nsec explanations. This is pure rendering — safe to do entirely in keep-android (strings + Compose), no core changes. Good good first issue-sized slice.
  • ⚠️ Rust core (../keep): the sign-policy decision and first-run flow are policy/state, which the bible says must live in Rust, not as Kotlin if/else. A first-run sign-policy choice must be driven through the keep FFI: the core owns the policy value, persists it, and acts on it. The native onboarding screen only renders the options and dispatches the chosen policy to the core — it must not branch on or store policy itself.
    • keep-android already exposes sign policy via the FFI (SignPolicyStore/core); confirm whether a "set at onboarding" entry point exists, and add a core-driven one if not, rather than replicating policy logic natively.
  • Tor/proxy setup is likewise a core-owned config (getProxyConfig/proxy state); a first-run prompt should configure it through the existing FFI, with native only collecting the port/toggle.

Decision-framework check (§1.5) for anything added: if a screen contains an if/else that decides app behavior (not layout), it belongs in the core.

Acceptance criteria

  • First-run explanatory content for FROST shares, threshold/recovery, and nsec-vs-share, using the UI/UX overhaul: design tokens, shared components, consistent screens #293 components (cards/section headers/empty states), strings in res/values/strings_*.xml.
  • Optional first-run sign-policy choice that dispatches the selection to the keep core; no policy logic or persistence added natively.
  • (Optional) first-run Tor prompt that configures proxy via the existing FFI only.
  • No business/policy if/else introduced in the Compose layer.

Notes

  • The copy/illustration slice can land independently (native-only, no keep.version bump). The sign-policy slice may need a small ../keep FFI addition if no onboarding entry point exists.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestmediump3Lowest PriorityuiUser interface

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions