> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent 向けインストールガイド

> このページを AI Agent に渡せば、Linkly AI のインストール・統合・検証をあなたの代わりに案内してくれます

このページは人間ではなく、主に **AI Agent** に向けて書かれています。

Claude Code、Codex、Cursor のようなシェルアクセスを持つ AI アシスタントをお使いなら、以下の一文をコピーしてアシスタントに送ってください。アシスタントがこのページを読み、セットアップを案内します：

```
https://linkly.ai/docs/ja/agent-setup.md を読んで、Linkly AI のインストールと統合を案内してください
```

もちろん、ご自身で読み進めていただいても構いません。これは人間が読んでも完結するセットアップガイドです。ただし通常のガイドより率直な書き方をしており、各ステップが本当に成功したかをどう見極めるかに重点を置いています。AI アシスタントがウェブにアクセスできない場合は、右上の **Copy page** からこのページを生の Markdown として取得し、そのまま貼り付けてください。

***

## AI Agent へ

以下はすべてあなたに向けた指示です。作業を始める前に、最後まで読んでください。

### あなたのタスク

ユーザーの Linkly AI のインストールと統合を案内します。次の状態になったら完了です：

1. Linkly AI デスクトップアプリがインストール・初期化され、インデックス作成が動作していること。**同梱のサンプルだけでも達成とみなして構いません。** ユーザー自身のドキュメントが入っていれば、なお良いです。かつ
2. あなた（またはユーザーが所有する別の AI ツール）が Linkly AI の検索ツールを実際に呼び出し、実在のドキュメントを見つけられること。

### あなたの権限範囲とルール

自分で実行してよいことと、ユーザーに委ねなければならないことがあります。**越権行為をせず、ユーザーの代わりに結果を決めつけないでください：**

* **自分で実行してよいこと**：診断コマンドの実行、CLI のインストール、MCP の設定、Skills のインストール、検証コマンドの実行、エラーの解釈、結果の報告。ソフトウェアをインストールするものについては、**先にコマンドを提示し、同意を得てください**。
* **ユーザーが行う必要があること**：インストーラーのダウンロードと実行、セットアップウィザードの完了、アプリ内でのドキュメントフォルダの追加、システム権限の付与。これらは GUI 操作であり、あなたが代わりに行うことはできません。

そして、いくつかの厳守ルール：

* **行動する前に診断すること。** ユーザーはすでに途中までセットアップ済みかもしれませんし、再インストール中かもしれません。頭から機械的に全ステップを実行しないでください。
* **各ステップを必ず検証すること。** 各ステップには合格判定基準が記載されています。基準を満たさないうちは次に進まないでください。
* **ユーザーの操作が必要な場面では、必要なことを一度にすべて伝え、そこで止まって 1 回の返信を待つこと。** 1 つの作業を何往復もの確認に分割しないでください。
* **インストールコマンドは提示して同意を得てから実行すること** — 特にネットワークからスクリプトをダウンロードして実行するものは必ず確認を取ってください。
* **進捗を誇張しないこと。** 検証できていないものは完了していません。どこで詰まり、何を試したかを正確に伝えてください。
* **権限・セキュリティ・検証の要件を回避しないこと。** トラブルシューティングで扱われていない問題に遭遇したら、まず `linkly doctor` を実行し、該当する公式ガイドを確認してください。ここに記載のない方法を使う場合は、その理由を述べ、再度検証してください。

### まず、コマンドを実行できるかを確認する

このガイドは、あなたがシェルを使えること（Claude Code、Codex、Cursor、Gemini CLI など）を前提としています。ChatGPT や Web 版 Claude.ai のような、**シェルを持たないオンラインアプリケーション**の場合、以下の診断コマンドは実行できず、CLI もインストールできません。それでも変わらず当てはまるのは、**デスクトップアプリは必ずインストールする必要がある**という点です（ステップ 1 の内容を一通りユーザーに伝えてください）。接続方法（リモート MCP、Skills のアップロードなど）はアプリケーションごとに大きく異なるため、`https://linkly.ai/docs/llms.txt` を読み、あなたが動作しているアプリケーション向けの統合ガイド（例：「Using Linkly AI in ChatGPT」）を見つけて、そのページに従ってユーザーを案内してください。このページから一般化しないでください。

