docs: modernise README, add config ToC, fix outdated clean prompt (#225)

* docs: modernise README, add ToC to config reference, fix outdated clean prompt text

* docs: update tagline to highlight monorepo-like development

Author: LauJosefsen

README.md

@@ -2,7 +2,24 @@
 
 [![license](https://img.shields.io/github/license/cego/gitte)](https://github.com/cego/gitte)
 
-Gitte is a developer environment orchestration tool for teams working across many git repositories. It keeps all your repos in sync, runs startup checks to verify your local machine is ready, and executes ordered actions (build, up, down, etc.) across projects with dependency resolution.
+**Monorepo-like development across many git repositories — without the monorepo.**
+
+Gitte keeps all your repos in sync, runs startup checks to verify your local machine is ready, and executes ordered actions (build, up, down, …) across projects with dependency resolution and parallel execution.
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Commands](#commands)
+- [Configuration](#configuration)
+- [Environment variables](#environment-variables)
+- [Global flags](#global-flags)
+- [State and override files](#state-and-override-files)
+
+---
 
 ## Features
 
@@ -11,9 +28,12 @@ Gitte is a developer environment orchestration tool for teams working across man
 - **Ordered actions** — run commands across projects with `needs`-based dependency ordering and parallel execution
 - **Project toggles** — interactively enable/disable projects per machine
 - **Template inheritance** — share action definitions across similar projects
-- **Feature gates** — toggle environment-variable-based features per machine
+- **Feature gates** — toggle environment-variable-based behaviours per machine
 - **Auto-discovery** — discover and sync repositories from GitLab groups or GitHub orgs
-- **TTY-aware output** — spinner TUI in a terminal, structured plain-text output in CI/non-TTY
+- **Clean operations** — remove untracked files, reset local changes, or check out default branches across all repos
+- **TTY-aware output** — animated spinner TUI in a terminal, structured plain-text output in CI / non-TTY
+
+---
 
 ## Installation
 
@@ -45,9 +65,11 @@ Requires Go 1.24 or later.
 go install github.com/cego/gitte@latest
 ```
 
+---
+
 ## Quick start
 
-Create a `.gitte.yml` in the root of your workspace:
+**1.** Create a `.gitte.yml` in your workspace root:
 
 ```yaml
 startup:
@@ -69,59 +91,73 @@ projects:
           local: ["docker", "compose", "down"]
 ```
 
-Then run:
+**2.** Run the full pipeline:
 
 ```bash
 gitte run up local
 ```
 
-Gitte will run startup checks, pull all repos, then execute the `up` action for group `local` on all enabled projects.
+Gitte will run startup checks, pull all repos, then execute the `up` action for group `local` across all enabled projects.
+
+---
 
 ## Commands
 
+### Overview
+
 | Command | Description |
 |---------|-------------|
 | `gitte run [action] [group] [projects]` | Full pipeline: startup checks → git sync → actions |
 | `gitte actions [action] [group] [projects]` | Run actions only (skip startup and git sync) |
 | `gitte startup` | Run startup checks only |
 | `gitte gitops [--discover]` | Clone/pull all repos; `--discover` also fetches from configured sources |
 | `gitte list` | List all projects and their available actions |
-| `gitte toggle` | Interactive TUI to enable/disable projects |
-| `gitte features list` | List all feature gates and their enabled state |
-| `gitte features enable <gate>` | Enable a feature gate |
-| `gitte features disable <gate>` | Disable a feature gate |
-| `gitte sources` | Manage local discovery sources (GitLab groups / GitHub orgs) |
-| `gitte token set <gitlab\|github> <host>` | Store an API token in the system keyring |
+| `gitte toggle` | Interactive TUI to enable/disable projects per machine |
+| `gitte clean <subcommand>` | Clean up repos (see below) |
+| `gitte features list\|enable\|disable` | Manage feature gates |
+| `gitte sources` | Manage discovery sources (GitLab groups / GitHub orgs) |
+| `gitte token set\|get\|delete\|list` | Store API tokens in the system keyring |
 | `gitte validate` | Validate config: schema, cycles, missing references |
-| `gitte clean [flags]` | Report repo state (see below) |
 
 ### Argument syntax
 
 Arguments to `run` and `actions` are positional: `action [group] [projects]`.
 
 ```bash
-gitte run up                      # up action, all groups, all enabled projects
-gitte run up local                # up action, group local, all enabled projects
-gitte run up local myservice      # up action, group local, project myservice only
+gitte run up                         # up action, all groups, all enabled projects
+gitte run up local                   # up action, group local, all enabled projects
+gitte run up local myservice         # up action, group local, project myservice only
 gitte run up local frontend+backend  # up action, group local, projects frontend and backend
-gitte run up+build                # run up then build, all groups, all enabled projects
+gitte run up+build                   # run up then build, all groups, all enabled projects
 ```
 
 Use `*` or `all` as a wildcard. Combine multiple values with `+`.
 
-### clean subcommands
+### gitte clean
+
+Destructive cleanup operations across all configured repositories. Each subcommand shows a live progress TUI while running.
 
 ```bash
 gitte clean untracked       # remove untracked files (git clean -fdx)
-gitte clean local-changes   # reset repos with local changes (prompts first)
+gitte clean local-changes   # reset repos with local changes (prompts before acting)
 gitte clean master          # checkout the default branch in all repos
 gitte clean all             # run all three in sequence
 ```
 
+`gitte clean local-changes` lists affected repos and prompts:
+
+```
+Reset [a]ll / [i]ndividually / [C]ancel?
+```
+
+---
+
 ## Configuration
 
 See [docs/config.md](./docs/config.md) for the full configuration reference.
 
+---
+
 ## Environment variables
 
 | Variable | Default | Description |
@@ -132,6 +168,8 @@ See [docs/config.md](./docs/config.md) for the full configuration reference.
 | `GITTE_NO_REBASE` | `false` | Set to `true` to skip auto-rebase onto default branch |
 | `GITTE_MAX_TASK_PARALLELIZATION` | unlimited | Cap the number of concurrent tasks |
 
+---
+
 ## Global flags
 
 ```
@@ -140,10 +178,10 @@ See [docs/config.md](./docs/config.md) for the full configuration reference.
 --no-tty           Force plain-text output
 ```
 
-## State file
+---
 
-Gitte stores per-machine state (project toggles, feature gate overrides, remote config cache) in `.gitte-state.yml` next to your `.gitte.yml`. This file is automatically added to `.gitignore`.
+## State and override files
 
-## Override file
+**`.gitte-state.yml`** — stores per-machine state: project toggles, feature gate overrides, and remote config cache. Gitte automatically adds this file to `.gitignore`. Do not commit it.
 
-If `.gitte-override.yml` exists alongside `.gitte.yml`, it is deep-merged on top. Use this for local machine overrides that should not be committed.
+**`.gitte-override.yml`** — deep-merged on top of `.gitte.yml` when present. Use this for local machine-specific settings that should not be committed (e.g. `sources` added via `gitte sources add`).

docs/commands.md

@@ -107,7 +107,7 @@ gitte validate
 
 ## gitte clean
 
-Destructive cleanup operations on project repositories.
+Destructive cleanup operations on project repositories. All subcommands show a live progress TUI while running (plain-text lines in non-TTY mode).
 
 ```bash
 gitte clean untracked       # run git clean -fdx in every repo
@@ -116,10 +116,13 @@ gitte clean master          # run git checkout <default_branch> in every repo
 gitte clean all             # run untracked → local-changes → master in sequence
 ```
 
-`gitte clean local-changes` shows all affected repos, then asks:
-`Reset all, handle individually, or cancel? [all/individually/cancel]`
+`gitte clean local-changes` shows all affected repos, then prompts for a single keypress:
 
-If `individually`, you are prompted per repo: `Reset <name>? [y/N]`
+```
+Reset [a]ll / [i]ndividually / [C]ancel?
+```
+
+If `i` (individually), you are prompted per repo with a single keypress: `Reset <name>? [y/N]`
 
 Operations run on all configured projects regardless of toggle state.
 

docs/config.md

@@ -6,6 +6,22 @@ An optional `.gitte-override.yml` in the same directory is deep-merged on top, u
 
 ---
 
+## Table of contents
+
+- [Top-level structure](#top-level-structure)
+- [startup](#startup)
+- [projects](#projects)
+- [templates](#templates)
+- [groupIncludes](#groupincludes)
+- [retry](#retry)
+- [actionOverride](#actionoverride)
+- [searchFor](#searchfor)
+- [feature\_gates](#feature_gates)
+- [sources](#sources)
+- [Remote configuration](#remote-configuration)
+
+---
+
 ## Top-level structure
 
 ```yaml