docscribe 1.4.2 → 1.5.1

data/README.md

@@ -1,10 +1,18 @@
-# Docscribe
-
-[![Gem Version](https://img.shields.io/gem/v/docscribe.svg)](https://rubygems.org/gems/docscribe)
-[![RubyGems Downloads](https://img.shields.io/gem/dt/docscribe.svg)](https://rubygems.org/gems/docscribe)
-[![CI](https://github.com/unurgunite/docscribe/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/unurgunite/docscribe/actions/workflows/ci.yml)
-[![License](https://img.shields.io/github/license/unurgunite/docscribe.svg)](https://github.com/unurgunite/docscribe/blob/master/LICENSE.txt)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7-blue.svg)](#installation)
+<p align="center">
+  <img src="assets/icons/icon_128x128.png" alt="Docscribe logo" width="128">
+</p>
+
+<h1 align="center">DocScribe</h1>
+
+<p align="center">
+<a href="https://rubygems.org/gems/docscribe"><img src="https://img.shields.io/gem/v/docscribe.svg" alt="Gem Version"></a>
+<a href="https://rubygems.org/gems/docscribe"><img src="https://img.shields.io/gem/dt/docscribe.svg" alt="RubyGems Downloads"></a>
+<a href="https://github.com/unurgunite/docscribe/actions/workflows/ci.yml"><img src="https://github.com/unurgunite/docscribe/actions/workflows/ci.yml/badge.svg?branch=master" alt="CI"></a>
+<a href="https://github.com/unurgunite/docscribe/blob/master/LICENSE.txt"><img src="https://img.shields.io/github/license/unurgunite/docscribe.svg" alt="License"></a>
+<a href="#installation"><img src="https://img.shields.io/badge/ruby-%3E%3D%202.7-blue.svg" alt="Ruby"></a>
+<a href="https://marketplace.visualstudio.com/items?itemName=unurgunite.docscribe-vscode"><img src="https://img.shields.io/badge/VS%20Code-plugin-blue?logo=visualstudiocode" alt="VS Code"></a>
+<a href="https://plugins.jetbrains.com/plugin/32349-docscribe"><img src="https://img.shields.io/badge/RubyMine-plugin-green?logo=jetbrains" alt="RubyMine"></a>
+</p>
 
 ![Docscribe before/after demo](docs/image.png)
 
@@ -29,6 +37,10 @@ returns), and respects Ruby visibility semantics — without using YARD to parse
     - `attr_reader` / `attr_writer` / `attr_accessor`;
     - `Struct.new` declarations in both constant-assigned and class-based styles.
 
+> [!NOTE]
+> Docscribe is under **active development**. If you run into any edge cases or have ideas for improvement, feel free to
+> [open an issue](https://github.com/unurgunite/docscribe/issues/new) or submit a pull request.
+
 Common workflows:
 
 - Inspect what safe doc updates would be applied: `docscribe lib`
@@ -38,21 +50,49 @@ Common workflows:
 - Use RBS signatures when available: `docscribe -a --rbs --sig-dir sig lib`
 - Use Sorbet signatures when available: `docscribe -a --sorbet --rbi-dir sorbet/rbi lib`
 
+## Quick start
+
+```shell
+# Check what safe doc updates would be applied
+docscribe lib
+
+# Apply safe updates (insert missing docs, merge existing)
+docscribe -a lib
+
+# Rebuild all doc blocks aggressively
+docscribe -A lib
+```
+
+> [!TIP]
+> See [CLI](#cli) for all options and [Update strategies](#update-strategies) for the
+> difference between safe and aggressive modes.
+>
+> Want IDE integration? Check out
+> the [VS Code](https://marketplace.visualstudio.com/items?itemName=unurgunite.docscribe-vscode)
+> and [RubyMine](https://plugins.jetbrains.com/plugin/32349-docscribe) plugins.
+
 ## Contents
 
 * [Docscribe](#docscribe)
+    * [Quick start](#quick-start)
     * [Contents](#contents)
     * [Installation](#installation)
-    * [Quick start](#quick-start)
     * [Architecture](#architecture)
         * [Data flow](#data-flow)
     * [CLI](#cli)
+        * [Exit codes](#exit-codes)
         * [Options](#options)
         * [Examples](#examples)
+        * [`docscribe sigs` — check RBS signature coverage](#docscribe-sigs--check-rbs-signature-coverage)
+        * [`docscribe rbs` — generate RBS from YARD](#docscribe-rbs--generate-rbs-from-yard)
+        * [`docscribe update_types` — two-pass type-aware documentation update](#docscribe-update_types--two-pass-type-aware-documentation-update)
+        * [`docscribe check_for_comments` — find placeholder documentation](#docscribe-check_for_comments--find-placeholder-documentation)
+        * [`docscribe server` — persistent daemon mode](#docscribe-server--persistent-daemon-mode)
     * [Update strategies](#update-strategies)
         * [Safe strategy](#safe-strategy)
         * [Aggressive strategy](#aggressive-strategy)
         * [Output markers](#output-markers)
+    * [Tips & tricks](#tips--tricks)
     * [Parser backend (Parser gem vs Prism)](#parser-backend-parser-gem-vs-prism)
     * [External type integrations (optional)](#external-type-integrations-optional)
         * [RBS](#rbs)
@@ -77,6 +117,7 @@ Common workflows:
         * [Idempotency](#idempotency)
         * [Plugin examples](#plugin-examples)
     * [Configuration](#configuration)
+        * [Anonymous block parameters](#anonymous-block-parameters)
         * [Filtering](#filtering)
         * [`attr_*` example](#attr_-example)
         * [`Struct.new` examples](#structnew-examples)
@@ -86,14 +127,17 @@ Common workflows:
         * [Param tag style](#param-tag-style)
         * [Create a starter config](#create-a-starter-config)
         * [Generate a plugin skeleton](#generate-a-plugin-skeleton)
+        * [Full configuration reference](#full-configuration-reference)
     * [CI integration](#ci-integration)
     * [Comparison to YARD's parser](#comparison-to-yards-parser)
-    * [Mermaid Architecture Reference](#mermaid-architecture-reference)
-        * [Data flow](#data-flow)
     * [Limitations](#limitations)
     * [Roadmap](#roadmap)
+    * [Editor Integration](#editor-integration)
+        * [VS Code](#vs-code)
+        * [RubyMine](#rubymine)
     * [Contributing](#contributing)
     * [Discussion & Community](#discussion--community)
+    * [Logo Attribution](#logo-attribution)
     * [License](#license)
 
 ## Installation
@@ -118,102 +162,16 @@ gem install docscribe
 
 Requires Ruby 2.7+.
 
-## Quick start
-
-Given code:
-
-```ruby
-class Demo
-  def foo(a, options: {})
-    42
-  end
-
-  def bar(verbose: true)
-    123
-  end
-
-  private
-
-  def self.bump
-    :ok
-  end
-
-  class << self
-    private
-
-    def internal; end
-  end
-end
-```
-
-Run:
-
-```shell
-echo "...code above..." | docscribe --stdin
-```
-
-Output:
-
-```ruby
-class Demo
-  # +Demo#foo+ -> Integer
-  #
-  # Method documentation.
-  #
-  # @param [Object] a Param documentation.
-  # @param [Hash] options Param documentation.
-  # @return [Integer]
-  def foo(a, options: {})
-    42
-  end
-
-  # +Demo#bar+ -> Integer
-  #
-  # Method documentation.
-  #
-  # @param [Boolean] verbose Param documentation.
-  # @return [Integer]
-  def bar(verbose: true)
-    123
-  end
-
-  private
-
-  # +Demo.bump+ -> Symbol
-  #
-  # Method documentation.
-  #
-  # @return [Symbol]
-  def self.bump
-    :ok
-  end
-
-  class << self
-    private
-
-    # +Demo.internal+ -> Object
-    #
-    # Method documentation.
-    #
-    # @private
-    # @return [Object]
-    def internal; end
-  end
-end
-```
-
-> [!NOTE]
-> - The tool inserts doc headers before method headers and preserves everything else.
-> - For methods with a leading Sorbet `sig`, docs are inserted above the first `sig`.
-> - Class methods show with a dot (`+Demo.bump+`, `+Demo.internal+`).
-> - Methods inside `class << self` under `private` are marked `@private`.
-
 ## Architecture
 
-Docscribe is organized into seven subsystems. The CLI layer receives user input and orchestrates configuration loading,
-then delegates to the core engine which parses source code, collects methods (using an AST walker), builds YARD doc
-lines — combining heuristic type inference, external RBS/Sorbet signatures, and plugin output — and finally rewrites the
-source via a strategy (safe merge or aggressive replace).
+Docscribe is organized into several subsystems. The CLI layer receives user input and orchestrates configuration
+loading, then delegates to the core engine which parses source code, collects methods (using an AST walker), builds YARD
+doc lines — combining heuristic type inference, external RBS/Sorbet signatures, and plugin output — and finally rewrites
+the source via a strategy (safe merge or aggressive replace).
+
+In server mode, a persistent daemon (`docscribe server`) keeps the runtime loaded and caches parsed results across
+invocations via an LRU cache, enabling near-instant repeated checks for IDE plugins. A thin client (`docscribe-client`)
+provides minimal-overhead socket communication without loading the full gem.
 
 ```mermaid
 flowchart TB
@@ -223,6 +181,9 @@ flowchart TB
         Options["CLI::Options\nARGV parsing\n(mode, strategy,\nfilters, flags)"]
         InitCmd["CLI::Init\ndocscribe init\nGenerate config"]
         GenCmd["CLI::Generate\ndocscribe generate\nScaffold plugins"]
+        SigsCmd["CLI::Sigs\ndocscribe sigs\nCheck RBS coverage"]
+        RbsGenCmd["CLI::RbsGen\ndocscribe rbs\nGenerate RBS from YARD"]
+        SarifFormatter["CLI::Formatters::Sarif\nSARIF 2.1 JSON\nCode Scanning"]
         ConfigBuilder["CLI::ConfigBuilder\nApply CLI overrides\nto config"]
     end
 
@@ -244,10 +205,10 @@ flowchart TB
     end
 
     subgraph Core["Core Engine"]
-        InlineRewriter["InlineRewriter\n· parse → collect\n· deduplicate → dispatch\n· rewrite"]
+        InlineRewriter["InlineRewriter\n· parse -> collect\n· deduplicate -> dispatch\n· rewrite"]
         Collector["Collector\n< Parser::AST::Processor\nAST walker\n· find methods/attrs\n· track visibility\n· track containers"]
         DocBuilder["DocBuilder\nGenerate YARD doc lines\n· combine inference\n· external signatures\n· plugin tags"]
-        DocBlock["DocBlock\nSafe strategy:\nparse → merge → sort\nexisting doc blocks"]
+        DocBlock["DocBlock\nSafe strategy:\nparse -> merge -> sort\nexisting doc blocks"]
         SourceHelpers["SourceHelpers\nPosition/range\nutilities"]
     end
 
@@ -256,36 +217,57 @@ flowchart TB
         Params["Infer::Params\nParameter type\nfrom name + default"]
         Returns["Infer::Returns\nReturn type\nfrom method body"]
         Raises["Infer::Raises\n@raise tags\nfrom raise/rescue"]
-        Literals["Infer::Literals\nAST literal →\ntype string"]
-        Names["Infer::Names\n:const node →\nFQN string"]
+        Literals["Infer::Literals\nAST literal ->\ntype string"]
+        Names["Infer::Names\n:const node ->\nFQN string"]
         ASTWalk["Infer::ASTWalk\nRecursive DFS\nAST traversal"]
     end
 
     subgraph Plugins["Plugin System"]
         PluginModule["Plugin\nTag/Collector\ndispatch"]
-        Registry["Plugin::Registry\nGlobal registry\n· register → route\n· tag_entries\n· collector_entries"]
-        TagPlugin["Base::TagPlugin\nOverride #call(context)\n→ Array<Tag>"]
-        CollectorPlugin["Base::CollectorPlugin\nOverride #collect(ast, buffer)\n→ Array<Hash>"]
+        Registry["Plugin::Registry\nGlobal registry\n· register -> route\n· tag_entries\n· collector_entries"]
+        TagPlugin["Base::TagPlugin\nOverride #call(context)\n-> Array<Tag>"]
+        CollectorPlugin["Base::CollectorPlugin\nOverride #collect(ast, buffer)\n-> Array<Hash>"]
         TagValue["Plugin::Tag\nStruct (name, text, types)"]
         Context["Plugin::Context\nMethod snapshot struct"]
     end
 
     subgraph Types["External Type System"]
         ProviderChain["ProviderChain\nComposite:\nquery in order\nfirst match wins"]
-        RBSProvider["RBS::Provider\n.rbs files\n→ RBS lib"]
-        RBSFormatter["RBS::TypeFormatter\nRBS type →\nYARD type string"]
+        RBSProvider["RBS::Provider\n.rbs files\n-> RBS lib"]
+        RBSFormatter["RBS::TypeFormatter\nRBS type ->\nYARD type string"]
         RBSCollection["RBS::CollectionLoader\nrbs_collection\n.lock.yaml"]
         SorbetBase["Sorbet::BaseProvider\nRBS::Prototype::RBI\nbridge"]
         SorbetSource["Sorbet::SourceProvider\nInline sig{}\ndeclarations"]
         SorbetRBI["Sorbet::RBIProvider\n.rbi files\ndirectories"]
     end
 
+    subgraph YardTypes["YARD Type Parser"]
+        YParser["Yard::Parser\nParse YARD type\nstrings -> AST"]
+        YFormatter["Yard::Formatter\nYARD AST ->\nRBS string"]
+        YTypes["Yard::Types\n9 AST node types\n(Named, Generic, etc.)"]
+    end
+
+    subgraph Server["Server / Daemon"]
+        ThinClient["exe/docscribe-client\nThin client\n· socket send/receive\n· no gem load"]
+        ServerDaemon["Server::Daemon\nSocket listener\n· check / fix / shutdown\n· JSON-RPC 2.0"]
+        Cache["Docscribe::LRUCache\nFile result cache\n(max 1000, by mtime)"]
+    end
+
     Exe --> Run
+    Exe --> ServerDaemon
+    ThinClient --> ServerDaemon
+    ServerDaemon --> ConfigClass
+    ServerDaemon --> Cache
+    ServerDaemon --> InlineRewriter
     Run --> Options
     Run --> InitCmd
     Run --> GenCmd
+    Run --> SigsCmd
+    Run --> RbsGenCmd
+    Run --> SarifFormatter
     Run --> ConfigBuilder
     ConfigBuilder --> ConfigClass
+    ConfigBuilder --> ServerDaemon
     ConfigClass --> Defaults
     ConfigClass --> Loader
     ConfigClass --> Emit
@@ -325,13 +307,35 @@ flowchart TB
     TagPlugin --> Context
     InlineRewriter --> DocBlock
     InlineRewriter --> SourceHelpers
+    RbsGenCmd --> ParsingModule
+    RbsGenCmd --> YParser
+    YParser --> YTypes
+    YParser --> YFormatter
 ```
 
 ### Data flow
 
 ```mermaid
 flowchart LR
-    Input["Source files\n(.rb)"] --> Parse["Parsing.parse_buffer\nParser gem / Prism"]
+    subgraph Entry["Entry Points"]
+        Direct["docscribe lib\n(no --server)"]
+        ViaServer["docscribe --server\nor docscribe-client"]
+    end
+
+    subgraph Daemon["Server Daemon (Unix Socket)"]
+        Socket["Daemon#listen_loop\nJSON-RPC 2.0 dispatch"]
+        CacheCheck{"File cached &\nmtime fresh?"}
+        CacheStorage["LRUCache\n(1000 entries)"]
+        ApplyOverrides["apply_cli_overrides\n(reset on nil)"]
+    end
+
+    ViaServer --> Socket
+    Socket --> ApplyOverrides
+    ApplyOverrides --> CacheCheck
+    CacheCheck -->|Hit| Socket
+    CacheCheck -->|Miss| Parse
+    Direct --> Parse
+    Parse["Parsing.parse_buffer\nParser gem / Prism"]
     Parse --> AST["AST + Comments"]
     AST --> Collect["Collector.process\n· Find methods\n· Track visibility\n· Find attr_*"]
     AST --> CollectPlugins["CollectorPlugin#collect\n· Custom AST walks\n· Non-standard constructs"]
@@ -348,25 +352,42 @@ flowchart LR
     ResultDoc --> Strategy{"Strategy?"}
     Strategy -->|Safe| Merge["DocBlock.merge\npreserve + append + sort"]
     Strategy -->|Aggressive| Replace["Replace entirely"]
-    Merge --> Rewritten["Rewriter#process\n→ rewritten source"]
+    Merge --> Rewritten["Rewriter#process\n-> rewritten source"]
     Replace --> Rewritten
-    Rewritten --> Output["Modified .rb file\n/ STDOUT"]
+    Rewritten --> Result["Result / response"]
+    Rewritten --> CacheStorage
+    CacheStorage --> Socket
+    Result -->|Direct mode| Output["Modified .rb file / STDOUT"]
+    Result -->|Server mode| Socket
 ```
 
 ## CLI
 
 ```shell
 docscribe [options] [files...]
+docscribe init [options]
+docscribe generate [type] [name] [options]
+docscribe sigs [options] [files...]
+docscribe rbs [options] [files...]
+docscribe update_types [directory]
+docscribe check_for_comments [paths...]
+docscribe server [start|status|stop] [options]
 ```
 
 Docscribe has three main ways to run:
 
-- **Inspect mode** (default): checks what safe doc updates would be applied and exits non-zero if files need changes.
+- **Inspect mode** (default): checks what safe doc updates would be applied and exits 1 if files need changes.
 - **Safe autocorrect** (`-a`, `--autocorrect`): writes safe, non-destructive updates in place.
 - **Aggressive autocorrect** (`-A`, `--autocorrect-all`): rewrites existing doc blocks more aggressively.
 - **STDIN mode** (`--stdin`): reads Ruby source from STDIN and prints rewritten source to STDOUT.
 
-If you pass no files and don’t use `--stdin`, Docscribe processes the current directory recursively.
+If you pass no files and don't use `--stdin`, Docscribe processes the current directory recursively.
+
+### Exit codes
+
+- **0** — all files are up to date (no changes needed)
+- **1** — some files need documentation updates
+- **2** — execution error (parse error, missing files, etc.)
 
 ### Options
 
@@ -385,10 +406,32 @@ If you pass no files and don’t use `--stdin`, Docscribe processes the current
   Read source from STDIN and print rewritten output.
 
 - `--verbose`  
-  Print per-file actions.
+  Print per-file actions. Also enables `--progress`.
+
+- `--progress`  
+  Show progress (`[N/total] path/to/file.rb`) on stderr as each file is processed.
+
+- `--quiet` (`-q`)  
+  Only show status, no details (suppresses change reasons).
+  Overrides the default detailed output.
 
 - `--explain`  
-  Show detailed reasons for each file that would change.
+  Show detailed reasons for each file (default; no-op for compatibility).
+
+- `--server`  
+  Run via a persistent daemon (Unix socket). Speeds up repeated invocations
+  by keeping the Ruby runtime loaded and caching results.
+
+- `-k`, `--keep-descriptions`  
+  Preserve existing documentation text when rebuilding doc blocks in aggressive mode.
+
+- `-B`, `--no-boilerplate`  
+  Suppress boilerplate text (`Method documentation.`, `Param documentation.`) in output.  
+  Equivalent to `emit.include_default_message: false` and `emit.include_param_documentation: false` in config.
+
+- `--format FORMAT`  
+  Output format: `text` (default, human-readable), `json` (machine-readable, RuboCop-compatible), or `sarif` (SARIF 2.1
+  JSON, compatible with GitHub Code Scanning).
 
 - `--rbs`  
   Use RBS signatures for `@param`/`@return` when available (falls back to inference).
@@ -396,6 +439,12 @@ If you pass no files and don’t use `--stdin`, Docscribe processes the current
 - `--sig-dir DIR`  
   Add an RBS signature directory (repeatable). Implies `--rbs`.
 
+- `--sorbet`  
+  Use Sorbet signatures for `@param`/`@return` when available (falls back to inference).
+
+- `--rbi-dir DIR`  
+  Add an Sorbet RBI directory (repeatable). Implies `--sorbet`.
+
 - `--include PATTERN`  
   Include PATTERN (method id or file path; glob or `/regex/`).
 
@@ -456,9 +505,224 @@ If you pass no files and don’t use `--stdin`, Docscribe processes the current
 
 - Show detailed reasons for files that would change:
   ```shell
-  docscribe --verbose --explain lib
+  docscribe --verbose lib
   ```
 
+### `docscribe sigs` — check RBS signature coverage
+
+> [!WARNING]
+> `docscribe sigs` requires **Ruby 3.0+** and the `rbs` gem. On Ruby 2.7 it will print an error and exit with code 2.
+
+`docscribe sigs` parses Ruby files, extracts method definitions, and checks each
+method against the configured RBS signature directories. Reports methods that lack RBS type signatures.
+
+```shell
+# Check lib/ against sig/ signatures
+docscribe sigs lib
+
+# Use RBS collection
+docscribe sigs --rbs-collection lib
+
+# Multiple signature directories
+docscribe sigs -s sig -s vendor/sigs lib
+
+# Verbose output (also prints methods that have signatures)
+docscribe sigs --verbose lib
+```
+
+**Flags:**
+
+- `-s`, `--sig-dir DIR` — add an RBS signature directory (repeatable). Default: `sig`.
+- `--rbs-collection` — use RBS collection (reads `rbs_collection.lock.yaml`).
+- `--verbose` — also print methods that have signatures.
+- `-h`, `--help` — show help.
+
+**Exit codes:**
+
+- `0` — all methods have RBS signatures.
+- `1` — some methods lack RBS signatures.
+- `2` — error occurred.
+
+### `docscribe rbs` — generate RBS from YARD
+
+> [!WARNING]
+> `docscribe rbs` requires **Ruby 3.0+** and the `rbs` gem. On Ruby 2.7 it will print an error and exit with code 2.
+
+`docscribe rbs` parses YARD comments (`@param`, `@return`, `@option`) from Ruby files
+and generates corresponding `.rbs` signature files.
+
+```shell
+# Generate RBS files in sig/
+docscribe rbs lib
+
+# Print to stdout (no files written)
+docscribe rbs -n lib
+
+# Specify output directory
+docscribe rbs -o sig/gen lib
+
+# Overwrite existing files
+docscribe rbs -f lib
+```
+
+**Flags:**
+
+- `-o`, `--output DIR` — output directory (default: `sig`).
+- `-n`, `--dry-run` — print generated RBS to stdout, do not write files.
+- `-f`, `--force` — overwrite existing files.
+- `-h`, `--help` — show help.
+
+**Exit codes:**
+
+- `0` — success.
+- `1` — errors occurred during processing.
+- `2` — execution error (no files found).
+
+```ruby
+# Example: lib/user.rb
+class User
+  # @param [String] name
+  # @param [Integer] age
+  # @return [User]
+  def initialize(name, age)
+    @name = name
+    @age = age
+  end
+end
+```
+
+```shell
+docscribe rbs lib
+# Generated sig/user.rbs
+```
+
+```ruby.rbs
+# sig/user.rbs
+class User
+    def initialize: (String name, Integer age) -> User
+end
+```
+
+### `docscribe update_types` — two-pass type-aware documentation update
+
+> [!NOTE]
+> `docscribe update_types` is a convenience alias for the two-pass workflow above. It requires Ruby 3.0+ and the `rbs`
+> gem (because of `--rbs-collection`). The RBS collection must be set up first with
+> `bundle exec rbs collection install`. Type accuracy depends on your RBS signatures — if signatures are incomplete or
+> missing, types will fall back to AST inference.
+
+`docscribe update_types` runs two passes to bring both docs and RBS signatures up to date:
+
+1. **Pass 1** — `docscribe -AkB --rbs-collection <dir>`: aggressively rebuilds doc blocks, preserves existing
+   descriptions, suppresses boilerplate, uses RBS collection types.
+2. **Pass 2** — `docscribe -aB --rbs-collection <dir>`: safe merge cleanup with no boilerplate.
+
+```shell
+# Update docs in lib/ using RBS collection
+docscribe update_types lib
+
+# Defaults to current directory
+docscribe update_types
+```
+
+### `docscribe check_for_comments` — find placeholder documentation
+
+`docscribe check_for_comments` scans Ruby source files for YARD comments that still contain default placeholder
+text. Reads the configured placeholder messages from `docscribe.yml` (or built-in defaults). Useful in CI to catch
+files where auto-generated text was never replaced with real documentation.
+
+```shell
+# Scan entire project
+docscribe check_for_comments
+
+# Scan specific directories
+docscribe check_for_comments lib app
+```
+
+Exit code `0` if no placeholders found, `1` if any are detected.
+
+**Flags:**
+
+- `-h`, `--help` — show help.
+
+### `docscribe server` — persistent daemon mode
+
+> [!NOTE]
+> Server mode requires **Ruby 3.1+** (`Process.fork` for background daemon).
+
+`docscribe server` starts a background daemon that keeps the Ruby runtime loaded and caches parsed ASTs across
+invocations. Subsequent `docscribe` calls with `--server` communicate with the daemon over a Unix socket instead of
+reloading the entire toolchain.
+
+```shell
+# Start the daemon (auto-detached in background)
+docscribe server start
+
+# Check if the daemon is running
+docscribe server status
+
+# Stop the daemon
+docscribe server stop
+
+# Use the daemon for file checks (much faster on repeated calls)
+docscribe --server lib
+docscribe -a --server lib
+```
+
+**How it works:**
+
+1. `docscribe server start` forks a background process that listens on a Unix socket in the system temp directory.
+2. The socket path is derived from the project root, `Gemfile.lock` mtime, and `rbs_collection.lock.yaml` mtime — so any
+   environment change spawns a fresh daemon automatically.
+3. Client requests (`docscribe --server`) send JSON-RPC 2.0 messages over the socket: `check` (inspect), `fix` (apply
+   changes), `shutdown`, and `ping` (health/version info).
+4. The daemon holds a reusable `Docscribe::Config` instance and an LRU file cache (bounded at 1000 entries), so repeated
+   checks on the same files are nearly instant.
+5. After 5 minutes of inactivity the daemon shuts down automatically.
+
+**Thin client (`docscribe-client`):**
+
+For IDE plugins and CI systems that need minimal startup overhead, a standalone thin client is available as
+`exe/docscribe-client`. It connects to the daemon via the same Unix socket protocol without loading the full docscribe
+gem:
+
+```shell
+# Check a file via the daemon
+docscribe-client --check lib/user.rb
+
+# Apply fixes via the daemon
+docscribe-client --fix lib/user.rb
+
+# Check if the daemon is running
+docscribe-client --status
+
+# Get version, pid, uptime from the daemon
+docscribe-client --ping
+
+# Stop the daemon
+docscribe-client --shutdown
+```
+
+The thin client is used automatically by
+the [VS Code](https://marketplace.visualstudio.com/items?itemName=unurgunite.docscribe-vscode)
+and [RubyMine](https://plugins.jetbrains.com/plugin/32349-docscribe) plugins when the daemon is running.
+
+**Environment invalidation:**
+
+The daemon's socket path includes a hash of:
+
+- `Gemfile.lock` mtime — gem changes that may affect RBS signatures.
+- `rbs_collection.lock.yaml` mtime — RBS collection signature updates.
+
+If any of these files change, the next `docscribe --server` call will start a new daemon automatically. The old daemon
+is left to idle-timeout on its own.
+
+**CLI override handling:**
+
+When CLI overrides (`-C`, `--include`, `--exclude`, etc.) change between requests, the daemon resets its effective
+configuration, clears the file cache, and applies the new overrides before processing. If no overrides are passed, the
+cached state from the initial load is used, preserving performance.
+
 ## Update strategies
 
 Docscribe supports two update strategies: **safe** and **aggressive**.
@@ -493,6 +757,9 @@ Aggressive strategy:
 
 Use it when you want to rebaseline or regenerate docs wholesale.
 
+> [!CAUTION]
+> Aggressive mode rewrites existing doc blocks entirely. Review changes with `git diff` before committing.
+
 ### Output markers
 
 In inspect mode, Docscribe prints one character per file:
@@ -500,14 +767,20 @@ In inspect mode, Docscribe prints one character per file:
 - `.` = file is up to date
 - `F` = file would change
 - `E` = file had an error
+- `M` = type mismatch detected (external RBS/Sorbet signature differs from inferred type)
 
 In write modes:
 
 - `.` = file already OK
 - `C` = file was updated
 - `E` = file had an error
+- `M` = file updated but type mismatch remains
+
+> [!IMPORTANT]
+> The `M` marker only appears when `--rbs` or `--sorbet` is enabled, since type mismatches are detected by
+> comparing external signatures against inferred types.
 
-With `--verbose`, Docscribe prints per-file statuses instead.
+With `--verbose`, Docscribe prints per-file statuses instead; type mismatches show as `MT` with the specific difference.
 
 With `--explain`, Docscribe also prints detailed reasons, such as:
 
@@ -516,6 +789,27 @@ With `--explain`, Docscribe also prints detailed reasons, such as:
 - missing module_function note
 - unsorted tags
 
+Use `--quiet` to suppress these details and show only file names and the summary line.
+
+## Tips & tricks
+
+Useful flag combinations for common workflows:
+
+- `docscribe -aB lib` — safe autocorrect without boilerplate. Uses safe mode but suppresses default text, leaving only
+  type tags (`@param`, `@return`). Clean minimal docs.
+- `docscribe -AkB lib` — aggressive autocorrect with preserved descriptions and no boilerplate. Rebuilds doc blocks,
+  keeps your hand-written descriptions, suppresses default text. Best for rebaselining.
+- `docscribe -a --rbs-collection lib` — safe autocorrect using RBS gem collection signatures. Recommended for Rails
+  projects.
+- `docscribe -a --sorbet --rbi-dir sorbet/rbi lib` — safe autocorrect using Sorbet RBI signatures.
+- `docscribe update_types lib` — two-pass type-aware update: aggressively rebuilds docs with kept descriptions and RBS
+  collection, then safe-merges to clean up.
+  See [docscribe update_types](#docscribe-update_types--two-pass-type-aware-documentation-update).
+
+> [!NOTE]
+> `docscribe update_types` is a convenient shortcut, but be aware it uses `--rbs-collection` under the hood.
+> If your RBS signatures are incomplete, types may fall back to AST inference.
+
 ## Parser backend (Parser gem vs Prism)
 
 Docscribe internally works with `parser`-gem-compatible AST nodes and `Parser::Source::*` objects (so it can use
@@ -524,6 +818,11 @@ Docscribe internally works with `parser`-gem-compatible AST nodes and `Parser::S
 - On Ruby **<= 3.3**, Docscribe parses using the `parser` gem.
 - On Ruby **>= 3.4**, Docscribe parses using **Prism** and translates the tree into the `parser` gem's AST.
 
+> [!NOTE]
+> Prism support is automatic on Ruby 3.4+. On earlier Rubies, the `parser` gem is always used.
+> You can override with `DOCSCRIBE_PARSER_BACKEND=prism` on Ruby 3.1+ if you have the `prism` gem installed,
+> but this is not recommended for production use.
+
 You can force a backend with an environment variable:
 
 ```shell
@@ -537,16 +836,33 @@ Docscribe can improve generated `@param` and `@return` types by reading external
 AST inference.
 
 > [!IMPORTANT]
-> When external type information is available, Docscribe resolves signatures in this order:
-> - inline Sorbet `sig` declarations in the current Ruby source;
-> - Sorbet RBI files;
-> - RBS files;
-> - AST inference fallback.
+> Docscribe resolves types in a two-level chain. For **documentation tags** (`@param`, `@return`), the priority is:
 >
-> If an external signature cannot be loaded or parsed, Docscribe falls back to normal inference instead of failing.
+> | Priority | Source                                                      | When active                                              |
+> |----------|-------------------------------------------------------------|----------------------------------------------------------|
+> | **1**    | Inline Sorbet `sig { ... }` in current file                 | `--sorbet` or `sorbet.enabled: true`                     |
+> | **2**    | Sorbet RBI files (`.rbi`)                                   | `--sorbet --rbi-dir` or `sorbet.rbi_dirs`                |
+> | **3**    | RBS files (sig_dirs + collection, loaded into one env)      | `--rbs --sig-dir` / `--rbs-collection` or `rbs.*` config |
+> | **3a**   | └─ Fallback: sig_dirs only (collection dropped on conflict) | Automatic if priority 3 env load fails                   |
+> | **4**    | AST inference (fallback)                                    | Always active                                            |
+>
+> For **intra-method body inference** (e.g. resolving `Integer#positive?` -> `Boolean`), a separate core RBS provider
+> loads only stdlib/built-in signatures and is active automatically when the `rbs` gem is available — even without
+> `--rbs`.
+>
+> If an external signature cannot be loaded or parsed, Docscribe falls back to the next source in the chain instead of
+> failing.
 
 ### RBS
 
+> [!IMPORTANT]
+> All RBS features require the `rbs` gem. Add `gem "rbs"` to your Gemfile and run `bundle install`,
+> or install it globally with `gem install rbs`.
+>
+> On Ruby 2.7 the `rbs` gem cannot load at all — `--rbs`, `--sig-dir`, `--rbs-collection`,
+> `docscribe sigs`, and `docscribe rbs` will print a warning and fall back to AST-only inference.
+> On Ruby 3.0+, if the gem is missing, Docscribe silently falls back to inference when you pass RBS flags.
+
 Docscribe can read method signatures from `.rbs` files and use them to generate more accurate parameter and return
 types.
 
@@ -566,12 +882,23 @@ Config:
 
 ```yaml
 rbs:
-  enabled: true
+  enabled: false
   sig_dirs:
     - sig
+  collection: false
   collapse_generics: false
+  collapse_object_generics: false
+  warn_missing_collection: true
 ```
 
+- `collection` — enable auto-discovery of RBS collection from `rbs_collection.lock.yaml`. Pass `--rbs-collection` on the
+  CLI.
+- `collapse_generics` — strip all generic type arguments (e.g. `Array<String>` -> `Array`).
+- `collapse_object_generics` — only strip generic arguments when all are `Object` (e.g. `Hash<Object, Object>` ->
+  `Hash`, but `Hash<Symbol, Object>` stays).
+- `warn_missing_collection` — warn on stderr when `rbs_collection.lock.yaml` is found but collection is not enabled. Set
+  to `false` to suppress.
+
 Example:
 
 ```ruby
@@ -794,24 +1121,29 @@ end
 
 ### Generic type formatting
 
-Both RBS and Sorbet integrations support `collapse_generics`.
+Both RBS and Sorbet integrations support generic type collapsing.
 
-When disabled:
+**`collapse_generics`** — strips all generic type arguments.
+**`collapse_object_generics`** — only strips arguments when all are `Object` (e.g. `Hash<Object, Object>` -> `Hash`, but
+`Hash<Symbol, Object>` stays).
+
+When both disabled:
 
 ```yaml
 rbs:
   collapse_generics: false
+  collapse_object_generics: false
 
 sorbet:
   collapse_generics: false
 ```
 
-Docscribe preserves generic container details where possible, for example:
+Docscribe preserves generic container details, for example:
 
 - `Array<String>`
 - `Hash<Symbol, Integer>`
 
-When enabled:
+When `collapse_generics` is enabled:
 
 ```yaml
 rbs:
@@ -821,7 +1153,7 @@ sorbet:
   collapse_generics: true
 ```
 
-Docscribe simplifies container types to their outer names, for example:
+Docscribe simplifies all container types to their outer names, for example:
 
 - `Array`
 - `Hash`
@@ -856,6 +1188,11 @@ Return values:
 - For simple bodies, Docscribe looks at the last expression or explicit `return`.
 - Unions with `nil` become optional types (e.g. `String` or `nil` -> `String?`).
 - For control flow (`if`/`case`), it unifies branches conservatively.
+
+> [!TIP]
+> Docscribe resolves return types for core Ruby methods (`Integer#positive?`, `String#upcase`, etc.)
+> **even without `--rbs`** — the core RBS provider is always active when the `rbs` gem is available.
+
 - **RBS core type inference**: when `--rbs` is enabled, Docscribe resolves return types for method calls on core types
   from their RBS definitions:
     - `arg.positive?` (`arg = 1`) -> `Boolean` (from `Integer#positive?`)
@@ -1168,6 +1505,19 @@ Sample plugins available at [examples](examples/plugins):
 
 Docscribe can be configured via a YAML file (`docscribe.yml` by default, or pass `--config PATH`).
 
+### Anonymous block parameters
+
+Ruby 3.2+ allows anonymous block arguments (`def foo(&)`). By default, Docscribe generates `@param [Proc] block` for
+these — but since the parameter has no name, the tag is misleading.
+
+To suppress the `@param` tag for anonymous block arguments:
+
+```yaml
+skip_anonymous_block_params: true
+```
+
+When `false` (default), anonymous block params generate `@param [Proc] block`.
+
 ### Filtering
 
 Docscribe can filter both *files* and *methods*.
@@ -1391,6 +1741,7 @@ docscribe generate tag SincePlugin --stdout
 ```
 
 The generated file contains:
+
 - the correct base class (`Base::TagPlugin` or `Base::CollectorPlugin`)
 - inline comments describing every available `Context` attribute (TagPlugin)
   or the expected return shape (CollectorPlugin)
@@ -1401,6 +1752,58 @@ The generated file contains:
 > The class name must be a valid Ruby constant (`MyPlugin`, `My::Plugin`).
 > The output filename is the snake_case equivalent (`my_plugin.rb`, `my/plugin.rb`).
 
+### Full configuration reference
+
+<details>
+<summary>Click to expand — 43 config keys</summary>
+
+| Key                                       | Type       | Default                                                                                      | Description                                                                |
+|-------------------------------------------|------------|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
+| `keep_descriptions`                       | `bool`     | `false`                                                                                      | Preserve existing doc text in aggressive mode                              |
+| `skip_anonymous_block_params`             | `bool`     | `false`                                                                                      | Skip `@param [Proc] block` for anonymous `&` params                        |
+| `emit.header`                             | `bool`     | `false`                                                                                      | Generate method header line (`+#foo+ -> ...`)                              |
+| `emit.include_default_message`            | `bool`     | `true`                                                                                       | Insert default message (`Method documentation.`)                           |
+| `emit.include_param_documentation`        | `bool`     | `true`                                                                                       | Insert param description text (`Param documentation.`)                     |
+| `emit.param_tags`                         | `bool`     | `true`                                                                                       | Generate `@param` tags                                                     |
+| `emit.return_tag`                         | `bool`     | `true`                                                                                       | Generate `@return` tag                                                     |
+| `emit.visibility_tags`                    | `bool`     | `true`                                                                                       | Generate `@private`/`@protected` tags                                      |
+| `emit.raise_tags`                         | `bool`     | `true`                                                                                       | Generate `@raise` tags (for `raise` in method body)                        |
+| `emit.rescue_conditional_returns`         | `bool`     | `true`                                                                                       | Consider `rescue` branches in return type inference                        |
+| `emit.attributes`                         | `bool`     | `false`                                                                                      | Generate `@!attribute` for `attr_*` and `Struct.new`                       |
+| `doc.default_message`                     | `string`   | `"Method documentation."`                                                                    | Default text for method description                                        |
+| `doc.param_documentation`                 | `string`   | `"Param documentation."`                                                                     | Default text for param description                                         |
+| `doc.sort_tags`                           | `bool`     | `true`                                                                                       | Sort tags according to `tag_order`                                         |
+| `doc.tag_order`                           | `string[]` | `["todo","note","api","private","protected","param","option","yieldparam","raise","return"]` | Tag sort order                                                             |
+| `doc.param_tag_style`                     | `string`   | `"type_name"`                                                                                | `@param` style: `type_name` (`[Type] name`) or `name_type` (`name [Type]`) |
+| `inference.fallback_type`                 | `string`   | `"Object"`                                                                                   | Fallback type when inference yields no result                              |
+| `inference.nil_as_optional`               | `bool`     | `true`                                                                                       | Treat `nil` as an optional type                                            |
+| `inference.treat_options_keyword_as_hash` | `bool`     | `true`                                                                                       | Treat `**options` as `Hash` in `@option` tags                              |
+| `filter.include`                          | `string[]` | `[]`                                                                                         | Only include methods matching pattern                                      |
+| `filter.exclude`                          | `string[]` | `[]`                                                                                         | Exclude methods matching pattern                                           |
+| `filter.visibilities`                     | `string[]` | `["public","protected","private"]`                                                           | Visibilities to process                                                    |
+| `filter.scopes`                           | `string[]` | `["instance","class"]`                                                                       | Scopes to process                                                          |
+| `filter.files.include`                    | `string[]` | `[]`                                                                                         | Only process files matching pattern                                        |
+| `filter.files.exclude`                    | `string[]` | `["spec"]`                                                                                   | Skip files matching pattern                                                |
+| `methods.instance.public`                 | `object`   | `{}`                                                                                         | Overrides for instance public methods                                      |
+| `methods.instance.protected`              | `object`   | `{}`                                                                                         | Overrides for instance protected methods                                   |
+| `methods.instance.private`                | `object`   | `{}`                                                                                         | Overrides for instance private methods                                     |
+| `methods.class.public`                    | `object`   | `{}`                                                                                         | Overrides for class public methods                                         |
+| `methods.class.protected`                 | `object`   | `{}`                                                                                         | Overrides for class protected methods                                      |
+| `methods.class.private`                   | `object`   | `{}`                                                                                         | Overrides for class private methods                                        |
+| `rbs.enabled`                             | `bool`     | `false`                                                                                      | Enable RBS integration                                                     |
+| `rbs.collection`                          | `bool`     | `false`                                                                                      | Auto-discover RBS collection from `rbs_collection.lock.yaml`               |
+| `rbs.sig_dirs`                            | `string[]` | `["sig"]`                                                                                    | RBS signature directories                                                  |
+| `rbs.collection_dirs`                     | `string[]` | `[]`                                                                                         | RBS collection directories (set automatically)                             |
+| `rbs.collapse_generics`                   | `bool`     | `false`                                                                                      | Strip generic arguments (`Array<String>` -> `Array`)                       |
+| `rbs.collapse_object_generics`            | `bool`     | `false`                                                                                      | Strip generics only when all are `Object`                                  |
+| `rbs.warn_missing_collection`             | `bool`     | `true`                                                                                       | Warn when `rbs_collection.lock.yaml` found but collection not enabled      |
+| `sorbet.enabled`                          | `bool`     | `false`                                                                                      | Enable Sorbet integration                                                  |
+| `sorbet.rbi_dirs`                         | `string[]` | `["sorbet/rbi","rbi"]`                                                                       | RBI file directories                                                       |
+| `sorbet.collapse_generics`                | `bool`     | `false`                                                                                      | Strip generic arguments from Sorbet signatures                             |
+| `plugins.require`                         | `string[]` | `[]`                                                                                         | Plugin paths for `require`                                                 |
+
+</details>
+
 ## CI integration
 
 Fail the build if files would need safe updates:
@@ -1417,11 +1820,33 @@ Apply safe fixes before the test stage:
   run: docscribe -a lib
 ```
 
-Aggressively rebuild docs:
+Rebuild docs aggressively, preserve descriptions, suppress boilerplate, with verbose output:
 
 ```yaml
 - name: Rebuild inline docs
-  run: docscribe -A lib
+  run: docscribe -AkB --verbose
+```
+
+Run static type checking with Steep (requires Ruby ≥ 3.2):
+
+```yaml
+- name: Steep (type check)
+  if: ${{ matrix.ruby >= 3.2 }}
+  run: bundle exec steep check
+```
+
+Fail the build if any generated docs still contain default placeholder text:
+
+```yaml
+- name: Check for placeholder docs
+  run: docscribe check_for_comments lib/
+```
+
+For stricter validation, check for empty doc blocks:
+
+```yaml
+- name: Check for empty doc blocks
+  run: "! grep -rn '^  # $' lib/"
 ```
 
 ## Comparison to YARD's parser
@@ -1450,13 +1875,42 @@ yard doc -o docs
 ## Roadmap
 
 - Method behavior inference from AST;
-- YAML-based plugin configuration;
+- Deeper YARD integration — parse `.c` source comments and generate docs for C-extensions;
+- Custom parser plugins — support non-Ruby languages (Crystal, etc.) via the plugin system;
 - Effective config dump;
-- JSON output;
 - Overload-aware signature selection;
 - Manual `@!attribute` merge policy;
 - Richer inference for common APIs;
-- Editor integration.
+- Documentation coverage report — percentage of documented methods, params, returns;
+- Pre-commit hook auto-install (`docscribe init --pre-commit`);
+- Parallel processing for large codebases.
+
+## Editor Integration
+
+Docscribe provides IDE plugins for a better development experience:
+
+### VS Code
+
+[![VS Code](https://img.shields.io/badge/VS%20Code-plugin-blue?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=unurgunite.docscribe-vscode)
+
+- **Repository:** [github.com/FlorexLabs/docscribe-vscode](https://github.com/FlorexLabs/docscribe-vscode)
+- **Marketplace:** [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=unurgunite.docscribe-vscode)
+- **Features:** inline diagnostics, quick-fix, auto-check on save, status bar
+
+### RubyMine
+
+[![RubyMine](https://img.shields.io/badge/RubyMine-plugin-green?logo=jetbrains)](https://plugins.jetbrains.com/plugin/32349-docscribe)
+
+- **Repository:** [github.com/FlorexLabs/docscribe-rubymine](https://github.com/FlorexLabs/docscribe-rubymine)
+- **Marketplace:** [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/32349-docscribe)
+- **Features:** ExternalAnnotator, AnAction, IntentionAction, Settings UI
+
+> [!NOTE]
+> Both plugins require **docscribe >= 1.5.0**.
+>
+> For optimal performance, both plugins use the `docscribe-client` thin client
+> to communicate with the docscribe daemon (see [server mode](#docscribe-server--persistent-daemon-mode)).
+> Start the daemon with `docscribe server start` for near-instant diagnostics.
 
 ## Contributing
 
@@ -1471,6 +1925,14 @@ bundle exec rubocop
 - [Dev.to article](https://dev.to/unurgunite)
 - [GitHub Discussions](https://github.com/unurgunite/docscribe/discussions)
 
+## Logo Attribution
+
+The Docscribe logo uses the Ruby gem icon by [FlorexLabs](https://github.com/FlorexLabs).
+
+<p>
+  <img src="assets/icons/icon_128x128.png" alt="Docscribe logo">
+</p>
+
 ## License
 
 MIT