indexion-readme

indexion readme — README の構築

テンプレート、ドキュメントコメント、手書きの文章、パッケージごとの README から、プロジェクトの README を構築します。このスキルでは構築側を扱います。具体的には、ひな形の作成、生成、計画、組み立て、検証です。既存ドキュメントの評価については、indexion-documentation を参照してください。

ファイルの配置場所

規約はプロジェクトによって異なるため、編集する前に実際に存在するものを確認してください。

アセット	確認された配置パターン
設定	doc.json（リポジトリのルート）または .indexion/readme/doc.json
パッケージごとのテンプレート	docs/templates/readme.md（SoT 定数なし。--template で指定）
静的な文章	docs/intro.md、docs/installation.md、docs/license.md、…
パッケージごとの README	cmd/<name>/README.md、src/<name>/README.md
組み立てられたルート README	通常は README.md。一部のプロジェクトでは .mbt.md サフィックスを使用し、そのファイルを MoonBit doctest モジュールとしても扱います。この場合、README.md は README.mbt.md へのシンボリックリンクです。
.indexion.toml	[doc] config_path / per_package が doc.json を自動読み込み

最初に確認することは、git diff / ls -la を使って、README.md がシンボリックリンクかどうか、doc.json（ルートまたは .indexion/readme/ 配下）があるかどうか、.indexion.toml があるかどうかを調べることです。これらがあれば、README が手動管理、ビルドによる組み立て、またはそのハイブリッドのどれなのかがわかります。

ワークフローの概要

