Enhanced Onboarding: Orient → Demo → Collect

[jeonghun-jj-lee]

Important

Problem: New Amicode users face two compounding issues at first launch. First, there is no model configured yet — the extension activates but there is nothing to talk to, so any conversational onboarding is impossible before this is resolved. Second, once a model is set up, the existing overture immediately asks profile questions with no explanation of what Amicode is or what value it delivers. Users answer on faith, the vault starts empty, and rich context they already have in existing AI-tool configs (CLAUDE.md, AGENTS.md, opencode configs, etc.) is discarded and re-asked from scratch.

Approach: A two-phase onboarding: a non-agentic webview (Stage 0) handles model setup before any chat is possible, then an agentic overture (Stages 1–8) orients, seeds, demos, and collects. The webview opens with the branded welcome animation — the first thing the user sees — then presents a provider/key/model form. Once a model is verified, the chat opens and Amico takes over. The context-seed step (Stage 3) reuses the existing distiller pipeline to bootstrap the vault from allowlisted AI-tool configs on opt-in, avoiding a parallel vault writer. The demo (Stage 4) is framed as a workflow showcase — not OC-specific — and is gated on Julia readiness so a failed demo never mars the first impression.

Approaches Considered:

Approach	Verdict
Enhanced overture score with integrated model setup + context-seed (chosen)	Chat-first after model gate; adaptive; shows real value via demo; vault starts warm; minimal new infrastructure
Separate welcome webview for full onboarding	Visually polished but sets false expectations (product is chat-first); significant lift; doesn't demonstrate the workflow
VS Code walkthrough contribution	Native surface but splits attention; can't adapt to experience level
Standalone amico import CLI outside onboarding	Low discoverability; onboarding is the only moment we know the vault is empty
Context-seed scan + auto-write with no preview	Privacy/accuracy risk; violates distiller no-secrets/idempotency discipline
Experience-level branching (QOC newcomer vs. experienced)	Removed — Amicode is a general agentic coding and research studio, not solely a QOC tool; pigeonholes the product identity at first impression

Scope:

• Stage 0 webview: welcome animation, provider picker, API key input, model selection, test-connection gate, config write
• Rewrite scores/overture/SCORE.md as 8 agentic stages (orientation, intent, context-seed, demo, environment, devices, goals, handoff)
• Auto-launch onboarding session on fresh install (wiring in extension.ts)
• Opt-in context-seed: allowlisted file scan, secret redaction, grouped preview with deselect, distiller materialization (profile + memory only initially)
• Demo workspace management (__demo__ problem workspace, auto-archived); demo framed as workflow showcase
• Intent multi-select (general coding & software development / research / exploring) recorded as profile metadata; handoff routes by selection
• Pre-fill of environment/device stages from seed results
• One-shot flags (welcome_shown separate from onboarding_completed)

Out of scope: storing secrets/tokens; importing raw pulses or problem state; writing team/project vaults; continuous background sync; exhaustive editor coverage (start with obvious files); method/reference hint extraction (future if signal is clean); research sub-type branching during onboarding (deferred to pulse-designer interview)

Assumptions / Open Qs:

• Exact file allowlist and scan roots (home vs armonia repos vs current workspace) are open — implementer proposes, reviewer approves
• Consent granularity (single toggle vs per-file/per-group deselect) is open — preview is required, exact UX is implementer's call
• Whether seeds pre-fill Stage 5/6 interactively ("I found you use QICK — confirm?") or silently skip re-asking is an implementation detail
• The vetted transmon X-gate template converges reliably in ~30s on a precompiled environment
• Julia readiness can be detected reliably (juliaup on PATH + Manifest.toml present)
• The in-chat animation (if any post-webview transition effect is desired) is achievable within the existing chat renderer architecture

---

Enhanced Onboarding: Model Setup → Orient → Seed → Demo → Collect

Stage Flow

┌─────────────────────────────────────────────────────┐
│ Extension activation                                 │
│   shouldOnboard? ──yes──► has model configured?      │
│                             no  → Stage 0 (webview)  │
│                             yes → auto-open chat     │
└─────────────────────────────────────────────────────┘

