Appendix: Issues Encountered

Issues Encountered

Problems hit during deployment and their resolutions:

Phase Issue Resolution

Phase	Issue	Resolution
0	`cp` to USB: permission denied	`sudo mount` without `uid/gid` flags — remount with `-o uid=$(id -u),gid=$(id -g)`
0	NFS mount hung on `nas-02`	Wrong hostname — `nas-01.inside.domusdigitalis.dev` is correct
1	DataConnect SQL `ORA-00904: invalid identifier`	Wrong column names (`CALLING_STATION_ID` etc.) — validated from codex: `mac_address`, `timestamp`, `passed`
2	`mkdir -p /mnt/\{boot/efi,…}` then mount ext4 on `/mnt/boot` — efi dir disappears	ext4 mount overlays btrfs. Create `efi/` AFTER mounting `/boot`: `mkdir -p /mnt/boot/efi`
4	ext4 `/boot` — systemd-boot "reboot to firmware" loop	Boot Loader Spec requires VFAT for XBOOTLDR. Entries + kernels must be on same partition. Fix: everything on ESP.
4	`efibootmgr` needed to register boot entry	ThinkPad didn’t auto-detect systemd-boot binary
4	Fallback preset not generating images	Arch ships with fallback commented out. Uncomment `PRESETS`, `fallback_image`, `fallback_options` in presets.
4	Boot entries at wrong path (`/boot/loader/entries/`)	`bootctl --boot-path=/boot` creates entries on ext4. Remove `--boot-path`, entries go on ESP.
4	512M ESP ran out of space copying all 4 initramfs	Only copy default images (no fallback). Fallback stays on ext4 `/boot` only.
6	`nvidia-smi` fails after install	Kernel module not loaded — must reboot. Also must sync new initramfs to ESP.
6	`nvidia` package not found	RTX 5090 requires `nvidia-open` (open kernel module), not proprietary `nvidia`.
7	iPSK VLAN blocks outbound port 22	Use `ssh.github.com:443` with `-l git`. Goes away after EAP-TLS on DOMUS-Secure.
7	stow conflicts with default shell configs	`rm -f ~/.bashrc ~/.bash_profile ~/.zshrc` before stowing
7	GPG database locked after rsync	Stale lock files from source. `find ~/.gnupg -name "*.lock" -delete && gpgconf --kill all`
7	gopass "not initialized" after rsync	Config references `~/.password-store` (legacy). Fix: `sed -i` to point at `~/.local/share/gopass/stores/root`
7	gopass `-c` (clipboard) fails over SSH	No clipboard daemon. Use `gopass show -f` to print to console.
7	rsync from Razer fails — password denied	Razer SSH config `Host *` forces pubkey-only. Use `-e "ssh -F /dev/null"`. Also enable `KbdInteractiveAuthentication` and `PasswordAuthentication` on target.
7	`sshd_config` sed didn’t match — password auth still `yes`	Line was `PasswordAuthentication yes` (commented). Use `s/^\?PasswordAuthentication.*/PasswordAuthentication no/`
7	nvim opens blank despite correct `~/.config/nvim` symlink	`.zshrc` exports `NVIM_APPNAME="nvim-domus"`. nvim looks at `~/.config/nvim-domus/`, not `~/.config/nvim/`.
7	dots-quantum missing `gpg/`, `hosts/`, `secrets/` packages	Gitignored private packages. Must scp/rsync separately from source machine.
7	SSH to Razer from P16g fails — pubkey denied	P16g’s key not in Razer’s `authorized_keys`. Added pub key manually. Proper fix: Vault SSH certs.
7	git clone remote URL set to port 443 format	Cloned with `ssh://ssh.github.com:443/` on iPSK. After moving to DOMUS-Secure: `git remote set-url origin git@github.com:user/repo.git`
8b	Vault cert issued with wrong hostname (`modestus-razer`)	`$(cat /etc/hostname)` on Razer returns Razer’s name. Must `HOSTNAME="modestus-p16g"` explicitly.
8b	Hostname set as `modestus-t16g` (wrong model)	Machine is P16g Gen 3, not T16g. `hostnamectl set-hostname modestus-p16g` + sed `/etc/hosts`.
7	GPG "No pinentry" — `pinentry-qt` missing `libKF6GuiAddons.so.6`	`kguiaddons` package not installed. Use `ldd /usr/bin/pinentry-qt \| grep "not found"` to find ALL missing deps at once, then `pacman -Qo` on a working machine to find package names.
7	GPG pinentry-qt prompts on desktop instead of SSH terminal	`gpg-agent` inherits `WAYLAND_DISPLAY` from desktop. `pinentry-auto` script checks `SSH_CONNECTION` first. Also need `gpg-connect-agent updatestartuptty /bye` on SSH login (added to `.zshrc`).
7	`env-gpu.conf` symlink in repo points to `hosts/razer/` — breaks on P16g	Per-host config committed as symlink to Razer. Fix: gitignore `hyprland/.config/hypr/env-gpu.conf`, each machine symlinks to its own `hosts/<hostname>/env-gpu.conf` manually.
4	ACPI interrupt storm — `gpe6E` firing 4.7M times, CPU at 84C idle	`acpi_mask_gpe=0x6E` kernel parameter masks the rogue GPE. Added to all boot entries. CPU dropped to 41C after reboot.
8b	`nmcli connection down` over SSH kills the WiFi link — SSH session dies, `connection up` never runs	NEVER bounce WiFi from an SSH session over that same WiFi. Run locally from the P16g desktop, or write to `/tmp/bounce-wifi.sh` over SSH and execute it from the local terminal. `nohup` with sleep also works but risky.
7	SSH config had wrong IPs for hosts	`modestus-razer` had `10.50.10.111` but actual IP is `10.50.1.106`. Verify IPs before encrypting: `ip -4 -o addr show \| awk '$2!="lo" \{print $2, $4}'`. Fix with `sed -i '/Host modestus-razer$/,/^$/s/HostName OLD/HostName NEW/'`. Re-encrypt + push + pull + decrypt on all machines.
7	`age -d … > file` fails with `zsh: file exists`	zsh `noclobber` prevents overwriting. Use `>\|` (force overwrite): `age -d -i key config.age >\| config`
7	`~/.ssh/sockets/` directory missing on P16g	SSH config uses `ControlPath ~/.ssh/sockets/…` but directory wasn’t created. `mkdir -p ~/.ssh/sockets` before first SSH.
7	stow audit script misses `share` package — shows X when stowed	`share` stows to `~/.local/share/awk/`, `sed/`, etc. at depth 4. Audit `find` uses `maxdepth 2` — change to `maxdepth 4` for accurate results.
7	`hosts`, `gpg`, `secrets` are NOT stow packages	`stow -t ~ hosts` creates wrong-level symlinks (`~/razer/`, `~/x1/`, `~/aw/`). These are per-host config containers — use manual symlinks only. `secrets` is a separate git repo at `~/.secrets/`.
7	`gcvault` (gocryptfs vault manager) not deployed	Entire `~/atelier/_vaults/` directory needs rsync from Razer. Contains 4 vaults: credentials, work-sensitive, network-configs, personal. Symlinks from `~/.config/gh` and `~/.claude/credentials.json` point into mounted vault.
7	SSH between P16g (VLAN 10) and Razer (VLAN 1) — connection hangs	Different subnets with no inter-VLAN routing by design (anti-pivot security). Administrators with EAP-TLS certs connect to VLAN 100 (management VLAN) which has routing to infrastructure VLANs. Need to verify Razer’s cert + ISE authorization profile assigns the correct VLAN for cross-VLAN SSH access.
9	`make` fails — `Cannot find module '@antora/lunr-extension'`	Fresh clone has no `node_modules/` (gitignored). `npx antora` auto-installs antora itself but not extensions from `package.json`. Fix: `npm install` in each domus-* repo after cloning. Not documented in any phase.
9	AsciiDoc validation not running on terminal commits	Claude Code hooks (PostToolUse in `~/.claude/settings.json`) only fire inside Claude Code sessions. Terminal `gach`/`git commit` bypasses validation entirely. No git-level pre-commit hook exists — `.git/hooks/` only contains `.sample` files. `core.hooksPath` not configured. dots-quantum `git` stow package has no hooks directory.
11	No Mandatory Access Control — AppArmor not installed or enabled	Discovered Apr 4 during domus-digitalis setup audit. Arch kernel has `CONFIG_SECURITY_APPARMOR=y` but it’s not enabled at boot. All user processes have unrestricted access to `~/.secrets/`, `~/.gnupg/`, `~/.age/`, gopass stores. Fix applied Apr 5: `pacman -S apparmor`, boot params updated on all 3 entries with `lsm=…apparmor,bpf apparmor=1 security=apparmor`, also restored missing `acpi_mask_gpe=0x6E` on fallback + LTS. `apparmor.service` enabled. Pending reboot. Now tracked as Phase 12. INC-2026-04-04-002. CR: AppArmor.
9	`make serve` fails — `docker: command not found`	Kroki diagram server requires Docker or Podman. Neither installed on P16g. `make serve` proceeds past the error but diagrams won’t render.
9	`make serve` fails — UI bundle not found	`domus-antora-ui` repo was cloned but `build/ui-bundle.zip` never built. Fix: `cd ~/atelier/_bibliotheca/domus-antora-ui && npm install && npx gulp bundle`. Note: `npx --prefix` does NOT change cwd for gulp — must `cd` into the repo first.
9	`lsof: command not found` during `make serve`	Makefile uses `lsof -ti:8000 \| xargs -r kill -9` to kill stale servers. `lsof` not installed on fresh Arch. Non-fatal but noisy. Fix: `sudo pacman -S lsof`.
12	AppArmor boot params not active after reboot — `aa-enabled` returns `No`	CR-2026-04-04 sed commands targeted `/boot/loader/entries/` (ext4 shadow) instead of `/boot/efi/loader/entries/` (ESP — what systemd-boot actually reads). Boot entries on ext4 had correct params but kernel never received them. This is the same Phase 4 deviation (entries must live on ESP VFAT) manifesting again. Fix: variable-driven idempotent patch targeting `ESP_ENTRIES="/boot/efi/loader/entries"` with `GUARD="apparmor=1"` check. See Phase 12 for the corrected commands.

