chore: document development modes in README.md

Author: jakehwll

CONTRIBUTING.md

@@ -10,7 +10,7 @@ Thanks for your interest in contributing. This is a small Go project; keeping ch
 
    ```bash
    go build -o intertui .
-   ./intertui init --server HOST --user YOU --pass SECRET   # or --offline
+   ./intertui init --server HOST --user YOU --pass SECRET
    ./intertui
    ```
 
@@ -33,28 +33,76 @@ Check open issues before starting large changes. For substantial features, open
 
 ## Development notes
 
-### Package layout
+### Project layout
+
+```
+intertui/
+  main.go
+  cmd/
+    dev/           # offline mock server + TUI (not installed)
+    probe/         # low-level protocol debugger
+  internal/
+    constants/     # DEFAULT_PORT
+    config/        # CLI flags and config file
+    intercept/     # protocol client and mock server
+    ui/            # Bubble Tea TUI
+```
 
 | Package | Role |
 |---------|------|
 | `internal/constants` | Default server host and port |
 | `internal/config` | CLI flags and environment variables |
 | `internal/intercept` | Network client, protocol parsing, mock server |
 | `internal/ui` | Bubble Tea model, view, input handling |
-| `cmd/probe` | Manual protocol debugging (not required for normal use) |
+| `cmd/dev` | Offline development entrypoint |
+| `cmd/probe` | Manual protocol debugging |
 
 ### Defaults and configuration
 
 Put shared default values in `internal/constants/constants.go` (`DEFAULT_PORT`, etc.). Do not duplicate magic strings in config or client code.
 
+Connection settings (`server`, `port`, transport mode) live in `~/.intertui/config.yaml` and are written by `intertui init`. The main binary only exposes `--user` and `--pass` on the command line; everything else is config-file driven.
+
 ### Offline development
 
-Use `--offline` or the mock server in `internal/intercept/mock.go` when you do not have access to a live game server:
+Run the dev entrypoint when you do not have access to a live game server:
 
 ```bash
-go run . --offline
+go run ./cmd/dev
 ```
 
