docs: align v0.30.0 READMEs, compatibility and benchmark claims with implementation

README.ja.md

@@ -34,7 +34,7 @@ curl --fail --get 'http://127.0.0.1:29483/search' \
   --data 'format=json' --data 'max_results=5'
 ```
 
-結果にはタイトル、URL、抜粋、検索元などの情報が含まれます。必要に応じて`language=ja`、`engines=wikipedia`、`include_domains=docs.rs`、`exclude_domains=example.com`、`time_range=day`、`include_raw_content=1`を指定できます。期間指定の精度は検索元によって異なります。
+結果にはタイトル、URL、抜粋、検索元などの情報が含まれます。未知の検索元指定をエラーにしたい場合は`strict_engines=1`を加えます（既定ではSearXNG互換のフォールバック動作を維持します）。必要に応じて`language=ja`、`engines=wikipedia`、`include_domains=docs.rs`、`exclude_domains=example.com`、`time_range=day`、`include_raw_content=1`を指定できます。期間指定の精度は検索元によって異なります。
 
 ブラウザーからは<http://127.0.0.1:29483/>を開いてください。JSON以外にCSV、RSS、HTMLでも結果を取得できます。
 
@@ -51,7 +51,7 @@ MCPには読み取り専用のツールが2つあります。
 - `search`：検索結果を順位順に返します。既定は5件、最大10件です。抜粋は1件500文字までです。
 - `read_page`：同じセッションの`search`が返したURLから本文を取得します。`query`を指定すると、取得済みのページ全体から関連する文章を最大3件選びます。
 
-`read_page`の既定の本文長は4,000文字で、`max_chars`は最大20,000まで指定できます。`offset`と`next_offset`を使えば続きも読めます。情報が省略されたかは`truncated`と`source_truncated`で確認できます。応答には文字数・バイト数の上限がありますが、トークン数を厳密に制限する機能ではありません。
+`read_page`の既定の本文長は4,000文字で、`max_chars`は最大20,000まで指定できます。`offset`と`next_offset`を使えば続きも読めます。情報が省略されたかは`truncated`と`source_truncated`で確認できます。文字数・バイト数の上限に加え、`tokenizer`（`cl100k_base`または`o200k_base`）と`max_payload_tokens`の両方を指定すると、MCPの`structuredContent`に対するトークン上限を適用できます。JSON-RPCの外枠や呼び出し側のプロンプトは計数対象外です。[出力の仕様](docs/AGENT-OUTPUT.md)を参照してください。
 
 本文取得では接続先とリダイレクトを検査し、プライベートIPへの接続を拒否します。robots.txt（RFC 9309）にも従います。MCPから任意のURLを直接取得することはできません。取得したWebページはAIへの指示ではなく、外部の情報として扱ってください。
 
@@ -66,14 +66,14 @@ HTTP APIでは`include_raw_content=1`で本文を取得できます。PDFの文
 | 構成 | コマンド | 検索先 |
 | --- | --- | --- |
 | Standard | `rustxng` | 取得先と用途の条件を記録したキー不要の34エントリと自前索引 |
-| Clean | `rustxng --profile clean` | 外部の検索に依存しない。自前の索引（クロール索引とWikipediaダンプ索引）だけが情報源 |
+| Clean | `rustxng --profile clean` | 構築済みのクロール索引とWikipediaダンプ索引だけを検索。外部検索プロバイダーには問い合わせない |
 | Full | `rustxng --profile full` | 利用規約の制限や許可が未確認のHTML検索先も含む構成。有料のExa Searchも追加（`EXA_API_KEY`が無いときは起動時に読み飛ばす） |
 
 Fullは利用許可を不要にする機能ではありません。個人利用やLAN内での運用でも検索元の規約が適用されます。必要な許可や契約を確認できない検索先は有効にしないでください。Cleanも法的な適合性を保証するものではありません。
 
-MCPでも`rustxng mcp --profile clean`のように指定できます。検索元によってはAPIキーや料金が必要です。RustXNGをローカルで動かしても、検索語は選択した外部サービスへ送信されます。
+MCPでも`rustxng mcp --profile clean`のように指定できます。StandardとFullでは、有効な外部検索元へ検索語を送信します。Cleanの検索対象はローカル索引だけですが、明示的に本文取得などを有効にした場合は外部通信が発生し得ます。FullのExa連携は有料で、キーを設定しただけではStandardで有効になりません。
 
-Standardでは未確認の検索元をすべて既定無効にしました。確認範囲は記録した取得用途で、原著作物のライセンス・クォータ・運用目的の条件は残ります。キーが存在するだけではAPIを有効にしません。[今回の測定と設定方法](docs/ISSUE-RESOLUTION-2026-11-05.md)を参照してください。
+Standardでは未審査の検索元を既定無効にしています。ただし、監査は記録された取得用途についての確認であり、商用利用、本文の保存・再配布、クォータなどすべての条件に対する許諾ではありません。[検索元の条件](docs/PROVIDERS.md)と[測定記録](docs/ISSUE-RESOLUTION-2026-11-05.md)を参照してください。
 
 ## 導入と設定
 
@@ -87,23 +87,28 @@ docker run --rm -p 127.0.0.1:29483:29483 \
 
 既定ではローカル接続のみを受け付けます。外部へ公開するときは認証やアクセス制限を設定してください。
 
-設定はバイナリに含まれています。変更したい項目だけをTOMLファイルに書いて指定できます。
+既定の設定はバイナリに含まれています。例えば`my-settings.toml`を作り、必要な項目だけを記載します。
+
+```toml
+[server]
+idle_timeout = 600
+```
 
 ```bash
