# Agent Operations Guide

## Non-negotiable rules

- Host commands are limited to `git`, `docker`, and `curl`. Everything else runs inside the provided wrapper scripts.
- Use `./run/dev.sh` for all development automation (scaffolding, linting, status updates).
- Use `./run/packager.sh` for packaging tasks that require the Cloudron CLI.
- Containers mount the repo at `/workspace`; do not write outside it.

## Images

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

## Common workflows

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

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

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

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

# Open the Cloudron packaging shell (add BUILD=1 to rebuild the image first)
./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.