Skip to main content

Ethos onboarding seeds

The curated-catalog screen a new user (or any user with no Ethos at their active scope) reaches after accepting the no-Ethos CTA. One scrollable list of canonical seeds; tap one, land in a Builder pre-seeded with that seed's body and the auto-Generate window already open.

The route is /ethos-onboarding/seeds; the component is EthosSeedSelectionScreen in gnostikon-client/src/components/ethos-onboarding/. This page describes the screen surface only — the flow that brings a user here and the behavior that picks up after the tap are covered by the two guides linked at the bottom.

Last reviewed against client commit ea9d091 (gnostikon-client, branch main).

Visible elements​

  • PageHeader at the top, with:
    • Eyebrow — Onboarding.
    • Title — Set up your Ethos.
    • Subtitle — scope-aware. For project <name> when the active scope is a project, For agent <name> when it is an agent, For your personal scope for the user scope.
    • Back affordance — labeled Home, navigates to /.
  • Loading state — single section card with a spinner and the label Loading…. Shown while the catalog request is in flight.
  • Empty state — section card with the headline No seeds available yet and the body The Ethos catalog is currently empty. Please contact an administrator. Shown when the catalog request succeeds but returns zero seeds.
  • Error state — danger-styled card with the headline Couldn't load the Ethos catalog, the body Check your connection and try again., and a Try again button that re-fetches the catalog. Shown for HTTP failures, network failures, or request timeouts.
  • Ready state — vertical list of seed cards. Each card shows the seed's display_name (single line, semibold) and, when present, the seed's summary (truncated to two lines, muted). The whole card is a tap target with accessibilityLabel="Use Ethos seed <display_name>".

The screen also exhibits a scope-flip dismissal behavior: if the user changes their active scope while the screen is open, the screen calls router.back() and unmounts. This is the FR-014 boundary from the onboarding spec — the seed list is bound to the scope the screen opened against, and a flip out of that scope is a cancel signal.

Events & calls​

The screen makes one backend call and dispatches four product events on the ethos.onboarding.* namespace. Every event carries scope_kind, scope_id_hash, and an onboarding_attempt_id so the funnel can be reconstructed end-to-end (the seed selection event also carries the public canonical_gnosis_id).

  • Catalog fetch — GET /api/ethos/seeds on mount, via the useEthosSeeds hook. Drives the loading → ready / empty / error transition.
  • ethos.onboarding.catalog_viewed — fired once when the catalog request resolves to a non-empty list, carrying the item count.
  • ethos.onboarding.catalog_empty — fired once when the catalog request resolves to an empty list.
  • ethos.onboarding.catalog_error — fired once on catalog failure, carrying kind (http | network | timeout) and the HTTP status when applicable.
  • ethos.onboarding.seed_selected — fired when the user taps a seed, carrying the seed's canonical_gnosis_id. After the event, a local Builder-handoff document is written (no network) and the screen navigates to /builder?mode=create.

The seeded Builder takes over from there. The auto-Analyze → short-term-memory → auto-Propose chain it runs with intent="onboarding" is documented in Auto-Generate bypass.

API endpoints consumed​

  • GET /api/ethos/seeds (operation list_ethos_seeds) — see the API reference for the response shape (EthosSeedsResponse, items of EthosSeedItem). No other backend call is issued from this screen.
  • Ethos onboarding — the flow that brings a user to this screen (no-Ethos CTA, scope handshake, seed catalog, Builder handoff).
  • Auto-Generate bypass — what happens in the Builder after the user taps a seed (auto-Analyze → STM → auto-Propose chain with the intent="onboarding" flag, and the natural window closure on save).