mdlogbook 0.1.0

data/docs/usage.md

@@ -0,0 +1,778 @@
+# mlb 使い方ガイド
+
+`mlb`は、Markdownで書いた作業記録から勤務時間を集計し、一覧・カレンダー・グラフ・抽出・匿名化形式で表示するCLIツールです。
+
+この文書は、日常的な使い方のガイドであると同時に、入出力やオプションの仕様を確認するためのリファレンスとしても使えるように構成しています。
+
+## この文書の読み方
+
+最初に使い始める場合は、次の順に読むと流れを追いやすくなります。
+
+1. [クイックスタート](#クイックスタート)
+2. [設定](#設定)
+3. [対象期間の指定](#対象期間の指定)
+
+特定の挙動を確認したい場合は、次の節を参照してください。
+
+- 入力ファイルの書式: [入力ファイル形式](#入力ファイル形式)
+- 期間指定の完全なルール: [対象期間の指定](#対象期間の指定)
+- 出力形式ごとの挙動: [出力形式](#出力形式)
+- 利用できるスイッチ一覧: [オプション一覧](#オプション一覧)
+
+## クイックスタート
+
+### 1. 設定ファイルを作成する
+
+はじめに以下のコマンドで設定ファイルの雛型を作成します:
+
+```bash
+mlb --init
+```
+
+設定ファイルは`$XDG_CONFIG_HOME/mdlogbook/config.yml`(`XDG_CONFIG_HOME`未設定時は`~/.config/mdlogbook/config.yml`)に作成されます。`--config`で別のパスを指定することもできます:
+
+```bash
+mlb --config ~/my-config.yml --init
+```
+
+初期内容:
+
+```yaml
+mdlogbook:
+  path: ~/.local/share/mdlogbook/logs
+  # target_hours: 160
+  anonymize:
+    salt: "<ランダムな32文字のhex>"
+```
+
+`path`にログファイルを置くディレクトリを、`target_hours`に月間の基準時間を設定します。`target_hours`は省略可能で、省略すると達成率やRemaining表示、カレンダーのサイン(◎○△×)、折れ線グラフのtargetラインが非表示になります。
+
+`default_view`でデフォルトの表示形式を変更できます(`simple`、`calendar`、`line_chart`、`grid`、`heatmap`)。省略時は`simple`です。コマンドラインで`-s`/`-c`/`-l`/`--grid`/`--heatmap`を指定すると上書きされます。
+
+### 2. ログファイルを書く
+
+ログファイルは日付・作業名・時間帯をMarkdownで記述します:
+
+```markdown
+# 2026-03-01
+## 開発
+* 09:30-12:00 (2.50)
+* 13:00-18:00 (5.00)
+
+# 2026-03-02
+## 会議
+* 10:00-11:30 (1.50)
+## 開発
+* 13:00-19:00 (6.00)
+```
+
+- `# YYYY-MM-DD`で日付を表す
+- `## ...`で作業区分や案件名を表す
+- `* HH:MM-HH:MM (x.xx)`で時間帯と記録時間を表す
+
+括弧内の記録時間と時刻から計算した差分が一致しない場合、`--simple`/`--calendar`では警告がstderrに表示されます。
+
+まとまったサンプルが必要な場合は、[sample-logs/](sample-logs/)に2025年の1年分の例を置いています。
+
+### 3. 当月の記録を確認する
+
+引数なしで実行すると、当月のファイルを自動的に選択して表示します:
+
+```bash
+mlb
+```
+
+表示形式は次のように切り替えられます:
+
+```bash
+mlb -s     # 一覧形式で表示(デフォルト)
+mlb -c     # カレンダー形式で表示
+```
+
+### 4. 記録ファイルを編集する
+
+`-e`オプションで、対象ファイルをエディタで開きます:
+
+```bash
+mlb -e              # 当月ファイルを開く
+mlb -e 2026/3       # 2026年3月のファイルを開く
+mlb -e 2026-03-15   # 2026年3月のファイルを開き、3月15日の行に移動
+```
+
+エディタを閉じた後、編集したファイル全体を検査し、時間帯の重なりや記録時間の不一致があればstderrに警告を表示します。これは`--simple`/`--calendar`で表示される警告と同じ内容です。警告の有無にかかわらず終了コードは0です。
+
+### 5. よく使う期間指定を試す
+
+```bash
+mlb m1            # 先月
+mlb 2026/1        # 2026年1月
+mlb 2026/1 2026/3 # 2026年1〜3月を月別表示
+mlb w..1          # 今週+先週
+mlb D30           # 直近30日間
+```
+
+## 設定
+
+### 設定ファイルの場所
+
+設定ファイルの探索順序は以下のとおりです:
+
+1. `--config=PATH`(コマンドラインオプション)
+2. `MDLOGBOOK_CONFIG`環境変数
+3. `$XDG_CONFIG_HOME/mdlogbook/config.yml`(`XDG_CONFIG_HOME`未設定時は`~/.config/mdlogbook/config.yml`)
+
+```bash
+mlb --config ~/work/config.yml   # コマンドラインで指定
+MDLOGBOOK_CONFIG=~/work/config.yml mlb  # 環境変数で指定
+```
+
+### ログディレクトリの上書き
+
+`--path`で設定ファイルの`path`を一時的に上書きできます:
+
+```bash
+mlb --path /tmp/test-logs    # このディレクトリのログファイルを使用
+```
+
+### プロジェクトごとの設定
+
+設定ファイルには複数のプロジェクトを定義できます:
+
+```yaml
+mdlogbook: &default
+  target_hours: 160
+  path: ~/.local/share/mdlogbook/logs
+project-a:
+  <<: *default
+  path: ~/Documents/project-a
+project-b:
+  <<: *default
+  path: /path/to/work/project-b
+```
+
+使用するプロジェクトは`-p`オプションまたは環境変数`MDLOGBOOK_PROJECT`で指定します。`-p`は環境変数より優先されます。どちらも未設定の場合は`mdlogbook`が使われます。
+
+```bash
+mlb -p project-a          # project-aを使用
+mlb --project=project-a   # 同上
+mlb --list-projects       # 設定済みプロジェクトの一覧を表示
+```
+
+[mise](https://mise.jdx.dev/)や[direnv](https://direnv.net/)と組み合わせてディレクトリごとに自動切り替えできます:
+
+```toml
+# .mise.toml の例
+[env]
+MDLOGBOOK_PROJECT = "project-a"
+MDLOGBOOK_CONFIG = "~/work/config.yml"  # 設定ファイルも切り替え可能
+```
+
+### ファイル命名規則
+
+ログファイルは以下の形式で命名します:
+
+```
+$path/$MDLOGBOOK_PROJECT-YYYY-MM.md
+```
+
+例: `~/.local/share/mdlogbook/logs/mdlogbook-2026-03.md`
+
+1つのファイルには1か月分の記録を書きます。
+
+### エディタの設定
+
+エディタは環境変数`VISUAL`(未設定の場合は`EDITOR`)を参照します。カーソル位置などの追加引数は設定ファイルの`editor_args`で設定します:
+
+```yaml
+mdlogbook:
+  path: ~/logs/mdlogbook
+  target_hours: 160
+  editor_args: "--goto {file}:{line}"  # VS Code
+```
+
+エディタごとの設定例:
+
+```yaml
+# VS Code
+editor_args: "--goto {file}:{line}"
+
+# Vim(当日の日付パターンで検索)
+editor_args: "+/{date} {file}"
+
+# 行番号で開く汎用設定
+editor_args: "+{line} {file}"
+```
+
+複数プロジェクトで同じエディタ設定を共有する場合はYAMLエイリアスが使えます:
+
+```yaml
+default: &default
+  target_hours: 160
+  editor_args: "--goto {file}:{line}"
+
+mdlogbook:
+  <<: *default
+  path: ~/logs/mdlogbook
+
+work:
+  <<: *default
+  path: ~/logs/work
+  editor_args: "+{line} {file}"  # このプロジェクトだけ別の設定
+```
+
+`editor_args`で使えるプレースホルダ:
+
+| プレースホルダ | 内容 |
+|---|---|
+| `{file}` | ファイルのパス |
+| `{line}` | 当日のエントリが始まる行番号 |
+| `{date}` | 当日の日付(`YYYY-MM-DD`形式) |
+
+`editor_args`が未設定の場合、エディタはファイルだけを引数として起動し、カーソル移動は行いません。
+
+## 入力ファイル形式
+
+入力ファイルは、日付見出し・作業見出し・時間帯エントリをMarkdownで並べたものです。
+
+```markdown
+# 2026-03-01
+## 開発
+* 09:30-12:00 (2.50)
+* 13:00-18:00 (5.00)
+
+# 2026-03-02
+## 会議
+* 10:00-11:30 (1.50)
+## 開発
+* 13:00-19:00 (6.00)
+```
+
+各行の意味:
+
+- `# YYYY-MM-DD`: 日付
+- `## ...`: 作業区分や案件名
+- `* HH:MM-HH:MM (x.xx)`: 時間帯と記録時間
+
+入力上の注意:
+
+- 括弧内の記録時間と時刻から計算した差分が一致しない場合、`--simple`/`--calendar`では警告がstderrに表示されます
+- 日をまたぐ時間帯は`23:30-24:30`のように`24:xx`で記述します
+- `23:30-00:30`のような`00:xx`表記も`23:30-24:30`として集計されますが、曖昧さを避けるため警告が表示されます
+
+より長い例は、[sample-logs/](sample-logs/)にある2025年のサンプルログを参照してください。
+
+## 対象期間の指定
+
+対象期間は、明示的な日付・月指定と、現在を基準にした相対指定の両方で指定できます。
+
+### 基本ルール
+
+- 引数なしの場合は当月を対象にします
+- 明示的な月指定(`YYYY/M`)はデフォルトで個別表示されます
+- 相対指定(`d`/`w`/`m`/`q`/`y`/`D`で始まる引数)はデフォルトでまとめて集計されます
+
+### 引数なし(当月)
+
+```bash
+mlb        # 当月($MDLOGBOOK_PROJECT-YYYY-MM.md)
+```
+
+### 明示的な指定
+
+#### 特定の月
+
+`YYYY/M`または`YYYY-M`形式で月を指定します:
+
+```bash
+mlb 2026/3     # 2026年3月
+mlb 2026-03    # 同上(ダッシュ区切り・ゼロ埋めも可)
+```
+
+#### 特定の日
+
+`YYYY-MM-DD`または`YYYY/MM/DD`形式で1日だけを対象にします:
+
+```bash
+mlb 2026-03-15    # 2026年3月15日だけを表示
+mlb 2026/03/15    # 同上(スラッシュ区切り)
+```
+
+#### 月の範囲
+
+引数を2つ指定すると、その範囲の月を対象にします。デフォルトで月別に個別表示します:
+
+```bash
+mlb 2026/1 2026/3          # 2026年1〜3月を月別表示
+mlb 2026-01 2026-03        # 同上(ダッシュ区切り)
+mlb 2026/1 2026/3 --merge  # 同期間を合算表示
+```
+
+#### globパターン
+
+bash/zshのブレース展開と同じ構文で、複雑な月の組み合わせを指定できます。**シェルに展開させないよう、引用符が必要です**:
+
+```bash
+mlb '2025/*'           # 2025年の全月
+mlb '2026/{08..11}'    # 2026年8〜11月
+mlb '2026/{1,3,5}'     # 2026年1・3・5月(列挙)
+mlb '202{4..6}/01'     # 2024〜2026年の1月
+mlb '*/*'              # 現在のプロジェクトの全月(ファイルが存在する月のみ)
+mlb '2026/0*'          # 2026年1〜9月のうちファイルが存在する月
+```
+
+### 相対指定
+
+現在の日時を基準に対象を指定します。
+
+#### 点指定(d / w / m / q / y)
+
+1つのカレンダー単位を指定します。`0`が現在、正の数が過去を表します:
+
+| 記法 | 意味 |
+|---|---|
+| `d` / `d0` | 今日 |
+| `d1` | 昨日 |
+| `d2` | 一昨日 |
+| `w` / `w0` | 今週(月〜日) |
+| `w1` | 先週 |
+| `w2` | 先々週 |
+| `m` / `m0` | 今月 |
+| `m1` | 先月 |
+| `q` / `q0` | 今期(3か月分に展開) |
+| `q1` | 前期 |
+| `y` / `y0` | 今年 |
+| `y1` | 昨年 |
+
+負の数は未来を表します(通常は使いません):
+
+| 記法 | 意味 |
+|---|---|
+| `d-1` | 明日 |
+| `w-1` | 来週 |
+| `m-1` | 来月 |
+| `q-1` | 来期 |
+
+#### 相対globパターン(範囲)
+
+点指定にglobパターンを使うことで複数の単位を指定できます。`{N..M}`の`N`・`M`は大きいほど過去です:
+
+```bash
+mlb 'w{0..1}'    # 今週+先週
+mlb 'm{0..2}'    # 今月+先月+先々月
+mlb 'd{0..6}'    # 今日を含む直近7日間
+mlb 'w{..1}'     # 今週+先週(始点省略=0とみなす)
+mlb 'y{1..}'     # 昨年以前すべて(終点省略=無限の過去)
+```
+
+ブレースなしの簡略記法も使えます。シェルによる展開を気にせずに書けます:
+
+```bash
+mlb w0..1        # 'w{0..1}'と同じ
+mlb m0..2        # 'm{0..2}'と同じ
+mlb w..1         # 'w{..1}'と同じ(始点省略)
+mlb d..          # 'd{0..}'と同じ(終点省略=全履歴)
+mlb d1..         # 'd{1..}'と同じ
+```
+
+#### 期間指定(D)
+
+`D`に日数を続けると、今日を含む直近N日間を指定します:
+
+```bash
+mlb D7     # 直近7日間
+mlb D30    # 直近30日間
+```
+
+`D7`は`d{0..6}`と等価です。
+
+### マージ動作
+
+相対指定を使うと、**デフォルトでまとめて集計**されます。`--no-merge`を指定すると単位ごとに個別表示します:
+
+```bash
+mlb m0..2             # 今月+先月+先々月を合算(デフォルト)
+mlb m0..2 --no-merge  # 月別に個別表示
+
+mlb y1                # 昨年を合算(デフォルト)
+mlb y1 --no-merge     # 月別に個別表示
+
+mlb w0..1             # 今週+先週を合算(デフォルト)
+mlb w0..1 --no-merge  # 週別に個別表示
+```
+
+明示的な月指定(`YYYY/M`)はデフォルトで個別表示され、`--merge`でまとめます。
+
+## オプション一覧
+
+オプションは用途ごとに見ると把握しやすくなります。
+
+### 表示・出力形式
+
+| オプション | 説明 |
+|---|---|
+| `-s`, `--simple` | 一覧形式で表示(デフォルト) |
+| `-c`, `--calendar` | カレンダー形式で表示 |
+| `-l`, `--line-chart` | 累積作業時間の折れ線グラフを表示(月単位指定のみ・最大3か月) |
+| `--grid` | 折れ線グラフをグリッド表示(月単位指定のみ・最大12か月・端末幅に応じて3/2/1列) |
+| `--heatmap` | 曜日×時刻の作業パターンをヒートマップで表示(解像度: 15m/30m/1h) |
+| `--anonymize` | 匿名化形式で表示 |
+| `--anonymize-dict` | 匿名化の逆引き辞書を出力 |
+| `--raw` | 生のMarkdown内容をそのまま出力(AI要約用) |
+
+### 対象の絞り込み・集計方法
+
+| オプション | 説明 |
+|---|---|
+| `--filter=REGEXP` | 作業名(`##`見出し)で時間集計の対象を正規表現フィルタ |
+| `--grep=REGEXP` | 見出し(`##`/`###`)にマッチするMarkdownセクションを抽出 |
+| `--merge` | 複数の対象をまとめて集計 |
+| `--no-merge` | 相対指定のデフォルトマージを無効にして個別表示 |
+| `--target-hours=HOURS` | 月間の基準時間を指定(設定ファイルの値を上書き) |
+| `--no-target-hours` | 基準時間を無効化(達成率・Remaining・サイン・targetラインを非表示) |
+
+### 設定
+
+| オプション | 説明 |
+|---|---|
+| `-p`, `--project=NAME` | 使用するプロジェクトを指定(環境変数`MDLOGBOOK_PROJECT`より優先) |
+| `--list-projects` | 設定ファイルに定義されたプロジェクト名の一覧を表示 |
+| `--config=PATH` | 設定ファイルのパスを指定(環境変数`MDLOGBOOK_CONFIG`より優先) |
+| `--path=PATH` | ログディレクトリのパスを指定(設定ファイルの`path`を上書き) |
+| `--init` | 設定ファイルの雛型を作成する |
+
+### 補助操作
+
+| オプション | 説明 |
+|---|---|
+| `-e`, `--edit` | 対象ファイルをエディタで開く(終了後にファイルを検査) |
+| `--completion=SHELL` | シェル補完スクリプトを出力(bash/zsh) |
+| `--debug` | 内部診断を表示(例: カレンダー表示の判定用内部値、見つからないファイルの警告) |
+| `-h`, `--help` | ヘルプを表示 |
+
+## 出力形式
+
+用途に応じて、一覧・カレンダー・グラフ・生テキスト出力・セクション抽出・匿名化を使い分けられます。
+
+### 一覧形式(simple)
+
+日付・時間帯・時間数・作業名を1行ずつ表示します。末尾に合計時間、8時間換算の日数、基準時間(`--target-hours`または設定ファイルの`target_hours`)に対する達成率を表示します。
+
+端末への出力時は、日付ごとに行の色が交互に変わります。
+
+### カレンダー形式(calendar)
+
+月曜始まりのカレンダーに日ごとの合計時間を表示します。各週の右端に週合計と平均、末尾に曜日ごとの合計と平均を表示します。
+
+各日に達成状況の記号が付きます。判定はその日の時間数またはその日までの月内平均のいずれかに適用されます:
+
+| 記号 | 判定 |
+|---|---|
+| `◎` | 日の時間数または月内平均 ≥ 基準の1.2倍 |
+| `○` | 日の時間数または月内平均 ≥ 基準 |
+| `△` | 上記に該当せず、基準の0.7倍以上 |
+| `×` | 基準の0.7倍未満 |
+
+基準は`target_hours`÷月間稼働日数(20日固定)です。デフォルト設定(`target_hours: 160`)では**8.0時間/日**となります。
+
+端末への出力時は記号と0時間の日が色付きで表示されます。
+
+当月を表示していて月末まで日が残っている場合、基準時間に達するために残り何時間必要か(稼働日あたり・暦日あたり・合計)を表示します。すでに達成している場合はその旨を表示します。
+
+### 折れ線グラフ表示(line-chart)
+
+利用例:
+
+```bash
+mlb --line-chart        # 今月を折れ線グラフで表示(通常の端末では端末幅に合わせて自動調整)
+mlb -l                  # 同上(-lは--line-chartの短縮形)
+mlb --line-chart=large  # largeサイズで表示
+mlb -ll                 # 同上(lはlargeの短縮形)
+mlb --line-chart q0     # 今期(3か月)を月ごとに表示
+mlb --line-chart 2026/1 2026/2 2026/3
+```
+
+仕様:
+
+- **月単位指定のみ**対応しています(週・日・期間指定は使用不可)
+- 最大3か月まで指定できます
+- 複数月を指定した場合は、月ごとに個別のグラフを表示します
+
+サイズは`=SIZE`で指定できます:
+
+| SIZE | 短縮形 | 幅 | 高さ |
+|---|---|---|---|
+| `small` | `s` | 60 | 15 |
+| `medium` | `m` | 80 | 20 |
+| `large` | `l` | 100 | 25 |
+| `max` | `x` | 端末幅に合わせて自動調整 | 35 |
+
+`SIZE`を省略した場合は、通常の端末出力では端末幅に合わせて自動調整されます。端末幅を取得できない場合は`medium`になります。
+
+グラフには3つの折れ線を表示します:
+
+| 系列 | 内容 |
+|---|---|
+| Actual | 当日までの累積作業時間 |
+| Linear target | `target_hours ÷ 月日数`を1日ずつ積み上げた直線目標 |
+| Weekday target | 稼働日(月〜金)のみに目標時間を積み上げた階段状目標 |
+
+グラフの下に、当月表示時は残り必要時間の統計も表示します(カレンダー形式と同じ形式)。
+
+設定ファイルの`visual`セクションで系列の表示・非表示と色をカスタマイズできます:
+
+```yaml
+mdlogbook:
+  visual:
+    today: true      # 今日の縦線(デフォルト: true)
+    weekday: false   # 稼働日目標(デフォルト: false)
+    linear: true     # 直線目標(デフォルト: true)
+    colors:
+      actual: cyan
+      linear: green
+      weekday: yellow
+      today: white
+```
+
+色に指定できる値: `red` / `green` / `blue` / `cyan` / `magenta` / `yellow` / `white` / `normal`
+
+### グリッド表示(grid)
+
+利用例:
+
+```bash
+mlb --grid              # 今月をグリッド表示
+mlb --grid q0           # 今期(3か月)を並べて表示
+mlb --grid '2025/*'     # 2025年の各月をまとめて表示
+```
+
+仕様:
+
+- **月単位指定のみ**対応しています(週・日・期間指定は使用不可)
+- 最大12か月まで指定できます
+- 端末幅に応じて3列・2列・1列に自動調整されます
+- 各チャートのタイトル行に、その月の合計時間と記録があった日の平均時間を表示します
+- 凡例は先頭行の右端のチャートにだけ表示されます
+- Remaining表示はありません
+
+`visual`セクションの設定は`--grid`にも適用されます。`today`/`weekday`/`linear`や色設定を共通で使えます。
+
+### ヒートマップ表示(heatmap)
+
+利用例:
+
+```bash
+mlb --heatmap q0           # 今期の作業パターンを表示(デフォルト: 30分刻み)
+mlb --heatmap y0           # 今年全体
+mlb --heatmap m0..3        # 直近4か月
+mlb --heatmap=15m q0       # 15分刻みで表示
+mlb --heatmap=1h q0        # 1時間刻みで表示
+```
+
+仕様:
+
+- 曜日(Mon-Sun)×時刻のヒートマップで、どの曜日の何時台に作業が集中しているかを可視化します
+- Y軸は曜日(Mon=上〜Sun=下)で固定7行、曜日ラベルはチャート右側に表示されます
+- X軸は`start_hour`から24時間分の範囲です(デフォルト: 0時〜24時)
+- 任意の期間指定に対応しています(月単位制約なし)
+- 複数期間のデータは常にマージして1つのプロットに統合されます
+
+解像度は`=RESOLUTION`で指定できます:
+
+| RESOLUTION | 列数 | 説明 |
+|---|---|---|
+| `1h` | 24 | 1時間刻み |
+| `30m` | 48 | 30分刻み(デフォルト) |
+| `15m` | 96 | 15分刻み |
+
+設定ファイルの`heatmap`セクションでX軸の開始時刻を変更できます:
+
+```yaml
+mdlogbook:
+  heatmap:
+    start_hour: 4   # X軸の開始時刻(デフォルト: 0)
+```
+
+`start_hour`より前の時刻は+24時間にラップされます。例えば`start_hour: 4`を指定すると3:00は27時として右端付近に表示されます。負値も指定可能です。
+
+### 生テキスト出力(raw)
+
+利用例:
+
+```bash
+mlb --raw        # 今月の記録をそのまま出力
+mlb --raw m1     # 先月の記録をそのまま出力
+```
+
+仕様:
+
+- 指定期間の記録をMarkdownのまま出力します
+- タスク名・時間エントリだけでなく、メモや自由記述を含むすべての行が対象です
+- AIに入力して作業内容を要約させる用途を想定しています
+
+設定ファイルの`extract`セクションで`preamble`/`postamble`を設定できます:
+
+```yaml
+mdlogbook:
+  extract:
+    preamble: |
+      以下は{range_begin}〜{range_end}の作業記録です。
+
+      書式はMarkdownです。`# YYYY-MM-DD`は日付、`## `で始まる行はタスク名、
+      `* hh:mm-hh:mm (h.hh)`は時間帯と時間数を表します。
+
+      この記録をもとに作業内容を要約してください。
+      作業時間が長いものから順に上位5件程度を、以下の形式で出力してください。
+      - タスク名と合計作業時間
+      - 作業内容・メモ・その他の情報の要約
+      - 記述から読み取れる範囲でのタスクの状況(完了・未完了・課題など)
+
+      ---
+```
+
+`{range_begin}`と`{range_end}`は対象期間の開始日・終了日に置換されます。
+
+### セクション抽出(grep)
+
+利用例:
+
+```bash
+mlb --grep 'FooBar' q1      # 見出しにFooBarを含むセクションを抽出
+mlb --grep 'TODO|Review' D2 # ここ2日間のTODO/Reviewセクションを抽出
+```
+
+仕様:
+
+- 見出し行のみを対象に正規表現マッチします
+- 対象見出しはデフォルトで`##`と`###`です
+- `# YYYY-MM-DD`は検索対象ではなく、日付境界として扱います
+- `## Foo`にマッチした場合、その配下の`###`見出しと本文を含めて、次の`##`以上の見出し直前までを出力します
+- `### TODO`にマッチした場合、その`### TODO`から次の`###`以上の見出し直前までを出力します
+- 出力は元のMarkdownを保ち、各断片の先頭に親の日付見出し`# YYYY-MM-DD`を付けます
+- `--grep`では`extract.preamble`/`extract.postamble`は適用しません
+
+### 集計フィルタ(filter)
+
+利用例:
+
+```bash
+mlb --filter 'ProjectA' q1
+```
+
+仕様:
+
+- 一覧表示、カレンダー表示、グラフ表示などの時間集計結果を、`##`見出しの作業名で絞り込みます
+- Markdown本文や`###`見出しの抽出は行いません
+
+### 匿名化形式(anonymize)
+
+利用例:
+
+```bash
+mlb --anonymize        # 今月を匿名化して出力
+mlb --anonymize m1     # 先月を匿名化して出力
+```
+
+仕様:
+
+- 作業記録をAIへ入力するなど、タスク名を伏せたい場面で使用します
+- 出力されるのは日付見出し・タスク見出し・時間帯の行のみで、その他のテキストは除外されます
+- タスク名は`project名 + anonymize.salt + task名`を入力にしたSHA-256の先頭8文字に置換されます
+- 同じタスク名は期間をまたいでも常に同じ値になります
+
+設定ファイルの`anonymize`セクションで出力をカスタマイズできます:
+
+```yaml
+mdlogbook:
+  path: ~/logs
+  anonymize:
+    salt: "0123456789abcdef0123456789abcdef"  # `mlb --init`で自動生成
+    format: "業務 {hash}"        # デフォルト: "{hash}"
+    passthrough:                  # 匿名化しないタスク名
+      - "定例ミーティング"        # 完全一致
+      - "/^社内/"                 # /pattern/形式で正規表現も指定可能
+    preamble: |
+      以下は{range_begin}〜{range_end}の作業記録です。
+
+      書式はMarkdownです。`# YYYY-MM-DD`は日付、`## `で始まる行はタスク名(匿名化済み)、
+      `* hh:mm-hh:mm (h.hh)`は時間帯と時間数を表します。
+
+      この記録をもとに以下の点を分析してください。
+      - 働き方の傾向と注意すべき点
+      - 期間中に傾向の変化があれば、その内容と考えられる理由
+
+      ---
+    postamble: ""
+```
+
+- `salt`: ハッシュ入力に追加するプロジェクト固有のsalt。`mlb --init`でランダム値を生成します
+- `format`: タスク見出し行の書式。`{hash}`が8文字のハッシュ値に置換されます
+- `passthrough`: ここに指定したタスク名はハッシュ化せずそのまま出力します。`/pattern/`形式で正規表現も使用できます
+- `preamble` / `postamble`: 出力の前後に付けるテキスト。`{range_begin}`と`{range_end}`は対象期間の開始日・終了日に置換されます
+
+### 逆引き辞書
+
+`--anonymize-dict`でハッシュ値と元のタスク名の対応表を出力します。`passthrough`に指定したタスクは除外されます。
+
+```bash
+mlb --anonymize-dict        # 今月の辞書を出力
+mlb --anonymize-dict m1..3  # 先月〜3ヶ月前の辞書を出力
+```
+
+出力例:
+
+```
+a1b2c3d4 ProjectA
+e5f6a7b8 ProjectB
+```
+
+## 補助機能と補足事項
+
+### 重複チェック
+
+`--simple`・`--calendar`で表示する際、出力対象期間内のエントリに時間帯の重複がないか自動チェックします。重複が見つかった場合はstderrへ出力されます:
+
+```
+2026-03-15 09:00-12:00 (line 5) overlaps 11:00-13:00 (line 9)
+```
+
+stderrが端末の場合は赤字で表示されます。
+
+### シェルコンプリーション
+
+`--completion`オプションでbash/zsh用の補完スクリプトを生成できます。オプション名だけでなく、`--line-chart`のサイズ(`small`, `medium`等)や`--heatmap`の解像度(`15m`, `30m`, `1h`)、`--project`のプロジェクト名なども補完されます。
+
+#### bash
+
+補完スクリプトをファイルに保存します(bash-completion 2.x+で遅延ロードされます):
+
+```bash
+mlb --completion bash > ~/.local/share/bash-completion/completions/mlb
+```
+
+または`.bashrc`に直接記述します:
+
+```bash
+eval "$(mlb --completion bash)"
+```
+
+#### zsh
+
+補完スクリプトを生成して`fpath`の通ったディレクトリに配置します:
+
+```zsh
+mlb --completion zsh > ~/.zsh/completions/_mlb
+```
+
+`~/.zsh/completions`が`fpath`に含まれていない場合は`.zshrc`に追加します:
+
+```zsh
+fpath=(~/.zsh/completions $fpath)
+autoload -Uz compinit && compinit
+```
+
+設定後、新しいシェルを起動するか`exec zsh`で反映します。
+
+### 注意点
+
+- 作業名の絞り込み(`--filter`)は、各記録の直前にある`##`見出しに対して適用されます
+- 終了時刻が開始時刻より前の場合は翌日として1回だけ繰り上げて計算します。`00:xx`表記は警告付きで受け付けます