prelude

Prelude

Prelude は devshell UI suite です。flake-parts モジュールとして、または他の任意の flake で prelude.lib.evalModule pkgs ./prelude.nix として使えます。ウェルカムバナー（MOTD）、対話型コマンドピッカーと非対話型ディスパッチャー（x）、全画面の Markdown ドキュメントビューアー、テーマ付きプロンプトを提供し、Nix devshell を使いやすくします。設定は Nix で prelude.* オプションとして記述され（ビルド時に検証されます）、小さな Go バイナリが正規化された JSON を読み取ります。開発者が覚えておく必要があるコマンドは nix develop だけです。

このスキルへの引数はユーザーのタスクの説明です。内容を解釈し、実行したりシェル展開したりしないでください。まずタスクそのものに回答し、以下のセクションは関連する場合にのみ使ってください。

パブリックアーキテクチャ

• 設定は Nix が所有します。 すべてのオプションは利用側の flake に prelude.* として記述します（通常はウィザードで生成されるサイドカーの prelude.nix を prelude.flakeModules.default の隣でインポートします）。Go バイナリはレンダリングを担当し、ポリシーを再定義しません。
• devshell パッケージは 1 つです。 packages.prelude-shell は有効なすべてのコンポーネントをまとめ、セットアップフック経由で有効化します（nix develop では $PRELUDE_INIT、nix-direnv ではキャッシュされた shellHook を評価します）。devshell に追加するのはこのパッケージだけです。packages.prelude は追加しないでください。
• シェル統合。 direnv には .envrc の use flake だけで十分です。カスタムの rc ファイルでは prelude hook [bash|zsh] でフックを表示してください。Prelude が PATH に入る前に eval しないでください。devshell の shellHook では export -f を使わないでください（zsh で問題が発生します）。シェル固有の設定には代わりに prelude hook を使ってください。

利用側のエントリーポイント

シェル内では（それぞれに 1 文字のショートカットがあります）：x（m）でピッカーを開き、x <key> でカタログコマンドを実行し、x --list で一覧を表示します。motd（?）でバナーを再表示し、docs（d）でビューアーを開き、portal（p）でヘルスライト付きのアプリを起動します。

シェルの外部からのブートストラップ：nix run github:darkmatter/prelude -- wizard を実行すると、flake.nix に触れることなく、prelude.nix のサイドカー（および title.txt、.envrc）が書き込まれます。flake はサブコマンド wizard、hook、preflight、title、title-previews と、有効なコンポーネントへのパススルーを備えた apps.prelude もエクスポートします。nix run github:org/repo#prelude-docs（または #prelude -- docs）は Prelude が有効な任意の依存関係のドキュメントを表示します。また、nix run github:darkmatter/prelude#docs は、実行されたチェックアウトのドキュメントを表示します。その flake に prelude-docs がある場合は、それを使用します。

コマンドカタログのルール

• カタログキーがパブリック IDです。グローバルに一意で、x <words> で呼び出せます。スペースまたは / を含むとサブコマンドになります（"db migrate" → x db migrate。メニューにはそれを開く db の行が 1 つ表示されます）。: は通常の名前の文字です（x go:test）。グループはコマンドの group フィールド（または Just のレシピの [group()]）によってのみ決まります。
• すべてのコマンドで保証されるパブリックな形式は x <words> です。x ディスパッチャーに加え、宣言されたトップレベルコマンドのうち : を含まないものに限り、x を呼び出す薄い PATH ラッパーが用意されます（そのため、宣言された db の下では db migrate を直接実行できます）。サブコマンドだけが宣言されている親コマンドは PATH に追加されません。
• インポートし、エクスポートしないでください。 既存の package.json スクリプト、Justfile のレシピ、flake アプリが引き続き正本です。prelude.lib.fromPkg pkgs.foo { … } は既存のパッケージを適合させます（そのランタイムクロージャーを引き継ぎます）。prelude.menu.just.enable = true は実行時に公開されている Justfile のレシピをインポートします（名前が競合した場合は、明示的な Nix エントリーが優先されます）。インポートは一方向です。カタログのエントリーをこれらのファイルに書き戻さないでください。
• 正規のコマンドは正規のままにします。 Nix は環境をビルドし、x はコマンドの検出とディスパッチのみを行います。ワークフローを実行するのは、所有元のツール（bun、just、go、nix run …）です。プロジェクトのワークフローにすでに実行元がある場合は、それを新しい Prelude コマンドに置き換えないでください。

