SouveraineOS/docs/substrate/tasks/alpha-tester-readiness.md

task_id	title	status	assignee	priority	phase
alpha-readiness-001	Alpha-Tester Readiness — Close the "it builds" / "a stranger can use it" gap	partial		high	readiness

Task: Alpha-Tester Readiness

Origin

Ani's own alpha-tester critical-path assessment (May 18, 2026), plus two TUI gaps Casey flagged alongside it. The codebase is ~13K lines, ~150 tests pass, clean compile — but there is a real gap between "it builds" and "a stranger can run it."

Resolved decision (May 18, 2026) — onboarding is the first-run wizard

The confusion between souveraine init and the TUI setup wizard is settled: onboarding is the first-run TUI wizard. init is demoted to a scriptable config-template writer.

The setup wizard (ui/setup.rs) already is the first run: souveraine tui on a fresh install routes through core::bootstrap::BootstrapPlan → SetupWizard (the FreshInstall flow) — Bifrost config, model picker, agent name, agent creation. souveraine init was a partial duplicate.

Done (Part A): run_init no longer pretends to onboard. It writes the souveraine.toml template and points at souveraine tui. The interactive Bifrost-key prompt was dropped (the wizard owns credentials). Command help updated.

Remaining (Part B) — make the wizard a complete onboarding: The wizard collects bifrost_url + key + model but the loop is not closed:

1. finish_setup (ui/app.rs) builds LocalBackend::new(self.config…) from the in-memory config — it ignores the bifrost_url/key the wizard just collected. Wire the wizard's Bifrost values into the config used for agent creation.
2. Nothing persists souveraine.toml. The wizard must write the config file on completion so the next launch is Ready with real Bifrost settings — not another FreshInstall. Decide the write location (CWD vs a stable path; see ConsciousnessConfig::discover_path()).
3. Store the Bifrost key in the OS keyring from the wizard (as the old interactive init did).

Once Part B lands, the first-run circle is fully closed: souveraine tui on a bare machine → wizard → working agent + persisted config, no CLI dance.

Hard Blockers — LAN-bound defaults ✅

Bifrost defaults point to Casey's LAN

default_bifrost_url() returns http://10.10.20.120:3360 — Casey's internal gateway. An alpha tester needs either their own Bifrost / OpenAI-compatible endpoint configured, or the local/in-process backend to work with a direct provider (it currently always routes through Bifrost).

Landed in 01b3d0e: All LAN IPs stripped from code, defaults, config template, doc comments. Replaced with 127.0.0.1 or empty placeholders.

Voice config also points to Casey's LAN

stt_url defaults to http://10.10.20.19:7862, tts_url to :7861. Gated behind voice.enabled = false, so it won't crash — but a tester who flips voice on hits a silent failure.

Landed in 01b3d0e: Defaults changed to 127.0.0.1.

Soft Blockers — work, but feel broken

4. No onboarding flow. The TUI has a Setup screen (ui/setup.rs, ~1033 lines) with a wizard — model picker, agent import, text input. But the CLI souveraine init doesn't offer to enter it, and souveraine init hits the no-agent error before the TUI ever loads.

5. No souveraine.toml template in the repo. CONFIG_TEMPLATE in main.rs is written by init, but there's no example file a tester can read before running the binary. The README's souveraine.toml reference is minimal.

6. Config validation absent. A fat-fingered TOML (wrong model name, missing Bifrost URL) surfaces as a cryptic parse failure or a streaming error mid-conversation — not a friendly "I can't reach your Bifrost at that URL."

7. $MEMORY_DIR stale-host override. An alpha tester who inherited $MEMORY_DIR from Letta-era config sees the wrong path in agent tools. Fixed in this batch: for_agent() now strips stale host env vars before injecting agent-specific values.

8. Tool posture visibility. No glanceable indicator of whether tool gestures are expanded (/code) or folded (/chat). Fixed in this batch: header bar shows [tools shown] / [tools folded].

9. Agent Health screen. Settings Agent category had no diagnostic info — no agent ID, subconscious pairing, filesystem layout. Fixed in this batch: read-only fields for agent id, subconscious id, memory/subconscious paths, disk existence check.

   This is inventory health, not identity health. It still does not say whether the agent has a node-local Unix account or whether the live turn and its tools are running as that account instead of the human. The living acceptance contract is ../../../../souveraine/saf/identity/02-agent-principal.md: missing admission is unadmitted; uid-1000 execution is acting-as-human, never green.

TUI Interaction Gaps (flagged by Casey, May 18)

These also block a comfortable first session — they match open entries in the subconscious's ledger/commitments.md:

• Click-to-copy is broken. Added in commit 8d393bf; does not work.
• Scrolling is a gap. Scroll-wheel events are not handled — the user is stuck with arrow keys. Casey prefers the scrollwheel.

(See also docs/tasks/tui-message-interactions.md and docs/tasks/chat-viewport-scroll-clip.md.)

What Already Works

• CLI ergonomics — souveraine --help is well-written.
• The TUI, once running, is genuinely strong: chat bubbles, tool cards, cockpit panel, portrait, presence, schedules editor.
• Federation transport — built end-to-end (all 8 phases).
• Compaction, reflection, archivist, skills, subconscious inbox — wired and tested.

The Delta to Alpha-Ready — roughly two focused sessions

1. Bootstrapping. souveraine init creates an agent with a seed identity and minimal memfs — or souveraine chat autocreates one if none exists. Highest leverage; do this first.
2. Config portability. souveraine init prompts for (or accepts flags for) Bifrost URL and API key at minimum, and writes them into the TOML. The generated template should carry comments explaining each section.
3. First-run TUI. After souveraine init, souveraine tui should land in the setup wizard and tell the tester what to configure.

Notes

• Blockers 2 and 3 (LAN defaults) overlap with the secrets-rotation note in CLAUDE.md — Casey is aware the Bifrost token ships in souveraine.toml and config.rs. Portability and de-LAN-ing the defaults should land together before any public push.