Add AGENTS.md, shellcheck automation, and version-check.sh

.ona/automations.yaml

@@ -0,0 +1,50 @@
+tasks:
+  installShellcheck:
+    name: Install shellcheck
+    description: Ensure shellcheck is available for linting shell scripts.
+    command: |
+      if ! command -v shellcheck &>/dev/null; then
+        sudo apt-get update -qq && sudo apt-get install -y shellcheck
+      else
+        echo "shellcheck $(shellcheck --version | grep version:) already installed"
+      fi
+    triggeredBy:
+      - postDevcontainerStart
+
+  lintScripts:
+    name: Lint shell scripts
+    description: Run shellcheck against all .sh files in the repo and report issues.
+    command: |
+      echo "=== Aaron Linux - Shell Script Lint ==="
+      echo ""
+
+      SCRIPTS=$(find . -name "*.sh" -not -path "./.git/*" | sort)
+      TOTAL=0
+      FAILED=0
+      PASSED=0
+
+      for f in $SCRIPTS; do
+        TOTAL=$((TOTAL + 1))
+        echo "Checking: $f"
+        if shellcheck -x "$f"; then
+          PASSED=$((PASSED + 1))
+        else
+          FAILED=$((FAILED + 1))
+        fi
+        echo ""
+      done
+
+      echo "======================================="
+      echo "Results: $TOTAL scripts checked"
+      echo "  Passed : $PASSED"
+      echo "  Failed : $FAILED"
+      echo "======================================="
+
+      if [ "$FAILED" -gt 0 ]; then
+        echo "Fix the issues above and re-run this task."
+        exit 1
+      fi
+    triggeredBy:
+      - manual
+    dependsOn:
+      - installShellcheck

AGENTS.md

@@ -0,0 +1,107 @@
+# AGENTS.md
+
+## Project Overview
+
+This repository is a Linux From Scratch (LFS) build environment. The goal is to compile a complete Linux system from source, following the [LFS book](https://www.linuxfromscratch.org/lfs/).
+
+## Environment
+
+This project runs inside a Gitpod (Ona) dev container based on Ubuntu 24.04.
+
+### Verified Host Tool Versions
+
+| Tool     | Version                          |
+|----------|----------------------------------|
+| bash     | 5.2.21(1)-release                |
+| Binutils | 2.42                             |
+| bison    | 3.8.2                            |
+| gcc      | 13.3.0                           |
+| g++      | 13.3.0                           |
+| glibc    | 2.39                             |
+| make     | 4.3                              |
+
+Run `bash version-check.sh` at any time to re-verify host tool availability.
+
+### Installed Tools
+
+- **opencode** (v1.14.50) — AI coding assistant. Run with `opencode` in any project directory.
+- **shellcheck** (v0.9.0) — Shell script static analysis tool.
+
+## Automations
+
+Defined in `.ona/automations.yaml`.
+
+| Task | Trigger | Description |
+|------|---------|-------------|
+| `installShellcheck` | `postDevcontainerStart` | Installs `shellcheck` if not present |
+| `lintScripts` | manual | Runs `shellcheck` against all `.sh` files in the repo |
+
+### Running the linter
+
+Via the Ona CLI:
+
+```bash
+gitpod automations task start lintScripts
+```
+
+Or directly:
+
+```bash
+find . -name "*.sh" -not -path "./.git/*" | sort | xargs shellcheck -x
+```
+
+The linter checks all shell scripts and reports issues by file. Fix `error` and `warning` level findings before committing. `info` level findings are advisory.
+
+## Agent Guidelines
+
+### General Rules
+
+- Follow the LFS book chapter order. Do not skip steps or reorder package builds unless you have a specific reason documented here.
+- All source packages must be downloaded to `$LFS/sources` and verified against their checksums before building.
+- All builds happen inside `$LFS/sources/<package-dir>`. Clean up build directories after a successful install.
+- Never modify files outside `$LFS` unless explicitly required by the host system setup chapters.
+
+### Environment Variables
+
+Before running any LFS build commands, ensure these are set:
+
+```bash
+export LFS=/mnt/lfs
+export LFS_TGT=$(uname -m)-lfs-linux-gnu
+export PATH=/usr/bin:/bin
+```
+
+For cross-compilation chapters, prepend the toolchain to PATH:
+
+```bash
+export PATH=$LFS/tools/bin:$PATH
+```
+
+### Build Discipline
+
+- Always `cd` into the extracted source directory before configuring or building.
+- Use `make -j$(nproc)` for parallel builds unless a package is known to fail with parallel jobs.
+- After `make install`, return to `$LFS/sources` and remove the build directory.
+- Log build output for any package that fails: `make 2>&1 | tee build.log`.
+
+### Partition and Filesystem
+
+- The LFS partition is expected at `$LFS` (`/mnt/lfs`).
+- Do not run `mkfs` or `fdisk` commands without explicit user confirmation.
+
+### Committing Changes
+
+- Commit scripts, patches, and configuration files — not compiled binaries or source tarballs.
+- Keep `.gitignore` updated to exclude `$LFS/sources/*.tar.*` and build artifacts.
+- Commit messages should state what LFS chapter/step the change relates to.
+- All shell scripts must pass `shellcheck` before committing.
+
+### Using opencode
+
+opencode is available for AI-assisted coding tasks:
+
+```bash
+opencode   # launch in the current directory
+```
+
+Use it for writing build scripts, debugging compilation errors, or generating patches.

version-check.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+export LC_ALL=C
+bash --version | head -n1 | cut -d" " -f2-4
+echo -n "Binutils: "; ld --version | head -n1 | cut -d" " -f3-
+bison --version | head -n1
+gcc --version | head -n1
+g++ --version | head -n1
+ldd --version | head -n1 | cut -d" " -f2-  # glibc version
+make --version | head -n1