Restructure repository into output workspace

output/docs/PACKAGING_GUIDE.md

@@ -0,0 +1,95 @@
+# Cloudron Packaging Playbook
+
+This repository standardises the workflow for building and maintaining Cloudron packages for the Known Element portfolio.
+
+## Reference workflow
+
+1. Build or refresh the devtools image when dependencies change:
+   ```bash
+   ./output/run/dev.sh python --version
+   ```
+2. Enter an interactive devtools shell so every command runs inside Docker:
+   ```bash
+   ./output/run/dev.sh bash --login
+   ```
+3. Implement application-specific build steps in `output/apps/<slug>/Dockerfile` and configure runtime behaviour through `start.sh`.
+4. Update `CloudronManifest.json` with accurate metadata, addons, ports, and health checks.
+5. Build and test using the devtools shell or one-off wrappers.
+6. Push new images via the Cloudron packager shell when smoke tests pass.
+
+## Cloudron packaging essentials
+
+- **Base image:** The runtime stage **must** derive from `cloudron/base:<version>`; use a dedicated builder stage to compile artefacts and copy only what you need.
+- **CloudronManifest:** Declare metadata, exposed ports, resource limits, addons, and health checks. Keep `id` stable and set realistic limits per app.
+- **Start script:** Render configuration from environment variables and launch the primary process as `cloudron`.
+- **Tests:** Provide smoke tests in `test/` so `cloudron build --test` can validate deployments.
+- **Updates:** Bump the manifest `version`, document the change in `changelog`, and rebuild for upstream releases.
+
+## Repository linting
+
+Run lint checks entirely through the devtools wrapper:
+
+```bash
+./output/run/dev.sh python output/scripts/lint_repo.py --slug apache-apisix --strict
+```
+
+Add `--base-prefix` if you intentionally change the final base image prefix.
+
+## Common workflows
+
+Interactive session (recommended while iterating):
+
+```bash
+./output/run/dev.sh bash --login
+
+# inside the container
+python output/scripts/new_app.py --slug apache-apisix
+python output/scripts/new_app.py --force
+python output/scripts/lint_repo.py --slug apache-apisix --strict
+python output/scripts/generate_status.py --preserve-timestamp
+```
+
+Non-interactive equivalents:
+
+```bash
+./output/run/dev.sh python output/scripts/new_app.py --slug apache-apisix
+./output/run/dev.sh python output/scripts/new_app.py --force
+./output/run/dev.sh python output/scripts/lint_repo.py --slug apache-apisix --strict
+./output/run/dev.sh python output/scripts/generate_status.py --preserve-timestamp
+```
+
+## Using the packager container
+
+Open the Cloudron packaging environment via:
+
+```bash
+./output/run/packager.sh
+```
+
+Pass `BUILD=1` to rebuild the image before launching (`BUILD=1 ./output/run/packager.sh`). Use this shell for `cloudron build`, `cloudron install`, and `cloudron push` operations.
+
+## Adding a new application
+
+Generate scaffolds with the devtools wrapper:
+
+```bash
+./output/run/dev.sh python output/scripts/new_app.py --force           # regenerate entire catalog
+./output/run/dev.sh python output/scripts/new_app.py --slug apache-apisix
+```
+
+Each scaffold contains:
+
+- `Dockerfile` – multi-stage build instructions
+- `start.sh` – runtime entrypoint
+- `CloudronManifest.json` – metadata and permissions
+- `test/smoke.sh` – placeholder smoke test
+- `metadata.json` – issue and upstream bookkeeping
+- `README.md` – packaging checklist
+
+Update these files with app-specific details, add artefacts under `app/`, and commit the changes.
+
+## Repository etiquette
+
+- Document design decisions and manual steps in `output/docs/` or the per-app README.
+- Keep automation scripts idempotent; rerunning them should not damage uncommitted work.
+- Use semantic versioning in manifest files (`MAJOR.MINOR.PATCH`).