# Agent Operations Guide

## Non-negotiable rules

- Host commands are limited to `git`, `docker`, and `curl`. Everything else runs inside the provided wrapper scripts.
- Use `./output/run/dev.sh` for all development automation (scaffolding, linting, status updates).
- Use `./output/run/packager.sh` for packaging tasks that require the Cloudron CLI.
- Containers mount the repo at `/workspace`; do not write outside it.
- Keep collaboration artifacts under `collab/` and agent-owned generated outputs under `output/`; treat these as the only top-level workspaces for coordination versus deliverables.

## Images

- `knel/cloudron-devtools` – built automatically by `./output/run/dev.sh`; contains Python tooling.
- `knel/cloudron-packager` – built automatically by `./output/run/packager.sh`; contains the Cloudron CLI.

## Common workflows

```bash
# Generate/refresh a scaffold
./output/run/dev.sh python output/scripts/new_app.py --slug apache-apisix

# Regenerate the full catalog (overwrites existing scaffolds)
./output/run/dev.sh python output/scripts/new_app.py --force

# Lint an app (fails on TODO placeholders)
./output/run/dev.sh python output/scripts/lint_repo.py --slug apache-apisix --strict

# Refresh output/docs/APP_STATUS.md without changing the timestamp
./output/run/dev.sh python output/scripts/generate_status.py --preserve-timestamp

# Open the Cloudron packaging shell (add BUILD=1 to rebuild the image first)
./output/run/packager.sh
```

## Notes

- The first invocation of either wrapper builds the corresponding Docker image if it is missing.
- Update documentation whenever command sequences change so future agents stay aligned.