┌─ Stage 0: model setup (NON-AGENTIC, webview) ───────┐
│                                                      │
│  A. Welcome animation                                │
│     Logo fade-in → dissolve (~2-3s)                  │
│     Pure brand moment, no interaction required       │
│                                                      │
│  B. Model configuration                              │
│     Provider picker → API key → model → test         │
│     On success: write config, close webview,         │
│                  auto-open chat panel                 │
│                                                      │
└──────────────────────────────────────────────────────┘
         │
         ▼  (chat opens — agentic from here)

┌─ Stage 1: orientation ──────────────────────────────┐
│ "I'm Amico." — 2-3 messages: what Amicode is —      │
│ agentic coding studio with memory, deep QOC          │
│ specialization today, growing into broader           │
│ research automation.                                 │
│ Collects name naturally ("what should I call you?")  │
└──────────────────────────────────────────────────────┘
         │
         ▼
┌─ Stage 2: intent (multi-select) ────────────────────┐
│ "What brings you to Amicode?" (select all that apply)│
│ ☐ General coding and software development            │
│ ☐ Research                                           │
│ ☐ Exploring                                          │
│ (Recorded as profile metadata; informs handoff.      │
│  Research sub-type deferred to pulse-designer.)      │
└──────────────────────────────────────────────────────┘
         │
         ▼
┌─ Stage 3: context-seed ─────────────────────────────┐
│ "I can scan your existing AI-tool configs to         │
│  bootstrap your vault — want me to?"                 │
│  yes → scan allowlisted, size-capped paths           │
│         redact secrets at read time                  │
│         show grouped preview (profile + memory)      │
│         user deselects groups if desired             │
│         confirm → distiller materializes seeds       │
│  no  → zero extra file reads, continue              │
└──────────────────────────────────────────────────────┘
         │
         ▼
┌─ Stage 4: demo ─────────────────────────────────────┐
│ Gate: Julia on PATH + Manifest.toml exists?          │
│  yes → "Let me show you the workflow end-to-end"     │
│         transmon X gate (T=10ns, N=50, max_iter=60)  │
│         entity strip populates, Run Inspector        │
│         streams, result converges (F > 0.999)        │
│         auto-archived __demo__ workspace             │
│  no  → explain readiness requirement, defer,         │
│         continue without demo                        │
└──────────────────────────────────────────────────────┘
         │
         ▼
┌─ Stage 5: environment ──────────────────────────────┐
│ QICK lab / cloud-Pasqal / simulation-only / other   │
│ (pre-filled from context-seed if available →         │
│  "I found you use QICK — confirm?")                  │
└──────────────────────────────────────────────────────┘
         │
         ▼
┌─ Stage 6: devices (optional) ───────────────────────┐
│ Specific QPU/emulator to remember                    │
│ (pre-filled from seeds if available)                 │
└──────────────────────────────────────────────────────┘
         │
         ▼
┌─ Stage 7: goals ────────────────────────────────────┐
│ What they want to accomplish with Amicode            │
└──────────────────────────────────────────────────────┘
         │
         ▼
┌─ Stage 8: handoff ──────────────────────────────────┐
│ Fire onboarding_completed                            │
│ Route by Stage 2 intent selections:                  │
│   Research (any) → offer pulse-designer interview    │
│   General coding only → open session, highlight      │
│                          memory + vault features     │
│   Exploring only → open session, offer tour          │
│   Research + General → pulse-designer, mention       │
│                          broader studio capabilities │
└──────────────────────────────────────────────────────┘

---

Acceptance Criteria

Stage 0 — Model setup:

1. On fresh Amicode install with no model configured, opening VS Code triggers the onboarding webview automatically — no user action required.
2. The webview opens with the branded welcome animation (logo fade-in, ~2-3s) as the first visual — before any form elements appear. Plays exactly once (welcome_shown flag).
3. After the animation, the model configuration form appears: provider picker, API key/credential input (masked), model selection, and a "Test connection" button. No LLM calls are made until the user initiates the test.
4. On successful connection test, config is written and the webview closes. The chat panel auto-opens and the agentic onboarding begins.
5. If a model is already configured on activation, Stage 0 is skipped entirely — the chat opens directly.

