path: root/docs/notes.org

#+TITLE: Claude Code Notes - archangel
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2026-01-17

* About This File

This file contains project-specific information for this project.

**When to read this:**
- At the start of EVERY session (after reading protocols.org)
- When needing project context or history
- When checking reminders or pending decisions

**What's in this file:**
- Project-specific context and goals
- Available workflows for this project
- Active reminders
- Pending decisions
- Session history

**For protocols and conventions, see:** [[file:protocols.org][protocols.org]]

* Project-Specific Context

** Overview

Build system for creating a custom Arch Linux installation ISO with ZFS support. The goal is to have a bootable ISO that can install Arch Linux on ZFS root without needing to manually compile ZFS or deal with kernel version mismatches.

** Repository

- Remote: =cjennings@cjennings.net:git/archangel.git=
- Branch: =main=
- docs/ is committed (not private)

** Key Components

- =build.sh= - Main build script (runs as root)
  - Downloads ZFS packages from archzfs.com repository
  - Creates custom archiso profile based on releng
  - Adds custom packages (nodejs, npm, jq, zsh, htop, ripgrep, etc.)
  - Copies custom installer scripts into ISO
  - Builds ISO with mkarchiso

- =custom/= - Custom scripts included in ISO
  - =archangel= - Main installer script
  - =install-claude= - Claude Code installer
  - =archsetup-zfs= - ZFS-specific Arch setup
  - =zfs-setup= - Installs ZFS packages and loads module (generated by build.sh)

- =scripts/test-vm.sh= - QEMU VM for testing the ISO

** Current State

TESTING: archangel installer supports both ZFS and Btrfs.

- ISO builds successfully with linux-lts + zfs-dkms
- ZFS installations use ZFSBootMenu
- Btrfs installations use GRUB + grub-btrfs for snapshot boot
- Both filesystems support multi-disk RAID configurations

** Goals

Create a bootable Arch Linux installation ISO that:
1. Installs Arch on ZFS root with native encryption
2. Uses sane defaults for dataset layout
3. Configures automatic snapshots (sanoid)
4. Sets up replication to TrueNAS for backups
5. Includes Claude Code on live ISO for emergency troubleshooting

** Design Decisions

*** Kernel Strategy
- Use =linux-lts= + =zfs-dkms= from archzfs.com repo
- DKMS builds ZFS from source, guaranteeing kernel compatibility
- Slower build time but eliminates version mismatch issues entirely
- LTS kernel provides stability, DKMS provides flexibility

*** ZFS Pool Configuration
| Setting | Value | Rationale |
|---------+-------+-----------|
| Pool name | =zroot= | Standard convention |
| Encryption | AES-256-GCM, passphrase | Required at every boot |
| Compression | =zstd= (default) | Good balance of speed/ratio |
| Ashift | 12 (4K sectors) | Modern drives |
| Root reservation | 50GB | Prevents pool from filling |

*** Dataset Layout
| Dataset | Mountpoint | Special Settings | Purpose |
|---------+------------+------------------+---------|
| zroot/ROOT/default | / | reservation=50G | Root filesystem |
| zroot/home | /home | | Home directories (archsetup creates user subdataset) |
| zroot/media | /media | compression=off | Pre-compressed media files |
| zroot/vms | /vms | recordsize=64K | VM disk images (qemu/libvirt + virtualbox) |
| zroot/var/log | /var/log | | System logs |
| zroot/var/cache | /var/cache | | Package cache |
| zroot/var/lib/pacman | /var/lib/pacman | | Package database |
| zroot/var/lib/docker | /var/lib/docker | | Docker storage |
| zroot/tmp | /tmp | auto-snapshot=false | Temp files |
| zroot/var/tmp | /var/tmp | auto-snapshot=false | Temp files |

*** Snapshot Policy (Sanoid)
Less aggressive since TrueNAS handles long-term backups:

