infrastructure/mw-pfeddersheim-workstation
2
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

doxify: inject DOX framework into AGENTS.md and update system config docs

Browse Source 
- Inject all 10 DOX sections into root AGENTS.md (Core Contract, Read Before
  Editing, Update After Editing, Hierarchy, Child Doc Shape, Style, Closeout,
  User Preferences, Child DOX Index)
- Update ADR 0002: linux612->linux618, 575xx->580xx NVIDIA migration
- Update setup.md: kernel/driver refs to current linux618 + 580xx
- Update stack.md, hardware-inventory.md: NVIDIA note 595.71->580xx
- Update manual-overrides.md: add br_vm_internal bridge deletion entry
- Update workstation-health.md: add Recent Cleanup section
- Update README.md: current software versions, expand roles list
- Add docs/neovim-cheatsheet.md
- Bump last_updated to 2026-06-17 on all modified docs
This commit is contained in:
ja
2026-06-17 14:13:34 +02:00
parent de24990208
commit d9392447f9
9 changed files with 203 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/adr/0002-kernel-and-nvidia-strategy.md
+36 -24
View File
@@ -1,7 +1,7 @@
---
description: >-
Decision to dual-install linux612 (LTS) + linux70 (stable) kernels and
migrate NVIDIA from the pinned 575xx branch to the mainline 595.71 branch
Decision to dual-install linux618 (LTS) + linux70 (stable) kernels and
migrate NVIDIA from the pinned 575xx branch to the 580xx branch (NFB)
to prepare the workstation for Hyprland/Wayland.
tags:
- adr
@@ -9,13 +9,13 @@ tags:
- nvidia
- hyprland
- wayland
last_updated: '2026-05-18'
last_updated: '2026-06-17'
---
# ADR 2: Kernel and NVIDIA Driver Strategy for Hyprland/Wayland
## Status
Accepted (2026-05-18)
Accepted (2026-05-18) — Updated (2026-06-17)
## Context
The workstation runs Manjaro Linux on AMD Ryzen 7 2700X with an NVIDIA
@@ -25,14 +25,14 @@ Wayland. Two preconditions must hold before that switch is safe:
1. **DRM/atomic and NVIDIA explicit-sync support** — Hyprland on NVIDIA
relies on driver-level explicit sync (introduced in 555.x and matured
through 575.x and 595.x). Without it, flickering and missed vblanks
through 575.x, 580.x, and 595.x). Without it, flickering and missed vblanks
are very common on Pascal+multi-monitor.
2. **Matching kernel modules** — Manjaro ships pre-built `*-nvidia`
modules pinned to a single `nvidia-utils` version. Mixing `575xx`
userspace with a kernel that only has `595.71` modules (or vice
userspace with a kernel that only has `580xx` modules (or vice
versa) breaks the driver at the next kernel boot.
The starting point at the time of this ADR:
The starting point at the time of this ADR (2026-05-18):
| Item | Version |
|---------------------------|------------------------|
@@ -43,17 +43,29 @@ The starting point at the time of this ADR:
| `linux70-nvidia` available | `595.71.05-0.1` |
| `linux612-nvidia` (mainline) | `595.71.05-2` |
Current state (2026-06-17):
| Item | Version |
|---------------------------|------------------------|
| Kernel packages | `linux618`, `linux70` |
| NVIDIA driver branch | `580xx` (NVIDIA Fast Branch) |
| NVIDIA kernel module pkg | `linux618-nvidia-580xx`, `linux70-nvidia-580xx` |
| NVIDIA userspace packages | `nvidia-580xx-utils`, `lib32-nvidia-580xx-utils`, `opencl-nvidia-580xx`, `nvidia-580xx-settings` |
| Legacy packages removed | `*-nvidia-575xx` family (see `nvidia_packages_to_remove`) |
## Decision
1. **Run two kernels side by side.**
- Keep `linux612` (LTS 6.12.x) installed as the *fallback* boot entry.
- Keep `linux618` (LTS 6.18.x) installed as the *fallback* boot entry.
- Install `linux70` (stable 7.0.x) and select it as the daily-driver
kernel via GRUB at the next reboot.
2. **Migrate NVIDIA from the `575xx` branch to mainline `595.71`** in
2. **Migrate NVIDIA from the `575xx` branch to `580xx` (NVIDIA Fast Branch)** in
one atomic pacman transaction so both kernels have matching modules:
- Remove: `linux612-nvidia-575xx`, `nvidia-575xx-utils`,
`lib32-nvidia-575xx-utils`, `nvidia-575xx-settings`.
- Install: `linux612-nvidia`, `linux70-nvidia`, `nvidia-utils`,
`lib32-nvidia-utils`, `opencl-nvidia`, `nvidia-settings`.
`lib32-nvidia-575xx-utils`, `nvidia-575xx-settings`,
and the entire `*-nvidia-575xx` family.
- Install: `linux618-nvidia-580xx`, `linux70-nvidia-580xx`,
`nvidia-580xx-utils`, `lib32-nvidia-580xx-utils`,
`opencl-nvidia-580xx`, `nvidia-580xx-settings`.
3. **Do not change `GRUB_DEFAULT` programmatically.** The user picks
`linux70` from the GRUB menu on first boot. If `linux70` misbehaves,
the next reboot is one menu selection away from the proven LTS path.
@@ -63,17 +75,18 @@ The starting point at the time of this ADR:
`--tags system-upgrade` and is safe on every subsequent run.
## Rationale
- **LTS as a parachute.** 6.12 is a Linux LTS series with a multi-year
- **LTS as a parachute.** 6.18 is a Linux LTS series with a multi-year
support window. Keeping it installed makes the migration reversible by
one keystroke in GRUB.
- **7.0 as the daily driver.** The 7.0 series brings the maturest
DRM/atomic-modeset and NVIDIA explicit-sync paths that Hyprland on
Pascal needs to avoid flicker on multi-monitor.
- **Mainline 595.71 over pinned 575.64.05.** Manjaro builds
`linux70-nvidia` only against `nvidia-utils=595.71.05`, so the 575xx
- **580xx over 595.71.** The NVIDIA Fast Branch (580xx) provides newer
driver improvements while maintaining backward compatibility. Manjaro
builds `linux70-nvidia` against `nvidia-580xx-utils`, so the 575xx
branch is not an option for the new kernel. Pascal (GP107) is fully
supported by 595.x, and 595.x ships the latest explicit-sync /
modesetting fixes upstream.
supported by 580.x, which ships explicit-sync / modesetting fixes
upstream.
- **Single atomic transaction.** Removing the old branch and installing
the new one in one pacman call (with the removal list narrowed to
packages that are *actually* installed) keeps the GPU-driver window
@@ -85,24 +98,23 @@ The starting point at the time of this ADR:
## Consequences
- **Two kernels on `/` partition.** Roughly +120 MB for `linux70` plus
~50 MB for `linux70-nvidia`. The role pre-flight refuses to start if
~50 MB for `linux70-nvidia-580xx`. The role pre-flight refuses to start if
free space on `/` is below 5 GiB.
- **`mhwd` profile referencing `575xx` stays as-is.** Only the
kernel-bound `linux612-nvidia-575xx` and matching userspace are
swapped; `mhwd-nvidia-575xx` stays installed so MHWD's profile
listing remains consistent. A future cleanup can switch the MHWD
profile to `video-nvidia` once `linux70` is verified.
kernel-bound `linux618-nvidia-580xx` and matching userspace are
installed; legacy `*-nvidia-575xx` packages are removed.
- **Manual reboot required.** The role never reboots the machine; it
ends with a clear notice instructing the user to boot into `linux70`
from GRUB before applying the next (Hyprland) playbook.
- **Future kernel pin bumps are one-line changes** in
- **Future kernel/driver pin bumps are one-line changes** in
`ansible/vars/main.yml` (`kernel_packages` /
`nvidia_kernel_modules` lists).
`nvidia_kernel_modules` / `nvidia_userspace_packages` lists).
## References
- Hyprland NVIDIA notes (wiki.hypr.land/Nvidia): explicit sync
available from driver ≥555 and required for tear-free Wayland.
- `docs/tech/hardware-inventory.md` (NVIDIA section).
- `ansible/roles/system-upgrade/tasks/main.yml`.
- `ansible/vars/main.yml` (current kernel and NVIDIA package pins).
- ADR 1: `docs/adr/0001-use-ansible-for-configuration.md` — anchors the
"Ansible-first" guardrail this decision follows.
docs/neovim-cheatsheet.md
+64
View File
@@ -0,0 +1,64 @@
---
title: "Neovim v0.12.2 Cheatsheet"
author: "mw-pfeddersheim-workstation"
date: "June 2026"
---
# Neovim Cheatsheet
**Version:** v0.12.2 (LuaJIT 2.1) **Config:** `~/.config/nvim/init.lua`
## Search
### Buffer Search (current file)
| Command | Action |
|---------|--------|
| `/pattern` | Search forward |
| `?pattern` | Search backward |
| `n` | Next match (forward) |
| `N` | Previous match (backward) |
### File Search (across files)
| Command | Action |
|---------|--------|
| `:grep pattern` | Search current directory with ripgrep |
| `:grep pattern /path/to/dir` | Search specific directory |
| `:cfirst` | Jump to first match |
| `:cnext` / `:cprev` | Next / previous match |
| `:copen` | Open quickfix window with all results |
| `:cclose` | Close quickfix window |
## Editing
| Command | Action |
|---------|--------|
| `D` | Delete from cursor to end of line |
| `d$` | Delete to end of line (same as `D`) |
| `dd` | Delete entire line |
| `C` | Change from cursor to end of line (delete + insert mode) |
## Text Objects
Delete or operate on structured text by type:
| Command | Action |
|---------|--------|
| `di{` | Delete **inside** `{}` (keeps braces) |
| `da{` | Delete **a** `{}` (removes braces too) |
| `di"` | Delete inside double quotes |
| `da"` | Delete a double-quoted section |
| `di(` | Delete inside parentheses |
| `da(` | Delete a parenthesized section |
| `di[` | Delete inside brackets |
| `da[` | Delete a bracketed section |
| `di<` | Delete inside angle brackets |
| `da<` | Delete an angle-bracketed section |
**Pattern:** `d` (delete) + `i` (inside) / `a` (around) + `{type}`
**Also works with:**
- `v` + text object — select (e.g. `vi{` selects inside braces)
- `y` + text object — yank/copy (e.g. `ya{` copies including braces)
- `c` + text object — change (e.g. `ci{` deletes + enters insert mode)
docs/tech/hardware-inventory.md
+2 -2
View File
@@ -105,8 +105,8 @@ last_updated: '2026-04-02'
| PCI Address | 08:00.0 |
> **Driver strategy**: This Pascal-generation GPU is being migrated from the
> pinned Manjaro `*-nvidia-575xx` branch to the mainline `*-nvidia` 595.71
> branch as part of the Hyprland/Wayland preparation. The migration is
> pinned Manjaro `*-nvidia-575xx` branch to `*-nvidia-580xx` (NVIDIA Fast Branch)
> as part of the Hyprland/Wayland preparation. The migration is
> automated by the `system-upgrade` Ansible role and documented in
> [ADR 0002 — Kernel and NVIDIA Driver Strategy for Hyprland/Wayland](../adr/0002-kernel-and-nvidia-strategy.md).
docs/tech/manual-overrides.md
+2 -1
View File
@@ -6,7 +6,7 @@ tags:
- manual-overrides
- infrastructure
- configuration
last_updated: '2026-03-09'
last_updated: '2026-06-17'
---
# Manual System Overrides
@@ -22,4 +22,5 @@ This document tracks all persistent system changes implemented manually that are
| Date | Change | Rationale | Ansible Status |
|------|--------|-----------|----------------|
| 2026-06-17 | Discovered and deleted `br_vm_internal` bridge (10.10.2.0/24) | Externally-created bridge, no NM config file, no VMs attached. Origin unknown — likely ad-hoc `nmcli con add` or manual `brctl` session (Jun 10). Traffic-shaping qdisc (`htb`) suggests prior VM network isolation attempt. Deleted via `nmcli con delete` + `ip link delete`. | N/A (removed) |
| 2026-04-02 | Moved LLM models to `/home/mw/models/` (SATA SSD) with symlinks | Free root NVMe space (93%→87%, +25G freed) | Not yet |
docs/tech/setup.md
+4 -4
View File
@@ -5,7 +5,7 @@ tags:
- setup
- bootstrap
- ansible
last_updated: '2026-05-20'
last_updated: '2026-06-17'
---
# Workstation Setup Guide
@@ -44,8 +44,8 @@ This guide describes how to bootstrap the **mw-pfeddersheim-workstation** infras
4. **Run system upgrade & kernel install** (preparation for Hyprland/Wayland)
This step runs the dedicated `system-upgrade` role: full `pacman -Syu`,
dual-kernel install (`linux612` LTS + `linux70` stable), and NVIDIA
driver migration from the pinned `575xx` branch to mainline `595.71`.
dual-kernel install (`linux618` LTS + `linux70` stable), and NVIDIA
driver migration from the pinned `575xx` branch to `580xx` (NVIDIA Fast Branch).
Always preview first with `--check`. See
[ADR 0002](../adr/0002-kernel-and-nvidia-strategy.md) for the rationale.
@@ -63,7 +63,7 @@ This guide describes how to bootstrap the **mw-pfeddersheim-workstation** infras
After it finishes, **reboot and select `linux70` from the GRUB menu**
before continuing to step 5. Verify with `uname -r` (expect 7.0.x)
and `nvidia-smi` (expect driver 595.71.05).
and `nvidia-smi` (expect driver 580.x).
5. **Run the Playbook** (remaining roles: common, dev-tools, maintenance)
```bash
docs/tech/stack.md
+1 -1
View File
@@ -6,7 +6,7 @@ tags:
- software-stack
- inventory
- tech-stack
last_updated: '2026-05-22'
last_updated: '2026-06-17'
---
# Software Stack - mw-pfeddersheim-workstation
docs/tech/workstation-health.md
+6 -2
View File
@@ -7,7 +7,7 @@ tags:
- health-check
- workstation
- monitoring
last_updated: '2026-03-17'
last_updated: '2026-06-17'
---
# Workstation Health Report: mw-manjaro-pf
@@ -87,4 +87,8 @@ Uptime: ~1 hour, 7 minutes
## Next Steps
1. Consider setting up automated crash monitoring for high-memory applications
2. Run health check script manually as needed: `/home/mw/internal/mw-pfeddersheim-workstation/scripts/morning-health-check.sh` (automated systemd timer removed 2026-05-26)
2. Run health check script manually as needed: `/home/mw/internal/mw-pfeddersheim-workstation/scripts/morning-health-check.sh` (automated systemd timer removed 2026-05-26)
## Recent Cleanup (2026-06-17)
- **Externally-created bridge `br_vm_internal` (10.10.2.0/24)** discovered and removed. No NM config file, no libvirt network, no attached VMs. Origin traced to Jun 10 2026 (first activation) — likely ad-hoc CLI creation. Bridge had `htb` qdisc suggesting prior VM network isolation attempt. Both the NM connection and kernel interface fully deleted.