gflows 0.1.18 → 1.0.0

package/README.md

@@ -1,556 +1,357 @@
-# gFlows
+# gflows
 
-A lightweight CLI for consistent Git branching workflows: long-lived **main** (production) and **dev** (integration), plus short-lived workflow branches with clear merge targets. Built for [Bun](https://bun.sh) and TypeScript; **scriptable** and **safe by default**—no history rewriting, predictable exit codes, and optional interactive pickers only when running in a TTY.
+[![npm](https://img.shields.io/npm/v/gflows.svg)](https://www.npmjs.com/package/gflows)
+[![JSR](https://jsr.io/badges/@alialnaghmoush/gflows)](https://jsr.io/@alialnaghmoush/gflows)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Bun](https://img.shields.io/badge/runtime-Bun-fbf0df?logo=bun&logoColor=black)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Ink](https://img.shields.io/badge/UI-Ink-E88C4A)](https://term.ink)
 
-**Author:** [Ali AlNaghmoush](https://github.com/alialnaghmoush) · **Repository:** [github.com/alialnaghmoush/gflows](https://github.com/alialnaghmoush/gflows)
+**Git branching that stays simple.**  
+Long-lived `main` + `dev`, short-lived typed branches, clear merge targets — as a Bun/TypeScript CLI.
 
----
-
-## Table of contents
-
-**Get started**
-
-- [Prerequisites](#prerequisites)
-- [Installation](#installation)
-- [Quick start](#quick-start)
-
-**Understand**
-
-- [Concepts](#concepts)
-- [Flowcharts](#flowcharts)
-- [Branch types in detail](#branch-types-in-detail)
-
-**Reference**
 
-- [Command reference](#command-reference)
+| You want…             | Do this                                                                |
+| --------------------- | ---------------------------------------------------------------------- |
+| Just pick from a menu | `gflows` or `g` → [hub](#three-ways-to-run-gflows)                     |
+| Type commands         | [5-minute path](#5-minute-path) · [cheat sheet](#command-cheat-sheet)  |
+| Agents / CI           | [AGENTS.md](AGENTS.md) · `gflows schema` · [Scripting](#scripting--ci) |
 
-**Configure & operate**
-
-- [Configuration](#configuration)
-- [Scripting and CI](#scripting-and-ci)
-- [Exit codes](#exit-codes)
-- [Troubleshooting](#troubleshooting)
-
-**More**
-
-- [Shell completion](#shell-completion)
-- [Publishing (maintainers)](#publishing-maintainers)
-- [License](#license)
 
 ---
 
-## Prerequisites
 
-- **Bun** ≥ 1.0 (recommended). The CLI runs TypeScript directly.
-- **Git** for repository operations.
 
-Check versions:
+## Three ways to run gflows
 
-```bash
-bun --version
-git --version
-```
 
----
+| Way                  | When                 | Example                                                        |
+| -------------------- | -------------------- | -------------------------------------------------------------- |
+| **1. Hub (select)**  | Daily, in a terminal | `gflows` / `g` → select or `/start` — wizards stay in Ink |
+| **2. Long commands** | Scripts, clarity     | `gflows start feature payments`                                |
+| **3. Short flags**   | Fast typing          | `g -S -f payments`                                             |
 
-## Installation
 
-**Dev dependency (recommended):** `bun add --dev gflows` or `npm install --save-dev gflows`.  
-**JSR:** `npx jsr add --dev @alialnaghmoush/gflows` or `deno add --dev jsr:@alialnaghmoush/gflows`.
 
-Run with `bunx gflows ...` or `npx gflows ...`. [npm](https://www.npmjs.com/package/gflows) · [JSR](https://jsr.io/@alialnaghmoush/gflows)
 
-**Global:** `bun add --global gflows` or `npm install --global gflows`
-
----
-
-## Quick start
-
-**1. One-time setup** — In your repo, ensure `main` exists and create `dev`:
+### Way 1 — Hub (recommended for humans)
 
 ```bash
-bun gflows init
+# optional, once — put in ~/.zshrc or ~/.bashrc
+alias g=gflows
+# or if gflows is only a project dependency:
+alias g='bunx gflows'
 ```
 
-Use `--no-push` to skip push, `--dry-run` to preview. Pass `--main`, `--dev`, `--remote` to persist to `.gflows.json`.
+Then:
 
 ```bash
-bun gflows init --main main --dev develop --remote origin
+g          # or: gflows
 ```
 
-**2. Daily development** (feature → dev):
+You get a fullscreen menu: what’s next, branch map, actions. **Select** an item (or type `/start`, `/finish`, `/sync`, …). Follow-up questions (type, name, push, rebase) stay **inside the Ink UI** — no drop-out to a separate prompt tool. Only the git command itself runs on the main screen, then you press enter to return.
 
-```bash
-bun gflows start feature add-login
-# ... code, commit ...
-bun gflows finish feature
-bun gflows finish feature --push
-bun gflows finish feature --push -D
 ```
-
-**3. Release** (dev → main, then tag):
-
-```bash
-bun gflows bump up minor
-bun gflows start release v1.3.0
-# ... update CHANGELOG, commit ...
-bun gflows finish release --push
+❯ ★ Start new work
+  Sync with base
+  Open pull request
+  Finish / merge branch
+  …
 ```
 
-**4. Hotfix** (main → fix → main + dev):
 
-```bash
-bun gflows start hotfix v1.3.1
-# ... fix, commit ...
-bun gflows finish hotfix --push
-```
 
----
+### Way 2 & 3 — Type it yourself
 
-## Concepts
+Same job, no menu (`alias g=gflows`):
 
-- **main** — Production branch. Only release and hotfix merge here.
-- **dev** — Integration branch. Feature, bugfix, chore, spike merge here. Created by `gflows init` from main.
-- **Workflow branches** — Short-lived branches with a type prefix; each has a base and merge target(s). No history rewriting.
-- **Merge targets:** feature/chore/spike → dev; bugfix → dev (or main with `-o main`); release/hotfix → main then dev + tag.
+| Long | Short |
+|------|-------|
+| `gflows start feature payments` | `g -S -f payments` |
+| `gflows finish feature -y -P` | `g -F -f -y -P` |
 
-Override names and prefixes via [configuration](#configuration).
+CI and agents should always use **typed** commands (never the hub). See [Scripting & CI](#scripting--ci).
 
 ---
 
-## Flowcharts
-
-### Lifecycle (init → start → finish)
-
-```mermaid
-flowchart LR
-  subgraph setup["One-time setup"]
-    A[main exists] --> B["bun gflows init"]
-    B --> C[dev created]
-    C --> D[optional: push dev]
-  end
-  subgraph daily["Daily workflow"]
-    E["bun gflows start<br/>type name"] --> F[work & commit]
-    F --> G["bun gflows finish<br/>type"]
-    G --> H{type?}
-    H -->|feature/bugfix/chore/spike| I[merged to dev]
-    H -->|release/hotfix| J[merged to main → dev + tag]
-  end
-  setup --> daily
-```
 
-### init
-
-```mermaid
-flowchart TD
-  Start([bun gflows init]) --> Repo{In git repo?}
-  Repo -->|no| ErrRepo[Exit: Not a repo]
-  Repo -->|yes| MainExists{main branch exists?}
-  MainExists -->|no| ErrMain[Exit: Create main first]
-  MainExists -->|yes| DevExists{dev branch exists?}
-  DevExists -->|yes| DoneNoOp[Done: nothing to do]
-  DevExists -->|no| CreateDev[Create dev from main]
-  CreateDev --> Push{--no-push?}
-  Push -->|no| DoPush[Push dev to remote]
-  Push -->|yes| SkipPush[Skip push]
-  DoPush --> Done[Done]
-  SkipPush --> Done
-  DoneNoOp --> Done
-```
 
-### start
-
-```mermaid
-flowchart TD
-  Start([bun gflows start type name]) --> Repo{In git repo?}
-  Repo -->|no| ErrRepo[Exit: Not a repo]
-  Repo -->|yes| Clean{Tree clean or --force?}
-  Clean -->|no| ErrDirty[Exit: Uncommitted changes]
-  Clean -->|yes| Base[Resolve base branch for type]
-  Base --> BaseExists{Base exists locally or remote?}
-  BaseExists -->|no| ErrBase[Exit: Base not found]
-  BaseExists -->|yes| Create[Create workflow branch from base]
-  Create --> PushOpt{--push?}
-  PushOpt -->|yes| Push[Push new branch to remote]
-  PushOpt -->|no| Done[Done]
-  Push --> Done
-```
+## Why gflows?
 
-### finish (merge targets by branch type)
-
-```mermaid
-flowchart TD
-  Start([bun gflows finish type]) --> Resolve[Resolve branch to finish]
-  Resolve --> T{type}
-  T -->|feature / chore / spike| M1[Merge → dev]
-  T -->|bugfix from dev| M1
-  T -->|bugfix from main| M2[Merge → main]
-  T -->|release| M3[Merge → main]
-  M3 --> M3b[Merge main → dev]
-  M3b --> Tag1[Create tag]
-  T -->|hotfix| M4[Merge → main]
-  M4 --> M4b[Merge main → dev]
-  M4b --> Tag2[Create tag]
-  M2 --> M2b[Merge main → dev]
-  M1 --> Opt[Optional: delete branch, push]
-  M2b --> Opt
-  Tag1 --> Opt
-  Tag2 --> Opt
-  Opt --> Done([Done])
-```
-
-### Branch types and merge targets
-
-```mermaid
-flowchart TB
-  subgraph longlived["Long-lived branches"]
-    main[main]
-    dev[dev]
-  end
-  subgraph workflow["Workflow branches"]
-    feature[feature/...]
-    bugfix[bugfix/...]
-    chore[chore/...]
-    release[release/...]
-    hotfix[hotfix/...]
-    spike[spike/...]
-  end
-  feature --> dev
-  chore --> dev
-  spike --> dev
-  bugfix --> dev
-  bugfix -.->|"-o main"| main
-  release --> main
-  main --> dev
-  release -.-> dev
-  hotfix --> main
-  main --> dev
-  hotfix -.-> dev
-```
+Most teams reinvent the same rules: features go to `dev`, releases hit `main`, hotfixes sync back. gflows encodes that so you stop typing fragile git-flow by hand.
 
-### bump (version)
-
-```mermaid
-flowchart LR
-  Start([bun gflows bump direction type]) --> Discover[Discover package.json, jsr.json]
-  Discover --> Read[Read version from primary root]
-  Read --> Calc[Compute new version]
-  Calc --> Write[Write to all roots]
-  Write --> Done([Done])
-```
+- **Safe defaults** — no history rewrite; finish refuses empty/dirty work; delete-after-finish is on (opt out with `-N`)
+- **Human + machine** — Ink hub in a TTY; explicit flags in CI; JSON + MCP for agents
+- **Recoverable** — `continue` / `abort` / `undo` after conflicts
 
 ---
 
-## Branch types in detail
-
-| Type    | Short | Base (default) | With `-o main` | Merge target(s)            | Tag |
-| ------- | ----- | -------------- | -------------- | -------------------------- | --- |
-| feature | `-f`  | dev            | —              | dev                        | no  |
-| bugfix  | `-b`  | dev            | main           | dev (or main if from main) | no  |
-| chore   | `-c`  | dev            | —              | dev                        | no  |
-| release | `-r`  | dev            | —              | main, then dev             | yes |
-| hotfix  | `-x`  | main           | —              | main, then dev             | yes |
-| spike   | `-e`  | dev            | —              | dev                        | no  |
-
-Release and hotfix names must be a version (`vX.Y.Z` or `X.Y.Z`). Branch names use default prefixes (e.g. `feature/add-login`); override in [configuration](#configuration). Invalid names (e.g. `..`, `*`, spaces) → exit 1.
-
----
-
-## Command reference
-
-### Summary table
-
-| Command      | Short | Description                                                               |
-| ------------ | ----- | ------------------------------------------------------------------------- |
-| `init`       | `-I`  | Ensure main exists; create dev from main.                                 |
-| `start`      | `-S`  | Create a workflow branch (requires type + name).                          |
-| `finish`     | `-F`  | Merge branch into target(s), optional tag (release/hotfix), delete, push. |
-| `switch`     | `-W`  | Switch to a workflow branch (picker or name); with uncommitted changes: prompt or `--move` / `--restore` / `--clean` / `--destroy` / `--cancel`. |
-| `delete`     | `-L`  | Delete local workflow branch(es). Never main/dev.                         |
-| `list`       | `-l`  | List workflow branches; optional type filter and remote.                  |
-| `bump`       | —     | Bump or rollback package version (patch/minor/major).                     |
-| `completion` | —     | Print shell completion script (bash/zsh/fish).                            |
-| `status`     | `-t`  | Show current branch, type, base, merge target(s), ahead/behind.           |
-| `help`       | `-h`  | Show usage and quick reference.                                           |
-| `version`    | `-V`  | Show version.                                                             |
-
 
-**Common flags:**
 
+## Install
 
-| Flag              | Short | Description                           |
-| ----------------- | ----- | ------------------------------------- |
-| `--path <dir>`    | `-C`  | Run as if in `<dir>`.                 |
-| `--dry-run`       | `-d`  | Log intended actions only; no writes. |
-| `--verbose`       | `-v`  | Verbose output.                       |
-| `--quiet`         | `-q`  | Minimal output.                       |
-| `--push`          | `-p`  | Push after init/start/finish.         |
-| `--no-push`       | `-P`  | Do not push.                          |
-| `--main <name>`   | —     | Main branch override.                 |
-| `--dev <name>`    | —     | Dev branch override.                  |
-| `--remote <name>` | `-R`  | Remote for push.                      |
-| `--from <branch>` | `-o`  | Base branch override (start).         |
-| `--branch <name>` | `-B`  | Branch name (finish).                 |
-| `--yes`           | `-y`  | Skip confirmations.                   |
-
-
----
-
-### init
-
-Ensures main exists; creates dev from main if missing. Use `--main`, `--dev`, `-R` to persist to `.gflows.json`.
-
-**Examples:**
+**Needs:** [Bun](https://bun.sh) ≥ 1.0 and Git.
 
 ```bash
-bun gflows init
-bun gflows init --main main --dev develop --remote origin
-bun gflows init -C ../other-repo --dry-run
-```
-
-**Flags:**
-
-
-| Flag              | Short | Description                                                   |
-| ----------------- | ----- | ------------------------------------------------------------- |
-| `--push`          | `-p`  | Push dev to remote after creating (default).                  |
-| `--main <name>`   | —     | Main branch name (persisted to `.gflows.json` when provided). |
-| `--dev <name>`    | —     | Dev branch name (persisted to `.gflows.json` when provided).  |
-| `--remote <name>` | `-R`  | Remote name (persisted to `.gflows.json` when provided).      |
-| `--path <dir>`    | `-C`  | Run as if in `<dir>`.                                         |
-| `--dry-run`       | `-d`  | Log intended actions only; no writes.                         |
-| `--verbose`       | `-v`  | Verbose output.                                               |
-| `--quiet`         | `-q`  | Minimal output.                                               |
-
-
----
+# project (recommended)
+bun add --dev gflows
 
-### start
+# or global
+bun add --global gflows
 
-Creates a workflow branch from the correct base. Requires type + name; release/hotfix name must be a version. Pre-checks: git repo, clean tree (or `--force`), base exists.
+# npm / npx also work
+npm install --save-dev gflows
+```
 
-**Examples:**
+**JSR:** `[@alialnaghmoush/gflows](https://jsr.io/@alialnaghmoush/gflows)`
 
 ```bash
-bun gflows start feature auth-refactor
-bun gflows start bugfix fix-login --from main
-bun gflows start release v2.0.0
-bun gflows start hotfix 1.2.1
-bun gflows start feature wip --force --push
+bunx gflows version   # sanity check
 ```
 
-**Flags:**
-
-
-| Flag              | Short | Description                                       |
-| ----------------- | ----- | ------------------------------------------------- |
-| `--force`         | —     | Allow dirty working tree.                         |
-| `--push`          | `-p`  | Push new branch to remote after creating.         |
-| `--from <branch>` | `-o`  | Base branch override (e.g. `-o main` for bugfix). |
-| `--remote <name>` | `-R`  | Remote for push.                                  |
-| `--path <dir>`    | `-C`  | Run as if in `<dir>`.                             |
-| `--dry-run`       | `-d`  | Log intended actions only; no writes.             |
-| `--verbose`       | `-v`  | Verbose output.                                   |
-| `--quiet`         | `-q`  | Minimal output.                                   |
-
-
 ---
 
-### finish
 
-Merges the branch (current or `-B`) into its target(s). Release/hotfix: merge to main, then main → dev, create tag. Use `--no-ff` for a merge commit. On conflict, resolve then `git merge --continue` or re-run finish.
 
-**Examples:**
+## Mental model (2 minutes)
 
-```bash
-bun gflows finish feature
-bun gflows finish feature -B feature/auth --push -D
-bun gflows finish release --push
-bun gflows finish hotfix -s -T -y
+```
+main  ←  release / hotfix only          (production)
+ │
+ └──→  dev  ←  feature / bugfix / chore / spike   (integration)
+              ↑
+         short-lived workflow branches
 ```
 
-**Flags:**
 
+| Branch                               | Role                                                        |
+| ------------------------------------ | ----------------------------------------------------------- |
+| **main**                             | Production                                                  |
+| **dev**                              | Integration (created by `init` from main)                   |
+| **feature / bugfix / chore / spike** | Day-to-day work → merge to **dev**                          |
+| **release / hotfix**                 | Versioned (`vX.Y.Z`) → **main**, then **main → dev**, + tag |
 
-| Flag                  | Short | Description                                                                          |
-| --------------------- | ----- | ------------------------------------------------------------------------------------ |
-| `--branch <name>`     | `-B`  | Branch to finish (current branch if omitted; picker in TTY when `-B` with no value). |
-| `--no-ff`             | —     | Always create a merge commit.                                                        |
-| `--delete`            | `-D`  | Delete branch after finish.                                                          |
-| `--no-delete`         | `-N`  | Do not delete branch after finish.                                                   |
-| `--push`              | `-p`  | Push after merge (finish prompts "Do you want to push?" when neither `-p` nor `-P`). |
-| `--no-push`           | `-P`  | Do not push.                                                                         |
-| `--sign`              | `-s`  | Sign the tag (release/hotfix; GPG).                                                  |
-| `--no-tag`            | `-T`  | Do not create tag (release/hotfix).                                                  |
-| `--tag-message <msg>` | `-M`  | Tag message.                                                                         |
-| `--message <msg>`     | `-m`  | Merge message.                                                                       |
-| `--yes`               | `-y`  | Skip confirmations (e.g. "Delete branch after finish?").                             |
-| `--path <dir>`        | `-C`  | Run as if in `<dir>`.                                                                |
-| `--dry-run`           | `-d`  | Log intended actions only; no writes.                                                |
-| `--verbose`           | `-v`  | Verbose output.                                                                      |
-| `--quiet`             | `-q`  | Minimal output.                                                                      |
 
+**Lifecycle:** `init` → `start` → commit → (`sync`) → (`pr`) → `finish`
 
 ---
 
-### switch
 
-Switch to a workflow branch. With TTY and no branch name, shows a picker; otherwise pass the branch name (e.g. `gflows switch dev` or `-B dev`).
 
-**Uncommitted changes:** If the working tree is dirty and stdin is a TTY, you are prompted to choose:
+## 5-minute path
 
-| Option | Description |
-| ------ | ----------- |
-| **Move** | Move current changes to the target branch. |
-| **Restore** | Save changes for this branch; restore target's saved state (if any). |
-| **Clean** | Discard changes and switch clean at HEAD. |
-| **Destroy** | Delete current branch and switch to the target branch (cannot destroy main or dev). |
-| **Cancel** | Abort switching. |
 
-You can skip the prompt by passing exactly one of the flags below. If the target branch has saved changes and you use **Clean**, a warning is shown (unless `-q`).
 
-**Examples:**
+### 1. Set up the repo (once)
 
 ```bash
-bun gflows switch
-bun gflows switch feature/auth-refactor
-bun gflows switch dev --restore
-bun gflows switch main --clean
-bun gflows switch dev --destroy
-bun gflows -W feature/auth-refactor
+cd your-repo          # must already be a git repo with main
+# Hub: g  →  select “Initialize repo”
 ```
 
-**Flags:**
+| Long | Short |
+|------|-------|
+| `gflows init` | `g -I` |
+| `gflows init --no-push -y --script-alias g` | `g -I -P -y --script-alias g` |
 
+Creates `dev` from `main`. Optional: `--main`, `--dev`, `--remote` → writes `.gflows.json`.  
+`--script-alias g` adds `"g": "gflows"` to `package.json` (then `bun run g -- …` — note the `--`).
 
-| Flag           | Short | Description                                                                 |
-| -------------- | ----- | --------------------------------------------------------------------------- |
-| `--path <dir>` | `-C`  | Run as if in `<dir>`.                                                      |
-| `--branch <name>` | `-B` | Branch to switch to (alternative to positional).                           |
-| `--move`       | —     | Move current changes to the target branch; no prompt.                       |
-| `--restore`    | —     | Save for this branch; restore target's saved state (if any); no prompt.     |
-| `--clean`      | —     | Discard changes and switch clean at HEAD; no prompt.                       |
-| `--destroy`    | —     | Delete current branch and switch to target; no prompt (not main/dev).      |
-| `--cancel`     | —     | Abort switching; no prompt.                                                |
-| `--verbose`    | `-v`  | Verbose output.                                                            |
-| `--quiet`      | `-q`  | Minimal output (suppresses Clean warning about saved changes on target).  |
+### 2. Ship a feature
 
+**Easiest — hub (select + prompts):**
 
----
+```bash
+g                 # or gflows
+# select ★ Start new work  → answer type / name / push?
+# … edit, git commit …
+g                 # select Sync / Open PR / Finish when ready
+```
 
-### delete
+**Or type it** (`alias g=gflows`):
 
-Delete local workflow branch(es). Never deletes main/dev. TTY: picker; otherwise pass branch name(s).
+| Long | Short |
+|------|-------|
+| `gflows start feature add-login` | `g -S -f add-login` |
+| `gflows finish feature -y -P` | `g -F -f -y -P` |
 
-**Examples:**
+Optional: `gflows sync --force` · `gflows pr`  
+Finish **deletes** the branch by default (`-N` to keep). Use `-p` instead of `-P` to push.
 
 ```bash
-bun gflows delete
-bun gflows delete feature/old-spike
-bun gflows delete feature/one feature/two
+gflows viz    # branch map in the scrollback (no fullscreen menu)
 ```
 
-**Flags:**
-
+---
 
-| Flag           | Short | Description           |
-| -------------- | ----- | --------------------- |
-| `--path <dir>` | `-C`  | Run as if in `<dir>`. |
-| `--verbose`    | `-v`  | Verbose output.       |
-| `--quiet`      | `-q`  | Minimal output.       |
 
 
----
+## Everyday recipes
 
-### list
+Hub: `g` → select the action. Typed short form assumes `alias g=gflows`.
 
-List workflow branches (one per line). Filter by type; use `-r` to include remote (may run `git fetch`).
+**Feature → dev**
 
-**Examples:**
 
-```bash
-bun gflows list
-bun gflows list feature
-bun gflows list -r
-```
+| Long                            | Short              |
+| ------------------------------- | ------------------ |
+| `gflows start feature payments` | `g -S -f payments` |
+| `gflows finish feature -y -P`   | `g -F -f -y -P`    |
 
-**Flags:**
 
 
-| Flag               | Short | Description                                             |
-| ------------------ | ----- | ------------------------------------------------------- |
-| `--include-remote` | `-r`  | Include remote-tracking branches (may run `git fetch`). |
-| `--path <dir>`     | `-C`  | Run as if in `<dir>`.                                   |
-| `--dry-run`        | `-d`  | Log intended actions only.                              |
-| `--verbose`        | `-v`  | Verbose output.                                         |
-| `--quiet`          | `-q`  | Minimal output.                                         |
 
+**Production bugfix (from main)** — merges **main**, then **main → dev**
 
----
+| Long | Short |
+|------|-------|
+| `gflows start bugfix login-crash -o main` | `g -S -b login-crash -o main` |
+| `gflows finish bugfix -y -p` | `g -F -b -y -p` |
 
-### bump
+**Release** — tag on finish; merges **main**, then **main → dev**
 
-Bump or rollback version in `package.json` and `jsr.json` (monorepo: all discovered roots). No git operations. Direction: `up`|`down`; type: `patch`|`minor`|`major`. TTY: interactive; non-TTY: both required.
+| Long | Short |
+|------|-------|
+| `gflows bump up minor` | `g -U up minor` |
+| `gflows start release v1.4.0` | `g -S -r v1.4.0` |
+| `gflows finish release -y -p` | `g -F -r -y -p` |
 
-**Examples:**
+**Hotfix**
 
-```bash
-bun gflows bump up patch
-bun gflows bump down minor
-bun gflows bump --dry-run
-```
+| Long | Short |
+|------|-------|
+| `gflows start hotfix v1.4.1` | `g -S -x v1.4.1` |
+| `gflows finish hotfix -y -p` | `g -F -x -y -p` |
 
-**Flags:**
+**Stuck after a conflict** — fix files and `git add` before `continue`
 
+| Long | Short |
+|------|-------|
+| `gflows continue` | — |
+| `gflows abort` | — |
+| `gflows undo` | — |
+| `gflows doctor` | — |
 
-| Flag           | Short | Description                                   |
-| -------------- | ----- | --------------------------------------------- |
-| `--dry-run`    | `-d`  | Print old → new version only; no file writes. |
-| `--path <dir>` | `-C`  | Run as if in `<dir>`.                         |
-| `--verbose`    | `-v`  | Verbose output.                               |
-| `--quiet`      | `-q`  | Minimal output.                               |
 
 
 ---
 
-### status
 
-Shows current branch, type, base, merge target(s), ahead/behind. Read-only.
 
-**Examples:**
+## Hub controls
 
-```bash
-bun gflows status
-bun gflows -t
-```
+Bare `gflows` / `g` in a **TTY** opens the Ink hub (see [Way 1](#way-1--hub-recommended-for-humans)).
 
-**Flags:**
 
+| Input                                      | Action                                 |
+| ------------------------------------------ | -------------------------------------- |
+| ↑↓ Enter                                   | Select an action — Ink wizard if needed |
+| `/start` `/finish` `/sync` …               | Slash command; wizards stay in the hub |
+| `?`                                        | Shortcut help                          |
+| `q` / Esc / Ctrl+C                         | Quit                                   |
 
-| Flag           | Short | Description           |
-| -------------- | ----- | --------------------- |
-| `--path <dir>` | `-C`  | Run as if in `<dir>`. |
-| `--verbose`    | `-v`  | Verbose output.       |
-| `--quiet`      | `-q`  | Minimal output.       |
 
+**Non-TTY never opens the hub** — pass full args (CI/agents).
 
 ---
 
-### completion
 
-Prints completion script for bash/zsh/fish. See [Shell completion](#shell-completion).
 
-### help & version
-
-`bun gflows help` · `bun gflows -V`
+## Command cheat sheet
+
+
+| Command                       | What it does                                |
+| ----------------------------- | ------------------------------------------- |
+| *(bare)*                      | Fullscreen hub (TTY only)                   |
+| `init` `-I`                   | Ensure main; create dev                     |
+| `start` `-S`                  | Create typed branch                         |
+| `finish` `-F`                 | Merge + close (plan; delete default **on**) |
+| `sync`                        | Update branch from its base                 |
+| `pr`                          | Open PR/MR (`gh` / `glab`)                  |
+| `switch` `-W`                 | Switch branch                               |
+| `delete` `-L`                 | Delete local workflow branch(es)            |
+| `list` `-l`                   | List workflow branches                      |
+| `status` `-t`                 | Current branch flow info                    |
+| `viz`                         | Scrollback visual map                       |
+| `doctor`                      | Health checks                               |
+| `config`                      | `get` / `set` `.gflows.json`                |
+| `bump` `-U`                   | Version bump/rollback in package files      |
+| `continue` / `abort` / `undo` | Recovery                                    |
+| `schema` / `mcp`              | Agents & tooling                            |
+| `completion`                  | bash / zsh / fish                           |
+| `help` `-h` · `version` `-V`  | Meta                                        |
+
+
+
+
+### Short form (flags)
+
+With `alias g=gflows`, replace the words with flags:
+
+| Long | Short |
+|------|-------|
+| `init` | `-I` |
+| `start` | `-S` |
+| `finish` | `-F` |
+| `switch` | `-W` |
+| `delete` | `-L` |
+| `list` | `-l` |
+| `status` | `-t` |
+| `bump` | `-U` |
+| `feature` | `-f` |
+| `bugfix` | `-b` |
+| `chore` | `-c` |
+| `release` | `-r` |
+| `hotfix` | `-x` |
+| `spike` | `-e` |
+
+| Long | Short |
+|------|-------|
+| `gflows start feature payments` | `g -S -f payments` |
+| `gflows finish feature -y -P` | `g -F -f -y -P` |
+| `gflows start bugfix x -o main` | `g -S -b x -o main` |
+| `gflows start release v1.4.0` | `g -S -r v1.4.0` |
+| `gflows start hotfix v1.4.1` | `g -S -x v1.4.1` |
+| `gflows init -y -P` | `g -I -y -P` |
+| `gflows bump up minor` | `g -U up minor` |
+| `gflows bump down patch` | `g -U down patch` |
+
+### Flags you’ll use most
+
+| Long | Short |
+|------|-------|
+| `--yes` | `-y` |
+| `--push` | `-p` |
+| `--no-push` | `-P` |
+| `--no-delete` | `-N` |
+| `--delete` | `-D` |
+| `--from <branch>` | `-o <branch>` |
+| `--branch <name>` | `-B <name>` |
+| `--dry-run` | `-d` |
+| `--path <dir>` | `-C <dir>` |
+
+Also: `--json` · `--rebase` · `--squash` · `--preview` · `--bump`  
+Full list: `gflows help`.
+
+### Finish in one glance
+
+| Long | Short |
+|------|-------|
+| `gflows finish feature -y -P` | `g -F -f -y -P` |
+| `gflows finish feature -y -p` | `g -F -f -y -p` |
+| `gflows finish feature -y -P -N` | `g -F -f -y -P -N` |
+| `gflows finish feature --preview` | — |
+
+`-P` = no push · `-p` = push · `-N` = keep branch  
+Non-interactive finish **must** include `-p` or `-P`. Empty branch → exit `2`.
 
 ---
 
-## Configuration
 
-Optional. Override main, dev, remote, prefixes. Resolution: defaults → `.gflows.json` or `package.json` "gflows" key → CLI flags. Invalid config is ignored (`-v` for warning).
 
-### Example: `.gflows.json` (full)
+## Configuration
+
+Optional `.gflows.json` in the repo root (written by `init` when you pass names, or `gflows config set`):
 
 ```json
 {
@@ -568,125 +369,98 @@ Optional. Override main, dev, remote, prefixes. Resolution: defaults → `.gflow
 }
 ```
 
-### Example: minimal
-
-```json
-{ "main": "master", "dev": "develop" }
+```bash
+gflows config get main
+gflows config set dev develop
 ```
 
-Or in `package.json`: `"gflows": { "main": "main", "dev": "development", "remote": "upstream" }`
+CLI `--main` / `--dev` / `-R` override for a single run.
 
 ---
 
-## Scripting and CI
 
-Non-TTY: no pickers; pass branch names explicitly. Use `-y` to skip confirmations. Exit codes: 0 success, 1 validation, 2 Git/state. Use `-C <dir>` to run in another directory.
 
-```bash
-bun gflows finish feature -B feature/add-login --push -y
-bun gflows list feature | while read -r b; do echo "$b"; done
-bun gflows -C ./packages/api list
-```
+## Scripting & CI
 
----
+Rules of thumb:
 
-## Exit codes
+1. Always pass a **command** (no bare hub).
+2. Finish: `-y` and `-p` **or** `-P`.
+3. Prefer `--json` for parsers; hints go to **stderr**.
 
-| Code  | Meaning            | Typical causes                                                                                                                                                                                                      |
-| ----- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **0** | Success            | Command completed without error.                                                                                                                                                                                    |
-| **1** | Usage / validation | Missing type or name for `start`; invalid branch name or version; wrong/missing positionals when not TTY.                                                                                                           |
-| **2** | Git / system       | Not a repo; branch not found; dirty tree; merge conflict; rebase/merge in progress; detached HEAD; finish on main/dev; tag exists; push failed.                                                                   |
+| Long | Short |
+|------|-------|
+| `gflows init --no-push -y` | `g -I -P -y` |
+| `gflows start feature ci-check` | `g -S -f ci-check` |
+| `gflows finish feature -y -P` | `g -F -f -y -P` |
+| `gflows status --json` | `g -t --json` |
+| `gflows doctor --json` | — |
 
----
+**Exit codes:** `0` ok · `1` usage/validation · `2` git/system (conflict, dirty tree, empty finish, …)
 
-## Troubleshooting
+**Agents:** [AGENTS.md](AGENTS.md) · `gflows schema` · `gflows mcp`
 
-| Situation                                          | What to do                                                                                                                                                                  |
-| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **"Not a Git repository"**                         | Run from a directory that contains `.git`, or use `-C <path>` to point to the repo root.                                                                                    |
-| **"Working tree has uncommitted changes"**         | Commit or stash changes before `start`, or use `--force` (only when you intend to carry uncommitted work).                                                                  |
-| **"Merge conflict while merging into …"**          | Resolve conflicts in your working tree, then run `git add` and `git merge --continue` (or `git merge --abort` to cancel). Re-run `gflows finish` after resolving if needed. |
-| **"Tag v1.2.3 already exists"**                    | Use a new version for the release/hotfix, or delete/move the tag if you know what you’re doing. gflows does not overwrite tags.                                             |
-| **"Cannot finish the long-lived branch main/dev"** | You’re on main or dev. Checkout a workflow branch first, or use `-B <branch>` to finish another branch.                                                                     |
-| **"HEAD is detached"**                             | Checkout a branch (e.g. `git checkout dev`) before running `start` or `finish`.                                                                                             |
-| **"A rebase or merge is in progress"**             | Run `git rebase --abort` or `git merge --abort`, or complete the operation, then retry gflows.                                                                              |
-| **Picker not showing / "requires branch name"**    | Without a TTY, gflows does not show interactive pickers. Pass the branch name explicitly (e.g. `-B feature/xyz` or `gflows switch feature/xyz`).                            |
-| **Wrong remote or branch names**                   | Use `.gflows.json` or `package.json` "gflows" key, or `gflows init --main … --dev … --remote …`. Use `-R` for one-off remote override.                                      |
+---
 
 
-Use `-v` for verbose git commands and diagnostics.
 
----
+## Troubleshooting
 
-## Shell completion
 
-**Bash:**
+| Symptom                | Fix                                                    |
+| ---------------------- | ------------------------------------------------------ |
+| Hub / pickers missing  | Not a TTY — pass branch names and flags explicitly     |
+| Finish wants push flag | Add `-p` or `-P`                                       |
+| “Nothing to finish”    | Commit on the branch first (ahead of base must be > 0) |
+| Merge conflict         | Fix → `git add` → `gflows continue`                    |
+| Tag already exists     | Bump the version; gflows won’t overwrite tags          |
+| Can’t finish main/dev  | Finish a **workflow** branch (`-B feature/…`)          |
+| Detached HEAD          | `git checkout dev` (or another branch) first           |
+| Wrong base for bugfix  | `gflows start bugfix name -o main`                     |
+
 
 ```bash
-source <(bun gflows completion bash)
-echo 'source <(bun gflows completion bash)' >> ~/.bashrc
+gflows doctor
+gflows viz
 ```
 
-**Zsh:**
+---
+
 
-```bash
-source <(bun gflows completion zsh)
-echo 'source <(bun gflows completion zsh)' >> ~/.zshrc
-```
 
-**Fish:**
+## Shell completion
 
 ```bash
-bun gflows completion fish | source
-bun gflows completion fish > ~/.config/fish/completions/gflows.fish
+# bash
+eval "$(gflows completion bash)"
+
+# zsh
+eval "$(gflows completion zsh)"
+
+# fish
+gflows completion fish | source
 ```
 
 ---
 
+
+
 ## Publishing (maintainers)
 
-Internal script `scripts/publish.ts`: syncs version from package.json to jsr.json, then publishes to npm and/or JSR. Not in published package.
+CI: `[.github/workflows/publish.yml](.github/workflows/publish.yml)` — test, lint, publish npm + JSR on `main`.
 
 ```bash
-bun run publish:all
-bun run publish:all -- --dry-run
-bun run publish:npm
-bun run publish:jsr
-bun run publish:all -- --force
+bun run publish:all    # or publish:npm / publish:jsr
 ```
 
-### Typical release workflow
+Link the JSR package to this GitHub repo for provenance; set `NPM_TOKEN` in Actions secrets.
 
-1. Ensure you’re on **main** with a clean working tree (or use `--force` when intentional).
-2. Bump version and tag in Git yourself, or use gflows bump + your own commit:
-  ```bash
-   gflows bump up minor --dry-run   # confirm
-   gflows bump up minor
-   git add package.json jsr.json && git commit -m "chore: bump to 1.4.0"
-  ```
-3. Run the publish script:
-  ```bash
-   bun run publish:all -- --dry-run # verify
-   bun run publish:all
-  ```
-4. Optionally push main and tags:
-  ```bash
-   git push origin main --tags
-  ```
-
-**Version sync:** The script reads `version` from **package.json** and writes it to **jsr.json** before publishing so the two registries never drift. Use `**gflows bump`** to change the version; the script does not bump for you.
-
-### JSR score (100%)
-
-To get a 100% score on [JSR](https://jsr.io/@alialnaghmoush/gflows/score):
+---
 
-1. **Description** — Set in `jsr.json` (already added). If the score still shows 0/1, set the description in [package settings](https://jsr.io/@alialnaghmoush/gflows/settings) on JSR.
-2. **Runtime compatibility** — In [package settings](https://jsr.io/@alialnaghmoush/gflows/settings), open “Runtime compatibility” and mark at least **Bun** and **Node.js** (or others) as **Supported**.
-3. **Provenance** — The repo includes `[.github/workflows/publish.yml](.github/workflows/publish.yml)` (test, lint, then publish to npm and JSR). In JSR package settings, **link** the package to this GitHub repository. Add `NPM_TOKEN` in repo Secrets for npm. After that, pushes to `main` run CI and publish both registries; JSR records provenance.
 
----
 
 ## License
 
-See [LICENSE](LICENSE) in this repository.
+[MIT](LICENSE) · [Ali AlNaghmoush](https://github.com/alialnaghmoush) · [github.com/alialnaghmoush/gflows](https://github.com/alialnaghmoush/gflows)
+
+Changelog: [CHANGELOG.md](CHANGELOG.md)