# First Run And Setup

The setup flow is responsible for choosing a usable model path without assuming local Ollama is the only option.

## Built-in Free Start

An unconfigured installation starts with **Built-in free** inference without an
API key, a local model download, or a setup conversation. Omnius selects the
highest-ranked compatible model from its discovered free catalog. Muse Spark
1.3 is the bundled default when current catalog discovery is unavailable.
Saved local and cloud profiles keep their selected endpoint and model, even
when that endpoint is temporarily offline.

Use `/model` to browse the **Built-in free** section alongside your configured
endpoint's models. Known bundled choices remain visible when catalog discovery
fails. `Saved catalog; availability unverified` and `Not currently listed`
describe catalog state; listing a model does not prove that it will answer.
Live catalog pricing and retirement status still control free eligibility.

With `/fallback auto`, the default, a failed selected route can fall back to
compatible alternatives. Attempts respect time limits, rate-limit cooldowns,
and the original response contract. `/fallback manual` asks before using an
alternative. If all eligible services fail, Omnius reports that inference could
not complete; free access does not guarantee an answer to every request.

## Optional Provider Setup

Use `/setup` to ask about providers or commands. Inside setup, `/free` selects
built-in free inference without asking for credentials. Use `/key openrouter`,
`/key openai`, or another `/key <provider>` only when choosing a provider that
requires a key. Setup input is hidden. Credentials are captured locally and
replaced with opaque references before the setup helper sees them; only the
chosen provider's pinned endpoint receives its key. The helper cannot read
project files, environment variables, project conversations, or raw vault values.

Keyed-provider setup lists models, checks the chosen model, and saves the exact
tested connection privately. `/setup local`, or `/local` inside setup, opens
explicit local model setup. Local inference tests require the normal hardware
preflight. `/exit` leaves optional setup without changing inference. Piped task
input follows the normal runtime and never becomes a setup conversation.

## What Setup Probes

Setup can inspect:

- local platform and hardware
- existing Ollama availability
- configured custom endpoints
- OpenAI-compatible endpoint model lists
- optional voice, media, and tool dependencies
- unified-memory hardware constraints

## Model And Endpoint Choice

The model picker includes built-in free choices independently of the configured
endpoint's availability. Selecting a free entry switches the complete model and
transport profile without inheriting the previous endpoint's keys. Selecting
another endpoint with `/endpoint` keeps its provider-specific model choices
available through `/model`.

The setup flow should not silently fall back to local Ollama when an external endpoint was selected.

## Sponsor Endpoint Banner

The setup banner is separate from consumer-visible sponsor endpoint labeling. Sponsor consumer headers should stay simple: a short sponsor-provided string and optional clickable link.

## Optional Dependency Setup

Optional installers can run before the TUI launches. If elevation is required in a terminal context, the TUI should temporarily clear or suspend its drawing state, present the password prompt directly, consume the password through the normal system elevation path, then restore the TUI state.

## Expected Outcome

After first run:

- an endpoint is selected
- a model is selected
- `.omnius/settings.json` exists if settings were persisted
- `.omnius/` is ignored by git
- the TUI can submit a prompt without re-entering setup; remote service availability still applies
