docs: add AGENTS.md (agent operating guide: container-only, approval before push)

AGENTS.md

@@ -0,0 +1,69 @@
+# 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.
+
+## Golden Rules
+- 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`.
+
+## Container-Only Workflow
+- 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`.
+
+## Creating a New Package
+- 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.
+
+## Validation Checklist (must pass before proposing push)
+- 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.
+
+## Approval Gate and Push Policy
+- 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.
+
+## Repository Hygiene
+- 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`).
+
+## Networking & External Access
+- 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.
+
+## Commit Messages
+- 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.
+
+## When in Doubt
+- Ask for maintainer guidance before introducing new tools, dependencies, or changing global structure.
+- Default to safer, smaller changes and explicit approval before pushing.
+