zread

zread スキル

zread は、LLM を使用して現在のワークスペース内のコードから Wiki ドキュメントを生成する CLI です。出力はワークスペース内の ./.zread/wiki/ に保存されます。公開リポジトリは https://zread.ai でも閲覧できます。

このスキルはエージェントでの使用を想定しています。生成されたファイルはディスクから直接読み取り、zread コマンドを実行する際は、人間向け TUI を解析しようとせず、デフォルトで --stdio を使用してください。

ディスク上の構成（直接読み取ってください）

常にワークスペースのルートから zread を実行してください。生成が成功した後の構成は次のとおりです。

• ./.zread/wiki/current — アクティブなバージョン ID を含むテキストファイルです （例：2026-03-12-010203）。
• ./.zread/wiki/versions/<id>/wiki.json — 目次です：{id, generated_at, language, pages: [{slug, title, file, section, group, level}]}。
• ./.zread/wiki/versions/<id>/<file> — pages[*].file で参照されるページの Markdown です。
• ./.zread/wiki/drafts/ — 生成途中のデータです。このディレクトリが存在する場合、前回の実行は完了していません。カタログフェーズの完了後に drafts/wiki.json が作成されます。
• ~/.zread/config.yaml — グローバル設定（LLM プロバイダー、言語、同時実行数）です。
• ~/.zread/login.json — このファイルが存在する場合、ユーザーはログイン済みです。

zread の出力がすでにあるコードベースについて質問に答えるには、ファイルツールを使ってこれらのファイルを直接読み取ってください。zread browse は実行しないでください。

コマンド

コマンド	用途	主なフラグ
zread generate	現在のディレクトリの Wiki を生成します	-y/--yes、--draft resume|clear|cancel、--skip-failed、--stdio
zread browse	http://localhost:9681+ でドキュメントを配信し、ブラウザーを開きます	--generate、--version <id>、--host、--port、--stdio
zread login	API キーを取得するために BigModel/Z.AI に OAuth ログインします	--custom、--model、--stdio
zread config	~/.zread/config.yaml を編集します	--stdio
zread update	CLI をセルフアップデートします	--stdio
zread version	バージョンを表示します	--stdio

すべてのコマンドで --stdio を使用できます。指定すると、プロセスは stdin/stdout 上で JSON ラインのマシンプロトコルを使用します。ワイヤーフォーマット（イベント、waiting_for、done、quit）については、references/stdio-protocol.md を参照してください。別のプログラムやエージェントから zread を実行する場合は、このファイルを読み込んでください。

AI エージェント向けの判断フロー

1. ユーザーは既存の Wiki コンテンツを読みたいですか？

   • ./.zread/wiki/current を確認します。存在する場合は、wiki.json とページの Markdown を直接読み取ります。CLI を実行する必要はありません。
   • 既知の公開 GitHub リポジトリでは、CLI を実行するよりも mcp__zread__* ツール（get_repo_structure、read_file、search_doc）を優先してください。

2. ユーザーはドキュメントを（再）生成したいですか？

   • まずユーザーに確認してください。generate は実行に時間がかかり、LLM を呼び出してファイルを書き込みます。見慣れないディレクトリでは明示的な同意を得てください。
   • ~/.zread/login.json が存在するか、~/.zread/config.yaml に llm.api_key が設定されていることを確認します。どちらもない場合は、先に zread login を実行してください。
   • ./.zread/wiki/drafts/ が存在する場合は、次のいずれかを選びます。
     • 前回の実行を再開する → zread generate --draft resume -y
     • 破棄して最初からやり直す → zread generate --draft clear -y
   • それ以外の場合：zread generate -y。
   • いくつかのページの失敗で処理を停止させない場合は、--skip-failed を追加してください。

3. ユーザーはブラウザーでドキュメントを閲覧したいですか？

   • zread browse（Wiki がまだない場合は、作成を開始するために --generate を追加します）。

4. ユーザーは zread をスクリプトから実行する、または出力をプログラムで利用したいですか？

   • --stdio を使用し、stdio-protocol.md の手順に従ってください。TUI をスクリーンスクレイピングしないでください。

非対話型実行のルール

• 無人実行で generate を実行する場合は、必ず -y を指定してください。指定しないと、カタログ確認の段階で停止します。
• 下書きが存在する可能性がある場合は、コマンドが確認を求めないよう、必ず --draft を明示的に設定してください。
• 別のエージェントやスクリプトからコマンドを実行する場合は、出力を ANSI TUI フレームではなく解析可能な JSON にするため、--stdio を使用してください。
• zread はログを ~/.zread/log/zread.log に書き込みます。実行が失敗してもエラーが表示されない場合は、このファイルを読んでください。

安全性／影響範囲

• generate は LLM トークンを消費するため、実際のコストが発生します。また、大規模なリポジトリでは完了まで数分かかる場合があります。実行前に確認してください。
• generate が書き込むのは ./.zread/ 配下のみで、Git にコミットすることはありません。処理が停止した状態から復旧するには、./.zread/wiki/drafts/ を安全に削除できます。
• update は zread バイナリをその場で置き換え、元に戻すのが困難です。ユーザーから明示的に依頼された場合にのみ実行してください。
• login は OAuth 認証のためにブラウザーを開きます。ユーザーから依頼されていない限り、非対話型のコンテキストでは実行しないでください。

参考ファイル

• references/stdio-protocol.md — すべてのコマンドの --stdio モードで共有される JSON 行形式のワイヤープロトコルです。zread をプログラムから操作するときに読み込んでください。