docs: update guidelines for new user and developer (#16)

- Remove old docs 1ff2546f63b8eac799dcd70374258c0075380726 - Update guidelines for new user - Update docs for development ---------
2026-07-02 16:54:03 +07:00
parent 8f89c15e72
commit b9cec2b3ac
9 changed files with 334 additions and 261 deletions
@@ -0,0 +1,221 @@
+# IRIS documentation
+
+Iris is a fast terminal autocomplete assistant written in Go. It wraps around your shell (Zsh, Bash, or Fish) to give you real-time command suggestions, a floating dropdown menu, and smart history search right where you type
+
+## Table of contents
+
+- [Getting started](#getting-started)
+- [Usage guide](#usage-guide)
+- [Configuration guide](#configuration-guide)
+- [Troubleshooting guide](#troubleshooting-guide)
+- [Developer guide](development.md)
+
+## Getting started
+
+### Dependencies
+
+Before installing Iris, ensure your system meets the following requirements:
+- OS: Linux or macOS
+- Terminal emulator with ANSI escape sequence support
+- Go 1.24 or newer if building from source
+
+### Installation
+
+You can install Iris using any of the three methods below:
+
+#### Method 1: Install script (recommended)
+
+Quickly download and install the precompiled binary using our install script:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/versenilvis/iris/main/scripts/install.sh | sh
+```
+
+#### Method 2: Go install
+
+If you already have Go installed on your system, install directly to your `GOBIN`:
+
+```bash
+go install github.com/versenilvis/iris@latest
+```
+
+Ensure that your `$GOPATH/bin` or `$HOME/go/bin` directory is added to your system `PATH`
+
+#### Method 3: Build from source
+
+To develop or compile Iris locally from source, install `just` command runner and execute `just reload`:
+
+```bash
+git clone https://github.com/versenilvis/iris.git
+cd iris
+just reload
+```
+
+### Shell integration setup
+
+To enable intelligent auto-completion and overlay rendering, connect Iris to your shell environment
+
+For Zsh (`~/.zshrc`):
+
+```zsh
+if command -v iris >/dev/null 2>&1; then
+    alias i="iris"
+fi
+```
+
+For Bash (`~/.bashrc`):
+
+```bash
+if command -v iris >/dev/null 2>&1; then
+    alias i="iris"
+fi
+```
+
+For Fish (`~/.config/fish/config.fish`):
+
+```fish
+if command -v iris >/dev/null 2>&1
+    alias i="iris"
+end
+```
+
+Verify your installation by running:
+
+```bash
+iris version
+```
+
+## Usage guide
+
+Once inside an interactive Iris session, your shell receives powerful real-time auto-completion overlays and navigation enhancements
+
+### Core navigation
+
+When you type a command or query, Iris displays a floating overlay box positioned directly below your cursor with matching suggestions
+
+- Up arrow (`↑`): Move the selection cursor up through the suggestion list
+- Down arrow (`↓`): Move the selection cursor down through the suggestion list
+- Tab: Insert the currently highlighted suggestion directly into your command line buffer without executing it
+- Enter: Execute the currently highlighted command immediately or submit the text typed in your prompt
+- Esc: Temporarily dismiss and hide the overlay suggestion menu for the current line
+- Shift+Tab: Permanently disable overlay suggestions until toggled back on
+
+### Mode switching
+
+Iris operates in two primary autocomplete modes: specification suggestions and history navigation
+
+You can toggle between these modes instantly at any time by pressing `Ctrl+R`
+
+- Specification mode (`spec`): Suggests available subcommands, flags, and arguments based on built-in tool specifications (such as git, npm, docker, or go)
+- History mode (`history`): Suggests previous commands from your shell history that match your typed prefix using fuzzy matching
+
+When navigating with arrow keys and pressing `Ctrl+R`, Iris resets the menu selection and immediately loads suggestions for your typed query under the newly active mode
+
+### Instant alias expansion
+
+Iris supports POSIX and shell aliases defined in your configuration
+
+When you type an alias keyword and press the `Space` key, Iris immediately expands the alias into its full command inside your command line buffer
+
+### Ghost text autosuggestions
+
+When ghost text is enabled, Iris displays inline completion suggestions ahead of your cursor in a muted style
+
+- Right Arrow (`→`): Accept the inline ghost text suggestion and append it to your current command line buffer
+
+## Configuration guide
+
+Iris uses a clean TOML configuration file located at `~/.config/iris/config.toml` to customize UI presentation, suggestion behavior, and core engine settings
+
+### Default configuration structure
+
+Below is a complete sample configuration template with all available parameters and comments:
+
+```toml
+# ~/.config/iris/config.toml
+# iris configuration file
+
+[core]
+# schema version
+# do not edit this field manually
+version = 1
+
+# override shell: "bash", "zsh", "fish", keep empty for auto detection
+shell = ""
+
+# startup mode: "last", "spec", "history"
+# "last" = remember last mode used
+mode = "last"
+
+# enable debug logging
+debug = false
+
+[ui]
+# enable inline ghost text
+ghost-text = true
+
+# maximum suggestions to display
+max-suggestions = 100
+
+# maximum height of the overlay
+max-height = 15
+
+[git]
+# hide current branch in checkout/switch list
+filter-active-branch = true
+
+# merge remote and local branches with same name
+deduplicate-branches = true
+
+[updater]
+# check for updates on startup
+check-on-startup = true
+
+# update channel: "stable", "nightly"
+channel = "nightly"
+
+# interval between update checks, e.g. "24h", "6h", "30m"
+check-interval = "24h"
+```
+
+### Configuration sections
+
+- `[core]`: Defines core engine settings including schema version, forced target shell (`bash`, `zsh`, `fish`), initial startup mode (`last`, `spec`, `history`), and diagnostic debug logging
+- `[ui]`: Controls visual layout such as inline ghost text autocompletion, total suggestions rendered, and maximum overlay box height
+- `[git]`: Specialized Git autocompletion behavior such as filtering out the currently active branch when switching and deduplicating local and remote branch names
+- `[updater]`: Configures automated background updates, checking frequency (`check-interval`), and release track (`channel`)
+
+### CLI configuration commands
+
+Iris provides built-in commands to inspect and modify settings directly from your shell:
+
+```bash
+iris config init
+iris config view
+iris config edit
+iris config reset
+```
+
+## Troubleshooting guide
+
+If you encounter unexpected behavior while running Iris, use the diagnostic procedures outlined below
+
+### Debug mode and logging
+
+To inspect overlay positioning or command interception bugs in real time, launch Iris in debug mode:
+
+```bash
+iris -d
+```
+
+Runtime activities are written directly to the log file located at `~/.cache/iris/iris.log`. You can follow real-time events by running:
+
+```bash
+tail -f ~/.cache/iris/iris.log
+```
+
+> [!Caution]
+> ### Common issues and solutions
+> - Overlay Position Misaligned: Multi-line shell prompts (such as Starship) emitting ANSI codes can cause offset issues. Iris automatically parses carriage returns (`\r`) and horizontal escape codes (`\033[nC`) to anchor visual columns accurately
+> - Menu Disappears When Toggling Mode: When pressing `Ctrl+R` after arrow navigation, Iris restores the original search query automatically so suggestions reload cleanly
+> - Inspecting Crash Logs: If the session terminates unexpectedly, inspect captured stack traces by running `iris crash-log`