From 86cd2a122d7f41d906fd4d487bcccd6bcecccef2 Mon Sep 17 00:00:00 2001
From: Shunsuke Hayashi <supernovasyun@gmail.com>
Date: Sun, 23 Nov 2025 01:51:38 +0900
Subject: [PATCH] docs: Add 60-second setup and troubleshooting to README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add prominent quick start section at the top
- Add comprehensive troubleshooting section
- Cover common issues: API key, terminal errors, build errors
- Include debug mode instructions and help resources

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/README.md b/README.md
index 2233dea..93ddf37 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,25 @@
 
 A powerful terminal-based AI assistant with TUI (Terminal User Interface) built in Rust.
 
+## 60-Second Setup
+
+```bash
+# 1. Clone and build
+git clone https://github.com/ShunsukeHayashi/miyabi-cli-standalone.git
+cd miyabi-cli-standalone
+cargo build --release
+
+# 2. Set API key
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# 3. Run
+./target/release/miyabi tui
+```
+
+That's it! Start chatting with Claude in your terminal.
+
+---
+
 ## Features
 
 - **Interactive TUI** - Beautiful terminal interface with markdown rendering
@@ -410,6 +429,61 @@ Supported models:
 - `claude-haiku-4-5-20251001`
 - `claude-sonnet-4-20250514`
 
+## Troubleshooting
+
+### Common Issues
+
+#### "API key not found"
+```bash
+# Check if environment variable is set
+echo $ANTHROPIC_API_KEY
+
+# Or add to config file
+vim ~/.miyabi/config.toml
+# [api]
+# api_key = "sk-ant-..."
+```
+
+#### "Device not configured" error on TUI start
+This usually means the terminal doesn't support the required features. Try:
+```bash
+# Use a different terminal emulator (iTerm2, Alacritty, etc.)
+# Or run with explicit terminal type
+TERM=xterm-256color ./target/release/miyabi tui
+```
+
+#### Build errors
+```bash
+# Make sure Rust is up to date
+rustup update
+
+# Clean and rebuild
+cargo clean
+cargo build --release
+```
+
+#### Session not saving
+```bash
+# Check permissions on sessions directory
+ls -la ~/.miyabi/sessions/
+
+# Create if missing
+mkdir -p ~/.miyabi/sessions
+```
+
+### Debug Mode
+
+For verbose logging:
+```bash
+RUST_LOG=debug ./target/release/miyabi tui
+```
+
+### Getting Help
+
+- Check `miyabi --help` for CLI options
+- Press `F1` in TUI for keybindings
+- Open an issue: https://github.com/ShunsukeHayashi/miyabi-cli-standalone/issues
+
 ## License
 
 MIT