Add Agent Context files

.github/workflows/publish-ppa.yml

@@ -121,7 +121,9 @@ jobs:
             # New upstream version — first repack
             NEW_REPACK=1
           else
-            # Same upstream version already published — increment repack for a fresh tarball
+            # Same upstream version already published — increment repack so each
+            # run produces a unique orig tarball name. Launchpad rejects
+            # re-uploads with different content under the same tarball name.
             NEW_REPACK=$((MAX_REPACK + 1))
           fi
           NEW_REV=1
@@ -230,7 +232,9 @@ jobs:
             mkdir -p "$BUILD_DIR"
             tar -xzf "$WORK_DIR/${ORIG_TARBALL}" -C "$BUILD_DIR" --strip-components=1
 
-            # Copy debian/ from packaging templates
+            # Copy debian/ from packaging templates. These are not used as-is:
+            # changelog is overwritten below, and control/rules are sed-modified
+            # per series (e.g. Noble uses versioned cargo-1.85/rustc-1.85).
             cp -r "$GITHUB_WORKSPACE/packaging/launchpad/debian" "$BUILD_DIR/debian"
 
             # Write series-specific changelog
@@ -252,7 +256,8 @@ jobs:
             sed -i "s|cargo build|${CARGO_BIN} build|; s|cargo clean|${CARGO_BIN} clean|" \
               "$BUILD_DIR/debian/rules"
 
-            # Build unsigned source package (orig tarball is already in $WORK_DIR which is ..)
+            # Build source-only package — Launchpad compiles in clean chroots,
+            # so all series can be built on a single runner.
             cd "$BUILD_DIR"
             debuild -S -sa -d -us -uc
           done
@@ -310,7 +315,10 @@ jobs:
           echo "==> GPG key not on keyserver, publishing $GPG_FINGERPRINT..."
           gpg --keyserver hkp://keyserver.ubuntu.com --send-keys "$GPG_FINGERPRINT"
 
-          # Dispatch the retry workflow with all state as inputs
+          # Dispatch the retry workflow with all pending-upload state as inputs.
+          # The retry workflow uses a gpg-retry-delay environment with a 20-min
+          # wait timer (no runner cost during the wait). It self-dispatches until
+          # the key propagates, then re-dispatches this PPA workflow. 6-hour timeout.
           echo "==> Scheduling GPG keyserver retry workflow..."
           gh workflow run gpg-keyserver-retry.yml \
             -f gpg_fingerprint="$GPG_FINGERPRINT" \

AGENTS.md

