diff --git a/AI.md b/AI.md
index 6c1e27b..e972c0a 100644
--- a/AI.md
+++ b/AI.md
@@ -1,607 +1,514 @@
-# Docker Container Repository Specification
+# CasjaysDev Docker Application Image Specification (casjaysdevdocker)
 
-## Repository Overview
+**Name**: {name}
 
-**Repository:** casjaysdevdocker  
-**Maintainer:** CasjaysDev <docker-admin@casjaysdev.pro>  
-**License:** WTFPL / MIT  
-**Purpose:** Collection of containerized applications using standardized Alpine-based templates
+**About this file:** This is the complete, authoritative specification for a CasjaysDev
+Docker **application image** repository (`casjaysdevdocker/{name}`). It is a master
+template — copied into an app image repo as that repo's `AI.md`. It is **permanent** —
+never delete it from a repo that carries it.
+
+**Note:** `{name}` in this file is a reference token, not setup-time replacement text. Its
+value is always the repo directory basename (`basename "$PWD"`).
+
+**Maintenance procedure:** The bootstrap/update runbook (regenerating files after upstream
+template changes, creating new repos) is NOT in this file — it lives in the
+`dockersrc-bootstrap` agent (it handles both repo families via `REPO_TYPE` detection).
+This file defines the standards that procedure enforces.
 
 ---
 
-## Repository Structure
+# PART INDEX
 
-This repository contains multiple Docker container projects organised as subdirectories. Each project follows a consistent structure and naming convention.
-
-### Directory Layout
-
-```
-casjaysdevdocker/
-├── ampache/           # Media streaming server
-├── apprise/           # Notification service
-├── aria2/             # Download manager
-├── bind/              # DNS server
-├── bun/               # JavaScript runtime
-├── caddy/             # Web server
-├── code/              # VS Code server
-├── couchdb/           # NoSQL database
-├── ddns/              # Dynamic DNS client
-├── deno/              # JavaScript runtime
-├── docker/            # Docker-in-Docker
-├── enclosed/          # Encrypted note sharing
-├── forgejo/           # Git forge
-├── gitea/             # Git service
-├── gotify/            # Push notification server
-├── i2pd/              # I2P router
-├── icecast/           # Audio streaming
-├── ifconfig/          # IP info service
-├── jekyll/            # Static site generator
-├── lighttpd/          # Web server
-├── mailman/           # Mailing list manager
-├── mariadb/           # SQL database
-├── mongodb/           # NoSQL database
-├── mpd/               # Music player daemon
-├── mysql/             # SQL database
-├── navidrome/         # Music streaming
-├── neovim/            # Text editor
-├── nextcloud/         # Cloud storage
-├── nginx/             # Web server
-├── nodejs/            # Node.js runtime
-├── ntfy/              # Notification service
-├── ollama/            # LLM runtime
-├── opencloud/         # Cloud platform
-├── opengist/          # Gist clone
-├── pastebin/          # Pastebin service
-├── php/               # PHP runtime
-├── podman/            # Container runtime
-├── postfix/           # Mail server
-├── postgres/          # SQL database
-├── proftpd/           # FTP server
-├── python/            # Python runtime
-├── redis/             # In-memory database
-├── soft-serve/        # Git server
-├── sqlite/            # SQL database
-├── ssl-ca/            # SSL certificate authority
-├── tftpd/             # TFTP server
-├── tor/               # Tor relay
-├── traefik/           # Reverse proxy
-├── transmission/      # BitTorrent client
-├── valkey/            # Redis fork
-├── vim/               # Text editor
-├── webmin/            # Web admin interface
-├── wordpress/         # CMS platform
-├── wttr/              # Weather service
-├── xfce4/             # Desktop environment
-├── ympd/              # MPD web client
-├── youtube-dl/        # Video downloader
-└── tools/             # Shared tools & scripts
-```
+| PART | Title |
+|------|-------|
+| 0 | Critical rules |
+| 1 | Repository model & structure |
+| 2 | Template system reference |
+| 3 | Tooling — gen-dockerfile & gen-script |
+| 4 | `.env.scripts` reference |
+| 5 | Runtime system — setup scripts, entrypoint, init.d |
+| 6 | README.md standard layout |
+| 7 | CI/CD workflows |
+| 8 | Verification & commit |
 
 ---
 
-## Standard Project Structure
+# PART 0: CRITICAL RULES
 
-Each project directory contains:
+## Org mapping
+
+| System | Org | Example |
+|--------|-----|---------|
+| GitHub (source) | `casjaysdevdocker` | `https://github.com/casjaysdevdocker/{name}` |
+| Docker Hub (push) | `casjaysdevdocker` | `casjaysdevdocker/{name}` |
+
+`casjaysdevdocker` repos are **applications** (gitea, opengist, super-productivity,
+ampache, aria2, …). They always build FROM the pre-built, multi-arch `casjaysdev/*` base
+images — never directly from upstream distro images. The bases themselves live in the
+separate `dockersrc` org (GitHub `dockersrc/{base}` → Docker Hub `casjaysdev/{base}`) —
+see the base specification (`DOCKERSRC.md`).
+
+## Non-negotiable rules
+
+1. **`AI.md` is permanent** — never delete it from the repo.
+2. **Generated files are owned by the template system** — never hand-tune content that
+   `gen-dockerfile` regenerates (see PART 1 ownership table); fix the upstream
+   `gen-dockerfile` template instead, then regenerate.
+3. **Hand-crafted files are owned by the repo** — `gen-dockerfile` must never overwrite
+   app-specific init.d scripts, custom bin scripts, a `05-custom.sh` with real content, or
+   a hand-crafted README (PART 6).
+4. **Removed OCI labels stay removed** (PART 2) — never re-add `base.name`,
+   `schema-version`, or duplicate `authors`/`source` entries.
+5. **`image.url` is a browsable page** — `https://hub.docker.com/r/casjaysdevdocker/{name}`.
+   `docker.io` is only a registry pull host; it is never a label URL.
+6. **`image.source` and `image.documentation` are the GitHub repo** —
+   `https://github.com/casjaysdevdocker/{name}`.
+7. **One Dockerfile, one file set** — app repos build one image (`latest` + date tag);
+   version variants (`Dockerfile.{ver}`) belong to base repos only.
+8. **Always `FROM casjaysdev/<base>`** — never pull an upstream distro image directly;
+   the base repos exist so every app shares one patched, multi-arch foundation.
+9. **Only `root/`, `tmp/`, and `usr/` may exist at `rootfs/` top level** (PART 1).
+10. **Maintenance runs through the `dockersrc-bootstrap` agent** — do not improvise the
+    update procedure from memory.
+
+---
+
+# PART 1: REPOSITORY MODEL & STRUCTURE
+
+## What an app image repo is
+
+A `casjaysdevdocker/{name}` repo containerizes one application on top of a
+`casjaysdev/*` base. It publishes a single image (`casjaysdevdocker/{name}:latest` plus a
+date tag) — no per-version Dockerfile variants. The application itself is installed in
+`05-custom.sh` and started by one or more init.d service scripts.
+
+## Standard tree
 
 ```
-project-name/
-├── .dockerignore              # [generated] Docker build exclusions
-├── .env.scripts               # [generated] Environment variables for gen-dockerfile
-├── .git/                      # Git repository
-├── .gitattributes             # [generated] Git attributes
+{name}/
+├── AI.md                          # This specification (permanent)
+├── Dockerfile                     # [generated] single build file
+├── .dockerignore                  # [generated]
+├── .env.scripts                   # [generated] build config
+├── .gitattributes                 # [generated]
 ├── .gitea/workflows/
-│   ├── docker.yaml            # [hand-crafted] Legacy CI workflow — do not overwrite
-│   └── build.yml              # [generated] by gen-dockerfile actions — regenerate freely
-├── .gitignore                 # [generated] Git ignore patterns
-├── Dockerfile                 # [generated] Container build definition
-├── LICENSE.md                 # License information
-├── README.md                  # [generated] Project documentation
-└── rootfs/                    # Container filesystem overlay
-    ├── root/docker/setup/     # [generated] Build-time setup scripts
-    │   ├── 00-init.sh
-    │   ├── 01-system.sh
-    │   ├── 02-packages.sh
-    │   ├── 03-files.sh
-    │   ├── 04-users.sh
-    │   ├── 05-custom.sh
-    │   ├── 06-post.sh
-    │   └── 07-cleanup.sh
+│   └── build.yml                  # [generated] gen-dockerfile actions
+├── .gitignore                     # [generated]
+├── LICENSE.md                     # License (WTFPL / app's own license)
+├── README.md                      # [generated*] standard layout (PART 6)
+└── rootfs/                        # Container filesystem overlay
+    ├── root/docker/setup/         # [generated*] build-time setup scripts 00–07
+    ├── tmp/                       # staged files installed at build time (optional)
     └── usr/local/
-        ├── bin/
-        │   ├── entrypoint.sh      # [generated] Container entrypoint
-        │   └── pkmgr              # [generated] Package manager wrapper
-        ├── etc/docker/
-        │   ├── functions/
-        │   │   └── entrypoint.sh  # [generated] Entrypoint functions
-        │   └── init.d/            # [hand-crafted] Runtime init scripts (one per service)
-        └── share/template-files/  # [hand-crafted] Config/data templates
-            ├── config/
-            ├── data/
-            └── defaults/
+        ├── bin/                   # [generated*] entrypoint.sh, pkmgr, symlink, copy,
+        │                          #   healthcheck + [hand-crafted] app-specific scripts
+        └── etc/docker/
+            ├── env/               # [hand-crafted] build/runtime env fragments (optional)
+            ├── functions/
+            │   └── entrypoint.sh  # [generated] entrypoint function library
+            └── init.d/            # [hand-crafted] runtime init scripts (one per service)
 ```
 
