MD-Memo 活用ガイド

• フォルダを開くと「ワークスペース読込完了: N 件のメモ」と表示されます。
• 探索するのは .md・.markdown・.txt だけで、深さは3階層までです。
• . で始まるフォルダ、node_modules、vendor、appdata、$recycle.bin、system volume information、windows は飛ばします。
• 300ノート、1500ファイル、2.5秒のどれかに達すると探索を打ち切ります。とても大きなフォルダでは、後ろのノートが対象に入らないことがあります（通知はありません）。
• 各ノートは、最初の見出し（なければファイル名）をタイトル、最初の1行をスニペットとして持ちます。
• 入力が止まって1.2秒後に、カーソルのある行と、カーソル前の250文字から、キーワード（2文字以上、最大8個）を取り出します。
• ほかの全ノートに点数を付け、上位2件をピルにします。

• zip で入れる: Releases ページ から zip をダウンロードして、任意のフォルダに展開します。
• ユニバーサルバイナリ: 次回リリースからmacOSビルドはユニバーサルバイナリになり、Apple SiliconとIntel Macの両方に対応します。
• Macがなくても試せます: このリポジトリへのプッシュのたびに、GitHub上のmacOSランナーが MD-Memo.app をビルドします。Actions タブを開く（または CI ワークフローを Run workflow で手動実行する）→ 最新の CI 実行を開く → Artifactsから md-memo-macos-<commit-sha> をダウンロードします。これもアドホック署名なので、上記と同じ初回起動の操作が必要です。
• アップデートの確認: 起動してしばらくすると、GitHub に新しいリリースがないかを確認します（api.github.com への1回のリクエストのみで、ノートの内容は送信されません）。新しいバージョンがあると、ヘルプ（?）ボタンに小さなバッジが表示されます。