Stage 1 — Orientation:
6. Amico's first message introduces Amicode as a general agentic coding and research studio (not solely a QOC tool). The orientation does not branch by experience level — it is the same depth for all users.
7. The user's name is collected naturally within the orientation messages (not as a separate form stage).

Stage 2 — Intent:
8. Amico presents a multi-select (checkbox) intent question: "General coding and software development", "Research", "Exploring". User can select any combination. Selections are recorded as profile metadata.
9. Research sub-type (platform, problem type) is NOT asked during onboarding — it is deferred to the pulse-designer interview at handoff.

Stage 3 — Context-seed:
10. Amico offers an explicit opt-in to scan existing AI-tool context files. Declining results in zero extra file reads and no behavior change.
11. On accept, only allowlisted, size-capped paths are read; secret-like values (api_key/token/password/Bearer/AKIA/PEM) are redacted to «credential omitted» at read time and never persisted.
12. User sees a preview of extractable facts (profile identity + typed memory cards) grouped by vault target with source provenance, and can deselect groups before confirming.
13. On confirm, seeds flow through the existing onboarding/events.jsonl → distiller pipeline and are materialized under <vault>/amicode/ with the usual hard rules (completion gate, pathspec-scoped commit, idempotency, no invention of fidelity).
14. Re-running the import is idempotent — no duplicate cards or MEMORY.md lines.

Stage 4 — Demo:
15. If Julia is installed and ~/.amico/julia/Manifest.toml exists, Amico offers and runs a transmon X-gate demo (T=10ns, N=50, max_iter=60), framed as a workflow showcase ("Let me show you the workflow end-to-end") — not as the user's first real solve. User sees the entity strip populate, Run Inspector stream iterations, and a converged result (F > 0.999).
16. If Julia is not ready, the demo is skipped with an honest explanation. The skip does not block onboarding.
17. The demo uses a __demo__ problem workspace that auto-archives after completion. It does not appear in the user's problem history.
18. The demo always uses the vetted transmon X-gate template with stock parameters — never a free-tier script.

Stages 5–7 — Collection:
19. Environment and device stages present values extracted by context-seed as confirmation prompts ("I found you use QICK — confirm?") rather than re-asking from scratch when seeds are available.

Session lifecycle:
20. Handoff fires onboarding_completed; subsequent sessions skip the overture entirely.
21. If the user closes the chat mid-onboarding, partial state is preserved. Re-opening triggers resume, not restart. The welcome animation does not replay.
22. "Skip" / "I'll do this later" at any point saves partial state, does NOT fire onboarding_completed, and the next session offers "Resume setup" prominently.
23. Handoff routes by Stage 2 intent: Research (alone or combined) → pulse-designer interview; General coding only or Exploring only → open session.

---

Key Decisions

Decision	Choice	Rationale
Model setup surface	Non-agentic webview form	No LLM exists yet; form is deterministic and can validate the connection before chat starts
First visual	Welcome animation in the webview (before form elements)	Pure brand moment at true first touch; chat opens into a live agent without replaying it
Experience-level branching	Removed	Amicode is a general agentic coding + research studio; OC-specific branching pigeonholes the product identity
Orientation tone	Generic: agentic studio with memory, deep QOC today, growing into research automation	Honest about current state and direction without narrowing first impression
Intent question	Multi-select checkboxes (general coding / research / exploring)	Multiple motivations coexist; checkboxes capture that honestly; single-select would force false exclusivity
Research sub-type	Deferred to pulse-designer interview	Pulse-designer already resolves platform and problem type naturally; front-loading it in onboarding is premature
Handoff routing	By intent selections (not a single branch)	Intent is a signal, not a lock; research + general coding users get both paths acknowledged
Context-seed placement	After orientation (Stage 3), before demo (Stage 4)	Name collected; extracted priors available for demo narration and pre-filling Stages 5–6
Context-seed pipeline	Reuse amicode_profile → events.jsonl → distiller	No new vault writer; leverages existing completion-gate, secret-scrub, pathspec-scoped commit discipline
Context-seed scope	Profile + memory only (initially)	Conservative start; expand to method/reference hints in follow-up if signal is clean
Demo content	Always transmon X gate (vetted template, stock params)	Fastest, most reliable convergence; showcases the full workflow loop regardless of user's domain
Demo framing	Workflow showcase ("end-to-end workflow")	Works for all intent selections, not just research/OC users
Demo gating	Gate before offering (Julia on PATH + Manifest.toml)	Failed demo during first impression is worse than no demo