cp to USB: permission denied

sudo mount without uid/gid flags — remount with -o uid=$(id -u),gid=$(id -g)

NFS mount hung on nas-02

Wrong hostname — nas-01.inside.domusdigitalis.dev is correct

DataConnect SQL ORA-00904: invalid identifier

Wrong column names (CALLING_STATION_ID etc.) — validated from codex: mac_address, timestamp, passed

mkdir -p /mnt/\{boot/efi,…} then mount ext4 on /mnt/boot — efi dir disappears

ext4 mount overlays btrfs. Create efi/ AFTER mounting /boot: mkdir -p /mnt/boot/efi

ext4 /boot — systemd-boot "reboot to firmware" loop

Boot Loader Spec requires VFAT for XBOOTLDR. Entries + kernels must be on same partition. Fix: everything on ESP.

efibootmgr needed to register boot entry

ThinkPad didn’t auto-detect systemd-boot binary

Fallback preset not generating images

Arch ships with fallback commented out. Uncomment PRESETS, fallback_image, fallback_options in presets.

Boot entries at wrong path (/boot/loader/entries/)

bootctl --boot-path=/boot creates entries on ext4. Remove --boot-path, entries go on ESP.

512M ESP ran out of space copying all 4 initramfs

Only copy default images (no fallback). Fallback stays on ext4 /boot only.

