Quick Start

Quick Start Guide

Welcome to Tuim! This guide walks you through your very first launch, explains the onboarding wizard, introduces the workspace layout, and shows you the essential shortcuts needed to get productive immediately.

---

1. First Run & Onboarding Wizard

When you launch Tuim for the first time by typing tuim, you are greeted by an interactive onboarding banner:

╭─────────────────────────────────────────────────────────────╮
│ Welcome to Tuim! Choose your preferred editing style:       │
│                                                             │
│   [i] IDE Mode    - Familiar modeless editing, Ctrl+S/Z/C/V │
│   [n] Normal Mode - Traditional Vim modal motions & leader  │
│   [l] Language Tools - Manage LSP servers & formatters      │
│                                                             │
│ Press 'i' or 'n' to select, or Escape to start editing.     │
╰─────────────────────────────────────────────────────────────╯

• Press i if you prefer IDE Mode: you can start typing immediately, select text with your mouse or Shift+Arrows, and use standard shortcuts (Ctrl+S to save, Ctrl+Z to undo, Ctrl+C/Ctrl+V for copy/paste).
• Press n if you prefer Normal Mode: you get standard Neovim modal editing (Normal, Insert, Visual modes, standard motions h/j/k/l, and <Space> as the leader key).
• Press l to inspect and install Language Servers via Mason.
• Press Esc, Enter, or q to close the guide and begin editing.

Tip

You can reopen the onboarding guide at any time by running :TuimOnboarding in Normal mode, or pressing o while viewing Help.

---

2. Interface Layout

Tuim's interface is divided into clean, focused functional areas:

┌─────────────────────────────────────────────────────────────┐
│ < Workspace   Explorer   [Commands F1]                      │ Header Bar
├────────────────┬────────────────────────────────────────────┤
│ Workspace      │ main.zig                                   │
│ ────────────── │ 1 const std = @import("std");              │
│ 📁 src         │ 2                                          │
│   📄 main.zig  │ 3 pub fn main() !void {                    │ Editor Viewport
│   📄 app.zig   │ 4     std.debug.print("Hello Tuim!\n", .{});│
│ 📁 tests       │ 5 }                                        │
│                │                                            │
├────────────────┴────────────────────────────────────────────┤
│ ❯_ Terminal                                            [x]  │ Persistent Terminal
│ user@host:~/Projects/demo$ zig build run                    │
├─────────────────────────────────────────────────────────────┤
│ [NORMAL] main.zig                                     utf-8 │ Status Footer
└─────────────────────────────────────────────────────────────┘

1. Header Bar: Displays current view controls, clickable breadcrumbs (< Workspace), and the [Commands F1] search trigger.
2. Left Sidebar: Houses the file Explorer, open files list, Git changes panel, Extensions manager, and AI Assistant launcher.
3. Editor Viewport: The main code editing area powered by Neovim, supporting splits, syntax highlighting, and hover diagnostics.
4. Integrated Terminal Panel: A persistent shell at the bottom, toggled with Ctrl+T.
5. Status Footer: Shows the current editing mode (NORMAL, IDE, or ZEN), active file path, encoding, and cursor position.

---

3. Essential Navigation Shortcuts

Action	Shortcut	What It Does
Search Commands	F1	Opens the fuzzy searchable command palette.
Cycle Regions	F6 / Shift+F6	Switches focus between Editor, Sidebar, and Terminal.
Toggle Sidebar	Ctrl+E	Shows or hides the workspace sidebar.
Toggle Terminal	Ctrl+T	Opens or hides the bottom persistent shell panel.
Toggle Zen Mode	F11	Enters distraction-free full-screen editor mode.
Find File	Ctrl+P	Fuzzy finds files across your project with Telescope.
Find in Files	Alt+G	Searches text across all files using ripgrep.
Save File	Ctrl+S	Saves current file. Prompts for filename on new buffers.

---

4. Your First Workflow: Creating & Saving a File

1. Create a Buffer:
   • Press Ctrl+N (or open F1 and select New file).
2. Write Content:
   • In IDE Mode, simply start typing.
   • In Normal Mode, press i to enter Insert mode, then type your text.
3. Save with a Name:
   • Press Ctrl+S.
   • A prompt appears asking for the file name (e.g., hello.zig or notes.txt).
   • Type the file path and press Enter.
   • If you change your mind, press Esc to cancel naming without losing any of your typed text.
4. Open the Terminal:
   • Press Ctrl+T to bring up your shell.
   • Run your compiler, script, or tests (e.g., zig build run).
   • Press Ctrl+T again to hide the terminal—your shell session continues running in the background!

---

5. Next Steps

• Read the Editing Modes Guide to learn how Normal, IDE, and Zen modes work.
• Check out the Keybindings & Shortcuts Guide to customize your keys.
• Explore Extensions & Plugins to customize your tools.