Replace root README with repo overview
This commit is contained in:
@@ -1 +0,0 @@
|
|||||||
dotfiles/emacs.d/README.org
|
|
||||||
228
README.org
Normal file
228
README.org
Normal file
@@ -0,0 +1,228 @@
|
|||||||
|
# -*- mode: org; -*-
|
||||||
|
#+TITLE: colonelpanic8's Dotfiles
|
||||||
|
|
||||||
|
This repository is the source of truth for my machines, user environment, and a
|
||||||
|
large set of day-to-day workflow scripts. It started as an Emacs configuration,
|
||||||
|
and that is still here, but the repo is now mostly a Nix-managed personal
|
||||||
|
systems repo: NixOS hosts, a nix-darwin host, Home Manager link management,
|
||||||
|
desktop/window-manager configuration, shell tooling, agent configuration, and
|
||||||
|
org-agenda-api deployment glue.
|
||||||
|
|
||||||
|
The old literate Emacs README lives at [[file:dotfiles/emacs.d/README.org][dotfiles/emacs.d/README.org]]. The
|
||||||
|
published GitHub Pages site is still generated from that document.
|
||||||
|
|
||||||
|
* What This Manages
|
||||||
|
|
||||||
|
- NixOS systems under [[file:nixos/][nixos/]], with one flake configuration per file in
|
||||||
|
[[file:nixos/machines/][nixos/machines/]].
|
||||||
|
- A nix-darwin configuration under [[file:nix-darwin/][nix-darwin/]] for the macOS machine.
|
||||||
|
- Shared Nix modules and overlays under [[file:nix-shared/][nix-shared/]].
|
||||||
|
- Home Manager placement of files from [[file:dotfiles/][dotfiles/]] into =$HOME= and
|
||||||
|
=$XDG_CONFIG_HOME=.
|
||||||
|
- Shell functions and executable helpers in [[file:dotfiles/lib/][dotfiles/lib/]], added to
|
||||||
|
=PATH= and =fpath= by the NixOS environment module.
|
||||||
|
- Desktop environment and tiling-window-manager configuration for Hyprland,
|
||||||
|
XMonad, River/XMonad experiments, Taffybar, Waybar, Rofi, Alacritty,
|
||||||
|
autorandr, and related utilities.
|
||||||
|
- Emacs and org-mode configuration, including the tangled org configuration used
|
||||||
|
by the org-agenda-api container.
|
||||||
|
- Agent and tool configuration for Codex, Claude, project guides, and local
|
||||||
|
task-specific skills.
|
||||||
|
- Container and deployment configuration for personal org-agenda-api instances.
|
||||||
|
|
||||||
|
This is not intended to be a generic starter dotfiles repo. Many modules assume
|
||||||
|
my users, hostnames, hardware, SSH keys, secrets layout, and local checkout path
|
||||||
|
=(~/dotfiles=). It is still useful as a reference for how the pieces fit
|
||||||
|
together.
|
||||||
|
|
||||||
|
* Layout
|
||||||
|
|
||||||
|
| Path | Purpose |
|
||||||
|
|------+---------|
|
||||||
|
| [[file:nixos/][nixos/]] | Main NixOS flake. Imports feature modules, host files, agenix secrets, Home Manager, overlays, and package checks. |
|
||||||
|
| [[file:nixos/machines/][nixos/machines/]] | Per-host NixOS entrypoints such as =strixi-minaj=, =ryzen-shine=, =railbird-sf=, WSL hosts, and Raspberry Pi hosts. |
|
||||||
|
| [[file:nix-darwin/][nix-darwin/]] | macOS system flake using nix-darwin, nix-homebrew, Home Manager, agenix, and shared packages. |
|
||||||
|
| [[file:nix-shared/][nix-shared/]] | Shared package lists, overlays, Home Manager modules, and Syncthing fragments used by Linux and macOS. |
|
||||||
|
| [[file:dotfiles/][dotfiles/]] | Files that are linked into the home directory. Top-level entries become dotfiles; =dotfiles/config/*= becomes XDG config. |
|
||||||
|
| [[file:dotfiles/lib/bin/][dotfiles/lib/bin/]] | User commands and desktop helpers, including Rofi scripts, Hyprland helpers, audio controls, and Syncthing utilities. |
|
||||||
|
| [[file:dotfiles/lib/functions/][dotfiles/lib/functions/]] | Zsh autoload functions and shell helpers. |
|
||||||
|
| [[file:dotfiles/config/hypr/][dotfiles/config/hypr/]] | Hyprland Lua config, lock/idle config, workspace files, scripts, and plugin state. |
|
||||||
|
| [[file:dotfiles/config/xmonad/][dotfiles/config/xmonad/]] | XMonad configuration, local Cabal package, flake, and upstream submodules. |
|
||||||
|
| [[file:dotfiles/config/taffybar/][dotfiles/config/taffybar/]] | Personal Taffybar package/configuration, CSS themes, scripts, and local upstream checkout. |
|
||||||
|
| [[file:dotfiles/emacs.d/][dotfiles/emacs.d/]] | Emacs configuration, literate org config, org-mode setup, snippets, and generated/tangled Elisp. |
|
||||||
|
| [[file:dotfiles/agents/][dotfiles/agents/]] | Agent instructions, project constellation guides, and local Codex skills. |
|
||||||
|
| [[file:org-agenda-api/][org-agenda-api/]] | Instance-specific config and container/deploy glue for org-agenda-api. |
|
||||||
|
| [[file:docs/][docs/]] | Design notes for Cachix, tiling WM behavior, River evaluation, and org-agenda-api consolidation. |
|
||||||
|
| [[file:gen-gh-pages/][gen-gh-pages/]] | Legacy/publication pipeline that exports the Emacs README to GitHub Pages. |
|
||||||
|
|
||||||
|
* NixOS
|
||||||
|
|
||||||
|
The NixOS flake is [[file:nixos/flake.nix][nixos/flake.nix]]. It discovers host configurations from
|
||||||
|
[[file:nixos/machines/][nixos/machines/]] and exposes them as =nixosConfigurations.<hostname>=.
|
||||||
|
The broad feature set is assembled by [[file:nixos/configuration.nix][nixos/configuration.nix]], where
|
||||||
|
=features.full.enable= expands into the normal desktop/profile modules.
|
||||||
|
|
||||||
|
Common workflow:
|
||||||
|
|
||||||
|
#+begin_src sh
|
||||||
|
cd ~/dotfiles/nixos
|
||||||
|
just switch
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
The local =just switch= recipe wraps =nixos-rebuild switch --flake ".#"=, waits
|
||||||
|
for an already-running switch to finish, and overrides the Taffybar inputs to
|
||||||
|
the live checkout under this repo. Use it instead of running =nixos-rebuild=
|
||||||
|
directly.
|
||||||
|
|
||||||
|
Useful variants:
|
||||||
|
|
||||||
|
#+begin_src sh
|
||||||
|
cd ~/dotfiles/nixos
|
||||||
|
just switch-remote
|
||||||
|
just switch-local-taffybar
|
||||||
|
just remote-switch <host>
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
Build/check examples:
|
||||||
|
|
||||||
|
#+begin_src sh
|
||||||
|
nix flake check ~/dotfiles/nixos
|
||||||
|
nix build ~/dotfiles/nixos#nixosConfigurations.strixi-minaj.config.system.build.toplevel
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
The flake also exposes package/check outputs for Hyprland plugins and a
|
||||||
|
Hyprland Lua config syntax/verification check.
|
||||||
|
|
||||||
|
* nix-darwin
|
||||||
|
|
||||||
|
The macOS configuration lives in [[file:nix-darwin/flake.nix][nix-darwin/flake.nix]]. It uses
|
||||||
|
nix-darwin, nix-homebrew, Home Manager, agenix, and the shared package list in
|
||||||
|
[[file:nix-shared/system/essential.nix][nix-shared/system/essential.nix]].
|
||||||
|
|
||||||
|
Common workflow:
|
||||||
|
|
||||||
|
#+begin_src sh
|
||||||
|
cd ~/dotfiles/nix-darwin
|
||||||
|
just switch
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
The active host configuration is =mac-demarco-mini=. There is also a
|
||||||
|
=mac-demarco-mini-imalison= target used while migrating the primary macOS user.
|
||||||
|
|
||||||
|
* Home File Linking
|
||||||
|
|
||||||
|
The NixOS Home Manager module [[file:nixos/dotfiles-links.nix][nixos/dotfiles-links.nix]] reproduces the useful
|
||||||
|
part of =rcm/rcup=:
|
||||||
|
|
||||||
|
- files under [[file:dotfiles/][dotfiles/]] are linked into =$HOME= with a leading dot;
|
||||||
|
- directories under [[file:dotfiles/config/][dotfiles/config/]] are linked into =$XDG_CONFIG_HOME=;
|
||||||
|
- links are out-of-store symlinks, so editing the checkout updates runtime
|
||||||
|
config immediately;
|
||||||
|
- generated or special directories such as =codex=, =lib=, =config=, and
|
||||||
|
=emacs.d= are handled separately.
|
||||||
|
|
||||||
|
On NixOS, shell scripts belong in [[file:dotfiles/lib/bin/][dotfiles/lib/bin/]] and autoloaded shell
|
||||||
|
functions belong in [[file:dotfiles/lib/functions/][dotfiles/lib/functions/]]. [[file:nixos/environment.nix][nixos/environment.nix]] adds
|
||||||
|
those paths to the shell environment.
|
||||||
|
|
||||||
|
The nix-darwin Home Manager module in [[file:nix-darwin/home/common.nix][nix-darwin/home/common.nix]] uses the
|
||||||
|
same basic idea for macOS, with extra launchd, GPG, Raycast, Homebrew, and agent
|
||||||
|
setup.
|
||||||
|
|
||||||
|
* Desktop Stack
|
||||||
|
|
||||||
|
The desktop setup is modular. [[file:nixos/desktop.nix][nixos/desktop.nix]] enables the common desktop
|
||||||
|
surface, while individual modules layer in window managers, panels, launchers,
|
||||||
|
notifications, SNI/tray support, fonts, and app defaults.
|
||||||
|
|
||||||
|
The currently important pieces are:
|
||||||
|
|
||||||
|
- Hyprland configuration in [[file:dotfiles/config/hypr/hyprland.lua][dotfiles/config/hypr/hyprland.lua]], backed by custom
|
||||||
|
plugin inputs in the NixOS flake.
|
||||||
|
- XMonad configuration in [[file:dotfiles/config/xmonad/xmonad.hs][dotfiles/config/xmonad/xmonad.hs]], with upstream
|
||||||
|
=xmonad= and =xmonad-contrib= available as submodules/checkouts.
|
||||||
|
- Taffybar configuration in [[file:dotfiles/config/taffybar/taffybar.hs][dotfiles/config/taffybar/taffybar.hs]], plus a local
|
||||||
|
flake and scripts for restart, screenshots, and SNI debugging.
|
||||||
|
- Waybar, Rofi, autorandr, Alacritty, Zellij, and miscellaneous app configs
|
||||||
|
under [[file:dotfiles/config/][dotfiles/config/]].
|
||||||
|
|
||||||
|
The intended tiling-WM behavior is documented in
|
||||||
|
[[file:docs/tiling-wm-experience.md][docs/tiling-wm-experience.md]], and the River/XMonad exploration is documented in
|
||||||
|
[[file:docs/riverwm-evaluation.md][docs/riverwm-evaluation.md]].
|
||||||
|
|
||||||
|
* Emacs And Org
|
||||||
|
|
||||||
|
Emacs is still a major part of the repo, just no longer the only thing here.
|
||||||
|
The main files are:
|
||||||
|
|
||||||
|
- [[file:dotfiles/emacs.d/README.org][dotfiles/emacs.d/README.org]]: the original literate Emacs README.
|
||||||
|
- [[file:dotfiles/emacs.d/init.el][dotfiles/emacs.d/init.el]] and [[file:dotfiles/emacs.d/early-init.el][early-init.el]]: runtime entrypoints.
|
||||||
|
- [[file:dotfiles/emacs.d/org-config.org][dotfiles/emacs.d/org-config.org]]: the org-mode configuration that is tangled
|
||||||
|
for normal Emacs and for org-agenda-api.
|
||||||
|
- [[file:gen-gh-pages/][gen-gh-pages/]] and [[file:.github/workflows/gh-pages.yml][.github/workflows/gh-pages.yml]]: export the Emacs README
|
||||||
|
to the public GitHub Pages site.
|
||||||
|
|
||||||
|
* org-agenda-api
|
||||||
|
|
||||||
|
The repo carries the personal integration layer for
|
||||||
|
[[https://github.com/colonelpanic8/org-agenda-api][org-agenda-api]].
|
||||||
|
[[file:nixos/org-agenda-api.nix][nixos/org-agenda-api.nix]] tangles the org-mode configuration from
|
||||||
|
[[file:dotfiles/emacs.d/org-config.org][dotfiles/emacs.d/org-config.org]]. [[file:org-agenda-api/container.nix][org-agenda-api/container.nix]] combines that
|
||||||
|
tangled config with per-instance loaders under [[file:org-agenda-api/configs/][org-agenda-api/configs/]] and
|
||||||
|
builds OCI containers exposed by the NixOS flake.
|
||||||
|
|
||||||
|
The host-side NixOS module [[file:nixos/org-agenda-api-host.nix][nixos/org-agenda-api-host.nix]] runs the container
|
||||||
|
behind nginx with ACME certificates and Podman.
|
||||||
|
|
||||||
|
To enter the deployment shell:
|
||||||
|
|
||||||
|
#+begin_src sh
|
||||||
|
nix develop ~/dotfiles/nixos#org-agenda-api
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
* Secrets
|
||||||
|
|
||||||
|
Secrets are intentionally not stored as plaintext in the repo. Nix-managed
|
||||||
|
secrets use agenix files under [[file:nixos/secrets/][nixos/secrets/]]. Runtime credentials and
|
||||||
|
personal service passwords live in =pass=. Modules and scripts should consume
|
||||||
|
secrets from those sources at runtime rather than checking derived values into
|
||||||
|
git.
|
||||||
|
|
||||||
|
* Submodules And Local Checkouts
|
||||||
|
|
||||||
|
Some third-party or upstream projects are tracked as submodules:
|
||||||
|
|
||||||
|
- =dotfiles/config/taffybar/taffybar=
|
||||||
|
- =dotfiles/config/xmonad/xmonad=
|
||||||
|
- =dotfiles/config/xmonad/xmonad-contrib=
|
||||||
|
- =dotfiles/config/alacritty/themes=
|
||||||
|
- =nixos/railbird.ai=
|
||||||
|
|
||||||
|
Clone with submodules when bootstrapping a new checkout:
|
||||||
|
|
||||||
|
#+begin_src sh
|
||||||
|
git clone --recurse-submodules git@github.com:IvanMalison/dotfiles.git ~/dotfiles
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
This repo also contains project-local git worktrees under =.worktrees/= during
|
||||||
|
active development. Those are machine-local working state and are ignored.
|
||||||
|
|
||||||
|
* CI And Caches
|
||||||
|
|
||||||
|
[[file:.github/workflows/cachix.yml][.github/workflows/cachix.yml]] can build the =strixi-minaj= NixOS closure and
|
||||||
|
push paths to Cachix. [[file:docs/cachix.md][docs/cachix.md]] documents the cache setup.
|
||||||
|
|
||||||
|
The top-level [[file:justfile][justfile]] contains helper commands for populating the
|
||||||
|
=colonelpanic8-dotfiles= Cachix cache from a local machine.
|
||||||
|
|
||||||
|
* Working In This Repo
|
||||||
|
|
||||||
|
- Prefer Nix modules for system-level behavior and Home Manager modules for
|
||||||
|
user-level placement and services.
|
||||||
|
- Put user commands in [[file:dotfiles/lib/bin/][dotfiles/lib/bin/]] and shell functions in
|
||||||
|
[[file:dotfiles/lib/functions/][dotfiles/lib/functions/]].
|
||||||
|
- Run NixOS switches from [[file:nixos/][nixos/]] with =just switch=.
|
||||||
|
- Run macOS switches from [[file:nix-darwin/][nix-darwin/]] with =just switch=.
|
||||||
|
- Keep host-specific behavior in [[file:nixos/machines/][nixos/machines/]] where possible.
|
||||||
|
- Do not commit secrets or generated local state; use agenix, =pass=, or ignored
|
||||||
|
machine-local files.
|
||||||
Reference in New Issue
Block a user