AI Agent Guidelines

Project Overview

This is a LaTeX document project (cheatsheet-systemd) that produces a systemd command reference cheatsheet as PDF, JPG, PNG, and SVG. The primary source is systemd_cheatsheet.tex. The build system uses GNU Make (makefile4latex) and Docker with TeXLive Full.

Build Commands

# Full build via Docker (PDF + JPG + PNG + SVG)
./run.sh

# Build only PDF via Docker
./run.sh pdf

# Verbose Docker build
./run.sh --verbose pdf

# Direct Make targets (requires local TeXLive + poppler-utils)
make pdf         # Build PDF
make jpg png svg # Build image formats
make mostlyclean # Clean temporary files, keep outputs
make clean       # Clean everything including outputs
make lint        # Run ChkTeX LaTeX linter
make pretty      # Format LaTeX with latexindent
make help        # Show all available targets

Lint and Validation Commands

# LaTeX linting
chktex systemd_cheatsheet.tex

# Shell script linting and formatting
shellcheck run.sh
shfmt --case-indent --indent 2 --space-redirects --diff run.sh

# Markdown linting
rumdl ./*.md

# Link checking
lychee --config lychee.toml .

# JSON linting (supports comments)
jsonlint --comments .github/renovate.json5

# GitHub Actions workflow validation
actionlint

# Full CI linting (runs all linters via MegaLinter)
# This runs in CI only; see .mega-linter.yml for configuration

There are no tests in this project. Validation is done through linting and successful LaTeX compilation.

Code Style Guidelines

General

• Indentation: 2 spaces everywhere (no tabs)
• Line length: Wrap at 80 characters for Markdown; wrap at 72 characters for commit messages; no strict limit for LaTeX or shell scripts
• Final newline: All files must end with a newline
• Trailing whitespace: Trim trailing whitespace

LaTeX (.tex)

• Lint with chktex (config in .chktexrc)
• Format with latexindent via make pretty
• Disabled ChkTeX warnings: n1 (command terminated with space), n8 (dash length), n12 (interword spacing), n44 (booktabs)
• Keep document structure simple; use standard packages

Shell Scripts (.sh)

• Start with #!/usr/bin/env bash and set -euo pipefail
• Variables: UPPERCASE with braces (${MY_VARIABLE})
• Formatting: shfmt --case-indent --indent 2 --space-redirects
• Linting: shellcheck (SC2317 excluded globally)
• Quote all variable expansions: "${VARIABLE}"
• Redirect errors to stderr: >&2
• Use command -v to check command existence
• Use cat << EOF heredocs for multi-line output

Markdown (.md)

• Must pass rumdl checks (config in .rumdl.toml)
• Wrap lines at 80 characters
• Use proper heading hierarchy (no skipped levels)
• Include language identifiers in code fences
• Shell code blocks are extracted and validated with shellcheck and shfmt during CI
• CHANGELOG.md is auto-generated; do not edit manually

JSON / YAML

• JSON: must pass jsonlint --comments
• YAML: use --- document separator at top of files
• Both: 2-space indentation

GitHub Actions Workflows

• Validate with actionlint after any modification
• Pin all actions to full SHA commits, never tags
• Set permissions: read-all as default; override minimally
• Always set timeout-minutes on jobs (5 or 10)
• All workflows must support workflow_dispatch
• Add a descriptive comment at the top of each workflow file

Security Scanning

CI runs these security scanners:

• Checkov: IaC scanner (skip CKV_GHA_7)
• DevSkim: Pattern scanner (ignore DS162092, DS137138)
• KICS: Fails only on HIGH severity
• Trivy: HIGH/CRITICAL only, ignores unfixed vulnerabilities
• CodeQL: Runs on pushes to main and weekly
• OSSF Scorecard: Runs on pushes to main and weekly

Version Control

Commit Messages

Use conventional commit format with these rules:

• Types: feat, fix, docs, chore, refactor, test, style, perf, ci, build, revert
• Format: <type>: <description> (imperative mood, lowercase)
• Subject line: maximum 72 characters, no trailing period
• Body: wrap at 72 characters, explain what and why
• Reference issues: Fixes #123, Closes #123, Resolves #123

feat: add automated dependency updates

- Implement Dependabot configuration
- Configure weekly security updates

Resolves: #123

Branching

Follow Conventional Branch format: <type>/<description>

• feature/ or feat/: new features
• bugfix/ or fix/: bug fixes
• hotfix/: urgent fixes
• release/: release prep (e.g., release/v1.2.0)
• chore/: non-code tasks

Use lowercase, hyphens, no consecutive/leading/trailing hyphens. Include issue numbers when applicable: feature/issue-123-description

Pull Requests

• Always create as draft initially
• Title must follow conventional commit format
• Include clear description of changes and motivation
• Link related issues with Fixes, Closes, or Resolves