wiki-setup

Obsidian のセットアップ — Vault の初期化

新しい Obsidian Wiki Vault をセットアップするか、既存のものを修復します。

ステップ 1：.env を作成する

.env が存在しない場合は、.env.example から作成します。ユーザーに以下を確認します。

1. Vault をどこに置きますか？ → OBSIDIAN_VAULT_PATH

   • デフォルト：~/Documents/obsidian-wiki-vault
   • 絶対パスである必要があります（展開後）

2. ソースドキュメントはどこにありますか？ → OBSIDIAN_SOURCES_DIR

   • 複数のパスをカンマ区切りで指定できます
   • デフォルト：~/Documents
   • ローカルの Git リポジトリのクローン（公開・非公開、ホストを問わず）もここに指定できます。まずリポジトリをローカルにクローンし、そのパスを追加してください。リポジトリソースの処理方法については、wiki-ingest/SKILL.md の「Git リポジトリの取り込み」を参照してください。

3. Claude の履歴をインポートしますか？ → CLAUDE_HISTORY_PATH

   • デフォルト：~/.claude から自動検出します
   • Claude のデータが別の場所にある場合は、明示的に設定してください

4. QMD はインストール済みですか？ → QMD_WIKI_COLLECTION / QMD_PAPERS_COLLECTION / QMD_TRANSPORT

   • 任意です。有効にすると、wiki-query でのセマンティック検索と、wiki-ingest でのソース検出が可能になります。
   • エージェントからローカルの qmd CLI を直接呼び出す場合を除き、デフォルトは QMD_TRANSPORT=mcp にします。
   • CLI モードを使用する場合は、デフォルトで QMD_CLI_SEARCH_MODE=quality を設定します。再ランク付けが遅すぎる場合は、balanced を提案してください。
   • 判断に迷う場合は、今は設定しなくてもかまいません。どちらのスキルも自動的に Grep にフォールバックします。
   • インストール手順については、.env.example の QMD セクションを参照してください。
   • QMD_WIKI_COLLECTION が設定されている場合は、そのコレクションが _raw/ を除外していることを確認してください。 Wiki コレクションと論文コレクションは、別々のレイヤー（編集済みの知識と未加工のステージングデータ）として wiki-query が引用するため、互いに重複しないようにする必要があります。また、OBSIDIAN_VAULT_PATH には _raw/ が含まれるため、qmd collection add <vault> をそのまま実行すると、2 つのコレクションが気付かないうちに統合されます。 ~/.config/qmd/index.yml を読み込み、$QMD_WIKI_COLLECTION のエントリを見つけて、ignore リストに _raw/**（可能であれば、セマンティックな価値のない log.md も）が含まれていることを確認してください。コレクションがまだ存在しない場合は、作成して（qmd collection add "$OBSIDIAN_VAULT_PATH" --name <collection-name>）、その後 index.yml に ignore ブロックを手動で追加します。qmd には --ignore フラグがなく、同じパスに対する 2 回目の collection add も拒否されるため、対象範囲を指定するには YAML を編集するしかありません。編集後に qmd update を実行してください。 コレクションがすでに存在し、ignore ブロックがない場合は、Wiki コレクションが _raw/（wiki-ingest が残した _raw/_archived/ の下書きを含む）をインデックス化していることをユーザーに伝え、ignore ブロックの追加と qmd update の再実行を提案してください。

5. トークン予算の警告しきい値は？ → WIKI_TOKEN_WARN_THRESHOLD

   • デフォルト：100000（Wiki 全体の読み込みに 10 万トークンを超えるコストがかかる場合に警告します）
   • 0 に設定すると、警告を完全に無効にします
   • wiki-status はトークン使用量の表を表示し、この警告を自動的に出します

6. ステージング書き込みを有効にしますか？ → WIKI_STAGED_WRITES

   • デフォルト：未設定／false（ページは最終保存先に直接書き込まれます）
   • チームの Wiki、重大な影響を伴う分野、または LLM が作成したページすべてについて人間が最終判断を行う Vault では、true に設定します
   • 有効にすると、新規ページと更新ページはすべて、まず _staging/ に保存されます。内容を確認して反映するには、/wiki-stage-commit を実行します
   • ファイルの確認待ちがある場合、wiki-status に「ステージング書き込みの保留中」件数が表示されます 設定を解決した後、.skills/llm-wiki/SKILL.md の Config Resolution Protocol に記載されている正確な obsidian_wiki_config_dir アルゴリズムを使って、グローバル設定ディレクトリを割り当てます。共有の執筆プロファイルは、まだ存在しない場合にのみ作成します。既存の $GLOBAL_CONFIG_DIR/WRITING.md は保持してください。上書きしてはいけません。また、執筆スタイルに関する追加の質問はしないでください。

設定から読み込まれている場合は、OBSIDIAN_WIKI_REPO を使います。設定にない場合は、読み込んだこのスキルの絶対パスからリポジトリ／データのルートを絶対パスとして導き出します。その際、パッケージ化された <root>/skills/wiki-setup/SKILL.md のレイアウトと、ソースの <root>/.skills/wiki-setup/SKILL.md のレイアウトを区別します。その後、次の両方の標準テンプレートレイアウトを確認します。

• パッケージ化されたインストール：<root>/skills/llm-wiki/references/WRITING.md
• ソースチェックアウト：<root>/.skills/llm-wiki/references/WRITING.md

GLOBAL_CONFIG_DIR="$(obsidian_wiki_config_dir)"
mkdir -p "$GLOBAL_CONFIG_DIR"

SKILL_FILE="<absolute path of this loaded wiki-setup/SKILL.md>"
SKILL_DIR="$(cd "$(dirname "$SKILL_FILE")" && pwd)"
if [ -n "${OBSIDIAN_WIKI_REPO:-}" ]; then
  WIKI_ROOT="${OBSIDIAN_WIKI_REPO%/}"
else
  case "$SKILL_DIR" in
    */.skills/wiki-setup) WIKI_ROOT="${SKILL_DIR%/.skills/wiki-setup}" ;;
    */skills/wiki-setup) WIKI_ROOT="${SKILL_DIR%/skills/wiki-setup}" ;;
    *) echo "Cannot derive writing-profile template root from $SKILL_DIR" >&2; exit 1 ;;
  esac