***

## ステップ 0：現在の状態を診断する

まず以下をまとめて実行し、その結果からどこから始めるかを判断します。

**macOS / Linux（bash / zsh）：**

```bash theme={null}
echo "--- 1. port file ---"
cat ~/.linkly/port 2>/dev/null || echo "NO_PORT_FILE"
echo ""
echo "--- 2. health ---"
PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port 2>/dev/null)
curl -sf --max-time 5 "http://127.0.0.1:${PORT:-60606}/health" || echo "UNREACHABLE"
echo ""
echo "--- 3. cli ---"
linkly --version 2>/dev/null || echo "NO_CLI"
echo "--- 4. status ---"
linkly status --json 2>/dev/null || echo "NO_STATUS"
echo "--- 5. skills ---"
ls ~/.claude/skills/linkly-ai/SKILL.md ~/.agents/skills/linkly-ai/SKILL.md 2>/dev/null || echo "NO_SKILLS"
```

**Windows（PowerShell）：**

```powershell theme={null}
Write-Output "--- 1. port file ---"
$port = 60606
if (Test-Path "$HOME\.linkly\port") {
  Get-Content "$HOME\.linkly\port"
  $port = (Get-Content "$HOME\.linkly\port" | ConvertFrom-Json).port
} else { Write-Output "NO_PORT_FILE" }
Write-Output "--- 2. health ---"
try { Invoke-RestMethod "http://127.0.0.1:$port/health" -TimeoutSec 5 | ConvertTo-Json -Compress } catch { "UNREACHABLE" }
Write-Output "--- 3. cli ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly --version } else { Write-Output "NO_CLI" }
Write-Output "--- 4. status ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly status --json } else { Write-Output "NO_STATUS" }
Write-Output "--- 5. skills ---"
if ((Test-Path "$HOME\.claude\skills\linkly-ai\SKILL.md") -or (Test-Path "$HOME\.agents\skills\linkly-ai\SKILL.md")) { Write-Output "SKILLS_OK" } else { Write-Output "NO_SKILLS" }
```

### 結果の読み方

`/health` は最も信頼できる診断手段です。サービスが動作していれば HTTP 200 と次のような JSON ボディを返します：

```json theme={null}
{
  "version": "0.8.1",
  "doc_count": 12009,
  "mcp_endpoint": "http://127.0.0.1:60606/mcp",
  "index_status": "watching",
  "capabilities": ["clips-v1"]
}
```

重要な点：

* **ポート 60606 をハードコードしないこと。** これはあくまでデフォルト値であり、そのポートが使用中の場合、アプリは番号を 1 つずつ繰り上げます。必ず `~/.linkly/port` から実際のポートを読み取ってください。中身は `{"port":60606}` のようなコンパクトな JSON です。
* **port file があるからといってサービスが動作しているとは限りません。** アプリが強制終了されたりクラッシュしたりすると、このファイルが残ります。正常性の判断は `/health` が 200 を返すかどうかだけで行ってください。
* **`mcp_endpoint` が `null` の場合は MCP トグルがオフになっています**（`/health` は 200 を返したままです）。ポートのデバッグを始めず、**設定 → MCP** でユーザーにオンにしてもらってください。
* **`index_status` の値**：`watching`（完了 — CLI では `Up to date` と表示）、`scanning`、`indexing`、`idle`、`error`。
* **`doc_count` はインデックス済みのドキュメント数**です。インデックス作成の進捗を測る目安として使い、ユーザーのファイルが取り込まれたことの確たる証拠とはしないでください。あくまで合計値であり、ファイルを 1〜2 個追加しただけでは 151 と 150 の区別はほとんどつきません。

### 状態対応表

**上から順に照合し、最初に一致した行に従ってください**（この表は単一の軸で状態を判定するため、各行は互いに排他的です）：