+This starts the built-in mock WebSocket server in `internal/intercept/mock.go` and launches the TUI against it. It is not part of the installed `intertui` binary.
+
+### Alternate transports and servers
+
+The live game server uses raw TCP on port `13373` by default. WebSocket mode and custom hosts are for development and testing.
+
+Set transport options in config via `intertui init`:
+
+```bash
+# Custom host or port
+./intertui init --server example.com --port 13373 --user YOU --pass SECRET --force
+
+# WebSocket (alternate API; not what the live server uses by default)
+./intertui init --ws --user YOU --pass SECRET --server HOST --force
+
+# Full WebSocket URL
+./intertui init --url wss://example.com/ws --user YOU --pass SECRET --force
+```
+
+`init` also accepts `--tls` (with WebSocket) and `--token` (API token login for WebSocket mode).
+
+### Protocol
+
+JSON request/response protocol, informed by [intercept.py](https://github.com/Martmists-GH/intercept.py):
+
+- **TCP (default):** one JSON object per line on port `13373` — `auth` (login) → `connect` (token)
+- **WebSocket:** JSON frames — `auth` → `systems` → `connect` (system)
+
+Inbound events include `chat`, `broadcast`, `command`, `connect`, and others. Commands are sent as `{"request":"command","cmd":"..."}`.
+
+WebSocket URLs are derived as `ws://host:port/ws` unless `url` is set in config.
+
 ### Live server tests
 
 Live tests are behind the `live` build tag and require real credentials:

README.md

@@ -8,11 +8,11 @@ This project is unofficial and not affiliated with the game or its authors.
 
 ## Features
 
-- Fullscreen UI in the style of Claude Code: log fills the screen with input and status pinned at the bottom; mouse wheel scrolls, and click-drag selects text in-app, copying it to your clipboard on release
+- Fullscreen terminal UI with a scrollable log, input line, and status bar
+- Mouse: wheel scroll, click to copy a word, drag to select text (copied on release)
 - ANSI colors for in-game `¬` color codes
-- TCP transport (default) with optional WebSocket mode
-- Username/password login (TCP) or extended WebSocket login flows
-- Offline mode with a built-in mock server for development
+- Tab completion for commands, subcommands, and filesystem paths
+- Session logging to `~/.intertui/logs/`
 
 ## Requirements
 
@@ -42,17 +42,8 @@ intertui init --server HOST --user YOU --pass SECRET
 # Connect using config file
 intertui
 
-# Or pass flags (override config)
-intertui --server HOST --user YOU --pass SECRET
-
-# Offline mock server (no network)
-./intertui --offline
-
-# WebSocket (alternate API; not what the live server uses by default)
-./intertui --ws --user YOU --pass SECRET
-
-# Custom host
-./intertui --server example.com --port 13373 --user YOU --pass SECRET
+# Override credentials for this session
+intertui --user YOU --pass SECRET
 ```
 
 ### Flags
@@ -61,26 +52,13 @@ intertui --server HOST --user YOU --pass SECRET
 |------|-------------|
 | `--user` | Intercept username |
 | `--pass` | Intercept password |
-| `--token` | API token (WebSocket mode only) |
-| `--server` | Game server host |
-| `--port` | Server port (default: `13373`) |
-| `--ws` | Use WebSocket instead of TCP |
-| `--tls` | Use `wss://` instead of `ws://` (with `--ws`) |
-| `--url` | Full WebSocket URL (overrides `--server` / `--port`) |
-| `--offline` | Built-in mock WebSocket server |
 
 ### Environment variables
 
 | Variable | Flag |
 |----------|------|
 | `INTERCEPT_USER` | `--user` |
 | `INTERCEPT_PASS` | `--pass` |
-| `INTERCEPT_TOKEN` | `--token` |
-| `INTERCEPT_SERVER` | `--server` |
-| `INTERCEPT_PORT` | `--port` |
-| `INTERCEPT_WS` | `--ws` (`1` or `true`) |
-| `INTERCEPT_TLS` | `--tls` (`1` or `true`) |
-| `INTERCEPT_URL` | `--url` |
 
 ### Keyboard shortcuts
 
@@ -103,44 +81,22 @@ intertui --server HOST --user YOU --pass SECRET
 
 ### Tab completion
 
-Press `Tab` to complete command names, subcommands, and filesystem paths. The first completion may query the server silently in the background; press `Tab` again if nothing happens immediately. Ambiguous matches are listed in the log.
+Press `Tab` to complete command names, subcommands, and filesystem paths. The first completion may query the server in the background; press `Tab` again if nothing appears right away. Ambiguous matches are listed in the log.
 
-The command list learned from `cmds` is cached for the rest of the session. Directory listings used for path completion are cleared when you run commands that change the filesystem (`mkdir`, `rm`, and similar) or when you reconnect.
+Command names from `cmds` are cached for the session. Directory listings are cleared when you run commands that change the filesystem (`mkdir`, `rm`, and similar) or when you reconnect.
 
-**Reconnecting:** Press `r` after a disconnect to reconnect. File-completion caches are reset, but the cached command vocabulary is kept on purpose — it reflects your account’s command set, not remote host state. If you reconnect to a **different** server or account (for example by changing flags and pressing `r`), tab completion may show stale commands until you restart `intertui`.
+If you reconnect to a different server or account, restart `intertui` to refresh the command cache.
 
 ## Configuration
 
-Default settings live in `~/.intertui/config.yaml` (create with `intertui init`). Flags and environment variables override the file. Default port is in [`internal/constants/constants.go`](internal/constants/constants.go) (`DEFAULT_PORT`). WebSocket URLs are derived as `ws://host:port/ws` unless you pass `--url`.
+Default settings live in `~/.intertui/config.yaml` (create with `intertui init`). `--user` and `--pass` override the file for a single session.
 
 Session logs are written to `~/.intertui/logs/latest.log`. On each launch, the previous `latest.log` is renamed to a timestamped file in the same directory (for example `2025-06-10T12-34-56.log`).
 
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## Protocol
-
-JSON request/response protocol, informed by [intercept.py](https://github.com/Martmists-GH/intercept.py):
-
-- **TCP (default):** one JSON object per line on port `13373` — `auth` (login) → `connect` (token)
-- **WebSocket:** JSON frames — `auth` → `systems` → `connect` (system)
-
-Inbound events include `chat`, `broadcast`, `command`, `connect`, and others. Commands are sent as `{"request":"command","cmd":"..."}`.
-
-## Project layout
-
-```
-intertui/
-  main.go
-  internal/
-    constants/     # DEFAULT_PORT
-    config/        # flags and env
-    intercept/     # protocol client
-    ui/            # Bubble Tea TUI
-  cmd/probe/       # optional protocol debugger
-```
-
 ## License
 
 GNU General Public License v3.0 or later. See [LICENSE](LICENSE).

cmd/dev/main.go

@@ -0,0 +1,49 @@
+// Dev entrypoint: built-in mock server for offline UI and protocol work.
+// Not installed with `go install`; run with `go run ./cmd/dev`.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	tea "charm.land/bubbletea/v2"
+
+	"intertui/internal/config"
+	"intertui/internal/intercept"
+	filelog "intertui/internal/log"
+	"intertui/internal/ui"
+)
+
+func main() {
+	srv, url := intercept.StartMockServer()
+	defer srv.Close()
+
+	cfg := config.Config{
+		URL:  url,
+		WS:   true,
+		User: "offline",
+		Pass: "offline",
+	}
+
+	if err := run(cfg); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func run(cfg config.Config) error {
+	if err := filelog.Open(); err != nil {
+		fmt.Fprintf(os.Stderr, "warning: file logging disabled: %v\n", err)
+	} else {
+		defer filelog.Close()
+	}
+
+	logPath, _ := filelog.Path()
+	filelog.Info("start target=%s ws=%v user=%s log=%s", cfg.DialDescription(), cfg.WS, cfg.User, logPath)
+
+	p := tea.NewProgram(ui.New(cfg), tea.WithFPS(30))
+	if _, err := p.Run(); err != nil {
+		return err
+	}
+	return nil
+}

internal/config/config.go

@@ -14,10 +14,9 @@ import (
 
 // Config holds runtime options for intertui.
 type Config struct {
-	User    string
-	Pass    string
-	Token   string
-	Offline bool
+	User  string
+	Pass  string
+	Token string
 
 	Server string
 	Port   int
@@ -57,59 +56,41 @@ func RootCmd(run func(Config) error) *serpent.Command {
 			Description: "Intercept password.",
 		},
 		{
-			Name:        "token",
-			Flag:        "token",
-			Env:         "INTERCEPT_TOKEN",
-			YAML:        "token",
-			Value:       serpent.StringOf(&cfg.Token),
-			Description: "Intercept API token (WebSocket mode only).",
+			Name:   "server",
+			YAML:   "server",
+			Hidden: true,
+			Value:  serpent.StringOf(&cfg.Server),
 		},
 		{
-			Name:        "server",
-			Flag:        "server",
-			Env:         "INTERCEPT_SERVER",
-			YAML:        "server",
-			Value:       serpent.StringOf(&cfg.Server),
-			Description: "Game server host or IP.",
+			Name:    "port",
+			YAML:    "port",
+			Hidden:  true,
+			Default: "0",
+			Value:   serpent.Int64Of(&port),
 		},
 		{
-			Name:        "port",
-			Flag:        "port",
-			Env:         "INTERCEPT_PORT",
-			YAML:        "port",
-			Default:     "0",
-			Value:       serpent.Int64Of(&port),
-			Description: fmt.Sprintf("Server port (default %d).", constants.DEFAULT_PORT),
+			Name:   "token",
+			YAML:   "token",
+			Hidden: true,
+			Value:  serpent.StringOf(&cfg.Token),
 		},
 		{
-			Name:        "ws",
-			Flag:        "ws",
-			Env:         "INTERCEPT_WS",
-			YAML:        "ws",
-			Value:       serpent.BoolOf(&cfg.WS),
-			Description: fmt.Sprintf("Use WebSocket transport (default: raw TCP on port %d).", constants.DEFAULT_PORT),
+			Name:   "ws",
+			YAML:   "ws",
+			Hidden: true,
+			Value:  serpent.BoolOf(&cfg.WS),
 		},
 		{
-			Name:        "tls",
-			Flag:        "tls",
-			Env:         "INTERCEPT_TLS",
-			YAML:        "tls",
-			Value:       serpent.BoolOf(&cfg.TLS),
-			Description: "Use wss:// instead of ws:// (with --ws).",
+			Name:   "tls",
+			YAML:   "tls",
+			Hidden: true,
+			Value:  serpent.BoolOf(&cfg.TLS),
 		},
 		{
-			Name:        "url",
-			Flag:        "url",
-			Env:         "INTERCEPT_URL",
-			YAML:        "url",
-			Value:       serpent.StringOf(&cfg.URL),
-			Description: "Full endpoint URL (overrides --server; ws:// or wss:// enables WebSocket).",
-		},
-		{
-			Name:        "offline",
-			Flag:        "offline",
-			Value:       serpent.BoolOf(&cfg.Offline),
-			Description: "Use built-in mock server.",
+			Name:   "url",
+			YAML:   "url",
+			Hidden: true,
+			Value:  serpent.StringOf(&cfg.URL),
 		},
 	}
 
@@ -172,9 +153,6 @@ func (c Config) ResolveURL() string {
 
 // DialDescription returns a human-readable target for status output.
 func (c Config) DialDescription() string {
-	if c.Offline {
-		return "offline mock server"
-	}
 	if c.WS || strings.HasPrefix(c.URL, "ws") {
 		return c.ResolveURL()
 	}

internal/ui/model.go

@@ -82,17 +82,12 @@ func New(cfg config.Config) Model {
 	styles.Cursor.Blink = false
 	ti.SetStyles(styles)
 
-	m := Model{
+	return Model{
 		cfg:        cfg,
 		input:      ti,
 		state:      stateConnecting,
 		completion: newCompletionState(),
 	}
-	if cfg.Offline && !cfg.HasCreds() {
-		m.cfg.User = "offline"
-		m.cfg.Pass = "offline"
-	}
-	return m
 }
 
 func (m Model) Init() tea.Cmd {