-**`[generated]`** — safe to overwrite with `gen-dockerfile --update`; changes will be lost on next regeneration.  
-**`[hand-crafted]`** — must not be overwritten by gen-dockerfile; customised per container.
+`[generated]` — safe to regenerate; local edits will be lost.
+`[generated*]` — regenerated from the template, EXCEPT files carrying repo-specific
+content (`05-custom.sh` with a real body, extra bin scripts, a hand-crafted README) —
+those follow the hand-crafted rules in PARTs 5 and 6.
+`[hand-crafted]` — never overwritten by the template system.
+
+App repos may additionally carry project files (`IDEA.md`, `CLAUDE.md`, `TODO.AI.md`)
+per the global project conventions — they are repo-owned and never touched by tooling.
+
+## rootfs top-level policy
+
+The only valid directories at the `rootfs/` root are `root/`, `tmp/`, and `usr/`.
+Anything else is a leftover from old patterns. Migration map:
+
+| Old rootfs path | Correct rootfs path |
+|-----------------|---------------------|
+| `rootfs/etc/{path}` | `rootfs/tmp/etc/{path}` |
+| `rootfs/config/{path}` | `rootfs/tmp/etc/{path}` |
+| `rootfs/data/{path}` | `rootfs/tmp/var/{path}` |
+| `rootfs/var/{path}` | `rootfs/tmp/var/{path}` |
+| `rootfs/opt/{path}` | `rootfs/tmp/opt/{path}` |
+| `rootfs/share/{path}` | `rootfs/usr/local/share/{path}` |
+
+`rootfs/usr/local/share/template-files/` is retired — the `DEFAULT_TEMPLATE_DIR`,
+`DEFAULT_FILE_DIR`, `DEFAULT_DATA_DIR`, and `DEFAULT_CONF_DIR` variables were removed
+from the template system; the entrypoint installs staged files from `rootfs/tmp/etc/`
+at container start instead.
+
+## Repo type detection
+
+A repo is an **app** repo when no `Dockerfile.*` variant files exist:
+
+```bash
+if find . -maxdepth 1 -name 'Dockerfile.*' -type f | grep -q -- .; then
+  REPO_TYPE="base"
+else
+  REPO_TYPE="app"
+fi
+```
 
 ---
 
-## gen-dockerfile Tool
+# PART 2: TEMPLATE SYSTEM REFERENCE
 
-All containers are built using the **gen-dockerfile** tool. It generates standardised Dockerfiles, `.env.scripts`, workflow YAML, `pkmgr` scripts, and `rootfs/` scaffolding.
-
-### Usage
+Templates ship with `gen-dockerfile`, installed at
+`/usr/local/share/CasjaysDev/scripts/templates/dockerfiles/`
+(`$CASJAYSDEVDIR/templates/dockerfiles/` in a dev checkout). To inspect what the current
+templates produce, generate a fresh reference tree in a temp dir:
 
 ```bash
-gen-dockerfile [options] [template] [Dockerfile]
-gen-dockerfile --dir ./myapp alpine
-gen-dockerfile --dir ./myapp --nginx --tag 1.25
-gen-dockerfile --dir ./existing-project --update
-gen-dockerfile --dir ./myapp actions
+gen-dockerfile /tmp/gen-dockerfile/{org}/{repo} {distro}
 ```
 
-### Templates (positional argument or `--template`)
+See `gen-dockerfile --help` for supported distros/types. Keep this PART in sync whenever
+the templates change.
 
-| Template | Description | Pull source (build stage) |
-|----------|-------------|--------------------------|
-| `alpine` | Alpine Linux (default) | `alpine` (Docker Hub official) |
-| `arch` / `archlinux` | Arch Linux ARM | `menci/archlinuxarm` |
-| `debian` | Debian | `debian` |
-| `ubuntu` | Ubuntu | `ubuntu` |
-| `rhel` / `almalinux` / `rockylinux` / `centos` / `oraclelinux` / `redhat` | AlmaLinux/RHEL family | `almalinux` |
-| `web` | Adds `xorg` + `x11-apps` packages on top of the build stage; scratch final image | `casjaysdev/web` (exists) — override via `ENV_PULL_URL` |
-| `xorg` | Adds `xorg` + `x11-apps` packages on top of the build stage; scratch final image | `casjaysdev/xorg` (**does not exist**) — must set `ENV_PULL_URL` |
-| `scratch` | Scratch final image only (pair with any build template) | N/A |
+## Template inventory
 
-> **Note:** The pull source is the base image pulled for the **build stage**. All templates produce a `FROM scratch` final stage. For standard distros (`alpine`, `debian`, `ubuntu`, `rhel`, `arch`), the pull source is the official upstream image. For `web` and `xorg`, gen-dockerfile defaults to `casjaysdev/<template>` when no `ENV_PULL_URL` is set — `casjaysdev/web` exists on Docker Hub; `casjaysdev/xorg` does not. Always set `ENV_PULL_URL` in `.env.scripts` for `xorg` projects.
+The template name selects the base OS family; for an app repo the resulting pull URL is
+always the matching `casjaysdev/*` image:
 
-### CLI Flags
+| Template | Final stage | Init / PID 1 | App pulls FROM |
+|----------|-------------|--------------|----------------|
+| `alpine.template` | `scratch.template` | tini | `casjaysdev/alpine` |
+| `debian.template` | `scratch.template` | tini | `casjaysdev/debian` |
+| `ubuntu.template` | `scratch.template` | tini | `casjaysdev/ubuntu` |
+| `rhel.template` | `scratch.template` | tini | `casjaysdev/almalinux` |
+| `archlinux.template` | `scratch.template` | tini | `casjaysdev/archlinux` (multi-arch manifest) |
+| `web.template` | `systemd.template` | `/sbin/init` | `casjaysdev/web` |
+| `xorg.template` | `systemd.template` | `/sbin/init` | `casjaysdev/xorg` |
 
-| Flag | Description |
-|------|-------------|
-| `--dir <path>` | Working directory (default: `$PWD`) |
-| `--template <name>` | Override template type |
-| `--registry <url>` | Registry provider URL (e.g. `https://docker.io`) |
-| `--org <[git\|reg:]name>` | Override org/namespace — prefix `git:` or `reg:` to scope to one system, bare value sets both |
-| `--user <[git\|reg:]name>` | Alias for `--org` |
-| `--repo <[git\|reg:]name>` | Override repo/image name — same scope prefix rules |
-| `--tag <version>` | Image version tag (default: `latest`) |
-| `--add-tags <tags>` | Comma-separated additional tags (or `USE_DATE` for auto date tag) |
-| `--distro-name <image>` | Base image pull URL (overrides `ENV_PULL_URL`) |
-| `--distro-version <tag>` | Base image tag (overrides `ENV_DISTRO_TAG`) |
-| `--startup` | Generate an init.d service script at `rootfs/usr/local/etc/docker/init.d/<name>` via `gen-script other start-service`; takes the script filename as a positional argument (e.g. `gen-dockerfile --startup 01-myapp.sh`) |
-| `--nogit` | Skip `git init` in the new project dir |
-| `--dockerfile` | Regenerate Dockerfile only — skip other files |
-| `--update` | Re-run gen-dockerfile on an existing project to regenerate files |
-| `--init` | Init mode |
-| `--x11` | Enable X11/xorg support |
-| `--ports <ports>` | Additional EXPOSE ports |
-| `--pkmgr` | Generate `pkmgr` script only and exit |
-| `--apache` | Add Apache2 packages + setup |
-| `--nginx` | Add nginx packages + setup |
-| `--mysql` | Add MariaDB packages + setup (`--mariadb` is handled in the case block but not registered in getopt — use `--mysql`) |
-| `--postgres` | Add PostgreSQL packages + setup |
-| `--php` | Add PHP packages + setup |
-| `--application <name>` | Add a templatemgr application install step |
-| `--alpine` / `--almalinux` / `--archlinux` / `--debian` / `--ubuntu` | Shortcut distro flags |
-| `--force` | Overwrite existing files without prompting |
-| `--silent` | Suppress non-error output |
-| `--debug` | Enable `set -x` tracing |
-| `--no-color` | Disable colour output |
+Default template for app repos is `alpine` unless the application needs systemd, a GUI
+stack, or a distro-specific package.
 
