indexion-wiki

indexion wiki

indexion の wiki システムは、wiki.json マニフェストによって管理される Markdown ファイル群として、.indexion/wiki/ にナレッジベースを維持します。

wiki ページは単なる .md ファイルではありません

wiki ページは、同期が保たれた4つの成果物で構成されます。

成果物	ファイル	更新するコマンド
ページの内容	<id>.md	wiki pages add、wiki pages update
マニフェストエントリー	wiki.json	wiki pages add、wiki pages update
検索インデックス	vectors.db、search-sections.json、tfidf-vocabulary.json	wiki pages update、wiki index build --full
監査ログ	log.json	wiki を変更するすべてのコマンド

wiki pages update は4つすべてを一度に更新します。 .md ファイルを直接編集すると、更新されるのは最初の成果物だけです。残りの3つは古くなり、検索結果が古いままになり、マニフェストの出所情報が誤ったものになり、ログにも変更の記録が残りません。

.md を直接編集した場合（例：Edit ツールを使用）、必ず直後に次の操作を行ってください。

indexion wiki pages update \
  --id=<page-id> \
  --content=.indexion/wiki/<page-id>.md \
  --sources="<comma-separated sources from wiki.json>" \
  --provenance=synthesized \
  --actor="agent:claude" \
  --wiki-dir=.indexion/wiki

すべての wiki ページには、マニフェストに次の出所情報フィールドも含まれます。

• provenance: "extracted" | "synthesized" | "manual"
• last_actor: "indexion" | "agent:<name>" | "user"

コマンド構成

indexion wiki
  ├── pages
  │   ├── plan    -- propose page structure (init-like)
  │   ├── add     -- create a new page (writes .md + manifest + index + log)
  │   ├── update  -- update an existing page (writes .md + manifest + index + log)
  │   └── ingest  -- detect stale pages by hashing sources
  ├── index
  │   └── build   -- rebuild index.md (and optionally vectors.db)
  ├── lint        -- structural integrity checks (no LLM needed)
  ├── export      -- export to GitHub/GitLab wiki format
  ├── import      -- import from GitHub/GitLab wiki format
  └── log         -- operation audit trail

wiki のナビゲーション（エージェント向け）

個々のページを読む前に、まずインデックスを確認してください。

# Generate or regenerate index.md — the entry point for navigation
indexion wiki index build --wiki-dir=.indexion/wiki

# Then read it
cat .indexion/wiki/index.md

index.md には、カテゴリ別のページ一覧と、ハブページ（最も多くリンクされているページ）が記載されています。ハブページは、よく知らないコードベースを理解するための最適な出発点です。

新しいページの作成

# 1. Write content to a temp file
cat > /tmp/my-page.md << 'EOF'
# My Page Title
...content...
EOF

# 2. Register it — this writes .md, updates wiki.json, updates search index, appends log
indexion wiki pages add \
  --id=my-page \
  --title="My Page Title" \
  --content=/tmp/my-page.md \
  --sources="src/my-module/" \
  --provenance=synthesized \
  --actor="agent:claude" \
  --wiki-dir=.indexion/wiki

--sources フィールドは、変更追跡のためにページとソースファイルを関連付けます。必ず指定してください。ソースがないページは wiki pages ingest で検出されません。

既存ページの更新

# 1. Write new content to a temp file
cat > /tmp/updated.md << 'EOF'
# Updated Page
...new content...
EOF

# 2. Update — this overwrites .md, updates wiki.json metadata,
#    incrementally updates the search index, and appends to log.json
indexion wiki pages update \
  --id=existing-page \
  --content=/tmp/updated.md \
  --sources="src/my-module/,src/other/" \
  --provenance=synthesized \
  --actor="agent:claude" \
  --wiki-dir=.indexion/wiki

想定される出力：Updated page 'existing-page' (search index updated)

更新が必要な項目の検出

# Find pages whose source files have changed since the last run
indexion wiki pages ingest --wiki-dir=.indexion/wiki

# Preview without recording the new hash state
indexion wiki pages ingest --dry-run --wiki-dir=.indexion/wiki

ingest は、wiki.json に記載されたすべてのソースファイルのハッシュを計算し、.indexion/wiki/ingest-manifest.json と比較します。更新タスクリストを出力しますが、ページ自体は書き換えません。これはエージェントの役割です。

ワークフロー：

1. wiki pages ingest を実行して、タスクリストを取得します。
2. 各タスクについて、変更されたソースファイルを読みます。
3. wiki pages update で wiki ページを更新します。
4. ingest を再実行します。注意が必要なページが0件と報告されるはずです。

構造的整合性の検証

# Run all 6 structural checks
indexion wiki lint --wiki-dir=.indexion/wiki

チェック項目	検出内容
リンク切れ	存在しないページへの wiki://page-id 参照
孤立ページ	ナビゲーションツリーから到達できず、他のページからもリンクされていないページ
相互参照の不足	ソースファイルを共有しているにもかかわらず、互いにリンクしていないページ
古いソース	ディスク上に存在しなくなった sources のパス
空のページ	内容がほとんどないページ
マニフェストとファイルの不一致	対応する .md ファイルがない wiki.json エントリー（またはその逆）

新しいページを書いた後は、必ず wiki lint を実行し、完了前に問題を修正してください。

関連する概念が複数のページに分かれている場合、相互参照に関する警告はよく発生します。wiki://page-id リンクを含む ## See Also セクションを追加して修正してください。

内容の正確性の検証（plan reconcile）

wiki lint は構造上の問題を検出します。plan reconcile は意味上のずれ、つまり wiki ページに記載されたコードシンボルがまだ存在するか、またページの最終記述以降にコードが変更されているかを検出します。

