didactyl/docs/wizard_menus.md

# Setup Wizard Menu Reference

Proposed wizard flow. Each menu the interactive setup wizard presents, in the
order an operator encounters them. Use this as a design reference.

---

## Main Menu

```
╔═ Main Menu ═══════════════════════════════════════════════════╗
║  Choose Setup Mode                                            ║
╠═══════════════════════════════════════════════════════════════╣
║  n  ew agent -- create a fresh identity                        ║
║  e  xisting -- start an already set up agent                   ║
║  l  oad -- boot from genesis.jsonc                             ║
║  q  uit                                                        ║
╚═══════════════════════════════════════════════════════════════╝
```

---

## New Agent Flow (8 steps)

### Step 1 of 8 — Agent Profile

```
  Agent name [Didactyl]: _
```
Single prompt. Default `Didactyl`.

### Step 2 of 8 — Relay Configuration

```
  Current relays:
    1. ws://localhost:7777
    2. wss://relay.laantungir.net
    3. wss://relay.primal.net

  a  dd a relay
  r  emove a relay (by number)
  d  one -- use this list
  b  ack
  q  uit
```

- **a** — prompt: `Relay URL (wss:// or ws://):`
- **r** — prompt: `Remove which number?` (cannot remove last relay)
- **d** — accept and continue
- Starts from the default relay list; operator adds/removes before identity
  validation queries the network

### Step 3 of 8 — Identity

```
  g  enerate a new Nostr keypair
  p  rovide an existing nsec
  s  ign with a running n_signer
  b  ack
  q  uit
```

- **g** — generates a fresh keypair, shows npub+nsec, asks to confirm saved
- **p** — prompts for nsec (echo-suppressed), derives pubkey
- **s** — enters the **n_signer Transport** sub-menu (below)

### Step 4 of 8 — Identity Validation & Existing Agent Detection

After the identity is established (new keypair, imported nsec, or n_signer
pubkey), the wizard queries the configured relays for a kind 10002 relay list
and kind 30078 encrypted config for this pubkey.

**If NO existing agent data is found:**

```
  Agent kind 10002: NOT FOUND (new identity available)
  Admin profile:   N/A

  c  ontinue to administrator setup
  q  uit
```

**If existing agent data IS found:**

```
  Agent kind 10002: FOUND
  Admin profile:   <admin name or NOT FOUND>

  This identity already has an agent configured on the network.

  d  ownload existing config and review it
  r  estart with a fresh identity
  c  ontinue anyway (overwrite existing state)
  q  uit
```

- **d** — downloads all relevant events (kind 10002 relay list, kind 30078
  encrypted config, kind 0 profile, kind 3 contacts) from the relays, decrypts
  the config, and presents everything on a single review page (see Step 4a
  below). This merges the "existing agent" recovery path into the new agent
  flow so the operator does not need to restart the wizard.
- **r** — returns to Step 3 (Identity) to pick a different identity
- **c** — continues to Step 5 (Administrator) as a fresh setup that will
  overwrite the existing state

#### Step 4a — Downloaded Config Review (only if `d` chosen)

```
  Downloaded configuration for this identity:

  Name:         <agent_name>
  Identity:     <pubkey>...
  Admin:        <admin pubkey or (not set)>
  LLM Provider: <provider or (not set)>
  LLM Model:    <model or (not set)>
  LLM Base URL: <base_url or (not set)>
  LLM API Key:  <masked or (not set)>
  Relays:       <N> configured
  DM Protocol:  <nip04/nip17/both>

  e  dit these settings
  b  oot with this config now
  i  nstall dedicated-user systemd service and boot
  q  uit
```

- **e** — enters the review/edit loop (admin, LLM, relays — same as the
  Existing Agent review loop), then returns here
- **b** — boots immediately with the downloaded config
- **i** — installs systemd service and boots

If the operator chooses **b** or **i**, the wizard skips Steps 5–8 and goes
straight to launch — the downloaded config is already complete.

### Step 5 of 8 — Administrator

```
  Admin pubkey (npub1... or 64-char hex): _
```
Single prompt. Accepts npub or hex.

### Step 6 of 8 — LLM Provider

```
  LLM provider [openai]: _
  API key: _
  Model [gpt-4o-mini]: _
  Base URL [https://api.openai.org/v1]: _
  Max tokens [512]: _
  Temperature [0.7]: _
```

### Step 7 of 8 — Default Skills

(silent — prepares default startup skill events)

### Step 8 of 8 — Review

```
  Name:        <agent_name>
  Identity:    <pubkey>...
  Admin:       <admin>...
  LLM:         <model> @ <base_url>
  Relays:      <N> configured
  DM Protocol: nip04

  b  oot the agent now
  i  nstall dedicated-user systemd service and boot
  s  tart over
  q  uit
```

