AGENTS.md — how changes are made in this repo

This file is read by AI agents (via opencode) and by human developers. Follow it.

What this repo is

The public homepage served at homepage.ffaerber.duckdns.org. The site is built into a Docker image, pushed to this Gitea instance's container registry, and deployed via the homelab stack (ffaerber/homelab). This repo holds the website source and its Dockerfile/build; it does not hold the deployment stack itself.

Golden rules

You may edit any file in this repo (site source, Dockerfile, .gitea/ workflows).
NEVER push to main, and NEVER merge a pull request. All work goes on a branch and becomes a PR that a human reviews and merges. You do not have merge authority — do not attempt it.
Never print, exfiltrate, or invent secret values. You may edit config that references secrets, but never paste real secret values into comments, PRs, logs, or code.
Keep changes minimal and match the conventions already in the file you're editing.
Do the work on a branch — never paste code or diffs into the issue thread.
The repo is public and the built image is public, so it can be pulled without registry credentials. Do not add anything secret to the image or the source.

Branches & pull requests

You start on branch ai/issue-<N> (N = the issue number).

Split independent changes into separate PRs so each can be reviewed and shipped on its own. For each independent change, use its own branch:

git checkout main
git checkout -b ai/issue-<N>-<short-slug>      # e.g. ai/issue-3-nav, ai/issue-3-styles
# make just that one change
git add -A && git commit -m "<what changed>" && git push -u origin HEAD

Only keep changes together on one branch if they genuinely must ship as a unit.
Commit and push incrementally as you work, so progress is visible on the branch.
Do not open pull requests yourself — the automation opens one PR per branch you push, and the maintainer merges them sequentially.

PR description

End your reply with a clean pull-request description wrapped EXACTLY between these markers. Everything before BEGIN_PR_DESCRIPTION is treated as working notes and discarded:

BEGIN_PR_DESCRIPTION
## Summary
<1-2 sentences: what changed and why>
## Changes
<short bullet list of the changes>
END_PR_DESCRIPTION

Do not paste full files or large diffs — the review happens in the PR diff.

Build & deploy

The site is packaged by a Dockerfile at the repo root (add one when the site source lands).
On merge to main, CI builds the image and pushes it to the Gitea container registry; the homelab stack then pulls and serves it at homepage.ffaerber.duckdns.org.
Keep the image small and the build reproducible. Prefer a static-site build served by a minimal web server (e.g. nginx) unless an issue says otherwise.

When unsure

If the task is genuinely unclear or missing details you cannot reasonably assume, make no changes and reply with specific questions instead.

3.0 KiB Raw Blame History