lsd-pi 1.1.6 → 1.1.9

package/README.md

@@ -1,33 +1,25 @@
-<div align="center">
-
 # LSD
 
-**Lucent Software Developer** — a standalone coding-agent CLI built on the Pi SDK.
-
-[![npm version](https://img.shields.io/npm/v/lsd-pi?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/lsd-pi)
-[![npm downloads](https://img.shields.io/npm/dm/lsd-pi?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/lsd-pi)
-[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
-
-LSD is a local-first agent shell for software work: coding, shell execution, browser automation, web research, MCP integrations, worktrees, sessions, and autonomous task execution.
+**Looks Sort of Done** — a standalone coding-agent CLI built on the Pi SDK. Use all your AI providers and all your loved features from Claude Code, Codex, and Gemini in one place.
 
-It is a **fork of GSD 2**, but positioned differently:
-
-- the heavy **GSD workflow/orchestration layer** was stripped away
-- LSD focuses on the **agent shell, tools, sessions, worktrees, and execution surface**
-- LSD keeps useful compatibility where practical, but it is **not presented as GSD**
-- LSD adds and emphasizes **permission modes**, where **auto mode** is treated as a special permission/execution style rather than the center of the whole product
+![LSD Screenshot](./lsd.png)
 
 ```bash
 npm install -g lsd-pi@latest
 ```
 
-</div>
-
 ---
 
 ## What LSD is
 
-LSD is the product and CLI.
+LSD is a general-purpose coding agent CLI. It combines:
+
+- **Interactive TUI** inspired by Gemini CLI — including an embedded interactive terminal inside the LSD CLI that both you and the agent can use, so the agent is not blocked by commands or tools that require terminal interaction
+- **Memory system and permission modes** inspired by Claude Code
+- **Sandbox isolation** inspired by Codex
+- **Auto mode** — a classifier-based autonomous execution mode
+- **Remote questions** — relay agent prompts to Telegram, Discord, or Slack so you can respond from your phone
+- **Background subagents, skills, worktrees, sessions, usage tracking, and more**
 
 - **Package:** `lsd-pi`
 - **Binary:** `lsd`
@@ -35,53 +27,9 @@ LSD is the product and CLI.
 - **Project config dir:** `.lsd/`
 - **User config dir:** `~/.lsd/`
 
-It is built on the Pi SDK and ships with a rich tool/runtime layer for:
-
-- code editing and file operations
-- shell execution (`bash`, `async_bash`, `bg_shell`)
-- browser automation and verification
-- web search and page extraction
-- MCP integrations
-- sessions and resumability
-- worktree-based parallel work
-- interactive and headless execution
-- configurable permission modes
-
 ### Fork lineage
 
-LSD is a fork of **GSD 2**.
-
-What changed:
-
-- the old GSD-specific project workflow layer is no longer the identity of the tool
-- LSD is centered on being a **general-purpose coding agent CLI**
-- the agent shell, tools, TUI, browser tools, sessions, worktrees, and integrations remain the core
-- auto execution still exists, but it is treated as **one operating mode among several**
-
-### Permission modes
-
-LSD supports different permission modes for how aggressively it can act in your environment.
-
-A key point of the LSD model is:
-
-- **auto** is a special permission mode / execution style
-- it is not the whole product
-- you can use LSD interactively, cautiously, or autonomously depending on the task
-
-## Important note on naming
-
-LSD has evolved from earlier GSD-branded work and is a fork of GSD 2. Some internal commands, docs, or compatibility surfaces may still use names like `/gsd`.
-
-**For users, the tool is LSD.**
-
-That means:
-
-- install with `npm install -g lsd-pi`
-- launch with `lsd`
-- use `.lsd/` for project state
-- use `~/.lsd/` for global LSD state
-
-Inside the interactive session, some slash commands still use the legacy `/gsd ...` namespace for compatibility, but the LSD direction is broader than the old workflow-centric GSD model.
+LSD is a fork of **GSD 2**. The GSD-specific project workflow layer was stripped out. LSD is centered on being a general-purpose coding agent CLI — the agent shell, tools, TUI, browser tools, sessions, worktrees, and integrations remain core.
 
 ---
 
@@ -89,12 +37,10 @@ Inside the interactive session, some slash commands still use the legacy `/gsd .
 
 ### Requirements
 
-- Node.js **>= 22**
+- Node.js **>= 22** (Node 24 LTS recommended)
 - Git
 - macOS, Linux, or Windows
 
-Node 24 LTS is recommended.
-
 ### Global install
 
 ```bash
@@ -111,354 +57,614 @@ Then ensure `$(npm prefix -g)/bin` is on your `PATH`.
 
 ### Local development build
 
-From this repo:
-
 ```bash
 npm install
 npm run build
 npm link
 ```
 
-That makes the local build available as `lsd` on your machine.
-
 ---
 
 ## Quick start
 
-### Start an interactive session
-
 ```bash
-lsd
+lsd                          # start interactive session
+lsd -c                       # resume last session
+lsd --print "summarize repo" # one-shot mode
+lsd -w                       # start in an isolated git worktree
+lsd config                   # re-run setup wizard
 ```
 
-### Resume the last session for the current directory
+---
 
-```bash
-lsd --continue
-# or
-lsd -c
-```
+## First launch
 
-### One-shot prompt mode
+On first run, LSD opens an interactive setup wizard for:
 
-```bash
-lsd --print "summarize this repository"
-```
+- LLM provider login or API key (Anthropic, OpenAI, Google, GitHub Copilot, and others)
+- Web search provider (Brave, Tavily, built-in)
+- Remote questions channel (Telegram, Discord, Slack)
+- Tool API keys (Context7, Jina, Groq for voice)
 
+Re-run setup any time:
 
 ```bash
+lsd config
 ```
 
-### Start in a git worktree
+---
+
+## Permission modes
+
+LSD supports different permission modes controlling how aggressively it acts in your environment:
+
+| Mode | Behaviour |
+|------|-----------|
+| **interactive** (default) | Asks for approval before write/edit/shell operations |
+| **auto** | Uses a classifier model to approve low-risk tool calls automatically; still asks for high-risk ones |
+| **bypass** | Runs without asking (used internally by headless/subagent workers) |
+
+Switch modes with `/permission` inside a session or pass flags to headless commands.
+
+---
+
+## Sandbox
+
+LSD supports filesystem sandboxing:
 
 ```bash
-lsd -w
-lsd -w my-feature
+lsd --sandbox workspace-write   # restrict writes to the current directory tree
+lsd --sandbox none               # no sandbox (default)
+lsd --no-sandbox                 # explicit no-sandbox
 ```
 
+`workspace-write` prevents the agent from writing outside the project directory.
+
 ---
 
-## First launch
+## Context files (lsd.md / CLAUDE.md / AGENTS.md)
 
-On first run, LSD opens a setup flow for:
+LSD automatically loads project instructions from these files (in order of preference):
 
-- LLM provider login or API key setup
-- optional web search provider setup
-- optional tool/API credentials
-- optional remote-question integrations
+- `lsd.md` — LSD-native project instructions
+- `CLAUDE.md` — Claude Code-compatible instructions
+- `AGENTS.md` — Codex-compatible instructions
 
-LSD supports multiple providers including Anthropic, OpenAI, Google, GitHub Copilot, and others depending on configuration and installed extensions.
+Place one of these files at the project root (or in `.lsd/`) to give the agent persistent per-project context, coding conventions, and rules.
 
-Re-run setup any time with:
+The `--bare` flag suppresses all of these (useful for CI):
 
 ```bash
-lsd config
+lsd headless --bare auto
 ```
 
 ---
 
+## Interactive TUI
+LSD comes with an embedded interactive terminal inspired by the gemini cli
+- user interaction with that terminal directly from the TUI
+- agent interaction with terminal programs and commands that require prompts, input, or other interactive flows without getting blocked
+
+![Interactive TUI Terminal](./docs/images/interactive-tui-terminal.png)
+
+### TUI slash commands
+
+Use `/help` inside LSD to see the live command list for your current session, including built-ins, extension commands, prompt templates, and skill commands.
+
+| Command | Description |
+|---------|-------------|
+| `/help [command]` | Show available commands or details for one command |
+| `/model` | Switch model |
+| `/login` | Add or switch provider credentials |
+| `/settings` | Open settings panel |
+| `/hotkeys` | Show keyboard shortcut reference |
+| `/cache-timer` | Toggle the prompt-cache countdown in the footer |
+| `/thinking` | Toggle extended thinking |
+| `/voice` | Toggle voice input mode |
+| `/clear` | Clear the current conversation |
+| `/exit` | Exit LSD |
+
+### Memory commands
+
+| Command | Description |
+|---------|-------------|
+| `/memories` | Browse saved memories for this project |
+| `/remember <text>` | Save a memory immediately |
+| `/forget <topic>` | Remove a memory |
+| `/dream` | Run a memory consolidation pass manually |
+
+### Remote questions commands
+
+| Command | Description |
+|---------|-------------|
+| `/lsd remote` | Show remote questions menu |
+| `/lsd remote telegram` | Connect Telegram |
+| `/lsd remote discord` | Connect Discord |
+| `/lsd remote slack` | Connect Slack |
+| `/lsd remote status` | Show current connection status |
+| `/lsd remote disconnect` | Disconnect and remove saved token |
+
+### Background process commands
+
+| Command | Description |
+|---------|-------------|
+| `/bg <cmd>` | Start a background shell process |
+| `/jobs` | List running async jobs |
+
+### Codex account commands
+
+| Command | Description |
+|---------|-------------|
+| `/codex add` | Add a ChatGPT/Codex OAuth account |
+| `/codex list` | List configured accounts |
+| `/codex status` | Show rotation state and token expiry |
+| `/codex remove <n>` | Remove an account |
+| `/codex enable <n>` | Re-enable a disabled account |
+| `/codex disable <n>` | Temporarily disable an account |
+| `/codex import` | Import from `~/.codex/auth.json` |
+| `/codex import-cockpit` | Import from Cockpit Tools |
+| `/codex sync` | Force refresh all tokens |
+
+### Other commands
+
+| Command | Description |
+|---------|-------------|
+| `/usage [today\|7d\|YYYY-MM-DD]` | Show token and cost usage |
+| `/subagents` | List background subagent jobs |
+| `/subagent` | Manage a specific subagent |
+| `/configs` | Discover config files from other AI tools (Claude Code, Cursor, Copilot, etc.) |
+| `/plan` | Create and run a multi-step plan |
+| `/audit` | Run a codebase audit |
+| `/search-provider` | Switch web search provider |
+
+### Compatibility note
+
+LSD is LSD-first. Some legacy `/gsd` aliases may still exist for compatibility, but the recommended commands and docs use `/lsd` and the standard slash commands shown above.
+
+### TUI settings
+
+The settings panel (`/settings`) includes toggles for:
+
+- **Codex rotate** — enable multi-account OAuth rotation
+- **Cache timer** — show a prompt-cache countdown in the footer
+- **Pin last prompt** — keep your most recent non-command prompt visible above the editor
+- **RTK shell compression** — compress repetitive shell output to save tokens
+- **Main accent** — change the accent color across the UI and thinking-level indicators
+
+---
+
 ## Persistent memory
 
-LSD includes a bundled **persistent memory** extension.
+LSD includes a built-in **persistent memory** extension.
 
-What it does:
+- Stores durable facts under `~/.lsd/projects/<project>/memory/`
+- Injects `MEMORY.md` into future sessions for the same project
+- Runs an **auto-extract** pass on session shutdown (detached worker, uses `budgetSubagentModel` if configured)
 
-- stores durable user/project memories under `~/.lsd/projects/<project>/memory/`
-- injects `MEMORY.md` into future turns for the same project
-- supports explicit memory commands:
-	- `/memories`
-	- `/remember <text>`
-	- `/forget <topic>`
-- runs an **auto-extract** pass on session shutdown to save durable facts from the transcript
+Debug files written to the project memory directory:
 
-Auto-extract notes:
+- `.last-auto-extract.txt` — latest status (`saved_memory`, `nothing_worth_saving`, etc.)
+- `.last-auto-extract.log` — extractor stdout/stderr
 
-- it runs in a detached `lsd headless --bare ...` worker after you exit a session
-- if `budgetSubagentModel` is configured in settings, auto-extract uses that model
-- otherwise it falls back to the normal default model resolution
-- it may decide that a transcript contains **nothing worth saving**
+---
 
-For debugging auto-extract, LSD writes two files in the project memory directory:
+## Codex multi-account rotation
 
-- `.last-auto-extract.txt` — latest status/result summary
-- `.last-auto-extract.log` — extractor stdout/stderr
+LSD bundles a Codex OAuth rotation extension for managing multiple ChatGPT/Codex accounts.
 
-Typical results in `.last-auto-extract.txt` include:
+- Round-robin credential selection across accounts
+- Background token refresh every 10 minutes
+- Automatic quota/rate-limit detection and per-account backoff
+- Import from `~/.codex/auth.json` or Cockpit Tools
 
-- `status: finished`
-- `result: saved_memory`
-- `result: nothing_worth_saving`
-- `completionReason: child_exit` or `completionReason: session_end_detected`
+See `/codex` commands above. Stored in `~/.lsd/agent/codex-accounts.json`.
 
 ---
 
-## Core ways to use LSD
+## Voice input
 
-## 1. Interactive TUI
+LSD supports voice input via microphone:
 
-The default `lsd` experience is an interactive terminal UI with:
+- **macOS** — uses a compiled Swift speech recognizer (built automatically on first use via `swiftc`)
+- **Linux** — uses a Python speech recognizer (requires `GROQ_API_KEY` and `python3` with `sounddevice`)
 
-- message history
-- tool execution rendering
-- slash commands
-- model switching
-- sessions
-- background process management
-- settings
+Toggle with `/voice` or the keyboard shortcut `Ctrl+Alt+V`.
 
-Useful built-in commands include:
+---
 
-- `/model`
-- `/login`
-- `/settings`
-- `/hotkeys`
-- `/cache-timer`
-- `/clear`
-- `/exit`
-- `/thinking`
-- `/voice`
+## Usage tracking
 
-A few quality-of-life touches in the TUI:
+Track token consumption and cost across sessions:
 
-- the footer can show a live cache timer for the current prompt-cache window
-- `/hotkeys` gives you a full shortcut reference on demand
-- `/settings` now includes toggles for Codex rotate, the cache timer, **Pin last prompt**, RTK shell-command compression, and a configurable **Main accent** preset
-- changing the main accent also updates accent-driven UI elements and the text input border across thinking levels
-- when **Pin last prompt** is enabled, LSD keeps your most recent non-command prompt visible above the editor as a lightweight reminder
+```bash
+/usage              # today, grouped by model
+/usage 7d           # last 7 days
+/usage 2024-03-01   # specific date
+/usage today --by project-model   # by project + model
+/usage --all-projects             # across all projects
+/usage --json                     # machine-readable output
+```
 
-Some workflow/automation commands still use the legacy namespace:
+---
 
-- `/gsd`
-- `/gsd auto`
-- `/gsd status`
-- `/gsd config`
-- `/gsd doctor`
-- `/gsd update`
+## Telegram integration
 
-## 2. Headless mode
+LSD can relay permission prompts and questions to a Telegram chat while running autonomously. Reply from your phone and LSD continues.
 
-Run LSD without the TUI for CI, scripts, or automation:
+### Step 1 — create a Telegram bot
 
-```bash
-lsd headless
-lsd headless next
-lsd headless status
-```
+1. Open Telegram and search for **@BotFather**
+2. Send `/newbot` and follow the prompts
+3. Copy the **bot token** (looks like `123456789:ABCdefGHI...`)
 
-Examples:
+### Step 2 — get your chat ID
 
-```bash
-lsd headless --timeout 60000 auto
-lsd headless --output-format json auto
-lsd headless --json status
-```
+**Easiest:** forward any message to **@userinfobot** — it replies with your chat ID.
+
+**Alternative:** open `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates` after sending your bot a message — look for `"chat":{"id":...}` in the response.
 
-## 3. Web UI
+Group chat IDs are negative numbers starting with `-100` (e.g. `-1001234567890`).
 
-Run LSD with a browser interface:
+### Step 3 — connect
 
 ```bash
+/lsd remote telegram
 ```
 
-This is useful for local dashboards, session monitoring, and browser-based interaction.
+LSD prompts for your bot token and chat ID, validates both, and sends a test message.
 
-## 4. Worktree workflow
+You can also connect during initial setup with `lsd config`.
 
-LSD supports isolated git worktrees for parallel streams of work:
+### Step 4 — verify
 
 ```bash
-lsd -w my-feature
-lsd worktree list
-lsd worktree merge my-feature
-lsd worktree clean
+/lsd remote status
 ```
 
----
+### Disconnect
 
-## Features
+```bash
+/lsd remote disconnect
+```
 
-## Coding + shell tools
+### PREFERENCES.md reference
 
-LSD includes file and shell tools such as:
+```yaml
+remote_questions:
+  channel: telegram
+  channel_id: "-1001234567890"
+  timeout_minutes: 5        # 1–30, how long LSD waits for a reply
+  poll_interval_seconds: 5  # 2–30, how often LSD polls
+```
 
-- `read`, `write`, `edit`
-- `bash`
-- `async_bash`
-- `bg_shell`
-- LSP-backed navigation and diagnostics (hover, definition, references, rename, code actions, formatting)
-- Language server auto-detection — run `/setup` to install missing servers for your project (TypeScript, Python, Go, Rust, and more)
+Stored in `~/.lsd/PREFERENCES.md`. Project-level overrides go in `.lsd/PREFERENCES.md`.
 
-## Browser automation
-
-Browser tools support:
+---
 
-- local app verification
-- screenshots
-- assertions
-- form filling
-- DOM inspection
-- interaction recording and debug bundles
+## Discord & Slack integration
 
-## Web research
+Same flow as Telegram — run `/lsd remote discord` or `/lsd remote slack`. Both support:
 
-LSD supports:
+- bot token validation
+- channel auto-discovery (Discord lists your servers and channels; Slack lists channels)
+- manual channel ID entry as fallback
+- test message on connect
 
-- Google-backed search (`google_search`)
-- Brave/Tavily-style web search flows
-- page extraction
-- combined search-and-read workflows
-- Context7 library docs lookup
+---
 
 ## MCP integrations
 
-LSD can discover and connect to MCP servers configured in the project:
+LSD discovers and connects to MCP servers configured in:
 
 - `.mcp.json`
 - `.lsd/mcp.json`
 
+Use `/configs` inside a session to scan for MCP servers from other AI tools (Claude Code, Cursor, Copilot, etc.) and import them.
+
+---
+
 ## Sessions
 
 LSD stores per-project sessions and can resume prior work.
 
-Browse sessions with:
+```bash
+lsd sessions     # browse and pick a session to resume
+lsd -c           # resume the most recent session automatically
+```
+
+---
+
+## Worktrees
+
+LSD supports isolated git worktrees for parallel streams of work:
 
 ```bash
-lsd sessions
+lsd -w                        # auto-named worktree
+lsd -w my-feature             # named worktree
+lsd worktree list             # list with status
+lsd worktree merge my-feature # squash-merge into main
+lsd worktree clean            # remove merged/empty worktrees
+lsd worktree remove NAME      # remove specific worktree
 ```
 
-## Extensions, themes, and skills
+Lifecycle:
+1. `lsd -w` — creates worktree, starts session inside it
+2. Work normally — all changes stay on the worktree branch
+3. Exit — dirty work is auto-committed
+4. `lsd -w` — resume where you left off
+5. `lsd worktree merge` — squash-merge into main when done
+
+---
+
+## Headless mode
+
+Run LSD without the TUI for CI, scripts, or automation:
 
-LSD supports:
+```bash
+lsd headless                                    # run auto mode
+lsd headless next                               # run one unit
+lsd headless status                             # show queue status
+lsd headless --json auto                        # JSONL event stream
+lsd headless --output-format json auto          # structured JSON result
+lsd headless --timeout 60000 auto              # with 1-minute timeout
+lsd headless --bare auto                        # skip lsd.md/CLAUDE.md/settings
+lsd headless --resume abc123 auto              # resume a prior session
+lsd headless --supervised auto                 # orchestrator mode
+lsd headless --answers answers.json auto       # pre-supply answers/secrets
+lsd headless new-milestone --context spec.md   # create milestone from file
+lsd headless new-milestone --context spec.md --auto  # create + execute
+```
 
-- extensions
-- themes
-- skills
-- prompt templates
-- package-like installs from supported sources
+Exit codes: `0` success, `1` error/timeout, `10` blocked, `11` cancelled.
 
 ---
 
-## Configuration paths
+## Browser automation
+
+LSD includes full browser automation via Playwright:
+
+- local app verification and screenshots
+- form filling and interaction
+- DOM inspection and accessibility tree
+- assertions and debug bundles
+- network request inspection
+- device emulation
+
+---
+
+## LSP code intelligence
+
+LSD includes a first-class `lsp` tool for semantic code navigation in typed codebases.
+
+Use it for:
+
+- go-to-definition
+- find references and implementations
+- hover/type info
+- workspace and file symbols
+- incoming/outgoing calls
+- diagnostics and quick fixes
+- formatting and safe rename operations
 
-### User-level
+### Why LSP is good
 
-LSD stores global state under:
+Unlike raw text search, LSP understands symbols, types, scopes, and project structure. That means the agent can:
+
+- jump to the right definition instead of matching the wrong string
+- find real references across the codebase
+- inspect function signatures and docs without reading huge files
+- catch type errors immediately after edits
+- apply safer refactors like rename and format
+
+In practice this makes the agent faster, more accurate, and less likely to break typed projects during navigation or refactors.
+
+### Typical LSP usage
 
 ```text
-~/.lsd/
+lsp definition      # jump to a symbol definition
+lsp references      # find where a symbol is used
+lsp hover           # inspect type/docs at a position
+lsp diagnostics     # check errors in a file or workspace
+lsp rename          # perform a semantic rename
+lsp format          # format a file with the language server
+lsp status          # show installed/active language servers
 ```
 
-Typical contents include:
+### In LSD sessions
+
+LSD prefers `lsp` over grep/find for typed codebases when a language server is available.
+
+If a server is missing, run:
+
+```bash
+/setup
+```
+
+or inspect status with:
 
 ```text
-~/.lsd/
-  agent/
-    auth.json
-    settings.json
-    extensions/
-    agents/
-  sessions/
+lsp status
 ```
 
-### Project-level
+---
 
-Per-project state lives in:
+## RTK shell compression
 
-```text
-.lsd/
+LSD supports **RTK** for shell-command compression.
+
+RTK rewrites certain shell commands into a more compact representation before they run, which helps reduce repetitive terminal output in agent context.
+
+### Why RTK is good
+
+RTK is useful when the agent or a background shell runs lots of repetitive commands like:
+
+- `git status`
+- `git diff`
+- test runs
+- package-manager commands
+- other high-noise shell commands
+
+Benefits:
+
+- saves context tokens
+- reduces noisy terminal output
+- keeps long sessions cleaner
+- lets the agent spend more context on code and reasoning instead of duplicated shell text
+
+When active, LSD can also surface session savings like how many tokens RTK saved.
+
+### Enable RTK
+
+Turn it on in `/settings` by enabling **RTK**.
+
+You can also enable it in preferences:
+
+```yaml
+experimental:
+  rtk: true
 ```
 
-Depending on your workflow, this may contain plan files, state files, generated artifacts, and project-local config.
+RTK requires a restart after toggling.
+
+### Where RTK helps most
+
+RTK is most valuable in long-running sessions, background shell workflows, and repos where the agent repeatedly checks git state, runs tests, or invokes build tooling.
 
 ---
 
-## Common commands
+## Web research
 
-### Main CLI
+- Google-backed search (`google_search`)
+- Brave / Tavily web search
+- Page extraction via Jina
+- Context7 library docs lookup (`/context7`)
 
-```bash
-lsd                      # start interactive session
-lsd -c                   # resume last session
-lsd --print "..."        # one-shot mode
-lsd --list-models        # list available models
-lsd --mode mcp           # run as MCP server
-```
+---
 
-### Setup + maintenance
+## Extensions, themes, and skills
+
+LSD supports a package-like extension system:
 
 ```bash
-lsd config               # re-run setup wizard
-lsd update               # update LSD
-lsd sessions             # browse saved sessions
+lsd install <source>   # install extension/theme/skill
+lsd remove <source>    # remove
+lsd list               # list installed packages
 ```
 
-### Worktrees
+Sources: `npm:@scope/pkg`, `git:github.com/user/repo`, `https://...`, local paths.
 
-```bash
-lsd -w                   # create/resume worktree session
-lsd worktree list
-lsd worktree merge NAME
-lsd worktree clean
-lsd worktree remove NAME
+Bundled extensions include: memory, remote-questions, browser-tools, subagent, codex-rotate, usage, voice, bg-shell, async-jobs, context7, universal-config, search-the-web, cache-timer, mac-tools, aws-auth.
+
+---
+
+## Configuration reference
+
+### PREFERENCES.md
+
+Stored in `~/.lsd/PREFERENCES.md` (global) or `.lsd/PREFERENCES.md` (project). YAML frontmatter:
+
+```yaml
+---
+search_provider: tavily         # tavily | brave | ollama | native | auto
+remote_questions:
+  channel: telegram             # telegram | discord | slack
+  channel_id: "-1001234567890"
+  timeout_minutes: 5
+  poll_interval_seconds: 5
+experimental:
+  rtk: true                     # RTK shell-command compression
+  codex_rotate: true            # Codex multi-account rotation
+subagent:
+  budget_model: claude-haiku-4  # model used for memory/subagent background work
+cmux:
+  enabled: false
+  notifications: false
+---
 ```
 
-### Headless
+### settings.json
 
-```bash
-lsd headless
-lsd headless next
-lsd headless status
-lsd headless --json auto
+Located at `~/.lsd/agent/settings.json`. Editable via `/settings` in the TUI. Includes model preferences, UI toggles (cache timer, pin last prompt, accent color), and `budgetSubagentModel`.
+
+### auth.json
+
+Located at `~/.lsd/agent/auth.json`. Stores provider API keys and OAuth tokens. Modified by `/login` and `/codex add`.
+
+### Configuration paths
+
+```text
+~/.lsd/
+  agent/
+    auth.json         API keys + OAuth tokens
+    settings.json     UI + model preferences
+    extensions/       Installed extensions
+    agents/           Custom agent definitions
+  sessions/           Saved sessions (all projects)
+  projects/
+    <project>/
+      memory/         Persistent memory files
+  PREFERENCES.md      Global preferences
+```
+
+```text
+.lsd/               Per-project state
+  PREFERENCES.md    Project-level preference overrides
+  mcp.json          Project MCP servers
 ```
 
 ---
 
-## Slash-command compatibility
+## Full CLI reference
 
-Inside the session, you may still see legacy commands such as:
+```bash
+lsd                          # interactive session
+lsd -c                       # resume last session
+lsd --continue               # resume last session (long form)
+lsd --print "..."            # one-shot mode
+lsd -w [name]                # worktree session
+lsd --model <id>             # override model
+lsd --sandbox <mode>         # sandbox mode: none | workspace-write | auto
+lsd --no-sandbox             # disable sandbox
+lsd --no-session             # disable session persistence
+lsd --extension <path>       # load extra extension
+lsd --tools a,b,c            # restrict available tools
+lsd --list-models [search]   # list available models
+lsd --version                # print version
+lsd --help                   # print help
+lsd --mode <text|json|rpc|mcp>  # output mode
+
+lsd config                   # re-run setup wizard
+lsd update                   # update to latest version
+lsd sessions                 # browse saved sessions
+lsd install <source>         # install package/extension
+lsd remove <source>          # remove installed package
+lsd list                     # list installed packages
+lsd worktree list            # list worktrees
+lsd worktree merge [name]    # merge worktree into main
+lsd worktree clean           # remove merged/empty worktrees
+lsd worktree remove <name>   # remove specific worktree
+lsd headless [cmd] [flags]   # headless mode (see above)
+```
+
+---
 
-- `/gsd auto`
-- `/gsd status`
-- `/gsd config`
-- `/gsd doctor`
-- `/gsd queue`
+## Naming note
 
-These remain usable, but the product branding is LSD.
+LSD evolved from GSD 2, but the product, docs, and recommended workflows are LSD-first. Prefer:
 
-If you are rewriting docs or onboarding material, prefer:
+- `lsd` — binary
+- `.lsd/` — project state
+- `~/.lsd/` — global state
+- `/lsd remote` — remote questions
+- `/help` — live in-session command reference
 
-- **LSD** for the product name
-- **`lsd`** for the command
-- **`.lsd/`** for project state
-- **`~/.lsd/`** for global state
+Any remaining `/gsd` surfaces should be treated as compatibility aliases, not the primary workflow.
 
 ---
 
 ## Documentation
 
-See the local docs in [`docs/`](./docs/) for deeper details.
-
-Recommended starting points:
+See [`docs/`](./docs/) for deeper details:
 
 - [Getting Started](./docs/getting-started.md)
 - [Commands Reference](./docs/commands.md)
@@ -469,34 +675,15 @@ Recommended starting points:
 - [Skills](./docs/skills.md)
 - [Custom Models](./docs/custom-models.md)
 
-> Note: parts of the docs may still contain older GSD wording. The README reflects the intended LSD-facing product language.
-
 ---
 
 ## Development
 
-Build the repo:
-
-```bash
-npm run build
-```
-
-Link the local CLI globally:
-
-```bash
-npm link
-```
-
-Run the dev CLI:
-
-```bash
-npm run gsd
-```
-
-Run tests:
-
 ```bash
-npm test
+npm run build    # build
+npm link         # link local CLI globally
+npm run gsd      # run dev CLI
+npm test         # run tests
 ```
 
 ---