diff --git a/packages/@d-zero/page-cluster/README.md b/packages/@d-zero/page-cluster/README.md
index b3db0439..0eeee5cb 100644
--- a/packages/@d-zero/page-cluster/README.md
+++ b/packages/@d-zero/page-cluster/README.md
@@ -1,70 +1,109 @@
# `@d-zero/page-cluster`
-大量クローリングした HTML の重複・類似ページ検出のためのパッケージ。`tokenize()` は `` 配下のHTMLを、テキストを除去した構造トークンに変換する。用途・設計判断のWHYは `src/tokenize.ts` の JSDoc を参照。
+大量クロール HTML の重複・類似ページを構造トークンで検出するパッケージ。CLI が主、ライブラリ関数群がオマケ。
-## Installation
+## What this does
+
+`page-cluster` は HTML ページ集合を受け取って、**同一テンプレートと判定できるページ**に同じキーを振る。テキストは無視して DOM 構造だけを見るので、記事本文が違うが同じテンプレートを使うページ群は 1 つのクラスタにまとまる。単一サイトで数万〜十数万ページ規模のクロール成果物を、テンプレート単位に畳んで概観したいときに使う。
+
+## Install
```sh
yarn add @d-zero/page-cluster
```
-## Usage
+インストールすると `page-cluster` コマンドが `node_modules/.bin/` 配下に入る。
+
+## Quickstart (CLI)
-```ts
-import { tokenize } from '@d-zero/page-cluster';
+**入力**: JSONL 1 行 1 ページ。フィールドは以下。`html` 以外はすべて任意（`paths` / `stylesheetHrefs` がないと粗い分類になる）。
-const { tokens, bodyClassList } = tokenize(
- '',
-);
-// tokens: ["body>.card>ul>li", "body>.card>ul>li"]
-// bodyClassList: ["law-page"]
+```json
+{
+ "id": "任意の識別子",
+ "html": "...",
+ "paths": ["news", "1"],
+ "stylesheetHrefs": ["/a.css"],
+ "host": "example.com"
+}
```
-### オプション
+**出力**: JSONL 1 行 1 ページ、入力順。
-```ts
-tokenize(html, {
- filterNoiseClasses: true, // 既定値。ハッシュ的自動生成class名を除外する
- includeComments: false, // 既定値。コメントノードをトークン化しない
-});
+```json
+{ "id": "任意の識別子", "clusterKey": "..." }
```
-### クラスタリング
+### クローラ出力（JSON 配列）を JSONL に変換して食わせる
-クロールしたページ群から最終的なクラスタキーを得るには `resolvePageClusterKeys()` を使う。ブロッキング（URLパス/スタイルシートによる粗い絞り込み）と構造クラスタリング（ブロック内でのcomplete-linkage階層的クラスタリング）を内部で連結し、ブロックを跨いで一意なキーを返す。既定で各ページのランドマーク要素（``/`