fix(clean-env): point the vendored skill at a script that exists

.claude/skills/clean-env/SKILL.md

@@ -5,14 +5,18 @@ description: Reset the OpenRegister development environment (stop, remove volume
 
 # Clean Environment
 
-Run the `clean-env.sh` script to fully reset the OpenRegister development environment.
+Reset the Conduction dev instance and bring it back up healthy.
 
-This will:
-1. Stop all containers from the OpenRegister docker-compose
-2. Remove all containers and volumes (full data reset)
-3. Start containers fresh
-4. Wait for Nextcloud to become ready
-5. Install core apps: openregister, opencatalogi, softwarecatalog, nldesign, mydash
+> **This skill used to name a script that does not exist.** It said to run
+> `bash .claude/scripts/clean-env.sh`; there is no such file in this repo or in
+> any app checkout, and there never was one to find. Its documented app list was
+> five entries long (`openregister opencatalogi softwarecatalog nldesign
+> launchpad`) at a time when the fleet was twenty-one and three of those five
+> names were app *directories* rather than app ids. Anyone following it got a
+> "command not found" if they were lucky and a half-configured instance if they
+> improvised past it. The real, maintained entry point is
+> `.github/dev-up.sh` — it is the one place that knows about the mounts, the
+> vendored PHP dependencies and the frontend bundles.
 
 **Model check — only apply when this skill is run standalone. Skip this section entirely if this skill was called from within another skill — the calling skill is responsible for model selection.**
 
@@ -27,22 +31,70 @@ This will:
 
 ## Instructions
 
-Run the clean-env script:
+Work from the workspace root (the directory holding `.github/` and the app
+checkouts as siblings).
+
+### Restart and heal — the common case
+
+Most "my environment is broken" reports need only this. It re-establishes
+partial mounts, clears maintenance mode, runs pending migrations, installs any
+missing `vendor/`, enables every mounted Conduction app and reports any app
+whose frontend bundle would render blank:
+
+```bash
+bash .github/dev-up.sh
+```
+
+### Full reset — destructive
+
+**This deletes the database and every volume.** Only run it when a full reset is
+actually intended; `dev-up.sh` alone fixes most breakage.
 
 ```bash
-bash .claude/scripts/clean-env.sh
+docker compose -p openregister -f .github/docker-compose.yml down -v
+bash .github/dev-up.sh
 ```
 
-**Important:** This is a destructive operation — it removes all database data and volumes. Only run when a full reset is intended.
+## Verifying
 
-After the script completes, verify the environment:
-1. Check that Nextcloud is accessible at http://nextcloud.local
-2. Log in with admin/admin
-3. Confirm apps are listed and enabled
+`dev-up.sh` ends in a status block — read it rather than assuming success:
+
+- `needsDbUpgrade: false` — an instance stuck at `true` serves a 503 the moment
+  anything trips maintenance mode.
+- `apps visible: N/N` — a shortfall is named per app, and it says whether the
+  cause is an empty checkout (clone it) or a mount that did not attach.
+- `apps enabled:` plus any `⚠` lines. **A `⚠ … need a frontend rebuild` line
+  means those apps are enabled and still render a blank page** — `occ` reports
+  them as perfectly healthy. Run the `npm ci && npm run build` command the
+  script prints for each one.
+
+Then open http://localhost:8080 (admin/admin) and confirm the apps appear in the
+app menu.
+
+## If an app still fails to enable
+
+`dev-up.sh` prints the actual `occ` error per app; act on that rather than
+retrying. The two failures that recur:
+
+- **`Class "…" not found`** — the app's `vendor/` is missing or half-installed.
+  `(cd <app-dir> && composer install --no-dev --ignore-platform-reqs)`. If
+  composer dies on `Could not delete …/vendor/…`, the tree contains root-owned
+  files from a container-side composer run; `dev-up.sh` heals that on its next
+  run.
+- **`SKIP <app> — empty checkout`** — the directory is mounted but empty. Clone
+  the repo into it, or drop its mount from `.github/docker-compose.yml`.
+
+To enable one by hand (note `-u www-data` — without it `occ` runs as root and
+refuses):
 
-If any app fails to enable, try running manually:
 ```bash
-docker exec nextcloud php occ app-enable <appname>
+docker exec -u www-data nextcloud php occ app:enable <app-id>
 ```
 
+Use the app **id** (`integriq`, `filinq`, `dossiq`, `stackiq`, `keepiq`,
+`larpinq`, `learniq`, `decidiq`, `buildiq`, `humaniq`), not the checkout
+directory name (`openconnector`, `docudesk`, `procest`, …). The id is the `<id>`
+in `appinfo/info.xml`; a wrong name is not an error you will notice, because
+`occ app:enable` on an unknown app just does nothing useful.
+
 > 💡 If you switched models to run this command, don't forget to switch back to your preferred model with `/model <name>` (e.g. `/model default` or `/model sonnet`).

.claude/skills/clean-env/examples/expected-output.md

@@ -1,64 +1,85 @@
-<!-- Example output — clean-env skill for OpenRegister development environment -->
+<!-- Example output — clean-env skill for the Conduction development environment -->
 
 # Expected Output: clean-env
 
+Captured from a real run on 2026-08-27, not written from memory. The previous
+version of this file showed a script that does not exist writing "✓ All apps
+installed" against five app names, at a URL (`http://nextcloud.local`) the
+instance does not serve — an example nobody could ever have produced.
+
 ## Successful run
 
 ```
-$ bash .claude/scripts/clean-env.sh
-
-[clean-env] Stopping containers...
-Stopping nextcloud ... done
-Stopping nextcloud_db ... done
-✓ Containers stopped
+$ bash .github/dev-up.sh
 
-[clean-env] Removing containers and volumes...
-Removing nextcloud ... done
-Removing nextcloud_db ... done
-Removing volume nextcloud_nextcloud_data ... done
-Removing volume nextcloud_db_data ... done
-✓ Containers and volumes removed
+==> Starting stack (project=openregister)
+==> Waiting for the DB
+==> Waiting for all 36 app mounts inside the container
+  only 34/36 app dirs visible
+    collectives: EMPTY CHECKOUT at openregister/custom_apps/collectives -- clone it or drop its mount; restarting cannot help
+    zaakafhandelapp: EMPTY CHECKOUT at zaakafhandelapp -- clone it or drop its mount; restarting cannot help
+  every missing dir is an empty checkout, not a mount failure -- not restarting
+==> Ensuring un-busted assets are not cached for 6 months
+  ok
+==> Ensuring custom_apps is writable by www-data
+  ok
+==> Clearing maintenance mode
+==> Reconciling pending app upgrades (only if needed)
+  no upgrade needed
+==> Healing PHP dependencies (vendor/)
+  stackiq: no vendor/autoload.php -- installing
+    ok
+==> Ensuring Conduction apps are enabled
+  enabling keepiq (disabled)
+    ok
+  enabling integriq (disabled)
+    ok
+  enabling stackiq (disabled)
+    ok
+  SKIP zaakafhandelapp -- empty checkout at ../zaakafhandelapp (nothing to enable)
+==> Re-reconciling upgrades (enabling an app can register a migration)
+  no upgrade needed
+==> Checking frontend bundles match the app id
+  ok
+==> Done. Status:
+      - installed: true
+      - version: 34.0.0.12
+      - maintenance: false
+      - needsDbUpgrade: false
+    apps visible:  34/36
+    apps enabled:  71
+    UI: http://localhost:8080   (admin/admin)
+```
 
-[clean-env] Starting fresh containers...
-Creating network "openregister_default" with the default driver
-Creating volume "nextcloud_db_data"    ... done
-Creating volume "nextcloud_nextcloud_data" ... done
-Creating nextcloud_db ... done
-Creating nextcloud    ... done
-✓ Containers started
+## What a problem looks like
 
-[clean-env] Waiting for Nextcloud to become ready...
-..........
-✓ Nextcloud is ready at http://nextcloud.local
+The script does not hide these; read to the end of the output.
 
-[clean-env] Installing apps...
-openregister installed and enabled.
-opencatalogi installed and enabled.
-softwarecatalog installed and enabled.
-nldesign installed and enabled.
-mydash installed and enabled.
-✓ All apps installed
+An app that is enabled and would still render a blank page — `occ` calls this
+app perfectly healthy, so this section is the only thing that reports it:
 
-[clean-env] Done! Environment is clean and ready.
+```
+==> Checking frontend bundles match the app id
+  integriq: js/integriq-main.js missing (found openconnector-main.js -- stale, pre-rename)
+    fix: (cd ../openconnector && npm ci && npm run build)
+...
+    ⚠ 5 app(s) need a frontend rebuild before their page renders
 ```
 
-## Post-script verification
+An app that refused to enable, with the reason rather than a shrug:
 
 ```
-✅ Nextcloud accessible at http://nextcloud.local
-✅ Logged in with admin/admin
-✅ Apps enabled and active:
-   - openregister     ✓
-   - opencatalogi     ✓
-   - softwarecatalog  ✓
-   - nldesign         ✓
-   - mydash           ✓
+  enabling keepiq (disabled)
+    FAILED: An unhandled exception has been thrown: Error: Class "Ramsey\Uuid\Uuid" not found in …/keepiq/lib/Repair/SeedSecretTypes.php:115
+  1 app(s) could not be enabled -- see the errors above
 ```
 
-## If an app fails to enable
+The stack failing to start at all — note that a **public** image answers
+`denied: denied` when the local ghcr.io credential has expired, so the script
+logs out and retries once before believing it:
 
-```bash
-# Re-enable manually:
-docker exec nextcloud php occ app:enable openregister
-docker exec nextcloud php occ app:enable opencatalogi
+```
+==> Starting stack (project=openregister)
+    Error response from daemon: Head "https://ghcr.io/v2/conductionnl/n8n-nextcloud/manifests/latest": denied: denied
+  ghcr.io denied a pull -- logging out (credentials may be stale) and retrying once
 ```