ドキュメント保守ガイド

Project N.E.K.O. のドキュメントはプロダクト契約の一部です。説明対象のコードの近くで保守し、文書の性質を明示し、変化しやすい事実を複数ページへコピーしないでください。

ドキュメントの階層

階層	目的	場所
ユーザー／開発ガイド	サポートされるセットアップと一般的な手順	guide/, config/, deployment/, frontend/, plugins/
アーキテクチャ／API	現在のコードに基づく契約	architecture/, modules/, api/
コントリビューター規則	リポジトリ全体の開発・検証規則	contributing/
プロジェクト記録	設計判断、ベンチマークのスナップショット、SDK 変更記録	design/, benchmarks/, changelog/
コンポーネント所有文書	単一コンポーネントと共に保守する詳細文書	例: plugin/plugins/neko_live/docs/

プロジェクト記録は根拠と背景を残す場所であり、現在のコード、テスト、承認済み issue の代わりではありません。

正本の原則

同じ事実には一つの正本を選びます。

• 動作と公開契約は担当ガイド、アーキテクチャ、API ページに置く。
• リポジトリ運用は contributing/ に置く。
• 実装理由と日付付き測定値はプロジェクト記録に置く。
• コンポーネント固有の手順はそのコンポーネントの近くに置く。
• 将来の作業は承認済み issue または保守中のプロジェクトボードで管理する。

コマンド一覧、provider 表、バージョン情報、roadmap の約束は複製せず、正本へリンクしてください。翻訳ページは意味を同期するもので、別仕様ではありません。

ステータス表現

計画や記録は冒頭付近で権威を明示します。

• Current contract — 現在のコードとテストが保証する動作。
• Implemented design record — 出荷済み動作の理由。詳細は後のコードに置き換わる場合がある。
• Proposal — ファイルが存在しても承認・実装済みとは限らない。
• Historical snapshot — 日付付きの証拠であり、現在の状態ではない。
• Deprecated — 移行または調査のためだけに保持する。

所有者と公式な追跡リンクがない「次のフェーズ」「将来のバージョン」などの曖昧な約束は避けてください。

言語

ドキュメントサイトには英語、簡体字中国語、日本語のナビゲーションがありますが、すべてのプロジェクト記録に翻訳があるわけではありません。対応ページがない場合、言語切替はその言語のホームへ戻ります。

既存のミラーガイドを変更するときは、すべての既存ミラーを同じ変更で更新し、コード識別子、パス、プレースホルダー、警告の意味を維持してください。保守できない空の翻訳は作らず、単一言語の記録は最寄りの索引に明記します。

ランタイム UI の 8 locale 同期規則は別の必須要件です。

docs/README_en.md、docs/README_ja.md、docs/README_ru.md は root README からリンクされるリポジトリ README の翻訳です。VitePress build から意図的に除外されており、サイト navigation page として使用しません。

docs/zh-CN/guide/openclaw_guide*.md と隣接 asset は、アプリが直接配信する多言語 runtime guide です。path を安定させ、VitePress から除外し続けてください。公開 integration contract は Agent／plugin documentation で保守します。

リンクと検証

• VitePress ページには /plugins/quick-start のようなサイトルートリンクを使う。
• ドキュメントサイト外のリポジトリファイルには完全な GitHub blob URL を使い、上位相対リンク（../）は使わない。
• 既存ルートを安定させ、移動が必要ならリダイレクトまたは互換ページを用意する。
• 生成物、ローカル worktree、一時レポート、機密ログ、未マージ PR を恒久リンクにしない。
• 提出前に現在のコードとテストを確認し、既存の言語ミラーを確認する。
• docs/ で npm ci と npm run build を実行する。
• PR は一つの目的に集中させ、stacked PR で無関係な文書作業を混ぜない。