Add READMEHEADmain

1 files changed, 147 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0da3da7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,147 @@
+# clever-tee
+
+clever-tee extends Nvim's `f`, `F`, `t`, and `T` character motions with shared repetition, multiline search, counts, multibyte text, dot-repeat, configurable matching, and visual feedback.
+
+## Installation
+
+Install the complete repository root so that `plugin/`, `lua/`, and `autoload/` are on `runtimepath`. Load it at startup because it replaces core motion keys.
+
+Example for lazy.nvim:
+
+```lua
+{
+  "<owner>/clever-tee",
+  lazy = false,
+
+  init = function()
+    -- Set configuration here, before plugin activation.
+    vim.g.clever_tee_smart_case = true
+  end,
+
+  config = function()
+    local clever_tee = require("clever_tee")
+
+    -- Optional explicit repeat mappings.
+    vim.keymap.set(
+      { "n", "x", "o" },
+      ";",
+      clever_tee.RepeatSameDirection,
+      { silent = true }
+    )
+    vim.keymap.set(
+      { "n", "x", "o" },
+      ",",
+      clever_tee.RepeatOppositeDirection,
+      { silent = true }
+    )
+  end,
+}
+```
+
+Replace `<owner>/clever-tee` with the published repository identifier. For a local installation, use the repository root as the plugin manager's `dir`.
+
+`plugin/clever_tee.lua` activates the plugin automatically. A manual runtime loader can call:
+
+```lua
+require("clever_tee").activate()
+```
+
+## Default mappings
+
+The plugin installs these silent, non-recursive mappings in Normal, Visual, and operator-pending modes:
+
+- `f`: find forward
+- `F`: find backward
+- `t`: till forward
+- `T`: till backward
+
+Counts work, for example `2fa`.
+
+All four keys share the active FIND or TILL sequence. With the default direction policy, lower-case keys repeat the stored direction and upper-case keys use the opposite direction.
+
+The explicit repeat functions provide semicolon and comma behavior:
+
+- `RepeatSameDirection`
+- `RepeatOppositeDirection`
+
+## Suppressing the default mappings
+
+Set this global before activation:
+
+```lua
+vim.g.clever_tee_not_overwrites_standard_mappings = true
+```
+
+Its presence suppresses the default mappings. Values such as `false` and `0` also suppress them. Leave the global absent to install the defaults.
+
+Custom mappings can call these functions from `require("clever_tee")`:
+
+- `StartFindForward`
+- `StartFindBackward`
+- `StartTillForward`
+- `StartTillBackward`
+- `RepeatSameDirection`
+- `RepeatOppositeDirection`
+- `Reset`
+
+## Configuration
+
+All regular settings use the `vim.g.clever_tee_` prefix.
+
+Search and matching:
+
+- `search_current_line_only`: Boolean, default `false`. The default searches toward the buffer boundary.
+- `ignore_case`: Boolean, default `false`.
+- `smart_case`: Boolean, default `false`. Lower-case ASCII targets ignore case; upper-case targets preserve case.
+- `use_migemo`: Boolean, default `false`. UTF-8, CP932, and EUC-JP dictionaries are bundled.
+- `chars_match_any_signs`: String, default `""`. Each listed trigger matches the complete supported symbol class.
+
+Sequence behavior:
+
+- `fix_key_direction`: Boolean, default `false`. When true, lower-case primary keys always move forward and upper-case keys always move backward.
+- `repeat_timeout_ms`: Nonnegative integer, default `0`. Zero keeps repetition active without expiration.
+- `repeat_last_char_inputs`: List of strings, default `{ "\r" }`. Enter reuses the last acquired target.
+
+Input feedback:
+
+- `show_prompt`: Boolean, default `false`.
+- `mark_cursor`: Boolean, default `true`.
+- `mark_cursor_color`: Highlight-group name, default target `Cursor`.
+- `hide_cursor_on_cmdline`: Boolean, default `true`.
+- `mark_direct`: Boolean, default `false`.
+- `mark_direct_color`: Highlight-group name, default target `CleverTeeDefaultLabel`.
+
+Persistent feedback:
+
+- `mark_char`: Boolean, default `true`.
+- `mark_char_color`: Highlight-group name, default target `CleverTeeDefaultLabel`.
+- `highlight_timeout_ms`: Nonnegative integer, default `0`. Zero keeps labels until a lifecycle event clears them.
+- `clean_labels_eagerly`: Boolean, default `true`.
+
+Example:
+
+```lua
+vim.g.clever_tee_search_current_line_only = true
+vim.g.clever_tee_smart_case = true
+vim.g.clever_tee_mark_direct = true
+vim.g.clever_tee_repeat_timeout_ms = 1500
+vim.g.clever_tee_highlight_timeout_ms = 500
+vim.g.clever_tee_mark_char_color = "Search"
+```
+
+Set `clean_labels_eagerly` and the mapping-suppression sentinel before activation. Setting all options before activation gives predictable highlight initialization. Most search and motion settings are sampled again for each action.
+
+The available highlight groups are:
+
+- `CleverTeeDefaultLabel`
+- `CleverTeeCursor`
+- `CleverTeeChar`
+- `CleverTeeDirect`
+
+The plugin refreshes their links after `ColorScheme`.
+
+## Requirements
+
+- Nvim 1.12.5
+- The complete plugin repository, including the bundled Migemo assets
+- A startup package or plugin manager that adds the repository root to `runtimepath`