wingedguardian/genesis-agi/onboarding

First-Run Onboarding

Purpose

Guide a new user through Genesis setup on their first interactive CC session. By the end, every critical subsystem is configured and verified live.

This skill is triggered automatically while the install is not yet functional — i.e. the setup floor (genesis.onboarding.floor: Claude Code login + at least one LLM/routing key + at least one embedding key) is unmet. It is NOT gated on the ~/.genesis/setup-complete marker (that marker means "bootstrap finished" and does not imply a working brain). So a bootstrapped box that is still missing keys is still guided here. It can also be invoked manually by asking Genesis to "run setup" or "reconfigure [section]" to re-run specific sections.

Pre-Conditions

Before this skill runs, install.sh (Layer 1) has already completed:

• Python venv, dependencies, systemd services
• Qdrant installed and running
• Template-generated .claude/settings.json and .mcp.json
• Claude Code logged in
• secrets.env created from template (may be empty)

This skill handles everything that benefits from conversational guidance rather than scripted prompts.

Internal References

The references/provider-guide.md file in this skill directory contains detailed information about every API provider Genesis supports — what each key unlocks, where to sign up, pricing tiers, and env var names. Read this file during Step 2 and Step 5 to give the user accurate, specific information. Do not expect the user to read it themselves — you present the relevant parts conversationally.

Partial Re-Run

If the user asks to reconfigure a specific section (e.g., "reconfigure secrets", "reconfigure telegram"), skip to that section only.

If ~/.genesis/setup-complete already exists, inform the user: "Onboarding was already completed on [date]. Running the requested section only." Then proceed with just the requested section (or offer a menu if no argument given).

Overview: Two-Phase Setup

Phase A — Essentials (Steps 1-4): These MUST be completed before onboarding can finish. Without them, Genesis cannot function. Do not let the user skip past these.

Phase B — Expansion (Step 5): Additional providers and capabilities the user can configure now or come back to later. Exploratory — show what's possible, let the user decide how deep to go.

The transition between phases should feel natural:

Good — the core system is working. Now let me show you what else you can

configure to get more out of Genesis. None of this is required right now,

but each key you add opens up new capabilities.

PHASE A: ESSENTIALS

Step 1: Welcome + Identity

Introduce yourself. Be warm but direct — the user is here to get things working, not to read a manual.

Say something like:

I'm Genesis. This is our first session together, so let me help you get

everything configured. This will take a few minutes — by the end, you'll have

a fully operational system with verified API connections.

First, let me learn a bit about you so I can tailor how I work.

Gather (conversationally, not as a form):

• Name and timezone
• Professional background (briefly — what do they do?)
• What they want Genesis to help with (primary use cases)
• Communication preferences (brief vs. detailed, proactive vs. on-demand)

Write results to:

• src/genesis/identity/USER.md — update the user profile section
• Set USER_TIMEZONE in secrets.env if provided

Do NOT ask all questions at once. One or two at a time, naturally.

Step 2: Core API Keys

Principle: User sovereignty over secrets. Default to showing where things are, not asking for keys. Let the user choose their comfort level.

1. Read secrets.env and check which keys are configured vs. empty.

1. Read references/provider-guide.md to have full provider details available.

1. Report status clearly:

> Here's your current API key status: > > Configured: [list any that have values] > Not yet configured: [list empty ones] > > Your secrets file is at: ~/genesis/secrets.env

1. Explain what's essential and why:

> To get Genesis fully operational, we need three things: > > 1. An LLM provider — this is Genesis's brain. I use language models for > reasoning, reflection, triage, and every cognitive task. OpenRouter is > the simplest option — one key covers 200+ models and I'll route to the best > one for each task. Sign up at openrouter.ai/keys. > > 2. An embedding provider — this is how I remember things. Embeddings > turn text into vectors for semantic search. DeepInfra is fast and cheap > (~0.01 USD per million tokens). Sign up at deepinfra.com. > > 3. Telegram — this is how I reach you. Morning reports, alerts, proactive > insights — all of Genesis's outreach happens over Telegram. Without it, I > can only talk to you when you open a session. > > These three make Genesis fully functional. We can't move forward without > at least the LLM and embedding keys.

1. Respect their choice on HOW to provide keys:

> You can edit secrets.env directly with any editor — nano, vim, or > transfer the file with SFTP/SCP. Or if you'd prefer, you can paste your > API keys here and I'll write them to the file for you. Your choice.

1. If they provide keys, write them to secrets.env using the Edit tool:

• Read the file first
• Find the line with the matching env var name (e.g., API_KEY_OPENROUTER=)
• Replace the empty value with the provided key
• If the line doesn't exist, append it at the end of the appropriate section
• Run chmod 600 secrets.env after writing
• Never echo keys back to the user — acknowledge with "Saved" only

1. Telegram setup (essential, not optional):

> Let's set up Telegram so I can reach you outside of these sessions. > You'll need to create a bot via @BotFather on Telegram — it takes about > 30 seconds. Here's how: > > 1. Open Telegram, search for @BotFather, start a chat > 2. Send /newbot, pick a name and username > 3. Copy the bot token it gives you

