prelude-install

Prelude のインストールと設定

Prelude は開発シェル向けの UI スイートです。flake-parts モジュール、または他の flake 向けの prelude.lib.evalModule として利用でき、nix develop のウェルカムバナー（MOTD）、対話型コマンドピッカー（x）、Markdown ドキュメントビューアー、テーマ付き Starship プロンプトを提供します。すべて公開済みの flake から実行されるため、Prelude リポジトリをチェックアウトする必要はありません。クローンせずにドキュメントを表示できます。

nix run github:darkmatter/prelude#skill -- install   # full consumer walkthrough
nix run github:darkmatter/prelude#skill -- options    # generated prelude.* reference

0. 既存の内容を確認する

変更を加える前に、リポジトリを確認します。

• flake.nix — flake-parts（flake-parts.lib.mkFlake）ではモジュールを使用します。それ以外（blueprint、通常の outputs 関数）では prelude.lib.evalModule を使用し、構成を組み替える必要はありません。既存の inputs、imports、devShells を確認し、維持してください。
• prelude.nix / title.txt — セットアップが必要か判断する前に、既存のサイドカーファイルを確認します。既存の設定をそのまま編集してください。ウィザードを再実行すると、両方のファイルが上書きされます。
• .envrc — 既存のローダーを維持してください。nix-direnv を導入するときのみ use flake を追加し、他の環境読み込み方式と併用しないでください。
• 既存の README と docs/ — セットアップでは変更されません。

1. ウィザードを実行する（新規インストール）

nix run github:darkmatter/prelude -- wizard

手順：タイトルテキストと FIGlet フォント、プロジェクト名、コマンド、コンポーネントの切り替え（motd／menu／prompt／docs／.envrc）、MOTD の文面とレイアウト、テーマ、確認。プロジェクトのルートから実行してください。対話型端末が必要です。以下を作成します。

• prelude.nix — すべてのオプションを含むテンプレートです。選択した項目は有効になり、その他のオプションはすべてコメントアウトされたデフォルトとして記載されます（このファイルはインラインドキュメントも兼ねます）。
• title.txt — レンダリングされたワードマークです。設定ファイルの隣に作成され、名前のみで参照されるため、どの -o ディレクトリからも解決されます。
• .envrc（内容は厳密に use flake）— 有効にされていて、既存のファイルがない場合のみ作成されます。
• docs を有効にした場合：プロジェクトのルートにスターター用の README.md と docs/getting-started.md を作成します。既存のファイルは維持されます。

-o path を指定すると、サイドカーファイルと title.txt が移動します。ただし、出力される docs のエントリー（./README.md、./docs/getting-started.md）はサイドカーファイルからの相対パスですが、スターターファイルはルートに作成されます。ルート以外の -o を指定した場合は、評価する前にこれらのパスを修正してください。ウィザードは -o flake.nix を拒否し、flake を作成または置換することはありません。flake がまったくない場合は、代わりに nix flake init -t github:darkmatter/prelude#default でスターターを生成します（prelude.* をインラインで設定し、_確認_に進んでください）。

2. flake に組み込む（置き換えずに統合する）

この例では、既存の flake.nix に統合する Prelude 固有の行を示します。現在のすべての input、import、開発シェルのパッケージを維持してください。

inputs.prelude.url = "github:darkmatter/prelude";
# Fresh repo, no pins yet: share one nixpkgs/flake-parts via inputs:
#   inputs.nixpkgs.follows = "prelude/nixpkgs";
#   inputs.flake-parts.follows = "prelude/flake-parts";
# flake.lock pins the resolved revision even with the default-branch URL.
# Preserve an existing lock; use that revision for wizard/reference commands.
# A URL ending in /<rev> may additionally select an explicit commit or tag.

# inside mkFlake's module argument:
imports = [
  inputs.prelude.flakeModules.default
  ./prelude.nix # generated sidecar; import it, never replace flake.nix
];

# inside perSystem, alongside existing packages:
devShells.default = pkgs.mkShell {
  packages = [config.packages.prelude-shell];
};

config.packages.prelude-shell のみを開発シェルに追加してください。これは有効なすべてのコンポーネントをまとめ、setup-hook によって有効化します。packages.prelude は追加しないでください（これは prelude アプリの基盤です）。

flake-parts を使わない場合（blueprint、通常の outputs 関数）：flake の構成はそのまま維持し、開発シェルが定義されている箇所で同じサイドカーファイルを評価してください。モジュールと同じパッケージがビルドされます。

# blueprint: devshell.nix (nix/devshells/default.nix with prefix = "nix/")
{pkgs, inputs, ...}: let
  prelude = inputs.prelude.lib.evalModule pkgs ./prelude.nix;
in
  pkgs.mkShell {packages = [prelude.packages.prelude-shell];}

モジュールには pkgs が渡されるため、パッケージを使うコマンドはそのまま prelude.commands に追加できます。perSystem はありません。他のモジュール引数（self、inputs）はラッパーモジュールの _module.args を通して渡してください。参考：examples/without-flake-parts/。