| 診断結果                                                  | 意味                         | 開始位置                                                                       |
| ----------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------- |
| port file なし、`/health` に到達できない                        | 未インストール、または一度も起動していない      | ステップ 1                                                                     |
| port file あり、`/health` に到達できない                        | インストール済みだが起動していない          | ユーザーに起動を依頼し、再診断                                                            |
| `/health` が 200、ただし `index_status` が `error`          | インデックス作成に失敗                | まず `linkly doctor` を実行（CLI がなければ **設定 → 情報 → ログ** をユーザーに開いてもらう）。回復するまで進まない |
| `/health` が 200、ただし `linkly status` が動作しない            | アプリは準備完了、CLI が未整備（または接続不可） | ステップ 2                                                                     |
| `/health` が 200、`linkly status` も正常だが、Skills が未インストール | チェーンは準備完了、Skills が未整備      | ステップ 3                                                                     |
| 上記すべてが準備完了で、Skills もインストール済み                          | ほぼセットアップ済み                 | ステップ 4 の検証                                                                 |

補足：どのステップから入る場合でも、`doc_count` がサンプルの水準（約 150）にとどまっているなら、最終報告の中で **設定 → フォルダ** から自分のフォルダを追加するようユーザーに提案してください。これは進行を妨げる要因ではありません。作業を続けてください。

***

## ステップ 1：インストールと初期化

このステップは完全に手動作業であり、あなたが代わりに実行することはできません。**以下の一連の手順をひとつのメッセージでユーザーにまとめて伝え、そこで止まって「完了しました」という 1 回の返信を待ってください。** 項目ごとに何往復もやり取りしないでください。

ユーザーに伝える内容は次のとおりです（言い回しは変えて構いませんが、5 つのパートをすべて含めてください）：

### 1. ダウンロードとインストール