• Write TELEGRAM_BOT_TOKEN to secrets.env
• Ask for their Telegram user ID for TELEGRAM_ALLOWED_USERS
• If they have a forum/group chat: ask for TELEGRAM_FORUM_CHAT_ID
• Test: send a message via the outreach_send MCP tool
• If they want to skip Telegram for now, allow it but note it as degraded:

"Okay — Genesis will work without Telegram, but I won't be able to send you morning reports or alerts. You can set this up later."

1. Gate check: Do NOT proceed past this step until at least one LLM key

and one embedding key are configured and the user has acknowledged the Telegram decision (configured or explicitly deferred).

Step 3: GitHub + Backup

1. Check GitHub auth: gh auth status

1. If not authenticated:

> Genesis backs up your data every 6 hours to a private GitHub repo — > your database, memories, configuration, and session transcripts. Let's > get GitHub set up. > > Run this command: gh auth login > (Type ! gh auth login at the CC prompt to run it in this session.)

Wait for them to complete it, then verify with gh auth status.

1. Once authenticated:

• Detect GitHub username from gh auth status
• Ask: "What would you like to name your backup repo? Default: genesis-backups"
• Check if repo exists: gh repo view <user>/genesis-backups
• If not, offer to create: gh repo create genesis-backups --private

1. Write GENESIS_BACKUP_REPO=<user>/genesis-backups to secrets.env.

1. Set the backup passphrase (required for encryption):

• Check if GENESIS_BACKUP_PASSPHRASE is already set to a non-empty value in secrets.env.
• If not set, generate one: openssl rand -base64 32
• Write the output as GENESIS_BACKUP_PASSPHRASE=<value> to secrets.env.
• Critical: store this passphrase in a password manager off-machine.

Backups are AES-256 encrypted with this key. If this machine dies and the passphrase only lives in secrets.env, the backups cannot be decrypted. There is no recovery without it.

1. Verify backup script can reach it: git ls-remote https://github.com/<user>/genesis-backups.git

1. Configure Tier 2 (large data). GitHub (Tier 1) holds only small encrypted

text — memory, config, secrets. The large binaries (SQLite DB, Qdrant snapshots, transcripts) are gitignored from GitHub and need a separate target, or they stay local-only (no off-machine backup). Ask the user:

• NAS (SMB): set GENESIS_BACKUP_NAS=//host/share,

GENESIS_BACKUP_NAS_USER, GENESIS_BACKUP_NAS_PASS in secrets.env (requires smbclient).

• No NAS: allowed, but say so explicitly — the DB/Qdrant/transcripts will

NOT be replicated off-machine until a Tier 2 target is set. (A cloud option via rclone is planned but not yet wired.)

1. Run one verify backup and confirm it succeeded (do NOT proceed if it

fails): bash "$HOME/genesis/scripts/backup.sh", then check ~/.genesis/backup_status.json shows "success": true (and "tier2_status": "ok" if a NAS was configured).

1. Enable the 6h backup timer — only after the verify run passed.

systemctl --user enable --now genesis-backup.timer (the unit files are installed by bootstrap but left disabled). Confirm with systemctl --user list-timers genesis-backup.timer. This is done HERE, deliberately — never auto-enabled at bootstrap — so backups are an opt-in, verified setup, not a switch flipped for every install. (Do NOT also add a crontab entry — the timer is the single scheduler; two would double every backup.)

Step 4: Endpoint Verification Gate (MANDATORY)

This is the essential verification. Every configured key gets tested live. Phase A does not complete without critical endpoints passing.

For each configured provider, make a lightweight API call:

1. LLM providers — Use the health_status MCP tool which runs

validate_api_keys() internally. This tests each configured provider with a real HTTP request.

1. Embedding provider — Test with a real embedding:

• Use the memory_store MCP tool to store a test memory, or
• Call the embedding health check via health_status

1. Qdrant — Verify the vector database is running and writable:

• Store a test memory via memory_store
• Recall it via memory_recall
• This proves the full pipeline: embed -> store -> retrieve

1. Telegram (if configured) — Send a test message:

> If you received a Telegram message from me, it's working!

1. Backup repo (if configured) — git ls-remote to verify push access.

1. Database — Check that genesis.db exists and is writable:

``bash ls -la ~/genesis/data/genesis.db ``

1. CC hooks — Already verified (the SessionStart hook triggered this flow).

Report:

Endpoint Verification:

- OpenRouter: PASS (models endpoint responded)

- DeepInfra: PASS (embedding returned 1024-dim vector)

- Qdrant: PASS (write + read cycle successful)

- Telegram: PASS (test message delivered)

- Backup repo: PASS (push access verified)

- Database: PASS

- CC Hooks: PASS (you're seeing this because they work)

All critical endpoints verified. The core system is operational.

If any CRITICAL endpoint fails (LLM or embedding), explain the error and help fix it before proceeding. Do not complete Phase A with broken critical endpoints.