• 対象の決まり方: 選択範囲があればそれ、なければカーソルのある行、行が空ならメモ全体の順です。ノートが空のときは「対象テキストなし（自由な質問）」と表示され、入力した指示だけがAIに送られます。
• 答えの入る場所: 対象の最後の行の下に、空行を1つずつはさんで入ります。空行にカーソルがあるときは、その空行に入ります。選択範囲や行そのものは書き換わりません。
• LLM が未設定のとき: 質問バーは開きません。「LLMが未設定です（設定 → AIモデル）」と出て、ノートは変わりません。モデルか接続先が空のとき、または Gemini・OpenAI などのクラウドサービスで API キーが空のときです（Ollama などのローカルは、キーなしで使えます）。
• 待っている間: ノートに [AI 生成中: 指示の先頭20文字...] という行が入り、答えが届くと、その行が答えに置き換わります。
• 失敗したとき: 答えの代わりに、[LLMエラー: 原因] という1行が入ります。原因は、改行を除いて300文字までに縮められます。
• 取り消し: 依頼は、タスクパネル（Alt + T）にエージェント名「LLM」で並びます。ここで取り消すと、待機中の行が消えてノートは元の状態に戻り、「LLMへの依頼を中断しました」と表示されます。AIへの通信そのものは止められないので、あとから届いた答えは捨てられます。
• 使うモデル: 設定 → AIモデル の、テキストLLMです。
• 日本語入力（IME）: 変換を確定する Enter では、送信されません。確定したあとにもう一度 Enter を押すと実行します。
• 回答のフェンスの扱い: モデルが回答全体を1つの ```markdown / ```md フェンスで囲んで返してきた場合、MD-Memoは挿入前にそのフェンスを自動で外します。コードブロックで囲むのではなく、Markdownそのものが挿入されるようにするためです。実際のコード回答（```python など）や、他の文章の中にフェンスコードブロックを含むだけの回答は、そのまま挿入されます。
• 以前のキー: 以前のバージョンで、この機能を Ctrl + K で使っていた場合は、設定を読み込むときに Ctrl + L へ自動で移り、お知らせが1回だけ出ます（別画面だったプロンプト入力は、この質問バーに統合されました）。

• 提案を出すのは、ローカルLLM（Ollama / Gemma 4）またはクラウドAPIです。設定は 設定 → AIモデル の「入力予測」にあります。
• 表示までの待機時間の既定は500msです。設定画面では200〜2000msですが、実際の下限は300msです。
• ステータスバーの「予測」バッジをクリックすると、ON / OFF を切り替えられます。

• 設定 → AIモデル → 画像解析 で、Geminiなどの画像モデルとAPIキーを設定します。
• 「画像ペースト(Ctrl+V)時に自動で画像マークダウン化 (Vision OCR) を実行」のスイッチが必要です（既定でオン）。
• クリップボードに画像しかないときだけ働きます。テキストと画像の両方があるときは、テキストが貼り付けられます。
• ローカルのビジョンモデル（OllamaやLM Studio）なら、APIキーなしでもOCRできます。
• OCRを使わず画像のまま貼りたいときは、そのまま貼る（Ctrl + Shift + V）で assets に保存します。スイッチがオフのとき、または画像モデルのAPIキーが未設定のときは、Ctrl + V でも、同じように assets に保存してリンクを貼ります（理由がトーストに出ます）。

変換されるもの（内蔵コンバータ。外部依存なし）

• 見出し（h1〜h6）、段落、改行、水平線
• 太字・斜体・取り消し線、インラインコード、言語付きのフェンスコードブロック
• 入れ子の引用、start を保持した入れ子のリスト、タスクリストのチェックボックス
• タイトル付きリンク、画像
• 列揃えを保ったGFMテーブル（セル内の | はエスケープ）
• Google Docs特有のラッパー構造にも対応します

安全のため取り除かれるもの: <script>・<style>・<iframe>・<svg> の中身、javascript: と data: のリンク、data: 画像。

画像の保存名: 拡張子は実際の画像形式に合わせて .png / .jpg / .gif / .webp になり、名前が重複すると -2、-3… が付きます。

./assets/ の保存先: メモが保存済みならそのメモの隣、そうでなければ現在のワークスペースフォルダ、ワークスペースも無ければアプリのデータフォルダです。最後のケースでは、挿入されるリンクは相対リンクではなく、絶対パスの file:/// リンクになります。

変換の対象: 表・見出し・リスト・リンク・画像・引用・区切り線・太字や斜体などが含まれるHTMLだけを変換します。段落と改行だけのHTML、VS Code のエディタからのコピー、1セルだけのExcelのコピーは、変換せずにそのまま貼ります。

役割を元に戻す: 設定 → 一般 の「Ctrl+V で Web・Word・Excel の内容を Markdown にして貼る」をオフにすると、以前の割り当てになります。Ctrl + V がプレーンテキスト、Ctrl + Shift + V がHTMLの変換です（このとき、貼り付けイベントにHTMLが含まれないアプリでは、非同期クリップボードAPIにフォールバックします。組み込みブラウザが、初回のみ独自の許可プロンプトを表示することがあります）。

トースト: 「Markdown に変換して貼り付けました」（変換成功時）、または「画像を assets に保存しました」（画像のみのクリップボードを ./assets/ に保存したとき）。

Ctrl + Shift + V は固定のキーで、設定 → ショートカット では変更できません。以前はプレビューを横に開くコマンドでしたが、そちらは Ctrl + Alt + V（macOS: Cmd + Option + V）に変わりました。

状況に応じたメッセージが、ステータスバーに6〜9秒ほど表示されます。

• モデル: 既定は gemini-3.5-transcribe です（以前は gemini-2.5-flash）。Geminiモデル限定で、オフラインやGemini以外のモデルは選べません。
• 呼び出し方: Google の Gemini 3.5 Transcribe を Interactions API（POST {base}/v1beta/interactions、ヘッダー x-goog-api-key）で呼びます。gemini-2.5-flash などの古いモデルは、プロンプト付きの generateContent 形式で動きます。
• ライブ版は使えません: gemini-3.5-transcribe-live はストリーミング（Live API）版で、録音した音声には使えません（指定すると、その旨のエラーが出ます）。
• プライバシー: MD-Memoは常に store: false を送ります。Google側に録音や文字起こしは保存されません。
• キー: APIキーとBase URLが空なら、画像OCR（ビジョン）の設定を使います。設定ファイルには voice.apiKey / voice.baseUrl というキーもありますが、設定画面に入力欄はありません。
• 日本語IME: IMEをオンにしたままでも、ショートカットは使えます。
• マイクの許可: 許可の確認を出すのはOSではなく組み込みブラウザ（WebView2）自身で、初回録音時に一度だけです。
• macOS: マイク使用の説明文は組み込み済みですが、macOSでの動作はまだ十分に検証されていません。

• 結果の扱い: 設定 → 連携 の「コマンド（実行する）」にある「コマンドの出力の入れ方」と「実行結果を新しいタブで開く」で決まります。選んだテキストがあるとき、出力は既定で、その最後の行の下に入り、選んだテキストは残ります。「選択範囲を置き換える」にすると、従来のフィルタのように、選んだテキストが出力に置き換わります。「実行結果を新しいタブで開く」がオン（既定）のときは、結果を新しいタブでも開きます。オフでは新しいタブを開かず、選択がなければ出力をノートの末尾に加えます（「置き換える」なら、ノート全体が出力に置き換わります）。
• 出力が空のとき: コマンドが成功しても何も出力しなかった場合、結果のタブに「(no output)」と表示されます。
• 作業ディレクトリ: コマンドは、MD-Memoアプリ自身の作業ディレクトリで実行されます。
• プリセット（入力欄の候補）: 履歴が先頭に並び、続けて、agents.yaml の snippets: に書いた自作の command のひな形、固定のフィルタ（sort、sort -u、jq .、tr、wc -l、duckdb -box など）、組み込みの command のひな形の順です。ひな形は、そのまま実行できるもの（${selection} や $0 などのプレースホルダを含まないもの）だけが並びます。組み込みは git status、git diff --stat、現在の日時、ファイル一覧などで、実行中の OS に合う版だけです。詳しくは 自動セレクター の「ひな形」をご覧ください。

• 書き方の決まり: [[ ... ]] は、中身が @llm か $ で始まるときだけ記法として扱います。ウィキリンク（[[Wiki Link]]）には触れません。1つの記法は1行に収めます。- [[ @llm ... ]] や > {{ @claude ... }} のように、リストや引用の記号の後ろにも書けます。
• @名前の探し方: {{ @名前 ... }} の名前は、まずエージェント（キー、別名の順）として探し、どれでもなければ、従来どおりスキル指定として扱います。既定の別名は、claude-code に claude・cc、agy に antigravity・gemini です。hermes と codex には、既定の別名がありません。
• エージェント指名の前提指示: {{ }} プロファイルの「コードブロックだけ返す」という前提の指示は、付きません（調査などが壊れるためです）。指示が空で、そのエージェントが指示を引数に取る（args に {instruction} がある）ときは、CLI を起動せず、結果に「指示が空です。{{ @名前 指示 }} の形で書いてください」と入ります。

結果ブロックの形

[[ @llm 英語に翻訳して ]]
<!-- md-memo:res a1b2 -->
結果の本文
<!-- /md-memo:res -->

• 実行中: 指示行の直下に、1行の目印 <!-- md-memo:run a1b2 --> が入ります。終わると、結果ブロックに置き換わります。a1b2 の部分は、英数字の短い id です。
• 指示行と結果: 指示行そのものは、実行しても書き換わりません。結果は、前後の空白を落として入ります。ブロックの中に、空行は足されません。
• コマンドの結果: 出力に含まれるバッククォートの連続より長いフェンスで囲んだ、コードブロックです。失敗したときは、出力・標準エラー・exit code N の行が、同じブロックに入ります。
• LLM・エージェントの失敗: LLM は [LLMエラー: メッセージ]、エージェントは [エージェント名 エラー: メッセージ] の1行が入ります。メッセージは1行にまとめられます。
• コメント行: 結果ブロックの前後のコメント行は、ノートの中の普通の文字です。エディタには見えますが、MD-Memo のプレビューでは隠れます。消しても、ほかには影響しません（実行中に消したときは、答えがノートの末尾に追加されます）。
• 再実行: 実行済みの指示行で Ctrl + Enter を押すと、下の結果ブロックを置き換えます（クラッシュなどで残った目印も同じです）。積み重なりません。実行中に押すと、「このスロットはすでに実行中です」と出ます。
• 中止: タスクパネル（Alt + T）の「中断」で、実行中の目印が消えます（指示行は残ります）。LLM は提供元に中止を伝えられないので、目印を消し、遅れて届いた答えを捨てる動きです。コマンドとエージェントは、実行を止めます。再実行の途中で中止すると、置き換えた古い結果は戻りません。
• 文脈（ctx=above）: 質問バーで記録した指示の目印には、ctx=above n=行数 が付きます（例: <!-- md-memo:res a1b2 ctx=above n=1 -->）。再実行では、指示行の真上にある、空白でない行（最大 n 行）を、対象のテキストとして再び送ります。間に別の指示行や結果ブロックがあれば、飛び越えます（最大80行・8000文字）。手書きの指示、ひな形から作った指示、行の書き換えで作った指示には付かず、書いた文言だけが送られます。周りの文章を、暗黙に送ることはありません。
• 結果ブロックの中: カーソルが結果ブロックの中にあるときは、「これは実行結果のブロックです。指示はブロックの外に書いてください。」と出て、何も起きません。結果に {{ }} が含まれていても、実行されません。

Ctrl + Enter を押したときの判断の順番（ネットワークを使わず、押した瞬間に決まります）

1. 日本語入力の変換を確定する Enter のときは、何もしません。押しっぱなしでも、繰り返しては実行しません。
2. カーソルが結果ブロックの中なら、「これは実行結果のブロックです。指示はブロックの外に書いてください。」と出して、何もしません。
3. カーソルの位置に、新しい記法のタスクがあれば、そのタスクだけを実行します。選択があるときは、選択の先頭にあるタスク、なければ選択した行の最初のタスクです。複数行を一度に走らせることはありません。
4. カーソルが従来の {{ }} 系のスロットの中なら、従来どおり実行します（結果で置き換わります）。
5. 自動判定がオフ、または行が空白なら、従来の動きです。カーソルより後ろの次のスロット、なければノートの最初のスロットを実行し、どれもなければ「実行できるスロットが見つかりません」と出ます。コードブロックの中では、何も起きません。
6. 対象は、選択範囲、なければ現在の行です。選択が行の一部だけのとき、選択が複数行のとき、行が指示に見えないとき、迷うときは、質問バーを開きます。行のテキスト全体を選んだときは、選択なしと同じ、その行の判定になります。
7. 行全体が指示に見えるときは、次の表のとおりに動きます。

設定 → 連携 の「自動判定したエージェント／コマンドは実行前に確認する」（既定はオン）をオフにすると、エージェントとコマンドも、書き換えと同時に実行します。

質問バーからの記録: 質問バーで指示を入力して Enter を押すと、対象の下の新しい行に [[ @llm 入力した指示 ]] が書かれて、すぐ実行されます。対象のテキスト自体は変わりません。LLM には、指示と対象のテキストの両方が渡されます。LLM が未設定のときは、バーを開かずにメッセージを出し、ノートは変わりません。

「指示に見える」ものの目安

• 指示と見なす: 依頼の言い回し（「〜して」「〜してください」「〜教えて」、翻訳・要約・校正 など）、疑問語のある質問、英語の命令形（translate、summarize など）。
• 指示と見なさない: 見出し、表の行、URL、コードらしい行、ふつうの文、4行以上、約240文字より長い文。質問バーが開きます。
• 行き先: 翻訳・要約・校正・言い換え・箇条書き・表・アイデアなどは LLM です。実装・リファクタリング・テストの実行・ビルド・コミットや PR などの Git 操作・調査・エラーログ、コードやバグの言葉が重なる修正などは、エージェントです（「テストを実行して」「npm test を実行して」もエージェントです）。git status、ls -la、cat a.txt | sort のように、既知のコマンド名で始まり引数が付く行は、コマンドです。どれでもなければ LLM です（文字の答えだけで済む、安全側の選び方です）。
• 行頭の指定が優先: 行頭に @llm、@エージェント名（別名も可）、$ があれば、それに従います。
• コマンドの自動判定: 書き込みや削除をするコマンド（rm、> での保存など）は、自動ではコマンドと判定されません。実行したいときは、[[ $ ... ]] と自分で書きます。
• 外れる例: 「資料は事前に共有してください」のような丁寧な依頼文も、LLM への指示と判定されます。

設定や環境が足りないとき

できないこと

• 判定は決まりごとで、外れることがあります。迷うときは質問バーが開き、ノートは勝手に変わりません。
• 1つのタスクは1行に収めます。1回の Ctrl + Enter で走るのは、1つのタスクだけです。
• コマンドに標準入力はありません（選択範囲をコマンドに流したいときは、コマンドバー Ctrl + E を使います）。
• LLM への通信そのものは止められません（中止は、答えを捨てる動きです）。

入口は3つ

• {{ のクイックセレクター: {{ を打つと出る候補に、従来のプロファイルとレシピのあと、ひな形が並びます（種類のタグ LLM / AGENT / CMD / TEXT、名前、本文の1行プレビュー）。数字キーの 1〜9 は、先頭の9行に付きます。プロファイルが先に並ぶので、これまでの手の動きは変わりません。Enter・Tab・数字で挿入、Esc で閉じます。打った {{ は、ひな形に置き換わります。
• コマンドパレット: 「タスクのひな形を挿入」で、ひな形だけの一覧が、カーソルの位置に開きます（上の図）。
• 短縮語 + Tab: 行頭か空白の後ろで、;sum のような短縮語を打って Tab を押すと、ひな形に展開します。短縮語が完全に一致するときだけです。それ以外の Tab は、これまでどおりです。

[[ を打っても、何も出ません（ウィキリンクの入力を邪魔しないためです）。command のひな形のうちプレースホルダを含まないものは、コマンドバー Ctrl + E の候補にも出ます。

組み込みのひな形（OS ごとに版があるものは、実行中の OS の版だけが出ます。コマンドは、Windows は PowerShell 版、macOS・Linux は sh 版です）

展開するときのプレースホルダ

• ${selection}: 選択範囲。コマンドパレットから挿入するときに入ります（{{ や短縮語から挿入するときは空です）。
• ${line}: 現在の行（打った語や選択範囲を除いた残り）。
• ${date}: 今日の日付（YYYY-MM-DD の形）。
• ${agent}: 既定のエージェント。
• $0: 展開したあとの、カーソルの位置。
• 文字どおりの $0 や ${ は、$$0、$${ と書きます。
• 安全: 展開される値は1行にまとめられ、[[ ]] や {{ }} を壊しません。コマンドでは、引用符・$・;・| などが取り除かれます。${selection} と ${line} は、タスクでは2000文字、コマンドでは300文字までです。

自作のひな形と別名（agents.yaml）

• snippets: 項目は id、label、kind（llm / agent / command / text）、trigger（任意）、body、os（win / unix / any。command 用）、agent（kind が agent のときの指名先。省略時は既定のエージェント）です。組み込みと同じ id を書くと差し替え、新しい id は追加になります。
• trigger: 空白を含まない2〜30文字です。大文字と小文字、全角と半角を区別せず、完全に一致したときだけ展開します。組み込みは ; で始まり、下の例は /weekly です。どちらの書き方も使えます。
• aliases: エージェントごとに、{{ @cc 指示 }} のような短い名前（別名）を付けられます。名前は、agents のキーか aliases のどれかで、大文字と小文字は区別しません。キーは、別のエージェントの別名より優先されます。書かなくても、claude-code と agy には、既定の別名が付きます。
• 反映: {{ の一覧、コマンドパレットの一覧、短縮語の展開は、MD-Memo を再起動したあとに新しい内容になります。{{ @別名 ... }} の実行と、コマンドバーの候補は、再起動しなくても新しい内容を使います（実行のときと、バーを開くたびに、agents.yaml を読みます）。設定 → 連携 の「agents.yaml を開く」で開くファイルがなければ、コメントアウトした例と説明が入った雛形が生成されます。

snippets:
  - id: "weekly"
    label: "今週の振り返り"
    kind: "llm"
    trigger: "/weekly"
    body: "この内容を今週の振り返りとして3点に要約して: ${selection}"

agents:
  claude-code:
    command: "claude"
    args: ["--file", "{file}", "--prompt", "{instruction}"]
    aliases: ["claude", "cc"]

• 実行するスロットの決まり方: カーソルが {{ }} などのブロックの中にあれば、Ctrl + Enter はそのスロットを実行します。ブロックの外では、自動セレクターが行の内容を見て動きます。カーソルより後ろにある次のスロットを実行し、それもなければノートの最初のスロットを実行する、という従来の動きになるのは、自動判定がオフのときと、行が空白のときだけです。コードブロックの中では、何も起きません。
• 見つからないとき: 従来の動きになる場面で、ノートにスロットがひとつもないと、ステータスバーに「実行できるスロットが見つかりません（カーソルを {{ }} などのブロック内に置いてください）」と数秒間表示されます。ノートの内容は変わりません。
• 実行中のとき: そのスロットがすでに実行中なら、「このスロットはすでに実行中です」と表示されます。
• 実行ボタン: 再生の三角のアイコンが付いた小さなボタンです。カーソルが、まだ実行していない完結したブロックの中にあると、そのブロックの横に現れます（ホバー時の表示: 「このスロットを実行 (Ctrl+Enter)」。macOS では Cmd+Enter）。押すと、Ctrl + Enter と同じ動きをします。[[ @llm ]]・[[ $ ]]・{{ @エージェント名 }} のタスクでは、指示行の右に出ます（実行中は出ません）。
• クイックセレクター: そのまま文章を打ち続けても、自動的に消えます。
• 日本語入力のとき: ｛｛ や 【？ と打ってしまっても、自動的に半角の記号へ直されます。
• 誤実行しません: コードブロック・インラインコード・Markdownリンク・URLの中に書かれた記号はスロットとして扱われないため、コード例の中に {{ }} が出てきても実行されません。

コマンドが見つからないと、スロットは次のようなエラー表示に置き換わります。原因を直したあと、同じスロットにカーソルを置いて Ctrl + Enter を押せば再実行できます。

{{ ⚠ エラー: エージェント起動失敗: ... (再試行: Ctrl+Enter) }}

• 作業ディレクトリ: ノートのある場所から上へたどって見つかったプロジェクトルートです。.md-memo/、agents.yaml（agents.yml / agents.json でも可）、AGENTS.md、skills/、.git/ のいずれかがあるフォルダで、どれも見つからなければノートのあるフォルダです。
• .env: プロジェクトルートに .env があれば、その内容が環境変数としてエージェントへ渡されます（読み込まれるのはこのファイルだけです）。

version: 2
default_agent: claude-code
timeout_seconds: 180
hover_peek_enabled: true
ghost_diff_duration_ms: 4000

# 1. 呼び出すCLIの定義。{instruction} は指示文、{file} はノートの絶対パスに置き換わります。
agents:
  claude-code:
    command: "claude"
    args: ["--file", "{file}", "--prompt", "{instruction}"]
    description: "Claude Code"
  my-agent:
    command: "my-cli"
    args: ["--prompt", "{instruction}"]
    description: "社内用エージェント"

# 2. 記法とエージェントの対応。ここに書いた分だけが有効になります。
slot_profiles:
  - trigger_open: "{{"
    trigger_close: "}}"
    name: "code"
    agent: "claude-code"
    system_instruction: "前置きを省き、そのまま動くコードブロックのみを出力してください。"

  - trigger_open: "<<"
    trigger_close: ">>"
    name: "review"
    agent: "my-agent"
    system_instruction: "変更点をレビューし、指摘を箇条書きで返してください。"

# 3. 複数ステップをまとめて実行するレシピ。
recipes:
  - trigger_open: "[>>"
    trigger_close: "]"
    name: "deep-research-and-code"
    description: "調査 → リスク反証 → 実装"
    steps:
      - "最新の公式仕様とベストプラクティスを調査する"
      - "移行リスクと破壊的変更を指摘する"
      - "上記を踏まえて実装コードを生成する"
    requires_approval_step: 2
    self_refine: true

• プレースホルダ: {instruction} はスロットに書いた指示、{file} は現在のノートの絶対パスに置き換わります。{instruction} をどこにも書かなかった場合は、最後の引数として自動的に追加されます。
• 記号の選び方: trigger_open / trigger_close には、Markdownの通常の記法（#、*、- など）とぶつからない組み合わせを選んでください。
• 上書きの挙動: slot_profiles や recipes を書くと、既定の記法は置き換わります。既定の4種類も残したい場合は、必要なものを書き写してください。一方 agents は、書かなかった既定のエージェント定義がそのまま残ります。
• aliases: エージェントに aliases: ["claude", "cc"] のように書くと、{{ @cc 指示 }} と短い名前で呼べます。書かなくても、claude-code と agy には既定の別名が付きます。
• snippets: 末尾に snippets: を書くと、自作のひな形が、{{ のクイックセレクターやコマンドパレットの「タスクのひな形を挿入」に並びます。書き方は 自動セレクター の「ひな形」をご覧ください。
• self_refine: true にすると、レシピの最初のステップで「下書き → 自己批判 → 修正」を最大2回繰り返してから次へ進みます。
• ファイルは UTF-8（BOMなし）で保存してください。

• ヒント行: パネルが開いている間は、「Ctrl+1..3 即実行 / Ctrl+Tab 移動 → Enter 決定 / Esc 閉じる」が表示されます。
• Enter だけを押したとき: Ctrl + Tab で選択を動かさないまま Enter を押すと、ただの改行になります（候補は実行されず、パネルは閉じます）。
• 書くことの邪魔になりません: 数字キーだけ・Tab だけ・Ctrl + Enter（自動セレクターとスロットの実行に使われます）は、パネルに横取りされません。
• 自動提示: Ctrl + J で呼び出すほか、入力が一定時間止まったときに自動で提示できます（既定で有効）。気になる場合は、設定 → 連携 の「提案（アクション候補）」で「手動呼び出しのみ」を選びます。待機時間の長さもそこで調整できます。
• キーの変更: ショートカットキー自体は、設定 → ショートカット から自由に変更できます。
• ステータスバーのバッジ: 「アクション」バッジが現在のモードを表し、クリックするたびに ON → 手動 → OFF → ON と切り替わります。表示は「アクション: ON」「アクション: Ctrl+J」（設定したキー。macOS では Cmd+J）「アクション: OFF」のいずれかです。設定 → 連携 → 提案（アクション候補）の2つのチェックボックスと連動しており、OFF の間は Ctrl + J を押しても何も起こりません。
• 出力のないコマンド: 「実行」カード（sh カード）のコマンドが成功して何も出力しなかったときは、> (出力なし) が挿入されます。実行されたことが分かるようにするためで、これはアクション候補だけの動作です（コマンドバーは、結果のタブに「(no output)」と表示します）。この挿入文字列は、英語版・日本語版どちらのビルドでも日本語のままです。
• 作業ディレクトリ: 「実行」カードのコマンドは、MD-Memoアプリ自身の作業ディレクトリで実行されます。たとえば git status -s は、MD-Memoを起動したフォルダの状態を返します。

• 既定では、内蔵のローカル規則だけで候補を出します。ノートの内容は外部に送信されません。
• 送信されるのは、下のどれかを設定した場合だけです。
• OpenRouter 経由の Jev: Base URL とモデル名を既定のまま（https://openrouter.ai/api/v1、jev-latest）にして、OpenRouter の API キー（sk-or-v1-…）を入力します。送信先は https://openrouter.ai/api/v1/systemone に固定です。
• TypeSafe の Jev: Base URL を https://api.typesafe.ai にして、TypeSafe の API キーを入力します。送信先は https://api.typesafe.ai/v1/systemone です。
• OpenRouter のチャットモデル: モデル名を Jev 以外（例: google/gemini-…）にして OpenRouter のキーを入力します。候補の文面をそのモデルに書かせます（送信先は OpenRouter の chat/completions）。
• 自前のサーバー: Base URL を上のどれでもない URL にすると、<Base URL>/predict へ送られます。
• キー欄は1つなので、キーの種類は Base URL とキーの形（OpenRouter のキーは sk-or- で始まります）で判断します。TypeSafe のキーを OpenRouter 用の Base URL のまま入れても、どこにも送られず、内蔵の候補になります。
• Jev は文章を書きません。内蔵の候補をすべて並べて「いまのメモに最も合うのはどれか」を1回だけ尋ね、その答えで並べ替えます。出るのは内蔵の候補だけです。
• Jev が答えられなかったとき（キーの誤り、残高不足、通信エラー、5秒の待ち時間切れ、確信が低いとき）は、内蔵ルールの候補に戻ります。そのキーを別のサービスへ送り直すことはありません。
• 送られるのはキャレット周辺の抜粋で、キャレットの前が最大1,500文字、後ろが最大500文字（合計約2,000文字）です。メモが空のときは送りません。
• Base URL とモデル名の欄には https://openrouter.ai/api/v1 と jev-latest があらかじめ入力されていますが、API キーが空のままなら外部には送られません。
• 安全性チェックの正体は AST ガードレールです。内部名称の意味は 用語集 にまとめています。

• コピーして取り込みます: 組み込みブラウザではドロップされたファイルの元のパスを取得できません。そのためMD-Memoは、ファイル（1件あたり最大25MB）をメモの隣の ./assets/ にコピーし、相対パスでリンクします。元のファイルの場所は記録されません。
• リンクの書式: リンク中のスペースと括弧はパーセントエンコード（%20、%28、%29）され、Markdownとして正しく保たれます。Ctrl + クリックで開く動作には影響しません。
• 開けるリンク: file:// リンク、絶対パス、メモからの相対パスに対応します。http(s): と mailto: は通常通り処理され、それ以外のスキームは拒否されます。
• サムネイル: 表示位置はおおよそのものです。

• モデル・アスペクト比・解像度は、設定 → AIモデル の「画像生成」で選びます。
• Gemini APIキーの欄が空のときは、Visionのキー、次にテキストのキーの順に引き継がれます。
• 画像は assets/diagram_<数字>.png に保存され、![Generated Diagram](assets/diagram_...png) が挿入されます。先にノートを保存しておくと、相対リンクになります。

CPUの全コア（runtime.NumCPU()）を駆使した、マルチスレッド並列Grepで検索しています。

保存されるときにノートへ入る行は、状況によって次の4通りです。この行は、UIの言語にかかわらず日本語です。

• 保存先: ./assets/YYYY-MM-DD-HHmmss.<拡張子> です。メモの隣、なければワークスペースフォルダ、それもなければアプリのデータフォルダ（この場合は file:// リンク）に保存されます。名前が重複すると -2、-3 が付きます。
• 保存にも失敗したとき: assets への保存まで失敗した場合だけ、その項目の見出しに続けて [Mobile Drop: <ファイル名> の処理に失敗しました: <エラー>] が追記されます。残りの項目は問題なく届きます。

• 写真・ファイルは最大10件、合計60MBまでです。
• 1件あたりの上限は、画像20MB、音声25MB、テキストファイル2MBです。それ以外のバイナリは受け付けません。

• ページの並び: 上から順に、「PCからのテキスト」カード、「PCへ送信トレイ」（追加した項目ごとに名前・サイズ・削除用の✕が表示されます）、カメラ／ファイル選択（複数可）／ボイス録音、テキスト入力欄です。送信ボタンは1つだけです。
• 「PCからのテキスト」: PCで選択中のテキスト（ダイアログを開いた時点で選択がなければ、クリップボードのテキスト）が、ワンタップコピー付きで表示されます。2秒ごとに更新され、最大64KBまで表示します。
• PC側の表示: ダイアログには「スマホに共有中: ...」として、80文字に切り詰めて表示されます。

• cloudflared が必要です。MD-Memoが自動でダウンロード・インストールすることはありません。
• 未導入の場合は、ダイアログにインストールコマンド（Windows: winget install --id Cloudflare.cloudflared -e、macOS: brew install cloudflared）と「コピー」ボタンが表示されます。実行してから、もう一度ボタンを押してください。
• トンネルを使っている間、送信内容は Cloudflare のサーバーを経由します。
• 90秒について: トンネルの90秒は、操作がない状態が続いたときのタイムアウトです。スマホでの操作があるたびに延び直します。「発行から90秒だけ有効」という固定の期限ではありません。

• ダイアログを開いている間だけ動きます。開くとPC内で小さなサーバーが起動し、1回送信されたとき、60秒間操作がなかったとき、ダイアログを閉じる／キャンセルしたときに停止します。スマホでページを開くことや、スマホ側での作業（ファイル追加・録音・入力）はすべて操作に数えられ、このタイマーをリセットします。そのため、大きめのバッチを組んでいても、60秒のアイドルタイムアウトにはかかりません。
• 1つのQRコードで送れるのは1回だけです。続けて送るときは、ダイアログを開き直してください。使い捨てトークンはリクエスト本体を読み込む前にチェックされます。
• コードを持つ人だけが送れます。アドレスにはランダムな使い捨てトークンが含まれ、トークンのないアクセスは、中身を読み込む前に拒否されます。
• 写真とクラウドモデル。ビジョンモデルがGeminiなどのクラウドサービスの場合、写真はそのプロバイダーへ送られます（Ctrl + V で画像を貼り付けたときと同じです）。APIキーが未設定でも写真は失われず、画像として保存されます（上の「未設定、または失敗したとき」）。
• 位置情報は任意で、トンネル使用時のみです。Cloudflareトンネル経由（HTTPS）で接続しているときだけ、スマホは位置情報を1回だけ、1度限りの試行として添付できます。付与されるのは最初の項目の見出しだけで、## Mobile Drop [14:20:05] — <ファイル名> (34.693, 135.502) のようになります。通常のLAN（HTTP）接続では、位置情報を要求することも添付することもありません。

通常のLAN接続では、ボイスメモを録るとスマホ本体の録音アプリが開きます。その間もセッションが切れないよう、スマホのページは次のように動きます。

• カメラ、ファイル選択、録音アプリへ切り替える直前に、PCへ「セッションをあと120秒まで延ばしてほしい」と依頼します（PC側のセッションは、通常60秒操作がないと終わります。サーバーは、この依頼を最大180秒までに制限します）。
• ページに戻ってくると、PCへ生存確認を送ります。
• 選んだファイルは、その場でメモリにコピーします（録音アプリがまだ書き込み中だったり、アクセス権を取り消したりすることがあるためです）。
• ファイルを読み込んでいる間は、送信ボタンが待機します。
• 送信に失敗したときは、PC側のセッションが生きているかを確認します。生きていれば、自動で1回だけ再送し、それでも失敗したら「通信エラー。もう一度お試しください」と表示します。
• PC側のセッションが終わっていれば、「PCとの接続が切れました。PCでMobile Dropを開き直し、QRコードを読み取り直してください」と表示します。
• 録音アプリを開かず、ページ内で直接録音するには、HTTPSのCloudflareトンネルが必要です。

• 両方が同じWi-Fiにつながっているか確認してください。ゲスト用ネットワークや一部のルーターは、機器どうしの通信を遮断します（AP分離）。PCまたはスマホのVPNが邪魔をすることもあります。
• Windowsでは、初回にMD-Memoのファイアウォールの確認が出ることがあります。プライベートネットワークで許可してください。
• QRコードのアドレスは、既定の通信経路（デフォルトルート）を持つネットワークアダプタのものです（WSLやDockerなどの仮想アダプタは除外します）。スマホがそのネットワークにいない場合は、上のCloudflare経由の接続を使ってください。

• 検索の対象は、20 個のコマンドと、開いているワークスペースフォルダのノートです。
• 「AIに質問」「コマンドバー」も、パレットから開けます。「コマンドバー: コマンドを実行」「コマンドバー: AIにコマンドを書かせる」は、モードを指定して開く項目で、既定のキーはありません。
• 「タスクのひな形を挿入」（説明: Ctrl+Enter で実行できる LLM・エージェント・コマンドのひな形）は、ひな形の一覧を、カーソルの位置に開きます。同じ一覧は、{{ を打っても出ます。詳しくは 自動セレクター の「ひな形」をご覧ください。
• 照合は単純な部分一致です。曖昧検索（ファジー検索）ではありません。
• 設定項目は検索できません。設定画面は Ctrl + ,（macOS: Cmd + ,）で開きます。

API キーなどの秘密情報

• 「API キーを含める」がオフのとき、名前に apikey、api_key、api-key、token、secret、password、passwd のどれかを含む設定項目の値を空にします。Git リモート URL の ユーザー:パスワード@ も取り除きます。
• エージェント定義は、env: の中にある同じ種類の値を空にします（コメントや並びはそのままです）。安全に書き換えられないときはファイルをそのまま入れ、「秘密情報が残っている可能性があります」と知らせます。共有する前に確かめてください。
• 空にした件数は、書き出しの完了画面に出ます。

読み込んだあとの動き

• 設定は、動いているアプリに統合されて、その場で保存されます。テーマ・言語・ツールバー・ショートカットもすぐ切り替わります。チェックを付けなかった区分は変わりません。
• エージェント定義とスキルは、MD-Memo 自身が書き込みます。config.json を直接書き換えて取り込むことはできません（起動中のアプリが、設定ファイルを持っているためです）。
• 書き込み先は、アプリ共通のエージェント定義が %APPDATA%\md-memo\agents.yaml（macOS は ~/Library/Application Support/md-memo/agents.yaml）、プロジェクトのものが <プロジェクト>/.md-memo/agents.yaml、スキルが <プロジェクト>/<フォルダ>/<名前> です。構文エラーのあるエージェント定義は、理由つきで読み飛ばします。
• 上書きされるエージェント定義とスキルは、先に %APPDATA%\md-memo\pack_backups\<日時>\（macOS は ~/Library/Application Support/md-memo/pack_backups/）へ退避されます。プロジェクトの外なので、スキルのフォルダに余計なファイルは増えません。場所は、読み込み後の画面にも出ます。
• 以前の設定 JSON（1 ファイルに全設定）も読み込めます。対象は設定だけで、API キーが入っていることがあります。書き出しの形式で「JSON（設定のみ）」を選ぶと、同じ形式のファイルができます。
• 設定の一部は、MD-Memo を再起動すると反映されます。読み込み後の画面に案内が出ます。

「プロジェクト」とは

開いているノートのフォルダ（保存前のノートは、開いているフォルダ、それも無ければスクラップフォルダ）から上へたどり、.md-memo、agents.yaml、AGENTS.md、skills、.git のどれかがある最初のフォルダです。ホームフォルダはプロジェクトとして扱いません（全体のスキルを持ち出さないためです）。決まらないときは、プロジェクトの項目に「プロジェクトが必要」と出て、選べません。

上限と安全

• パッケージは 50 MB・3000 ファイルまで、1 ファイルは 10 MB まで、展開後の合計は 100 MB までです。設定は 2 MB、エージェント定義は 1 ファイル 1 MB までです。上限を超えるスキルは、注意を出して書き出しから外します。
• スキルのフォルダにある .env と .env.*（.env.example などの雛形は入ります）、.git、node_modules、__pycache__ フォルダ、シンボリックリンクは入りません。
• 危険なパス（..・絶対パス・ドライブ文字など）を含むもの、暗号化されたものや壊れたもの、新しい版のパッケージは、読み込めません。目録（マニフェスト）に載っていないファイルは無視します。
• スキルはエージェントが従う指示で、エージェント定義には MD-Memo が実行するコマンドが入ります。信頼できる相手のものだけを読み込んでください。

• jev verify [--mode strict|reviewed|unattended] <cmd> は、GUIの実行ゲートと同じ、決定論的でローカル完結の常時稼働AST解析を使っています。外部には何も送信されません。
• 終了コード: 0 安全、1 ブロック、2 警告（破壊的とは断定できないが、ガードが安全を保証できない）。
• モード: モードはルールそのものを変えるのではなく、誰が見ているかによって判定の重みづけを変えます。strict（既定）は誰もレビューしないワンクリック経路向け、reviewed は実行前に人が確認する前提、unattended はフック向けです。
• sudo rm -rf / のようなコマンドは、どのモードでもブロックと判定されます。

エージェントは、この表を skills/md-memo/references/setup-guide.md の (e) から読みます。人が手で確認するときにも使えます。

• MD-Memo自身が読む変数: TYPESAFE_API_KEY（なければ JEV_API_KEY）、OPENROUTER_API_KEY（CLIだけ）、JEV_MODEL、JEV_API_URL、そして PATH など。
• 読まれない変数: GEMINI_API_KEY、GOOGLE_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY、OLLAMA_HOST。MD-Memo自身のLLM機能のキーとURLは、config.json からだけ読みます。これらの変数が役に立つのは、それを読む外部のエージェントCLIだけです。
• GUIアプリは引き継ぎません: スタートメニューやFinderから起動したアプリは、シェルのプロファイルの変数を引き継ぎません。macOSでは、MD-Memoが PATH だけを補正します。ほかの変数は、プロジェクトの .env を使ってください。
• Windowsで保存する: setx NAME "値" でユーザー環境変数に保存し、MD-Memoをトレイから完全に終了して、起動し直します。
• おすすめの分け方: エージェントのキーは <プロジェクトルート>/.env、MD-Memo自身のキーは config.json、OSの環境変数はPATHの追加とJev関連だけ。