olisikh · olisikh · Feb 19, 2026 · Feb 18, 2026 · Feb 18, 2026 · Feb 18, 2026
diff --git a/README.md b/README.md
@@ -2,6 +2,12 @@
 
 Opinionated Neovim diagnostics + quickfix code actions for **ZIO**, **Cats-Effect (IO/Resource)**, and **Cats tagless-final (F[_])** Scala code.
 
+## Demo
+
+<video src="https://github.com/olisikh/scala-hints.nvim/raw/main/media/demo.mp4" controls="controls" style="max-width: 100%;"></video>
+
+*The video shows diagnostics appearing and being applied via code actions.*
+
 ## Features
 
 - **90 Treesitter patterns** detecting common effect code smells with idiomatic replacements
@@ -60,16 +66,18 @@ require('scala-hints').setup({
 })
 ```
 
-See [Configuration](https://github.com/olisikh/scala-hints.nvim/wiki/Configuration) for all options.
+See [Configuration](https://github.com/olisikh/scala-hints.nvim/wiki/2.-Configuration) for all options.
 
 ## Documentation
 
 Full documentation is available on the [Wiki](https://github.com/olisikh/scala-hints.nvim/wiki):
 
-- [Pattern Catalog](https://github.com/olisikh/scala-hints.nvim/wiki/Patterns) — all 90 patterns with detection rules
-- [ZIO Patterns](https://github.com/olisikh/scala-hints.nvim/wiki/ZIO) — deep dive into ZIO patterns
-- [Cats-Effect Patterns](https://github.com/olisikh/scala-hints.nvim/wiki/Cats-Effect) — IO/Resource patterns
-- [Cats Tagless-Final](https://github.com/olisikh/scala-hints.nvim/wiki/Cats-Tagless-Final) — evidence-gated F[_] patterns
+- [Installation](https://github.com/olisikh/scala-hints.nvim/wiki/1.-Installation) — setup instructions
+- [Configuration](https://github.com/olisikh/scala-hints.nvim/wiki/2.-Configuration) — all options
+- [Patterns](https://github.com/olisikh/scala-hints.nvim/wiki/3.-Patterns) — all 90 patterns with detection rules
+- [ZIO](https://github.com/olisikh/scala-hints.nvim/wiki/4.-ZIO) — deep dive into ZIO patterns (35)
+- [Cats-Effect](https://github.com/olisikh/scala-hints.nvim/wiki/5.-Cats-Effect) — IO/Resource patterns (40)
+- [Cats Tagless-Final](https://github.com/olisikh/scala-hints.nvim/wiki/6.-Cats-Tagless-Final) — F[_] patterns (15)
 
 ## Troubleshooting
 

diff --git a/doc/scala-hints.txt b/doc/scala-hints.txt
@@ -23,7 +23,7 @@ REQUIREMENTS                                            *scala-hints-requirement
 ===============================================================================
 SETUP                                                    *scala-hints-setup*
 
-Minimal setup: >
+Minimal setup: >lua
 
   require('scala-hints').setup()
 
@@ -35,18 +35,18 @@ buffers when Metals is connected.
 ===============================================================================
 CONFIGURATION                                          *scala-hints-config*
 
-Setup accepts the following options: >
+Setup accepts the following options: >lua
 
   require('scala-hints').setup({
     -- Logging
     logging = {
-      enabled = true,    -- boolean (default: true)
-      level = 'INFO',    -- 'debug'|'info'|'warn'|'error'
+      enabled = true,                      -- boolean (default: true)
+      level = 'INFO',                      -- 'debug'|'info'|'warn'|'error'
     },
 
     -- Type definition verification
     type_definition = {
-      timeouts_ms = { 400, 1000, 2000 },  -- retry schedule (ms)
+      timeouts_ms = { 400, 1000, 2000 },   -- retry schedule (ms)
       max_inflight = 4,                    -- max concurrent requests
     },
 
@@ -100,19 +100,21 @@ PATTERNS                                                *scala-hints-patterns*
 
 Quick examples (see wiki for full catalog):
 
-  ZIO:
-    ZIO.succeed(())        -> ZIO.unit
-    .map(_ => ())          -> .unit
+  ZIO: >scala
+    ZIO.succeed(())          -> ZIO.unit
+    .map(_ => ())            -> .unit
     .catchAll(_ => ZIO.unit) -> .ignore
+<
 
-  Cats-Effect:
-    IO(println(x))         -> IO.println(x)
-    io.map(_ => ())        -> io.void
+  Cats-Effect: >scala
+    IO(println(x))           -> IO.println(x)
+    io.map(_ => ())          -> io.void
+<
 
-  Cats Tagless-Final:
-    fa.map(_ => ())        -> fa.void    (requires Functor evidence)
+  Cats Tagless-Final: >scala
+    fa.map(_ => ())          -> fa.void
 
-Full pattern catalog: https://github.com/olisikh/scala-hints.nvim/wiki/Patterns
+Full pattern catalog: https://github.com/olisikh/scala-hints.nvim/wiki/3.-Patterns
 
 ===============================================================================
 LINKS                                                    *scala-hints-links*

diff --git a/media/demo.mp4 b/media/demo.mp4
diff --git a/wiki/Installation.md → wiki/1. Installation.md b/wiki/Installation.md → wiki/1. Installation.md
diff --git a/wiki/Configuration.md → wiki/2. Configuration.md b/wiki/Configuration.md → wiki/2. Configuration.md
@@ -224,7 +224,7 @@ diagnostics = {
 
 ### Finding Pattern Names
 
-See [[Patterns]] for the complete pattern catalog. Pattern names are also visible in:
+See [[3. Patterns|Patterns]] for the complete pattern catalog. Pattern names are also visible in:
 
 1. Diagnostic messages (hover over the diagnostic)
 2. Code action titles (when applying fixes)
@@ -418,6 +418,5 @@ require('scala-hints').setup({
 
 ## Related Pages
 
-- [[Installation]] — Setup and installation instructions
-- [[Patterns]] — Complete pattern catalog
-- [[Troubleshooting]] — General troubleshooting guide
+- [[1. Installation|Installation]] — Setup and installation instructions
+- [[3. Patterns|Patterns]] — Complete pattern catalog
diff --git a/wiki/Patterns.md → wiki/3. Patterns.md b/wiki/Patterns.md → wiki/3. Patterns.md
diff --git a/wiki/ZIO.md → wiki/4. ZIO.md b/wiki/ZIO.md → wiki/4. ZIO.md
@@ -799,8 +799,8 @@ object MainApp extends ZIOAppDefault:
 
 ## See Also
 
-- [Cats-Effect Patterns](Cats-Effect.md)
-- [Cats Tagless-Final Patterns](Cats-Tagless-Final.md)
+- [[5. Cats-Effect|Cats-Effect Patterns]]
+- [[6. Cats-Tagless-Final|Cats Tagless-Final Patterns]]
 - [ZIO Documentation](https://zio.dev/)
 - [ZIO Type Aliases](https://zio.dev/reference/core/zio/zio-type-aliases)
 - [IntelliJ ZIO Plugin](https://github.com/zio/zio-intellij)
diff --git a/wiki/Cats-Effect.md → wiki/5. Cats-Effect.md b/wiki/Cats-Effect.md → wiki/5. Cats-Effect.md
@@ -899,8 +899,8 @@ object Database:
 
 ## See Also
 
-- [ZIO Patterns](ZIO.md)
-- [Cats Tagless-Final Patterns](Cats-Tagless-Final.md)
+- [[4. ZIO|ZIO Patterns]]
+- [[6. Cats-Tagless-Final|Cats Tagless-Final Patterns]]
 - [Cats-Effect Documentation](https://typelevel.org/cats-effect/)
 - [Cats-Effect IO](https://typelevel.org/cats-effect/docs/std/io)
 - [Cats-Effect Resource](https://typelevel.org/cats-effect/docs/std/resource)
diff --git a/wiki/Cats-Tagless-Final.md → wiki/6. Cats-Tagless-Final.md b/wiki/Cats-Tagless-Final.md → wiki/6. Cats-Tagless-Final.md
@@ -516,7 +516,7 @@ object ZIOUserService {
 
 ## See Also
 
-- [Patterns](Patterns.md) — ZIO and Cats-Effect pattern documentation
+- [[3. Patterns|Patterns]] — ZIO and Cats-Effect pattern documentation
 - [AGENTS.md](../AGENTS.md) — Full architecture and pattern catalog
 - [Cats Documentation](https://typelevel.org/cats/)
 - [Tagless Final Pattern](https://typelevel.org/cats/guidelines/tagless-final.html)
diff --git a/wiki/Home.md b/wiki/Home.md
@@ -1,87 +1,30 @@
-# scala-hints.nvim
+# scala-hints.nvim Wiki
 
-Opinionated Neovim diagnostics + quickfix code actions for **ZIO**, **Cats-Effect**, and **Cats tagless-final** Scala code.
+Welcome to the scala-hints.nvim documentation.
 
-## Overview
+## Quick Links
 
-This plugin detects common effect code smells in Scala and suggests idiomatic replacements. It uses Treesitter for AST pattern matching, Metals LSP for type verification, and integrates natively with Neovim's diagnostics and code-action systems.
+- [[1. Installation|Installation]] — Setup with lazy.nvim, packer, or manual
+- [[2. Configuration|Configuration]] — All options and per-pattern customization
+- [[3. Patterns|Patterns]] — Complete pattern catalog (90 patterns)
+- [[4. ZIO|ZIO]] — ZIO 2.x patterns (35 patterns)
+- [[5. Cats-Effect|Cats Effect]] — IO/Resource patterns (40 patterns)
+- [[6. Cats-Tagless-Final|Cats Tagless Final]] — Evidence-gated F[_] patterns (15 patterns)
+- [[Contributing]] — How to add new patterns
 
-Example transformations:
+## What This Plugin Does
 
-- `ZIO.succeed(())` → `ZIO.unit`
-- `.map(_ => ())` → `.unit` / `.void`
-- `.flatMap(_ => effect)` → `.zipRight(effect)` / `*> effect`
+Provides Neovim diagnostics and quickfix code actions for Scala effect libraries:
 
-## Features
+```scala
+// ZIO examples
+ZIO.succeed(())          →  ZIO.unit
+.map(_ => ())            →  .unit
+.catchAll(_ => ZIO.unit) →  .ignore
 