- **b** — publishes kind-30078 config, boots immediately
- **i** — publishes config, installs systemd unit, starts service
- **s** — resets config and returns to Main Menu

---

## n_signer Transport Sub-menu

Reached from Step 3 (`s`) or Existing Agent (`s`).

```
  u  nix abstract socket (auto-discover or named)
  t  cp (host:port + optional auth privkey)
  s  erial USB device (auto-discover or path)
  f  d pair (read_fd:write_fd -- advanced)
  e  xec -- Qubes cross-qube qrexec (target qube + service)
  b  ack
  q  uit
```

### Per-transport prompts

**u (unix)**
```
  Discovered n_signer abstract sockets:
    1. nsigner_hairy_dog
  Pick a number, type a custom name, or press Enter for auto-discovery.
  Socket name [1]: _
```

**t (tcp)**
```
  host:port [127.0.0.1:7777]: _
  Auth privkey hex (64 chars, optional, echo-suppressed): _
```

**s (serial)**
```
  Discovered serial devices:
    1. /dev/ttyACM0
  Pick a number or type a custom path.
  Device [1]: _
```

**f (fds)**
```
  read_fd:write_fd: _
```

**e (qrexec)**
```
  Target qube [nostr_signer]: _
  qrexec service [qubes.NsignerRpc]: _
```

### Common role + path prompts (after transport chosen)

```
  Role [nostr_range]: _

  Derivation path presets:
    1) m/44'/1237'/0'/0/0      (NIP-06 standard)
    2) m/44'/1237'/0'/0'/0'    (all-hardened)
    3) custom
  Select preset [1]: _
  role_path [m/44'/1237'/0'/0/0]: _

  Timeout ms [15000]: _
```

Then a connectivity check runs:
```
  Checking connectivity to n_signer (mode=nsigner_unix, ..., role=nostr_range, path=m/44'/1237'/0'/0/0)...
  Connectivity check: OK. Pubkey: <hex>
```
On failure, the n_signer error string is shown and the operator can retry.

---

## Existing Agent Flow

Kept as a separate entry point from the Main Menu for operators who know they
want to recover an existing agent and do not want to go through the new-agent
steps.

### Identity

```
  n  sec -- enter the agent private key
  s  ign with a running n_signer (no nsec required)
  q  uit
```

- **n** — prompt: `Enter your agent nsec (nsec1... or 64-char hex):` (echo-suppressed)
- **s** — enters the **n_signer Transport** sub-menu (same as above)

### Config Recovery

If no kind 10002 relay list is found:
```
  Relay list (kind 10002):  NOT FOUND

  n  ew agent setup with this identity
  q  uit to main menu
```

### Recovered Configuration (review loop)

```
  Your agent was found. Change any of the following:

  Name:         <name>
  Identity:     <pubkey>...
  Admin:        <admin>
  LLM Provider: <provider>
  LLM Model:    <model>
  LLM Base URL: <base_url>
  LLM API Key:  <masked>
  Relays:       <N> configured

  a  dmin pubkey
  l  lm config
  r  elay configuration
  c  ontinue to launch options
  q  uit
```

- **a** — re-prompt admin pubkey
- **l** — re-prompt LLM config
- **r** — relay add/remove/done sub-menu (same as Step 2)
- **c** — proceed to launch

### Launch Options

```
  Name:        <name>
  Identity:    <pubkey>...
  Admin:       <admin>...
  LLM:         <model> @ <base_url>
  Relays:      <N> configured

  b  oot the agent now
  i  nstall dedicated-user systemd service and boot
  q  uit
```

---

## Load Genesis Flow

```
  Path to genesis.jsonc: _
```
Single prompt. Loads and boots.

---

## Default Relays

```
    1. ws://localhost:7777
    2. wss://relay.laantungir.net
    3. wss://relay.primal.net
```

---

## Summary of changes from previous design

1. **Default relays changed** to `ws://localhost:7777`,
   `wss://relay.laantungir.net`, `wss://relay.primal.net`
2. **Step order changed**: Agent (1) → Relays (2) → Identity (3) → Validation
   (4) → Admin (5) → LLM (6) → Skills (7) → Review (8)
3. **Step 4 redesigned**: if an existing agent is detected, the operator is
   notified and offered three choices: download existing config and review it
   (merges the recovery path inline), restart with a fresh identity, or
   continue anyway (overwrite). The download path shows all recovered settings
   on a single page and lets the operator edit or boot directly — skipping
   Steps 5–8 since the config is already complete.