# Developer Guide for Agentic Coding Agents

This guide provides the necessary context, commands, and conventions for working effectively in the `docker-qmx-fusion` repository.

## 1. Project Overview
This repository maintains the Docker image for QMX-Fusion, based on Chromium. It follows the [LinuxServer.io](https://linuxserver.io) standards. It uses the `s6-overlay` for process management and the `selkies` base image for GUI-in-browser functionality.

## 2. Critical Development Rules
- **NEVER edit auto-generated files directly:**
  - `README.md` (Edit `readme-vars.yml` instead)
  - `Jenkinsfile` (Edit `jenkins-vars.yml` instead)
  - `package_versions.txt` (Auto-generated by CI)
- **Synchronize Dockerfiles:** If you add a package or change logic in `Dockerfile`, ensure the same changes are applied to `Dockerfile.aarch64`.
- **Package Sorting:** Always list packages in `apt-get install` blocks in **alphabetical order**.
- **Changelog:** Every logic or Dockerfile change MUST include an entry in `readme-vars.yml` under the `changelogs` section.

## 3. Build, Lint, and Test Commands

### Build
To build the image locally (amd64):
```bash
docker build --no-cache --pull -t lscr.io/linuxserver/chromium:latest .
```

### Linting
We use `shellcheck` for all shell scripts. Run it on any script you modify:
```bash
shellcheck root/usr/bin/wrapped-chromium
```

### Testing
Container testing is performed using the LinuxServer.io CI tool. To run tests locally, you need the built image and the CI container:
```bash
docker run --rm \
  --shm-size=1gb \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e IMAGE="lscr.io/linuxserver/chromium" \
  -e TAGS="latest" \
  -t ghcr.io/linuxserver/ci:latest \
  python3 test_build.py
```

## 4. Configuration Management (`readme-vars.yml`)
The `readme-vars.yml` file is the source of truth for documentation and container parameters.

### Adding Environment Variables
Add new variables under `opt_param_env_vars` (optional) or `param_env_vars` (required):
```yaml
opt_param_env_vars:
  - { env_var: "CHROME_CLI", env_value: "https://www.linuxserver.io/", desc: "Specify Chromium CLI flags" }
```

### Updating Changelog
Always add a new entry at the top of the `changelogs` list:
```yaml
changelogs:
  - { date: "06.01.26:", desc: "Update logic for X feature." }
```

## 5. Code Style Guidelines

### Shell Scripts (`root/`)
- **Shebang:** Always use `#!/bin/bash`.
- **Indentation:** Use 2 spaces for indentation.
- **Wrapper Pattern:** Follow the pattern in `root/usr/bin/wrapped-chromium`.
- **Cleanup:** Scripts should handle cleanup of temporary files (e.g., Chromium Singleton locks).
- **Security:** Check for privileged mode when necessary:
  ```bash
  if grep -q 'Seccomp:.0' /proc/1/status; then
    # Privileged mode logic
  fi
  ```

### Dockerfiles
- **Base Image:** Use the specified LinuxServer.io base image (e.g., `ghcr.io/linuxserver/baseimage-selkies`).
- **Layer Optimization:** Chain commands with `&& \` and perform cleanup in the same `RUN` block to minimize image size.
- **Cleanup Commands:**
  ```bash
  apt-get autoclean && \
  rm -rf /var/lib/apt/lists/* /var/tmp/* /tmp/*
  ```

### LinuxServer.io Conventions
- **PUID/PGID:** Support for user mapping is handled by the base image; ensure any new files in `root/` are compatible with the `abc` user.
- **S6 Overlay:** Use S6 service files for process management if adding new background services. Ensure `run` scripts are executable (`chmod +x`). In this project, an `nginx` service is used to serve local content.

## 6. Error Handling and Logging
- **Redirection:** In Shell scripts, redirect stderr to stdout or `/dev/null` as appropriate: `"$@" > /dev/null 2>&1`.
- **Exit Codes:** Use `set -e` in complex scripts to exit on failure.
- **Validation:** Validate the existence of binaries or directories before execution.

## 7. Directory Structure
- `/root`: Files here are copied directly to the root of the container image.
- `/root/defaults`: Default configuration files for Openbox and autostart.
- `/root/usr/bin`: Custom scripts and wrappers.
- `/root/etc/services.d`: s6-overlay service definitions.
- `/.github`: CI/CD workflows and issue templates.

## 8. Multi-Architecture Support
- Always update both `Dockerfile` (amd64) and `Dockerfile.aarch64` (arm64).
- Use `lscr.io/linuxserver/qemu-static` to build ARM images on x86 hardware.
- Avoid architecture-specific binaries in `root/` unless handled by logic in scripts.