索引を正にし、被参照を描くときに算出し、ずれを点検で見つける仕組み
使う側が書いた索引から、本文の用語のツールチップと、文書を参照している文書の一覧が描かれるまでの考え方。 書き方は 索引と用語集を書く。
文書のメタデータ（題・概要・別名・関連）と用語の意味は、使う側が書く索引の YAML だけに持つ。
索引の形は 索引。
mdmark はブラウザでファイルを読まない。
使う側のサーバーが索引と文書を読み、読んだオブジェクトを mount・render と、参照の表を作る collectReferences、本文の参照を取り出す collectMatches、ずれを見つける checkIndex に渡す。
用語は、索引の terms のほかに、文書の用語集の表（用語集の表）からも入る。
同じ語が複数あるときは、索引の terms、描く文書の表、ほかの文書の表（索引の docs で先に並ぶ文書）の順に優先する。
同じ語かどうかは、NFKC・英字の小文字化・前後の空白の除去で正規化した後で比べる。
タグは、索引の docs[].tags に書き、最上位の tags にタグの語彙（名前・グループ・説明・別名・振り替え先）を任意で置ける。
文書のタグには、その文書の主題を表す印（main: true）を付けられる。
タグは文書を描くことには使わず、Claude Code が find_docs で文書を引くときの絞り込みと並びに使う（Claude Code に使い方を渡す仕組み）。
語彙を置いた索引では、文書のタグを語彙の名前と別名に突き合わせ、点検がずれを知らせる（ずれの点検）。
ある文書を参照している文書（被参照）は、どこにも書かずに、描くときに算出する。 参照は、次のどれかで数える。
| 参照 | 数え方 |
|---|---|
related |
参照元の文書の related に、参照先の id がある（オブジェクトの要素は to が参照先の id） |
| 本文のリンク | 参照元の本文のリンクが、参照先の path を指す |
| 文書の別名 | 参照元の本文に、参照先の aliases が出る |
文書の別名の出現は、別名と本文の文字を正規化して比べて数える。 自分自身は数えない。 参照される側の文書に、参照元を書き足す必要は無い。 文書を書き換えると、参照の表を作り直した次の描画から反映される。
索引の related の要素は、相手（to）・関係の種類（type）・いつ読むか（when）を持つ。
記載するのは関連を持つ側の文書だけで、逆向きは保存せず、描くときと引くときに算出する。
描くときは、相手の文書の末尾の関連文書の一覧に、その文書を参照している文書として並ぶ。
引くときは、find_docs の related_to が、向きと逆向きの名前（required_by など）つきで返す。
change_together だけは、両側に記載する。
被参照を描く文書が、ほかの文書の本文を読まずに済むよう、使う側が全ての文書から参照の表を作って渡す（参照の表を作る）。
参照の表は、文書ごとの被参照と、各文書の用語集の表から入れた用語を持つ。
参照の表を渡さないときは、被参照を索引の related だけから出し、ほかの文書の用語集の表の用語を照合しない。
描く文書の本文に出た用語の語・別名と、文書の別名に、破線の下線を引き、意味と関連文書のツールチップを付ける。
索引の用語と用語集の表のやめた言い方が本文に出たときは、波線のマーカーを引き、代わりの用語の語と意味のツールチップを付ける。
やめた言い方は参照先を持たないため、被参照の一覧にも collectMatches の byDocument・targets にも数えない。
文書の末尾には、その文書を参照している文書の一覧を、題「関連文書」で置く。
索引を渡さないときは、用語集の表から入れた用語だけにツールチップを付け、被参照の一覧を出さない。
索引も用語集の表も無い文書は、これまでどおりに描く。
索引が Schema に合わなくても、用語集の表の列名が表に無くても、本文の描画は止まらない。 合わない文書・用語は除いて使い、用語集の表の誤りはその箇所の書き方の警告で知らせる。
下線とツールチップは画面に描くものだが、使う側の処理が同じ補足を画面なしで受け取りたいことがある（AI へ本文を返すときなど）。
collectMatches は、索引と文書の本文を渡すと、描いた文書の下線・ツールチップと同じ照合で、本文に出た用語・文書の別名の一致を返す（本文の参照を取り出す）。
返すのは、参照先の種類・id・タイトル・短い説明と、一致した文字列・本文の中の位置。
一致した文字列は索引・用語集の表に記載した表記で返し、本文の表記は本文の中の位置から引く。
本文に出たやめた言い方は、byDocument・targets には入れず、代わりの用語（種類・id・タイトル・短い説明）と一致した文字列・本文の中の位置つきで avoided に返す。
同じ実行環境で描いた文書の下線と同じ語が一致し、ツールチップの節ごとの最初の 1 回の制限は効かず、同じ参照先の出現を全て返す。
索引と文書は別々に書くため、文書を移した・消したときにずれが出る。
checkIndex が、索引に無い文書・索引にあって消えた文書・related の切れた id・文字列の関連・片側だけの change_together・本文のリンクと重なる関連・用語の重複・本文に出た用語のやめた言い方・Schema に合わない索引を、ファイル・場所・種類・内容の一覧で返す（索引を点検する）。
ずれの種類は 点検が返すずれ。
change_together の組のうち片方の文書だけが変わった直し忘れは、比べる基準から変わった文書のパスを渡したときだけ点検する。
mdmark check は --base に渡した git の ref と HEAD の merge-base から、変わったファイルを引く。
索引がタグの語彙を置いているときは、語彙に無いタグ（未登録の候補）・やめたタグ・語彙の name の重複・別名の重なり・振り替え先の切れも返す。
文書の読み込みと描画は止めない。
語彙を置いていない索引では、タグのずれを返さない。