## Problem The first time a user runs `duo`, the experience does not match the standard emerging across modern AI CLIs: - There is no project context scaffolding (`AGENTS.md` or equivalent) created on first run, so the agent starts from the auto-detected git remote alone. - The TUI loads into an empty chat. There is no welcome, no shortcut hint, and no example prompt. `/help` exists but is undiscoverable, and there is no quick-access key (e.g. `?`) to open it. - The configuration TUI shown when credentials are missing offers no guidance on what is being asked for, no validation, and no escape hatch. - The existing TUI status bar shows the active model only — no project, no session state — so users have no quick way to confirm what they are working on. - There is no theme picker and no visible cue that the user is ready to interact. The result: a user who installs `duo` and runs it for the first time has to read external documentation before they can do anything useful. ## Goal A first-time user can go from `duo` (after install) to a useful first interaction inside 60 seconds, without reading external documentation. ## Scope This Epic groups the work needed to overhaul the first-run path: project scaffolding, in-TUI orientation, theme handling, and configuration UX. Sign-in flow and credential handling are intentionally **out of scope** — they have their own Epic covering OAuth, granular tokens, and credential storage: [`&22820` Improve credential handling](https://gitlab.com/groups/gitlab-org/-/epics/22820) (see Related). ### Issues already open that fall under this Epic - gitlab-org/editor-extensions/gitlab-lsp#2326 — Customise themes - gitlab-org/editor-extensions/gitlab-lsp#1945 — Add `--help` flag documentation for `duo` command - gitlab-org/editor-extensions/gitlab-lsp#2247 — Skill slash commands not available immediately on TUI startup ### New issues to be created under this Epic 1. First-run welcome card in the TUI — detected project, current model, top shortcuts, one example prompt; dismissed on first keystroke. 2. Add `?` keybinding to open the help dialog from the TUI input, as a shorthand for `/help`. Gated on empty input so typing `?` in a prompt still works. 3. Extend the existing TUI status bar — fill in project (left) and session state (middle); model (right) is already present. Sensible defaults only; user-configurable status line content is out of scope. 4. Improve the configuration TUI shown when credentials are missing — clearer copy, API ping validation on submit, and an explicit "use `glab` instead" exit. 5. Show theme picker on first run (depends on #2326). 6. Rotating tip line shown above the TUI input on launch. 7. Design alignment for first-run TUI layout — short design artifact covering stacking order, transient vs persistent elements, and narrow-terminal handling. Gates implementation of 1, 3, and 6. 8. Docs: GitLab Duo CLI — refresh first-run / onboarding documentation. Created in the `gitlab-org/gitlab` docs project, cross-linked from this Epic. ### Related but out of scope - [**`&22820` Improve credential handling**](https://gitlab.com/groups/gitlab-org/-/epics/22820)**.** Covers browser-based OAuth (nested `gitlab-org/editor-extensions&233`), credential storage (`#1649`, `#2409`), and the scope/granularity of tokens issued. - gitlab-org/-/epics/21199 — Granular tokens for Duo CLI and IDE features. Will likely be a sibling of, or inform, the sign-in Epic. - gitlab-org/editor-extensions/gitlab-lsp#2316 — UX analysis that motivated this Epic. Not a child issue; this Epic is its output. - User-configurable status line content. The default is in scope; making it configurable is a separate, post-onboarding ask. ## Success criteria - A new user with valid credentials can run `duo`, see the project context, learn the core shortcuts and slash commands without leaving the TUI, and send a useful first prompt without consulting external documentation. - Active model, project, and session state are visible in the TUI status bar without running a slash command. - Keyboard shortcuts and slash commands are discoverable from the TUI itself. - Public getting-started documentation matches the in-product behaviour at the end of this Epic.