@@ -0,0 +1,109 @@
+# siomon - Agent Context
+
+## Project Overview
+
+siomon is a Linux hardware information and real-time sensor monitoring tool
+written in Rust (edition 2024, rust-version 1.85+). The binary is called `sio`,
+the package is called `siomon`. Licensed under MIT.
+
+Repository: https://github.com/level1techs/siomon
+
+Architectures: x86_64 and aarch64 (including NVIDIA Tegra/Jetson platforms).
+
+Two operating modes:
+- **TUI dashboard** -- real-time sensor monitoring with min/max/avg tracking,
+  alerts, and CSV logging. This is the default when no subcommand is given,
+  stdout is a terminal, and format is not explicitly set.
+- **One-shot info** -- hardware details via subcommands (`sio cpu`, `sio gpu`,
+  etc.) or a sensor snapshot (`sio sensors`).
+
+## Source Structure
+
+The `src/` directory is organized by concern:
+
+- `collectors/` -- one-shot hardware data collection (one module per subsystem).
+  Each exposes a `collect()` function.
+- `sensors/` -- real-time polling sources implementing the `SensorSource` trait.
+  Includes hwmon, CPU, GPU, RAPL, disk, network, IPMI, HSMP, EDAC, MCE, AER,
+  I2C/PMBus, and Super I/O chip drivers.
+- `model/` -- serde data structures shared between collectors and output.
+- `output/` -- formatters (text, json, xml, html, csv) and the TUI dashboard.
+- `platform/` -- OS interface abstraction (sysfs, procfs, MSR, NVML, NVMe/SATA
+  ioctl, port I/O, kernel module, Tegra).
+- `parsers/` -- binary format parsers (SMBIOS, EDID).
+- `db/` -- embedded lookup databases (CPU codenames, sensor labels, board
+  templates organized by vendor).
+- `cli` -- clap argument definitions.
+- `config` -- config file loading (`$XDG_CONFIG_HOME/siomon/config.toml`).
+- `error` -- error types (thiserror).
+
+## Key Patterns
+
+**Parallel collection** -- all hardware collectors run in parallel via
+`std::thread::scope()`. Panics are caught and default values returned.
+
+**SensorSource trait** -- each polling source implements `name()` and `poll()`.
+Discovery happens during construction. A poller orchestrates the loop in a
+background thread with shared state.
+
+**Board database** -- per-board templates matched by DMI board name substring,
+organized by vendor under `db/boards/`. First match wins — more specific boards
+must come before generic ones. Adding a board: create the `.rs` file, add it to
+the vendor's `mod.rs`, and register it in the `BOARDS` array.
+
+**Direct I/O** -- Super I/O (port I/O) and I2C/PMBus/SPD5118 sensors are only
+enabled with the `--direct-io` flag (requires root). Standard hwmon sensors work
+without root.
+
+## Feature Flags
+
+From `Cargo.toml`: `default = ["tui", "nvidia", "json", "csv"]`
+
+| Feature | Purpose | Optional dep |
+|---------|---------|-------------|
+| `tui` | Interactive TUI dashboard | ratatui, crossterm |
+| `nvidia` | GPU support via NVML (dlopen) | libloading |
+| `json` | JSON output | serde_json |
+| `csv` | CSV sensor logging | csv |
+| `html` | HTML report output | (none) |
+| `xml` | XML output | quick-xml |
+
+Build with `--no-default-features` for a text-only minimal binary.
+
+## CLI
+
+Subcommands: `cpu`, `gpu`, `memory`, `storage`, `network`, `pci`, `usb`,
+`audio`, `battery`, `board`, `pcie`, `sensors`.
+
+TUI auto-activates when: no subcommand + stdout is terminal + format not
+explicitly set + `tui` feature enabled. Config file values apply as defaults
+for any CLI argument not explicitly set on the command line.
+
+## Kernel Module
+
+`kmod/sinfo_io/` contains a DKMS-based Linux kernel module (`sinfo_io.c`,
+`sinfo_io.h`, `Makefile`, `dkms.conf`). Accessed from Rust via
+`src/platform/sinfo_io.rs`.
+
+## CI and Release
+
+**CI** (`.github/workflows/ci.yml`) -- triggered on push/PR to main. Jobs:
+check, clippy (with `-A dead_code`), fmt, test, build, build-minimal.
+
+**Release** (`.github/workflows/release.yml`) -- triggered on `v*` tags.
+Build matrix: x86_64 + aarch64 (cross-compiled). Pipeline: build → crates.io
+publish (OIDC) → GitHub Release → AUR + PPA in parallel.
+
+**Packaging** -- AUR and PPA workflows auto-increment version numbers. See
+`packaging/aur/AGENTS.md` and `packaging/launchpad/AGENTS.md` for details.
+
+## Build and Test
+
+Release profile: `opt-level = "z"`, LTO, `codegen-units = 1`, `panic = "abort"`,
+strip.
+
+```bash
+cargo test --all-features
+cargo clippy --all-features -- -D warnings -A dead_code
+cargo build --release --all-features
+```

packaging/aur/AGENTS.md

@@ -0,0 +1,18 @@
+# AUR Packaging - Agent Context
+
+## Purpose
+
+PKGBUILD template for the Arch User Repository (AUR). Contains template
+values for `pkgver`, `_tag`, `pkgrel`, and `b2sums` that the CI workflow
+overwrites at build time via `sed` and `updpkgsums`.
+
+## Key Sources
+
+- `packaging/aur/README.md` — how the build process works, version format,
+  and local testing instructions.
+- `.github/workflows/publish-aur.yml` — the workflow implementation.
+  Inline comments document why a non-root builder user is created.
+- `packaging/aur/PKGBUILD` — the template itself. Inline comments document
+  the architecture field requirement.
+- `PACKAGING.md` — one-time setup guide for secrets, SSH keys, and AUR
+  account configuration.

packaging/aur/PKGBUILD

@@ -4,6 +4,8 @@ pkgname=siomon
 pkgver=0.2.3
 pkgrel=1
 pkgdesc="Hardware information and real-time sensor monitoring tool"
+# Must list compiled architectures, not "any" — namcap rejects ELF binaries
+# in an "any" package.
 arch=(x86_64 aarch64)
 url="https://github.com/level1techs/siomon"
 license=('MIT')

packaging/launchpad/AGENTS.md

@@ -0,0 +1,20 @@
+# Launchpad PPA Packaging - Agent Context
+
+## Purpose
+
+Debian packaging templates for building source packages uploaded to a
+Launchpad PPA. The `debian/` files here are **templates** — the CI workflow
+copies them into a build directory, then modifies them per Ubuntu series.
+
+## Key Sources
+
+- `packaging/launchpad/README.md` — how the build process works, version
+  format, series-specific handling, and local testing instructions.
+- `.github/workflows/publish-ppa.yml` — the workflow implementation.
+  Inline comments document key gotchas: template `sed` modifications,
+  source-only builds, orig tarball uniqueness via repack suffix, and the
+  GPG keyserver retry mechanism.
+- `.github/workflows/gpg-keyserver-retry.yml` — GPG key propagation retry
+  loop (dispatched automatically when needed).
+- `PACKAGING.md` — one-time setup guide for secrets, GPG keys, Launchpad
+  account, and GitHub environment configuration.