From ab7409fb86f78259cb2dad1abb51bfa1f71dbb7d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Wojciech=20P=C4=99dzim=C4=85=C5=BC?=
 <wojciech.pedzimaz@techmo.pl>
Date: Wed, 6 May 2026 14:14:23 +0200
Subject: [PATCH] =?UTF-8?q?docs(readme):=20fix=20Update=20section=20?=
 =?UTF-8?q?=E2=80=94=20add=20git=20pull=20step=20and=20clarify=20update.sh?=
 =?UTF-8?q?=20scope?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md | 12 ++++++++++++
 README.md    | 31 +++++++++++++++++++++++++++++++
 VERSION      |  2 +-
 3 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 257275d..ccb6ce0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.3] - 2026-05-06
+
+### Fixed
+- `README.md`: Update section now shows the correct two-step flow — `git pull`
+  first (to get config file changes), then `./update.sh` (to upgrade tool binaries
+  and plugins). The previous single-command version was misleading: `update.sh`
+  does not pull the dotfiles repo and does not install tools added in newer
+  versions. Also documents `get.sh` as the simpler alternative and `--check` mode.
+- `README.md`: Machine-specific config section now lists `~/.gitconfig.local`
+  alongside `~/.zshrc.local` and `~/.p10k.zsh`, with a pointer to
+  `git/.gitconfig.local.example`.
+
 ## [1.6.2] - 2026-05-06
 
 ### Fixed
diff --git a/README.md b/README.md
index 70e9049..84dc4a4 100644
--- a/README.md
+++ b/README.md
@@ -227,10 +227,39 @@ docker run --rm -it -v "$PWD":/root/dotfiles my-devenv bash
 
 ## Update
 
+**Step 1 — pull the dotfiles repo** (config files: `.zshrc`, `init.lua`, `.tmux.conf.local`, scripts):
+
+```bash
+cd ~/.dotfiles && git pull
+```
+
+Or use `get.sh`, which auto-stashes local modifications, pulls, then restores them:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/YASoftwareDev/dotfiles/master/get.sh | bash -s -- workstation
+```
+
+**Step 2 — update tool binaries and plugins:**
+
 ```bash
 cd ~/.dotfiles && ./update.sh
 ```
 
+`update.sh` upgrades: system packages (apt), oh-my-zsh, tmux plugins, zsh plugins,
+fzf, ripgrep, fd, shellcheck, zoxide, delta, eza, uv/uvx, ruff, neovim, cheat, xcape.
+
+> **Note:** `update.sh` only upgrades tools that are already installed. If a new
+> version of the dotfiles adds a tool, re-run `install.sh` to install it:
+> ```bash
+> bash ~/.dotfiles/install.sh workstation
+> ```
+
+To check what would be updated without making changes:
+
+```bash
+cd ~/.dotfiles && ./update.sh --check
+```
+
 ## Repository structure
 
 ```
@@ -436,4 +465,6 @@ cmake and git accept an optional version argument: `./scripts/install-cmake.sh 4
 Files not tracked by git, loaded if present:
 - `~/.zshrc.local` — machine-specific zsh overrides (sourced at end of `.zshrc`)
 - `~/.p10k.zsh` — powerlevel10k prompt config (generated by `p10k configure`)
+- `~/.gitconfig.local` — git identity and credential helpers (included at end of `.gitconfig`);
+  copy `git/.gitconfig.local.example` for the expected format
 
diff --git a/VERSION b/VERSION
index fdd3be6..266146b 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.6.2
+1.6.3