Scaffold Cloudron packaging workspace

README.md

@@ -10,47 +10,41 @@ This repository scaffolds Cloudron packages for Known Element's portfolio. It pr
 ## Quick start
 
 ```bash
-# Generate all app scaffolds from the catalog
-python3 scripts/new_app.py
+# Build or refresh the devtools image (first run builds automatically)
+./run/dev.sh python --version
 
-# Or regenerate scaffolds via Makefile
-make scaffold
+# Generate or refresh a single app scaffold
+./run/dev.sh python scripts/new_app.py --slug apache-apisix
 
-# Work on a single app skeleton
-python3 scripts/new_app.py --slug apache-apisix
+# Regenerate every scaffold (overwrites existing directories)
+./run/dev.sh python scripts/new_app.py --force
 
-# Update the status table
-make status
+# Lint an app and fail on placeholders
+./run/dev.sh python scripts/lint_repo.py --slug apache-apisix --strict
 
-# Lint generated apps
-make lint
-
-# Run the full CI harness locally
-make ci-local
-
-# Build and enter the Cloudron packager container
-BUILD=1 scripts/run_packager.sh
-scripts/run_packager.sh
+# Update the status dashboard
+./run/dev.sh python scripts/generate_status.py --preserve-timestamp
 ```
 
-Within the container, use the Cloudron CLI to build, test, and publish packages without touching the host environment:
+### Packaging shell
 
 ```bash
-cloudron login my.example.cloudron
-cloudron build
-cloudron install --app my-example
-cloudron push
+# Build the Cloudron packager image (run when Dockerfile changes)
+BUILD=1 ./run/packager.sh
+
+# Launch an interactive Cloudron packaging shell
+./run/packager.sh
 ```
 
-Refer to `docs/PACKAGING_GUIDE.md` for detailed guidance.
+All other development tasks should also use `./run/dev.sh` (pass the desired command after the script). The wrapper will build the devtools image if needed and ensure every command executes inside Docker.
 
-See `docs/APP_STATUS.md` for the automatically generated status table.
 
 ## Repository layout
 
 - `apps/` – generated app scaffolds and metadata
 - `docs/` – playbooks and architecture notes
 - `docs/CI_CD_GITEA.md` – instructions for running CI/CD and publishing images via the Gitea instance
+- `docker/devtools/` – Docker image that runs scaffolding, linting, and status tooling
 - `docker/packager/` – Docker image for Cloudron packaging workflows
 - `scripts/` – helper scripts (scaffolding, tooling entrypoints)
 - `templates/` – base Cloudron app template
@@ -118,11 +112,30 @@ See `docs/APP_STATUS.md` for the automatically generated status table.
 All entries are initially marked as `todo`; update individual READMEs as progress is made.
 
 
-## Local Harness
+## Local Verification
 
-Run `./scripts/ci_local.sh` (or `make ci-local`) to execute the same lint and smoke tests that the future Gitea runner will use. Install git hooks via `./scripts/hooks/install_hooks.sh` so pre-commit, post-commit, and pre-push events invoke the harness automatically. Export `SKIP_CI_HOOKS=1` to bypass them when necessary. See `docs/LOCAL_TESTING.md` for full details.
+Run quality checks via the devtools wrapper:
+
+```bash
+# Fail if placeholders remain in the target manifest/start script
+./run/dev.sh python scripts/lint_repo.py --slug apache-apisix --strict
+
+# Refresh docs/APP_STATUS.md without changing the existing timestamp
+./run/dev.sh python scripts/generate_status.py --preserve-timestamp
+```
+
+Use `./run/packager.sh` whenever you need the Cloudron CLI to build, install, or push packages—it drops you into the dedicated packaging container.
 
 ## CI/CD
 
-Once a runner is provisioned, enable `.gitea/workflows/ci.yml` to call the same harness remotely (it currently requires manual `workflow_dispatch`). Mirror `actions/checkout@v4` and label the runner `ubuntu-22.04`. See `docs/CI_CD_GITEA.md` for setup details.
+The workflow `.gitea/workflows/ci.yml` mirrors the same commands by invoking the devtools container inside the runner. To reproduce the pipeline locally, run:
 
+```bash
+./run/dev.sh python scripts/lint_repo.py --strict --slug apache-apisix
+./run/dev.sh python scripts/generate_status.py --preserve-timestamp
+BUILD=1 ./run/packager.sh    # optional: rebuild packager image before smoke tests
+```
+
+Once a Gitea Actions runner is available, enable the workflow and it will build `knel/cloudron-devtools`/`knel/cloudron-ci` automatically.
+
+Refer to `docs/PACKAGING_GUIDE.md` and `AGENTS.md` for detailed operating procedures.