nix run github:darkmatter/prelude#docs（および #prelude-docs）でプロジェクト独自のドキュメントを開けるようにするには、prelude-docs を公開してください。flake-parts ではすでに設定されています。それ以外の場合は、legacyPackages = forAllSystems (pkgs: (prelude.lib.evalModule pkgs ./prelude.nix).packages); を追加するか、blueprint では packages/prelude-docs.nix を追加してください。

3. 有効化の方法

• nix develop — フル機能の対話型 devshell です。プロンプトコンポーネントが有効な場合（ウィザードのデフォルト）、セットアップフックが生成された init を読み込みます。MOTD が表示され、x／docs が PATH に追加され、STARSHIP_CONFIG がエクスポートされます。追加の設定は不要です。prelude.workspace.enable = true の場合、TTY を備えた対話型 Bash は、フッターとカタログ補完を含むワークスペースにフォアグラウンドで入ります。Starship の自動設定は prelude.prompt.enable に従います。

• direnv（nix-direnv）— 生成された .envrc（use flake）がキャッシュ済みの環境を読み込み、MOTD を表示し、プロンプトコンポーネントが有効な場合は、初期化済みの Starship プロンプトにテーマを適用します。起動は軽量で、フルフッターやカタログ補完はありません。新しい開発者に必要なのは既存の direnv フックだけで、Prelude の Bash rc フックを追加する必要はありません。既存の .envrc とそのローダーは維持してください。 prelude.workspace.enable = true の場合も、.envrc は use flake のままにしてください。.envrc からワークスペースを起動したり、対話型プロジェクトの init を読み込んだりしないでください。ローダーのみの MOTD には「Run nix develop for the full devshell」と表示されます。このヒントはワークスペースモードまたは quiet モードでは非表示になります。有効なワークスペースを使うには、対話型の nix develop を実行してください。公開されている prelude hook bash は、direnv の後にすでに設定済みの対話型引き継ぎで引き続き任意で使えますが、オンボーディングには不要です。 各 init は起動前に記録されるため、終了または失敗してもすぐには再度開きません。devshell から退出して再入するか、init に変更があると、再度入れるようになります。非対話型、envrc、lorri、zsh、TTY 以外の各コンテキストでは自動起動しません。PRELUDE_WORKSPACE_ACTIVE によって子プロセスでの再帰を防ぎます。ワークスペースモードでは従来の BLE 初期化をスキップします。手動での x prelude:workspace と prelude-workspace --starship も引き続きサポートされます。

• lorri — Nix ビルダー内で shellHook を実行するため、同じ .envrc を経由させます。use flake を eval "$(lorri export direnv-adapter)" に置き換えてください。

• カスタム shellHook — eval "$(prelude-preflight)" がローダー対応の有効化行です。shellHook では export -f を絶対に使わないでください（zsh は BASH_FUNC_…%% の名前に含まれる % を拒否します）。シェル固有の設定は prelude hook に記述してください。

4. カスタマイズ

生成された prelude.nix を編集してください（flake.nix 内のインライン設定でも構いません）。すべてのオプションがコメント付きのデフォルト値としてそこにあります。主な項目：

• prelude.theme — prelude（デフォルト）、phosphor、minted、amber、 solarized、nord、gruvbox、paper（ライト）、mono、apathy。トークンの 上書きには prelude.palette を使います。
• prelude.commands.<key> — x から利用するカタログ項目。スペースまたは / を使うとサブコマンドになります（"db migrate" → db 行の下に x db migrate を表示）。group = "…" はメニューの見出しを設定します。パッケージに基づくコマンド： prelude.lib.fromPkg packages.dev { description = …; motd = 1; }。
• prelude.docs.pages = [{text = ./docs/foo.md;}] — ファイルごとに 1 ページを指定します。

5. 新規ファイルを Git の追跡対象にしてから検証する

Git 管理の flake では、未追跡ファイルは除外されます。git status --short を確認し、このセットアップ用に作成または編集したファイルのうち、意図したものだけをステージしてください。無関係な変更はステージせず、git add のエラーを抑制しないでください。参照先になっている新規作成の README.md、実際のサイドカーと隣接する title.txt の場所（カスタム -o パスを含む）、新たに参照するドキュメントを含めてください。ウィザードで使うというだけの理由で、既存の .envrc をステージしないでください。ローカルでの評価にコミットは不要です。

代わりに nix develop path:. と nix flake check path:. で検証すれば、インデックスを変更せずに作業ディレクトリを対象にできます。通常は Git によって除外されるファイルが含まれる場合があるため、信頼できるローカルの作業ツリーでのみ使用してください。

次に、実際のスモークチェックを実行します。

nix develop     # MOTD renders, themed prompt appears
x --list        # catalogue table prints non-interactively
x               # picker opens (q quits)
docs            # viewer opens when docs pages exist (q quits)
motd            # banner reprints on demand
nix flake check # full build gate (heavier)

非対話型の nix develop -c … は設計上、出力を表示しません（ビルドログにバナーは出ません）。MOTD を確認するには、対話型シェルを使ってください。

引き継ぎ

• /prelude-just <arg> — 既存の justfile を適応させます。
• /prelude-docs — docs-viewer のページを作成します。
• /prelude <anything> — その他の Prelude 作業に使います。