# Didactyl — Genesis Bootstrapping

See also: [CONTEXT.md](CONTEXT.md) · [SKILLS.md](SKILLS.md) · [README.md](../README.md)

## Purpose

`genesis.jsonc` is the first-run bootstrap document for a Didactyl agent.

It defines initial identity, admin policy, startup events, default skill context, and baseline runtime settings so the agent can publish itself onto Nostr.

After bootstrap, the long-term direction is **nsec-only startup** with state recovered from Nostr events.

---

## File Format

`genesis.jsonc` is JSONC (JSON + comments).

Minimum practical sections:

- `key.nsec` (or runtime `--nsec` / `DIDACTYL_NSEC`)
- `admin.pubkey`
- `llm`
- `startup_events` (must include kind `10002` relay tags)

Typical optional sections:

- `dm_protocol`
- `tools`
- `security`
- `admin_context`
- `api`
- `default_skill` (reserved for default-skill publishing workflows)

---

## First-Run Flow

On first run, the agent:

1. Loads `genesis.jsonc`.
2. Derives keys (from `key.nsec` or runtime nsec override).
3. Connects to relay set from startup kind `10002` tags.
4. Publishes/reconciles startup events.
5. Initializes runtime services (DM subscriptions, triggers, API if enabled).

First-run detection is based on querying own kind `10002` relay-list availability.

---

## Subsequent-Run Flow

On subsequent runs, the agent can start with nsec supplied via:

- CLI: `--nsec <nsec_or_hex>`
- Environment: `DIDACTYL_NSEC`

Optional runtime API overrides:

- `--api-port <port>`
- `--api-bind <address>`

Subsequent-run bootstrap-event republishing is skipped when prior kind `10002` state is found.

---

## Interactive Setup (Zero-Argument Startup)

When Didactyl is run with **no arguments**:

```bash
./didactyl
```

it enters an interactive setup wizard instead of immediately trying to load `./genesis.jsonc`.

Wizard entry choices:

- **New agent** — generate/provide identity, configure admin + LLM + relays
- **Existing agent** — provide nsec and recover relay/admin/LLM config from Nostr
- **Load genesis** — load a specified genesis file path

Menu UX conventions:

- Single-letter hotkeys (case-insensitive)
- First-letter menu mnemonics (e.g., `N` for New, `E` for Existing)
- `q` / `x` exits or backs out of menus

Security behavior:

- nsec entry is masked in terminal
- writing genesis with nsec is explicit and warned
- recommended export mode is genesis without nsec plus runtime `--nsec`/`DIDACTYL_NSEC`

---

## Encrypted Config Events

Didactyl exposes config persistence tools for encrypted self-config on Nostr:

- `config_store` — publish encrypted kind `30078` config by `d_tag`
- `config_recall` — query+decrypt kind `30078` config by `d_tag`

Recommended tags:

- `d=llm_config`
- `d=agent_config`

These are encrypted to self with NIP-44.

---

## Relay Bootstrap Strategy

`startup_events` must include kind `10002` relay tags (`["r", "wss://..."]`).

That relay list is used as the initial network attachment for querying existing state and publishing startup events.

---

## Migration Notes (Legacy -> Genesis)

Legacy deployments using `config.jsonc` can migrate by:

1. Copying equivalent sections to `genesis.jsonc`.
2. Ensuring startup kind `10002` relay tags are present.
3. Providing nsec at runtime (`--nsec` or `DIDACTYL_NSEC`) where desired.
4. Treating `context_template.md` / `config.jsonc.example` as legacy references.

---

## Security Notes

- Keep nsec secret.
- Prefer environment or secure credential injection for production nsec handling.
- Avoid publishing plaintext sensitive config; use encrypted `config_store` for long-term state.