fi

WRITING_TEMPLATE=""
for candidate in \
  "$WIKI_ROOT/skills/llm-wiki/references/WRITING.md" \
  "$WIKI_ROOT/.skills/llm-wiki/references/WRITING.md"
do
  if [ -f "$candidate" ]; then
    WRITING_TEMPLATE="$candidate"
    break
  fi
done
[ -n "$WRITING_TEMPLATE" ] || { echo "Writing profile template not found under $WIKI_ROOT" >&2; exit 1; }

WRITING_PROFILE="$GLOBAL_CONFIG_DIR/WRITING.md"
if [ ! -e "$WRITING_PROFILE" ]; then
  cp "$WRITING_TEMPLATE" "$WRITING_PROFILE"
fi

ステップ 2：Vault のディレクトリ構造を作成する

mkdir -p "$OBSIDIAN_VAULT_PATH"/{concepts,entities,skills,references,synthesis,journal,projects,_archives,_raw,_staging,.obsidian}

• .obsidian/ — Obsidian 独自の設定です。Vault として認識されるようになります。
• projects/ — プロジェクトごとのナレッジです（取り込み時に追加されます）。
• _archives/ — 再構築／復元用の wiki スナップショットを保存します。
• _raw/ — 未処理の下書きを置くステージング領域です。粗いメモをここに置くと、wiki-ingest が適切な wiki ページに変換し、元のファイルを _raw/_archived/（初回使用時に作成）へ移動します。
• _staging/ — WIKI_STAGED_WRITES=true の場合に、LLM が作成したページを確認するためのキューです。ここにあるページは、/wiki-stage-commit で昇格するまで Obsidian のグラフに表示されません。