必ずプロジェクトのルート（.）を対象にしてください。 --doc フラグは対象となるドキュメントを絞り込みますが、対象ディレクトリによってコードシンボルの範囲が決まります。サブディレクトリを対象にするとシンボルの集合が小さくなり、フラグメント数が0のレポートが出力されます。

indexion plan reconcile \
  --doc='.indexion/wiki/*.md' \
  --doc-spec=markdown \
  --format=md \
  .

レポートの読み方

概要 — 主要指標は New logical reviews（前回の実行以降に発生した新たな差分）です。

推奨レビューグループ — 対応が必要な項目の中心です。

カテゴリ	意味	対応
stale_doc	Wiki ページの最終更新後にコードが変更された	wiki pages update でページを更新します
missing_doc	対応する Wiki の記載がないコードシンボル	記載を追加するか、wiki pages add で新しいページを作成します
review_both	コードより Wiki のほうが新しい	Wiki の内容が正しいことを確認します。これはメンテナンスサイクル後に想定される状態です

各グループには、影響を受けるシンボルと、関連する Wiki ページを示す Docs: が記載されています。 Docs: 行のないグループは、そのモジュールをカバーする Wiki ページがありません。

メンテナンス後も残る候補

整合性確認の候補がゼロになることはありません。候補が残り続ける原因は次の 3 つです。

1. Wiki ページのないモジュールでは missing_doc が発生します。記載が必要であれば、ページを作成してください。
2. 修飾されたメソッド名（Wiki 内の Type::method）は、修飾なしのシンボル名 （コード内の method）と一致しません。項目を追加する前に、Wiki 内でシンボル名を検索して確認してください。
3. 同名のシンボルが複数のモジュールにある場合（get、tokenize、to_json_string）、モジュールをまたいだ誤検出が発生します。Wiki ページが実際にどのモジュールについて記述しているか確認してください。

収束の指標として New logical reviews を追跡します。この値がゼロになれば、対応が必要な差分はすべて解消されています。

Wiki のメンテナンスサイクル全体

# 1. Detect stale pages (source files changed)
indexion wiki pages ingest --wiki-dir=.indexion/wiki

# 2. Read the index to understand the wiki structure
cat .indexion/wiki/index.md

# 3. For each stale page: read changed sources, write new content to temp file,
#    then update through the command (NOT by editing .md directly)
indexion wiki pages update --id=<page-id> --content=/tmp/updated.md \
  --sources="..." --provenance=synthesized --actor="agent:<name>" \
  --wiki-dir=.indexion/wiki

# 4. Verify structural integrity
indexion wiki lint --wiki-dir=.indexion/wiki

# 5. Verify content accuracy — target project root, iterate until NLR=0
indexion plan reconcile \
  --doc='.indexion/wiki/*.md' \
  --doc-spec=markdown \
  --format=md \
  .
# → Fix stale_doc groups first. Re-run. Expect 2-3 rounds.
# → For each fix, use `wiki pages update`, not direct .md edits.

# 6. Regenerate the navigation index
indexion wiki index build --wiki-dir=.indexion/wiki

# 7. Confirm everything is current
indexion wiki pages ingest --dry-run --wiki-dir=.indexion/wiki

新しい Wiki をゼロから計画する

Wiki がまだ存在しない場合や、構造を大幅に見直す必要がある場合：

# Analyze the project and generate a page structure proposal
indexion wiki pages plan --format=md <project-dir>

# Then execute the plan: add each proposed page
indexion wiki pages add --id=<id> --title="..." --content=/tmp/page.md \
  --sources="..." --provenance=synthesized --actor="agent:<name>"

初期化の手順は不要です。 最初の wiki pages add の呼び出しで、.indexion/wiki/ と空の wiki.json マニフェストが自動的に作成されます。個別の wiki init コマンドはありません。

wiki pages plan は CodeGraph を使って、ファイル単位ではなく概念単位のページを提案します。 ファイル単位のページ（例：「src/kgf/lexer/lexer.mbt」）より、概念単位のページ（例：「KGF System」）を優先してください。

検索インデックスの構築

# Build navigation index only (index.md)
indexion wiki index build --wiki-dir=.indexion/wiki

# Build navigation + vector search index (vectors.db)
indexion wiki index build --full --wiki-dir=.indexion/wiki

# Preview index.md without writing
indexion wiki index build --dry-run --wiki-dir=.indexion/wiki

--full を指定すると、indexion search .indexion/wiki/ はクエリごとに最初から再構築するのではなく、事前に構築されたベクトルを使用します。

監査証跡の確認

# Recent operations
indexion wiki log --wiki-dir=.indexion/wiki --tail=20

# Full log as JSON
indexion wiki log --wiki-dir=.indexion/wiki --json

pages add、pages update、lint、pages ingest、index build を呼び出すたびに、.indexion/wiki/log.json に記録が追加されます。このログを使って、以前のエージェントの実行が正常に完了したことを確認したり、ページが最後に変更された理由を把握したりできます。

主な注意点

バッククォートで囲まれた wiki:// 参照はリンクではありません。 lint チェッカーは、コードスパン内の wiki:// を正しく無視します。実際の相互参照を作成するには、バッククォートで囲まない wiki://page-id または Markdown リンク [Title](wiki://page-id) を使用してください。

wiki pages ingest は、最後に実行した時点の状態をマニフェストに記録します。 pages update でページの sources リストに新しいソースファイルを追加すると、次回の ingest 実行時に、そのページは対応が必要なものとして表示されます（新しいソースのハッシュが記録されていないためです）。これは想定される動作です。更新後にもう一度 ingest を実行して、ベースラインを記録してください。