sam_oneal/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme with current packages; add AGENTS.md for AI guidance

Browse Source
This commit is contained in:
Samuel ONeal
2026-08-14 21:35:27 -06:00
parent 804ec54090
commit 260b202d6f
2 changed files with 150 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+74
View File
@@ -0,0 +1,74 @@
# AGENTS.md
Guidance for AI agents (and humans) working on this repo. This file documents
how AI assistance has been used on this project and the expectations for future
sessions.
## What this repo is
A set of GNU-stow packages containing the user's machine configuration
(Hyprland desktop, terminal, shell, systemd units, scripts, wallpapers). Each
top-level directory is a stow package rooted at `$HOME` (or `/` for system
dirs like `etc`). See `README.md` for the full package table and quick start.
## How AI has been used here
All prior work is captured in session transcripts under
`resources/ai/sessions/`. The main efforts so far:
- **Hyprland migration to Lua** (`session-ses_ffd7.md`): converted the
hyprlang `.conf` configs to Lua configs for Hyprland 0.56.2, migrated
plugins and themes (Catppuccin Mocha palette lives in `hyprmocha/`).
- **uwsm/sddm sign-in debugging** (`session-ses_ffd3.md`): diagnosed why the
uwsm Hyprland session would not allow sign-in; added a `sudo-askpass.sh`
(zenity prompt via `SUDO_ASKPASS`) and disabled linger.
- **Performance work** (`session-ses_ffcb.md`): profiled Hyprland CPU usage,
identified the animated `borderangle` loop as the culprit; added mako
notifications and waybar modules.
- **Monitor management** (`session-ses_ffc9.md`): adopted
[monique](https://github.com/notwidow/monique) for arranging multiple
monitors, including clamshell mode and the `hypr-lid-power` service
(`hyprland/.config/systemd/user/hypr-lid-power.service`).
- **Cloudflare tunnel + secrets** (`session-ses_0098.md`): wired the
`cloudflared-k8s` service to pull the Cloudflare Access service token from
the Homelab 1Password vault at runtime via `op run` — it is never written to
disk.
## Rules for agents
1. **Never commit secrets.** No API keys, tokens, passwords, or private keys
may be committed. Use 1Password references (`op://Vault/Item/...`) and
inject at runtime with `op run -- ...`. `.secrets.baseline` + `detect-secrets`
(via pre-commit) is the guardrail; keep it updated (`detect-secrets scan`
and re-baseline if a benign false positive is added).
2. **Fit every change into the stow layout.** Config files must live under a
package directory mirroring their destination (e.g. a new app config goes
under `<pkg>/.config/<app>/`). After changes, the package must be
committable and stowable (`make link` / `make unlink` must keep working).
3. **`resources/` is untracked and must stay untracked.** Session transcripts
under `resources/ai/sessions/` can contain sensitive values (e.g. a
Cloudflare client secret shown during a session). Do not stage, add, or
commit anything under `resources/`. Note `wluma/` is likewise local-only.
4. **Hyprland config is Lua, not hyprlang.** All `hyprland/.config/hypr/`
configs are `.lua` files driven by `hyprland.lua`. Do not reintroduce
`.conf`/hyprlang syntax.
5. **`nvim/` is a private submodule** pointing at a self-hosted Gitea/GitLab
repo; never replace it with a public fork and don't commit submodule state
changes unless intended. Pull with `make pull-updates`.
6. **Behave like the user's own assistant on this machine.** These dotfiles
reference real hosts (`sams_laptop`, `k8s.samoneal.io`, `git-ssh.samoneal.io`)
and real 1Password vaults — work with them, but keep the repo portable by
leaving secrets and machine-specific absolute paths in comments rather than
committed values where practical.
7. **Verify before finishing.** Run `git status`/`git diff` to confirm only
intended files changed and nothing sensitive is staged. If unsure whether a
value is a secret, treat it as one.
## Workflow
- Pre-commit hooks: `pre-commit install` (runs trailing-whitespace +
detect-secrets).
- Lint/typecheck: this repo is plain config + shell; shell scripts should stay
`sh`/`bash`-compatible and pass `shellcheck` if available.
- Record substantial AI sessions: if a session materially changes this repo,
save the transcript under `resources/ai/sessions/` (keep it untracked).
README.md
+76 -10
View File
@@ -1,14 +1,80 @@
# Dotfiles
All the configuration files for my current machine setup.
All the configuration files for my current machine setup. Managed with GNU
stow so every package maps directly onto the relevant `~/.config`, `~/.local`,
`/etc`, etc. paths.
## Configurations
## Requirements
- Ghostty
- Hyprland
- Local
- Monique
- NVIM
- SSH
- SystemD
- ZSH
- [GNU stow](https://www.gnu.org/software/stow/)
- `make`
- [op (1Password CLI)](https://developer.1password.com/docs/cli/) for anything
that needs a secret
## Quick start
```sh
# Install stow if missing (auto-detects Arch/Debian/macOS)
make check-stow
# Link every package into $HOME (system dirs like /etc are stowed with sudo)
make link
# Unlink everything again
make unlink
# Pull main plus submodules
make pull-updates
```
## Packages
| Package | Path | Description |
| ----------- | -------------- | ------------------------------------------------------- |
| `backgrounds` | `~/.config/backgrounds` | Wallpaper collection (incl. Dynamic-Wallpapers) |
| `ghostty` | `~/.config/ghostty` | Ghostty terminal config |
| `hosts` | `~/.config/hosts` | Custom `HOSTALIASES` file (`HOSTALIASES=~/.config/hosts`) |
| `hyprland` | `~/.config/hypr`, `~/.local/bin` | Hyprland config (Lua), scripts, `hypr-lid-power` service |
| `hyprlock` | `~/.config/hypr` | Lockscreen config |
| `hyprmocha` | `~/.config/hypr` | Catppuccin Mocha palette as Lua |
| `hyprpaper` | `~/.config/hypr` | Wallpaper daemon config |
| `hyprshell` | `~/.config/hyprshell` | Launcher/overview (Rust, RON config + CSS) |
| `local` | `~/.local/bin` | Local scripts (e.g. `fetch-nas-credentials.sh`) |
| `mako` | `~/.config/mako` | Notifications |
| `monique` | `~/.config/monique` | Monitor/clamshell arrangement |
| `nvim` | `~/.config/nvim` | Git submodule (private repo) |
| `rofi` | `~/.config/rofi` | Launcher (Catppuccin Mocha) |
| `ssh` | `~/.ssh/config` | SSH config (1Password agent + cloudflared proxy) |
| `sunsetr` | `~/.config/sunsetr` | Screen color temperature (`geo.toml` is gitignored) |
| `systemd` | `~/.config/systemd/user`, `/etc/systemd` | User + system units (cloudflared, rclone/GDrive, NAS mounts, 1Password sign-in) |
| `waybar` | `~/.config/waybar` | Top bar |
| `wofi` | `~/.config/wofi` | App menu |
| `yay` | `~/.config/yay` | AUR helper config |
| `zsh` | `~/.zshrc` | Zsh config |
`wluma/` and `resources/` exist locally but are **not** committed (see
`AGENTS.md`).
## Secrets management
No secrets are committed to this repo. Anything secret goes through
[1Password](https://1password.com):
- References look like `op://Vault/Item/field[/section]` (e.g. the Cloudflare
service token in `systemd/.config/systemd/user/cloudflared-k8s.service`).
- Services inject secrets at runtime with `op run -- ...`, so values never hit
disk or git.
- `fetch-nas-credentials.sh` writes fetched NAS credentials to
`~/.nas/.smbcredentials` (chmod 600) at boot.
- `detect-secrets` runs via `pre-commit` against `.secrets.baseline`.
## Submodules
- `nvim/.config/nvim` → `git@git-ssh.samoneal.io:2222/sam_oneal/nvim-config.git`
(private). Pull with `make pull-updates`.
## AI assistance
This repo is developed with AI assistance. See `AGENTS.md` for how AI has been
used, the conventions it must follow, and where session transcripts are kept
(`resources/ai/sessions/`).