ステップ 3：特別なファイルを作成する

obsidian-wiki setup --vault <path> [--timezone <IANA name>] を実行すると、これらのファイルがすべて一度に作成されます。以下のテンプレートは、手動でセットアップする場合に書き込まれる内容です。

index.md

---
title: Wiki Index
---

# Wiki Index

*This index is automatically maintained. Last updated: TIMESTAMP*

## Concepts

*No pages yet. Use `wiki-ingest` to add your first source.*

## Entities

## Skills

## References

## Synthesis

## Journal

log.md

---
title: Wiki Log
---

# Wiki Log

- [TIMESTAMP] INIT vault_path="OBSIDIAN_VAULT_PATH" categories=concepts,entities,skills,references,synthesis,journal

hot.md

---
title: Hot Cache
updated: TIMESTAMP
---

# Hot Cache

*A ~500-word semantic snapshot of recent activity. Updated after every major write operation.*

## Recent Activity

- [TIMESTAMP] INIT — vault created at OBSIDIAN_VAULT_PATH

## Active Threads

*None yet — start ingesting sources to populate.*

## Key Takeaways

*None yet.*

## Flagged Contradictions

*None yet.*

.manifest.json

取り込みスキルが追記するための追跡ファイルを用意し、obsidian-wiki doctor で Vault が完全な状態として報告されるように、空のマニフェストを作成します（.manifest.json は必須のコアファイルとして扱われます）。

printf '{}\n' > "$OBSIDIAN_VAULT_PATH/.manifest.json"

ステップ 4：.obsidian の設定を作成する

すぐに快適に使えるよう、最小限の Obsidian 設定を作成します。

.obsidian/app.json

{
  "strictLineBreaks": false,
  "showFrontmatter": false,
  "defaultViewMode": "preview",
  "livePreview": true
}

.obsidian/appearance.json

{
  "baseFontSize": 16,
  "enabledCssSnippets": ["obsidian-wiki-folders"]
}

フォルダーの色とグラフのデフォルト設定

obsidian-wiki setup は、.obsidian/snippets/obsidian-wiki-folders.css（ファイルエクスプローラーでカテゴリーフォルダーごとに色を設定し、_ で始まるフォルダーを暗く表示）と、.obsidian/graph.json（グラフビューで同じ色を使い、_raw/、_archives/、_staging/、_meta/、index、log、hot を除外）も書き込みます。CLI が利用できる場合は、手動で書き込む代わりに obsidian-wiki setup --vault "$OBSIDIAN_VAULT_PATH" を実行してください。既存の .obsidian ファイルは上書きしないでください。後から色を変更するには、graph-colorize を使ってください。

ステップ 5：Obsidian プラグインを推奨する

次のおすすめコミュニティプラグインをユーザーに紹介します（手動でインストールします）。

1. Dataview — ページのメタデータをクエリし、動的な表を作成します。wiki に欠かせないプラグインです。
2. Graph Analysis — 接続を探索するための、機能強化されたグラフビューです。
3. Templater — テンプレートを使って手動でページを作成したい場合に便利です。
4. Obsidian Git — Vault を git リポジトリに自動バックアップします。

Step 6: セットアップを確認する

簡単な健全性チェックを実行します。

• Vault ディレクトリに次のディレクトリが存在する：concepts/、entities/、skills/、references/、synthesis/、journal/、projects/、_archives/、_raw/
• Vault のルートに index.md が存在する
• ユーザーがタイムゾーンを選択した場合、index.md のフロントマターに timezone: が含まれている（obsidian-wiki memory status で使用中のタイムゾーンを確認できます）
• Vault のルートに log.md が存在する
• Vault のルートに hot.md が存在する
• Vault のルートに .manifest.json が存在する（空の {} でも問題ありません）
• .env に OBSIDIAN_VAULT_PATH が設定されている
• .obsidian/ ディレクトリが存在する
• _staging/ ディレクトリが存在する（WIKI_STAGED_WRITES が設定されていない場合も必須です。今後の使用に備えてセットアップ時に作成されます）
• 解決されたグローバル設定ディレクトリに WRITING_PROFILE が存在する
• ソースディレクトリ（設定されている場合）が存在し、読み取り可能である