**[https://linkly.ai/#download](https://linkly.ai/#download)** にアクセスし、お使いの OS に合ったビルドを入手します。

* **macOS**：`.dmg` をダブルクリックしてマウントし、**LinklyAI** アイコンを **Applications** にドラッグしてから、Launchpad で起動します。
* **Windows**：`.exe` をダブルクリックしてウィザードに従います（デフォルトではユーザーディレクトリにインストールされます）。その後スタートメニューから起動します。
* **Linux**：AppImage の場合は `chmod +x LinklyAI-*.AppImage && ./LinklyAI-*.AppImage`、deb の場合は `sudo dpkg -i linkly-ai-*.deb`。

### 2. 初回起動ウィザードを完了する

初回起動時にガイドウィンドウが開きます：**カバー画面 → サインイン → 準備中 → 使いはじめパネル**（右下のステップ表示は中間の 2 画面だけを数えるため、1/2、2/2 と表示されます）。

* **カバー画面**：インターフェースの言語とテーマを選びます。**先に進むには「以下を読み、同意します: プライバシーポリシー」にチェックを入れる必要があります。** 同じ画面に「Linkly AI の改善に協力する」というテレメトリのトグルがあり、デフォルトでオンですが、オフにできます。
* **サインイン**（1/2）：「サインイン / 新規登録」をクリックするとブラウザが開き、OAuth 認証が行われます。**このステップはスキップできます** — スキップの入口は画面下部の小さな文字で書かれた「サインインをスキップ」というリンクです。ユーザーに伝えてください：サインインは公式 AI モデルの試用枠とクラウドナレッジベース機能を手早く入手して、お試しを容易にするためだけのものです。**ローカルのインデックス作成、ローカル検索、MCP サービスはネットワーク接続をまったく必要としません。**
* **準備中**（2/2）：アプリが同梱のサンプルドキュメントを展開してインデックスを作成します。通常は数分で完了します。「始める」ボタンが有効になるまで待ってください。
* **使いはじめパネル**：6 枚の機能カードが表示されます。いずれかのカードをクリックして主要機能を試し、右上の × をクリックするとウィザードが終了します。

### 3. 自分のドキュメントフォルダを追加する（任意）

ウィザードが終わった時点では、インデックスされているのは同梱のサンプルドキュメントだけで、ユーザー自身のファイルは含まれていません。提案する価値はありますが、必須ではありません。Linkly AI を試すだけならサンプルで十分ですし、フォルダは後からいつでも追加できます。追加する場合は、どちらの方法でも構いません：

* **設定 → フォルダ** を開き、インデックス対象のディレクトリ（ドキュメント、ダウンロード、プロジェクトのディレクトリなど）を追加する。
* あるいは `~/LinklyAI` フォルダにファイルを置く — このフォルダはデフォルトで監視されているため、置いたものは自動的にインデックスされます。

権限が不足していると表示された場合（macOS でよくあります）、**システム設定 → プライバシーとセキュリティ → フルディスクアクセス** で Linkly AI を追加し、アプリを再起動してください。

ドキュメント、クラウドドライブ、NAS など、ローカルファイルが多く保存されているユーザー自身のフォルダをインデックスに追加するよう提案してください。

### 4. モデルがバックグラウンドでダウンロードされていることを把握する（操作は不要だが、ユーザーに伝える）

初回起動後、アプリはバックグラウンドで約 **710MB** のモデルファイルをダウンロードします（セマンティック検索用が約 639MB、OCR 用が約 70MB）。回線状況によっては数分から 1 時間以上かかることがあります。その間：

* **キーワード検索はすぐに使え**、まったく影響を受けません。
* **セマンティック検索はダウンロードとインデックス作成の完了を待ちます。** それまでは `search` は自動的にキーワードのみ（全文）検索にフォールバックします — 関連度はわずかに下がります。これは想定どおりの動作であり、不具合ではありません。

### 5. すべて終わったら 1 回だけ返信する

以上がすべて完了したら、感謝の口調でユーザーに一度だけ返信してください。残りはあなたが引き継ぎます。

***

**合格判定**：`/health` が 200 を返し、`doc_count` が 0 より大きいこと。ウィザードを終えたばかりで `doc_count` がまだ 0、かつ `index_status` が `scanning`/`indexing` の場合は、サンプルがまだ取り込み中です — **10 秒ごとに、最大 6 回まで再試行してください**。それでも 0 のままなら、トラブルシューティングの `error` のケースとして扱ってください。ユーザーが自分のフォルダを追加していれば `doc_count` はサンプルの水準を明らかに上回りますが、追加していなくても以降のステップを止める理由にはなりません。

***

## ステップ 2：ツール経路を接続する

経路は 2 つあり、**互いに排他的ではありません**。**まず CLI をインストールしてください**：インストールした瞬間から動作するため、現在のセッション内で呼び出してループを閉じられます。MCP は動作前にセッションの再起動が必要なため、その場では検証できません。これは「このセッション内で自己検証できるか」という観点での優先順位にすぎず、製品として CLI が MCP より優れているという意味ではありません。ユーザーが別の AI ツールでも Linkly AI を使いたい場合は、両方を設定して構いません。

**以下のどのコマンドでもポートをハードコードしないでください。** このステップの最初に、実際のポートを変数に取り込み、以降はそれを参照してください：

```bash theme={null}
PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port)
MCP_URL="http://127.0.0.1:$PORT/mcp"
```

PowerShell では、ステップ 0 の `$port` を再利用します：`$mcpUrl = "http://127.0.0.1:$port/mcp"`。

### 方法 A：CLI をインストールする（推奨）

まずユーザーにコマンドを提示し、ネットワークからインストールスクリプトをダウンロードして実行するものであることを説明したうえで、**同意を得てから実行してください**：

macOS / Linux：

```bash theme={null}
curl -sSL https://updater.linkly.ai/cli/install.sh | sh
```

または Homebrew 経由：

```bash theme={null}
brew tap LinklyAI/tap
brew install linkly
```

Windows（PowerShell）：

```powershell theme={null}
irm https://updater.linkly.ai/cli/install.ps1 | iex
```

全プラットフォーム共通（Rust ツールチェーンが必要）：

```bash theme={null}
cargo install linkly-ai-cli
```

インストールスクリプトは CLI をインストールし、PATH に追加します。実行後に `linkly` が見つからない場合は、ユーザーに**新しいターミナルウィンドウを開いてもらう**か（PATH の変更はすでに開いているウィンドウには適用されません）、フルパスを直接実行してもらってください：

* macOS / Linux：`~/.linkly/bin/linkly` にインストールされ、`.zshrc` / `.bashrc` / `.profile` に PATH が追加されます。
* Windows：`%LOCALAPPDATA%\linkly\bin\linkly.exe` にインストールされ、ユーザーレベルの PATH が変更されます。

**合格判定**：`linkly --version` がバージョンを表示し、`linkly status --json` が `app_version` と `doc_count` を含む JSON を返すこと。（人間向けの `linkly status` では、このフィールドは `Docs:` と表示され、桁区切りが付きます。プログラムによるチェックでは必ず `--json` を使ってください。）

### 方法 B：MCP を設定する

ユーザーの環境で CLI のインストールが難しい場合や、複数の AI ツールから Linkly AI を使いたい場合はこちらを使います。ステップ 2 の最初で設定した `$MCP_URL`（つまり `http://127.0.0.1:$PORT/mcp`）を使ってください — **60606 をハードコードしないでください**。

主なクライアント：

* **Claude Code**：`claude mcp add --transport http linkly-ai "$MCP_URL"`
* **Codex**：`codex mcp add linkly-ai --url "$MCP_URL"`
* **Cursor**：Settings → MCP Servers → Add Server を開き、Name は `linkly-ai`、Type は `StreamableHTTP`、URL は `$MCP_URL` を解決した値を指定します。

その他のクライアントについては [MCP で AI アシスタントと統合する](/docs/ja/use-mcp)をご覧ください。

**新しく設定した MCP サーバーは、通常は現在のセッションでは利用できるようになりません** — ほとんどのクライアントでは、設定の再読み込みか新しいセッションの開始が必要です。クライアント自身のガイドに従ってください。ユーザーにはっきり伝えてください：「設定は書き込みました。再読み込みするか新しいセッションを開始して、もう一度試してください」。**ツールが現れたかどうかを現在のセッションで何度も確認し続けないでください。**

**合格判定**：設定が正常に書き込まれたこと。何も再起動せずにサーバー自体の正常性を確認したい場合は、直接ハンドシェイクを送信します（`$MCP_URL` は解決した値に置き換えてください）：

```bash theme={null}
curl -sf --max-time 5 -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'
```

レスポンスに `"serverInfo":{"name":"linkly-ai"` が含まれていれば、MCP サービスは正常です。**403** が返る場合は MCP トグルがオフになっています — **設定 → MCP** でユーザーにオンにしてもらってください。

***

## ステップ 3：Skills をインストールする

Skills は Linkly AI のツールを上手に使う方法をあなたに教えます — まず検索し、次にアウトラインを見て、重要な箇所だけを読む — これにより検索品質が目に見えて向上します。**強くお勧めします。**

ここでも、コマンドを提示して同意を得てから実行してください：

```bash theme={null}
npx skills add LinklyAI/linkly-ai-skills
```

`npx` が使えない場合は、手動でクローンします：

```bash theme={null}
# Claude Code (user level)
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.claude/skills/linkly-ai

# Codex CLI
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.agents/skills/linkly-ai
```

GitHub にアクセスできないユーザーもいます — その場合は Linkly CDN から代替パッケージをダウンロードしてください：

```
https://updater.linkly.ai/skills/linkly-skills-latest.zip
```

特定のクライアントだけにインストールする方法（例：`-a claude-code` / `-a codex`）やその他の方法については [Skills の使い方](/docs/ja/use-skills)をご覧ください。対象ディレクトリがすでに存在する場合は、すでにインストール済みなのでスキップしてください（更新するには、そのディレクトリに `cd` して `git pull` します）。

**Skills も読み込みにセッションの再起動が必要です。** 合格判定はファイルが正しいディレクトリに配置されたことであり、現在のセッションですぐに呼び出せることではありません。作業後に再起動するようユーザーに伝えてください。

**合格判定**：次のいずれかのパスに `SKILL.md` ファイルが存在すること — `~/.claude/skills/linkly-ai/SKILL.md`（Claude Code ユーザーレベル）、`.claude/skills/linkly-ai/SKILL.md`（プロジェクトレベル）、`~/.agents/skills/linkly-ai/SKILL.md`（Codex）。`npx skills add` は検出したクライアントに基づいて自動的に 1 つを選ぶため、実行後はこれら 3 つのパスを確認するだけで十分です。

***

## ステップ 4：エンドツーエンドの検証

**CLI をインストールした場合（方法 A）**：実際の検索を 1 回実行して、チェーン全体が動作することを確認します。まず `doc_count` を確認してください — サンプルの水準（約 150）なら、サンプルライブラリの語（例：`Holmes`）で検索します。サンプルの水準を明らかに上回っている場合は、ユーザーが自分のフォルダを追加しているので、そのドキュメントに含まれていそうな語を使ってください：

```bash theme={null}
linkly search "Holmes" --json
```

**成功の条件**：実在のドキュメントのエントリが返ってくること（サンプルだけで実行している場合は、サンプルのドキュメントがヒットすれば成功とみなします）。

**MCP 経路だけを選んだ場合（方法 B）**：このステップは現在のセッション内では完了できません — ツールはクライアントが再読み込みするか新しいセッションを開始した後にしか現れませんが、これは読み込みの仕組みであって失敗ではありません。「設定は書き込み済み、サーバーのハンドシェイクは正常、再起動後のユーザー検証待ち」として締めくくり、以下の一文をユーザーに渡してから止まってください（これは進捗の誇張にはあたりません）：

> 再読み込みまたは新しいセッションの開始後、私に「linkly-ai で Holmes を検索して」と頼んでください — ドキュメントのエントリが返ってくれば、チェーン全体が動作しています。

CLI の検索が空で返ってきても、すぐにモデルのせいにしないでください — モデルが未準備のとき、`search` はキーワードのみに劣化するだけで、空を返すことはありません。次の順で確認してください：クエリは妥当か → `doc_count` が 0 か（サンプルがまだ取り込み中、ステップ 1 の合格判定を参照）→ ユーザーはフォルダを追加したか → 形式は対応しているか。`linkly status --json` で `index_status` を読み取ってください：`indexing` はまだインデックスを構築中かモデルをダウンロード中という意味なので、待つだけです。`error` の場合はトラブルシューティングを参照してください。

注意：スキャンの終了からコンテンツ抽出の開始までのわずかな間、`index_status` が先走って `watching`（つまり `Up to date`）と表示されます。**1 回のサンプリングだけで準備完了と判断しないでください** — 数秒後にもう一度確認するか、`doc_count` がまだ増えているかを見てください。

***

## トラブルシューティング

| 症状                                     | 原因と対処                                                                                                                                  |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `/health` が接続拒否                        | デスクトップアプリが起動していません。ユーザーに起動を依頼して再試行してください。                                                                                              |
| port file はあるが `/health` が失敗する         | 異常終了によって残った古いファイルです。ユーザーにアプリの再起動を依頼してください。                                                                                             |
| アプリは起動しているのにポートに到達できない                 | 60606 が使用中で、ポートが繰り上がっています。`~/.linkly/port` から実際のポートを読み取ってください。                                                                         |
| `/health` は正常だがハンドシェイクが **403** を返す    | MCP トグルがオフです。**設定 → MCP** でユーザーにオンにしてもらってください。                                                                                         |
| `index_status` が `error`               | インデックス作成に失敗しました。`linkly doctor` を実行してください（CLI がなければ **設定 → 情報 → ログ** をユーザーに開いてもらう）。回復するまで先に進まないでください。                                  |
| `linkly` コマンドが見つからない                   | 新しいターミナルを開いてもらってください。macOS/Linux は `~/.linkly/bin/linkly`、Windows は `%LOCALAPPDATA%\linkly\bin\linkly.exe` を使います。                      |
| PowerShell がスクリプトはブロックされていると表示する       | 実行ポリシーの制限です。同じウィンドウで（そのウィンドウ内のみ）`Set-ExecutionPolicy -Scope Process -Bypass` を実行してもらってから再試行するか、`cargo install linkly-ai-cli` を使ってください。 |
| 検索結果が空                                 | 最初にモデルのせいにしないでください（モデルが未準備のときは全文検索に劣化するだけで、空は返しません）。次の順で確認してください：クエリ、`doc_count` が 0 かどうか、ユーザーがフォルダを追加したか、形式が対応しているか。                  |
| `index_status` が `indexing` のまま止まって見える | 大量のドキュメントやモデルのダウンロード中では正常です。`doc_count` が増えているかを確認してください。                                                                              |
| macOS で権限エラーが出る                        | **システム設定 → プライバシーとセキュリティ → フルディスクアクセス** で Linkly AI を追加し、アプリを再起動します。                                                                   |
| MCP を設定したのにツールが現れない                    | 設定の再読み込みか新しいセッションが必要です。これはクライアント側の読み込み仕様であり、設定ミスではありません。                                                                               |
| より詳しい診断が必要                             | `linkly doctor` を実行してください。接続チェーンを順に検査し、対処法を提案します。                                                                                      |

***

## 完了したら報告する

最後に、以下を含む短いサマリーをユーザーに伝えてください：

* どのステップを、どの経路（CLI または MCP）で完了したか
* 反映のためにセッションの再起動が必要なものがあるか
* 現在のインデックスの状態とドキュメント数
* 実際の使い方 — 例えば任意のプロンプトの末尾に `use linkly-ai` を付ける、`CMD/Ctrl + Shift + L` で検索ランチャーを開く、など

完了できなかったステップがある場合は、率直に伝えてください：どこで詰まったか、何を試したか、ユーザーが次に何をできるか。

### 最後に 4 つの質問例を添える

レポートの最後に、ユーザーがそのままコピーして試せる質問を 4 つ提示してください。**できる限り、ユーザー自身の資料に合わせてカスタマイズしてください**：

まずユーザーが何をインデックスしたかを少し調べます——`explore` ツール（CLI では `linkly explore`）で全体像をつかみ、必要なら `search` でいくつかのテーマを確認します。そのうえで、ユーザーが実際に尋ねそうな質問を 4 つ書いてください。本人のドキュメントと関心事に根ざした具体的なものにし、「私のドキュメントを要約して」のような当たり障りのない内容は避けてください。良い質問は「これは確かに自分の資料の話だ」と一目で伝わります。

ユーザーがまだ自分のドキュメントを追加していない場合（`doc_count` がサンプルのみの水準）は、内蔵サンプルライブラリ向けの次の 4 つをそのまま使ってください：

1. A Life in 10 Years を読んで、Samuel Pepys の10年間の日記に繰り返し現れる人生のパターンと、彼自身は気づいていなかったかもしれない盲点を分析してください。
2. シャーロック・ホームズはなぜ勝てるのか？Detectives Library の12の事件簿を読んで、彼の推理の公式を抽出し、Holmes の手法を複雑なビジネス課題を診断するためのチェックリストに変換してください。
3. アメリカの建国者たちが本当に恐れていたものは何か？Federalist Papers 全体を読んで、答えを出してください。野心と派閥を互いに抑制させる制度をどう設計したのかを説明し、最後にそのロジックを今日の AI 企業やインターネットプラットフォームのガバナンス原則に翻訳してください。
4. 数百人の元奴隷たちが自ら語った回想を読んで、アメリカの歴史教科書が最も詳しく語ろうとしないことは何かを見つけてください。WPA Slave Narratives に基づいて答えてください。

***

## 関連ドキュメント

* [クイックスタート](/docs/ja/quickstart) — 人間向けに書かれた、インストールと導入の完全ガイド
* [CLI の使い方](/docs/ja/use-cli) — CLI のすべてのサブコマンドとパラメータ
* [MCP の使い方](/docs/ja/use-mcp) — 3 つのアクセス方式とクライアント別の設定方法
* [Skills の使い方](/docs/ja/use-skills) — Skills のインストール方法と動作の仕組み