ALNEAS 共通ドキュメントガバナンスポリシー

状態: 正式運用 (2026-10-17)
対象: eaos-workspace (public/private), tools, web-framework, github-docs

[!NOTE] AIエージェントや自動化スクリプトは、以下のプレーンMarkdownエンドポイントを直接参照できます：
/policies/documentation-policy.md

github-docs は、ALNEASエコシステム全体の公開閲覧・検索・ナビゲーションを集約する単一窓口（ポータル）です。本ポリシーは、EAOSの文書管理規約（正本管理・生成コピー分離・AIと人間の役割境界）を正式に継承し、**「人間にとっての圧倒的な見やすさ」と「AIエージェントにとっての文脈理解・誤認防止」**を両立し、同時に機密情報の漏洩を防ぐための統制ルールです。

1. 正本（SSOT）と一方向同期の原則

文書分類	正本（SSOT）の所在	github-docs への扱い
全体ナビゲーション・エコシステム紹介・共通ポリシー	`github-docs`	当リポジトリで直接編集・管理する
各プロジェクトの技術ガイド・API仕様	各実装プロジェクト	明示的に選定された公開文書のみを一方向で取り込む
自動抽出API仕様（JSDoc / OpenAPI）	各プロジェクトのソースコード	`docgen` により抽出され、翻訳辞書と合流して自動出力
EAOS private業務ガイド・有料plugin内部実装	privateリポジトリ	絶対に取り込まない（紹介が必要なら独立した公開用概要を書く）
顧客環境設定・運用手順・配備記録・内部receipt	各privateホスト環境	絶対に取り込まない
計画・調査・移行メモ・過去記録	各プロジェクトの `docs/`	原則取り込まない（現在の利用手順と明確に区別する）
AI作業スキル（SKILL.md）	所有側のリポジトリ	人間向けAPI仕様の正本にしない（手順ガイドと明確に分離）

原則

逆同期の禁止: 集約先（github-docs）で見つかった修正は、集約先で直接直すのではなく必ず「所有元リポジトリ」で修正して再同期します。
手編集生成物の保護: 自動生成領域（src/content/docs/**/api.md や generated/）を手編集してはなりません。
版とハッシュの追跡: 同期元リポジトリのコミット、対象ファイルの相対パス、内容SHA-256ハッシュを検証し、更新差分を正確に追跡します。

2. 4つのドキュメント体系（Diátaxisフレームワーク）

すべてのページは以下の4つのいずれか単一の役割に徹します：

                【実践・タスク志向】
                       ▲
   Tutorials (導入学習) │ How-To Guides (目的別手順)
───────────────────────┼───────────────────────────
   Explanation (設計・背景)│ Reference (機械的仕様・API)
                       ▼
                【理論・理解志向】

3. オープンコアモデルと完全非公開の分離戦略

パブリック集約サイトでのオープンコア（Open-Core）運用: 有料プラグインやエンタープライズ機能であっても、概要や公開API仕様、導入手順は完全公開し、エコシステムの価値を最大化します。
完全非公開（社外秘・運用機密）の分離: 実IP、DB接続情報、受入ログ、配備記録などの機密は、独立した社内ポータル（INTERNAL=true + Cloudflare Access）で保護します。