# 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.
- 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`.

## 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
- 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.

## 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.
- 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.

## 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.