nvidia-smi fails after install

Kernel module not loaded — must reboot. Also must sync new initramfs to ESP.

nvidia package not found

RTX 5090 requires nvidia-open (open kernel module), not proprietary nvidia.

iPSK VLAN blocks outbound port 22

Use ssh.github.com:443 with -l git. Goes away after EAP-TLS on DOMUS-Secure.

stow conflicts with default shell configs

rm -f ~/.bashrc ~/.bash_profile ~/.zshrc before stowing

GPG database locked after rsync

Stale lock files from source. find ~/.gnupg -name "*.lock" -delete && gpgconf --kill all

gopass "not initialized" after rsync

Config references ~/.password-store (legacy). Fix: sed -i to point at ~/.local/share/gopass/stores/root

gopass -c (clipboard) fails over SSH

No clipboard daemon. Use gopass show -f to print to console.

rsync from Razer fails — password denied

Razer SSH config Host * forces pubkey-only. Use -e "ssh -F /dev/null". Also enable KbdInteractiveAuthentication and PasswordAuthentication on target.

sshd_config sed didn’t match — password auth still yes

Line was PasswordAuthentication yes (commented). Use s/^\?PasswordAuthentication.*/PasswordAuthentication no/

nvim opens blank despite correct ~/.config/nvim symlink