-### Special Subcommands
+## Final-stage templates
+
+`scratch.template` — all non-GUI templates.
+- `ENTRYPOINT [ "tini", "-p", "SIGTERM","--", "/usr/local/bin/entrypoint.sh" ]`
+- `STOPSIGNAL SIGRTMIN+3`
+
+`systemd.template` — `web` and `xorg` (systemd is PID 1; tini is redundant).
+- `ENTRYPOINT [ "/sbin/init" ]`
+- `STOPSIGNAL SIGRTMIN+3`
+- No `tini_provider` stage, no `COPY --from=tini_provider` line.
+
+Both are identical apart from `ENTRYPOINT`. OCI labels, `ENV HOSTNAME`, and
+`VOLUME`/`EXPOSE`/`HEALTHCHECK` are the same in both.
+
+## OCI label standard
+
+Both final-stage templates emit these labels (no others):
+
+```
+LABEL maintainer="${GEN_DOCKERFILE_MAINTAINER}"
+LABEL org.opencontainers.image.vendor="${GEN_DOCKERFILE_VENDOR:-CasjaysDev}"
+LABEL org.opencontainers.image.authors="${GEN_DOCKERFILE_AUTHOR:-CasjaysDev}"
+LABEL org.opencontainers.image.licenses="${LICENSE}"
+LABEL org.opencontainers.image.title="${IMAGE_NAME}"
+LABEL org.opencontainers.image.description="Containerized version of ${IMAGE_NAME}"
+LABEL org.opencontainers.image.created="${BUILD_DATE}"
+LABEL org.opencontainers.image.version="${BUILD_VERSION}"
+LABEL org.opencontainers.image.revision="${GIT_COMMIT}"
+LABEL org.opencontainers.image.url="${GEN_DOCKERFILE_HUB_REPO}"
+LABEL org.opencontainers.image.source="${GEN_DOCKERFILE_GIT_REPO}"
+LABEL org.opencontainers.image.documentation="${GEN_DOCKERFILE_GIT_REPO}"
+LABEL org.opencontainers.image.vcs-type="Git"
+LABEL com.github.containers.toolbox="false"
+```
+
+Shell-expanded values (no `\`) are evaluated at template-render time by `gen-dockerfile`.
+Dollar-escaped values (`\${...}`) become literal Docker `ARG`/`ENV` references in the
+generated `Dockerfile`.
+
+Resolved values for a `casjaysdevdocker` repo pushing to Docker Hub:
+
+| Label | Value |
+|-------|-------|
+| `url` | `https://hub.docker.com/r/casjaysdevdocker/{name}` — browsable Hub page; `gen-dockerfile` derives it from the registry host (`docker.io` → `hub.docker.com/r/`) |
+| `source` | `https://github.com/casjaysdevdocker/{name}` |
+| `documentation` | `https://github.com/casjaysdevdocker/{name}` |
+
+Older app repos may still carry `url="https://docker.io/casjaysdevdocker/{name}"` — that
+is the stale form; regeneration corrects it. Removed labels (never re-add):
+- `org.opencontainers.image.base.name` — belongs on the base image, not this image
+- `org.opencontainers.image.schema-version` — non-spec; redundant with `version`
+- Any duplicate `authors` or `source` entries
+
+## HOSTNAME convention
+
+All templates set `ENV HOSTNAME="casjaysdevdocker-${IMAGE_NAME}"` in every stage that
+declares it. The prefix is always `casjaysdevdocker-`, never `casjaysdev-`.
+
+## `GEN_DOCKERFILE_APP_DIR` and pull URL logic
+
+`GEN_DOCKERFILE_APP_DIR` is auto-detected by `gen-dockerfile` from the parent directory
+of `$PWD` (the org the checkout lives in):
 
 ```bash
-gen-dockerfile --dir ./myapp actions
+GEN_DOCKERFILE_APP_DIR="${GEN_DOCKERFILE_APP_DIR:-$(basename -- "$(dirname -- "$PWD")")}"
 ```
 
-Creates `.gitea/workflows/build.yml` (or `build.$version.yml` for versioned tags) from the existing `Dockerfile`. The canonical reference for the legacy hand-written style is `.gitea/workflows/docker.yaml` in the `casjaysdevdocker/.github` org-level repository (`casjaysdevdocker/.github/example/`); `gen-dockerfile actions` generates the modern `build.yml` — use that for all new containers.
+It selects the `GEN_DOCKER_SPECIFY_IMAGE_SOURCE_*` defaults:
 
-### Template Resolution
+- `casjaysdevdocker/*` repos → `FROM casjaysdev/<distro>:latest` (pre-built, multi-arch)
+- `dockersrc/*` and all other orgs → `FROM <distro>:latest` (upstream official images)
 
-Templates are loaded from the first match:
+App repos must resolve to the `casjaysdev/*` branch — a checkout outside
+`~/Projects/*/casjaysdevdocker/` needs `GEN_DOCKERFILE_APP_DIR="casjaysdevdocker"`
+exported before calling `gen-dockerfile`, or the regenerated Dockerfile silently reverts
+to upstream distro pulls (rule 8 violation).
+
+## Arch Linux apps
+
+`casjaysdev/archlinux` is a multi-arch manifest (`linux/amd64` + `linux/arm64`), so app
+repos use a single `FROM ${PULL_URL}:${DISTRO_VERSION} AS build` — the three-stage
+`base-${TARGETARCH}` FROM block belongs to the base repo only.
+
+## `web.template` / `xorg.template` notes
+
+`web` apps inherit the systemd + noVNC stack (`SERVICE_PORT="5800"`,
+`EXPOSE_PORTS="5800 5900"` defaults); `xorg` apps inherit the systemd + Xorg stack. App
+packages go in `ENV_PACKAGES` / `02-packages.sh`, never by editing the template's stack
+list.
+
+## `debian.template` / `ubuntu.template` — RUN continuation
+
+The first `RUN` block must have `; \` after the `echo` line so
+`export DEBIAN_FRONTEND=noninteractive` executes before `apt-get`:
+
+```dockerfile
+RUN set -e; \
+  echo "Updating the system"; \
+  export DEBIAN_FRONTEND=noninteractive; \
+  apt-get update && apt-get upgrade -yy && apt-get dist-upgrade -yy
+```
+
+Without the `; \` the export is a no-op and `apt-get` may prompt interactively.
+
+## Template resolution order
 
 1. `$GEN_DOCKERFILE_CONFIG_DIR/templates/<name>.template` (user override)
-2. `/usr/local/share/CasjaysDev/scripts/templates/dockerfiles/<name>.template` (installed; also `$CASJAYSDEVDIR/templates/dockerfiles/` when running from a dev checkout)
+2. `/usr/local/share/CasjaysDev/scripts/templates/dockerfiles/<name>.template`
+   (installed; `$CASJAYSDEVDIR/templates/dockerfiles/` in a dev checkout)
 
-`template_options.source` is sourced after `__set_variables` runs, allowing template-specific variable overrides.
+`template_options.source` is sourced after `__set_variables`, allowing template-specific
+variable overrides.
 
 ---
 
-## `.env.scripts` File
+# PART 3: TOOLING — gen-dockerfile & gen-script
 
-Generated at project root; sourced by gen-dockerfile and by the CI workflow at build time.
+## `gen-dockerfile`
 
-### Current Variable Names
-
-```bash
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-##@Version           :  202601291955-git
-# ...
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-
-# Entrypoint Settings
-DOCKER_ENTYPOINT_PORTS_WEB="${DOCKER_ENTYPOINT_PORTS_WEB}"
-DOCKER_ENTYPOINT_PORTS_SRV="${DOCKER_ENTYPOINT_PORTS_SRV}"
-DOCKER_ENTYPOINT_HEALTH_APPS="$DOCKER_ENTYPOINT_HEALTH_APPS"
-DOCKER_ENTYPOINT_HEALTH_ENDPOINTS="$DOCKER_ENTYPOINT_HEALTH_ENDPOINTS"
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-# Dockerfile info
-ENV_DOCKERFILE="Dockerfile"
-# ENV_REGISTRY_REPO: Registry repository/image name
-ENV_REGISTRY_REPO="myapp"
-ENV_USE_TEMPLATE="alpine"
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-# Maintainer info
-ENV_REGISTRY_ORG="casjaysdevdocker"
-ENV_VENDOR="CasjaysDev"
-ENV_AUTHOR="CasjaysDev"
-ENV_MAINTAINER="CasjaysDev <docker-admin@casjaysdev.pro>"
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-# Repository URLs (Full URLs)
-# ENV_GIT_REPO_URL: Complete Git repository URL for source code
-ENV_GIT_REPO_URL="https://github.com/casjaysdevdocker/myapp"
-# ENV_REGISTRY_URL: Registry provider base URL
-ENV_REGISTRY_URL="https://docker.io"
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-# Push Configuration
-# ENV_REGISTRY_PUSH: Complete push destination (registry/org/repo)
-ENV_REGISTRY_PUSH="casjaysdevdocker/myapp"
-# ENV_IMAGE_TAG: Default tag for the image
-ENV_IMAGE_TAG="latest"
-# ENV_ADD_TAGS: Additional tags, comma-separated (USE_DATE = auto date tag)
-ENV_ADD_TAGS=""
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-# Additional push destinations (if needed)
-ENV_ADD_IMAGE_PUSH=""
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-# Pull Configuration
-# ENV_PULL_URL: Source image to pull from (base image)
-ENV_PULL_URL="alpine"
-# ENV_DISTRO_TAG: Tag for the pull source image
-ENV_DISTRO_TAG="${IMAGE_VERSION}"
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-# Port exposure
-SERVICE_PORT=""
-EXPOSE_PORTS=""
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-# Language runtime version (go, php, rust, ruby, etc)
-LANG_VERSION=""
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-# Runtime versions
-PHP_VERSION="system"
-NODE_VERSION="system"
-NODE_MANAGER="system"
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-# Default directories
-WWW_ROOT_DIR="/usr/local/share/httpd/default"
-# - - - - - - - - - - - - - - - - - - - - - - - - -
-ENV_PACKAGES=""
+```
+Usage: gen-dockerfile [options] [dir] [template] [repo-name] [git-repo-url]
 ```
 
-### Variable Reference
+| Flag | Meaning |
+|------|---------|
+| `--update` | Rewrite `.env.scripts` (add/drop vars against the current template) and update ARG/LABEL lines in the `Dockerfile`. Touches no other file. |
+| `--nogit` | Do not init or commit a git repo — required inside an existing repo. |
+| `--dir PATH` | Operate on / write output to PATH instead of `$PWD`. |
+| `--template NAME` | Template to use (`alpine`, `debian`, `ubuntu`, `rhel`, `archlinux`, `scratch`, `web`, `xorg`). Defaults to `alpine`. |
+| `--repo NAME` | Registry repo name (image basename). Defaults to the directory name. |
+| `--org NAME` | Registry owner / GitHub org (`--user` is an alias). Prefix `git:` or `reg:` to scope to one system; bare value sets both. For app repos both are `casjaysdevdocker`. |
+| `--registry URL` | Registry provider URL (e.g. `https://docker.io`). |
+| `--tag VERSION` | Image version tag (default `latest`). |
+| `--add-tags TAGS` | Comma-separated additional tags (`USE_DATE` = auto date tag). |
+| `--distro-name IMG` | Base image pull URL (overrides `ENV_PULL_URL`). |
+| `--distro-version T` | Base image tag (overrides `ENV_DISTRO_TAG`). |
+| `--startup FILE` | Generate an init.d service script at `rootfs/usr/local/etc/docker/init.d/FILE` via `gen-script other/start-service`. |
+| `--dockerfile` | Regenerate the Dockerfile only. |
+| `--force` | Overwrite existing files without prompting. |
+
+Resolution order when a value is not given by a flag: flags → git remote → project dirs →
+defaults.
+
+Special subcommand — `gen-dockerfile actions` writes `.gitea/workflows/build.yml` from
+the existing `Dockerfile` (PART 7). App repos have no versioned `build.{ver}.yml` files.
+
+## `gen-script`
+
+```
+Usage: gen-script [options] [template] [filename]
+```
+
+| Flag / env var | Meaning |
+|----------------|---------|
+| `--dir PATH` | Write the generated file to `PATH/filename`. |
+| `-n` / `--name VALUE` | Service name substituted into the template — fills `REPLACE_SERVICE_NAME` in `other/start-service`, pre-populating `SERVICE_NAME=` without a sed step. |
+| `GEN_SCRIPT_OVERWRITE="Y"` | Overwrite the output without prompting (default `"A"` = ask). Required when the target exists, even with `GEN_SCRIPT_EDITFILE="N"`. |
+| `GEN_SCRIPT_EDITFILE="N"` | Suppress the interactive editor after generation. `-e`/`--no` sets BOTH this AND `GEN_SCRIPT_OVERWRITE="Y"`; the env var alone does not. |
+| `other/start-service` | Template path — positional arg 1, slash-joined words, matching the `@@Template` header. |
+| `filename` | Output basename — positional arg 2, combined with `--dir`. |
+
+Other flags: `-k`/`--keep` (never overwrite), `--replace` (new header replaces old),
+`-d`/`--desc` (header description), `-p`/`--prev` (copy header metadata from a file).
+
+---
+
+# PART 4: `.env.scripts` REFERENCE
+
+Generated at the repo root; sourced by `gen-dockerfile` and by CI at build time. App
+repos carry exactly one. It is a pure `KEY="value"` file — no logic.
+
+## Variables
 
 | Variable | Purpose |
 |----------|---------|
-| `ENV_REGISTRY_REPO` | Image name in the registry |
-| `ENV_REGISTRY_ORG` | Organisation/namespace in the registry |
-| `ENV_REGISTRY_URL` | Registry base URL (e.g. `https://docker.io`) |
-| `ENV_REGISTRY_PUSH` | Full push path `org/repo` (registry host prepended if not `docker.io`) |
+| `ENV_DOCKERFILE` | Dockerfile to build (`Dockerfile`) |
+| `ENV_REGISTRY_REPO` | Image name in the registry (`{name}`) |
+| `ENV_REGISTRY_ORG` | Registry namespace — `casjaysdevdocker` for app repos |
+| `ENV_REGISTRY_URL` | Registry base URL (`https://docker.io`) — pull/push host, never a label URL |
+| `ENV_REGISTRY_PUSH` | Full push path `org/repo` (`casjaysdevdocker/{name}`) |
 | `ENV_ADD_IMAGE_PUSH` | Extra push destinations |
-| `ENV_GIT_REPO_URL` | Full Git repository URL |
-| `ENV_USE_TEMPLATE` | Template name to use (alpine, debian, etc.) |
-| `ENV_PULL_URL` | Base image to pull from |
-| `ENV_DISTRO_TAG` | Tag for the base image |
-| `ENV_IMAGE_TAG` | Default image tag (default: `latest`) |
-| `ENV_ADD_TAGS` | Additional comma-separated tags; `USE_DATE` auto-generates a `YYMM` tag |
-| `ENV_PACKAGES` | Space-separated package list to install |
+| `ENV_GIT_REPO_URL` | Full Git repo URL — `https://github.com/casjaysdevdocker/{name}`; feeds the `source`/`documentation` labels, so a wrong value here regresses labels on regeneration |
+| `ENV_USE_TEMPLATE` | Template name (`alpine`, `debian`, …) — the authoritative record of which base family the app builds on |
+| `ENV_PULL_URL` | Base image to pull FROM (`casjaysdev/<base>`) |
+| `ENV_DISTRO_TAG` | Tag for the pull image (`latest`) |
+| `ENV_IMAGE_TAG` | Default image tag (`latest`) |
+| `ENV_ADD_TAGS` | Additional comma-separated tags; `USE_DATE` auto-generates a date tag |
+| `ENV_PACKAGES` | Space-separated package list |
 | `ENV_VENDOR` / `ENV_AUTHOR` / `ENV_MAINTAINER` | Label metadata |
-| `SERVICE_PORT` | Primary exposed port |
+| `SERVICE_PORT` | Primary exposed port — apps normally set this |
 | `EXPOSE_PORTS` | Additional exposed ports |
-| `LANG_VERSION` | Language runtime version (go, php, rust, ruby, etc.) |
-| `PHP_VERSION` / `NODE_VERSION` / `NODE_MANAGER` | Runtime versions |
-| `WWW_ROOT_DIR` | Web root directory (default: `/usr/local/share/httpd/default`) |
-| `DOCKER_ENTYPOINT_PORTS_WEB` | Web ports passed to entrypoint |
-| `DOCKER_ENTYPOINT_PORTS_SRV` | Service ports passed to entrypoint |
-| `DOCKER_ENTYPOINT_HEALTH_APPS` | Apps to health-check |
-| `DOCKER_ENTYPOINT_HEALTH_ENDPOINTS` | Endpoints to health-check |
+| `PHP_VERSION` / `NODE_VERSION` / `NODE_MANAGER` | Runtime versions (`system` default) |
+| `WWW_ROOT_DIR` | Web root (`/usr/local/share/httpd/default`) |
+| `DOCKER_ENTYPOINT_PORTS_WEB` / `DOCKER_ENTYPOINT_PORTS_SRV` | Ports passed to the entrypoint |
+| `DOCKER_ENTYPOINT_HEALTH_APPS` / `DOCKER_ENTYPOINT_HEALTH_ENDPOINTS` | Healthcheck targets |
 
-### Legacy Variable Auto-Migration
+## Legacy variable auto-migration
 
-`gen-dockerfile --update` (and on every run) calls `__migrate_env_script` which automatically renames old variable names to the current ones. Old names that are no longer used:
+`gen-dockerfile` calls `__migrate_env_script` on every run, renaming old variables:
 
-| Old Name | Current Name |
+| Old name | Current name |
 |----------|-------------|
 | `ENV_IMAGE_NAME` | `ENV_REGISTRY_REPO` |
 | `ENV_IMAGE_PUSH` | `ENV_REGISTRY_PUSH` |
 | `ENV_HUB_BASE` | `ENV_REGISTRY_URL` |
 | `ENV_ORG_NAME` | `ENV_REGISTRY_ORG` |
 
-Never use the old names in new `.env.scripts` files.
+Never use the old names in new files. Retired variables that must not reappear anywhere:
+`DEFAULT_TEMPLATE_DIR`, `DEFAULT_FILE_DIR`, `DEFAULT_DATA_DIR`, `DEFAULT_CONF_DIR`.
 
 ---
 
-## Dockerfile Template Structure
+# PART 5: RUNTIME SYSTEM — SETUP SCRIPTS, ENTRYPOINT, INIT.D
 
-### Build Arguments
+## Build-time setup scripts (`rootfs/root/docker/setup/`)
 
-Top-of-file ARGs (before any `FROM`):
+Run in order inside the build stage:
 
-| Argument | Description | Default |
-|----------|-------------|---------|
-| `IMAGE_NAME` | Container name | (from `ENV_REGISTRY_REPO`) |
-| `PHP_SERVER` | PHP server name | (same as `IMAGE_NAME`) |
-| `BUILD_DATE` | Build timestamp | YYYYMMDDHHMM |
-| `LANGUAGE` | System locale | `en_US.UTF-8` |
-| `TIMEZONE` | System timezone | `America/New_York` |
-| `WWW_ROOT_DIR` | Web root | `/usr/local/share/httpd/default` |
-| `PATH` | System `PATH` | `/usr/local/etc/docker/bin:/usr/local/sbin:...` |
-| `USER` | Build user | `root` |
-| `SHELL_OPTS` | Shell options | `set -e -o pipefail` |
-| `SERVICE_PORT` | Primary service port | (from `.env.scripts`) |
-| `EXPOSE_PORTS` | Additional ports | (from `.env.scripts`) |
-| `PHP_VERSION` | PHP version | `system` |
-| `NODE_VERSION` | Node.js version | `system` |
-| `NODE_MANAGER` | Node manager | `system` |
-| `IMAGE_REPO` | Full push path `org/repo` | (computed) |
-| `IMAGE_VERSION` | Image version | `latest` |
-| `CONTAINER_VERSION` | Additional image tags | (computed) |
-| `PULL_URL` | Base image to pull | `alpine` (official Docker Hub) |
-| `DISTRO_VERSION` | Base image tag | `${IMAGE_VERSION}` |
-| `BUILD_VERSION` | Build version alias | `${BUILD_DATE}` |
+| Script | Role |
+|--------|------|
+| `00-init.sh` | Initialize base directory structure and environment |
+| `01-system.sh` | Repos, locales, timezone, system settings |
+| `02-packages.sh` | App-specific packages, package managers, language runtimes |
+| `03-files.sh` | Install staged files (`rootfs/tmp/etc/*` → `/etc/*`), permissions, symlinks |
+| `04-users.sh` | Create service users/groups |
+| `05-custom.sh` | Application install logic — the heart of an app repo |
+| `06-post.sh` | Post-install configuration |
+| `07-cleanup.sh` | Remove build deps, caches, temp files |
 
-Stage 2 (`FROM scratch`) additional ARGs:
+**`05-custom.sh` ownership:** the upstream template ships an empty stub. An app repo's
+`05-custom.sh` carries the application install (download/build, users, default config) —
+that content exists only in the repo's git history, never in the template. On
+regeneration, keep the existing body and pull forward only boilerplate (version-stamp
+header, `set` line, shellcheck-disable line). The same rule applies to any other `0*.sh`
+found to contain real logic beyond the stub.
 
-| Argument | Description |
-|----------|-------------|
-| `TZ` | Timezone alias |
-| `GIT_COMMIT` | Git SHA at build time (from CI) |
-| `LICENSE` | Image license | default `WTFPL` |
-| `ENV_PORTS` | Alias for `${EXPOSE_PORTS}` |
-
-### Generated Dockerfile Structure
-
-#### Stage 1: Build Stage
-
-```dockerfile
-FROM tianon/gosu:latest AS gosu
-FROM ${PULL_URL}:${DISTRO_VERSION} AS build
-
-# ... ARG declarations ...
-
-ENV ENV=~/.profile
-ENV SHELL="/bin/sh"
-ENV PATH="${PATH}"
-ENV TZ="${TIMEZONE}"
-ENV TIMEZONE="${TZ}"
-ENV LANG="${LANGUAGE}"
-ENV TERM="xterm-256color"
-ENV HOSTNAME="casjaysdevdocker-${IMAGE_NAME}"
-
-COPY ./rootfs/. /
-RUN pkmgr update; pkmgr install bash ca-certificates; update-ca-certificates
-
-ENV SHELL="/bin/bash"
-SHELL ["/bin/bash", "-c"]
-COPY --from=gosu /usr/local/bin/gosu /usr/local/bin/gosu
-
-# Setup scripts run in order:
-# 00-init.sh      - Initialize base system
-# 01-system.sh    - Configure system settings
-# 02-packages.sh  - Install/configure packages (after PACK_LIST install)
-# 03-files.sh     - Copy/modify files
-# 04-users.sh     - Create users/groups
-# 05-custom.sh    - Custom application setup
-# 06-post.sh      - Post-installation tasks
-# 07-cleanup.sh   - Clean up temporary files
-```
-
-#### Stage 2: Final Image
-
-```dockerfile
-FROM scratch
-
-# ... ARG and LABEL declarations ...
-
-ENV ENV=~/.bashrc
-ENV USER="${USER}"
-ENV PATH="${PATH}"
-ENV TZ="${TIMEZONE}"
-ENV SHELL="/bin/bash"
-ENV TIMEZONE="${TZ}"
-ENV LANG="${LANGUAGE}"
-ENV TERM="xterm-256color"
-ENV PORT="${SERVICE_PORT}"
-ENV ENV_PORTS="${ENV_PORTS}"
-ENV CONTAINER_NAME="${IMAGE_NAME}"
-ENV HOSTNAME="casjaysdev-${IMAGE_NAME}"
-ENV PHP_SERVER="${PHP_SERVER}"
-ENV NODE_VERSION="${NODE_VERSION}"
-ENV NODE_MANAGER="${NODE_MANAGER}"
-ENV PHP_VERSION="${PHP_VERSION}"
-ENV DISTRO_VERSION="${IMAGE_VERSION}"
-ENV WWW_ROOT_DIR="${WWW_ROOT_DIR}"
-
-COPY --from=build /. /
-
-VOLUME [ "/config", "/data" ]
-EXPOSE ${SERVICE_PORT} ${ENV_PORTS}
-STOPSIGNAL SIGRTMIN+3
-ENTRYPOINT [ "tini", "-p", "SIGTERM", "--", "/usr/local/bin/entrypoint.sh" ]
-HEALTHCHECK --start-period=10m --interval=5m --timeout=15s \
-  CMD [ "/usr/local/bin/entrypoint.sh", "healthcheck" ]
-```
-
-### Container Labels
-
-All containers include OpenContainers standard labels:
-
-```dockerfile
-LABEL maintainer="CasjaysDev <docker-admin@casjaysdev.pro>"
-LABEL org.opencontainers.image.vendor="CasjaysDev"
-LABEL org.opencontainers.image.authors="CasjaysDev"
-LABEL org.opencontainers.image.description="Containerized version of ${IMAGE_NAME}"
-LABEL org.opencontainers.image.title="${IMAGE_NAME}"
-LABEL org.opencontainers.image.base.name="${IMAGE_NAME}"
-LABEL org.opencontainers.image.authors="${LICENSE}"
-LABEL org.opencontainers.image.created="${BUILD_DATE}"
-LABEL org.opencontainers.image.version="${BUILD_VERSION}"
-LABEL org.opencontainers.image.schema-version="${BUILD_VERSION}"
-LABEL org.opencontainers.image.url="${GEN_DOCKERFILE_HUB_REPO}"
-LABEL org.opencontainers.image.source="${GEN_DOCKERFILE_HUB_REPO}"
-LABEL org.opencontainers.image.vcs-type="Git"
-LABEL org.opencontainers.image.revision="${GIT_COMMIT}"
-LABEL org.opencontainers.image.source="${GEN_DOCKERFILE_GIT_REPO}"
-LABEL org.opencontainers.image.documentation="${GEN_DOCKERFILE_GIT_REPO}"
-LABEL com.github.containers.toolbox="false"
-```
-
-> **Note:** `org.opencontainers.image.source` appears twice intentionally — first set to `GEN_DOCKERFILE_HUB_REPO` (computed from `ENV_REGISTRY_URL`/`ENV_REGISTRY_PUSH`), then overridden to `GEN_DOCKERFILE_GIT_REPO` (the Git remote URL). The second value wins at runtime. Neither URL is hardcoded — they reflect whatever registry and org the project is configured for.
-
----
-
-## Common Package List
-
-Standard packages included in most containers (Alpine template):
+## Entrypoint flow
 
 ```
-bash-completion git curl wget sudo unzip iproute2 ssmtp openssl jq tzdata
-mailcap ncurses util-linux pciutils usbutils coreutils binutils findutils
-grep rsync zip tini py3-pip procps net-tools sed gawk attr readline lsof
-less shadow ca-certificates
-```
-
----
-
-## Setup Scripts Convention
-
-Build-time scripts in `rootfs/root/docker/setup/` run inside the Docker build layer.
-
-### 00-init.sh
-- Initialize base directory structure
-- Set up template directories
-- Create initial environment
-
-### 01-system.sh
-- Configure APK/apt/yum repositories
-- Set up system settings
-- Configure locales and timezone
-
-### 02-packages.sh
-- Install application-specific packages
-- Configure package managers (pip, npm, etc.)
-- Set up language runtimes
-
-### 03-files.sh
-- Copy configuration files
-- Set file permissions
-- Create symlinks
-
-### 04-users.sh
-- Create application users
-- Set up user directories
-- Configure user permissions
-
-### 05-custom.sh
-- Application-specific installation
-- Download/compile software
-- Custom configuration
-
-### 06-post.sh
-- Post-installation configuration
-- Initialize databases
-- Generate default configs
-
-### 07-cleanup.sh
-- Remove build dependencies
-- Clean package caches
-- Remove temporary files
-
----
-
-## Entrypoint System
-
-### Entrypoint Script Flow
-
-```
-/usr/local/bin/entrypoint.sh
-├─ Load functions from /usr/local/etc/docker/functions/entrypoint.sh
-├─ Set up environment variables (sources /root/env.sh, /usr/local/etc/docker/env/*.sh, /config/env/*.sh)
-├─ Create /config and /data volumes
-├─ Run ALL init scripts from /usr/local/etc/docker/init.d/ (sorted order) via __start_init_scripts
-├─ Handle healthcheck command
+tini → /usr/local/bin/entrypoint.sh
+├─ Load /usr/local/etc/docker/functions/entrypoint.sh
+├─ Source env: /root/env.sh, /usr/local/etc/docker/env/*.sh, /config/env/*.sh
+├─ Seed /config and /data on first run
+├─ __start_init_scripts — source every init.d/*.sh in sort order
+├─ Handle `healthcheck` command
 └─ Execute main application
 ```
 
-### Init.d Scripts — CRITICAL RULES
+`rootfs/usr/local/bin/` generated set: `entrypoint.sh`, `pkmgr`, `symlink`, `copy`,
+`healthcheck`. `pkmgr` wraps the native package manager (`apk`, `apt-get`, `dnf`,
+`pacman`) behind `pkmgr update|install|remove|clean`.
 
-**Each service in a repo gets its own numbered init.d script. Never merge or remove them.**
+## App-specific bin scripts
 
-- `__start_init_scripts` iterates and sources **every** `*.sh` file in `init.d/` in sort order.
-- Multi-process repos have **one script per service**. Example for a repo running three daemons:
-  ```
-  init.d/01-named.sh     — BIND/named DNS server
-  init.d/02-nginx.sh     — nginx web front-end
-  init.d/03-php-fpm.sh   — PHP-FPM for web UI
-  ```
-- **Migration task = UPDATE each script to the canonical pattern, never delete services.**
-- The canonical pattern is `04-example.sh` in the `casjaysdevdocker/.github` org-level repository, or generate a fresh one with `gen-dockerfile --startup <name>`.
+Extra scripts in `rootfs/usr/local/bin/` that `gen-dockerfile` does not generate are
+repo-owned. Their `@@Template` header governs maintenance:
 
-### Required Variables in Every Init.d Script
+- `@@Template : shell/sh` — boilerplate synced from `$TEMPLATE_DIR/scripts/shell/sh`;
+  `#!/usr/bin/env sh`, `set -e` only (`pipefail` is a bashism — must NOT appear)
+- `@@Template : shell/bash` — synced from `shell/bash`; `set -eo pipefail` required
+- No `@@Template` header — hand-written; never modified by tooling
+
+## init.d scripts — critical rules
+
+**Each service gets its own numbered init.d script. Never merge or remove services.**
+`__start_init_scripts` sources every `*.sh` in sort order — multi-process apps have one
+script per daemon (e.g. gitea: `05-dockerd.sh`, `08-gitea.sh`, `zz-act_runner.sh`).
+
+init.d scripts are **regenerated, never patched in place** — old copies may call functions
+removed from the current `functions/entrypoint.sh`. Generate fresh via
+`gen-script other/start-service` (or `gen-dockerfile --startup`), then restore the
+app-specific values. They are `#!/usr/bin/env bash` with `set -eo pipefail`.
+
+Required variables in every init.d script:
 
 ```bash
-SERVICE_NAME="myapp"           # used for PID files, log dirs, config dirs
-EXEC_CMD_BIN='myapp'          # daemon binary (single-quoted — expanded later)
-EXEC_CMD_ARGS=''               # daemon arguments (single-quoted)
-EXEC_PRE_SCRIPT=''             # pre-start script (single-quoted)
-SERVICE_USES_PID=''            # '' for long-running daemons; 'no' for config-only steps
-IS_WEB_SERVER="no"             # 'yes' sets RESET_ENV and default port 80
+SERVICE_NAME="myapp"
+EXEC_CMD_BIN='myapp'
+EXEC_CMD_ARGS=''
+EXEC_PRE_SCRIPT=''
+SERVICE_USES_PID=''
+IS_WEB_SERVER="no"
 IS_DATABASE_SERVICE="no"
 USES_DATABASE_SERVICE="no"
-DATABASE_SERVICE_TYPE="sqlite" # custom|sqlite|redis|postgres|mariadb|mysql|couchdb|mongodb|supabase
+DATABASE_SERVICE_TYPE="sqlite"
 RUNAS_USER="root"
 ```
 
-### Hook Functions in Every Init.d Script
-
-The `start-service` template **generates all eleven hook functions** fully implemented inside each init.d script — they are not stubs the developer writes from scratch. The developer customises behaviour via a matching `*_local()` variant that each outer hook calls automatically if defined.
-
-**Outer hooks** (generated, do not redefine):
+Directory variables:
 
 ```bash
-__run_precopy()              # runs before copying /config to /etc
-__execute_prerun()           # custom prerun — e.g. set up WWW_ROOT_DIR
-__run_pre_execute_checks()   # validation before exec; non-zero exitStatus aborts start
-__update_conf_files()        # runs sed replacements on config files
-__pre_execute()              # final setup before exec
-__post_execute()             # background post-start tasks
-__pre_message()              # message shown before exec
-__update_ssl_conf()          # SSL certificate setup
-__create_service_env()       # generates /config/env/$SERVICE_NAME.sh template
-__run_start_script()         # builds and executes the service start command
-__run_secure_function()      # chmod 600 on credential files
+DATA_DIR="/data/$SERVICE_NAME"
+CONF_DIR="/config/$SERVICE_NAME"
+ETC_DIR="/etc/$SERVICE_NAME"
+LOG_DIR="/data/logs/$SERVICE_NAME"
+TMP_DIR="/tmp/$SERVICE_NAME"
+RUN_DIR="/run/$SERVICE_NAME"
+ROOT_FILE_PREFIX="/config/secure/auth/root"
+USER_FILE_PREFIX="/config/secure/auth/user"
 ```
 
-**`*_local()` stubs** (customise these — defined as `{ true; }` by default):
+## Hook functions
+
+The `start-service` template generates all outer hooks fully implemented — customise via
+the matching `*_local()` stub, which each outer hook calls automatically if defined:
+
+| Outer hook (do not redefine) | Customise via |
+|------------------------------|---------------|
+| `__run_precopy` | `__run_precopy_local` |
+| `__execute_prerun` | `__execute_prerun_local` |
+| `__run_pre_execute_checks` | `__run_pre_execute_checks_local` |
+| `__update_conf_files` | `__update_conf_files_local` |
+| `__pre_execute` | `__pre_execute_local` |
+| `__post_execute` | `__post_execute_local` |
+| `__pre_message` | `__pre_message_local` |
+| `__update_ssl_conf` | `__update_ssl_conf_local` |
+| `__create_service_env` | — |
+| `__run_start_script` | — |
+| `__run_secure_function` | — |
+
+## PID sentinel guard
+
+Every init.d script must guard on exactly this sentinel — leading dot, no underscores in
+the filename portion; any other form silently skips the guard:
 
 ```bash
-__run_precopy_local()
-__execute_prerun_local()
-__run_pre_execute_checks_local()
-__update_conf_files_local()    # ← put sed/config replacements here
-__pre_execute_local()
-__post_execute_local()
-__pre_message_local()
-__update_ssl_conf_local()
-```
-
-Each outer hook checks `builtin type -t __<name>_local | grep -q 'function'` before calling the local variant, so stubs that are never overridden cost nothing.
-
-### PID Sentinel Check (CRITICAL)
-
-Every init.d script **must** guard on the correct sentinel file:
-
-```bash
-# Correct — dot prefix, no double underscore
 if [ ! -f "/run/.start_init_scripts.pid" ]; then
   echo "__start_init_scripts function hasn't been Initialized" >&2
   SERVICE_IS_RUNNING="no"
@@ -609,236 +516,182 @@ if [ ! -f "/run/.start_init_scripts.pid" ]; then
 fi
 ```
 
-The file is `/run/.start_init_scripts.pid` — a leading dot, no underscores in the filename portion. Any other form silently skips the guard.
+## Volumes
 
-### Directory Variables
-
-```bash
-DATA_DIR="/data/$SERVICE_NAME"         # persistent data
-CONF_DIR="/config/$SERVICE_NAME"       # persistent config
-ETC_DIR="/etc/$SERVICE_NAME"           # runtime etc (synced from CONF_DIR)
-LOG_DIR="/data/logs/$SERVICE_NAME"     # logs
-TMP_DIR="/tmp/$SERVICE_NAME"
-RUN_DIR="/run/$SERVICE_NAME"
-ROOT_FILE_PREFIX="/config/secure/auth/root"
-USER_FILE_PREFIX="/config/secure/auth/user"
-```
-
-### Volume Mounts
-
-- `/config` — Persistent configuration files
-- `/data` — Persistent application data
+- `/config` — persistent configuration
+- `/data` — persistent application data
 
 ---
 
-## CI/CD Integration
+# PART 6: README.md STANDARD LAYOUT
 
-### Two Workflow Files — Hand-Crafted vs Generated
+App image layout (`casjaysdevdocker/{name}` → `casjaysdevdocker/{name}`). Substitute
+`{name}` and `{port}` (the value of `SERVICE_PORT`); omit all `-p`/`ports:` sections only
+in the rare case `SERVICE_PORT` is empty.
 
-| File | Origin | Never overwrite? |
-|------|--------|-----------------|
-| `.gitea/workflows/docker.yaml` | Hand-crafted legacy file; reference copy in `casjaysdevdocker/.github/example/` | Yes — do not overwrite |
-| `.gitea/workflows/build.yml` | Generated by `gen-dockerfile actions` | No — regenerate freely |
+**Hand-crafted README exception:** a repo whose README deliberately diverges from this
+layout (full env-var tables, app-specific quick-start flags — e.g. gitea) owns its README.
+Update its facts (image name, org, ports, URLs), never rewrite its structure back to the
+generated layout.
 
-### Generated Workflow (`gen-dockerfile actions`)
+````markdown
+## 👋 Welcome to {name} 🚀
 
-`gen-dockerfile actions` writes `.gitea/workflows/build.yml` (or `build.<version>.yml` for versioned tags) from the current `Dockerfile`. All actions are SHA-pinned.
+{name} README
 
-**Triggers:** `push` to `main`, monthly schedule (`cron: '0 2 1 * *'`), `workflow_dispatch`.
 
-**Registry strategy:**
-- Always logs in to the Gitea registry using the auto-provided `GITEA_TOKEN`.
-- Conditionally logs in to Docker Hub (or another registry) when `vars.DOCKER_USERNAME` is set; credentials via `vars.DOCKER_USERNAME` + `secrets.DOCKER_PASSWORD`.
-- `vars.DOCKER_REGISTRY` overrides the registry URL (default: `docker.io`).
-- `vars.DOCKER_ORG` overrides the namespace (fallback: `vars.DOCKER_USERNAME`).
+## Install my system scripts
 
-**`build-args` passed:** only `BUILD_DATE`, `GIT_COMMIT`, `BUILD_VERSION` — not `TIMEZONE`, `LANGUAGE`, `LICENSE`, or `TZ`.
+```shell
+ sudo bash -c "$(curl -q -LSsf "https://github.com/systemmgr/installer/raw/main/install.sh")"
+ sudo systemmgr --config && sudo systemmgr install scripts
+```
 
-**Tags pushed:** `<yymm>` and `latest` to both Gitea and (if configured) Docker Hub.
+## Automatic install/update
+
+```shell
+dockermgr update {name}
+```
+
+## Install and run container
+
+```shell
+dockerHome="/srv/$USER/docker/casjaysdevdocker/{name}/latest/volumes"
+mkdir -p "$dockerHome"
+git clone "https://github.com/dockermgr/{name}" "$HOME/.local/share/CasjaysDev/dockermgr/{name}"
+cp -Rfva "$HOME/.local/share/CasjaysDev/dockermgr/{name}/volumes/." "$dockerHome/"
+docker run -d \
+--restart always \
+--privileged \
+--name casjaysdevdocker-{name}-latest \
+--hostname {name} \
+-e TZ=${TIMEZONE:-America/New_York} \
+-v "$dockerHome/data:/data:z" \
+-v "$dockerHome/config:/config:z" \
+-p {port}:{port} \
+casjaysdevdocker/{name}:latest
+```
+
+## via docker-compose
 
 ```yaml
-name: Build and Push
-
-on:
-  push:
-    branches: [main]
-  schedule:
-    - cron: '0 2 1 * *'
-  workflow_dispatch:
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
-
-      - name: Compute build metadata
-        id: meta
-        run: |
-          echo "build_date=$(date -u +%Y%m%d%H%M)" >> "$GITHUB_OUTPUT"
-          echo "tag_yymm=$(date -u +%y%m)" >> "$GITHUB_OUTPUT"
-          echo "git_commit=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
-          echo "registry_host=$(echo '${{ github.server_url }}' | sed 's|https://||')" >> "$GITHUB_OUTPUT"
-
-      - name: Login to Gitea registry
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
-        with:
-          registry: ${{ steps.meta.outputs.registry_host }}
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITEA_TOKEN }}
-
-      - name: Login to Docker Hub
-        if: vars.DOCKER_USERNAME != ''
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
-        with:
-          registry: ${{ vars.DOCKER_REGISTRY || 'docker.io' }}
-          username: ${{ vars.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_PASSWORD }}
-
-      - name: Build and push
-        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
-        with:
-          context: .
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: |
-            ${{ steps.meta.outputs.registry_host }}/${{ github.repository }}:${{ steps.meta.outputs.tag_yymm }}
-            ${{ vars.DOCKER_USERNAME != '' && format('{0}/{1}/{2}:{3}', vars.DOCKER_REGISTRY || 'docker.io', vars.DOCKER_ORG || vars.DOCKER_USERNAME, github.event.repository.name, steps.meta.outputs.tag_yymm) || '' }}
-            ${{ steps.meta.outputs.registry_host }}/${{ github.repository }}:latest
-            ${{ vars.DOCKER_USERNAME != '' && format('{0}/{1}/{2}:{3}', vars.DOCKER_REGISTRY || 'docker.io', vars.DOCKER_ORG || vars.DOCKER_USERNAME, github.event.repository.name, 'latest') || '' }}
-          build-args: |
-            BUILD_DATE=${{ steps.meta.outputs.build_date }}
-            GIT_COMMIT=${{ steps.meta.outputs.git_commit }}
-            BUILD_VERSION=${{ steps.meta.outputs.tag_yymm }}
-          annotations: |
-            org.opencontainers.image.created=${{ steps.meta.outputs.build_date }}
-            org.opencontainers.image.version=latest
-            org.opencontainers.image.revision=${{ steps.meta.outputs.git_commit }}
-            org.opencontainers.image.title=${{ github.event.repository.name }}
-            org.opencontainers.image.description=Containerized version of ${{ github.event.repository.name }}
-            org.opencontainers.image.vendor=CasjaysDev
-            org.opencontainers.image.authors=CasjaysDev
-            org.opencontainers.image.licenses=WTFPL
-            org.opencontainers.image.url=${{ github.server_url }}/${{ github.repository }}
-            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
-            org.opencontainers.image.documentation=${{ github.server_url }}/${{ github.repository }}
-            org.opencontainers.image.vcs-type=Git
-            com.github.containers.toolbox=false
+services:
+  ProjectName:
+    image: casjaysdevdocker/{name}
+    container_name: casjaysdevdocker-{name}
+    environment:
+      - TZ=America/New_York
+      - HOSTNAME={name}
+    volumes:
+      - "/srv/$USER/docker/casjaysdevdocker/{name}/latest/volumes/data:/data:z"
+      - "/srv/$USER/docker/casjaysdevdocker/{name}/latest/volumes/config:/config:z"
+    ports:
+      - {port}:{port}
+    restart: always
 ```
 
-For versioned builds (`gen-dockerfile actions` on a tagged version), the workflow is named `Build and Push <version>`, omits the schedule trigger, and pushes only that fixed version tag.
+## Get source files
 
-### Hand-Crafted Workflow (`.gitea/workflows/docker.yaml`)
+```shell
+dockermgr download src casjaysdevdocker/{name}
+```
 
-The legacy `docker.yaml` is hand-crafted; the reference copy lives in `casjaysdevdocker/.github/example/` (the org-level repository). It differs from the generated workflow: uses `catthehacker/ubuntu:act-latest` container, tag-pinned actions (`@v2`/`@v3`/`@v4`), `secrets.DOCKER_USERNAME` + `secrets.DOCKER_TOKEN`, and the old `steps.meta.outputs.*` pattern. Do not use this as a template for new containers — use `gen-dockerfile actions` instead.
+OR
+
+```shell
+git clone "https://github.com/casjaysdevdocker/{name}" "$HOME/Projects/github/casjaysdevdocker/{name}"
+```
+
+## Build container
+
+```shell
+cd "$HOME/Projects/github/casjaysdevdocker/{name}"
+buildx
+```
+
+## Authors
+
+🤖 casjay: [Github](https://github.com/casjay) 🤖
+⛵ casjaysdevdocker: [Github](https://github.com/casjaysdevdocker) [Docker](https://hub.docker.com/u/casjaysdevdocker) ⛵
+````
 
 ---
 
-## Package Manager Wrapper (pkmgr)
+# PART 7: CI/CD WORKFLOWS
 
-The `pkmgr` script in `rootfs/usr/local/bin/pkmgr` provides a unified interface:
+## Generated workflow (`gen-dockerfile actions`)
+
+`gen-dockerfile actions` writes `.gitea/workflows/build.yml` from the current
+`Dockerfile`. App repos get the single `build.yml` only — no versioned variants. All
+actions are SHA-pinned — never tag-pinned.
+
+- **Triggers:** `push` to `main`, monthly schedule, `workflow_dispatch`
+- **Registry strategy:** always logs in to the Gitea registry via the auto-provided
+  `GITEA_TOKEN`; conditionally logs in to Docker Hub when `vars.DOCKER_USERNAME` is set
+  (`vars.DOCKER_USERNAME` + `secrets.DOCKER_PASSWORD`; `vars.DOCKER_REGISTRY` overrides
+  the registry, `vars.DOCKER_ORG` the namespace)
+- **Platforms:** `linux/amd64,linux/arm64`
+- **build-args:** only `BUILD_DATE`, `GIT_COMMIT`, `BUILD_VERSION`
+- **Tags pushed:** date tag (`yymm`) + `latest` to both registries
+- **Annotations:** mirror the OCI label standard (PART 2), with `url`/`source`/
+  `documentation` set to the workflow's repository URL
+
+## Legacy workflow (`docker.yaml`)
+
+A hand-crafted `.gitea/workflows/docker.yaml` may exist in older repos — reference copy in
+the org-level `.github` repo. **Never overwrite it, and never use it as a template for new
+work** — it uses tag-pinned actions and retired secret names. All new/updated workflows
+come from `gen-dockerfile actions`.
+
+---
+
+# PART 8: VERIFICATION & COMMIT
+
+## Syntax gates
+
+Every touched script must pass before commit:
 
 ```bash
-pkmgr update          # Update package lists
-pkmgr install <pkg>   # Install packages
-pkmgr remove <pkg>    # Remove packages
-pkmgr clean           # Clean package cache
+for f in rootfs/usr/local/bin/*; do
+  [ -f "$f" ] || continue
+  case "$(head -1 "$f")" in
+    *bash*) bash -n "$f" || exit 1 ;;
+    *sh*)   sh -n "$f"   || exit 1 ;;
+  esac
+done
+
+bash -n rootfs/usr/local/etc/docker/functions/entrypoint.sh
+
+for f in rootfs/root/docker/setup/0*.sh rootfs/usr/local/etc/docker/init.d/*.sh; do
+  [ -f "$f" ] || continue
+  bash -n "$f" || exit 1
+done
 ```
 
-Automatically detects and uses the appropriate package manager (apk, apt-get, dnf, pacman).
+## Dead-reference gates
 
----
+After any regeneration:
 
-## Development Workflow
+1. No script references an env var removed from `.env.scripts` (diff-driven check).
+2. No script calls a function absent from both the current
+   `functions/entrypoint.sh` and the script itself.
+3. No `__copy_templates` calls remain (retired with `DEFAULT_TEMPLATE_DIR`).
+4. `Dockerfile` still pulls `FROM casjaysdev/*` (rule 8) — an upstream distro pull means
+   `GEN_DOCKERFILE_APP_DIR` resolved wrong during regeneration.
 
-### Creating a New Container
+## Commit
 
 ```bash
-# 1. Generate scaffolding
-gen-dockerfile --dir ./myapp alpine
-
-# 2. Customise .env.scripts (set ENV_REGISTRY_REPO, ENV_REGISTRY_ORG, ports, etc.)
-
-# 3. Customise setup scripts in rootfs/root/docker/setup/
-
-# 4. Generate an init.d runtime script
-gen-dockerfile --startup 01-myapp.sh
-
-# 5. Build and test
-docker build -t myapp .
-docker run -it myapp
-
-# 6. Commit and push to trigger CI/CD
+git status --porcelain
+git diff --stat
 ```
 
-### Updating an Existing Container
+Write `.git/COMMIT_MESS` from the actual diff — subject ≤64 chars, body as
+`- path: change` bullets covering every changed file. Then:
 
 ```bash
-# Regenerate Dockerfile and related files from current .env.scripts
-gen-dockerfile --dir ./myapp --update
-
-# Regenerate workflow file only
-gen-dockerfile --dir ./myapp actions
+gitcommit --dir "$(git rev-parse --show-toplevel)" all
 ```
 
-### Adding a New Container from Scratch
-
-1. `gen-dockerfile --dir /path/to/new-container --nogit alpine`
-2. Edit `.env.scripts` — set `ENV_REGISTRY_REPO`, `ENV_REGISTRY_PUSH`, `ENV_GIT_REPO_URL`
-3. Generate the init.d service script: `gen-dockerfile --startup 01-myapp.sh`
-4. Add application-specific setup in `rootfs/root/docker/setup/05-custom.sh`
-
----
-
-## Project Categories
-
-### Web Servers
-- nginx, lighttpd, caddy
-
-### Databases
-- mysql, mariadb, postgres, mongodb, couchdb, redis, valkey, sqlite
-
-### Development Tools
-- code, neovim, vim, nodejs, python, php, deno, bun
-
-### Container Tools
-- docker, podman
-
-### Git Services
-- gitea, forgejo, soft-serve, opengist
-
-### Media Services
-- ampache, navidrome, mpd, ympd, icecast, youtube-dl
-
-### Networking
-- bind, traefik, tor, i2pd, ddns, ifconfig
-
-### Communication
-- mailman, postfix, gotify, ntfy, apprise
-
-### Cloud Services
-- nextcloud, wordpress
-
-### Utilities
-- tools, transmission, aria2, tftpd, ssl-ca, wttr, xfce4, webmin
-
----
-
-## Resources
-
-- **Docker Hub:** <https://hub.docker.com/u/casjaysdevdocker>
-- **Git Repository:** <https://github.com/casjaysdevdocker>
-- **gen-dockerfile Tool:** `/usr/local/bin/gen-dockerfile`
-- **Template Source:** `/usr/local/share/CasjaysDev/scripts/templates/dockerfiles/` (installed) or `$CASJAYSDEVDIR/templates/dockerfiles/` (dev override)
-- **Example Project:** `casjaysdevdocker/.github/example/` (org-level repository — not present in individual container repos)
+`git commit` / `git push` directly are forbidden. Never commit with a failing syntax
+gate.