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
AGENTS.md
+81
View File
@@ -35,3 +35,84 @@ This repository manages the infrastructure, configuration, and maintenance for M
- Global rules: `Rules/`
- Project rules: `.clinerules/`
- Agent instructions: `AGENTS.md` (this file)
# DOX Framework
## Core Contract
- AGENTS.md files are binding work contracts for their subtrees
- Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable AGENTS.md plus every parent AGENTS.md above it
## Read Before Editing
1. Read the root AGENTS.md
2. Identify every file or folder you expect to touch
3. Walk from the repository root to each target path
4. Read every AGENTS.md found along each route
5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there
6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules
7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX
Do not rely on memory. Re-read the applicable DOX chain in the current session before editing.
## Update After Editing
Every meaningful change requires a DOX pass before the task is done.
Update the closest owning AGENTS.md when a change affects:
- purpose, scope, ownership, or responsibilities
- durable structure, contracts, workflows, or operating rules
- required inputs, outputs, permissions, constraints, side effects, or artifacts
- user preferences about behavior, communication, process, organization, or quality
- AGENTS.md creation, deletion, move, rename, or index contents
Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the DOX pass still must happen.
## Hierarchy
- Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index
- Child AGENTS.md files own domain-specific instructions and their own Child DOX Index
- Each parent explains what its direct children cover and what stays owned by the parent
- The closer a doc is to the work, the more specific and practical it must be
## Child Doc Shape
- Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards
- Work Guidance must reflect the current standards of the project or user instructions; if there are no specific standards or instructions yet, leave it empty
- Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists
Default section order:
- Purpose
- Ownership
- Local Contracts
- Work Guidance
- Verification
- Child DOX Index
## Style
- Keep docs concise, current, and operational
- Document stable contracts, not diary entries
- Put broad rules in parent docs and concrete details in child docs
- Prefer direct bullets with explicit names
- Do not duplicate rules across many files unless each scope needs a local version
- Delete stale notes instead of explaining history
- Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist
## Closeout
1. Re-check changed paths against the DOX chain
2. Update nearest owning docs and any affected parents or children
3. Refresh every affected Child DOX Index
4. Remove stale or contradictory text
5. Run existing verification when relevant
6. Report any docs intentionally left unchanged and why
## User Preferences
When the user requests a durable behavior change, record it here or in the relevant child AGENTS.md
## Child DOX Index
No child AGENTS.md files found. The root AGENTS.md covers the entire project scope.
README.md
+7 -10
View File
@@ -8,7 +8,7 @@ tags:
- infrastructure-as-code
- linux
- automation
last_updated: '2026-03-17'
last_updated: '2026-06-17'
---
# saTway® Infrastructure - mw-pfeddersheim-workstation
@@ -34,25 +34,22 @@ bash scripts/daily-routine.sh morning-full
bash scripts/daily-routine.sh eod
```
## 📊 Current Status (2026-03-17)
- **System Health**: ✅ Healthy (Load: 0.40, Disk: 84% used, Memory: 19% used, Swap: 16GB)
- **Active Containers**: 6 running (with memory limits)
- **Network**: Tailscale active
## 📂 Project Structure
| Directory | Purpose |
|-----------|---------|
| `ansible/` | Configuration-as-Code (Roles: `common`, `dev-tools`, `maintenance`) |
| `ansible/` | Configuration-as-Code (Roles: `system-upgrade`, `common`, `dev-tools`, `maintenance`, `fonts`, `pdf`, `hyprland`, `greetd`) |
| `config/` | System configuration templates (`.j2`) |
| `docs/` | PARA-structured documentation (`product`, `adr`, `learnings`, `tech`) |
| `docs/` | PARA-structured documentation (`product`, `adr`, `learnings`, `tech`, `workflows`, `plans`) |
| `scripts/` | Maintenance and automation scripts |
## 🛠 Software Stack
- **Languages**: Node.js 22 LTS, Python 3.12+, PHP 8.4
- **Languages**: Node.js 25.6.1, Python 3.14.3, PHP 8.5.3 (CLI)
- **Automation**: Ansible, Docker
- **Desktop**: Hyprland (Wayland), greetd + tuigreet, Waybar, Kitty
- **Kernel**: linux618 (LTS fallback) + linux70 (daily driver)
- **NVIDIA**: 580xx branch (Pascal/GT 1050 Ti)
- **Environment**: Manjaro/Arch Linux, Bash
## 📜 Core Principles
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
+5 -1
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
@@ -88,3 +88,7 @@ Uptime: ~1 hour, 7 minutes
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)
## 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.