.zshrc exports NVIM_APPNAME="nvim-domus". nvim looks at ~/.config/nvim-domus/, not ~/.config/nvim/.

dots-quantum missing gpg/, hosts/, secrets/ packages

Gitignored private packages. Must scp/rsync separately from source machine.

SSH to Razer from P16g fails — pubkey denied

P16g’s key not in Razer’s authorized_keys. Added pub key manually. Proper fix: Vault SSH certs.

git clone remote URL set to port 443 format

Cloned with ssh://ssh.github.com:443/ on iPSK. After moving to DOMUS-Secure: git remote set-url origin git@github.com:user/repo.git

Vault cert issued with wrong hostname (modestus-razer)

$(cat /etc/hostname) on Razer returns Razer’s name. Must HOSTNAME="modestus-p16g" explicitly.

Hostname set as modestus-t16g (wrong model)

Machine is P16g Gen 3, not T16g. hostnamectl set-hostname modestus-p16g + sed /etc/hosts.

GPG "No pinentry" — pinentry-qt missing libKF6GuiAddons.so.6

kguiaddons package not installed. Use ldd /usr/bin/pinentry-qt | grep "not found" to find ALL missing deps at once, then pacman -Qo on a working machine to find package names.

GPG pinentry-qt prompts on desktop instead of SSH terminal

gpg-agent inherits WAYLAND_DISPLAY from desktop. pinentry-auto script checks SSH_CONNECTION first. Also need gpg-connect-agent updatestartuptty /bye on SSH login (added to .zshrc).

env-gpu.conf symlink in repo points to hosts/razer/ — breaks on P16g

Per-host config committed as symlink to Razer. Fix: gitignore hyprland/.config/hypr/env-gpu.conf, each machine symlinks to its own hosts/<hostname>/env-gpu.conf manually.

ACPI interrupt storm — gpe6E firing 4.7M times, CPU at 84C idle

acpi_mask_gpe=0x6E kernel parameter masks the rogue GPE. Added to all boot entries. CPU dropped to 41C after reboot.

nmcli connection down over SSH kills the WiFi link — SSH session dies, connection up never runs

NEVER bounce WiFi from an SSH session over that same WiFi. Run locally from the P16g desktop, or write to /tmp/bounce-wifi.sh over SSH and execute it from the local terminal. nohup with sleep also works but risky.

SSH config had wrong IPs for hosts

modestus-razer had 10.50.10.111 but actual IP is 10.50.1.106. Verify IPs before encrypting: ip -4 -o addr show | awk '$2!="lo" \{print $2, $4}'. Fix with sed -i '/Host modestus-razer$/,/^$/s/HostName OLD/HostName NEW/'. Re-encrypt + push + pull + decrypt on all machines.

age -d … > file fails with zsh: file exists