---

Constraints & Invariants

• Stage 0 webview MUST NOT make any LLM calls — it is entirely deterministic until "Test connection" succeeds
• Welcome animation MUST play before any form elements appear in the webview
• Welcome animation plays exactly once (welcome_shown flag); does not replay on resume or re-open
• Orientation MUST NOT branch by experience level — same depth for all users
• Context-seed MUST NOT store secrets — redact to «credential omitted» and note omission
• Context-seed MUST NOT write outside <vault>/amicode/ and MUST use pathspec-scoped commits
• Context-seed MUST NOT invent facts — every seeded line must trace to a file or explicit user confirmation
• Context-seed MUST NOT break shouldOnboard routing — declining still completes overture normally
• Permission grants for scanning are narrowly scoped to the allowlist; no broad home-directory grant
• Vault routing: personal vault only; team/public promotion remains PR-gated
• Demo MUST use the vetted template with stock parameters — never free-tier
• shouldOnboard predicate logic unchanged (same conditions, extended with model-presence check)
• onboarding_completed marker meaning unchanged — distiller contract stable
• Auto-launch fires at most once per VS Code window (in-memory flag prevents re-trigger on dismiss)

---

Prior Art

• macOS setup assistant: branded welcome → progressive collection → first experience
• Existing overture score (scores/overture/SCORE.md): 6-stage linear interview (this replaces it)
• Existing shouldOnboard predicate and compileChainedScore machinery
• __demo__ workspace pattern (similar to Bug session archival — ADR 0004)
• packages/extension/opencode-plugin/onboarding.ts — ops-side events.jsonl stream, secret scrub, triggerOnboardingDistill
• packages/extension/src/substrate/distiller.ts + packages/extension/opencode-plugin/distill_queue.ts — queue/lock/drain + OPENCODE_CONFIG_CONTENT transport
• packages/extension/DISTILLER.md — onboarding materialization templates for PROFILE.md/environment/devices/memory; hard rules (pathspec commit, completion gate, idempotency, match-before-create)
• packages/extension/scripts/distill_batch.mjs — precedent for retro-ingest from external sources (context-seed is the third source after problems/runs)
• packages/extension/src/substrate/vault_setup.ts + mount_store.ts / vault_store.ts — vault creation, discovery, readProfileMd / hasOnboardingCompleted gates
• packages/extension/src/opencode_config.ts:shouldOnboard — routing predicate to extend (add model-presence check)

---

Source

• Original design (Enhanced Onboarding: Orient → Demo → Collect #359): brainstorming session, all branches resolved
• Context-seed feature (Seed onboarding vault from existing Claude/Codex/etc. context #422): session request; subsumed into this design as Stage 3
• Scratchpad: ~/.amico/vaults/vault-aaron/scratchpad/issue-onboarding-seed-from-ai-context.md

---

Notes

• The orientation messages in the SCORE are guidance, not canned strings — Amico adapts naturally to user questions mid-flow
• Demo workspace archival should follow Bug session precedent (ADR 0004): machine-managed lifecycle, kept out of problem history
• No new domain terms introduced — "overture" remains the correct term for the agentic phase (Stages 1–8)
• Welcome animation lives in the webview (Stage 0); the chat renderer does not need to implement it
• Context-seed allowlist/UX details are intentionally open — implementer proposes and gets review before building
• Expand seed scope to method/reference hints in a follow-up issue if profile + memory signal is clean
• If the allowlist covers ~/, ~/.config/, or ~/armonia/repos/*, keep depth and byte caps explicit and add corresponding external_directory grants only for the overture agent