From 8650b71c3cb7fb2667210125bd620568638546a6 Mon Sep 17 00:00:00 2001
From: MatMoul <matmoul@gmail.com>
Date: Mon, 1 Jun 2026 00:03:59 +0200
Subject: [PATCH] docs: align README with current script behavior

Update the usage, feature summary, and notes to reflect known_hosts support, current option flags, and the sample configuration layout.
---
 .memory/project.md |  4 ++--
 README.md          | 57 ++++++++++++++++++++++++++++++----------------
 2 files changed, 40 insertions(+), 21 deletions(-)

diff --git a/.memory/project.md b/.memory/project.md
index 54c84f3..16c5f8a 100644
--- a/.memory/project.md
+++ b/.memory/project.md
@@ -5,6 +5,6 @@
 - Main entry point: `mtm-ssh-menu`
 - Configuration: `~/.config/mtm-ssh-menu/global.yaml` and `hosts/*.yaml` by default.
 - Dependencies: `bash`, `ssh`, `fzf`, `jq`, `yq`.
-- Sample config is stored in `sample-config/`.
+- Sample config is stored in `sample-config/` and mirrors current script behavior.
 - Documentation language: English.
-- Current task focus: keep README aligned with the working script and sample configuration.
+- Current task focus: keep README and memory aligned with the working script and sample configuration.
diff --git a/README.md b/README.md
index fdca782..1f50f77 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,17 @@
 # mtm-ssh-menu
 
-A small Bash utility to browse SSH targets from YAML configuration and connect to them with `fzf`.
+A Bash SSH target picker built around `fzf` and YAML configuration.
 
-## Features
+## What it does
 
-- Interactive selection with `fzf`
-- Global defaults for SSH user, port, and jump hosts
-- Per-host overrides in grouped YAML files
-- Support for jump hosts via named aliases
-- Simple, dependency-light Bash script
+- Lists SSH targets from grouped YAML files
+- Supports global defaults for user, port, and jump hosts
+- Supports per-host overrides
+- Can also browse entries from `~/.ssh/known_hosts`
+- Launches `ssh` directly from the selected entry
 
 ## Requirements
 
-- `bash`
 - `ssh`
 - `fzf`
 - `jq`
@@ -21,13 +20,14 @@ A small Bash utility to browse SSH targets from YAML configuration and connect t
 ## Usage
 
 ```bash
-./mtm-ssh-menu [--config-dir DIR]
+./mtm-ssh-menu [--config-dir DIR] [-k [user]]
 ```
 
 Options:
 
-- `--help`: show help
+- `-h`, `--help`: show help
 - `--config-dir DIR`: use a custom configuration directory
+- `-k`, `--known-hosts [user]`: include hosts from `~/.ssh/known_hosts`
 
 By default, the script reads configuration from:
 
@@ -59,6 +59,27 @@ servers:
     host: 192.168.10.11
     user: dev
     port: 2222
+
+  - name: web-1
+    aliases:
+      - frontend
+      - ui
+    host: 192.168.10.12
+    user: dev
+    port: 22
+```
+
+### `hosts/prod.yaml`
+
+```yaml
+group: prod
+servers:
+  - name: web-1
+    aliases:
+      - frontend
+      - web
+    host: web-1.prod.internal
+    jump_host: office
 ```
 
 Each host entry can define:
@@ -70,19 +91,17 @@ Each host entry can define:
 - `port`
 - `jump_host`
 
-## Example workflow
-
-1. Create the config directory.
-2. Add `global.yaml` and one or more files under `hosts/`.
-3. Run the script.
-4. Select a target in the menu and connect.
-
 ## Sample configuration
 
 A complete sample configuration is available in `sample-config/`.
 
 ## Notes
 
-- The script requires `yq`, `jq`, `ssh`, and `fzf` to be installed.
-- Jump hosts are resolved by name from `global.yaml`.
+- `jump_host` values are resolved by name from `global.yaml`.
 - If a host does not define a user or port, global defaults are used.
+- `default_options` is present in the config but not consumed by the current script.
+- The sample config includes `ssh_options` in one file, but the current script does not consume it yet.
+- When `-k` is used, entries from `known_hosts` are shown with the selected user or `root` by default.
+- `known_hosts` entries use port `22`.
+- The script uses strict Bash mode (`set -euo pipefail`).
+- The script name shown in usage is `sshm`, while the repository file is `mtm-ssh-menu`.