結果を報告します。解決された WRITING_PROFILE の絶対パスも含め、ユーザーが次の操作を実行できることを伝えます。

1. Obsidian で Vault を開く（File → Open Vault → ディレクトリを選択）
2. wiki-status を実行して、取り込み可能な項目を確認する
3. wiki-ingest を実行して、最初のソースを追加する
4. claude-history-ingest を実行して、Claude での会話をマイニングする
5. codex-history-ingest を実行して、Codex のセッションをマイニングする（Codex を使用している場合）
6. いつでも wiki-status を再実行して、差分を確認する

オプション：Stop フックをインストールする（自動キャプチャ）

ユーザーに尋ねます：「セッション終了時に調査結果を自動キャプチャしますか？」

「はい」の場合、Stop フックをユーザーのグローバルな Claude Code 設定にインストールします。これにより、意味のある作業を行ったセッションでは、終了前に /wiki-capture --quick の実行が自動的に促されます。

フックの動作： Stop 時にセッションのトランスクリプトを読み取り、ファイル編集とシェル呼び出しの数をカウントします。重要な作業が行われた場合は、Claude に /wiki-capture --quick を一度実行するよう促します。wiki-capture のクイックモードにある KEEP/SKIP ゲートがノイズを防ぎ、通常のセッションや結論の出なかったセッションは自動的にスキップされます。

インストール手順：

1. obsidian-wiki リポジトリのパスを確認します。設定で OBSIDIAN_WIKI_REPO が設定されている場合は、その値を使用します。設定されていない場合は、一般的な場所である ~/Documents/projects/obsidian-wiki、~/obsidian-wiki を確認するか、ユーザーに尋ねます。

2. wiki-stop-capture.sh スクリプトを探します。パスは pip/uv でのインストールとソースチェックアウトで異なるため、<REPO_PATH> 以下の両方の構成を確認し、最初に見つかったものを使用します。

   • <REPO_PATH>/hooks/wiki-stop-capture.sh — パッケージ済みのインストール（OBSIDIAN_WIKI_REPO はバンドルされた _data/ ディレクトリを指しており、そこには hooks/ 以下にフックが含まれています）。
   • <REPO_PATH>/.claude/hooks/wiki-stop-capture.sh — ソースチェックアウト。

   どちらも見つからない場合（フックの同梱より前の古い wheel など）は、正規のコピーを安定した場所に取得し、代わりにそのパスを指定します。llm-wiki/SKILL.md の Config Resolution Protocol に記載されたグローバル設定ディレクトリを使用します（デフォルトは XDG 形式の ~/.config/obsidian-wiki。すでに存在する場合は従来の ~/.obsidian-wiki を使用します）。

   CONFIG_DIR="$( [[ -d "$HOME/.obsidian-wiki" && ! -e "${XDG_CONFIG_HOME:-$HOME/.config}/obsidian-wiki" ]] && echo "$HOME/.obsidian-wiki" || echo "${XDG_CONFIG_HOME:-$HOME/.config}/obsidian-wiki" )"
   mkdir -p "$CONFIG_DIR/hooks"
   curl -fsSL https://raw.githubusercontent.com/Ar9av/obsidian-wiki/main/.claude/hooks/wiki-stop-capture.sh \
     -o "$CONFIG_DIR/hooks/wiki-stop-capture.sh"
   chmod +x "$CONFIG_DIR/hooks/wiki-stop-capture.sh"
   

   解決した絶対パスを、以下の <HOOK_PATH> として使用します。

