Agent Operating Guide (Project-wide)

Scope: This file applies to the entire repository. It defines how assistants and automation must work here.

Purpose

Package ~100 free/libre/open-source applications as Cloudron apps with a fast, container-only workflow and a minimal, single-branch repo.

Single branch: use only main. Do not create feature branches unless explicitly requested.
No host pollution: never install packages or tools on the host. The only required host tools are docker, git (and optionally tea).
Containers only: all build, test, lint, and packaging commands must run inside the packaging container.
Do not push to remote without approval: never run git push for a package change until it has been validated and explicitly approved by the maintainer.
Keep repo slim: do not commit upstream source trees or build artefacts. Only commit package files under CloudronPackages/<AppName>/, small helper scripts, and minimal docs.
Secrets: do not commit secrets or credentials. Use environment variables or Cloudron addons.
Consistency: follow .editorconfig, .gitattributes, and .gitignore.

Packaging image: built from docker/packaging/Dockerfile.
Control scripts (host-side wrappers):
- scripts/packaging-up.sh – build and start the packaging container; mounts repo at /workspace and /var/run/docker.sock.
- scripts/packaging-enter.sh – open a shell inside the container.
- scripts/packaging-exec.sh <cmd> – run any command inside the container.
- scripts/workspace-clone.sh – clone upstream repos (inside container).
- scripts/workspace-update.sh – update upstream repos (inside container).
Never run package build/test outside the container. If a command needs to run, wrap it via scripts/packaging-exec.sh.

Scaffold from template using the helper:
- scripts/new-package.sh <AppName> --id <com.example.app> --title "Title" --port <port> [--base <cloudron_base_tag>]
Edit CloudronPackages/<AppName>/Dockerfile and start.sh to run the app.
Prefer prebuilt upstream releases over building toolchains in Docker to keep images small.
Default Cloudron base image tag is 5.0.0. Override with --base as needed.

Build succeeds inside the packaging container:
- scripts/packaging-exec.sh "docker build -t <app>:dev CloudronPackages/<AppName>"
Run sanity check inside container:
- scripts/packaging-exec.sh "docker run --rm -p <hp>:<hp> -v <app>-data:/app/data <app>:dev"
- Health endpoint responds; logs show no fatal errors; app starts with least privilege.
Manifest sanity: CloudronManifest.json has accurate id, version, httpPort or addon definitions, and healthCheckPath.
No secrets or hard-coded credentials; proper ownership of /app/data.
Image hygiene: no unnecessary build deps; minimal layers; correct exposed ports.
Optional: cloudron install --image <app>:dev tested from inside the packaging container using cloudron CLI, if available.

After validation, present a summary of what changed and the validation output to the maintainer.
Only on explicit approval run git push origin main for the package commit(s).
Never force-push unless explicitly instructed.

Do not commit upstream repos. The directories PackagingForCloudronWorkspace/Docker/ and PackagingForCloudronWorkspace/NonDocker/ are gitignored on purpose.
Keep package directories focused: CloudronManifest.json, Dockerfile, start.sh, and minimal config (e.g., nginx.conf, supervisord.conf, config.yaml, logo.png).
Use LF line endings and 2-space indentation (see .editorconfig/.gitattributes).

All networked actions (git clones, docker pulls, downloads) must happen from within the packaging container.
Do not attempt host-level network configuration or host-level package installation.

Use conventional, concise messages:
- feat(<app>): ... for new packages or features
- fix(<app>): ... for fixes
- chore(...), docs(...) for non-functional changes
Avoid large, mixed commits; keep changes scoped to an app.

Ask for maintainer guidance before introducing new tools, dependencies, or changing global structure.
Default to safer, smaller changes and explicit approval before pushing.