| Template | Hourly | Daily | Weekly | Monthly | Used For |
|----------+--------+-------+--------+---------+----------|
| production | 6 | 7 | 2 | 1 | root, home, var/log, pacman |
| backup | 0 | 3 | 2 | 1 | media, vms |
| none | 0 | 0 | 0 | 0 | tmp, cache |

Plus: Pacman hook creates snapshot before every transaction.

*** TrueNAS Replication
- Primary: =truenas.local= (local network)
- Fallback: =truenas= (tailscale)
- Destination pool: =vault/[TBD]=
- Schedule: Nightly at 2:00 AM
- Datasets: ROOT/default, home, media, vms

*** Included Packages
- Base system + development tools
- =nodejs=, =npm=, =jq= (for Claude Code)
- =zsh=, =htop=, =ripgrep=, =eza=, =fd=, =fzf=
- =sanoid= (snapshot management)
- =dialog= (installer UI)

*** Installation UX
- All questions asked upfront, then unattended installation
- WiFi tested before installation begins (if provided)
- User can walk away during install and come back
- Summary + final confirmation before starting

*** User Account Strategy
- install-archzfs creates root account only (asks for root password)
- No user account created during install
- Just create =zroot/home= dataset (no user-specific subdataset)
- archsetup creates user account + home dataset post-reboot

*** GRUB HiDPI Support
- Generate 32px DejaVuSansMono font during install
- Set =GRUB_FONT= to use custom font
- Works well on HiDPI and regular displays

*** WiFi Configuration
- Ask for SSID + password during install (optional)
- Test connection before installation starts
- Copy connection profile to installed system
- Auto-connects after reboot

*** Post-Install Workflow
1. install-archzfs: Minimal ZFS system + root account
2. Reboot, login as root
3. Run archsetup manually for full workstation setup

*** Testing/Debugging (VM)
- SSH access on live ISO: sshd enabled, known root password
- Serial console: =-serial mon:stdio= in QEMU for terminal copy/paste
- Port forwarding: 2222→22 (already configured)
- Allows easy copy/paste of error messages during testing

** Open Questions

- [ ] TrueNAS destination dataset path (vault/???)

* AVAILABLE WORKFLOWS

This section lists all documented workflows for this project. Update this section whenever a new workflow is created.

** create-workflow
File: [[file:workflows/create-workflow.org][docs/workflows/create-workflow.org]]

Meta-workflow for creating new workflows. Use this when identifying repetitive workflows that would benefit from documentation.

Workflow:
1. Q&A discovery (4 core questions)
2. Assess completeness
3. Name the workflow
4. Document it
5. Update notes.org
6. Validate by execution

Created: [Date when workflow was created]

** create-v2mom
File: [[file:workflows/create-v2mom.org][docs/workflows/create-v2mom.org]]

Workflow for creating a V2MOM (Vision, Values, Methods, Obstacles, Metrics) strategic framework for any project or goal.

Workflow:
1. Understand V2MOM framework
2. Create document structure
3. Define Vision (aspirational picture of success)
4. Define Values (2-4 principles with concrete definitions)
5. Define Methods (4-7 approaches ordered by priority)
6. Identify Obstacles (honest personal/technical challenges)
7. Define Metrics (measurable outcomes)
8. Review and refine
9. Commit and use immediately

Time: ~2-3 hours total
Applicable to: Any project (health, finance, software, personal infrastructure, etc.)

Created: 2025-11-05

** startup
File: [[file:workflows/startup.org][docs/workflows/startup.org]]

Workflow for beginning a Claude Code session with proper context and priorities.

Triggered by: **Automatically at the start of EVERY session**

