docs: reorganize README into a docs/ guide with a table of contents

docs/README.md

@@ -0,0 +1,39 @@
+# GX Documentation
+
+GX is a smart Git CLI with interactive pickers, a workspace (git worktree)
+manager, a pull-request dashboard, and shell integration.
+
+New to gx? Start with **[Getting Started](getting-started.md)**.
+
+## Contents
+
+| Guide | What's inside |
+| --- | --- |
+| [Getting Started](getting-started.md) | Installation, prerequisites, shell integration, and a first workflow. |
+| [Core Commands](commands.md) | Everyday Git, made interactive: `checkout`, `status`, `add`, `commit`, `push`, `stash`, `log`, and git pass-through. |
+| [Workspaces](workspaces.md) | Manage git worktrees: create, switch, update, sync setup files, and clean up stale workspaces and branches. |
+| [Pull Requests](pull-requests.md) | The interactive PR dashboard: review-state grouping, quick actions, reviewer suggestions. |
+| [Repo Onboarding](onboarding.md) | Make new workspaces reproducible with shared (`.gx/workspace.toml`) or personal setup, including pre/post-create hooks. |
+| [Shell Integration](shell-integration.md) | `gx setup`: aliases, the `cd`-on-switch wrapper, and completions for zsh, bash, and fish. |
+| [Configuration](configuration.md) | The `~/.config/gx/config.toml` reference: AI, workspace, and PR-dashboard settings. |
+| [Agent Skills](skills.md) | Ship gx as a guide rail for autonomous AI coding agents. |
+
+## Command reference at a glance
+
+| Command | Aliases | Documentation |
+| --- | --- | --- |
+| `checkout` | `co`, `switch` | [Core Commands → Checkout](commands.md#checkout) |
+| `status` | `s` | [Core Commands → Status](commands.md#status) |
+| `add` | `a` | [Core Commands → Add](commands.md#add) |
+| `commit` | `c` | [Core Commands → Commit](commands.md#commit) |
+| `push` | `p` | [Core Commands → Push](commands.md#push) |
+| `stash` | `st` | [Core Commands → Stash](commands.md#stash) |
+| `log` | `l` | [Core Commands → Log](commands.md#log) |
+| `workspace` | `ws` | [Workspaces](workspaces.md) |
+| `pr` | `prs`, `pullrequest`, `pullrequests` | [Pull Requests](pull-requests.md) |
+| `onboarding` | `onboard` | [Repo Onboarding](onboarding.md) |
+| `setup` | — | [Shell Integration](shell-integration.md) |
+
+---
+
+[← Back to the project README](../README.md)

docs/commands.md

@@ -0,0 +1,159 @@
+# Core Commands
+
+[← Docs index](README.md)
+
+Everyday Git operations, made interactive. Every command has short aliases, and
+unrecognized commands pass straight through to `git`.
+
+- [Checkout](#checkout)
+- [Status](#status)
+- [Add](#add)
+- [Commit](#commit)
+- [Push](#push)
+- [Stash](#stash)
+- [Log](#log)
+- [Git pass-through](#git-pass-through)
+
+## Checkout
+
+Switch to a branch, commit, or tag.
+
+```bash
+gx checkout <query>
+gx co <query>
+gx switch <query>
+
+# GitHub references resolve to a branch in the current repo, then check it out:
+gx checkout https://github.com/<owner>/<repo>/pull/13   # PR -> its head branch
+gx checkout https://github.com/<owner>/<repo>/tree/<branch>
+gx checkout '#13'                                        # shorthand for a PR (quote it)
+```
+
+**Arguments**
+
+- `query` (optional): branch/commit/tag to checkout (supports fuzzy matching).
+
+**GitHub references:** in place of a query you can pass a GitHub pull-request
+URL, a branch (`/tree/...`) URL, or the `#<number>` PR shorthand. gx verifies the
+reference belongs to this repository's `origin` remote (erroring otherwise),
+resolves pull requests to their head branch via the GitHub CLI (`gh`), and
+checks it out. Pull requests opened from a fork are not supported. The same
+references also work for [`gx workspace new`](workspaces.md#creating-a-workspace)
+(the workspace is named after the resolved branch) and `gx workspace go`.
+
+## Status
+
+Show the current repository status with an interactive TUI.
+
+```bash
+gx status
+gx s
+```
+
+## Add
+
+Stage files for commit.
+
+```bash
+gx add                    # Stage all files
+gx add <paths...>         # Stage specific files
+gx add -i                 # Interactive mode - select files to stage
+gx a -i
+```
+
+**Flags**
+
+- `-i`, `--interactive`: select files interactively.
+
+## Commit
+
+Create a new commit.
+
+```bash
+gx commit                 # Opens editor for message
+gx commit "message"       # Use provided message
+gx commit -m "message"
+gx c -m "message"
+gx commit --amend         # Amend previous commit
+gx commit --ai            # Generate commit message using AI
+gx commit --no-edit       # Amend without editing message
+```
+
+**Flags**
+
+- `-m`, `--message`: commit message.
+- `--amend`: amend the previous commit.
+- `--no-edit`: use the existing commit message without editing.
+- `--ai`: generate a commit message using AI (see [AI configuration](configuration.md#ai-configuration)).
+
+## Push
+
+Push commits to the remote repository.
+
+```bash
+gx push
+gx p
+gx push --force
+gx push --force-dangerously
+```
+
+**Flags**
+
+- `-f`, `--force`: force push with lease (safer).
+- `--force-dangerously`: force push without lease (dangerous).
+
+## Stash
+
+Stash changes with various subcommands.
+
+```bash
+gx stash                 # Interactive stash picker
+gx st
+gx stash push            # Push stash (default)
+gx stash push -m "msg"   # Push stash with message
+gx stash push -u         # Include untracked files
+gx stash list            # List all stashes
+gx stash pop             # Apply and remove latest stash
+gx stash pop 0           # Apply and remove specific stash
+gx stash apply           # Apply without removing
+gx stash drop            # Drop latest stash
+gx stash drop 0          # Drop specific stash
+gx stash clear           # Remove all stashes
+gx stash show            # Show diff of latest stash
+gx stash show 0          # Show diff of specific stash
+gx stash branch <name>   # Create branch from stash
+```
+
+**Flags**
+
+- `-m`, `--message`: stash message (`push`).
+- `-u`, `--untracked`: include untracked files (`push`).
+
+## Log
+
+View commit history.
+
+```bash
+gx log
+gx l
+gx log -n 10
+gx log --limit 10
+```
+
+**Flags**
+
+- `-n`, `--limit`: maximum number of commits to show.
+
+## Git pass-through
+
+Any command gx doesn't recognize is passed through to `git`, so you can keep
+using gx as your everyday git entry point.
+
+```bash
+gx git <command>
+gx remote -v
+```
+
+---
+
+[← Docs index](README.md) · [Workspaces →](workspaces.md)

docs/configuration.md

@@ -0,0 +1,98 @@
+# Configuration
+
+[← Docs index](README.md)
+
+GX uses a global configuration file at `~/.config/gx/config.toml`. It controls
+aliases, the AI agent, workspace defaults, and the PR dashboard. Add
+`eval "$(gx setup)"` to your shell config to load the aliases you define here
+(see [Shell Integration](shell-integration.md)).
+
+> Looking for **per-repository** workspace setup (`.gx/workspace.toml`, copy
+> files, setup scripts, hooks)? That lives with [Repo Onboarding](onboarding.md).
+
+- [AI configuration](#ai-configuration)
+- [Workspace configuration](#workspace-configuration)
+- [PR dashboard configuration](#pr-dashboard-configuration)
+
+## AI configuration
+
+Configure the AI agent and model used for AI-generated commit messages
+([`gx commit --ai`](commands.md#commit)) and reviewer suggestions.
+
+```toml
+[ai]
+agent = "opencode"  # Options: "opencode" or "claude"
+model = "opencode/big-pickle"  # Model to use
+```
+
+For Claude, the default model you should use is `"haiku"`. You can configure the
+agent and model to your preference.
+
+## Workspace configuration
+
+```toml
+[workspace]
+# Where workspaces are created. "{repo}" is replaced with the repository
+# directory name. Supports "~" for the home directory and absolute paths;
+# relative paths are resolved against the main worktree root.
+root = "~/gx/workspaces/{repo}"
+
+# Files copied from the main worktree into new workspaces.
+# Paths are relative to the repo root. "*" / "?" match within one path
+# component; "**" matches zero or more path components. Directories are
+# copied recursively, missing entries are skipped.
+copy_files = [".env"]
+
+# Branches cleanup must never remove, on top of the always-protected set
+# (the default branch, "main", "master", the current branch, and any branch
+# checked out in a worktree). Managed by `gx workspace protect`/`unprotect`.
+protected_branches = []
+
+[workspace.clean]
+# A workspace counts as "stale" once it is at least this many days old.
+# Only consulted by `gx workspace clean --auto --use-threshold`.
+threshold_days = 7
+
+# When true, a bare `gx workspace clean` behaves like `--auto`.
+auto = false
+```
+
+Example with more setup files:
+
+```toml
+[workspace]
+copy_files = [".env*", "**/.env.local", "config/local.toml", ".vscode"]
+```
+
+See [Workspaces](workspaces.md) for the commands these settings affect, and
+[Repo Onboarding](onboarding.md) for committable, per-repo workspace policy.
+
+## PR dashboard configuration
+
+Settings for the [pull-request dashboard](pull-requests.md).
+
+```toml
+[pr]
+# Orgs offered in the dashboard's "org" scope (ctrl+s cycles through scopes).
+# Each entry becomes a `gh search --owner <org>` qualifier. Empty by default,
+# which omits the org scope from the cycle.
+orgs = []
+
+# Default merge method used by the merge action: "squash", "merge", or "rebase".
+merge_method = "squash"
+
+# Whether reviewer suggestion falls back to the configured AI agent when the
+# deterministic (CODEOWNERS + commit history) signal is thin.
+reviewer_ai_fallback = true
+```
+
+Example scoping the org filter to your org:
+
+```toml
+[pr]
+orgs = ["dash0hq"]
+```
+
+---
+
+[← Shell Integration](shell-integration.md) · [Docs index](README.md) · [Agent Skills →](skills.md)

docs/getting-started.md

@@ -0,0 +1,72 @@
+# Getting Started
+
+[← Docs index](README.md)
+
+## Prerequisites
+
+- **Git** — gx is a layer on top of git.
+- **GitHub CLI (`gh`)** — required for the
+  [pull-request dashboard](pull-requests.md) and for resolving GitHub URLs in
+  [`checkout`](commands.md#checkout) and [`workspace`](workspaces.md) commands.
+  Install it and run `gh auth login`.
+
+## Installation
+
+**Homebrew**
+
+```bash
+brew install reckerp/tap/gx
+```
+
+**From source**
+
+```bash
+cargo install --path .
+```
+
+## Shell integration
+
+Add this to your shell config (`~/.zshrc`, `~/.bashrc`, or
+`~/.config/fish/config.fish`):
+
+```bash
+eval "$(gx setup)"
+```
+
+This loads your aliases, the wrapper that lets `gx workspace` change your shell's
+directory, and shell completions. See [Shell Integration](shell-integration.md)
+for details and customization.
+
+> Without the wrapper, gx still works — it just prints the workspace path so you
+> can `cd "$(gx workspace go <query>)"` yourself.
+
+## Your first workflow
+
+```bash
+# Stage and commit interactively
+gx status            # see what changed
+gx add -i            # pick files to stage
+gx commit --ai       # generate a commit message with AI (or: gx commit -m "...")
+gx push
+
+# Start an isolated task in its own workspace (git worktree)
+gx workspace new feat/awesome
+# ... edit, commit, and push from inside the workspace ...
+
+# Switch back to another workspace later
+gx workspace go      # fuzzy-pick, or pass a query: gx workspace go main
+
+# Review and act on your pull requests
+gx pr
+```
+
+## Where to go next
+
+- [Core Commands](commands.md) — the day-to-day git wrappers.
+- [Workspaces](workspaces.md) — get the most out of git worktrees.
+- [Repo Onboarding](onboarding.md) — make new workspaces reproducible.
+- [Configuration](configuration.md) — customize aliases, AI, and defaults.
+
+---
+
+[Docs index](README.md) · [Core Commands →](commands.md)