@uehaj/sys1grep 0.5.0-next.1 → 0.5.0-next.2

package/README.ja.md

@@ -4,6 +4,8 @@
 
 背景と設計の解説: [Jevのキラーアプリ、「意味で探す grep」を作った（Zenn）](https://zenn.dev/uehaj/articles/jev-semgrep-grep-by-meaning)
 
+> **semgrep から改名しました（0.5.0）。** 理由は 2 つです。1 つは、静的解析ツール [Semgrep](https://semgrep.dev/) の商標と名前が衝突すること。もう 1 つは、このツールがもともと Jev 専用ではなく、System 1 モデル全般を対象にしていることです。TypeSafe AI が Jev の後に Jev 以外の名前で出すかもしれないモデルにも対応したいです :)。そこで 0.5.0 から **sys1grep**（System 1 + grep）になりました。npm パッケージは `@uehaj/sys1grep`（旧 `@uehaj/semgrep`）、コマンドは `sys1grep` / `git sys1grep`、環境変数は `SYS1GREP_*`、設定ファイルは `~/.config/sys1grep/.env` です。旧 `SEMGREP_*` と `~/.config/semgrep/.env` は 1 マイナーリリースの間は読み、使うたびに非推奨の 1 行を出します（1.0.0 で廃止）。詳細は [CHANGELOG](CHANGELOG.md#renamed)。Zenn 記事の URL は旧 slug のままです。
+
 正規表現ではなく **意味** で行を探す grep です。
 判定には [TypeSafe AI](https://typesafe.ai/) の System One モデル **Jev** を使います。
 Jev は文章を生成せず、typed な質問に確率だけを返すモデルなので、1 行ごとに
@@ -13,9 +15,9 @@ Jev は文章を生成せず、typed な質問に確率だけを返すモデル
 ./sys1grep -n -e "顧客が怒っている、または不満を持っている" tickets.txt
 ```
 
-[![sys1grep のデモ: 日本語の意味で 6 言語の返金要求を探す / 「返金について」と「返金を求めている」の違い / -Q で答えを探す](docs/demo.svg)](https://uehaj.github.io/jev-semgrep/)
+[![sys1grep のデモ: 日本語の意味で 6 言語の返金要求を探す / 「返金について」と「返金を求めている」の違い / -Q で答えを探す](docs/demo.svg)](https://sys1grep.js.org/)
 
-<sub>▶ デモをクリックするか <a href="https://uehaj.github.io/sys1grep/">uehaj.github.io/sys1grep</a> を開くと、ランディングページで全編のデモが見られます。</sub>
+<sub>▶ デモをクリックするか <a href="https://sys1grep.js.org/">uehaj.github.io/sys1grep</a> を開くと、ランディングページで全編のデモが見られます。</sub>
 
 - 依存ゼロ。1 ファイル、Node.js 20.16 以降と `fetch` だけで動きます。
 - 速い。30 行を 1 リクエストにまとめ、8 本並列で投げます。210 行のファイルが 1 秒弱で終わります。
@@ -168,7 +170,8 @@ Jev に送る行が増えるほど、費用も時間もかかります。いち
   尋ねられます。空行は送りません。`-M`/`--max-columns`（既定 2000、`-z` なら 8000）を超える行は、
   先頭からその文字数までだけを送ります。判定はそれでも行われ、超えた先にしか無い一致だけが見つかりません。
 - **何回判定するか。** [`--dedup`](#テンプレートごとに-1-行だけ判定する---dedup) は、ID・数値・時刻・パスだけが
-  違う行をまとめて、テンプレートごとに 1 行だけ判定します。
+  違う行をまとめて、テンプレートごとに 1 行だけ判定します。`auto`/`always`/`never`、当面は既定で off。
+  `--dedup=auto` が割に合うときはヒントを出します。
 - **払う前に確かめる。** `--dry-run` は何も送らず、この検索が使う設定、検索するファイル、ファイルごとの
   送る行数、各リクエストとその質問を表示します。最後の行には入力トークン数と、TypeSafe 本体なら料金の
   見積もりが出ます（`~3178 input tokens, ~$0.000133`。誤差 1 割程度）。`-i` は同じ集計を端末に出し、
@@ -602,12 +605,70 @@ $ git config diff.golang.xfuncname '^(func|type)[[:space:]]'
 `-M` の既定は `-z` と同じ 8000 文字で、それより長い関数は先頭 8000 文字で判定します。`--chunk` は関数の数、
 `-A`/`-B`/`-C` と `-c` は文の単位と同じく行の数を数えます。`-z`・`-g`・`-o` とは併用できません。
 
+### 関数から関数へたどる (`--step-to`)
+
+コードについての問いは、2 段になることがよくあります。`--summarize` はどこで行をツールに渡しているか。そして、
+それが失敗したらどうなるか。2 段目の「それ」は 1 段目で見つけたものです。多段階マッチングは両方を 1 回で
+答えます。`--step-to` の前の式で開始点を探し、そこから呼び出しをたどり、たどり着いた関数のうち `--step-to` の
+後ろの式に当たるものを選びます。2 つの式は Jev が判定します。どの呼び出しをたどるかはスコアで決めません。
+
+```sh
+$ sys1grep -e "--summarize が行をツールに渡している" --step-to "ツールの起動や応答が失敗したときの処理" sys1grep.mjs
+```
+
+意味は、最初の例のようにダッシュで始めてもかまいません。`-e`・`-a`・`-v`・`-Q` のどの検索でも同じです。`-` で始まる値は、オプションでなければ意味として扱います（オプションには空白が入りません）。
+
+パスは木の形で出ます。ホップ数 (開始点からの呼び出しの数)、`file:line`、関数名の順で、終点の後ろは `:`、途中の
+関数の後ろは `-` です (grep が一致行と文脈行を分けるのと同じ)。開始と終点の式が正規表現だけなら何も送らないので、
+無料で到達可能性を調べられます。Python 3.6 の `json` で、`load` からたどり着き `raise` を含む関数:
+
+```
+$ cd /usr/lib64/python3.6/json && sys1grep -e '/^\s*def load\b/' --step-to '/\braise\b/' *.py
+sys1grep: walk: 1 at hop 0, 1 at hop 1, 3 at hop 2, 1 at hop 3, 1 at hop 4, 1 at hop 5; stopped: no new unit
+0 __init__.py-274-load
+  1 __init__.py:302:loads
+    2 decoder.py:334:decode
+      3 decoder.py:345:raw_decode
+        4 scanner.py-65-scan_once
+          5 scanner.py:28:_scan_once
+```
+
+- **式。** `--step-to` の前の式が開始の式で、普通の検索と同じです。後ろの `-e` / `-a` / `-v` / `-Q` はすべて終点の式です。
+  `--step-to 意味` と `--step-to '/RE/'` は `--step-to -e ...` と同じで、ファイル名はその後に置きます。step はホップでは
+  なく検索の段です。間に何ホップあっても、`--step-to` 1 つで 2 段です。
+- **辺。** `--edges` が無ければ単位は関数 (`--unit=function`) で、辺は呼び出しです。関数本体 (コメント・docstring・
+  文字列は除く) の `名前(` が、その名前の関数すべてにつながります。名前は関数名の行 (デコレータの下の `def`) から
+  取ります。`--edges=FILE` は別の関係をたどります。1 行 1 本で `FROM_FILE:LINE<TAB>FROM_NAME<TAB>TO_FILE:LINE<TAB>TO_NAME`、
+  行はそれを含む単位を指します。`--reverse` は辺を逆にたどります (呼ばれる側から呼ぶ側へ)。
+- **歩き方。** すべての開始点から同時に幅優先でたどります。関数のホップ数は、どれかの開始点からの最短距離です。
+  各関数には 1 度しか着かないので、循環しても止まります。`--hops=N`・`--hops=M..N`・`--hops=M..` で終点のホップ数を
+  選びます (既定 `0..`。終点の式に当たる開始点はホップ 0 の終点)。終点に着かないパスは出しません。stderr には
+  ホップごとにたどり着いた関数の数と、止まった理由 (新しい関数が無い、または `--hops`) を出します。
+- **費用。** Jev はまずすべての関数を開始の式と 1 回のバッチで照らし、次に `--hops` の範囲でたどり着いた関数を
+  終点の式ともう 1 回のバッチで照らします。`--max-cost` は 2 回目の前にも、1 回目の分を含めて確かめます。
+  `--dry-run` はどの問いにも 0 と答えるので、開始の式が当たりうる関数すべてから歩き、その上限を見せます。
+- **併用できない**のは `-z`・`-g`・`-o`・`-c`・`-l`・`-A`/`-B`/`-C`・`--rank`・`--summarize`・`--dedup` です。
+  `-p` は終点の式と照らした関数にその確率を足し、`-q` は何も出さず、終点があれば終了コード 0 にします。
+
 ### テンプレートごとに 1 行だけ判定する (`--dedup`)
 
 費用は送るテキストの量に比例します。機械が吐くログの大半は、ID や数値だけが違う同じ骨格の繰り返しです。
 `--dedup` は ID・ハッシュ・数値・日付と時刻・パス・URL をマスクして行をまとめ、グループごとに 1 行だけ送って、
 その答えを残りの行にも使います。送るのはその行の原文で、出力も各行がそのまま出ます。
 
+`--dedup` は `auto`・`always`・`never` を取り、裸の `--dedup` は `--dedup=always` です。**当面の既定は
+`never`**（#143）。`auto` は、実運用の統計が既定にしてよいと言うまで見送ります。それでも毎回、送る前に
+ローカルで、全種類を縮めた場合（最良のケース）にどれだけ浮くかを見積もり、それが `--dedup` 自身の質問の
+費用の 2 倍以上なら stderr に一行ヒントを出します。
+
+```
+$ sys1grep -e "a request failed" app.log
+sys1grep: 2040 units fold to at most 31 templates; --dedup=auto would save ~68 requests (~44k tokens)
+```
+
+`--dedup=auto` はその見積もりが割に合うときだけ尋ねてまとめます。ほとんど縮まないファイルは、追加のリクエスト
+なしに全行を送ります。`--verbose`・`--dry-run` はどの値でもこの判定と数字を表示します。
+
 ```sh
 $ ./sys1grep --dedup -n -e "a request failed" app.log
 1:worker request 3fa9c1e27b failed: connection reset
@@ -656,9 +717,11 @@ $ sys1grep -r -n --summarize -e "API キーをファイルから読んでいる"
 - `-n`・`-A/-B/-C`・`-p`・ファイル名は表示どおりに渡し、色は付けません。一致がなければ何も渡しません（終了コード 1）。
 - `SYS1GREP_SUMMARIZER` は値を付けない `--summarize` の TOOL を、`SYS1GREP_SUMMARIZER_MODEL` はそのモデルを決めます。
 - `-q`・`-l`・`-c` は行を出さないので、一緒には使えません。
+- `SYS1GREP_OPTS` に書くとすべての検索を要約するので、一致した行は毎回 TOOL の提供元へも送られます。
+  1 回だけ止めるには `--no-summarize` を付けます。
 - 答えはプレーンテキストです。何も言わなければ LLM は Markdown で書き、端末では雑音になるので、plain を頼みます。
-  `--summarize-format=markdown` か `=html` でそれらを頼めます（`… --summarize-format=html … > summary.html`）。
-  答えは確かめずにそのまま表示します。`SYS1GREP_OPTS` に書けば常用の設定になり、`--summarize` が無いときは無視します。
+  `--format=markdown` か `=html` でそれらを頼めます（`… --format=html … > summary.html`）。
+  答えは確かめずにそのまま表示します。`SYS1GREP_OPTS` に書けば常用の設定になり、`--summarize` も `--rank` も無いときは無視します。
 - `--dedup` では、Jev に送ったものと同じく、テンプレートごとの代表を 1 回だけ `(×N like it)` を付けて渡します。
   答えを使い回したすべての行は渡しません。
 - 200 KB（約 5 万トークン）を超えるときは何も渡さず、大きさを示して終了コード 2 で止まります。TOOL の費用がかかる前です。
@@ -671,7 +734,7 @@ $ sys1grep -r -n --summarize --summarize-prompt="3 行以内で。どのファ
     -e "API キーをファイルから読んでいる" .
 ```
 
-`--summarize` が要ります。空の TEXT は指定しないのと同じです。`--summarize-format` の文より後に置くので、TEXT で書式を上書きできます。
+`--summarize` が要ります。空の TEXT は指定しないのと同じです。`--format` の文より後に置くので、TEXT で書式を上書きできます。
 
 他の TOOL:
 
@@ -690,6 +753,92 @@ OpenAI 互換サーバ全般です。3 つとも `SYS1GREP_SUMMARIZER_MODEL` が
 （Jev 用の `SYS1GREP_API_KEY` は送りません）。`OLLAMA_HOST` で ollama 側のホストを変えられます
 （`ollama` CLI 自体と同じ）。
 
+### 良いものから順に出す (`--rank`)
+
+一致は grep と同じくファイル順に出ます。多いときは `--rank` で、結果を良いものから順に、番号付きの見出しの下に
+出せます。結果とは一致とその `-A/-B/-C` の行で、文脈が接する一致は 1 つの結果になります。
+
+```sh
+$ sys1grep -n -C1 --rank -e "返金を断られた" tickets/
+1. tickets/b.txt
+tickets/b.txt-2-注文番号 1234、2026-08-01 注文。
+tickets/b.txt:3:注文から 30 日を過ぎているため、返金はお受けできません。
+tickets/b.txt-4-サポートまでご連絡ください。
+
+2. tickets/a.txt
+tickets/a.txt-11-注文番号 88 が届きました。
+tickets/a.txt:12:返金のご依頼を受け付けました。
+tickets/a.txt-13-確認いたします。
+```
+
+- `--rank` は `--rank=jev` です。検索の後、各結果（行と文脈をまとめて）が否定でない意味に関係するかを Jev に
+  聞きます。結果ごとに質問が 1 つ増え、1 リクエストに `--chunk` 個まとめます。どんな結果があるかは検索の後で
+  しか分からないので、`--dry-run` / `-i` は上限を出します。
+- `--rank=match` は結果の中で最も高い一致の確率で並べ、リクエストを送りません。1 行ずつの yes/no の答えなので、
+  はっきりした一致どうしは近い値になり、文脈も読みません。
+- `-p` は見出しに点数を付けます（`1. [0.96] tickets/b.txt`）。`-l` は最良の結果の順にファイル名を出します。
+- `--format=markdown` は結果ごとに `## 1. tickets/b.txt` の見出しとコードブロックを、`--format=html` はテンプレート
+  （下記）から 1 つの自己完結した HTML 文書を書きます。ライトとダークに対応し、結果ごとに関連度のバーが付きます。
+  行は表示どおりで、エスケープし、色は付けません。
+- `--summarize` には順位どおりに渡します。`--dedup` では代表 1 つが 1 つの結果です。
+- 意味が要ります（正規表現・`!`・`-v` だけでは並べられない）。`-c`・`-o`・`-q` とは併用できません。
+  `--no-rank` はそれより前の `--rank`（`SYS1GREP_OPTS` のものなど）を取り消します。
+
+### HTML のテンプレート (`--template`)
+
+`--rank --format=html` と `--summarize --format=html` はテンプレートを埋めて書きます。同梱は 4 つで、`default`、`print`（白地に黒の明朝系、
+紙と PDF 向け）、`search`（Web 検索エンジン風の結果ページ）、`terminal`（暗い背景の等幅）です。`--template=NAME` で選び、環境変数か
+`~/.config/sys1grep/.env` の `SYS1GREP_TEMPLATE` で既定を決められます。
+
+```sh
+$ sys1grep -r -n -C1 --rank -p --format=html --template=print -e "返金を断られた" tickets/ > refunds.html
+```
+
+テンプレートは 1 つの HTML ファイルです。`<!--result-->` と `<!--/result-->` の間を結果ごとに繰り返し、
+その前と後は 1 回だけ書きます。次の文字列をエスケープした値に置き換え、それ以外の `{{…}}` はそのまま残します。
+
+| 置き換える文字列 | 使える場所 | 値 |
+|---|---|---|
+| `{{title}}` | どこでも | `sys1grep: ` と意味 |
+| `{{query}}` | どこでも | 意味。`"refund" and not "policy"` の形 |
+| `{{count}}` | どこでも | 結果の数（`--summarize` では一致した行の数） |
+| `{{answer}}` | どこでも | `--summarize` の答え。`--rank` では空 |
+| `{{rank}}` | 結果ごと | 1, 2, … |
+| `{{score}}` | 結果ごと | `-p` が出す形の点数（`0.96`）。`-p` が無ければ空 |
+| `{{score_pct}}` | 結果ごと | 点数を 0〜100 の整数にしたもの。`-p` が無くても入る（バーには `style="--s:{{score_pct}}"`） |
+| `{{file}}` | 結果ごと | ファイル名。1 ファイルだけを探したときは空 |
+| `{{lines}}` | 結果ごと | 結果の行。表示どおり |
+
+`--template=NAME` は `~/.config/sys1grep/templates/NAME.html` があればそれを、無ければ同梱のものを読みます。
+なので自分の `default` を置けば同梱のものに代わります。`/` を含むか `.html` で終わる値はファイルのパスです。
+自分のものを作るには、同梱のものをコピーして編集します。
+
+```sh
+$ sys1grep --install-templates            # ファイルごとに "copied PATH"
+$ cp ~/.config/sys1grep/templates/default.html ~/.config/sys1grep/templates/team.html
+$ sys1grep -r --rank --format=html --template=team -e "..." src/ > out.html
+$ sys1grep --template=list                # 1 行に 1 つの名前。~/.config のものには "(user)"
+```
+
+`{{score_pct}}` は `-p` が無くても入るので、数字を出さずに関連度をバーで見せられます。
+
+`--summarize --format=html` では TOOL に平文を書かせ、その答えを、終わってからエスケープして `{{answer}}` に入れます。
+`<!--result-->` と `<!--/result-->` の間は書きません。`--summarize` で使うテンプレートには、その外に `{{answer}}`
+が要ります（同梱のものにはあります。`--rank` のときは空）。
+
+```sh
+$ sys1grep -r --summarize --format=html --template=print -e "返金を断った理由" tickets/ > why.html
+```
+
+テンプレートは信頼したローカルの入力として扱います。指定したパスやテンプレートのディレクトリにあるシンボリック
+リンクはそのまま読み、エスケープするのは埋め込む結果だけです。
+
+`--install-templates` は既にあるファイルを上書きしません（そのファイルには `kept` と出します）。テンプレートが
+見つからない、あるいは `<!--result-->` 1 つの後に `<!--/result-->` 1 つ、になっていないときは、そのファイルを
+示して終了コード 2 です。コマンドラインの `--template` には、`--rank` か `--summarize` と `--format=html` が要ります（`-l` とは併用不可）。
+`SYS1GREP_TEMPLATE` はそれ以外では使われないだけです。`--template=list` と `--install-templates` は他の引数と
+併用できず、`SYS1GREP_OPTS` には書けません。
+
 ## Claude Code から使う
 
 sys1grep を代わりに走らせてくれる Claude Code のスキルがあります。探したいものを言葉で書くと、式を組み立てて
@@ -770,6 +919,10 @@ usage: sys1grep [OPTION]... -e MEANING|-Q QUESTION [-a MEANING] [-v MEANING]...
                --unit=sentence-by-* と併用すると、レコードごとに文に分ける
   --unit=sentence-by-jev|sentence-by-rule  行ではなく文ごとに判定する (前述の「1 文ずつ判定する」を参照)
   --unit=function  関数ごとに判定し、当たった関数の行を出す (前述の「関数ごとに判定する」を参照)
+  --step-to 式  前の式に当たる関数から呼び出しをたどり、後ろの式に当たる関数までのパスを出す
+               (前述の「関数から関数へたどる」を参照)
+  --edges=FILE 呼び出しの代わりに FILE の辺をたどる。--reverse は逆向きにたどる
+  --hops=N|M..N|M..  終点のホップ数 (既定 0..)
   -o           --unit=sentence-by-* と併用し、当たった文だけを出す
   -p           各意味の確率を行末に表示 (閾値調整用)
   --dry-run    何も送らず、この検索が使う設定 (コマンドラインでなければその出どころも)・検索するファイル・
@@ -785,7 +938,14 @@ usage: sys1grep [OPTION]... -e MEANING|-Q QUESTION [-a MEANING] [-v MEANING]...
   --max-cost=USD  送る予定の入力を見積もって値段を出す。超えれば (既定 1) 端末で続けるか聞く。
                -y は聞かずに yes と答える。端末が無く超えていれば終了コード 2、-q でも変わらない
                (スクリプトからは -y)。-i は無条件かつこれより前に聞くので二重には聞かない
-  --dedup      テンプレートごとに 1 行だけ判定し、その答えを残りにも使う (前述の「テンプレートごとに 1 行だけ判定する」を参照)
+  --dedup[=auto|always|never]  テンプレートごとに 1 行だけ判定し、その答えを残りにも使う (当面の既定は never。
+               前述の「テンプレートごとに 1 行だけ判定する」を参照)
+  --rank[=jev|match]  結果 (一致とその文脈) を良いものから順に番号付きの見出しの下に出す。jev (値なしの
+               --rank) は各結果を Jev に聞き、match は最も高い一致の確率で並べる (前述の「良いものから順に出す」を参照)。--no-rank でファイル順
+  --template=NAME  --rank か --summarize の --format=html が書く文書。~/.config/sys1grep/templates/NAME.html、無ければ同梱のもの
+               (default, print, terminal)、またはファイル。既定は SYS1GREP_TEMPLATE、無ければ default。
+               --template=list は名前を出す (前述の「HTML のテンプレート」を参照)
+  --install-templates  同梱のテンプレートを ~/.config/sys1grep/templates へコピーする。既にあるファイルは残す
   --color[=WHEN] 色付け。auto (端末なら付ける、既定) / always / never。=WHEN 省略時は auto
                ファイル名・行番号は grep と同じ配色。-p の確率は閾値以上を緑、
                否定側の閾値未満を赤、あいだを黄で表示。NO_COLOR にも従う

package/README.md

@@ -4,6 +4,8 @@
 
 Background and design notes (Japanese): [Jevのキラーアプリ、「意味で探す grep」を作った](https://zenn.dev/uehaj/articles/jev-semgrep-grep-by-meaning) on Zenn.
 
+> **Renamed from semgrep (0.5.0).** Two reasons. The name collided with the static-analysis tool [Semgrep](https://semgrep.dev/), a trademark. And the tool was never meant for Jev alone: it targets System 1 models in general, and I'd like it to work with any models TypeSafe AI may release after Jev under other names :). So from 0.5.0 this is **sys1grep** (System 1 + grep): npm package `@uehaj/sys1grep` (was `@uehaj/semgrep`), commands `sys1grep` / `git sys1grep`, environment `SYS1GREP_*`, config `~/.config/sys1grep/.env`. The old `SEMGREP_*` names and `~/.config/semgrep/.env` still work for one minor release, each use printing a deprecation line; 1.0.0 drops them. Details: [CHANGELOG](CHANGELOG.md#renamed). The Zenn article's URL keeps its old slug.
+
 A grep that finds lines by **what they mean**, not by regular expressions.
 Matching is done by **Jev**, the System One model from [TypeSafe AI](https://typesafe.ai/).
 Jev does not generate text. It answers typed questions with probabilities, so for every line
@@ -14,9 +16,9 @@ and applies a threshold.
 ./sys1grep -n -e "customer is angry or frustrated" tickets.txt
 ```
 
-[![sys1grep demo: a Japanese meaning finds refund requests in six languages; "asking for a refund" vs "about a refund"; -Q finds the answer](docs/demo.svg)](https://uehaj.github.io/jev-semgrep/)
+[![sys1grep demo: a Japanese meaning finds refund requests in six languages; "asking for a refund" vs "about a refund"; -Q finds the answer](docs/demo.svg)](https://sys1grep.js.org/)
 
-<sub>▶ Click the demo, or open <a href="https://uehaj.github.io/sys1grep/">uehaj.github.io/sys1grep</a>, for the full demo on the landing page.</sub>
+<sub>▶ Click the demo, or open <a href="https://sys1grep.js.org/">uehaj.github.io/sys1grep</a>, for the full demo on the landing page.</sub>
 
 - Zero dependencies. One file, Node.js 20.16+ and `fetch`.
 - Fast. 30 lines go into one request, requests run 8 at a time. A 210-line file finishes in under a second.
@@ -180,7 +182,8 @@ to the narrowest:
   its AND term's meanings. Blank lines are never sent. Only the first `-M`/`--max-columns` characters of a line
   (default 2000, 8000 with `-z`) are sent: it is still searched and judged, just not past that cutoff.
 - **How many times.** [`--dedup`](#one-line-per-template---dedup) judges one line per template: lines that
-  differ only in ids, numbers, times or paths share one answer.
+  differ only in ids, numbers, times or paths share one answer. `auto`/`always`/`never`, off by default for
+  now: a hint says when `--dedup=auto` would pay.
 - **Check before paying.** `--dry-run` sends nothing and prints the settings the search would run with, the
   files, how many lines each would send and every request with its questions. Its last line estimates the input
   tokens and, for TypeSafe itself, the price (`~3178 input tokens, ~$0.000133`; within about 10%). `-i` shows the
@@ -620,6 +623,56 @@ $ git config diff.golang.xfuncname '^(func|type)[[:space:]]'
 `--chunk` counts functions, `-A`/`-B`/`-C` and `-c` count lines, as with the sentence units. `-z`, `-g` and
 `-o` are refused.
 
+### From one function to another (`--step-to`)
+
+A question about code often comes in two steps: where does `--summarize` hand the lines to the tool, and then,
+what happens when that fails. The "that" in the second step is what the first one found. Multi-step matching
+answers both in one run: the expression before `--step-to` finds the start, sys1grep walks the calls from it,
+and the expression after `--step-to` picks the functions it reaches that match. Jev judges the two
+expressions; no score decides which call to follow.
+
+```sh
+$ sys1grep -e "--summarize hands the lines to the tool" --step-to "what happens when the tool fails to start or answer" sys1grep.mjs
+```
+
+A meaning may start with a dash, as the first one does, on any search and for `-e`, `-a`, `-v` and `-Q`: a value that starts with `-` is taken as the meaning unless it is an option (an option holds no space).
+
+Each path prints as a tree: the hop (the number of calls from the start), `file:line` and the function's name,
+`:` after an end and `-` after a function on the way, as grep marks a match and its context. A regex-only
+start and end send nothing, which makes a free reachability search. In Python 3.6's `json`, the functions
+that `load` reaches and that hold a `raise`:
+
+```
+$ cd /usr/lib64/python3.6/json && sys1grep -e '/^\s*def load\b/' --step-to '/\braise\b/' *.py
+sys1grep: walk: 1 at hop 0, 1 at hop 1, 3 at hop 2, 1 at hop 3, 1 at hop 4, 1 at hop 5; stopped: no new unit
+0 __init__.py-274-load
+  1 __init__.py:302:loads
+    2 decoder.py:334:decode
+      3 decoder.py:345:raw_decode
+        4 scanner.py-65-scan_once
+          5 scanner.py:28:_scan_once
+```
+
+- **The expressions.** The expression before `--step-to` is the start's, as in any search; every `-e` / `-a` /
+  `-v` / `-Q` after it is the end's. `--step-to MEANING` and `--step-to '/RE/'` are `--step-to -e ...`; the file
+  names follow. A step is a search, not a hop: one `--step-to` is two steps, whatever the hops between them.
+- **The edges.** Without `--edges` the unit is a function (`--unit=function`) and an edge is a call: `name(` in
+  a function's body, its comments, docstrings and strings left out, links to every function of that name. A name
+  comes from the funcname line (the `def` under a decorator). `--edges=FILE` walks any other relation instead,
+  one edge per line, `FROM_FILE:LINE<TAB>FROM_NAME<TAB>TO_FILE:LINE<TAB>TO_NAME`; a line stands for the unit that
+  holds it. `--reverse` walks the edges backwards, callee to caller.
+- **The walk.** Breadth first from every start at once. A function's hop is its shortest distance from any
+  start, and each function is reached once, so a cycle ends. `--hops=N`, `--hops=M..N` and `--hops=M..` pick the
+  hops an end may be at (default `0..`: a start that matches the end expression is an end at hop 0). A path that
+  reaches no end is left out. stderr says how many functions each hop reached and why the walk stopped: no new
+  function, or `--hops`.
+- **The cost.** Jev judges every function against the start expression in one batch, then the functions reached
+  within `--hops` against the end expression in another. `--max-cost` asks again before the second, counting the
+  first. `--dry-run` answers every question 0, so it walks from every function the start expression could hold
+  for and shows that bound.
+- **Not with** `-z`, `-g`, `-o`, `-c`, `-l`, `-A`/`-B`/`-C`, `--rank`, `--summarize` or `--dedup`. `-p` adds the
+  end expression's scores to each function judged against it; `-q` prints nothing and exits 0 when there is an end.
+
 ### One line per template (`--dedup`)
 
 Cost is proportional to the text sent, and machine-generated logs are mostly one skeleton with a different
@@ -627,6 +680,19 @@ id or number in it. `--dedup` masks ids, hashes, numbers, dates and times, paths
 the result, sends one line per group and reuses its answer for the rest. What is sent is that line's
 original text, and every line is printed as itself:
 
+`--dedup` takes `auto`, `always` or `never`; a bare `--dedup` is `--dedup=always`. **Default is `never`, for
+now** (#143): `auto` is held back until real-run stats say it should be the default. Every run still
+estimates locally, before anything is sent, what folding every kind (the best case) would save, and prints
+one stderr hint when that is worth at least twice the cost of `--dedup`'s own question:
+
+```
+$ sys1grep -e "a request failed" app.log
+sys1grep: 2040 units fold to at most 31 templates; --dedup=auto would save ~68 requests (~44k tokens)
+```
+
+`--dedup=auto` asks and folds only when that estimate says it pays; a file that barely repeats sends every
+line, asking nothing extra. `--verbose` / `--dry-run` print the decision and its numbers for every value.
+
 ```sh
 $ ./sys1grep --dedup -n -e "a request failed" app.log
 1:worker request 3fa9c1e27b failed: connection reset
@@ -675,9 +741,11 @@ $0.094 to $0.013, with the same answer (#69). It pays when the answer sits in a
 - `-n`, `-A/-B/-C`, `-p` and file names go in as they would print; colors never do. No match runs nothing (exit 1).
 - `SYS1GREP_SUMMARIZER` picks the TOOL of a bare `--summarize`, `SYS1GREP_SUMMARIZER_MODEL` its model.
 - `-q`, `-l` and `-c` print no lines, so they cannot be combined with it.
+- In `SYS1GREP_OPTS` it summarizes every search, so every match goes to TOOL's provider too;
+  `--no-summarize` turns it off for one search.
 - The answer is plain text: an LLM that is not told writes Markdown, noise on a terminal, so plain is asked for.
-  `--summarize-format=markdown` or `=html` asks for those instead (`… --summarize-format=html … > summary.html`).
-  The answer prints as it comes, unchecked. In `SYS1GREP_OPTS` it is a standing preference, ignored without `--summarize`.
+  `--format=markdown` or `=html` asks for those instead (`… --format=html … > summary.html`).
+  The answer prints as it comes, unchecked. In `SYS1GREP_OPTS` it is a standing preference, ignored without `--summarize` or `--rank`.
 - With `--dedup`, the TOOL gets what Jev got: each template's representative once, marked `(×N like it)`,
   not every line its answer was reused for.
 - More than 200 KB (about 50k tokens) is not sent at all: exit 2, with the size, before the TOOL is paid.
@@ -690,7 +758,7 @@ $ sys1grep -r -n --summarize --summarize-prompt="3 lines or fewer, just which fi
     -e "the API key is read from a file" .
 ```
 
-It needs `--summarize`; empty TEXT is the same as leaving it out. It comes after the `--summarize-format` sentence,
+It needs `--summarize`; empty TEXT is the same as leaving it out. It comes after the `--format` sentence,
 so TEXT can override the format.
 
 Other TOOLs:
@@ -709,6 +777,93 @@ OpenAI-compatible server. All three need `SYS1GREP_SUMMARIZER_MODEL`: none has a
 `SYS1GREP_SUMMARIZER_API_KEY` goes as `Authorization: Bearer` to a URL TOOL only (never `SYS1GREP_API_KEY`,
 which is Jev's). `OLLAMA_HOST` moves ollama's host, as it does for the `ollama` CLI itself.
 
+### Best first (`--rank`)
+
+Matches print in file order, as grep prints them. With many, `--rank` prints the results best first, each under a
+numbered header. A result is a match with its `-A/-B/-C` lines; matches whose context touches are one result.
+
+```sh
+$ sys1grep -n -C1 --rank -e "the refund was refused" tickets/
+1. tickets/b.txt
+tickets/b.txt-2-Order #1234, placed 2026-08-01.
+tickets/b.txt:3:Your refund was declined: the order is older than 30 days.
+tickets/b.txt-4-Please contact support.
+
+2. tickets/a.txt
+tickets/a.txt-11-Order #88 arrived.
+tickets/a.txt:12:Refund request received.
+tickets/a.txt-13-We will check it.
+```
+
+- `--rank` is `--rank=jev`: after the search, Jev is asked of each result, lines and context together, whether it
+  is relevant to the meanings that are not negated. One more question per result, `--chunk` results to a request;
+  `--dry-run` / `-i` show an upper bound, since which results there are is known only after the search.
+- `--rank=match` sorts by each result's highest match probability, with no request. It is the answer to a yes/no
+  question on one line, so clear matches sit close together, and the context is not read.
+- `-p` puts the score on the header (`1. [0.96] tickets/b.txt`). `-l` lists the files by their best result.
+- `--format=markdown` writes a `## 1. tickets/b.txt` heading and a fenced block per result; `--format=html` one
+  self-contained HTML document from a template (below), light and dark, with a relevance bar per result. The lines
+  are as they print, escaped and uncolored.
+- `--summarize` gets the results in ranked order; with `--dedup` a representative is one result.
+- It needs a meaning (a regex, `!` or `-v` alone ranks nothing), and cannot be combined with `-c`, `-o` or `-q`.
+  `--no-rank` turns off an earlier one, from `SYS1GREP_OPTS` say.
+
+### HTML templates (`--template`)
+
+`--rank --format=html` and `--summarize --format=html` fill in a template. Four come with sys1grep: `default`, `print` (black on white, serif,
+for paper and PDF), `search` (a results page like a web search engine's) and `terminal` (dark monospace).
+`--template=NAME` picks one; `SYS1GREP_TEMPLATE`, in the
+environment or `~/.config/sys1grep/.env`, sets the default.
+
+```sh
+$ sys1grep -r -n -C1 --rank -p --format=html --template=print -e "the refund was refused" tickets/ > refunds.html
+```
+
+A template is one HTML file. The part between `<!--result-->` and `<!--/result-->` is repeated for each result;
+what is before and after it is written once. sys1grep replaces these, escaped, and leaves any other `{{…}}` as
+written:
+
+| placeholder | where | value |
+|---|---|---|
+| `{{title}}` | anywhere | `sys1grep: ` and the meanings |
+| `{{query}}` | anywhere | the meanings, as in `"refund" and not "policy"` |
+| `{{count}}` | anywhere | the number of results (with `--summarize`, of matching lines) |
+| `{{answer}}` | anywhere | `--summarize`'s answer; empty with `--rank` |
+| `{{rank}}` | per result | 1, 2, … |
+| `{{score}}` | per result | the score as `-p` prints it (`0.96`); empty without `-p` |
+| `{{score_pct}}` | per result | the score as a whole number 0 to 100, set even without `-p` (for a bar: `style="--s:{{score_pct}}"`) |
+| `{{file}}` | per result | the file name; empty when one file is searched |
+| `{{lines}}` | per result | the result's lines as they print |
+
+`--template=NAME` reads `~/.config/sys1grep/templates/NAME.html` if it is there, else the bundled one, so your
+copy of `default` replaces it. A value containing `/` or ending in `.html` is a file path. To make your own, copy
+the bundled ones and edit:
+
+```sh
+$ sys1grep --install-templates            # "copied PATH" for each file
+$ cp ~/.config/sys1grep/templates/default.html ~/.config/sys1grep/templates/team.html
+$ sys1grep -r --rank --format=html --template=team -e "..." src/ > out.html
+$ sys1grep --template=list                # one name a line, "(user)" after those under ~/.config
+```
+
+`{{score_pct}}` is set even without `-p`, so a bar can show the relevance without printing the number.
+
+With `--summarize --format=html` the TOOL is asked for plain text, and that answer, escaped, goes into `{{answer}}`
+once it has finished; the part between `<!--result-->` and `<!--/result-->` is not written. A template for
+`--summarize` therefore needs `{{answer}}` outside that part (the bundled ones have it; with `--rank` it is empty).
+
+```sh
+$ sys1grep -r --summarize --format=html --template=print -e "why the refunds were refused" tickets/ > why.html
+```
+
+A template is trusted local input: a path you give, or a symlink in the templates directory, is read as it is;
+only the results put into it are escaped.
+
+`--install-templates` never overwrites a file that is already there (it prints `kept` for it). A missing
+template, or one without exactly one `<!--result-->` before one `<!--/result-->`, is exit 2 naming the file.
+`--template` on the command line needs `--format=html` with `--rank` or `--summarize` (not `-l`); `SYS1GREP_TEMPLATE` is simply unused elsewhere.
+`--template=list` and `--install-templates` take no other arguments and are refused in `SYS1GREP_OPTS`.
+
 ## Use it from Claude Code
 
 There is a Claude Code skill that runs sys1grep for you: describe what you are looking for in plain words
@@ -790,6 +945,10 @@ usage: sys1grep [OPTION]... -e MEANING|-Q QUESTION [-a MEANING] [-v MEANING]...
                with --unit=sentence-by-*, each record is split into sentences
   --unit=sentence-by-jev|sentence-by-rule  judge each sentence instead of each line (see "One sentence at a time" above)
   --unit=function  judge each function and print its lines (see "One function at a time" above)
+  --step-to EXPRESSION  print the paths from the functions the expression before it matches, along the
+               calls, to the functions the expression after it matches (see "From one function to another" above)
+  --edges=FILE walk the edges in FILE instead of the calls; --reverse walks them backwards
+  --hops=N|M..N|M..  the hops an end may be at (default 0..)
   -o           with --unit=sentence-by-*, print only the matching sentences
   -p           print each meaning's probability at the end of the line
   --dry-run    send nothing; print the settings the search would run with (and their source, when not the
@@ -805,7 +964,14 @@ usage: sys1grep [OPTION]... -e MEANING|-Q QUESTION [-a MEANING] [-v MEANING]...
   --max-cost=USD  price the input about to be sent; over it (default 1), ask to continue on the terminal; -y
                answers yes without asking; no terminal and the limit exceeded is exit 2, unchanged by -q
                (scripts pass -y); -i already asks unconditionally and earlier, so this does not ask again
-  --dedup      judge one line per template and reuse its answer for the rest (see "One line per template" above)
+  --dedup[=auto|always|never]  judge one line per template and reuse its answer for the rest (default never,
+               for now; see "One line per template" above)
+  --rank[=jev|match]  print the results (a match with its context) best first, under numbered headers; jev
+               (bare --rank) asks Jev of each result, match sorts by its best match probability (see "Best first"); --no-rank: file order
+  --template=NAME  the document --rank or --summarize --format=html writes: ~/.config/sys1grep/templates/NAME.html, else the
+               bundled one (default, print, terminal), or a file; default SYS1GREP_TEMPLATE, else default.
+               --template=list prints the names (see "HTML templates")
+  --install-templates  copy the bundled templates to ~/.config/sys1grep/templates, keeping existing files
   --color[=WHEN] auto (default: color when stdout is a terminal) / always / never; bare --color means auto
                file and line number use grep's colors; with -p, probabilities are
                green at or above the positive threshold, red below the negative one,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uehaj/sys1grep",
-  "version": "0.5.0-next.1",
+  "version": "0.5.0-next.2",
   "description": "grep by meaning, across languages. TypeSafe Jev scores every line against a meaning; combine meanings with AND/OR/NOT.",
   "keywords": [
     "grep",
@@ -29,7 +29,11 @@
     "README.ja.md",
     "docs/color.svg",
     "docs/demo.svg",
-    "docs/sentence.svg"
+    "docs/sentence.svg",
+    "templates/default.html",
+    "templates/print.html",
+    "templates/search.html",
+    "templates/terminal.html"
   ],
   "engines": {
     "node": ">=20.16"
@@ -39,6 +43,8 @@
     "test:offline": "sh tests/offline.sh",
     "judge": "node --no-warnings --env-file-if-exists=.env tests/judge.mts",
     "scope-eval": "node tests/scope-eval.mjs",
+    "dedup-eval": "node tests/dedup-eval.mjs",
+    "skill-eval": "bash tests/skill-eval/run.sh",
     "release": "sh scripts/release.sh"
   }
 }