zsh noclobber prevents overwriting. Use >| (force overwrite): age -d -i key config.age >| config

~/.ssh/sockets/ directory missing on P16g

SSH config uses ControlPath ~/.ssh/sockets/… but directory wasn’t created. mkdir -p ~/.ssh/sockets before first SSH.

stow audit script misses share package — shows X when stowed

share stows to ~/.local/share/awk/, sed/, etc. at depth 4. Audit find uses maxdepth 2 — change to maxdepth 4 for accurate results.

hosts, gpg, secrets are NOT stow packages

stow -t ~ hosts creates wrong-level symlinks (~/razer/, ~/x1/, ~/aw/). These are per-host config containers — use manual symlinks only. secrets is a separate git repo at ~/.secrets/.

gcvault (gocryptfs vault manager) not deployed

Entire ~/atelier/_vaults/ directory needs rsync from Razer. Contains 4 vaults: credentials, work-sensitive, network-configs, personal. Symlinks from ~/.config/gh and ~/.claude/credentials.json point into mounted vault.

SSH between P16g (VLAN 10) and Razer (VLAN 1) — connection hangs

Different subnets with no inter-VLAN routing by design (anti-pivot security). Administrators with EAP-TLS certs connect to VLAN 100 (management VLAN) which has routing to infrastructure VLANs. Need to verify Razer’s cert + ISE authorization profile assigns the correct VLAN for cross-VLAN SSH access.

make fails — Cannot find module '@antora/lunr-extension'

Fresh clone has no node_modules/ (gitignored). npx antora auto-installs antora itself but not extensions from package.json. Fix: npm install in each domus-* repo after cloning. Not documented in any phase.

AsciiDoc validation not running on terminal commits

Claude Code hooks (PostToolUse in ~/.claude/settings.json) only fire inside Claude Code sessions. Terminal gach/git commit bypasses validation entirely. No git-level pre-commit hook exists — .git/hooks/ only contains .sample files. core.hooksPath not configured. dots-quantum git stow package has no hooks directory.

No Mandatory Access Control — AppArmor not installed or enabled

Discovered Apr 4 during domus-digitalis setup audit. Arch kernel has CONFIG_SECURITY_APPARMOR=y but it’s not enabled at boot. All user processes have unrestricted access to ~/.secrets/, ~/.gnupg/, ~/.age/, gopass stores. Fix applied Apr 5: pacman -S apparmor, boot params updated on all 3 entries with lsm=…apparmor,bpf apparmor=1 security=apparmor, also restored missing acpi_mask_gpe=0x6E on fallback + LTS. apparmor.service enabled. Pending reboot. Now tracked as Phase 12. INC-2026-04-04-002. CR: AppArmor.

make serve fails — docker: command not found

Kroki diagram server requires Docker or Podman. Neither installed on P16g. make serve proceeds past the error but diagrams won’t render.

make serve fails — UI bundle not found

domus-antora-ui repo was cloned but build/ui-bundle.zip never built. Fix: cd ~/atelier/_bibliotheca/domus-antora-ui && npm install && npx gulp bundle. Note: npx --prefix does NOT change cwd for gulp — must cd into the repo first.

lsof: command not found during make serve

Makefile uses lsof -ti:8000 | xargs -r kill -9 to kill stale servers. lsof not installed on fresh Arch. Non-fatal but noisy. Fix: sudo pacman -S lsof.

AppArmor boot params not active after reboot — aa-enabled returns No

CR-2026-04-04 sed commands targeted /boot/loader/entries/ (ext4 shadow) instead of /boot/efi/loader/entries/ (ESP — what systemd-boot actually reads). Boot entries on ext4 had correct params but kernel never received them. This is the same Phase 4 deviation (entries must live on ESP VFAT) manifesting again. Fix: variable-driven idempotent patch targeting ESP_ENTRIES="/boot/efi/loader/entries" with GUARD="apparmor=1" check. See Phase 12 for the corrected commands.