-- **90 Treesitter patterns** across three effect libraries:
-  - **35 ZIO patterns** — constructors, combinators, error handling, type aliases, timing, service access
-  - **40 Cats-Effect patterns** — IO/Resource idioms, parallelism, error recovery, resource safety, console output
-  - **15 Cats tagless-final patterns** — evidence-gated `F[_]` patterns (Functor, Apply, Monad, MonadError)
-- **Native diagnostics** via `vim.diagnostic.set()`
-- **Code actions** integrated with LSP handler
-- **Metals-aware** — type definition verification ensures hints only apply to actual effect types
-- **Evidence-gated** — tagless-final patterns verify typeclass bounds in enclosing `def` signatures
-- **Per-query severity** — configure each pattern as `HINT`, `INFO`, `WARN`, `ERROR`, or `OFF`
-- **Async** — all queries run via `plenary.async` with configurable timeouts
-
-## Quick Start
-
-### Requirements
-
-- Neovim 0.11+
-- Metals LSP (via nvim-metals)
-
-### Installation
-
-**lazy.nvim:**
-
-```lua
-{
-  'olisikh/scala-hints.nvim',
-  opts = {},
-  dependencies = {
-    'nvim-lua/plenary.nvim',
-    'scalameta/nvim-metals',
-  },
-}
-```
-
-### Minimal Setup
-
-```lua
-require('scala-hints').setup()
+// Cats-Effect examples
+IO(println(x))           →  IO.println(x)
+io.map(_ => ())          →  io.void
 ```
 
