# 案内ドキュメントの構成

## 目的

利用者が最初に見る案内を重複なく配置し、公開リポジトリと各言語のrelease packageで同じ判断ができるようにする。

## 配置と正本

| 優先順位 | 配置 | 内容 | 言語 |
| --- | --- | --- | --- |
| 1 | リポジトリおよびrelease packageのトップ | `README.md`、`LICENSE.md`、`SECURITY.md` | 日本語を先、英語を後にした日英併記 |
| 2 | `docs/ja/` | 日本語版の利用者文書と `legal/` | 日本語だけ。ただしライセンスの英語原文は法的正本として併記できる。 |
| 2 | `docs/en/` | 英語版の利用者文書と `legal/` | 英語だけ。 |
| 3 | `licenses/`（release package） | 第三者ライセンスの原文 | 各ライセンスの原文 |

トップの3文書は共通の入口であり、言語別の別名ファイルを置かない。トップREADMEは入手方法、editionの違い、対応する言語別文書へのリンクを示す。トップLICENSEは英語原文を法的正本として明示し、トップSECURITYは非公開報告経路を案内する。

GitHub Pagesの文書ポータルは、`/` を日本語入口、`/en/` を英語入口とする。入口ページと各言語別文書は表示言語を混在させない。対応文書がある場合だけ、右上の単独リンクで反対言語へ移れるようにする（日本語文書では `English`、英語文書では `日本語`）。

## Release package

日本語packageと英語packageは、それぞれ選択した言語の `docs/` とsample workspaceだけを含める。一方で、トップの `README.md`、`LICENSE.md`、`SECURITY.md` は両packageに同じ日英併記文書を入れる。

トップREADMEの `docs/ja/` と `docs/en/` へのリンクは、梱包時に選択languageの `docs/README.md` へ書き換える。トップ文書から第三者通知を参照する場合は、同じpackage内の `docs/legal/THIRD_PARTY_NOTICES.md` を参照する。

## 作成・更新の優先順位

1. 事実・契約・安全要件は、言語別文書とトップ文書で矛盾させない。
2. 言語固有の操作説明、画面文言、sampleの説明は、必ず対応する `docs/<locale>/` にだけ書く。
3. 両言語の利用者に共通する入手方法、ライセンス、脆弱性報告はトップの共通文書へ書く。
4. 詳細を追加する前に、トップから到達する言語別の正本を更新する。
5. release時は共通3文書の存在・非空・ローカルリンク、選択localeの `docs/`、未選択localeの不混入を検査する。

この方針と個別のrelease実装が矛盾する場合は、データ保護、外部通信禁止、無音要件、言語別配布契約の順で安全側に判断する。