From 3b6f46b9f64d700908af98109ed816ece3598571 Mon Sep 17 00:00:00 2001
From: NicolasGB <ngou0210@gmail.com>
Date: Thu, 12 Mar 2026 17:58:23 +0100
Subject: [PATCH] docs(readme): Document the new `editor.auto_insert` config
 option

---
 README.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/README.md b/README.md
index c873709..e463990 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,7 @@
   - [Diff Commands](#diff-commands)
 - [Default Config](#default-config)
 - [Configuration Examples](#configuration-examples)
+  - [Editor Options](#editor-options)
   - [New Command Options](#new-command-options)
   - [Push Command Options](#push-command-options)
   - [Bookmark Management Command Options](#bookmark-management-command-options)
@@ -397,6 +398,13 @@ The plugin also provides `:Jdiff`, `:Jvdiff`, and `:Jhdiff` commands for diffing
     snacks = {}
   },
 
+  -- Configure editor behavior for describe/commit buffers
+  editor = {
+    -- When true, automatically enter insert mode only if the description is empty.
+    -- If a description already exists, stay in normal mode.
+    auto_insert = false,
+  },
+
   -- Customize syntax highlighting colors for the describe buffer
   highlights = {
     editor = {
@@ -563,6 +571,36 @@ require("jj").setup({
 })
 ```
 
+### Editor Options
+
+The top-level `editor` config controls behavior for the describe/commit editor buffers.
+
+#### `editor.auto_insert`
+
+When `auto_insert = true`, `jj.nvim` automatically enters Insert mode when opening a describe or commit buffer **only if the description is empty**.
+
+If the change already has a description, the buffer stays in Normal mode so you can review or edit the existing message without being dropped straight into Insert mode.
+
+Default:
+
+```lua
+require("jj").setup({
+  editor = {
+    auto_insert = false,
+  }
+})
+```
+
+Enable smart auto-insert:
+
+```lua
+require("jj").setup({
+  editor = {
+    auto_insert = true,
+  }
+})
+```
+
 ### Highlight Customization
 
 The `highlights` option allows you to customize the colors used in the describe buffer's file status display. Each highlight accepts standard Neovim highlight attributes: