Stage 5: Onboarding Conversation 🌱

Setup is not a form. Setup is a conversation. Axiom interviews you, understands what you do, and grows your organism in front of you.

Status: ✅ Complete Lives in: agents/axiom/instruction.md (ONBOARDING MODE section) Flag: system.onboarding collection (single record after completion)

The Paradigm

Every AI tool onboards you with forms, wizards, or setup checklists. Orbita doesn't. The first time you open /talk, Axiom greets you, asks questions, and builds your organism as you answer.

There is no admin panel to fill out. There is no config file to write. The setup experience IS the product — it proves, in the first 3 minutes, what the rest of the system is.

The Flag (empty-state detection)

A single cheap record tells Axiom whether to onboard:

system.onboarding
  → [ ]                     → ONBOARDING mode
  → [{ completed: true, completedAt, leaderName }]  → OPERATIONAL mode

Every inbound message, Axiom's first action is query_data(namespace: "system", collection: "onboarding", filter: {}). One query, one path. Expensive scans (list_agents, list_people) only happen when actually needed.

Why a flag, not scanning state? Checking list_agents to infer "is this empty" made every message pay a directory-scan cost. The flag makes the hot path O(1) and semantically explicit — "this organism has been through setup" is a fact, not something to re-derive.

The 8-Step Flow

Step 1 — Warm greeting

Explain what Orbita is in plain language. No jargon. Frame the empty organism as a feature: "it's yours, let's grow it."

Step 2 — Learn who they are

One question at a time: name, role, org type, language. Create them as an active person-agent (is_leader: true, active: true). Leaders think; team members relay.

Step 3 — Understand their world

Open questions: "Who do you coordinate with? What do you delegate? What eats your time?" Listen before building.

Step 4 — Add their people

As they describe team members, add each as a passive person-agent with their correct language. Confirm each one plainly: "Added Radha (Telugu speaker) to your team."

Step 5 — Identify specialist agents

Based on their described needs, suggest specialist agents (attendance-manager, receptionist, etc.). Always ask before creating. Compose from catalog skills first. Only invoke build_with_architect when custom code is genuinely needed.

Step 6 — Show them what they built

Call list_people and list_agents. Present the organism clearly: "Here's what we built."

Step 7 — Mark onboarding complete, suggest FUSE

Write the flag into system.onboarding, then suggest switching to FUSE mode to lock in the structure.

Step 8 — Invite first use

End with a concrete call to action: "Try it now — ask me to delegate something to Radha."

Conversation Rules

Axiom's onboarding is tuned for first-impression quality:

• One question at a time. No batched forms-disguised-as-chat.
• Don't over-engineer. Start minimal. The user can add later.
• Match their language. If they switch to Hindi, switch with them.
• Confirm after every creation. No silent side effects.
• Speak plainly. Say "team member," not "passive agent."

Everything Exercised in One Flow

Onboarding is the integration test of the whole organism. It hits:

Primitive	Used For
add_person (active)	The leader
add_person (passive)	Each team member
add_agent	Specialist agents the user needs
Catalog composition	Skills assigned per agent
build_with_architect	Custom tools for novel domains (when needed)
set_mode	BUILD → FUSE transition
store_data (system ns)	The onboarding flag
DNA propagation	Every new agent inherits dna.md
Language-aware routing	Each person agent has their own language

If onboarding works end-to-end, the organism works end-to-end.

Why This Is The Killer Demo

A prospect sees Orbita for the first time. They open /talk. Axiom says hi. Three minutes later they have:

• A leader agent (themselves)
• A team of passive agents (their people)
• A specialist agent for their domain
• Mode: FUSE
• A working delegation flow

No forms. No setup screens. No documentation. The conversation was the setup. That's the pitch, delivered.

Failure Modes to Watch

• User says nothing useful — Axiom should still add them as the leader and wait.
• User wants to skip setup — respect it, still write the flag so they're not re-prompted.
• Ambiguous role descriptions — ask clarifying questions rather than guess.
• User comes back mid-onboarding — no persisted progress yet; they restart. (Future: partial-state resume.)

Testing This Yourself

# Wipe the onboarding flag to re-trigger setup:
#   (via Axiom in BUILD mode)
delete_data(namespace: "system", collection: "onboarding", id: <record id>)

# Or fresh DB:
rm -rf .db-data && npm start
# → open http://localhost:3210/talk
# → say "hi"
# → Axiom should greet you as a new user