doc init                      → .indexion/readme/template.md + doc.json (greenfield)
edit doc.json + docs/*.md     → declare sources of truth
doc readme --per-package      → cmd/<pkg>/README.md (API skeletons; non-overwriting)
hand-write each per-package README's Overview / Usage / Options / Examples
doc readme --config           → assembled root README
plan drift <prev> <new>       → verify the assembled output (or hand-edit) is purely additive

ステップ 1：初期化（新規プロジェクトのみ）

indexion doc init <project-dir>

.indexion/readme/template.md と .indexion/readme/doc.json を作成します。すでに doc.json がある場合、または .indexion.toml がそのファイルを参照している場合は、このステップを省略してください。

ステップ 2：doc.json を設定する

{
  "$schema": "./schemas/doc-config.schema.json",
  "version": "1.0",
  "spec": "moonbit",
  "output": { "format": "markdown", "filename": "README.md" },
  "packages": [
    {
      "path": "cmd/<name>",
      "title": "<command name>",
      "include_in_root": true,
      "sections": ["overview", "usage"]
    }
    // …one entry per package that should appear in the assembled root README
  ],
  "root": {
    "output": "README.md",
    "sections": [
      { "type": "static",   "file": "docs/intro.md" },
      { "type": "toc",      "title": "Commands" },
      { "type": "packages", "filter": "cmd/**" },
      { "type": "static",   "file": "docs/installation.md" },
      { "type": "static",   "file": "docs/license.md" }
    ]
  }
}

ルートセクションの種類：

• static — Markdown ファイルをそのまま挿入します
• toc — 目次の見出しを挿入します
• packages — packages 配列の項目を glob でフィルタリングして取り込みます

パッケージのフィールド：

• include_in_root — 組み立てたルート README に含めるかどうか
• sections — 抽出する README の見出し。パッケージごとの抽出処理で使用されます。ルートの { "type": "packages" } は、現在、パッケージごとの sections が示唆する Overview/Usage の詳細展開ではなく、パッケージへのリンクをまとめた表を出力する点に注意してください。詳しくは以下の「既知の制限」を参照してください。

ステップ 3：パッケージごとの README を生成する

indexion doc readme --per-package src/ cmd/

README がまだない各パッケージディレクトリに README.md を生成します。既存ファイルは上書きされません。パッケージごとの README はそのまま残ります。

生成されるひな形は API のみです（KGF を通じて /// ドキュメントコメントから抽出）。これを出発点として、後から文章のセクション（Overview、Usage、Options、Examples）を手書きしてください。

# Single package to stdout
indexion doc readme src/kgf/lexer/

# Single package to a file
indexion doc readme -o=README.md src/kgf/lexer/

副作用に関する注意： doc readme --template=<t> <paths...>（以下のテンプレートベースのモード）は、指定されたパスを走査し、--per-package を指定していなくても、README がないパッケージにはパッケージごとの README を自動作成します。広い範囲のパス（cmd/、src/）を指定して実行すると、関係のないパッケージにも新しいファイルが作成される可能性があります。狭い範囲のパスを指定するか、実行後に git status を確認して、意図しないファイルを削除してください。

ステップ 4：静的コンテンツを作成する

root.sections が参照する docs/intro.md、docs/installation.md などを作成します。これらは手書きの文章であり、アセンブラーはそのまま取り込みます。

ステップ 5：執筆計画を生成する（任意）

indexion plan readme --template=docs/templates/readme.md --plans-dir=.indexion/plans src/

手動または LLM を使った執筆のために、セクションごとの執筆タスクを出力します。

ステップ 6：README を組み立てる

# Config-driven (preferred; doc.json controls layout and packages list)
indexion doc readme --config=doc.json

# Template-driven (alternative; {{include:…}} and {{packages}} placeholders)
indexion doc readme --template=docs/templates/readme.md -o=README.md cmd/

設定ファイルはリポジトリのルートにも .indexion/readme/ 配下にも置けます。.indexion.toml に [doc] config_path = "…" があれば、--config= フラグは省略できます。

ステップ 7：plan drift で検証する

再生成またはルートの README を手動編集した後、変更が純粋な追加であることを確認します（気付かない削除や、無関係なセクションの再配置がないこと）。

# Snapshot the previous version
git show HEAD:README.md > /tmp/README.before.md

# Compare against the new version
indexion plan drift --top=20 /tmp/README.before.md README.md

出力で確認する項目：

• Drift terms in /tmp/README.before.md (missing on the other side): (none) — 削除されたものはありません
• Drift terms in README.md (missing on the other side): … — 追加する予定だった語彙（コマンド名、新しいフラグ、新しい概念）のみです
• 小規模な追加変更では Cosine similarity が 1.0 に近く、セクションの構成を大幅に変更した場合はかなり低くなります

CI との連携：

indexion plan drift --vocab-threshold=0.05 /tmp/README.before.md README.md
# exits 1 if cosine_distance > 0.05 — useful as a guard against accidental large rewrites

この同じワークフローは、翻訳済み README のペア（README.md ↔ README-ja.md）にも適用できます。語彙のサブトークン化が kgfs/natural/ の自然言語 KGF に処理を委ねるため、言語をまたいだドリフト検出が標準で機能します。

テンプレート構文

テンプレートファイルでは、{{placeholder}} による置換をサポートしています。

プレースホルダー	展開内容
{{include:path}}	ファイルの内容（プロジェクトルートからの相対パス）
{{packages}}	検出されたすべてのパッケージ（CLI の --include / --exclude で絞り込み）
{{module_doc}}	モジュールレベルのドキュメントのみ

.indexion.toml との連携

[doc]
config_path = "doc.json"   # auto-loads doc.json without --config
per_package = true         # makes `doc readme <path>` default to --per-package

明示的に指定した --config=… が常に優先されます。

既知の制限：packages ルートセクションは詳細な展開ではなく、テーブルを生成します

doc-config.schema.json では、各 packageEntry に sections: ["overview", "usage", …] を指定できますが、現在の doc readme --config 実装では、ルートで { "type": "packages" } を出力する際に、これらのセクションをインライン展開しません。出力されるのは、説明が空のパッケージリンクの Markdown テーブルです。

これにより、実務上は次の 2 点に注意が必要です。

1. プロジェクトのチェックイン済みルート README にコマンドごとの詳しい Overview / Usage の段落がある場合、それらは現状の doc readme --config によって生成されたものではありません。手動で管理されています。doc readme --config -o=/tmp/regen.md とチェックイン済み README を比較すると、手動で整備された部分がどれくらいあるか確認できます。差分が非常に大きい場合、README の大部分が手動で管理されています。
2. 新しいコマンドを追加する場合、doc.json へのパッケージエントリの追加と、パッケージごとの README の作成に加え、組み立て済み README に詳細セクションも手動で追加する必要があります。上記の plan drift 検証を使い、手動編集が削除を伴わず、追加のみであることを確認してください。

この制限を修正した場合（{ "type": "packages" } が各エントリの sections を反映するようにした場合）、このスキルからこのセクションを削除してください。

よくある落とし穴

「doc readme --per-package を実行しても何も生成されない」

• すべてのパッケージにすでに README があります。このコマンドは新しいファイルのみを作成し、既存のファイルは上書きしません。再生成するには、先に既存の README を削除してください。

「cmd/ で doc readme --template … を実行したら、触れていないパッケージにも README が作成された」

• テンプレートモードでは、副作用として、存在しないパッケージごとの README が自動生成されます。対象を絞ったパスを指定するか、git status で意図せず作成されたファイルを元に戻してください。

「自動生成されたパッケージごとの README が API の一覧だけになっている」

• これは意図された動作です。Overview、Usage、Options、Examples は手動で記述してください。CLI コマンドの正式な動作仕様は indexion <command> --help にあります。

「README.md を手動編集したら、doc readme --config によって変更が消されてしまう」

• アセンブラーが詳細な形式を生成するようになった場合は、変更が消えます（「既知の制限」を参照）。それまではアセンブラーが厳密なサブセット（テーブル）を生成するため、詳細セクションへの手動編集は保持されます。必ず plan drift で相互チェックし、確認してください。

「README.md の編集で無関係なセクションが壊れた」

• plan drift HEAD:README.md README.md を実行し、以前のバージョンについて「missing on the other side」の出力を確認してください。(none) 以外が表示された場合は、内容を削除しています。