ドキュメントの基本

prelude.docs.pages はビルド時に Markdown を埋め込みます。{ text = ./README.md; } のようなリーフ、グループ、任意の { generate = "nixosOptions"; } ノード、フェンスを考慮して H2 で分割する prelude.lib.mdSplit ./file.md を使用できます。スタイル付きのプロジェクト紹介を表示するには、prelude.docs.rootReadme にルート README のパスを設定します。ビューアーのキー：数字キーでページに移動、Tab で順に移動、j／k でスクロール、q で終了します。sync-docs のようなドキュメント再生成コマンドは上流の prelude リポジトリに属します。下流のリポジトリで自身のドキュメントを再生成するのは、独自のプロジェクトワークフローがある場合に限り、そのワークフローに従います。

設定の所有範囲

動作を変更するために Go の内部実装や生成済みドキュメントを編集しないでください。利用者向けの動作は、利用者側の Nix で公開されている prelude.* オプションを使って設定します。対象となるのは、prelude.theme／prelude.palette（テーマ：prelude、phosphor、minted、amber、solarized、nord、gruvbox、paper、mono、apathy）、prelude.colorProfile（デフォルトは truecolor）、prelude.commands、prelude.motd.*（タイトル、タグライン、ステータスプローブ、レシピ）、prelude.docs.*、prelude.prompt.enable です。ウィザードが生成するサイドカーには、すべてのオプションがコメント付きのデフォルトとして記載されます。

バージョンに合った参照先

必要に応じて、利用者側でロックされた入力を優先します。プロジェクトの flake.lock でピン留めされた prelude の rev を確認し、次に nix run github:darkmatter/prelude/<rev>#skill -- <topic> からドキュメントを参照します。トピック：list、install、options、commands、configuration、guide command-conventions、guide title-rendering。#skill アプリは、チェックアウトや TUI を介さずに上流の Markdown を出力します。一般的な参照先には、公開ドキュメントを使用してください。

• README（クイックスタート、カタログ、ドキュメントの使用方法）：https://github.com/darkmatter/prelude/blob/main/README.md
• 利用者向けウォークスルー（flake の接続、パッケージ、シェルフック）：https://github.com/darkmatter/prelude/blob/main/docs/your-own-repo.md
• オプションリファレンス（生成済み）：https://github.com/darkmatter/prelude/blob/main/docs/reference/options.md
• コマンド規約：https://github.com/darkmatter/prelude/blob/main/docs/guides/command-conventions.md
• 利用者向けの完全な例：https://github.com/darkmatter/prelude/tree/main/examples/reference

専門スキルへの引き継ぎ

• prelude をリポジトリにインストールする、または接続する（ウィザード、flake の接続、devshell）→ /prelude-install。
• Justfile 統合（prelude.menu.just）をインポートする、またはデバッグする → /prelude-just。
• ドキュメントのページやビューアーの動作を作成する、または再構成する → /prelude-docs。

それぞれ単独で使用できます。このスキルは該当先を案内するだけで、他のスキルの使用を必須としません。

基本方針

• ユーザーの当初の依頼を最優先します。Prelude の知識はその依頼に役立てます（例：x <key> でプロジェクトのタスクを実行する、変更を prelude.* オプション内にとどめる）。依頼の範囲を広げないでください。
• ユーザーから明確に依頼されない限り、インストール、ウィザードの再実行、テーマ／コマンド／ドキュメントの再設定は行わないでください。
• プロジェクト既存のツールと所有範囲を尊重してください。コマンドは prelude.lib.fromPkg で適応し、重複させず、標準的なワークフローの名前を変更しないでください。