-rustxng --config settings.toml
+rustxng --config my-settings.toml
 ```
 
-設定ファイルは選択したプロファイルを上書きします。意図せず上書きしないよう、既定設定を丸ごとコピーするのは避けてください。
+利用者の設定は選択したプロファイルに重ねて適用します。意図しない検索元の上書きを避けるため、同梱設定を丸ごとコピーしないでください。
 
 更新確認は`rustxng --check-update`、対応するバイナリの更新は`rustxng --update`です。パッケージ管理やDockerで導入した場合は、それぞれの方法で更新してください。
 
 `/healthz`で確認できるのはプロセスの稼働状態です。検索元が使えるかどうかは、実際にJSON検索を実行して確認します。稼働統計は`/stats`と`/metrics`で確認できます。
 
 ## 検索精度について
 
-[2026年11月4日の比較](docs/COMPARISON-2026-11-04.md)では、技術文書100問とSealQA 254問で3つの構成を測定しています。技術文書100問のHit@10は、Standardが88、Cleanが61、Fullが98でした。測定時にはローカルの索引を使用しています。
+[11月4日の比較](docs/COMPARISON-2026-11-04.md)は旧構成の記録であり、v0.30.0の性能測定ではありません。検索元を見直した後の[11月5日のStandard測定](docs/ISSUE-RESOLUTION-2026-11-05.md)では、技術文書100問のHit@5が**67〜69/100**でした。変更前構成の84/100から低下しています。一方、ローカル索引専用となったCleanでは、[保存済みのSealQA測定](docs/CLEAN-PROFILE.md)でHit@10が**85/254**、応答時間の中央値が42.7msでした。評価対象が異なるため、両者を直接比較することはできません。
 
-これは正解ページが検索結果に含まれる割合であり、AIの回答正解率ではありません。評価用の質問は開発中の調整にも使われており、索引対象には設問と関連する文書サイトが含まれます。他社APIの保存済み結果とも測定日時が異なります。この数値だけで一般的な検索性能の優劣は判断できません。
+いずれも参照ページへの到達率であり、AIの回答正解率ではありません。評価用の質問は開発中の調整にも使われており、索引には関連する文書サイトが含まれます。他社APIの保存済み結果も同時測定ではありません。**これらをv0.30.0の再測定値や、一般的な検索性能の優劣として扱わないでください。**
 
 ## 関連ドキュメント
 

README.ko.md

@@ -34,7 +34,7 @@ curl --fail --get 'http://127.0.0.1:29483/search' \
   --data 'format=json' --data 'max_results=5'
 ```
 
-결과에는 제목, URL, 발췌문, 검색 제공자 정보가 포함됩니다. `language=ja`, `engines=wikipedia`, `include_domains=docs.rs`, `exclude_domains=example.com`, `time_range=day`, `include_raw_content=1` 등의 매개변수를 사용할 수 있습니다. 기간 필터의 정확도는 제공자마다 다릅니다.
+결과에는 제목, URL, 발췌문, 검색 제공자 정보가 포함됩니다. 알 수 없는 검색 엔진 이름을 오류로 처리하려면 `strict_engines=1`을 지정하세요. 기본값은 SearXNG 호환 폴백 동작을 유지합니다. `language=ja`, `engines=wikipedia`, `include_domains=docs.rs`, `exclude_domains=example.com`, `time_range=day`, `include_raw_content=1` 등의 매개변수를 사용할 수 있습니다. 기간 필터의 정확도는 제공자마다 다릅니다.
 
 브라우저 화면은 <http://127.0.0.1:29483/>에 있습니다. JSON 외에 CSV, RSS, HTML 출력도 지원합니다.
 
