feat: first-run UX — /connect flow, doctor hints, TUI polish, docs refresh

#449: /connect guides Ollama or OpenRouter key entry when no model
is configured. Auth PUT discovers OpenRouter. Welcome and status bar
cue /connect when no providers are found.

#450: doctor treats local connection refused as warning when another
provider works. Exit 1 only with no usable provider. Next-step hints.

#451: README and install.sh lead with install script and Homebrew.
First-prompt quickstart path. Go 1.27.1+ requirement. Config filenames.

#452: TUI polish — help title, sessions key 'o', which-key 2s timeout,
"New Session" in sidebar, Esc no longer rejects permissions.

#453: /init documented as optional Red Hat plugin/role setup. Points
users to /connect for model configuration.

Author: bobbyjohnstx

CHANGELOG.md

@@ -34,6 +34,7 @@ Security, stability, and correctness fixes from two rounds of code review (61 is
 - Goal patterns expanded to multi-ecosystem support (Go, Python, Node, Rust, Java)
 - Readline preview for command history
 - Overflow false-positive detection in context window warnings
+- First-run `/connect` flow: empty-state Ollama/OpenRouter guidance, prompt short-circuit, and OpenRouter API key entry in the TUI
 
 ### Architecture
 - `Context.clone()` replaces manual copy sites in tool execution

README.md

@@ -6,15 +6,50 @@ Local-first AI coding assistant. Bring any model — single binary, no runtime d
 
 [![Go CI](https://github.com/bobbyjohnstx/tinycode/actions/workflows/go-ci.yml/badge.svg)](https://github.com/bobbyjohnstx/tinycode/actions/workflows/go-ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-## What it is
+Local-first, model-agnostic AI coding assistant. A single Go binary embeds the HTTP server, terminal UI, session management, LLM client, and tool execution --- no Node.js, no separate server process. Works with any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, OpenRouter, and more). Your sessions stay in local SQLite; data leaves your machine only when you send a prompt to a provider you configured.
+
+## Quick start
+
+### Install
+
+```bash
+# One-liner (macOS / Linux) — installs to ~/.local/bin
+curl -fsSL https://raw.githubusercontent.com/bobbyjohnstx/tinycode/main/install.sh | sh
+
+# Or Homebrew
+brew install bobbyjohnstx/tap/tinycode
+```
+
+See [docs/install.md](docs/install.md) for platform notes, PATH setup, and verifying the install.
+
+### First prompt
+
+Have a local model running (for example `ollama serve` and `ollama pull qwen3.5:9b`), then:
+
+```bash
+tinycode                          # TUI in the current directory
+tinycode /path/to/project         # TUI against a project
+```
+
+Type a prompt and press Enter:
+
+```
+Explain what this repository does in 2 sentences.
+```
 
-tinycode is a local-first, model-agnostic AI coding assistant. A single Go binary embeds everything: HTTP server, terminal UI, session management, LLM client, and tool execution. No separate server process, no Node.js, no runtime dependencies.
+Press `Ctrl+X` then `m` to pick a model if needed. Full walkthrough: [docs/getting-started.md](docs/getting-started.md).
 
-**Works with any OpenAI-compatible endpoint.** Connect to local models (Ollama, vLLM, LM Studio), cloud providers (OpenRouter, Anthropic, OpenAI), or your own infrastructure (RHOAI, Azure, custom endpoints). Swap models mid-session. No vendor lock-in.
+### Build from source
 
-**Your data stays on your machine.** Sessions, config, and conversation history are stored locally in SQLite. No telemetry, no cloud calls, no sign-up. Data only leaves your machine when you explicitly send a prompt to a cloud provider you configured.
+```bash
+git clone https://github.com/bobbyjohnstx/tinycode.git && cd tinycode
+make build
+./dist/tinycode
+```
 
-tinycode reads your files, runs commands, edits code, and works through multi-step tasks --- the same workflow as cloud AI coding tools, but you choose the model and control the data.
+Requires Go 1.27.1+. Other modes: `tinycode serve` (headless API), `tinycode acp` (IDE), `tinycode run` (non-interactive).
+
+## What it is
 
 ### Key features
 
@@ -60,24 +95,6 @@ tinycode also supports:
 - **Agent Client Protocol** (`tinycode acp`) --- stdio transport for IDE integration (VS Code, Zed, JetBrains)
 - **Non-interactive mode** (`tinycode run`) --- run a prompt and exit, for scripts and CI
 
-## Quick start
-
-```bash
-# Build from source
-git clone https://github.com/bobbyjohnstx/tinycode.git && cd tinycode
-make build
-./dist/tinycode
-
-# Or with a specific project directory
-./dist/tinycode /path/to/project
-
-# Headless API server
-./dist/tinycode serve
-
-# IDE integration (Agent Client Protocol)
-./dist/tinycode acp
-```
-
 ## Architecture
 
 Standard Go layout: `cmd/` for binaries, `internal/` for private packages, `pkg/` for public SDK.
@@ -98,7 +115,7 @@ Single entry point. Subcommands: `tui` (default), `serve`, `web`, `acp`, `run`,
 | `provider/`    | Provider auto-discovery (Ollama, vLLM, LM Studio, OpenRouter)                  |
 | `agent/`       | Agent definitions and prompt files                                             |
 | `tool/`        | Tool implementations (file ops, shell, grep, glob)                             |
-| `config/`      | Config file parsing (`~/.config/tinycode/config.json`), JSONC support          |
+| `config/`      | Config file parsing (`tinycode.jsonc` → `tinycode.json` → `config.json`)       |
 | `storage/`     | SQLite via modernc.org/sqlite, migrations                                      |
 | `bus/`         | Event bus for inter-component communication                                    |
 | `mcp/`         | Model Context Protocol client                                                  |
@@ -206,9 +223,10 @@ Agents with a `.compact.md` variant automatically use a smaller prompt for model
 
 ## Configuration
 
-Config lives at `~/.config/tinycode/config.json` (JSONC supported):
+Config is loaded from `~/.config/tinycode/` with a 3-name fallback per directory: `tinycode.jsonc` → `tinycode.json` → `config.json` (first file found wins; JSONC comments are supported). Project config uses the same names under `.tinycode/` (or walking up from the working directory); innermost wins.
 
 ```jsonc
+// ~/.config/tinycode/tinycode.jsonc
 {
   "model": "ollama/qwen3.5:9b",
   "small_model": "ollama/qwen3.5:1.7b",
@@ -286,7 +304,9 @@ The runtime is Go only. The `packages/` tree is legacy TypeScript retained for `
 
 ## Documentation
 
-- **Spec index (start here):** [docs/spec/README.md](docs/spec/README.md)
+- **Install:** [docs/install.md](docs/install.md)
+- **Getting started:** [docs/getting-started.md](docs/getting-started.md)
+- **Spec index:** [docs/spec/README.md](docs/spec/README.md)
 - **Architecture:** [docs/architecture.md](docs/architecture.md)
 - **Build & embed web UI:** [docs/building.md](docs/building.md)
 - **TypeScript features not in Go:** [docs/spec/16-not-implemented.md](docs/spec/16-not-implemented.md)

cmd/tinycode/commands.go

@@ -443,7 +443,8 @@ func runInit() {
 		_ = json.Unmarshal(data, &result)
 	}
 
-	fmt.Println("tinycode init")
+	fmt.Println("tinycode init — Red Hat plugin/role setup")
+	fmt.Println("(Not required for first run. For models: /connect in the TUI, OPENROUTER_API_KEY, or Ollama.)")
 	fmt.Println()
 
 	// --- Step 1: Model selection ---

cmd/tinycode/doctor.go

@@ -18,7 +18,7 @@ import (
 const (
 	checkPass = "\033[32m✓\033[0m" // green check
 	checkFail = "\033[31m✗\033[0m" // red X
-	checkWarn = "\033[33m!\033[0m"      // yellow !
+	checkWarn = "\033[33m!\033[0m" // yellow !
 )
 
 func runDoctor() {
@@ -160,21 +160,25 @@ func checkProviders(cfg *config.Info, failed *bool) {
 		probes = append(probes, providerProbe{name: "vllm", url: v})
 	}
 
+	anyLocal := false
 	for _, p := range probes {
 		if probeHTTP(p.url) {
 			fmt.Printf("%s Provider: %s -- connected (%s)\n", checkPass, p.name, p.url)
-		} else {
-			fmt.Printf("%s Provider: %s -- connection refused (%s)\n", checkFail, p.name, p.url)
-			*failed = true
+			anyLocal = true
+			continue
 		}
+		// Local refusal is a warning — fail only if no usable provider path remains.
+		fmt.Printf("%s Provider: %s -- connection refused (%s)\n", checkWarn, p.name, p.url)
 	}
 
-	// OpenRouter: check API key
+	hasCloudKey := false
 	if apiKey := os.Getenv("OPENROUTER_API_KEY"); apiKey != "" {
 		fmt.Printf("%s Provider: openrouter -- API key set\n", checkPass)
+		hasCloudKey = true
 	}
 
 	// Config-defined providers
+	anyConfig := false
 	knownProbe := map[string]bool{"ollama": true, "vllm": true, "lm-studio": true, "openrouter": true}
 	for id, pc := range cfg.Provider {
 		if knownProbe[id] {
@@ -184,15 +188,35 @@ func checkProviders(cfg *config.Info, failed *bool) {
 			if baseURL, ok := pc.Options["baseURL"].(string); ok && baseURL != "" {
 				if probeHTTP(baseURL) {
 					fmt.Printf("%s Provider: %s -- connected (%s)\n", checkPass, id, baseURL)
+					anyConfig = true
 				} else {
-					fmt.Printf("%s Provider: %s -- connection refused (%s)\n", checkFail, id, baseURL)
-					*failed = true
+					fmt.Printf("%s Provider: %s -- connection refused (%s)\n", checkWarn, id, baseURL)
 				}
 				continue
 			}
 		}
 		fmt.Printf("%s Provider: %s -- configured (no URL to probe)\n", checkWarn, id)
 	}
+
+	if providerPathUsable(anyLocal, hasCloudKey, anyConfig) {
+		return
+	}
+
+	fmt.Printf("%s Provider: no usable provider path (no local provider connected and no cloud API key)\n", checkWarn)
+	printProviderNextSteps()
+	*failed = true
+}
+
+// providerPathUsable reports whether doctor found at least one way to reach a model.
+func providerPathUsable(anyLocalConnected, hasCloudAPIKey, anyConfigConnected bool) bool {
+	return anyLocalConnected || hasCloudAPIKey || anyConfigConnected
+}
+
+func printProviderNextSteps() {
+	fmt.Println("    next steps:")
+	fmt.Println("    - start Ollama: ollama serve")
+	fmt.Println("    - or set OPENROUTER_API_KEY for cloud models")
+	fmt.Println("    - then run: tinycode models")
 }
 
 func ollamaURL() string {

cmd/tinycode/doctor_test.go

@@ -0,0 +1,53 @@
+package main
+
+import "testing"
+
+func TestProviderPathUsable_Scenario(t *testing.T) {
+	tests := []struct {
+		name               string
+		anyLocalConnected  bool
+		hasCloudAPIKey     bool
+		anyConfigConnected bool
+		want               bool
+	}{
+		{
+			name:              "cloud only with openrouter key",
+			hasCloudAPIKey:    true,
+			anyLocalConnected: false,
+			want:              true,
+		},
+		{
+			name:              "local only",
+			anyLocalConnected: true,
+			want:              true,
+		},
+		{
+			name:               "config provider only",
+			anyConfigConnected: true,
+			want:               true,
+		},
+		{
+			name:              "no local and no cloud key",
+			anyLocalConnected: false,
+			hasCloudAPIKey:    false,
+			want:              false,
+		},
+		{
+			name:               "all paths available",
+			anyLocalConnected:  true,
+			hasCloudAPIKey:     true,
+			anyConfigConnected: true,
+			want:               true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := providerPathUsable(tt.anyLocalConnected, tt.hasCloudAPIKey, tt.anyConfigConnected)
+			if got != tt.want {
+				t.Errorf("providerPathUsable(%v, %v, %v) = %v, want %v",
+					tt.anyLocalConnected, tt.hasCloudAPIKey, tt.anyConfigConnected, got, tt.want)
+			}
+		})
+	}
+}

cmd/tinycode/main.go

@@ -118,7 +118,7 @@ func printUsage() {
 	fmt.Println("  status     Show server health and status")
 	fmt.Println("  export     Export session messages as JSON")
 	fmt.Println("  plugin     Manage plugins (list, install, uninstall)")
-	fmt.Println("  init       Interactive plugin setup by role")
+	fmt.Println("  init       Red Hat plugin/role setup (optional; not first-run)")
 	fmt.Println("  agent      List available agents")
 	fmt.Println("  doctor     Run diagnostics and check system health")
 	fmt.Println("  debug      Debug info (config, paths)")

docs/install.md

@@ -1,16 +1,50 @@
 # Installation
 
-tinycode is a single static binary with no runtime dependencies. Works with any OpenAI-compatible LLM endpoint --- local or cloud. Build from source, then run.
+tinycode is a single static binary with no runtime dependencies. Works with any OpenAI-compatible LLM endpoint --- local or cloud.
 
-## Prerequisites
+## Binary install (recommended)
 
-- **Go 1.27+** -- [download](https://go.dev/dl/)
+### One-liner (`install.sh`)
+
+Downloads the latest GitHub release for your platform and installs to `~/.local/bin`:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/bobbyjohnstx/tinycode/main/install.sh | sh
+```
+
+Supported platforms: macOS and Linux (`amd64` / `arm64`). Override defaults with environment variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `TINYCODE_INSTALL_DIR` | `$HOME/.local/bin` | Install destination |
+| `VERSION` | latest release | Pin a release tag (for example `v2.1.3`) |
+| `TINYCODE_REPO` | `bobbyjohnstx/tinycode` | GitHub `owner/repo` |
+| `TINYCODE_BASE_URL` | `https://github.com` | Release download host |
+| `TINYCODE_API_URL` | `https://api.github.com` | Releases API host |
+
+If `~/.local/bin` is not on your `PATH`, the script prints shell-specific instructions.
+
+### Homebrew
+
+```bash
+brew install bobbyjohnstx/tap/tinycode
+```
+
+### Manual download
+
+Download a platform archive from [GitHub Releases](https://github.com/bobbyjohnstx/tinycode/releases) (for example `tinycode-darwin-arm64.tar.gz`), extract the `tinycode` binary, and place it on your `PATH`.
+
+## Build from source
+
+### Prerequisites
+
+- **Go 1.27.1+** -- [download](https://go.dev/dl/) (matches `go.mod`)
 - **make** -- included on macOS and most Linux distributions
 - **git** -- to clone the repo
 
 No C toolchain needed. SQLite is pure Go (`modernc.org/sqlite`), so CGO is not required.
 
-## macOS
+### macOS
 
 ```bash
 # Clone and build
@@ -31,13 +65,10 @@ Go can be installed via Homebrew:
 brew install go
 ```
 
-## Linux
+### Linux
 
 ```bash
-# Install Go (Debian/Ubuntu)
-sudo apt install golang
-
-# Or download from https://go.dev/dl/ for the latest version
+# Install Go 1.27.1+ from https://go.dev/dl/ (distro packages may be older)
 
 # Clone and build
 git clone https://github.com/bobbyjohnstx/tinycode.git
@@ -64,15 +95,33 @@ Without a clipboard utility, clipboard commands will fail with an error message.
 
 For `/paste-image` with image support, `xclip` must be compiled with image format support (the default package includes it). On Wayland, `wl-paste` handles images natively.
 
-## Windows (WSL)
+### Windows (WSL)
 
 Native Windows is not supported -- bubbletea requires a Unix terminal.
 
 Use WSL2 instead:
 
 1. Install WSL2: `wsl --install` (from PowerShell as admin)
 2. Open your WSL distribution (Ubuntu is the default)
-3. Follow the Linux instructions above
+3. Follow the Linux instructions above (binary install or build from source)
+
+## Configuration
+
+Config files are loaded with a 3-name fallback in each directory:
+
+1. `tinycode.jsonc`
+2. `tinycode.json`
+3. `config.json`
+
+Global config: `~/.config/tinycode/` (first matching name wins). Project config: `.tinycode/` walking up from the working directory (innermost wins). JSONC comments are supported.
+
+```jsonc
+// ~/.config/tinycode/tinycode.jsonc
+{
+  "model": "ollama/qwen3.5:9b",
+  "default_agent": "build"
+}
+```
 
 ## Cross-compilation
 
@@ -94,7 +143,7 @@ This produces binaries in `dist/` for:
 
 | Requirement | When | Notes |
 |-------------|------|-------|
-| Go 1.22+ | Build only | Not needed at runtime |
+| Go 1.27.1+ | Build only | Not needed at runtime; matches `go.mod` |
 | make | Build only | For the Makefile targets |
 | xclip / wl-clipboard | Runtime (optional) | Linux clipboard support |
 
@@ -124,6 +173,12 @@ tinycode models
 
 ## Updating
 
+### Binary install
+
+Re-run `install.sh`, or `brew upgrade tinycode` if you installed via Homebrew.
+
+### From source
+
 Pull the latest source and rebuild:
 
 ```bash