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.
Host is read-only: do not install or modify anything on the host OS. You MAY only check for the presence of tools and run them if already installed.
Allowed host tools (if present): docker, git, tea (optional), and curl for connectivity checks. Never attempt to install or upgrade them.
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.

Commits: frequent, small, and descriptive commits are encouraged; no approval needed for local commits.
After validation, present a concise summary of changes and validation output to the maintainer and request permission to push.
Push only at “natural” points (coherent, validated milestones). Examples:
- First green build of a new package scaffold (image builds + container starts + health OK).
- A feature-complete slice (e.g., addon integration added and tested).
- A bug fix with verification.
- Pre-release stabilization checkpoint.
Batch pushes to avoid noise (aim for 1–3 pushes per active app per work session).
NEVER push a broken or non‑validated build.
Only on explicit approval run git push origin main for package-affecting changes.
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.
Host-level curl allowance: You MAY use curl on the host strictly for quick connectivity checks IF it is already installed. Do not install any host packages.
Do not attempt other host-level network configuration, filesystem changes outside the repo, 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.