@@ -51,7 +51,7 @@ MCP는 읽기 전용 도구 두 개를 제공합니다.
 - `search`: 정렬된 검색 결과를 반환합니다. 기본 5개, 최대 10개이며 발췌문은 결과당 500자로 제한됩니다.
 - `read_page`: 같은 세션에서 `search`가 반환한 URL의 본문을 읽습니다. `query`를 지정하면 추출된 페이지 전체에서 관련 문장 최대 3개를 선택합니다.
 
-`read_page`는 기본 4,000자를 반환하고 `max_chars`로 최대 20,000자를 지정할 수 있습니다. `offset`과 `next_offset`으로 이어서 읽을 수 있으며, `truncated`와 `source_truncated`로 생략 여부를 확인할 수 있습니다. 응답의 문자 수와 바이트 수는 제한하지만 모델별 토큰 수를 정확하게 제한하지는 않습니다.
+`read_page`는 기본 4,000자를 반환하고 `max_chars`로 최대 20,000자를 지정할 수 있습니다. `offset`과 `next_offset`으로 이어서 읽을 수 있으며, `truncated`와 `source_truncated`로 생략 여부를 확인할 수 있습니다. 문자 및 바이트 제한 외에 `tokenizer`(`cl100k_base` 또는 `o200k_base`)와 `max_payload_tokens`를 함께 지정하면 직렬화된 MCP `structuredContent`에 토큰 제한을 적용할 수 있습니다. JSON-RPC 외피와 클라이언트 또는 모델의 프롬프트 구성은 계산에 포함되지 않습니다. [출력 계약](docs/AGENT-OUTPUT.md)을 참조하세요.
 
 페이지를 읽을 때 대상 주소와 리디렉션을 검사해 비공개 IP 연결을 차단하고 robots.txt(RFC 9309)를 준수합니다. MCP에서는 임의의 URL을 바로 읽을 수 없습니다. 검색 결과와 본문은 지시문이 아닌 신뢰할 수 없는 외부 데이터로 취급해야 합니다.
 
@@ -64,14 +64,14 @@ HTTP API는 `include_raw_content=1`로 본문을 가져올 수 있습니다. PDF
 | 프로필 | 명령 | 검색 원천 |
 | --- | --- | --- |
 | Standard | `rustxng` | 엔드포인트·사용 조건을 기록한 키 없는 항목 34개와 로컬 색인 |
-| Clean | `rustxng --profile clean` | 외부 검색에 의존하지 않음. 자체 색인(크롤 색인과 Wikipedia 덤프 색인)만 정보원 |
+| Clean | `rustxng --profile clean` | 미리 만든 크롤 및 Wikipedia 덤프 색인만 검색. 외부 검색 제공자에 요청하지 않음 |
 | Full | `rustxng --profile full` | 자동 접근 제한 또는 허가가 확인되지 않은 HTML 검색 제공자도 포함. 유료 Exa Search도 추가(`EXA_API_KEY`가 없으면 시작 시 건너뜀) |
 
 **Full을 사용해도 제공자 약관을 우회할 수 없습니다.** 필요한 허가를 확인하지 못한 제공자는 활성화하지 마세요. 개인용 서버도 이용 약관을 따라야 합니다. Clean 프로필 역시 법적 적합성을 보증하지 않습니다.
 
-MCP에서도 `rustxng mcp --profile clean`처럼 선택할 수 있습니다. 일부 API 제공자는 키나 요금을 요구합니다. RustXNG를 로컬에서 실행해도 검색어는 활성화한 외부 제공자로 전송됩니다.
+MCP에서도 `rustxng mcp --profile clean`처럼 선택할 수 있습니다. Standard와 Full은 활성화된 외부 제공자에게 검색어를 보냅니다. Clean은 로컬 색인만 검색하지만 본문 가져오기 같은 네트워크 기능을 명시적으로 요청하면 외부 통신이 발생할 수 있습니다. Full의 Exa 통합은 유료이며 API 키가 있다는 이유만으로 Standard에서 활성화되지 않습니다.
 
