Redesign onboarding: distribute spotlight highlights + unicycle tutorial loop

[jeonghun-jj-lee]

Important

Problem — The onboarding flow has three issues: (1) Kate's spotlight highlights are bunched at the end in a standalone tour (Stage 7) instead of being woven contextually through the experience, (2) the shouldOnboard predicate includes a profileHasIdentity() check that short-circuits score injection when profile.json already has data from the About You card, and (3) after creating a profile the user is dropped into an unguided session with no understanding of how to use Amicode's research loop, side panel, or project layout.

Approach — Redesign the overture score into a 10-stage unified flow: 6 profile interview stages with distributed spotlight highlights woven in contextually, a bridge stage covering remaining UI surfaces, and a 3-loop guided tutorial using a pre-canned unicycle control problem (feedforward → PID → MPC in Python). The tutorial scaffolds a real Research Project, switches from plan to research mode as a teaching moment, and walks through the side panel (Preview, Files Changed), file tree, context ring, and session management. Fix the loading bug by removing profileHasIdentity() from the onboarding gate. Reuse the existing Tour · prefix spotlight system with 4 new tour targets.

Approaches considered — (A) Tutorial subsystem with dedicated TypeScript orchestration — deterministic scaffolding/execution via a new TS module instead of LLM instructions. More reliable but larger code surface and more to maintain; rejected because the score system was designed for exactly this kind of guided flow. (B) Progressive disclosure — tutorial runs on first research session instead of during onboarding. Shorter onboarding but users leave without seeing most of the UI and it adds complex first-session detection logic; rejected because the goal is full confidence at onboarding exit.

Scope — in: overture SCORE.md rewrite, shouldOnboard bug fix, 4 new tour target annotations, 3 pre-canned Python scripts, tutorial Research Project template, handoff routing simplification, test updates · out: changes to the spotlight rendering engine, new question tool schema fields, intent-specific tutorial variants, changes to the research mode's actual protocol

Assumptions — Python 3.10+ with NumPy, SciPy, and Matplotlib is available on the user's machine (standard scientific Python stack). The LLM can reliably follow structured score instructions for file scaffolding and script execution. The existing Tour · prefix spotlight system handles interleaved tour and non-tour question cards correctly.

Acceptance Criteria

• shouldOnboard() returns true when ~/.amico/profile.json has identity fields but ~/.amico/amicode/onboarding/completed does not exist
• The overture score compiles with 10 stages (welcome, links, intent, research_area, handoff, bridge, tutorial_setup, tutorial_loop_1, tutorial_loop_2, tutorial_loop_3)
• Spotlight highlights fire during the profile interview stages (composer during welcome, tabs during intent, profile + settings after handoff) — not only in a standalone tour stage
• Stage 6 (bridge) presents a compact multi-stop tour card covering context-ring, side-panel, sessions, new-chat, and status
• The tutorial scaffolds a Research Project at ~/amicode-tutorial/ with research-project.toml, environments/, experiments/ (3 scripts), and ledger/
• Each of the 3 tutorial scripts (01_feedforward.py, 02_pid.py, 03_mpc.py) exits 0 and produces expected output in a clean Python 3.10+ environment with NumPy, SciPy, Matplotlib
• The tutorial highlights Preview tab, Files Changed tab, file tree, posture indicator, and context ring at the designated loops
• The session transitions from plan mode to research mode during tutorial_setup
• The completion marker is written after the final tutorial loop, not after the profile handoff
• A user who quits mid-tutorial resumes from the last incomplete stage on next launch
• The standalone Stage 7 tour (9-stop walkthrough) no longer exists in the score
• Score lint (pnpm --filter amicode test -- repertoire_lint) passes
• All 13 tour stops (9 existing + 4 new) resolve to valid CSS selectors in session-tour.test.ts

Testing Decisions

Extend the existing test suites — no new test files needed except for the Python tutorial scripts:

• session-tour.test.ts — extend SCORED_STOPS to include the 4 new targets (file-tree, preview-tab, files-changed, posture)
• repertoire_lint — the existing score linter validates the restructured SCORE.md
• opencode_config.test.ts — add a case for shouldOnboard returning true when profile.json has identity but no completion marker
• New: scores/overture/tutorial/test_scripts.py — pytest runner that executes all 3 scripts in isolation and checks exit codes + output files

Key Decisions

1. Reuse existing spotlight system — the Tour · prefix, isTourRequest(), and SessionTourSpotlight component are unchanged. Highlights are distributed by interleaving Tour-prefixed question cards with regular question cards in the score flow.
2. One unified score — the profile interview and tutorial are a single overture score, not two chained scores. Simpler routing, single completion marker, one resume path.
3. Pre-canned deterministic scripts — the tutorial scripts are bundled static assets, not LLM-authored. Eliminates variance and ensures every user sees the same results.
4. Python runtime for tutorial — universal availability, no Julia toolchain dependency during onboarding. The quantum control workflow (Julia/Piccolo) is introduced post-onboarding.
5. Everyone gets the tutorial — regardless of intent selection. The tutorial teaches Amicode's UI and research loop, which are valuable for all user types.
6. Plan → research mode transition — the tutorial starts in plan mode and explicitly switches to research mode, making the mode system a teaching moment.

Constraints & Invariants

• The spotlight system's Tour · header prefix contract must not change — other scores and future features depend on it
• Tutorial scripts must have zero dependencies beyond NumPy, SciPy, Matplotlib (no cvxpy, no casadi)
• The completion marker path (~/.amico/amicode/onboarding/completed) must remain the sole completion gate
• The score's resume logic must handle mid-tutorial interruption without data loss (profile fields already written remain)
• Pre-canned scripts must be deterministic — same input produces same output on every platform

Prior Art

• scores/overture/SCORE.md — current onboarding score (7 stages)
• session-tour.tsx — spotlight system with TOUR_TARGETS map
• opencode_config.ts:705-711 — shouldOnboard predicate
• handoff_routing.ts — post-onboarding intent routing
• modes/research/ — research mode bundle (mode.toml, pack.toml, card.md)

Notes

The unicycle circle-tracking problem was chosen for universality (no domain expertise needed), fast execution (sub-second Python), and a natural 3-loop narrative (feedforward → PID → MPC) that mirrors the research loop's hypothesis-experiment-analysis cycle. The tutorial project at ~/amicode-tutorial/ persists after onboarding so users can reference it later.