Workflow:
1. Add session start timestamp (check for interrupted sessions)
2. Sync with templates (exclude notes.org and previous-session-history.org)
3. Scan workflows directory for available workflows
4. Read key notes.org sections (NOT entire file)
5. Process inbox (mandatory)
6. Ask about priorities (urgent work vs what's-next workflow)

Ensures: Full context, current templates, processed inbox, clear session direction

Created: 2025-11-14

** wrap-it-up
File: [[file:workflows/wrap-it-up.org][docs/workflows/wrap-it-up.org]]

Workflow for ending a Claude Code session cleanly with proper documentation and version control.

Triggered by: "wrap it up," "that's a wrap," "let's call it a wrap," or similar phrases

Workflow:
1. Write session notes to notes.org Session History section
2. Archive sessions older than 5 sessions to previous-session-history.org
3. Git commit and push all changes (NO Claude attribution)
4. Provide brief valediction with accomplishments and next steps

Ensures: Clean handoff between sessions, nothing lost, clear git history, proper documentation

Created: 2025-11-14

** [Add more workflows as they are created]

Format for new entries:
#+begin_example
** workflow-name
File: [[file:workflows/workflow-name.org][docs/workflows/workflow-name.org]]

Brief description of what this workflow does.

Workflow:
1. Step 1
2. Step 2
3. Step 3

Created: YYYY-MM-DD
#+end_example

* PENDING DECISIONS

This section tracks decisions that need Craig's input before work can proceed.

**Instructions:**
- Add pending decisions as they arise during sessions
- Format: =** [Topic/Feature Name]=
- Include: What needs to be decided, options available, why it matters
- Remove decisions once resolved (document resolution in Session History)

**Example format:**
#+begin_example
** Feature Name or Topic

Craig needs to decide on [specific question].

Options:
1. Option A - [brief description, pros/cons]
2. Option B - [brief description, pros/cons]

Why this matters: [impact on project]

Implementation is ready - just need Craig's preference.
#+end_example

** Current Pending Decisions

(None currently - will be added as they arise)

* Technical Debt Backlog

Catalogued 2026-04-12 after =lib/zfs.sh= removal. Ordered by impact × ease
(ripe fruit first). File:line references were accurate at catalog time —
re-verify before acting.

** Ripe Fruit (minutes–hour each)

*** [#A] Duplicate =mount_efi()= — 15 min
- =installer/archangel=:916 defines a ZFS-specific no-arg version
- =installer/lib/disk.sh=:126 defines a general (partition, mountpoint) version that's never called
- Fix: remove from monolith, call library version with =EFI_PARTS[0]=

*** [#A] =get_zfs_passphrase()= vs =get_luks_passphrase()= — 20 min
- =installer/archangel=:639 and :583, 90% identical prompt+confirm+min-length logic
- Fix: unify into =get_encryption_passphrase(var_name, description)=

*** [#A] =install_base()= vs =install_base_btrfs()= — 45 min
- =installer/archangel=:925 vs :975, 95% copy-paste, differ only in package list
- Fix: single =install_base()= with =FILESYSTEM=-conditional package array

*** [#B] Fragile grep-head chains — 20 min
- =installer/archangel=:1269, :1170 use =... | head -1 | grep -oP ...= without null guards
- Silent failure → empty variable → cryptic failure downstream
- Fix: =x=$(...) || error "..."= pattern

*** [#B] Redundant =sed= calls on sshd_config — 25 min
- =installer/archangel=:1099-1100 runs sed twice without =-e= combining
- Both fail silently if config has unexpected format; SSH config never logged
- Fix: single sed with =-e -e=, explicit error check

** Medium Lifts (half-day each)

*** [#B] =partition_disks()= is ZFS-only — 45 min
- =installer/archangel=:756 hardcodes =EFI_PARTS= + =ZFS_PARTS=, called only from =install_zfs()=
- Btrfs path uses =partition_disk()= (singular) — parallel partitioning logic
- Fix: merge into =disk.sh=, dispatch on =FILESYSTEM=

*** [#B] FILESYSTEM validation scattered — 30 min
- =config.sh=:113+ validates, then =archangel=:135-137 re-validates, then :115 sets defaults
- Unclear which wins; easy to drift
- Fix: single source of truth in =config.sh=, monolith trusts it

*** [#C] Hardcoded =/mnt/efi= paths — 30 min
- =btrfs.sh=:731-739 and =archangel=:920
- Fix: export =MNTPOINT=/mnt= and =EFI_DIR=/mnt/efi= at startup

** Scale Smells (full day+)

*** [#B] =get_raid_level()= is 146 lines — 2 hr
- =installer/archangel=:350-496, 3-level nested if/elif on RAID_LEVEL × disk count × encryption
- Hard to unit-test, hard to spot uncovered branches
- Fix: extract raid mode dispatch; use =case= instead of if chains

*** [#C] ZFS vs Btrfs install paths diverge — 1.5 hr
- =install_zfs()= (:1590) sequential calls, no mid-step recovery
- =install_btrfs()= (:1614) captures partition arrays but doesn't validate population
- Two eras of code; LUKS-open failure mid-btrfs install goes unnoticed
- Fix: return checks after partition ops, shared error hooks

** Review Cadence

Revisit this section at the start of any session that touches the
installer. Completed items move to Session History with a commit ref.
Add new items as they're discovered (format: priority, title, time
estimate, locations, fix direction).

* Active Reminders

** Current Reminders

- =[2026-04-13]= **Investigate =zfs-mirror-encrypt= rollback soft-failure.**
  In tonight's full VM integration run (=test-logs/full-run-05-53.log=,
  05:53-08:10 EDT), the test framework marked =zfs-mirror-encrypt= PASSED
  but logged =ERROR: Rollback failed - test file not restored= →
  =WARN: Rollback verification had issues=. ZFS rollback completed but
  the filesystem state wasn't what =verify_rollback= expected. Not a
  regression from tonight's refactors (rollback code wasn't touched).
  Worth a look — possibly drift in =verify_rollback= vs. the ZFS
  rollback semantics on a mirrored pool.

** Instructions for This Section

When Craig says "remind me" about something:
1. Add it here with timestamp and description
2. If it's a TODO, also add to =/home/cjennings/sync/org/roam/inbox.org= scheduled for today
3. Check this section at start of every session
4. Remove reminders once addressed

Format:
- =[YYYY-MM-DD]= Description of what to remind Craig about

* Session History

This section contains notes from each session with Craig. Sessions are logged in reverse chronological order (most recent first).

**Note:** Sessions older than 5 sessions are archived in [[file:previous-session-history.org][Previous Session History]]

** Format for Session History Entries

Each entry should use this format:

- **Timestamp:** =*** YYYY-MM-DD Day @ HH:MM TZ= (get TZ with =date +%z=)
- **Time estimate:** How long the session took
- **Status:** COMPLETE / IN PROGRESS / PAUSED
- **What We Completed:** Bulleted list of accomplishments
- **Key Decisions:** Any important decisions made
- **Files Modified:** Links to changed files (use relative paths)
- **Next Steps:** What to do next session (if applicable)

**Best practices:**
- Keep entries concise but informative
- Include enough context to resume work later
- Document important technical insights
- Note any new patterns or preferences discovered
- Link to files using org-mode =file:= links

** Session Entries

*** 2026-04-12 Sun → 2026-04-13 Mon @ 23:12-08:10 EDT

*Status:* COMPLETE

*What We Completed:*

**1. Security scrub** — =cmjdase1n= (velox LUKS/ZFS passphrase + root
password) was leaked into git history in the velox-{zfs,btrfs}.conf
files and in prior session-context notes. Used =git filter-branch
--tree-filter= to rewrite 182 commits, replacing the literal with
=welcome=; cleaned refs/original + gc =--prune=now=; force-pushed
main (8e47d45 → d59fe14) and tag v0.8 (8444325 → 05f5c36). Templated
=velox-{zfs,btrfs}.conf= as =.example= files, real files added to
=.gitignore=. Craig declined to rotate the leaked passphrase or
contact GitHub Support to purge cached commit views.

**2. Testing infrastructure** — shellcheck was already wired; added
bats-core (v1.13 via pacman). Created =tests/unit/test_common.bats=,
=test_config.bats=, =test_raid.bats=. =make bats= + =make test= targets
(lint + bats). 65 bats tests total; shellcheck clean.

**3. Refactor scan** (=/refactor full=) — 13 findings. Applied all 5
critical+high in sequence, each behavior-preserving, lint+bats clean,
individual commit:
- =ce4f716= drop dead =mount_efi= + =select_raid_level= in =lib/disk.sh=
- =81b169f= unify =get_{luks,zfs}_passphrase= + =get_root_password= →
  =prompt_password(varname, label, min_len)= via nameref
- =32422a8= merge =install_base= + =install_base_btrfs= → extract
  =pacstrap_packages(filesystem)= pure helper
- =53df8d4= dedupe =findmnt= invocation in =build.sh:safe_cleanup_work_dir=
- =ea6f252= decompose =install_btrfs()= into five named orchestration
  stages in =lib/btrfs.sh= (=btrfs_open_encryption=,
  =btrfs_make_filesystem=, =btrfs_configure_luks_target=,
  =btrfs_install_grub=, =btrfs_close_encryption=). Dropped from ~99
  lines of nested conditionals to a ~45-line flat sequence.

**4. Earlier in session** — =610d6be= extracted pure RAID logic into
=lib/raid.sh= (=raid_valid_levels_for_count=, =raid_is_valid=,
=raid_usable_bytes=, =raid_fault_tolerance=) with 30 bats tests.

**5. Docs** — =402bbd8= testing-strategy.org got a proper "Unit Tests
(bats)" section; README.org testing section renamed + two-layer
framed, project structure tree synced (dropped zfs.sh, added raid.sh
+ tests/unit/), archzfs link updated to GitHub Releases.

**6. todo.org** — created at project root (gitignored) with the 8
remaining refactor items tagged =:refactor:= (#4–#13 from the scan,
all medium or low). Includes =[[file:../todo.org][Archangel Open Work]]= open-list +
Archangel Resolved ledger.

**7. Full VM test run** — =make test-install=. First pass failed 6/12
(all ZFS configs) due to DKMS compile timeout on kernel 6.18.22. Root
cause: =INSTALL_TIMEOUT=600= in =scripts/test-install.sh= — your
2026-02-12 session notes mentioned bumping to 1800 but the change
never made it into git. =d42fa81= bumped to 1800. Second pass (direct
=./scripts/test-install.sh=, skipping rebuild): **12/12 PASSED** in
~2h 17m.

*Key Decisions:*
- bats-core installed system-wide via pacman rather than vendored as
  a submodule — follows the pattern already used for shellcheck.
- Namerefs (=local -n=) added two new =.shellcheckrc= disables
  (SC2178, SC2153) as recurring false positives.
- For the #5 =install_btrfs= decomposition: no new bats tests added,
  because every new helper shells out to real LUKS/mkfs.btrfs
  operations. VM integration tests remain the behavior validator;
  the VM run confirmed no regression.
- Tech-debt backlog that had been sitting uncommitted in =docs/notes.org=
  since the prior (velox) session wrap-up got rolled into this
  wrap-up commit.

*Files Modified (session):*
- [[file:../installer/archangel][installer/archangel]] — lib/raid.sh source, prompt_password,
  install_base merge, install_btrfs decompose
- [[file:../installer/lib/common.sh][installer/lib/common.sh]] — prompt_password, pacstrap_packages
- [[file:../installer/lib/disk.sh][installer/lib/disk.sh]] — dropped dead =mount_efi=, =select_raid_level=
- [[file:../installer/lib/btrfs.sh][installer/lib/btrfs.sh]] — 5 new =btrfs_*= orchestration helpers
- [[file:../installer/lib/raid.sh][installer/lib/raid.sh]] — NEW, pure RAID logic
- [[file:../build.sh][build.sh]] — dedupe findmnt in =safe_cleanup_work_dir=
- [[file:../scripts/test-install.sh][scripts/test-install.sh]] — =INSTALL_TIMEOUT=1800=
- [[file:../.shellcheckrc][.shellcheckrc]] — disable SC2178, SC2153
- [[file:../.gitignore][.gitignore]] — add =installer/velox-*.conf=
- [[file:../Makefile][Makefile]] — add =bats= target, =test=lint+bats=
- [[file:../README.org][README.org]] — testing section update
- [[file:../testing-strategy.org][testing-strategy.org]] — new "Unit Tests (bats)" section

*Files Created:*
- [[file:../installer/lib/raid.sh][installer/lib/raid.sh]] (70 lines)
- [[file:../tests/unit/test_common.bats][tests/unit/test_common.bats]] (23 tests)
- [[file:../tests/unit/test_config.bats][tests/unit/test_config.bats]] (12 tests)
- [[file:../tests/unit/test_raid.bats][tests/unit/test_raid.bats]] (30 tests)
- [[file:../installer/velox-btrfs.conf.example][installer/velox-btrfs.conf.example]] (template)
- [[file:../installer/velox-zfs.conf.example][installer/velox-zfs.conf.example]] (template)
- [[file:../todo.org][todo.org]] (gitignored, tracks remaining refactors)

*Commits (main branch, chronological):*
1. =d59fe14= security: gitignore host configs, add .example templates (post-scrub)
2. =626428e= test: add bats unit tests for common.sh and config.sh
3. =610d6be= refactor: extract pure RAID logic to lib/raid.sh with bats coverage
4. =ce4f716= refactor: drop dead mount_efi and select_raid_level from lib/disk.sh
5. =81b169f= refactor: unify get_{luks,zfs}_passphrase and get_root_password
6. =32422a8= refactor: merge install_base and install_base_btrfs
7. =53df8d4= refactor: dedupe findmnt invocation in safe_cleanup_work_dir
8. =ea6f252= refactor: decompose install_btrfs into named orchestration stages
9. =402bbd8= docs: document bats unit tests + sync stale README bits
10. =d42fa81= fix: bump INSTALL_TIMEOUT from 600 to 1800 for kernel 6.18+ DKMS builds

(Plus the filter-branch rewrite of all prior commits and v0.8 tag
earlier in session — all pre-scrub SHAs are now invalidated.)

*Next Session Pickup:*
- **[Reminder] Investigate =zfs-mirror-encrypt= rollback soft-failure**
  logged in =test-logs/full-run-05-53.log= — see Active Reminders section.
- 8 remaining =:refactor:= items in =todo.org= (6 medium-priority quick
  wins + 1 medium multi-hour #8 partition_disks consolidation + 1 low
  #13 build.sh shadow-file fallback).

*** 2026-04-09 Thu @ 21:30-22:31 -0500

*Status:* COMPLETE

*What We Completed:*
- Attempted ZFS install on bare metal machine "velox" (7.3T NVMe) — failed due to archzfs.com repo being stale (ZFS 2.3.3, max kernel 6.15)
- Fell back to Btrfs/LUKS install — completed but GRUB rejected the correct LUKS passphrase at boot
  - Root cause: LUKS2 created with argon2id PBKDF, GRUB only supports pbkdf2
  - Fixed in installer/lib/btrfs.sh (both single-disk and multi-disk paths)
- Processed inbox: archzfs repo migration notice
  - archzfs.com abandoned mid-2025, project moved to GitHub Releases
  - Updated build.sh and installer/archangel to use new URL: github.com/archzfs/archzfs/releases/download/experimental
  - ZFS 2.4.1 now available for kernel 6.18.21
- Rebuilt ISO with all fixes (archzfs URL, LUKS pbkdf2, no-color default)
- Successfully installed velox with ZFS encrypted root — boots and unlocks via ZFSBootMenu
- Added --color flag to archangel (default: no color, opt-in with flag)
- Added inetutils to installed system packages (hostname was missing)
- Tagged v0.8 and created GitHub release
- Distributed ISO to Ventoy USB and truenas.local:/mnt/vault/isos/ (cleaned up old ISOs)
- Created archsetup ZFS snapshot on velox
- Created velox-zfs.conf and velox-btrfs.conf config files for unattended installs

*Key Decisions:*
- archzfs repo migrated to GitHub Releases permanently
- LUKS2 containers now use pbkdf2 instead of argon2id for GRUB compatibility
- Installer output is colorless by default; --color flag enables it

*Bugs Found and Fixed:*
- GRUB LUKS2 argon2id incompatibility (installer/lib/btrfs.sh)
- archzfs.com stale repo causing ZFS/kernel mismatch (build.sh, installer/archangel)
- inetutils missing from target system packages (installer/archangel)

*Files Modified:*
- [[file:../build.sh][build.sh]] — archzfs URL, comment update
- [[file:../installer/archangel][installer/archangel]] — archzfs URL (2 places), added inetutils to both pacstrap lists
- [[file:../installer/lib/btrfs.sh][installer/lib/btrfs.sh]] — argon2id → pbkdf2
- [[file:../installer/lib/common.sh][installer/lib/common.sh]] — no-color default + enable_color()
- [[file:../installer/lib/config.sh][installer/lib/config.sh]] — --color flag parsing

*Files Created:*
- [[file:../installer/velox-zfs.conf][installer/velox-zfs.conf]] — ZFS unattended config for velox
- [[file:../installer/velox-btrfs.conf][installer/velox-btrfs.conf]] — Btrfs unattended config for velox

*Next Steps:*
- Add build-time check to prevent ZFS/kernel incompatibility in build.sh
- Continue open-sourcing prep

*** 2026-03-28 Sat @ 13:24-13:42 -0500

*Status:* COMPLETE

*What We Completed:*
- Synced templates from claude-templates (protocols, workflows, scripts, announcements)
- Moved 3 logo images from inbox/ to new assets/ directory (renamed space-in-filename)
- Added TODO [#C] task to todo.org: choose a project logo
- Built new archangel ISO for linux-lts 6.18.20 kernel
  - ISO: archangel-2026-03-28-vmlinuz-6.18.20-lts-x86_64.iso (2.0G)
  - First build failed (mkarchiso /proc cleanup race condition), retry succeeded
- Mounted Ventoy USB, copied ISO to /mnt/ventoy/
- Copied ISO to truenas.local:/mnt/vault/isos/ via rsync
- Unmounted Ventoy USB

*Files Modified:*
- [[file:../todo.org][todo.org]] — added logo selection task

*Files Added:*
- [[file:../assets/archangel-logo.png][assets/archangel-logo.png]]
- [[file:../assets/archangel-logo2.png][assets/archangel-logo2.png]]
- [[file:../assets/archangel-logo-samples.png][assets/archangel-logo-samples.png]]

*Next Steps:*
- Choose a project logo from candidates in assets/
- Build AUR packages as local repo for ISO (todo.org [#A] task)
- Continue open-sourcing prep

*** 2026-02-24 Tue @ 08:51-09:12 -0600

*Status:* COMPLETE

*What We Completed:*
- Built new archangel ISO for linux-lts 6.12.74-1 kernel
- ISO: archangel-2026-02-24-vmlinuz-6.12.74-lts-x86_64.iso (1.8G)
- ZFS DKMS 2.3.3 compiled successfully against new kernel
- Sanity test passed: 26/26 checks (ZFS, Btrfs, networking, scripts)
- Distributed locally to ~/archangel-isos/
- Pushed ISO to truenas.local:/mnt/vault/isos/ (TrueNAS now reachable)
- Cleared TrueNAS ISO hash reminder from 2026-02-12 (connectivity restored, ISO pushed)

*Files Modified:*
- None (build artifacts only, no source changes)

*Next Steps:*
- Continue with open-sourcing prep or other todo.org items
- Manual LUKS reboot verification when hardware available

*** 2026-02-24 Tue @ 08:42 -0600

*Status:* COMPLETE

*What We Completed:*
- Reorganized README.org sections to follow logical user journey (build → boot → install → post-reboot)
- Eliminated "Bare Metal Installation" section, redistributing content:
  - =dd= command → Building the ISO > Writing to USB
  - Secure Boot/boot steps → new "Booting the ISO" section
  - SSH/Avahi content → "SSH Access" subsection under Booting the ISO
  - =archangel= invocation + minimal install note → "Installation" intro
  - ZFS/Btrfs first-boot steps → new "Post-Reboot" section
- Renamed sections: "Connecting via SSH Server" → "Booting the ISO", "Arch Linux Install Walkthrough" → "Installation"
- Updated internal org links (#ssh-server → #ssh-access)

*Files Modified:*
- [[file:../README.org][README.org]] — section reorganization, no content lost

*Next Steps:*
- Continue with open-sourcing prep or other todo.org items
- Verify TrueNAS ISO hash (still pending from 2026-02-12)

*** 2026-02-19 Thu @ 16:11-16:14 -0600

*Status:* COMPLETE

*What We Completed:*
- Template sync from claude-templates (protocols, workflows, scripts, announcements)
- Processed 4 announcements:
  1. Calendar workflows updated with cross-calendar visibility
  2. gcalcli now available for Google Calendar CLI access
  3. New open-tasks workflow — updated todo.org headers to project-named convention (Archangel Open Work / Archangel Resolved)
  4. New summarize-emails workflow added
- New workflows synced: add-calendar-event, delete-calendar-event, edit-calendar-event, read-calendar-events, open-tasks, summarize-emails
- New script synced: maildir-flag-manager.py

*Files Modified:*
- [[file:../todo.org][todo.org]] — renamed headers to project-named convention

*Files Added (from template):*
- docs/workflows/{add,delete,edit,read}-calendar-event.org
- docs/workflows/open-tasks.org, summarize-emails.org
- docs/scripts/maildir-flag-manager.py
- docs/announcements/inbox-gitkeep.txt

*Outstanding Reminder:*
- [2026-02-12] Verify TrueNAS ISO hash — still pending

*** 2026-02-12 Thu @ 08:23-16:08 -0600

*Status:* COMPLETE

*What We Completed:*
- Rebuilt archangel ISO for linux-lts 6.12.70-1 kernel
- ISO: archangel-vmlinuz-6.12.70-lts-2026-02-12-x86_64.iso (2.3G)
- All tests passed: sanity (26/26), single-disk, mirror, raidz1
- Fixed archzfs GPG key prompt hanging unattended installs (SigLevel → Never)
- Fixed pgrep false positive in full-test.sh (avahi matched hostname pattern)
- Bumped INSTALL_TIMEOUT from 900s to 1800s for DKMS builds
- Added local distribution to build-release (~/downloads/isos + archsetup inbox notification)
- Distributed ISO to ~/downloads/isos and truenas.local:/mnt/vault/isos
- Audited codebase for open-source readiness, added todo.org task with full checklist
- Dropped SSH access info and test VM rebuild notice in archsetup inbox

*Key Decisions:*
- archzfs SigLevel changed to Never (HTTPS provides transport security; GPG key management kept breaking unattended installs)
- USB drives removed as distribution target
- build-release now handles ~/downloads/isos and archsetup inbox automatically

*Bugs Found and Fixed:*
1. archzfs GPG key prompt: pacstrap -K creates empty keyring, pacman-key -r silently fails, pacman prompts interactively → changed SigLevel to Never in custom/archangel (2 locations)
2. Test pgrep false positive: pgrep -f 'archangel' matched avahi-daemon's "running [archangel.local]" → changed to pgrep -f '/usr/local/bin/archangel'
3. Install timeout: 15 min too short for DKMS compile in VM → bumped to 30 min

*Files Modified:*
- [[file:../custom/archangel][custom/archangel]] — SigLevel fix (install_base + configure_system)
- [[file:../scripts/full-test.sh][scripts/full-test.sh]] — pgrep fix, timeout bump
- [[file:../scripts/build-release][scripts/build-release]] — local distribution + archsetup inbox
- [[file:../todo.org][todo.org]] — open-sourcing prep task

*Next Steps:*
- Verify TrueNAS ISO hash (was unreachable at session end)
- Fix TrueNAS connectivity issues
- Continue with open-sourcing prep or other todo.org items