-Standard는 검토하지 않은 제공자를 모두 기본 비활성화합니다. 검토 범위는 기록된 검색 용도이며 콘텐츠 라이선스, 할당량과 배포 목적의 조건은 계속 적용됩니다. 키가 존재하는 것만으로 API를 활성화하지 않습니다. [현재 측정 및 설정](docs/ISSUE-RESOLUTION-2026-11-05.md)을 참고하세요.
+Standard는 미검토 검색 제공자를 기본 비활성화합니다. 다만 검토는 기록된 검색 용도에 한정되며 상업적 이용, 원문 저장 및 재배포, 이용량 제한까지 일괄 허가하는 것은 아닙니다. [제공자별 조건](docs/PROVIDERS.md)과 [측정 기록](docs/ISSUE-RESOLUTION-2026-11-05.md)을 참고하세요.
 
 ## 설치와 설정
 
@@ -85,23 +85,28 @@ docker run --rm -p 127.0.0.1:29483:29483 \
 
 기본 설정은 로컬 접속만 받습니다. 외부에 공개한다면 인증과 접근 제어를 별도로 설정하세요.
 
-기본 설정은 바이너리에 포함되어 있습니다. 필요한 항목만 TOML 파일에 작성해 덮어쓸 수 있습니다.
+기본 설정은 바이너리에 포함되어 있습니다. 예를 들어 `my-settings.toml` 파일에 변경할 항목만 작성하세요.
+
+```toml
+[server]
+idle_timeout = 600
+```
 
 ```bash
-rustxng --config settings.toml
+rustxng --config my-settings.toml
 ```
 
-사용자 설정 파일은 선택한 프로필을 덮어쓰므로 전체 기본 설정을 복사할 때는 주의하세요.
+사용자 설정은 선택한 프로필 위에 적용됩니다. 의도하지 않은 검색 제공자 변경을 피하려면 전체 기본 설정을 복사하지 마세요.
 
 `rustxng --check-update`로 업데이트를 확인하고, 지원되는 바이너리 설치에서는 `rustxng --update`를 사용할 수 있습니다. 컨테이너나 패키지 관리자로 설치했다면 원래의 업데이트 방법을 사용하세요.
 
 `/healthz`는 프로세스 상태만 확인합니다. 실제 검색 가능 여부는 JSON 검색으로 검증하세요. 실행 통계는 `/stats`와 `/metrics`에서 볼 수 있습니다.
 
 ## 검색 품질과 제한
 
-[2026년 11월 4일 비교](docs/COMPARISON-2026-11-04.md)는 기술 문서 100개 질문과 SealQA 254개 질문으로 세 프로필을 측정했습니다. 기술 문서의 Hit@10은 Standard 88, Clean 61, Full 98이었습니다. 측정 환경에는 로컬 색인이 포함되었습니다.
+[11월 4일 비교](docs/COMPARISON-2026-11-04.md)는 이전 프로필의 기록이며 v0.30.0을 다시 측정한 결과가 아닙니다. 제공자 권한 검토 후의 [11월 5일 Standard 기록](docs/ISSUE-RESOLUTION-2026-11-05.md)에서는 기술 문서 100개 질문의 Hit@5가 **67~69/100**으로, 이전 구성의 84/100보다 낮았습니다. 로컬 색인 전용 Clean은 [SealQA 기록](docs/CLEAN-PROFILE.md)에서 Hit@10 **85/254**, 응답 시간 중앙값 42.7ms를 보였습니다. 두 실험의 데이터셋이 달라 직접 비교할 수 없습니다.
 
-이는 정답으로 지정한 페이지를 검색 결과에서 찾은 비율이지 AI 답변의 정확도가 아닙니다. 평가 질문을 개발 과정에서도 사용했으며, 로컬 색인에는 평가에 관련된 문서 사이트가 포함되어 있습니다. 다른 검색 API와의 저장된 비교 결과 역시 측정 시점이 다릅니다. 이 수치만으로 일반적인 우열을 판단할 수 없습니다.
+이 지표는 참조 페이지 검색 성공률이지 AI 답변의 정확도가 아닙니다. 질문 집합은 개발에도 사용되었고 관련 문서 사이트가 로컬 색인에 포함되어 있으며, 외부 API 결과도 동시 측정한 값이 아닙니다. 이러한 수치를 v0.30.0의 검증된 성능이나 일반적인 우위로 주장해서는 안 됩니다.
 
 ## 문서