3. フックエントリを ~/.claude/settings.json にマージします。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash <HOOK_PATH>"
          }
        ]
      }
    ]
  }
}

~/.claude/settings.json がすでに存在し、hooks.Stop 配列がある場合は、置き換えずに新しいエントリを追加します。既存のフックを上書きしないでください。

注 — このリポジトリ内では通知が重複する場合があります。 obsidian-wiki リポジトリには、同じ Stop フックを相対パスで登録する、Git で追跡されている .claude/settings.json が含まれています。Claude Code はプロジェクトレベルとユーザーレベルのフック設定を、一方で他方を上書きするのではなくマージします。そのため、リポジトリ内で終了するセッションでは両方の登録が実行されます。これは想定どおりであり、問題ありません。フックはセッションごとにアトミックなセンチネルを確保するため、通知は一度だけ送られます。両方の設定を残してください。プロジェクト側のエントリを削除すると、追跡対象のフレームワークファイルに変更が生じ、グローバルインストールを行わずにリポジトリをクローンしたユーザーがキャプチャを利用できなくなります。

4. 次のように確認します：「Stop フックをインストールしました。ファイルを書き込むか、シェルコマンドを 4 回以上実行したセッションの終了時に、Claude Code が /wiki-capture --quick の実行を促します。」

後でアンインストールするには： ~/.claude/settings.json からフックエントリを削除するか、シェルで WIKI_STOP_CAPTURE=false を設定すると、単一のセッションでキャプチャをスキップできます（HIVEMIND_CAPTURE=false も引き続き有効です）。

オプション：GitHub 同期を設定する

ユーザーに「ボルトをプライベートな GitHub リポジトリに同期しますか？」と尋ねます。

ボルトはプレーンな Markdown なので、Git にプッシュすると、バージョン履歴、バックアップ、デバイス間同期を無料で利用できます。これはオプトインです。ユーザーが希望しない場合や、まだリポジトリを用意していない場合はスキップしてください。

はいの場合：

1. リポジトリの URL（例：https://github.com/you/my-wiki.git）を尋ねます。ボルトに個人的なメモが含まれている場合は、プライベートにすることをおすすめします。
2. git init、デフォルトの .gitignore、origin リモートの設定を処理する CLI を実行します。これは obsidian-wiki setup の対話型プロンプトと setup.sh が使うものと同じコードパスであり、正しく保つ必要のある実装が一つで済みます（その理由については issue #153 を参照してください）。

   obsidian-wiki sync-setup "<repo-url>" --vault "$OBSIDIAN_VAULT_PATH"
   

   obsidian-wiki バイナリが PATH にない場合（インストールせずにソースをチェックアウトした場合）は、代わりにリポジトリから実行します。利用可能な OBSIDIAN_WIKI_REPO またはローカルのチェックアウトパスを使用して、PYTHONPATH="$OBSIDIAN_WIKI_REPO" python3 -m obsidian_wiki.cli sync-setup ... を実行してください。
3. その後いつでも obsidian-wiki sync を実行すれば、保留中のボルトの変更をコミットしてプッシュできることをユーザーに伝えます（すべてをステージングし、タイムスタンプ付きでコミットして、プッシュします）。同期状態を確認するための設定ファイルはありません。ボルト自体の git remote が信頼できる情報源です。

オプション：セットアップ後に QMD を更新する

QMD_WIKI_COLLECTION が設定されていて、ローカルの QMD CLI が利用可能な場合は、初期ボルトファイルが作成された後に qmd update を実行し、新しいボルトをすぐにクエリできるようにします。セットアップ時のボルトは空のため、通常は埋め込み処理を実行する必要はなく、すでにページを追加していない限り、通常の更新だけで十分です。実行前に、Step 1.4 で説明されている _raw/ の除外設定が適用されていることを確認してください。適用されていない場合、この更新で現在空のステージングディレクトリもウィキコレクションにインデックスされ、今後そこに置かれる下書きがすべて気付かれないまま加わってしまいます。