[Phase 1] Gated tutorial session type: first-launch detection, skip, and replay #334

Story

As a first-time TalkTerm user,
I want have the guided tutorial launch automatically on my very first run, with a clearly visible way to skip it and a way to replay it later,
so that I get a gentle introduction the first time without ever being forced through it again or losing the option to revisit it.

Acceptance Criteria

1. A dedicated tutorial/onboarding session type exists, distinct from a normal session, that can be started programmatically.
2. On first launch (detected via absence of an existing user profile per FR36) the tutorial session starts automatically.
3. A clearly visible Skip control is present throughout the tutorial and ends it immediately, returning the user to the normal app entry point.
4. Completing or skipping the tutorial is persisted so it never auto-launches again for that user.
5. A manual 'replay tutorial' entry point re-runs the tutorial on demand without altering the first-launch persistence semantics.
6. A feature flag can disable auto-launch of the tutorial without removing the manual replay entry point.

Tasks / Subtasks

• Register a dedicated tutorial/onboarding session type distinct from a normal session. (AC: Install BMad Method v6.2.0 with Claude Code integration #1)
• Add first-launch detection based on user-profile existence (FR36) and auto-start the tutorial session when no profile exists. (AC: Add brainstorming session: TalkTerm concept review and revision #2)
• Add a persistent, always-visible Skip control that terminates the tutorial and routes to the normal entry point. (AC: chore: add Dependabot with auto-merge via GitHub App #3)
• Persist a 'tutorial seen' flag on completion and on skip, and gate auto-launch on it. (AC: Bump actions/create-github-app-token from 1 to 3 #4)
• Expose a manual replay entry point that starts the tutorial session without clearing the 'tutorial seen' flag. (AC: Add architecture, UX design, and enhanced planning artifacts #5)
• Add a feature flag that disables auto-launch while leaving manual replay intact. (AC: fix: configure CodeQL to scan Python only #6)

Dev Notes

• This story is the gating/lifecycle shell only; the step content and step engine come in later stories. Keep the tutorial session type a thin wrapper the engine plugs into.
• First-launch detection must reuse the existing FR36 profile-existence check rather than introduce a second source of truth for 'has this user run before'.
• Skip must be reachable at every step (a persistent control, not per-step), because a user may decide to bail at any point.
• Persist 'tutorial seen' the same way other first-run/profile state is persisted so it survives restarts; do not gate solely on in-memory state.
• Testing: unit-test the gating decision (profile present/absent x flag on/off x seen/unseen) as a pure function so it is deterministic and does not require driving the UI.

Project Structure Notes

Adds a new session type alongside existing session types and a small first-run gating check; no changes to the underlying avatar/ActionCard/OutputPanel systems.

References

• TalkTerm FR36 — first-launch detection via user-profile existence
• TalkTerm PRD — Journey 1 (Sarah's first workflow) and the setup (Epic 2) to first-workflow (Epic 6) gap
• Ideas Discussion 💡 Guided Interactive Onboarding: Avatar-Led Learn-by-Doing First Session #245 — Suggested Next Step (first-launch-only, with skip option)

Likely target surface

• session-type registration / routing
• first-run gating check
• onboarding feature flag

Story prepared by the BMAD Scrum Master (Bob) for epic #333. Status: ready-for-dev.