Update readme

1 files changed, 96 insertions, 1 deletions

diff --git a/crates/atuin-nucleo/README.md b/crates/atuin-nucleo/README.md
index e617cfa0..d7c10735 100644
--- a/crates/atuin-nucleo/README.md
+++ b/crates/atuin-nucleo/README.md
@@ -1,4 +1,99 @@
-# Nucleo
+# nucleo-ext
+
+This is a fork of [helix-editor/nucleo](https://github.com/helix-editor/nucleo) that includes filtering and custom scoring built into the matching loop.
+
+## Fork Changes
+
+### Filter Callback
+
+Filter items before fuzzy matching. Useful for category/facet filtering (e.g., filter by directory, host, session).
+
+```rust
+use std::sync::Arc;
+
+// Filter to only include items where category == 1
+nucleo.set_filter(Some(Arc::new(|item: &MyItem| item.category == 1)));
+
+// Remove filter
+nucleo.set_filter(None);
+```
+
+Filters are applied:
+- During initial matching of new items
+- When rescoring existing matches after pattern changes
+- When resetting matches for empty patterns
+
+Setting a filter triggers a rescore on the next `tick()`.
+
+### Scorer Callback
+
+Compute custom scores after fuzzy matching. The scorer receives the item and the fuzzy score, and returns the final score used for sorting.
+
+```rust
+use std::sync::Arc;
+
+// Use item priority as the score (ignoring fuzzy score)
+nucleo.set_scorer(Some(Arc::new(|item: &MyItem, _fuzzy_score| {
+    item.priority
+})));
+
+// Combine fuzzy score with frecency
+nucleo.set_scorer(Some(Arc::new(|item: &MyItem, fuzzy_score| {
+    fuzzy_score + item.frecency_score
+})));
+
+// Remove scorer (use raw fuzzy score)
+nucleo.set_scorer(None);
+```
+
+The scorer output is stored in `Match::external_score` and used as the primary sort key.
+
+### Match Struct Changes
+
+The `Match` struct now has an additional field:
+
+```rust
+pub struct Match {
+    pub score: u32,           // Raw fuzzy match score
+    pub external_score: u32,  // Scorer output (used for sorting)
+    pub idx: u32,             // Item index
+}
+```
+
+Results are sorted by `external_score` (descending), with tie-breakers on item length and index.
+
+### Use Case: Frecency Ranking
+
+This fork was created to support frecency-based ranking in [Atuin](https://github.com/atuinsh/atuin). The typical pattern is:
+
+1. Store metadata (frecency scores, categories) in a separate data structure
+2. Use filter callback to exclude items that don't match the current context
+3. Use scorer callback to combine fuzzy score with frecency at query time
+
+```rust
+// External data store
+let metadata: Arc<DashMap<String, ItemMetadata>> = /* ... */;
+
+// Filter: only show items used in current directory
+let dir = current_dir.clone();
+let meta = metadata.clone();
+nucleo.set_filter(Some(Arc::new(move |cmd: &String| {
+    meta.get(cmd).map(|m| m.used_in_dir(&dir)).unwrap_or(false)
+})));
+
+// Scorer: combine fuzzy score with frecency
+let meta = metadata.clone();
+nucleo.set_scorer(Some(Arc::new(move |cmd: &String, fuzzy_score| {
+    let frecency = meta.get(cmd).map(|m| m.frecency()).unwrap_or(0);
+    fuzzy_score + (frecency * 10)
+})));
+```
+
+---
+
+The original Nucleo readme follows.
+
+---
 
 
 `nucleo` is a highly performant fuzzy matcher written in Rust. It aims to fill the same use case as `fzf` and `skim`. Compared to `fzf` `nucleo` has a significantly faster matching algorithm. This mainly makes a difference when matching patterns with low selectivity on many items. An (unscientific) comparison is shown in the benchmark section below.