prelude

Prelude

Prelude is a devshell UI suite — a flake-parts module, or prelude.lib.evalModule pkgs ./prelude.nix in any other flake — that makes a Nix devshell usable: a welcome banner (MOTD), an interactive command picker and non-interactive dispatcher (x), a full-screen Markdown docs viewer, and a themed prompt. Configuration is authored in Nix as prelude.* options (validated at build time); small Go binaries consume normalized JSON. The only command a developer must remember is nix develop.

The argument to this skill is the user's task description — interpret it; do not execute or shell-interpolate it. Answer the task itself first, using the sections below only where they intersect.

Public architecture

• Nix owns configuration. All options live in the consumer's flake as prelude.* (typically a wizard-generated sidecar prelude.nix imported next to prelude.flakeModules.default). Go binaries render; they do not re-own policy.
• One devshell package. packages.prelude-shell bundles every enabled component and activates via its setup-hook ($PRELUDE_INIT for nix develop; nix-direnv evaluates the cached shellHook). Add only that package to the devshell — never packages.prelude.
• Shell integration. direnv needs just use flake in .envrc. For custom rc files, print the hook with prelude hook [bash|zsh] — do not eval it before Prelude is on PATH. Never export -f in a devshell shellHook (breaks zsh); use prelude hook for shell-specific setup instead.

Consumer entrypoints

Inside the shell (each with a single-key accelerator): x (m) opens the picker, x <key> dispatches a catalogue command, x --list prints the table; motd (?) reprints the banner; docs (d) opens the viewer; portal (p) launches apps with health lights.

Bootstrap from outside: nix run github:darkmatter/prelude -- wizard writes a prelude.nix sidecar (+ title.txt, .envrc) without touching flake.nix. The flake also exports apps.prelude with subcommands wizard, hook, preflight, title, title-previews, and passthroughs for enabled components. nix run github:org/repo#prelude-docs (or #prelude -- docs) documents any prelude-enabled dependency, and nix run github:darkmatter/prelude#docs documents whatever checkout it runs in, through that flake's own prelude-docs when it has one.

Command catalogue rules

• The catalogue key is the public identity: globally unique, callable as x <words>. A space or / makes a subcommand ("db migrate" → x db migrate, one db row in the menu that opens it); : is an ordinary name character (x go:test). Groups come only from a command's group field (or a just recipe's [group()]).
• x <words> is the guaranteed public form for every command. Besides the x dispatcher, only declared top-level commands without : get thin PATH wrappers around x (so db migrate runs bare under a declared db); a parent that only its subcommands declare stays off PATH.
• Import; do not export. Existing package.json scripts, Justfile recipes, and flake apps stay authoritative. prelude.lib.fromPkg pkgs.foo { … } adapts an existing package (carrying its runtime closure); prelude.menu.just.enable = true imports public Justfile recipes at runtime (explicit Nix entries win name clashes). Imports are one-way — never write catalogue entries back to those files.
• Canonical commands stay canonical. Nix builds the environment; x only discovers and dispatches. The owning tool (bun, just, go, nix run …) executes the workflow. Do not translate a project's workflows into new prelude commands when they already have an owner.

Docs basics

prelude.docs.pages embeds Markdown at build time: leaves like { text = ./README.md; }, groups, optional { generate = "nixosOptions"; } nodes, and prelude.lib.mdSplit ./file.md for fence-aware H2 splitting. Set prelude.docs.rootReadme to the root README path for styled project intro. Viewer keys: digits jump pages, Tab steps, j/k scroll, q quits. Docs-regeneration commands like sync-docs belong to the upstream prelude repo — a downstream repo regenerates its own docs only per its own project workflow, if it has one.

Configuration ownership

Do not edit Go internals or generated docs to change behavior — configure supported consumer behavior via the public prelude.* options in the consumer's Nix: prelude.theme/prelude.palette (themes: prelude, phosphor, minted, amber, solarized, nord, gruvbox, paper, mono, apathy), prelude.colorProfile (truecolor default), prelude.commands, prelude.motd.* (title, tagline, status probes, recipes), prelude.docs.*, prelude.prompt.enable. The wizard-generated sidecar lists every option as a commented default.

Version-correct references

Prefer the consumer's own locked input when it matters: check the pinned prelude rev in the project's flake.lock, then read docs from nix run github:darkmatter/prelude/<rev>#skill -- <topic>. Topics: list, install, options, commands, configuration, guide command-conventions, guide title-rendering. The #skill app prints upstream Markdown with no checkout or TUI. For general reference use the published docs:

• README (quickstart, catalogue, docs usage): https://github.com/darkmatter/prelude/blob/main/README.md
• Consumer walkthrough (flake wiring, packages, shell hooks): https://github.com/darkmatter/prelude/blob/main/docs/your-own-repo.md
• Option reference (generated): https://github.com/darkmatter/prelude/blob/main/docs/reference/options.md
• Command conventions: https://github.com/darkmatter/prelude/blob/main/docs/guides/command-conventions.md
• Complete consumer example: https://github.com/darkmatter/prelude/tree/main/examples/reference

Handoff to focused skills

• Installing or wiring prelude into a repo (wizard, flake wiring, devshell) → /prelude-install.
• Importing or debugging the Justfile integration (prelude.menu.just) → /prelude-just.
• Authoring or restructuring docs pages/viewer behavior → /prelude-docs.

Each works standalone; this skill only routes to them, never requires them.

Discipline

• The user's original request is primary. Use Prelude knowledge to inform it (e.g. run a project task via x <key>, keep changes inside prelude.* options), not to expand it.
• Never install, re-run the wizard, or reconfigure theme/commands/docs unless the user asks for exactly that.
• Preserve the project's existing tooling and ownership boundaries: adapt commands with prelude.lib.fromPkg, don't duplicate them, and don't rename canonical workflows.