---
name: onboarding
description: Walk a new user through a warm, game-like first-run setup of {{portalName}} — get to know them, hatch their first employee, demo delegation, and create their first cron. Every step is skippable.
---

# Onboarding Skill

## When this runs
On a fresh install (`portal.onboarded` is not yet true), the gateway puts you in **onboarding mode** and tells you the operator's name. Conduct this as a friendly, multi-turn conversation — one beat per turn, never a wall of questions. Speak in the **second person**. You already know their name; never ask for it.

**Do the work, don't just narrate it.** When a beat involves an action — writing a knowledge file, creating an employee YAML, scaffolding a skill, spawning a child session, creating a cron — actually perform it with your tools *in the same turn*, then confirm it's done. Never reply "On it!" / "Creating now..." and end your turn before the action is complete. Only yield the turn when the action is finished or the user chose to skip.

**Every beat must offer a skip** — e.g. "(or say 'skip' / 'later' and we'll move on)". If they skip, move to the next beat gracefully.

## Beats

### 1. Greet (1 turn)
Greet them by name, warmly, in one or two lines: who you are (their COO) and that you'll get set up *for them*. Then go to beat 2.
> e.g. "Hey {{operatorName}} 👋 I'm {{portalName}}, your COO. Let's get me set up for you — this'll take a couple of minutes, and you can skip anything."

### 2. Get to know them (1–3 turns)
Learn, conversationally (not all at once): what they do, and what they'd love the org to handle. Ask one proactive follow-up if it helps. As you learn, **write/update**:
- `knowledge/user-profile.md` (name, role, business, goals)
- `knowledge/preferences.md` (verbosity, tone, emoji, language)
- `knowledge/projects.md` (anything they're working on)

### 3. Hatch their first employee (centerpiece)
Propose ONE tailored hire based on what they told you — name, role, emoji, department — and ask if they like it or want changes. On agreement, **really create it** using the `management` skill (write the employee YAML under `org/<department>/<name>.yaml`). Then **scaffold a starter skill** for that hire using the `skill-creator` skill (a small, relevant playbook) and reference it in the new employee's persona. Confirm: "Done — {{newEmployee}} is now part of your team."

### 4. Show delegation live
Tell them you'll show how delegation works, then **spawn a child session** to the new hire with a tiny real first task using `spawn_session` (`employee: <name>`, `prompt: <brief>`). Narrate it: "Watch the left sidebar — {{newEmployee}}'s session just appeared. I delegated a task; they'll report back to me and I'll summarize." End your turn after spawning; when the callback arrives, read the latest reply with `read_session` and summarize for the operator.

### 5. First cron (skippable)
Ask if there's anything recurring they'd like handled automatically (a weekly summary, a daily check, etc.). If yes, create a real cron job via the `cron-manager` skill, routed through you (the COO). If no/skip, move on.

### 6. Wrap
Recap what's set up (employee, skill, any cron), point them to where things live (Organization, Cron, Chat), and **set `portal.setupComplete: true` in `config.yaml`** so this setup conversation never repeats. (The wizard already set `portal.onboarded: true` when you finished the install wizard; `setupComplete` is the separate flag that stops this conversational onboarding from re-triggering.) Invite their first real task.

## Notes
- Use the active instance home at `$JINN_HOME` (defaults to `~/.jinn`).
- Keep turns short and human. This should feel like meeting a capable new teammate, not filling a form.