[minor] Document compose reconcile startup (#15)

Author: joecorall

apps.mdx

@@ -0,0 +1,65 @@
+---
+title: Managed applications
+description: How sitectl-managed application templates use Docker Compose, local image builds, and development overrides.
+---
+
+import { Compose } from "/snippets/compose-tooltip.mdx";
+
+`sitectl` application templates are normal <Compose /> projects with a shared operating contract. The repository owns the application workload, and `sitectl` supplies context-aware lifecycle commands, component updates, health checks, image overrides, and service helpers.
+
+## Compose Files
+
+`docker-compose.yml` or `docker-compose.yaml` is the production contract. It should describe the stack that runs on the host: services, volumes, secrets, Traefik ingress, health checks, build definitions, and the default published ports.
+
+Local-only changes belong in `docker-compose.override.yml`. That file is intentionally ignored by template repositories. Developers can use it for temporary bind mounts, image overrides, secrets used only on their workstation, and port swaps. Production should not rely on a Compose override file; production behavior should be visible in the tracked Compose file and tracked component changes.
+
+When an application service requires MariaDB during startup, declare that relationship in the tracked Compose file with `depends_on` and `condition: service_healthy`. The application plugins' standard healthcheck runner verifies that policy for MariaDB-backed web apps.
+
+## Local Image Builds
+
+Every application template includes a Dockerfile for the local application image. The Dockerfile starts from the matching LibOps base image, copies lockfiles and downloaded dependencies before copying local modules, plugins, themes, config, or other customization points, and leaves runtime configuration to the Compose environment where possible.
+
+This keeps local builds fast:
+
+- Docker can reuse package-manager and download cache layers when only local custom code changed.
+- The build uses the platform selected by the Docker CLI on the host.
+- Local builds do not push images. Publishing images belongs in CI or another explicit release workflow.
+
+The LibOps base images provide the default PHP and nginx configuration. When a template needs to tune upload size, timeouts, trusted proxy handling, or similar runtime behavior, prefer environment values in the Compose service over rebuilding nginx or PHP config into the downstream template image.
+
+Use [`sitectl image set`](/commands/image) when you need a local context to run a different image, tag, or build argument without editing the tracked template files.
+
+## Development Ports
+
+Application templates should publish standard ingress ports in the tracked Compose file:
+
+```yaml
+services:
+  traefik:
+    ports:
+      - "80:80"
+```
+
+If the stack serves HTTPS directly, publish `443:443` in the tracked Compose file as well. `sitectl` infers `URI_SCHEME=https` when the Compose project publishes target port `443` or Traefik declares an HTTPS entrypoint on `:443`; otherwise it uses `URI_SCHEME=http`.
+
+For local development contexts, [`sitectl compose up`](/commands/compose) checks whether `80` or `443` is already occupied. If another process owns a needed port, it writes `docker-compose.override.yml` with a Compose `ports: !override` entry such as:
+
+```yaml
+services:
+  traefik:
+    ports: !override
+      - "8443:443"
+```
+
+That smart port allocation is a development convenience only. It should not be committed and should not be part of production deployment.
+
+## Local HTTPS
+
+If production runs HTTPS and a developer wants the local site to behave the same way, use mkcert-backed Traefik TLS:
+
+```bash
+sitectl traefik tls mkcert --domain app.localhost
+sitectl compose up --remove-orphans -d
+```
+
+See [Traefik service commands](/plugins/traefik) for TLS modes and [Compose commands](/commands/compose) for the local port behavior.

commands/compose.mdx

@@ -5,15 +5,61 @@ description: Run Docker Compose commands through the active sitectl context.
 
 import { Compose } from "/snippets/compose-tooltip.mdx";
 import ComposeCmd from "/snippets/commands/sitectl-compose.mdx";
+import ComposeCleanCmd from "/snippets/commands/sitectl-compose-clean.mdx";
+import ComposeReconcileCmd from "/snippets/commands/sitectl-compose-reconcile.mdx";
 
 # <Compose /> command
 
 The `compose` command is a core `sitectl` command that runs <Compose /> commands against the active `sitectl` context.
 
 Use it when you want the same <Compose /> operation to respect the site and environment wiring already stored in the context.
 
-For local development contexts, `sitectl compose up` checks whether the default HTTP host port is already in use. If another process owns it, sitectl passes `HOST_INSECURE_PORT` to Docker Compose with the next available development port. It only checks and sets `HOST_SECURE_PORT` when the active Compose files publish target port `443` or reference `HOST_SECURE_PORT`, so HTTP-only stacks do not bind HTTPS. This behavior only applies to local dev contexts, not local production workloads.
+For local development contexts, `sitectl compose up` checks whether the default HTTP or HTTPS host port is already in use. If another process owns a needed port, sitectl writes `docker-compose.override.yml` with a Compose `ports: !override` entry for the next available development port before invoking Docker Compose.
+
+HTTP-only stacks publish target port `80` and use `URI_SCHEME=http`. Stacks that publish target port `443`, or whose Traefik command declares an HTTPS entrypoint on `:443`, use `URI_SCHEME=https`. This behavior only applies to local dev contexts, not local production workloads.
+
+See [Managed applications](/apps) for the application template Compose contract.
+
+## Reconcile
+
+For local plugin-owned contexts, `sitectl compose up` can perform a reconcile before handing off to Docker Compose. It reads the plugin's default create definition, checks init artifacts, declared volumes, and local image metadata, then runs the plugin's init and build commands when they are still needed.
+
+This lets a setup-only checkout start cleanly:
+
+```bash
+sitectl create ojs/default --setup-only --path ./ojs --type local --checkout-source template
+sitectl compose up
+```
+
+You can also run the same workflow explicitly:
+
+```bash
+sitectl compose reconcile
+sitectl compose reconcile --force
+sitectl compose reconcile --reset-init
+```
+
+The reconcile cache is local to the workstation and expires after 7 days. `--force` ignores the cache and reruns build/up. `--reset-init` removes plugin-declared init artifacts and init volumes, clears the cache entry, then reconciles again.
+
+The reconcile step is a synchronous CLI workflow for one local <Compose /> project. It borrows condition names such as `Initialized` and `ImagesAvailable`, but it is not a Kubernetes controller or background loop.
+
+## Clean
+
+Use `sitectl compose clean` when you need to throw away local runtime state and return to a fresh init/build flow:
+
+```bash
+sitectl compose clean
+sitectl compose clean --yes
+```
+
+`clean` runs `docker compose down -v`, removes plugin-declared init artifacts such as generated secrets, certs, UID markers, and env files, and clears the reconcile cache entry. It is destructive and prompts for a typed confirmation unless `--yes` is passed.
+
+See [Compose reconcile contract](/contributing/compose-reconcile) for the contributor-facing contract.
 
 ## Reference
 
 <ComposeCmd />
+
+<ComposeReconcileCmd />
+
+<ComposeCleanCmd />

commands/create.mdx

@@ -50,3 +50,26 @@ sitectl create drupal/default --path ./drupal --context staging
 Plugin-specific create flags (for example `--path`, `--type`, `--checkout-source`,
 `--setup-only`, or ISLE's `--fcrepo` and `--blazegraph`) still go after the target,
 because they belong to the plugin's create runner.
+
+## Setup-Only and First Start
+
+`--setup-only` creates the local checkout and context without starting the stack. A fresh template checkout may still run clone-time init. For plugin-owned local contexts, the first later `sitectl compose up` checks the plugin's declared init artifacts and images, then runs any remaining init or build commands before starting Compose:
+
+```bash
+sitectl create ojs/default --path ./ojs --type local --checkout-source template --setup-only
+sitectl compose up
+```
+
+That handoff uses the plugin create definition as desired lifecycle metadata. See [Compose reconcile contract](/contributing/compose-reconcile) for contributor details.
+
+## Image and Build Overrides
+
+Compose template create runners can accept image override flags:
+
+```bash
+sitectl create wp/default --path ./wp --type local --tag wp=nginx-1.30.3-php84
+sitectl create ojs/default --path ./ojs --type local --image ojs=ghcr.io/example/ojs:pr-123
+sitectl create drupal/default --path ./drupal --type local --build-arg drupal.BASE_IMAGE=libops/drupal:php84
+```
+
+These flags write the same local `docker-compose.override.yml` file used by [`sitectl image set`](/commands/image). Use `sitectl image set` later when you need to change image or build-arg overrides for an existing local context.

commands/healthcheck.mdx

@@ -12,6 +12,13 @@ context's plugin registers a healthcheck handler, its runtime checks run too and
 are merged into the report. The command exits non-zero if any check still fails
 after the timeout, so it is safe to use in scripts and CI.
 
+Application plugins use shared helpers for common web stacks: route checks, MariaDB
+ping checks, optional HTTP service checks, and the expected `depends_on:
+condition: service_healthy` relationship between the app container and MariaDB.
+For route checks, localhost-style URLs are tested from the host first; app-domain
+URLs can be checked from inside the app container with the correct HTTP `Host`
+header.
+
 ## Reference
 
 <HealthcheckCmd />

commands/image.mdx

@@ -0,0 +1,71 @@
+---
+title: image
+description: Manage local Docker Compose image and build-arg overrides.
+---
+
+import { Compose } from "/snippets/compose-tooltip.mdx";
+import ImageCmd from "/snippets/commands/sitectl-image.mdx";
+import ImageClearCmd from "/snippets/commands/sitectl-image-clear.mdx";
+import ImageSetCmd from "/snippets/commands/sitectl-image-set.mdx";
+
+The `image` command manages local <Compose /> image overrides for the active `sitectl` context.
+
+Use `sitectl image set` when you want a local site to run a different image tag, image reference, or build argument without editing the upstream template files directly.
+
+```bash
+sitectl image set --tag wp=nginx-1.30.3-php84
+sitectl image set --image app=ghcr.io/example/app:pr-123
+sitectl image set --build-arg app.BASE_IMAGE=libops/app:php84
+```
+
+`sitectl image set` currently requires a local context with a project directory. It writes `docker-compose.override.yml` in that project.
+
+Use `sitectl image clear` to remove image and build-arg override keys without deleting unrelated local override content:
+
+```bash
+sitectl image clear
+sitectl image clear wp
+```
+
+With no service arguments, `clear` removes image/build-arg overrides for every service in the override file. With service arguments, it clears only those services.
+
+## Flags
+
+| Flag | Format | Use |
+|---|---|---|
+| `--tag` | `SERVICE=TAG` | Set a known LibOps service to a published LibOps tag. |
+| `--image` | `SERVICE=IMAGE` | Set any Compose service to an explicit image reference. |
+| `--build-arg` | `SERVICE.ARG=VALUE` | Set a Compose build argument for a service. |
+
+`--tag` only works for services known to sitectl's shared LibOps image map. For app-specific services, use `--image` or `--build-arg`.
+
+## Compose Reconcile
+
+Image overrides participate in the first-run `sitectl compose up` reconcile contract:
+
+- an explicit image override for a service means core does not require the plugin's default image to exist locally
+- a build-arg override triggers the build phase so the new arguments are applied
+- the override file fingerprint is part of the local reconcile cache key
+
+After changing overrides, run:
+
+```bash
+sitectl compose up
+```
+
+If you clear a build-arg override and want to rebuild with the default image metadata immediately, run:
+
+```bash
+sitectl image clear wp
+sitectl compose reconcile --force
+```
+
+See [Compose reconcile contract](/contributing/compose-reconcile) for the contributor-facing contract.
+
+## Reference
+
+<ImageCmd />
+
+<ImageSetCmd />
+
+<ImageClearCmd />

contributing/app-template.mdx

@@ -0,0 +1,125 @@
+---
+title: Application plugin template
+description: How to build a new Compose-backed sitectl application plugin from sitectl-app-tmpl.
+---
+
+import { Compose } from "/snippets/compose-tooltip.mdx";
+
+Use [`sitectl-app-tmpl`](https://github.com/libops/sitectl-app-tmpl) when adding a new application plugin for a standalone <Compose /> template repository.
+
+The template is intentionally thin. The application repository owns the Compose workload. Core `sitectl` owns shared lifecycle commands. The plugin contributes app-specific metadata and helpers.
+
+## Command Ownership
+
+| Concern | Owner | Examples |
+|---|---|---|
+| Compose lifecycle | Core `sitectl` | `sitectl compose up`, `sitectl compose down`, `sitectl compose logs`, `sitectl compose ps` |
+| Create flow metadata | App plugin | `CreateSpec`, template repo, init artifacts, image specs |
+| App-specific commands | App plugin | `sitectl <app> exec ...`, API wrappers, application maintenance helpers |
+| Shared service operations | Core `sitectl` | `sitectl mariadb backup`, `sitectl solr info`, `sitectl traefik tls` |
+| Cross-cutting reports | Core command plus plugin runner | `sitectl debug`, `sitectl validate`, `sitectl healthcheck` |
+
+New app plugins should usually call `RegisterComposeTemplateCreateRunner`, not `RegisterStandardComposeTemplate`. The latter still exists for plugins that deliberately want direct namespace lifecycle commands, but first-class app plugins should let core `sitectl compose` provide the shared lifecycle surface.
+
+## Create Definition Contract
+
+The create definition is more than a clone recipe. It is also the desired state metadata used by core `sitectl compose up` to decide whether a local checkout needs first-run init or image build work. See [Compose reconcile contract](/contributing/compose-reconcile) for the shared core behavior.
+
+```go
+func createDefinition() plugin.CreateSpec {
+    return plugin.CreateSpec{
+        Name:                "default",
+        Default:             true,
+        DockerComposeRepo:   TemplateRepo,
+        DockerComposeBranch: TemplateBranch,
+        DockerComposeInit: []string{
+            "if [ ! -f .env ]; then cp sample.env .env; fi",
+            "docker compose run --rm init",
+        },
+        InitArtifacts: []plugin.InitArtifact{
+            {Path: ".env"},
+            {Path: "secrets/DB_ROOT_PASSWORD"},
+            {Path: "secrets/APP_DB_PASSWORD"},
+        },
+        InitVolumes: []plugin.InitVolume{
+            {Name: "mariadb-data"},
+        },
+        DockerComposeBuild: []string{
+            "docker compose pull --ignore-buildable",
+            "docker compose build --pull",
+        },
+        Images: []plugin.ComposeImageSpec{
+            {
+                Service:     "app",
+                Image:       "libops/app:local",
+                BuildPolicy: plugin.BuildPolicyIfNotPresent,
+            },
+        },
+        DockerComposeUp: []string{
+            "docker compose up --remove-orphans -d",
+        },
+        DockerComposeDown:    []string{"docker compose down"},
+        DockerComposeRollout: []string{"./scripts/rollout.sh"},
+    }
+}
+```
+
+`DockerComposeInit` should be idempotent. It may create `.env`, run an `init` service, and write deterministic secret files. It must not destroy existing application data when run again.
+
+`InitArtifacts` should list files that prove init has completed. Prefer explicit files over probing container state. Use `ValueFrom: plugin.InitArtifactValueFromHostUID` for a UID marker file when generated files need to match the local host user.
+
+`InitVolumes` should list named Compose volumes that prove first-start runtime state exists, such as database volumes and application file/upload volumes. Core resolves those names through `docker compose config`, so custom Compose project names and explicit volume names still work.
+
+`Images` should list local images the template expects to build. Use `BuildPolicyIfNotPresent` for normal local images, `BuildPolicyAlways` only when every `compose up` should rebuild, and `BuildPolicyNever` for services that should never trigger the build phase.
+
+## Image Overrides
+
+Core `sitectl image set` writes `docker-compose.override.yml` for local contexts:
+
+```bash
+sitectl image set --tag mariadb=11.4
+sitectl image set --image app=ghcr.io/example/app:pr-123
+sitectl image set --build-arg app.BASE_IMAGE=libops/app:php84
+```
+
+Image overrides affect reconcile:
+
+- an explicit image override for a service means core does not require the plugin's default image to exist locally
+- a build-arg override triggers the build phase so the new arguments are applied
+- the override file fingerprint is part of the reconcile cache key
+
+Use `--image` or `--build-arg` for app-specific services that are not known to the shared `--tag` map.
+
+## Template Checklist
+
+After creating a repository from `sitectl-app-tmpl`:
+
+1. Rename the Go module, binary, plugin name, display name, and release workflow outputs.
+2. Set `TemplateRepo`, `TemplateBranch`, `DefaultPath`, `AppService`, `AppImage`, `DatabaseService`, `DatabaseName`, and codebase rootfs constants.
+3. Update `CreateSpec` lifecycle commands, `InitArtifacts`, `InitVolumes`, and `Images` to match the real template repository.
+4. Tune project discovery in `SetComposeProjectDiscovery`. Use service names and durable codebase markers that identify the real project.
+5. Keep app-specific commands in the plugin namespace. Avoid registering `build`, `init`, `up`, `down`, `status`, `logs`, or `rollout` unless the app has a deliberate compatibility need.
+6. Use core service commands for shared operations. For example, document `sitectl mariadb backup app` rather than adding a thin app plugin alias.
+7. Implement debug, validate, and healthcheck runners through the SDK. Results should be structured; progress and diagnostics should go to stderr.
+8. Keep local workspace wiring in `go.work`; do not add sibling-module `replace` directives to `go.mod`.
+9. Update the integration script to create with `--setup-only`, start with `sitectl compose up`, and then run `sitectl healthcheck`.
+10. Add a plugin page to `sitectl-docs` for app-specific operations.
+
+## Local Verification
+
+Run the standard local workflow:
+
+```bash
+make work
+make test
+make install
+```
+
+Then verify the installed plugin can be discovered and used through core commands:
+
+```bash
+sitectl create app-tmpl/default --path ./app --type local --checkout-source template --setup-only
+sitectl compose up
+sitectl healthcheck
+sitectl app-tmpl exec -- printenv
+```