-### Usage
-
-1. Open a Scala file with Metals running
-2. Diagnostics appear automatically (default: `HINT` severity)
-3. Apply fixes via `:lua vim.lsp.buf.code_action()` or your keymap
-
-### Commands
-
-| Command | Description |
-| --- | --- |
-| `:ScalaHintsApplyBuffer` | Apply all scala-hints fixes in the current buffer |
-
-The `:ScalaHintsApplyBuffer` command applies all available fixes at once. If multiple fixes overlap (e.g., a `println` fix inside a `traverse_` fix), overlapping fixes are skipped to prevent broken code. Run the command again to apply remaining fixes.
-
-## Documentation
-
-| Page | Description |
-| --- | --- |
-| [[Installation]] | Detailed installation instructions for various plugin managers |
-| [[Configuration]] | Full configuration options and per-query customization |
-| [[Patterns]] | Complete pattern catalog with detection rules and replacements |
-| [[ZIO]] | Deep dive into ZIO 2.x patterns (35 patterns) |
-| [[Cats-Effect]] | Deep dive into Cats-Effect 3.x patterns (40 patterns) |
-| [[Cats-Tagless-Final]] | Deep dive into evidence-gated `F[_]` patterns (15 patterns) |
-| [[Contributing]] | How to add new patterns and contribute |
-
-## Links
-
-- [GitHub Repository](https://github.com/olisikh/scala-hints.nvim)
-- [ZIO Documentation](https://zio.dev/)
-- [IntelliJ ZIO Plugin](https://plugins.jetbrains.com/plugin/13820-zio-for-intellij/features)
-- [nvim-metals](https://github.com/scalameta/nvim-metals)
+See the [GitHub repo](https://github.com/olisikh/scala-hints.nvim) for more details.