diff options
| -rw-r--r-- | .chezmoiignore | 2 | ||||
| l---------[-rw-r--r--] | .github/copilot-instructions.md | 71 | ||||
| -rw-r--r-- | AGENTS.md | 50 | ||||
| l--------- | CLAUDE.md | 1 |
4 files changed, 47 insertions, 77 deletions
diff --git a/.chezmoiignore b/.chezmoiignore index 2600fd3..997ca33 100644 --- a/.chezmoiignore +++ b/.chezmoiignore @@ -1,6 +1,8 @@ .direnv/ .envrc +.github/ AGENTS.md +CLAUDE.md KEYBINDS.md README.md bootstrap.sh diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index df238ad..be77ac8 100644..120000 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,70 +1 @@ -# Copilot Instructions - -## Execution environment - -You run inside an ephemeral podman container that shares only the current working directory with the host. The container does **not** share the host's installed tools — things like `chezmoi`, `paru`, `pacman`, `sway`, etc. are not available to you unless you install them. You have full root permissions inside the container and can install anything needed for testing or verification. The container is disposable, so don't worry about leaving it in a bad state. This also means you cannot test commands that require the user's actual system state (installed packages, running services, LibreWolf profile, etc.) — those must be verified by the user on the host. - -## Repository overview - -This is a personal dotfiles repository for an Arch Linux system, managed with [chezmoi](https://www.chezmoi.io/). - -## Architecture - -The repo root is a chezmoi source directory. Files targeting `$HOME` use chezmoi naming conventions (`dot_`, `private_`, `executable_` prefixes). Deploy with `chezmoi apply -v`. - -- `dot_config/`, `private_dot_gnupg/`, `private_dot_ssh/`, etc. — chezmoi source state mapping to `$HOME`. Prefix meanings: `dot_` → leading `.`, `private_` → restricted permissions, `executable_` → `+x` bit. -- `etc/` contains system-level configs (`/etc/` targets) — systemd units, pacman hooks, sysctl tunables, kernel module loading. Deployed by `run_onchange_after_deploy-etc.sh.tmpl`. -- `meta/` contains plain text package lists for Arch Linux (one package per line, `#` comments). Each `.txt` file represents a group. The layout is intentionally flat: `base.txt` holds everything universal; the only other groups are truly optional / per-machine — `flatpak.txt` (magic name; per-user flatpak app IDs), `intel.txt`/`nvidia.txt` (hardware-specific), `work.txt`/`btc.txt` (per-machine policy). Install with `just pkg-apply base intel` or `just pkg-apply` (all groups). Detect drift with `just pkg-status` (or `just status` for the aggregate). -- `systemd-units/` contains two flat plain-text files: `system.txt` (enabled via `sudo systemctl`) and `user.txt` (enabled via `systemctl --user`). One unit per line, `#` comments OK. Sibling `system.ignore` / `user.ignore` files suppress distro-default units from `unit-status` uncurated output. Units listed here are enabled by `just unit-apply` (run automatically by `just init`, walks both scopes). Inspect with `just unit-list`, detect drift with `just unit-status`. `just unit-add <unit>...` and `just unit-forget <unit>...` infer scope by probing `systemctl [--user] cat <unit>` — no group/scope argument. -- `firefox/` contains Firefox/LibreWolf hardening overrides (`user-overrides.js`) and custom CSS (`chrome/userChrome.css`). Deployed by `run_onchange_after_deploy-firefox.sh.tmpl`. -- `bootstrap.sh` at the repo root is a POSIX shell script that takes a fresh minimal Arch install (only `base`) to a fully deployed state. It installs prerequisites, enables `%wheel` sudoers, bootstraps `paru-bin` from the AUR, clones the repo, and runs `just init`. On EFI systems missing an Arch boot entry it prints the `efibootmgr` command to register the UKI. Designed to be curlable: `curl -fsSL .../bootstrap.sh | sh`. -- `.chezmoiignore` excludes non-home files (`etc/`, `meta/`, `systemd-units/`, `firefox/`, docs) from deployment to `$HOME`. -- `.githooks/` contains git hooks: `pre-commit` runs `just check` as a code quality gate (bypass with `--no-verify`); `post-commit` runs `chezmoi apply`. Activated by `just init`. -- `justfile` uses a `DOMAIN-VERB` scheme across four domains (`dotfiles`, `etc`, `pkg`, `unit`) with chezmoi-aligned verbs (`add`, `forget`, `re-add`, `apply`, `diff`, `merge`, `status`). Top-level dispatchers (`add`, `forget`, `re-add`, `diff`, `merge`) sniff argument shape and delegate: args containing `/` → path (prefix `/?etc` → etc, else dotfiles); args ending in `.service`/`.timer`/`.socket`/`.mount`/`.target`/`.path` → unit; otherwise bare words → pkg. Full list: `init`, `sync`, `apply`, top-level `add`/`forget`/`re-add`/`diff`/`merge`/`status`; `dotfiles-add`/`forget`/`re-add`/`diff`/`merge`/`status`; `etc-add`/`forget`/`re-add`/`diff`/`merge`/`status`/`reset`/`restore`/`untrack`/`upstream-diff`; `pkg-add`/`forget`/`apply`/`fix`/`list`/`status` + `undeclared`; `unit-add`/`forget`/`apply`/`list`/`status`; `fmt`, `check-fmt`, `lint`, `check`, `doctor`. Run `just` or `just --list` for the menu. - -## Window manager - -Sway (Wayland compositor, i3-compatible). Config lives in `dot_config/sway/config`. Uses vanilla sway defaults for all standard WM operations with personal keybinds layered on top for media, volume, screenshots, lock screen, notifications, and display mode switching. The status bar is waybar (`dot_config/waybar/`), notifications via mako (`dot_config/mako/config`), and the launcher is fuzzel (`dot_config/fuzzel/fuzzel.ini`). - -## Terminal multiplexer - -Zellij is the terminal multiplexer. Config lives in `dot_config/zellij/config.kdl`. Most features are built-in defaults (session resurrection, mouse mode, clipboard). The `vim-zellij-navigator` WASM plugin enables seamless Ctrl h/j/k/l navigation between zellij panes and neovim splits (paired with `smart-splits.nvim` on the neovim side). - -## Shell configuration - -Zsh-only setup with three files: - -- `dot_zshenv` — bootstrap: sets `ZDOTDIR=$HOME/.config/zsh` so all zsh config lives under XDG. -- `dot_config/zsh/dot_zprofile` — login shell: environment variables, XDG dirs, PATH, tool configs, secrets via `pass`. -- `dot_config/zsh/dot_zshrc` — interactive shell: options, completion, keybindings, aliases, plugins. - -Additionally, `dot_config/sh/inputrc` provides readline config for non-zsh tools (python REPL, etc.). - -## Key conventions - -- **XDG compliance**: All tools are configured to respect XDG base directories. History files, caches, and data go to `$XDG_CACHE_HOME`, `$XDG_DATA_HOME`, etc. — never bare `~/` dotfiles when avoidable. -- **`sudo-rs` (memory-safe Rust sudo), not opendoas or the C sudo**: The system uses `sudo-rs` as the privilege escalation tool. The `sudo` package is not installed; `/usr/local/bin/{sudo,su,visudo,sudoedit}` are symlinks to the `sudo-rs` binaries. Sudoers config lives in `/etc/sudoers-rs` (sudo-rs prefers that path over `/etc/sudoers`). -- **GPG-signed commits**: All git commits and tags are signed. The GPG agent also handles SSH authentication. -- **Secrets via `pass`**: API keys and tokens are stored in the `pass` password manager and sourced into env vars at shell init, never hardcoded. -- **EditorConfig**: LF line endings, UTF-8, final newlines, trimmed trailing whitespace. Lua uses 2-space indentation with 80-char line limit. Makefiles use tabs. - -## Editing guidelines - -When modifying configs, use chezmoi naming conventions: `dot_` prefix for dotfiles, `private_` for restricted-permission dirs/files, `executable_` for scripts. To add a new config file, use `chezmoi add <target-path>`. - -The `run_onchange_after_*` scripts are chezmoi templates (`.tmpl`) that embed `sha256sum` hashes of the files they deploy. Chezmoi only re-runs them when file content changes. Both the `etc` and `firefox` deploy scripts auto-enumerate every file under their respective directories (single combined hash via chezmoi's `output` function + `find`); just drop new files into `etc/` or `firefox/` and they'll be deployed on next `chezmoi apply`. - -When editing shell config, all zsh configuration goes in `dot_config/zsh/` — do not create files in `dot_config/sh/` (only `inputrc` remains there). - -## Keybinds reference - -`KEYBINDS.md` at the repository root documents every non-default keybind across neovim, zellij, zsh, ghostty, and sway. Whenever you add, remove, or change a keybind in any of these tools, you must update `KEYBINDS.md` to reflect the change in the same commit. - -## VM chezmoi role - -The remote-dev Ubuntu VM also runs chezmoi. Home-Manager installs packages and VM session variables only; it must not deploy normal dotfiles. Machine-specific dotfile behavior belongs in chezmoi templates keyed by `machineRole`: - -- `host`: user dotfiles plus host-only `/etc`, Firefox/LibreWolf, and Flatpak integration hooks. -- `vm`: user dotfiles, skipping host-only `/etc` and Firefox/LibreWolf hooks. - -When adding, removing, or renaming user config under `dot_config/`, `dot_claude/`, `private_dot_ssh/`, `private_dot_gnupg/`, etc., use chezmoi naming conventions only. Do not add corresponding `xdg.configFile` or `home.file` mappings to `nix/vm.nix`. +../AGENTS.md
\ No newline at end of file @@ -1,13 +1,49 @@ -# Agent Notes +# Dotfiles Repository Notes -- Keep comments in config files operational. Prefer section labels and short - purpose notes; avoid migration history or explanations that only justify an - old decision. -- Package placement: pacman owns system-coupled pieces; Home-Manager owns - user-leaf tools; project compilers/linkers belong in per-project Nix dev - shells via direnv. +This is a personal dotfiles repository for an Arch Linux host and an Ubuntu +remote-dev VM. The repo root is a chezmoi source directory. + +## Layout + +- Home-directory targets use chezmoi naming conventions: `dot_` for leading + dots, `private_` for restricted permissions, and `executable_` for scripts. +- `etc/` contains host `/etc` source files deployed by the repo's onchange + script. +- `meta/` contains flat package lists. Keep one package per line and use short + comments only when they help future maintenance. +- `systemd-units/` tracks enabled system and user units in plain text. +- `firefox/` and `thunderbird/` hold browser and mail profile source files. +- `nix/` owns Home-Manager profiles and the repo development shell. +- `.githooks/` contains hooks installed by the repo recipes. + +## Package Ownership + +- Pacman owns system-coupled pieces. +- Home-Manager owns user-leaf tools. +- Project compilers, linkers, and language runtimes belong in per-project Nix + dev shells via direnv. - Do not add global Home-Manager packages that shadow the system build toolchain (`gcc`, `clang`, `ld`, `make`, `pkg-config`, language runtimes, etc.) unless the user explicitly asks for that tradeoff. - On the Arch host, keep GPU/OpenGL Wayland apps in pacman unless they have been smoke-tested from Nix against the host graphics stack. + +## Chezmoi Roles + +- `host`: user dotfiles plus host-only `/etc`, Firefox/LibreWolf, and Flatpak + integration hooks. +- `vm`: user dotfiles, skipping host-only `/etc` and Firefox/LibreWolf hooks. +- Machine-specific dotfile behavior belongs in chezmoi templates keyed by + `machineRole`. +- The VM Home-Manager profile installs packages and session variables only. Do + not add ordinary dotfiles to `xdg.configFile` or `home.file` in `nix/vm.nix`. + +## Config Conventions + +- Keep comments in config files operational. Prefer section labels and short + purpose notes over migration history. +- Add new user config through chezmoi source naming. +- Zsh config lives in `dot_config/zsh/` and `dot_zshenv`. Do not add new shell + config under `dot_config/sh/`; only `inputrc` belongs there. +- `KEYBINDS.md` documents non-default keybinds across neovim, zellij, zsh, + ghostty, and sway. Update it in the same change when keybinds change. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md
\ No newline at end of file |