From 77746ab054a8601c7804f934245e13e4c5f1d12b Mon Sep 17 00:00:00 2001
From: Michael Johnson <buhnux@gmail.com>
Date: Thu, 1 Oct 2026 18:08:44 -0400
Subject: [PATCH 1/2] generate: stack choices, one way to deploy per runtime;
 release v1.10.0

x-daemonless.choices. A database choice (kind: database) names the engines
the app runs on and what it calls the connection in its own env; dbuild
supplies the postgres or mariadb service from one shared definition, so
twenty apps do not carry twenty copies of the same block and a fix lands
everywhere. sqlite runs nothing; external asks for a database the person
already runs. A part choice (immich's machine learning) is the app's own:
a profile to switch on, env to set, values to ask for. The default is
always the compose as it stands, so podman-compose up -d with nothing set
is the default answer; lint refuses a default that switches something on
and a mapped variable the app never reads.
---
 .github/workflows/daemonless-build.yaml  |   2 +-
 dbuild/__init__.py                       |   2 +-
 dbuild/choices.py                        | 410 +++++++++++++++++++++++
 dbuild/config.py                         |  16 +-
 dbuild/docs.py                           | 121 +++++++
 dbuild/lint.py                           |   5 +
 dbuild/templates/README.j2               | 224 +++++--------
 dbuild/templates/README.mkdocs.j2        | 188 ++++++-----
 dbuild/templates/appjail-director.yml.j2 |   5 +-
 docs/dbuild.1                            |   2 +-
 tests/test_docs.py                       | 185 ++++++++++
 11 files changed, 924 insertions(+), 236 deletions(-)
 create mode 100644 dbuild/choices.py

diff --git a/.github/workflows/daemonless-build.yaml b/.github/workflows/daemonless-build.yaml
index 5b3e73a..83e3c75 100644
--- a/.github/workflows/daemonless-build.yaml
+++ b/.github/workflows/daemonless-build.yaml
@@ -50,7 +50,7 @@ on:
 
 env:
   REGISTRY: ghcr.io
-  DBUILD_REF: v1.9.17
+  DBUILD_REF: v1.10.0
 
 jobs:
   # Detect which variants exist and build dynamic matrix
diff --git a/dbuild/__init__.py b/dbuild/__init__.py
index 849ab40..a8c4b3a 100644
--- a/dbuild/__init__.py
+++ b/dbuild/__init__.py
@@ -1,4 +1,4 @@
 """dbuild: FreeBSD OCI container image build tool.
 """
 
-VERSION = "1.9.17"
+VERSION = "1.10.0"
diff --git a/dbuild/choices.py b/dbuild/choices.py
new file mode 100644
index 0000000..52aba7f
--- /dev/null
+++ b/dbuild/choices.py
@@ -0,0 +1,410 @@
+"""Stack choices: what a compose offers under ``x-daemonless.choices``.
+
+Two kinds of choice. The common one is a **database**: the app says which
+engines it can run on and what it calls the connection in its own env, and
+dbuild supplies the services -- one definition of a daemonless postgres or
+mariadb service, shared by every app, fixed in one place::
+
+    x-daemonless:
+      choices:
+        database:
+          kind: database
+          offers: [sqlite, postgres, mariadb, external]
+          default: sqlite
+          env:
+            type: VIKUNJA_DATABASE_TYPE       # the app's own names
+            host: VIKUNJA_DATABASE_HOST
+            user: VIKUNJA_DATABASE_USER
+            password: VIKUNJA_DATABASE_PASSWORD
+            name: VIKUNJA_DATABASE_DATABASE
+          types: { mariadb: mysql }           # the app's word for an engine, when it differs
+
+The app's service reads those variables (``${VIKUNJA_DATABASE_TYPE:-sqlite}``
+and so on); lint checks they are there. The generated database service reads
+the same variables, so one .env feeds both and nothing is wired by hand.
+``external`` is a database the person already runs: no service, the
+connection asked for.
+
+The other kind is a **part** the app can run with or without (immich's
+machine learning). That one is the app's own, so it is written out: a
+profile to switch on, env to set, values to ask for::
+
+    choices:
+      machine_learning:
+        label: Machine learning
+        default: "on"
+        options:
+          "on":  { label: On, profile: ml }
+          "off": { label: Off, env: { IMMICH_ML_ENABLED: "false" } }
+
+Either way the default option is the compose as it stands: it names no
+profile and adds no service, so ``podman-compose up -d`` with nothing set
+is the default answer -- what a script, or a host with no UI, gets.
+
+For everyone who copies files instead of running fjord, each non-default
+option gets a flattened pair: ``compose.<choice>-<option>.yaml`` with that
+option's services in and the others out, and ``example.<choice>-<option>.env``
+with its values applied. Generated, committed like README.md, never edited.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import yaml
+
+# The database engines dbuild knows how to run. One place: an app that
+# offers postgres gets this service, and a fix here fixes every app.
+ENGINES: dict[str, dict[str, Any]] = {
+    "sqlite": {"label": "SQLite", "type": "sqlite",
+               "doc": "A file in the app's config folder. Right for one person, nothing extra to run."},
+    "postgres": {
+        "label": "PostgreSQL", "type": "postgres", "service": "postgres", "port": 5432,
+        "image": "ghcr.io/daemonless/postgres:17", "data": "/var/lib/postgresql/data",
+        "env": {"user": "POSTGRES_USER", "password": "POSTGRES_PASSWORD", "name": "POSTGRES_DB"},
+        # PostgreSQL wants SysV shared memory, which a jail does not get by
+        # default; without it the server fails with an error that reads like
+        # a configuration problem.
+        "annotations": {"org.freebsd.jail.allow.sysvipc": "true"},
+        "jail_template": (
+            "# The jail PostgreSQL runs in: SysV shared memory, which a jail does not\n"
+            "# get by default. ip4/ip6 are set here because the director's ip4_inherit\n"
+            "# option is a no-op in AppJail 5.5.0.\n\n"
+            "exec.start: \"/bin/sh /etc/rc\"\nexec.stop: \"/bin/sh /etc/rc.shutdown jail\"\n"
+            "sysvmsg: new\nsysvsem: new\nsysvshm: new\nmount.devfs\npersist\nip4: inherit\nip6: inherit\n"
+        ),
+        "doc": "One more container, its data in its own folder. For a household, or an app that wants it.",
+    },
+    "mariadb": {
+        "label": "MariaDB", "type": "mysql", "service": "mariadb", "port": 3306,
+        "image": "ghcr.io/daemonless/mariadb:11.4", "data": "/config",
+        "env": {"user": "MYSQL_USER", "password": "MYSQL_PASSWORD", "name": "MYSQL_DATABASE"},
+        "extra_env": {"MYSQL_ROOT_PASSWORD": "${{{password}}}"},
+        "doc": "One more container, its data in its own folder. If you already know MariaDB, or the app prefers it.",
+    },
+    "external": {"label": "Your own", "type": "",
+                 "doc": "A database you already run, here or on another machine. Nothing extra runs; you give the address and the account."},
+}
+
+
+@dataclass
+class Ask:
+    name: str
+    label: str = ""
+    default: str = ""
+    type: str = "string"            # string | secret
+    values: dict[str, str] = field(default_factory=dict)  # a fixed set to pick from
+
+
+@dataclass
+class Option:
+    id: str
+    label: str
+    doc: str = ""
+    profile: str = ""
+    env: dict[str, str] = field(default_factory=dict)
+    ask: list[Ask] = field(default_factory=list)
+    # A service dbuild adds for this option (database kind), as compose YAML
+    # text under services:, and the .env lines it needs beyond env/ask.
+    service_yaml: str = ""
+    env_lines: list[str] = field(default_factory=list)
+    # The same service for appjail-director: a depends_on entry the director
+    # template renders, the env that differs there (the host is the jail's
+    # name), and a jail template file when the engine needs one.
+    director_dep: dict[str, Any] = field(default_factory=dict)
+    env_appjail: dict[str, str] = field(default_factory=dict)
+    jail_template_file: str = ""
+    jail_template: str = ""
+
+
+@dataclass
+class Choice:
+    id: str
+    label: str
+    kind: str = "part"               # part | database
+    doc: str = ""
+    default: str = ""
+    service: str = ""                # the app service the choice wires (database); "" = first
+    env_map: dict[str, str] = field(default_factory=dict)   # database: role -> the app's variable
+    options: list[Option] = field(default_factory=list)
+
+    @property
+    def default_option(self) -> Option | None:
+        return next((o for o in self.options if o.id == self.default), None)
+
+
+def _database_options(cid: str, c: dict[str, Any], services: dict[str, Any]) -> tuple[list[Option], dict[str, str]]:
+    env_map = {str(k): str(v) for k, v in (c.get("env") or {}).items()}
+    types = {str(k): str(v) for k, v in (c.get("types") or {}).items()}
+    offers = [str(x) for x in (c.get("offers") or [])]
+    app = str(c.get("service", "")) or (next(iter(services)) if services else "app")
+    var = lambda role, fallback: env_map.get(role, fallback)  # noqa: E731
+    v_type, v_host, v_port = var("type", ""), var("host", ""), var("port", "")
+    v_user, v_pass, v_name = var("user", f"{cid.upper()}_USER"), var("password", f"{cid.upper()}_PASSWORD"), var("name", f"{cid.upper()}_NAME")
+    v_data = f"{cid.upper()}_LOCATION"   # the fleet's name for a data folder (UPLOAD_LOCATION, DB_DATA_LOCATION)
+    opts: list[Option] = []
+    for eid in offers:
+        e = ENGINES.get(eid)
+        if e is None:
+            continue
+        word = types.get(eid, e["type"])
+        if eid == "external":
+            kinds = {types.get(k, ENGINES[k]["type"]): ENGINES[k]["label"] for k in offers if k in ("postgres", "mariadb")}
+            ask = []
+            if v_type:
+                ask.append(Ask(name=v_type, label="Kind", values=kinds))
+            ask += [Ask(name=v_host, label="Host")] if v_host else []
+            ask += [Ask(name=v_port, label="Port")] if v_port else []
+            ask += [Ask(name=v_user, label="User"), Ask(name=v_pass, label="Password", type="secret"), Ask(name=v_name, label="Database")]
+            opts.append(Option(id=eid, label=e["label"], doc=e["doc"], ask=ask))
+            continue
+        env = {v_type: word} if v_type else {}
+        if "service" not in e:            # sqlite: nothing to run
+            opts.append(Option(id=eid, label=e["label"], doc=e["doc"], env=env))
+            continue
+        # A service dbuild supplies. It reads the app's variables, so one
+        # .env feeds both sides.
+        env.update({v_host: e["service"]} if v_host else {})
+        env.update({v_port: str(e["port"])} if v_port else {})
+        extra = "".join(f"      - {k}={v.format(password=v_pass)}\n" for k, v in (e.get("extra_env") or {}).items())
+        ann = "".join(f"      {k}: \"{v}\"\n" for k, v in (e.get("annotations") or {}).items())
+        service_yaml = (
+            f"  {e['service']}:\n"
+            f"    image: {e['image']}\n"
+            f"    restart: always\n"
+            + (f"    annotations:\n{ann}" if ann else "")
+            + f"    environment:\n"
+            f"      - {e['env']['user']}=${{{v_user}}}\n"
+            f"      - {e['env']['password']}=${{{v_pass}}}\n"
+            f"      - {e['env']['name']}=${{{v_name}}}\n"
+            f"{extra}"
+            f"    volumes:\n"
+            f"      - \"${{{v_data}}}:{e['data']}\"\n"
+        )
+        env_lines = [f"{v_user}={app}", f"{v_pass}=  # set one", f"{v_name}={app}", f"{v_data}=/containers/{app}/{e['service']}"]
+        # appjail-director: the service is a jail named <app>_<engine>, which
+        # is also its hostname on the project's network; it starts before the
+        # app (director starts by ascending priority, default 99).
+        jail = f"{app}-{e['service']}"
+        tpl_file = f"{e['service']}-template.conf" if e.get("jail_template") else ""
+        dep_env = {e["env"]["user"]: f"!ENV '${{{v_user}}}'", e["env"]["password"]: f"!ENV '${{{v_pass}}}'",
+                   e["env"]["name"]: f"!ENV '${{{v_name}}}'"}
+        for k, v in (e.get("extra_env") or {}).items():
+            dep_env[k] = "!ENV '" + v.format(password=v_pass) + "'"
+        director_dep = {"name": jail, "image": e["image"], "template": tpl_file, "priority": 10,
+                        "env": dep_env, "volumes": {cid: e["data"]}}
+        env_appjail = {v_host: jail.replace("-", "_")} if v_host else {}
+        opts.append(Option(id=eid, label=e["label"], doc=e["doc"], env=env, service_yaml=service_yaml, env_lines=env_lines,
+                           director_dep=director_dep, env_appjail=env_appjail,
+                           jail_template_file=tpl_file, jail_template=e.get("jail_template", "")))
+    return opts, env_map
+
+
+def parse(meta: dict[str, Any], compose_data: dict[str, Any] | None = None) -> list[Choice]:
+    """Read ``x-daemonless.choices`` into Choice objects. Shape errors are
+    left to lint; here anything unreadable is skipped."""
+    raw = meta.get("choices")
+    if not isinstance(raw, dict):
+        return []
+    services = (compose_data or {}).get("services") or {}
+    out: list[Choice] = []
+    for cid, c in raw.items():
+        if not isinstance(c, dict):
+            continue
+        kind = str(c.get("kind", "part"))
+        env_map: dict[str, str] = {}
+        if kind == "database":
+            opts, env_map = _database_options(str(cid), c, services)
+            label = str(c.get("label", "Database"))
+            doc = str(c.get("doc", "")) or "Where the app keeps its data. The default needs nothing else running."
+
+        else:
+            label, doc = str(c.get("label", str(cid))), str(c.get("doc", ""))
+            opts = []
+            for oid, o in (c.get("options") or {}).items():
+                o = o if isinstance(o, dict) else {}
+                asks = []
+                for a in o.get("ask") or []:
+                    if isinstance(a, dict) and a.get("name"):
+                        asks.append(Ask(
+                            name=str(a["name"]), label=str(a.get("label", "")),
+                            default=str(a.get("default", "")), type=str(a.get("type", "string")),
+                            values={str(k): str(v) for k, v in (a.get("values") or {}).items()},
+                        ))
+                opts.append(Option(
+                    id=str(oid), label=str(o.get("label", str(oid))), doc=str(o.get("doc", "")),
+                    profile=str(o.get("profile", "")),
+                    env={str(k): str(v) for k, v in (o.get("env") or {}).items()},
+                    ask=asks,
+                ))
+        default = str(c.get("default", "")) or (opts[0].id if opts else "")
+        out.append(Choice(id=str(cid), label=label, kind=kind, doc=doc, default=default,
+                          service=str(c.get("service", "")), env_map=env_map, options=opts))
+    return out
+
+
+def validate(choices: list[Choice], compose_data: dict[str, Any]) -> list[str]:
+    """What lint reports about a declaration."""
+    errors: list[str] = []
+    services = compose_data.get("services") or {}
+    profiled: dict[str, list[str]] = {}
+    for name, svc in services.items():
+        for p in (svc or {}).get("profiles") or []:
+            profiled.setdefault(str(p), []).append(name)
+    raw = (compose_data.get("x-daemonless") or {}).get("choices") or {}
+    for c in choices:
+        where = f"x-daemonless.choices.{c.id}"
+        if not c.options:
+            errors.append(f"{where}: no options")
+            continue
+        if c.default_option is None:
+            errors.append(f"{where}: default '{c.default}' is not one of its options")
+        elif c.default_option.profile or c.default_option.service_yaml:
+            errors.append(f"{where}: the default option '{c.default}' switches a service on; "
+                          "the default is the compose as it stands")
+        if c.kind == "database":
+            for eid in (raw.get(c.id) or {}).get("offers") or []:
+                if str(eid) not in ENGINES:
+                    errors.append(f"{where}: offers '{eid}', which dbuild does not know (one of {', '.join(ENGINES)})")
+            app = c.service or (next(iter(services)) if services else "")
+            svc = services.get(app) or {}
+            raw_env = svc.get("environment") or []
+            names = set(raw_env.keys()) if isinstance(raw_env, dict) else {str(e).split("=", 1)[0] for e in raw_env}
+            for role, var in c.env_map.items():
+                if var not in names:
+                    errors.append(f"{where}.env.{role}: {var} is not in {app}'s environment, so the choice would set a variable the app never reads")
+            if services.get(c.default_option.id if c.default_option else ""):
+                pass
+            for o in c.options:
+                if o.service_yaml and ENGINES[o.id]["service"] in services:
+                    errors.append(f"{where}: the compose already has a '{ENGINES[o.id]['service']}' service; dbuild supplies it for the {o.label} option")
+        for o in c.options:
+            if o.profile and o.profile not in profiled:
+                errors.append(f"{where}.options.{o.id}: no service carries profiles: [{o.profile}]")
+            for a in o.ask:
+                if a.type not in ("string", "secret"):
+                    errors.append(f"{where}.options.{o.id}: ask {a.name}: type must be string or secret")
+    return errors
+
+
+# --- flattening ---------------------------------------------------------
+
+_SERVICE_RE = re.compile(r"^  ([A-Za-z0-9_.-]+):\s*(#.*)?$")
+
+
+def flatten_compose(text: str, compose_data: dict[str, Any], option: Option | None) -> str:
+    """The compose for one option: its profile's services in, every other
+    profiled service out, ``profiles:`` keys gone, and the service dbuild
+    supplies (a database) appended under ``services:``.
+
+    Line-based so the comments survive -- they are the explanation a reader
+    needs, and a YAML round trip drops them. Checked afterwards by parsing:
+    the result has to hold exactly the services the option gets.
+    """
+    profile = option.profile if option else ""
+    services = compose_data.get("services") or {}
+    keep = {n for n, s in services.items()
+            if not (s or {}).get("profiles") or profile in [str(p) for p in (s or {}).get("profiles")]}
+    # The app waits for the service dbuild adds: compose starts a
+    # depends_on first, so the app does not spend its first seconds
+    # retrying a database that is still coming up.
+    app = next(iter(services), "")
+    dep = _SERVICE_RE.match(option.service_yaml.splitlines()[0]).group(1) if option and option.service_yaml else ""
+    out: list[str] = []
+    in_services = False
+    dropping = False
+    skipping_profiles = False
+    inserted = False
+    for line in text.splitlines():
+        top = bool(line) and not line[0].isspace() and not line.startswith("#")
+        if top:
+            if in_services and option and option.service_yaml and not inserted:
+                out.append(option.service_yaml.rstrip("\n"))
+                inserted = True
+            in_services = line.startswith("services:")
+            dropping = False
+            skipping_profiles = False
+            out.append(line)
+            continue
+        if in_services:
+            m = _SERVICE_RE.match(line)
+            if m:
+                dropping = m.group(1) not in keep
+                skipping_profiles = False
+                if not dropping and dep and m.group(1) == app:
+                    out.append(line)
+                    out.append(f"    depends_on: [{dep}]")
+                    continue
+            if dropping:
+                continue
+            stripped = line.strip()
+            if re.match(r"^profiles:\s*(\[.*\])?\s*$", stripped):
+                skipping_profiles = stripped.endswith("profiles:")   # block list follows
+                continue
+            if skipping_profiles:
+                if stripped.startswith("- "):
+                    continue
+                skipping_profiles = False
+        out.append(line)
+    if in_services and option and option.service_yaml and not inserted:
+        out.append(option.service_yaml.rstrip("\n"))
+        inserted = True
+    result = "\n".join(out).rstrip("\n") + "\n"
+    result = re.sub(r"\n{3,}", "\n\n", result)
+    want = set(keep)
+    if option and option.service_yaml:
+        want.add(_SERVICE_RE.match(option.service_yaml.splitlines()[0]).group(1))
+    got = set(((yaml.safe_load(result) or {}).get("services") or {}).keys())
+    if got != want:
+        raise ValueError(f"flattening for option '{option.id if option else 'default'}' kept {sorted(got)}, "
+                         f"wanted {sorted(want)}; the compose's services need two-space indents")
+    return result
+
+
+def env_with_option(example_env: str, choice: Choice, option: Option) -> str:
+    """example.env with the option's values applied and its asks listed.
+
+    A key already in the file is replaced in place; the rest lands under a
+    heading for the option. Asked values are left empty, their label as the
+    comment, so a reader sees what to fill in.
+    """
+    lines = example_env.rstrip("\n").splitlines() if example_env.strip() else []
+    pending: list[tuple[str, str, str]] = []  # (key, value, comment)
+    for k, v in option.env.items():
+        pending.append((k, v, ""))
+    for ln in option.env_lines:
+        k, _, rest = ln.partition("=")
+        v, _, comment = rest.partition("  # ")
+        pending.append((k, v, comment))
+    for a in option.ask:
+        if any(a.name == k for k, _, _ in pending):
+            continue
+        comment = a.label or a.name
+        if a.values:
+            comment += ": " + " | ".join(a.values.keys())
+        pending.append((a.name, a.default, comment))
+    remaining: list[tuple[str, str, str]] = []
+    for k, v, comment in pending:
+        done = False
+        for i, ln in enumerate(lines):
+            if re.match(rf"^#?\s*{re.escape(k)}=", ln):
+                lines[i] = f"{k}={v}" + (f"  # {comment}" if comment else "")
+                done = True
+                break
+        if not done:
+            remaining.append((k, v, comment))
+    if remaining:
+        if lines:
+            lines.append("")
+        lines.append(f"# {choice.label}: {option.label}")
+        for k, v, comment in remaining:
+            lines.append(f"{k}={v}" + (f"  # {comment}" if comment else ""))
+    return "\n".join(lines) + "\n"
+
+
+def variant_names(choice: Choice, option: Option) -> tuple[str, str]:
+    """(compose file, env file) for a non-default option."""
+    suffix = f"{choice.id}-{option.id}"
+    return f"compose.{suffix}.yaml", f"example.{suffix}.env"
diff --git a/dbuild/config.py b/dbuild/config.py
index 751c8d9..ae9170b 100644
--- a/dbuild/config.py
+++ b/dbuild/config.py
@@ -15,6 +15,8 @@
 from pathlib import Path
 from typing import Any
 
+from dbuild import choices as choices_mod
+
 DEFAULT_COMMUNITY = "Discord:https://discord.gg/Kb9tkhecZT"
 
 try:
@@ -383,7 +385,7 @@ class Metadata:
         "desc": (
             "Image class controlling README layout. Valid values: "
             + ", ".join(f"`{c}`" for c in VALID_IMAGE_CLASSES)
-            + ". `service` (default): persistent daemon with compose/CLI/ansible docs. "
+            + ". `service` (default): persistent daemon with compose, AppJail Director and Bastille docs. "
             "`cli`: run-and-exit tool, deployment section replaced with usage example. "
             "`base`: base image for FROM, no deployment docs."
         ),
@@ -391,6 +393,10 @@ class Metadata:
     deprecated: DeprecationInfo | None = field(default=None, metadata={
         "desc": "Mark this image as deprecated. Bare key disables builds; pass a dict with `reason`, `replacement`, `sunset_date`, and/or `migration_guide` for structured messaging.",
     })
+    choices: list[Any] = field(default_factory=list, metadata={
+        "doc": "Stack choices (x-daemonless.choices): what the compose offers "
+               "under profiles -- a database to pick, a part to leave out. See dbuild.choices.",
+    })
     readme: ReadmeBlocks | None = field(default=None, metadata={
         "desc": "Custom Markdown blocks to inject into specific sections of the README.",
     })
@@ -420,6 +426,7 @@ class Config:
     # environment. Empty for a single service, where the snippet is right.
     compose_text: str = ""
     example_env: str = ""
+    compose_data: dict[str, Any] = field(default_factory=dict)
 
     @property
     def full_image(self) -> str:
@@ -751,6 +758,7 @@ def _parse_metadata(data: dict[str, Any], app_name: str, base: Path | None = Non
         healthcheck=meta.get("healthcheck"),
         docs=meta.get("docs", {}),
         image_class=meta.get("class", "service"),
+        choices=choices_mod.parse(meta, data),
         deprecated=_parse_deprecated(meta),
         readme=ReadmeBlocks(**meta.get("readme", {})),
     )
@@ -957,7 +965,10 @@ def load(base: Path | None = None) -> Config:
     compose_text = ""
     example_env = ""
     services = compose_data.get("services")
-    if isinstance(services, dict) and len(services) > 1:
+    # The compose itself is what people copy when it is more than one
+    # service -- or offers choices, since the flattened files start from it.
+    offers_choices = bool((compose_data.get("x-daemonless") or {}).get("choices"))
+    if isinstance(services, dict) and (len(services) > 1 or offers_choices):
         compose_text = _without_top_level_key(compose_path.read_text(), "x-daemonless")
         example_env_path = base / "example.env"
         if example_env_path.is_file():
@@ -976,6 +987,7 @@ def load(base: Path | None = None) -> Config:
         ports=ports,
         compose_text=compose_text,
         example_env=example_env,
+        compose_data=compose_data if isinstance(compose_data, dict) else {},
     )
 
 
diff --git a/dbuild/docs.py b/dbuild/docs.py
index 955c7ce..6bf566c 100644
--- a/dbuild/docs.py
+++ b/dbuild/docs.py
@@ -19,7 +19,10 @@
 
 import dataclasses
 
+import yaml
+
 import dbuild
+from dbuild import choices as choices_mod
 from dbuild import log
 from dbuild.config import (
     DEFAULT_COMMUNITY,
@@ -314,6 +317,108 @@ def _site_placeholders(text: str, env_file: bool = False) -> str:
     return text
 
 
+def _choice_variants(cfg: Config) -> list[tuple[Any, Any, str, str]]:
+    """(choice, option, compose text, env text) for every non-default option."""
+    out = []
+    for c in cfg.metadata.choices:
+        for o in c.options:
+            if o.id == c.default:
+                continue
+            compose_text = choices_mod.flatten_compose(cfg.compose_text, cfg.compose_data, o)
+            out.append((c, o, compose_text, choices_mod.env_with_option(cfg.example_env, c, o)))
+    return out
+
+
+def _choice_context(cfg: Config, context_env: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """The choices as the templates read them: options in declared order,
+    the default first, each with its files in both renderings. context_env
+    is the app's env list as the templates see it (name/default/placeholder)."""
+    if not cfg.metadata.choices or not cfg.compose_text:
+        return []
+    variants = {(c.id, o.id): (ct, et) for c, o, ct, et in _choice_variants(cfg)}
+    out = []
+    for c in cfg.metadata.choices:
+        opts = []
+        ordered = sorted(c.options, key=lambda o: o.id != c.default)
+        for o in ordered:
+            if o.id == c.default:
+                # The default is the file as it stands.
+                ct, et = choices_mod.flatten_compose(cfg.compose_text, cfg.compose_data, None), cfg.example_env
+                compose_file, env_file = "compose.yaml", "example.env"
+            else:
+                ct, et = variants[(c.id, o.id)]
+                compose_file, env_file = choices_mod.variant_names(c, o)
+            # The AppJail side: the director's depends_on grows the engine's
+            # jail, and the .env takes the option's values with the host
+            # being that jail's name.
+            aj = dict(cfg.metadata.appjail) if isinstance(cfg.metadata.appjail, dict) else {}
+            if o.director_dep:
+                aj["depends_on"] = [*(aj.get("depends_on") or []), o.director_dep]
+            values = dict(o.env)
+            values.update(o.env_appjail)
+            for ln in o.env_lines:
+                k, _, rest = ln.partition("=")
+                values.setdefault(k, rest.partition("  #")[0].strip())
+            for a in o.ask:
+                values.setdefault(a.name, a.default)
+            aj_env = []
+            seen = set()
+            for e in context_env:
+                item = dict(e)
+                if item["name"] in values:
+                    item["default"] = values[item["name"]]
+                    item.pop("placeholder", None)
+                seen.add(item["name"])
+                aj_env.append(item)
+            for k, v in values.items():
+                if k not in seen:
+                    # In .env for the director's own use (a volume device),
+                    # not something to hand the app's jail.
+                    aj_env.append({"name": k, "default": v, "env_only": True})
+            # What this option runs, in words: the services of its flattened
+            # compose with their images, the jails under director, and the
+            # host folders the data lands in. The page says this before any
+            # YAML.
+            parsed = (yaml.safe_load(ct) or {}).get("services") or {}
+            engine_services = {ENGINE["service"] for ENGINE in choices_mod.ENGINES.values() if ENGINE.get("service")}
+            parts, jails = [], []
+            for sname, svc in parsed.items():
+                img = str((svc or {}).get("image", ""))
+                short = img.split("/")[-1]
+                kind = "db" if sname in engine_services else "app"
+                parts.append({"name": sname, "image": short, "kind": kind})
+                jails.append({"name": sname.replace("-", "_") if kind == "app" else f"{cfg.image}_{sname}".replace("-", "_"), "image": short, "kind": kind})
+            if o.id == "external":
+                parts.append({"name": "your database", "image": "not run here", "kind": "none"})
+                jails.append({"name": "your database", "image": "not run here", "kind": "none"})
+            folders = []
+            for svc in parsed.values():
+                for v in (svc or {}).get("volumes") or []:
+                    src = v.split(":")[0] if isinstance(v, str) else str((v or {}).get("source", ""))
+                    if src.startswith("/") and src not in folders:
+                        folders.append(src)
+            for ln in o.env_lines:
+                k, _, v = ln.partition("=")
+                if k.endswith("_LOCATION") and v and v not in folders:
+                    folders.append(v)
+            folders = [f.replace("/containers", "@CONTAINER_CONFIG_ROOT@") for f in folders]
+            opts.append({
+                "id": o.id, "label": o.label, "doc": o.doc, "default": o.id == c.default,
+                "parts": parts, "jails": jails, "folders": folders,
+                "appjail": aj, "appjail_env": aj_env,
+                "jail_template_file": o.jail_template_file, "jail_template": o.jail_template,
+                "profile": o.profile, "env": o.env,
+                "ask": [{"name": a.name, "label": a.label, "default": a.default, "type": a.type, "values": a.values} for a in o.ask],
+                "compose_file": compose_file, "env_file": env_file,
+                "compose_text": ct, "example_env": et,
+                "compose_text_site": _site_placeholders(ct),
+                "example_env_site": _site_placeholders(et, env_file=True),
+                "zip": f"{cfg.image}-podman" + ("" if o.id == c.default else f"-{o.id}"),
+            })
+        out.append({"id": c.id, "label": c.label, "doc": c.doc, "default": c.default, "options": opts})
+    return out
+
+
 def _enrich_metadata(cfg: Config, community_override: str | None = None) -> dict[str, Any]:
     """Build a context dict for templates with enriched env/vol/port data from Config."""
     meta = cfg.metadata
@@ -416,6 +521,9 @@ def _enrich_metadata(cfg: Config, community_override: str | None = None) -> dict
         # what a one-service page gets from its generated snippet.
         "compose_text_site": _site_placeholders(cfg.compose_text),
         "example_env_site": _site_placeholders(cfg.example_env, env_file=True),
+        # What the compose offers (x-daemonless.choices): per option, the
+        # flattened compose and .env a reader copies. Empty for most images.
+        "choices": [],  # filled below, once env is known
         # The AppJail bundle carries the sidecar (x-daemonless.appjail.depends_on),
         # so its Director section runs the whole app, not the app alone.
         "appjail_sidecar": bool((getattr(meta, "appjail", None) or {}).get("depends_on")),
@@ -532,6 +640,7 @@ def _enrich_metadata(cfg: Config, community_override: str | None = None) -> dict
             "target": tgt
         })
 
+    context["choices"] = _choice_context(cfg, context["env"])
     return context
 
 
@@ -772,6 +881,18 @@ def render_generated(
                     f"README.j2 failed to render: included template '{e.name}' not found"
                 )
 
+    # Stack choices: the flattened compose + .env per non-default option, so
+    # whoever copies files instead of running fjord needs no flag.
+    if cfg.metadata.choices and cfg.compose_text:
+        try:
+            for c, o, compose_text, env_text in _choice_variants(cfg):
+                compose_file, env_file = choices_mod.variant_names(c, o)
+                head = f"# Generated by dbuild from compose.yaml: {c.label} = {o.label}. Edit compose.yaml, not this.\n"
+                outputs[compose_file] = head + compose_text
+                outputs[env_file] = head + env_text
+        except ValueError as e:
+            errors.append(f"choices: {e}")
+
     # Containerfiles — repo-only loader (local includes, no bundled fallback).
     for j2_path in sorted(base.glob("Containerfile*.j2")):
         out_name = j2_path.name.replace(".j2", "")
diff --git a/dbuild/lint.py b/dbuild/lint.py
index 165c01e..3d0e44d 100644
--- a/dbuild/lint.py
+++ b/dbuild/lint.py
@@ -10,6 +10,7 @@
 from pathlib import Path
 from typing import Any
 
+from dbuild import choices as choices_mod
 from dbuild.config import VALID_CATEGORIES, VALID_TYPES
 
 try:
@@ -102,6 +103,10 @@ def lint_repo(repo_path: Path, verbose: bool = False) -> tuple[list[str], list[s
                     f" Valid: {', '.join(VALID_CATEGORIES)}"
                 )
 
+            if verbose:
+                print("  checking choices")
+            errors.extend(choices_mod.validate(choices_mod.parse(meta, data), data))
+
             if verbose:
                 print("  checking type")
             image_type = meta.get("type", "")
diff --git a/dbuild/templates/README.j2 b/dbuild/templates/README.j2
index 8a3070c..163dee7 100644
--- a/dbuild/templates/README.j2
+++ b/dbuild/templates/README.j2
@@ -34,7 +34,7 @@
 {%- macro compose_snippet(override_port=None) -%}
 services:
   {{ name }}:
-    image: "{{ reg_var }}/{{ name }}:latest"
+    image: "{{ reg_var }}/{{ name }}:{{ default_tag }}"
     container_name: {{ name }}
 {%- if env %}
     environment:
@@ -82,25 +82,36 @@ services:
 {%- endif %}
 {%- endmacro %}
 
-{%- macro appjail_director_snippet(override_port=None) -%}
+{#- option: one of a choice's options (see dbuild.choices); its director
+    carries the service dbuild supplies and its .env the option's values. #}
+{%- macro appjail_director_snippet(override_port=None, option=None) -%}
+{%- set appjail = option.appjail if option else appjail %}
+{%- set env = option.appjail_env if option else env %}
+{%- set zip = name ~ "-appjail" ~ ("-" ~ option.id if option and not option.default else "") %}
 {%- if render_mode == "mkdocs" %}
-``` { data-zip-bundle="{{ name }}-appjail" data-zip-filename=".env" }
+``` { data-zip-bundle="{{ zip }}" data-zip-filename=".env" }
 {% include 'appjail.env.j2' %}
 ```
 
-```yaml { data-zip-bundle="{{ name }}-appjail" data-zip-filename="appjail-director.yaml" }
+```yaml { data-zip-bundle="{{ zip }}" data-zip-filename="appjail-director.yaml" }
 {% include 'appjail-director.yml.j2' %}
 ```
 
-``` { data-zip-bundle="{{ name }}-appjail" data-zip-filename="Makejail" }
+``` { data-zip-bundle="{{ zip }}" data-zip-filename="Makejail" }
 {% include 'Makejail.j2' %}
 ```
 {%- if jail_allow -%}
 {{ '\n' }}
-``` { data-zip-bundle="{{ name }}-appjail" data-zip-filename="template.conf" }
+``` { data-zip-bundle="{{ zip }}" data-zip-filename="template.conf" }
 {% include 'appjail-template.conf.j2' %}
 ```
 {%- endif %}
+{%- if option and option.jail_template_file -%}
+{{ '\n' }}
+``` { data-zip-bundle="{{ zip }}" data-zip-filename="{{ option.jail_template_file }}" }
+{{ option.jail_template | trim }}
+```
+{%- endif %}
 {%- else -%}
 **.env**:
 
@@ -127,6 +138,14 @@ services:
 {% include 'appjail-template.conf.j2' %}
 ```
 {%- endif %}
+{%- if option and option.jail_template_file -%}
+{{ '\n' }}
+**{{ option.jail_template_file }}**:
+
+```
+{{ option.jail_template | trim }}
+```
+{%- endif %}
 {%- endif %}
 {%- endmacro %}
 
@@ -155,85 +174,16 @@ podman run -d --name {{ name }} \
 {%- for v in volumes %}
   -v {{ vol_src(v) }}:{{ vol_tgt(v) }}{{ " # optional" if v.optional else "" }} \
 {%- endfor %}
-  {{ reg_var }}/{{ name }}:latest
+  {{ reg_var }}/{{ name }}:{{ default_tag }}
 {%- endmacro %}
 
-{%- macro appjail_snippet(override_port=None) -%}
-{%- if render_mode == "mkdocs" %}
-```bash { data-zip-bundle="{{ name }}-appjail-cli" data-zip-filename="run.sh" }
-{%- else %}
-```bash
-{%- endif %}
-{%- if image_class == "service" -%}
-{{ '\n' }}appjail oci run -Pd \
-{%- else %}
-{{ '\n' }}appjail oci run \
-  -o ephemeral \
-{%- endif %}
-  -o overwrite=force \
-  -o container="args:--pull" \
-{%- if appjail and appjail.cli and appjail.cli.options %}
-{%- for opt in appjail.cli.options %}
-  -o {{ opt }} \
-{%- endfor %}
-{%- else %}
-  -o virtualnet=":<random> default" \
-  -o nat \
-{%- endif %}
-{%- if jail_allow -%}
-{{ '\n' }}  -o template=template.conf \
-{%- endif %}
-{%- for p in ports %}
-{%- if loop.first %}
-  -o expose="{{ override_port if override_port else port_var }}:{{ p.target }} proto:{{ p.protocol }}" \
-{%- else %}
-  -o expose="{{ p.port }}:{{ p.target }} proto:{{ p.protocol }}" \
-{%- endif %}
-{%- endfor %}
-{%- for e in env %}
-  -e {{ e.name }}={{ e.placeholder if (render_mode == "mkdocs" and e.placeholder) else e.default }} \
-{%- endfor %}
-{%- for v in volumes %}
-  -o fstab="{{ vol_src(v) }} {{ v.path }} <pseudofs>" \{{ " # optional" if v.optional else "" }}
-{%- endfor %}
-  {{ reg_var }}/{{ name }}:latest {{ name }}
-```
-{%- if jail_allow -%}
-{{ '\n' }}
-**template.conf**:
-
-{%- if render_mode == "mkdocs" %}
-``` { data-zip-bundle="{{ name }}-appjail-cli" data-zip-filename="template.conf" }
-{%- else %}
-```
-{%- endif %}
-{% include 'appjail-template.conf.j2' %}
-```
-{%- endif %}
-{%- endmacro %}
 
-{#- Bastille OCI (experimental). Bastille shares the host network stack
-    (`inherit`). Volumes mount via `--volume HOST JAIL`; without the flag,
-    image-declared VOLUMEs land under ${bastille_volumesdir}/${jail}.
-    `bastille up` reads bastille-compose.yml with its own schema
-    (name/image/network/ports/environment/volumes/depend), so we hand-shape
-    the file rather than reuse compose_snippet. -#}
-{%- macro bastille_snippet(override_port=None) -%}
-bastille create -O \
-{%- for e in env %}
-  --env {{ e.name }}={{ e.placeholder if (render_mode == "mkdocs" and e.placeholder) else e.default }} \
-{%- endfor %}
-{%- for v in volumes %}
-  --volume {{ vol_src(v) }} {{ v.path }} \
-{%- endfor %}
-  {{ name }} {{ reg_var }}/{{ name }}:latest inherit
-{%- endmacro %}
 
 {%- macro bastille_compose_snippet(override_port=None) -%}
 services:
   {{ name }}:
     name: {{ name }}
-    image: "{{ reg_var }}/{{ name }}:latest"
+    image: "{{ reg_var }}/{{ name }}:{{ default_tag }}"
     network:
       - mode: host
 {%- if env %}
@@ -250,43 +200,6 @@ services:
 {%- endif %}
 {%- endmacro %}
 
-{%- macro ansible_snippet(override_port=None) -%}
-- name: Deploy {{ name }}
-  containers.podman.podman_container:
-    name: {{ name }}
-    image: "{{ reg_var }}/{{ name }}:latest"
-    state: started
-    restart_policy: always
-{%- if env %}
-    env:
-{%- for e in env %}
-      {{ e.name }}: "{{ e.placeholder if (render_mode == "mkdocs" and e.placeholder) else e.default }}"
-{%- endfor %}
-{%- endif %}
-{%- if ports %}
-    ports:
-{%- for p in ports %}
-{%- if loop.first %}
-      - "{{ override_port if override_port else port_var }}:{{ p.target }}"
-{%- else %}
-      - "{{ p.port }}:{{ p.target }}"
-{%- endif %}
-{%- endfor %}
-{%- endif %}
-{%- if volumes %}
-    volumes:
-{%- for v in volumes %}
-      - "{{ vol_src(v) }}:{{ vol_tgt(v) }}"{{ " # optional" if v.optional else "" }}
-{%- endfor %}
-{%- endif %}
-{%- if annotations %}
-    annotation:
-{%- for a in annotations %}
-{%- set kv = a.split("=", 1) %}
-      {{ kv[0] }}: "{{ kv[1] }}"
-{%- endfor %}
-{%- endif %}
-{%- endmacro -%}
 
 {#- Version-tags table, with an optional arch suffix appended to every tag
     (e.g. suffix="-aarch64" -> `15.1-aarch64`). Bare (amd64) uses suffix="". -#}
@@ -447,7 +360,34 @@ Before deploying, ensure your host environment is ready. See the [Quick Start Gu
 
 ### Podman Compose
 
-{%- if compose_text %}
+{%- if compose_text and choices %}
+{%- for c in choices %}
+
+**{{ c.label }}.** {{ c.doc }}
+{%- for o in c.options %}
+
+#### {{ o.label }}{% if o.default %} (default){% endif %}
+{%- if o.doc %}
+
+{{ o.doc }}
+{%- endif %}
+
+**1.** Save as `.env`{% if o.ask %} and fill in {{ o.ask | map(attribute='label') | join(', ') }}{% else %} and fill in what is empty{% endif %}:
+
+```env { data-zip-bundle="{{ o.zip }}" data-zip-filename=".env" }
+{{ o.example_env | trim }}
+```
+
+**2.** Save as `compose.yaml`:
+
+```yaml { data-zip-bundle="{{ o.zip }}" data-zip-filename="compose.yaml" }
+{{ o.compose_text | trim }}
+```
+
+Then run `podman-compose up -d`.
+{%- endfor %}
+{%- endfor %}
+{%- elif compose_text %}
 {%- if example_env %}
 
 **1.** Save as `.env` and fill in what is empty:
@@ -488,7 +428,20 @@ Then run `podman-compose up -d`.
 Save as `compose.yaml`, then run `podman-compose up -d`.
 {%- endif %}
 {%- endif %}
-{%- if appjail_enabled and (not compose_text or appjail_sidecar) %}
+{%- if appjail_enabled and choices %}
+
+### AppJail Director
+{%- for c in choices %}
+{%- for o in c.options %}
+
+#### {{ o.label }}{% if o.default %} (default){% endif %}
+
+{{ appjail_director_snippet(option=o) }}
+
+Save the files above, then run `appjail-director up`.
+{%- endfor %}
+{%- endfor %}
+{%- elif appjail_enabled and (not compose_text or appjail_sidecar) %}
 
 ### AppJail Director
 
@@ -504,11 +457,17 @@ Save the files above, then run `appjail-director up`.
 {%- endif %}
 {%- endif %}
 
-{#- One-container recipes cannot start a sidecar: a compose with several
-    services (an app and its database) is deployed with compose only. #}
-{%- if image_class in ["service", "cli"] and not compose_text %}
+{#- One way per runtime. Compose for a service (it is also what fjord
+    deploys), the one-liner only for a tool that runs and exits. Bastille's
+    OCI support is experimental and single-container, so it stays off a
+    compose that carries a sidecar. #}
+{%- if image_class == "cli" %}
 
 ### Podman CLI
+{%- if docs is mapping and docs.usage %}
+
+{{ docs.usage | trim }}
+{%- else %}
 
 ```bash
 {{ cli_snippet() }}
@@ -516,18 +475,8 @@ Save the files above, then run `appjail-director up`.
 
 Save as `run.sh`, then run `sh run.sh`.
 {%- endif %}
-{%- if image_class == "service" and not compose_text %}
-{%- if appjail_enabled %}
-
-### AppJail
-
-{{ appjail_snippet() }}
-
-Save the files above, then run `sh run.sh`.
-
-{{ appjail_note_expose_ports() }}
 {%- endif %}
-{%- if bastille_enabled %}
+{%- if image_class == "service" and not compose_text and bastille_enabled %}
 
 ### Bastille
 
@@ -538,20 +487,7 @@ Save the files above, then run `sh run.sh`.
 {{ bastille_compose_snippet() }}
 ```
 
-Save as `bastille-compose.yml`, then run `bastille up`. Or via CLI:
-
-```bash
-{{ bastille_snippet() }}
-```
-{%- endif %}
-
-### Ansible
-
-```yaml
-{{ ansible_snippet() }}
-```
-
-Save as `{{ name }}-deploy.yaml`, then run `ansible-playbook {{ name }}-deploy.yaml`.
+Save as `bastille-compose.yml`, then run `bastille up`.
 {%- endif %}
 {%- endblock %}
 
diff --git a/dbuild/templates/README.mkdocs.j2 b/dbuild/templates/README.mkdocs.j2
index 09d2f51..8b49fce 100644
--- a/dbuild/templates/README.mkdocs.j2
+++ b/dbuild/templates/README.mkdocs.j2
@@ -1,5 +1,15 @@
 {% extends "README.j2" %}
 
+{#- What an option runs, before any YAML: one chip per container or jail,
+    then the count and the host folders. Markdown, not a raw HTML block: a
+    block inside a tab gets paragraph-wrapped and magiclink turns a
+    placeholder's @ into a GitHub mention; a code span keeps it as text. #}
+{%- macro you_get(o, parts, unit) -%}
+{%- set running = parts | rejectattr("kind", "equalto", "none") | list -%}
+**You get**{% for p in parts %} <span class="part part-{{ p.kind }}"><i></i>{{ p.name }} <code>{{ p.image }}</code></span>{% endfor %} <span class="sum">{{ running | length }} {{ unit }}{{ "" if running | length == 1 else "s" }}{% if o.folders %}, data in {% for f in o.folders %}`{{ f }}`{{ ", " if not loop.last }}{% endfor %}{% endif %}</span>
+{: .you-get }
+{%- endmacro %}
+
 {% block frontmatter -%}
 ---
 title: "Run {{ title }} on FreeBSD — Native OCI Container"
@@ -86,9 +96,36 @@ Before deploying, ensure your host environment is ready. See the [Quick Start Gu
 {%- if compose_text %}
 {#- An app shipped with its database: the real compose and the .env it reads.
     The one-service snippet dropped the database; the one-container recipes
-    (CLI, Ansible, Bastille) would start the app without it. #}
-=== ":material-docker: Podman"
-{% if example_env %}
+    (Bastille) would start the app without it. #}
+=== ":podman-podman: Podman"
+{% if choices %}
+{% for c in choices %}
+    **{{ c.label }}** {{ c.doc }}
+    {: .deploy-choice }
+{% for o in c.options %}
+    === "{{ o.label }}"
+
+        {{ you_get(o, o.parts, "container") | indent(8) }}
+
+{% if o.doc %}
+        {{ o.doc }}
+{% endif %}
+        **1.** Save as `.env`{% if o.ask %} and fill in {{ o.ask | map(attribute='label') | join(', ') }}{% else %} and fill in what is empty{% endif %}:
+
+        ```env { data-zip-bundle="{{ o.zip }}" data-zip-filename=".env" }
+        {{ o.example_env_site | trim | indent(8) }}
+        ```
+
+        **2.** Save as `compose.yaml`:
+
+        ```yaml { data-zip-bundle="{{ o.zip }}" data-zip-filename="compose.yaml" }
+        {{ o.compose_text_site | trim | indent(8) }}
+        ```
+
+        Then run `podman-compose up -d`.
+{% endfor %}
+{% endfor %}
+{% elif example_env %}
     **1.** Save as `.env` and fill in what is empty:
 
     ```env { data-zip-bundle="{{ name }}-podman" data-zip-filename=".env" }
@@ -97,132 +134,111 @@ Before deploying, ensure your host environment is ready. See the [Quick Start Gu
 
     **2.** Save as `compose.yaml`:
 {% endif %}
+{% if not choices %}
     ```yaml { data-zip-bundle="{{ name }}-podman" data-zip-filename="compose.yaml" }
     {{ compose_text_site | trim | indent(4) }}
     ```
 
     Then run `podman-compose up -d`.
-{% if appjail_enabled and appjail_sidecar %}
+{% endif %}
+{% if appjail_enabled and choices %}
 === ":appjail-appjail: AppJail"
+{% for c in choices %}
+    **{{ c.label }}** {{ c.doc }}
+    {: .deploy-choice }
+{% for o in c.options %}
+    === "{{ o.label }}"
 
-    === ":material-file-document-outline: Director"
+        {{ you_get(o, o.jails, "jail") | indent(8) }}
 
-        {{ appjail_director_snippet(port_var) | indent(8) }}
-
-        Save the files above, then run `appjail-director up`.
+{% if o.doc %}
+        {{ o.doc }}
 {% endif %}
-{%- elif appjail_enabled or bastille_tab %}
-{#- More than one runtime: nest formats under a per-runtime outer tab. #}
-=== ":material-docker: Podman"
+        {{ appjail_director_snippet(port_var, o) | indent(8) }}
 
-{% if image_class == "service" %}
-    === ":material-file-document-outline: Compose"
+        Save the files above, then run `appjail-director up`.
+{% endfor %}
+{% endfor %}
+{% elif appjail_enabled and appjail_sidecar %}
+=== ":appjail-appjail: AppJail"
 
-        ```yaml { data-zip-bundle="{{ name }}-podman" data-zip-filename="compose.yaml" }
-        {{ compose_snippet(port_var) | indent(8) }}
-        ```
+    === ":material-file-document-outline: Director"
 
-        Save as `compose.yaml`, then run `podman-compose up -d`.
+        {{ appjail_director_snippet(port_var) | indent(8) }}
 
+        Save the files above, then run `appjail-director up`.
 {% endif %}
-    === ":material-console: CLI"
-
-        ```bash { data-zip-bundle="{{ name }}-podman-cli" data-zip-filename="run.sh" }
-        {{ cli_snippet(port_var) | indent(8) }}
-        ```
-
-        Save as `run.sh`, then run `sh run.sh`.
+{%- elif appjail_enabled or bastille_tab %}
+{#- One tab per runtime, one way each. #}
+=== ":podman-podman: Podman"
 {% if image_class == "service" %}
+    ```yaml { data-zip-bundle="{{ name }}-podman" data-zip-filename="compose.yaml" }
+    {{ compose_snippet(port_var) | indent(4) }}
+    ```
 
-    === ":simple-ansible: Ansible"
-
-        ```yaml { data-zip-bundle="{{ name }}-ansible" data-zip-filename="{{ name }}-deploy.yaml" }
-        {{ ansible_snippet(port_var) | indent(8) }}
-        ```
+    Save as `compose.yaml`, then run `podman-compose up -d`.
+{% elif docs is mapping and docs.usage %}
+    {{ docs.usage | trim | indent(4) }}
+{% else %}
+    ```bash { data-zip-bundle="{{ name }}-podman-cli" data-zip-filename="run.sh" }
+    {{ cli_snippet(port_var) | indent(4) }}
+    ```
 
-        Save as `{{ name }}-deploy.yaml`, then run `ansible-playbook {{ name }}-deploy.yaml`.
+    Save as `run.sh`, then run `sh run.sh`.
 {% endif %}
-
-{% if appjail_enabled %}
+{% if appjail_enabled and image_class == "service" %}
 === ":appjail-appjail: AppJail"
 {% if ports %}
     !!! warning
         Exposing ports in AppJail means that your service can be reached from remote hosts. If that is not your intention, do not expose the ports and communicate with the service using the jail's IPv4 address or hostname assigned by the virtual network.
 {% endif %}
+    {{ appjail_director_snippet(port_var) | indent(4) }}
 
-{% if image_class == "service" %}
-    === ":material-file-document-outline: Director"
-
-        {{ appjail_director_snippet(port_var) | indent(8) }}
-
-        Save the files above, then run `appjail-director up`.
-
-{% endif %}
-    === ":material-console: CLI"
-
-        {{ appjail_snippet(port_var) | indent(8) }}
-
-        Save the files above, then run `sh run.sh`.
+    Save the files above, then run `appjail-director up`.
 {% endif %}
 {% if bastille_tab %}
 === ":bastille-bastille: Bastille"
 
     !!! warning "Experimental"
         Bastille's OCI support is experimental. It requires `buildah` and shares the host network stack (`inherit`). Mount volumes with `--volume HOST JAIL`; without it, image-declared volumes are stored under `${bastille_volumesdir}/${jail}`.
+{% if choices %}
+    Bastille runs one jail on the host's network stack, so it cannot add a database of its own: this is the default setup ({% for c in choices %}{{ c.label }} = {% for o in c.options if o.default %}{{ o.label }}{% endfor %}{{ ", " if not loop.last }}{% endfor %}). For another, point the app at a database you already run.
+{% endif %}
+    ```yaml { data-zip-bundle="{{ name }}-bastille" data-zip-filename="bastille-compose.yml" }
+    {{ bastille_compose_snippet(port_var) | indent(4) }}
+    ```
 
-    === ":material-file-document-outline: Compose"
-
-        ```yaml { data-zip-bundle="{{ name }}-bastille" data-zip-filename="bastille-compose.yml" }
-        {{ bastille_compose_snippet(port_var) | indent(8) }}
-        ```
-
-        Save as `bastille-compose.yml`, then run `bastille up`.
-
-    === ":material-console: CLI"
-
-        ```bash { data-zip-bundle="{{ name }}-bastille-cli" data-zip-filename="run.sh" }
-        {{ bastille_snippet(port_var) | indent(8) }}
-        ```
+    Save as `bastille-compose.yml`, then run `bastille up`.
 {% endif %}
 {%- else %}
-{#- Podman-only: keep formats flat, no redundant outer runtime tab. #}
+{#- Podman only: nothing to pick, so no tabs. #}
 {% if image_class == "service" %}
-=== ":material-docker: Compose"
-
-    ```yaml { data-zip-bundle="{{ name }}-podman" data-zip-filename="compose.yaml" }
-    {{ compose_snippet(port_var) | indent(4) }}
-    ```
-
-    Save as `compose.yaml`, then run `podman-compose up -d`.
-
+```yaml { data-zip-bundle="{{ name }}-podman" data-zip-filename="compose.yaml" }
+{{ compose_snippet(port_var) }}
+```
+
+Save as `compose.yaml`, then run `podman-compose up -d`.
+{% elif docs is mapping and docs.usage %}
+{{ docs.usage | trim }}
+{% else %}
+```bash { data-zip-bundle="{{ name }}-podman-cli" data-zip-filename="run.sh" }
+{{ cli_snippet(port_var) }}
+```
+
+Save as `run.sh`, then run `sh run.sh`.
 {% endif %}
-=== ":material-console: Podman CLI"
-
-    ```bash { data-zip-bundle="{{ name }}-podman-cli" data-zip-filename="run.sh" }
-    {{ cli_snippet(port_var) | indent(4) }}
-    ```
-
-    Save as `run.sh`, then run `sh run.sh`.
-{%- if image_class == "service" %}
-
-=== ":simple-ansible: Ansible"
-
-    ```yaml { data-zip-bundle="{{ name }}-ansible" data-zip-filename="{{ name }}-deploy.yaml" }
-    {{ ansible_snippet(port_var) | indent(4) }}
-    ```
-
-    Save as `{{ name }}-deploy.yaml`, then run `ansible-playbook {{ name }}-deploy.yaml`.
-{%- endif %}
 {%- endif %}
 {% endblock %}
 
 {% block interactive_config %}
-{%- if image_class == "service" %}
+{#- The settings table lands under this heading (ux-settings-v2.js moves it
+    here); without the heading it stays wherever the plugin drops it. Every
+    page has at least the registry placeholder, a base image included, so
+    every page gets the heading; an empty table hides itself. #}
 
 ### Interactive Configuration
 
 <div class="placeholder-settings-panel"></div>
-{%- endif %}
 {% endblock %}
 
 {% block implementation_details %}
diff --git a/dbuild/templates/appjail-director.yml.j2 b/dbuild/templates/appjail-director.yml.j2
index 46e626c..78eef25 100644
--- a/dbuild/templates/appjail-director.yml.j2
+++ b/dbuild/templates/appjail-director.yml.j2
@@ -48,7 +48,7 @@ services:
     oci:
       user: root
       environment:
-{%- for e in env %}
+{%- for e in env if not e.env_only %}
         - {{ e.name }}: !ENV '${{ '{' }}{{ e.name }}{{ '}' }}'
 {%- endfor %}
 {%- endif %}
@@ -64,6 +64,9 @@ services:
 {%- for dep in appjail.depends_on %}
   {{ dep.name }}:
     name: {{ dep.name | replace("-", "_") }}
+{%- if dep.priority %}
+    priority: {{ dep.priority }}
+{%- endif %}
     options:
       - from: {{ dep.image }}
 {#- A sidecar needs a jail template too (host networking, jail params); its
diff --git a/docs/dbuild.1 b/docs/dbuild.1
index 90072ea..08867bb 100644
--- a/docs/dbuild.1
+++ b/docs/dbuild.1
@@ -1,4 +1,4 @@
-.TH DBUILD 1 "2026-09-29" "dbuild 1.9.17" "User Commands"
+.TH DBUILD 1 "2026-10-01" "dbuild 1.10.0" "User Commands"
 .SH NAME
 dbuild \- FreeBSD OCI container image build tool
 .SH SYNOPSIS
diff --git a/tests/test_docs.py b/tests/test_docs.py
index c985989..41418e0 100644
--- a/tests/test_docs.py
+++ b/tests/test_docs.py
@@ -183,9 +183,26 @@ def test_cli_image_renders_podman_cli_usage(self):
                 self.assertEqual(docs.run(cfg, args), 0)
 
             readme = (repo / "README.md").read_text()
+            # A tool that runs and exits keeps the one-liner; nothing else.
             self.assertIn("### Podman CLI", readme)
             self.assertIn("podman run --rm", readme)
             self.assertIn("ghcr.io/daemonless/", readme)
+            for gone in ("### Podman Compose", "### Ansible", "### AppJail", "ansible-playbook"):
+                self.assertNotIn(gone, readme)
+
+    def test_service_image_gets_one_way_per_runtime(self):
+        with tempfile.TemporaryDirectory() as d:
+            repo = Path(d)
+            (repo / "Containerfile.j2").write_text(CONTAINERFILE_J2)
+            (repo / "compose.yaml").write_text(COMPOSE_YAML.format(name="svc").replace("  docs: manual\n", ""))
+            with _chdir(repo):
+                cfg = dbuild_config.load(repo)
+                self.assertEqual(docs.run(cfg, argparse.Namespace(community=None)), 0)
+            readme = (repo / "README.md").read_text()
+            self.assertIn("### Podman Compose", readme)
+            self.assertIn("podman-compose up -d", readme)
+            for gone in ("### Podman CLI", "### Ansible", "podman run --rm", "ansible-playbook", "### AppJail\n"):
+                self.assertNotIn(gone, readme)
 
 
 class TestReadmeWithSidecar(unittest.TestCase):
@@ -305,3 +322,171 @@ def test_repo_compose_and_env_get_site_placeholders(self):
         assert _site_placeholders(env, env_file=True) == (
             "CONFIG_LOCATION=@CONTAINER_CONFIG_ROOT@/app\nTZ=@TZ@\n")
         assert _site_placeholders("") == ""
+
+
+# ── Stack choices ──────────────────────────────────────────────────────
+
+CHOICES_COMPOSE = """\
+name: todo
+x-daemonless:
+  title: "Todo"
+  description: "A to-do app."
+  category: "Utilities"
+  icon: ":test:"
+  upstream_url: "https://example.com"
+  user: "bsd"
+  choices:
+    database:
+      kind: database
+      offers: [sqlite, postgres, mariadb, external]
+      default: sqlite
+      env:
+        type: TODO_DB_TYPE
+        host: TODO_DB_HOST
+        user: TODO_DB_USER
+        password: TODO_DB_PASSWORD
+        name: TODO_DB_NAME
+      types: { mariadb: mysql }
+    search:
+      label: Search
+      default: "off"
+      options:
+        "off": { label: Off }
+        "on":  { label: On, profile: search, env: { TODO_SEARCH: "true" } }
+services:
+  todo:
+    image: ghcr.io/daemonless/todo:latest
+    environment:
+      - PUID=1000
+      - TODO_DB_TYPE=${TODO_DB_TYPE:-sqlite}
+      - TODO_DB_HOST=${TODO_DB_HOST:-}
+      - TODO_DB_USER=${TODO_DB_USER:-}
+      - TODO_DB_PASSWORD=${TODO_DB_PASSWORD:-}
+      - TODO_DB_NAME=${TODO_DB_NAME:-}
+      - TODO_SEARCH=${TODO_SEARCH:-false}
+    ports:
+      - "3456:3456"
+  meili:
+    # search, only when asked for
+    image: ghcr.io/daemonless/meilisearch:latest
+    profiles: [search]
+"""
+
+CHOICES_ENV = "TZ=UTC\nTODO_DB_TYPE=sqlite\n"
+
+
+class TestStackChoices(unittest.TestCase):
+    def _render(self, tmp: Path):
+        (tmp / "compose.yaml").write_text(CHOICES_COMPOSE)
+        (tmp / "example.env").write_text(CHOICES_ENV)
+        (tmp / "Containerfile.j2").write_text(CONTAINERFILE_J2)
+        with _chdir(tmp):
+            cfg = dbuild_config.load(tmp)
+            outputs, errors = docs.render_generated(cfg, argparse.Namespace(community=None), tmp)
+        return outputs, errors
+
+    def test_database_services_come_from_dbuild(self):
+        with tempfile.TemporaryDirectory() as d:
+            outputs, errors = self._render(Path(d))
+        self.assertEqual(errors, [])
+        pg = outputs["compose.database-postgres.yaml"]
+        self.assertIn("  postgres:\n    image: ghcr.io/daemonless/postgres:17", pg)
+        self.assertIn("POSTGRES_PASSWORD=${TODO_DB_PASSWORD}", pg, "the supplied service reads the app's own variables")
+        self.assertIn('"${DATABASE_LOCATION}:/var/lib/postgresql/data"', pg)
+        self.assertIn("  todo:\n    depends_on: [postgres]", pg, "the app waits for the database")
+        self.assertNotIn("meili", pg, "another choice's profiled service stays out")
+        self.assertNotIn("profiles", pg)
+        mdb = outputs["compose.database-mariadb.yaml"]
+        self.assertIn("MYSQL_ROOT_PASSWORD=${TODO_DB_PASSWORD}", mdb)
+        self.assertNotIn("compose.database-sqlite.yaml", outputs, "the default is the compose as it stands")
+        ext = outputs["compose.database-external.yaml"]
+        self.assertNotIn("postgres:", ext.split("services:")[1])
+
+    def test_env_applied_in_the_apps_words(self):
+        with tempfile.TemporaryDirectory() as d:
+            outputs, _ = self._render(Path(d))
+        pg = outputs["example.database-postgres.env"]
+        self.assertIn("TODO_DB_TYPE=postgres", pg)
+        self.assertNotIn("TODO_DB_TYPE=sqlite", pg, "a key already there is replaced, not doubled")
+        self.assertIn("TODO_DB_HOST=postgres", pg)
+        self.assertIn("TODO_DB_PASSWORD=  # set one", pg)
+        self.assertIn("DATABASE_LOCATION=/containers/todo/postgres", pg)
+        self.assertIn("TODO_DB_TYPE=mysql", outputs["example.database-mariadb.env"], "types: maps the engine to the app's word")
+        ext = outputs["example.database-external.env"]
+        self.assertIn("TODO_DB_TYPE=  # Kind: postgres | mysql", ext)
+        self.assertIn("TODO_DB_PASSWORD=  # Password", ext)
+
+    def test_you_get_names_what_runs_and_where_data_lands(self):
+        with tempfile.TemporaryDirectory() as d:
+            t = Path(d)
+            (t / "compose.yaml").write_text(CHOICES_COMPOSE)
+            (t / "example.env").write_text(CHOICES_ENV)
+            (t / "Containerfile.j2").write_text(CONTAINERFILE_J2)
+            with _chdir(t):
+                ctx = docs._enrich_metadata(dbuild_config.load(t), None)
+        db = next(c for c in ctx["choices"] if c["id"] == "database")
+        pg = next(o for o in db["options"] if o["id"] == "postgres")
+        self.assertEqual([(p["name"], p["kind"]) for p in pg["parts"]], [("todo", "app"), ("postgres", "db")])
+        self.assertEqual(pg["parts"][1]["image"], "postgres:17")
+        self.assertTrue(pg["jails"][1]["name"].endswith("_postgres"), pg["jails"])  # <image>_postgres
+        self.assertIn("@CONTAINER_CONFIG_ROOT@/todo/postgres", pg["folders"])
+        ext = next(o for o in db["options"] if o["id"] == "external")
+        self.assertEqual(ext["parts"][-1]["kind"], "none")
+
+    def test_a_part_choice_switches_a_profile(self):
+        with tempfile.TemporaryDirectory() as d:
+            outputs, _ = self._render(Path(d))
+        on = outputs["compose.search-on.yaml"]
+        self.assertIn("  meili:", on)
+        self.assertIn("# search, only when asked for", on, "comments survive flattening")
+        self.assertNotIn("profiles", on)
+        self.assertIn("TODO_SEARCH=true", outputs["example.search-on.env"])
+
+    def test_readme_has_a_section_per_option_default_first(self):
+        with tempfile.TemporaryDirectory() as d:
+            outputs, _ = self._render(Path(d))
+        readme = outputs["README.md"]
+        i_sql, i_pg, i_ext = (readme.index(h) for h in ("#### SQLite (default)", "#### PostgreSQL", "#### Your own"))
+        self.assertTrue(i_sql < i_pg < i_ext)
+        self.assertIn("fill in Kind, Host, User, Password, Database", readme)
+
+    def test_lint_catches_the_wiring_mistakes(self):
+        import yaml as _yaml
+
+        from dbuild import choices as choices_mod
+        data = _yaml.safe_load(CHOICES_COMPOSE)
+        ch = data["x-daemonless"]["choices"]
+        ch["database"]["default"] = "postgres"
+        ch["database"]["offers"].append("oracle")
+        ch["database"]["env"]["port"] = "TODO_DB_PORT"      # not in the app's environment
+        ch["search"]["options"]["on"]["profile"] = "nothing"
+        errs = choices_mod.validate(choices_mod.parse(data["x-daemonless"], data), data)
+        self.assertTrue(any("switches a service on" in e for e in errs), errs)
+        self.assertTrue(any("offers 'oracle'" in e for e in errs), errs)
+        self.assertTrue(any("TODO_DB_PORT is not in todo's environment" in e for e in errs), errs)
+        self.assertTrue(any("no service carries profiles: [nothing]" in e for e in errs), errs)
+
+    def test_director_per_option_from_the_same_engine_table(self):
+        with tempfile.TemporaryDirectory() as d:
+            # appjail on, so the README carries a Director per option
+            (Path(d) / ".daemonless").mkdir()
+            compose = CHOICES_COMPOSE.replace('  user: "bsd"\n', '  user: "bsd"\n  appjail: {}\n')
+            (Path(d) / "compose.yaml").write_text(compose)
+            (Path(d) / "example.env").write_text(CHOICES_ENV)
+            (Path(d) / "Containerfile.j2").write_text(CONTAINERFILE_J2)
+            with _chdir(Path(d)):
+                cfg = dbuild_config.load(Path(d))
+                outputs, errors = docs.render_generated(cfg, argparse.Namespace(community=None), Path(d))
+        self.assertEqual(errors, [])
+        readme = outputs["README.md"]
+        aj = readme[readme.index("### AppJail Director"):]
+        pg = aj[aj.index("#### PostgreSQL"):aj.index("#### MariaDB")]
+        self.assertIn("  todo-postgres:\n    name: todo_postgres\n    priority: 10", pg, "the engine's jail starts first")
+        self.assertIn("POSTGRES_PASSWORD: !ENV '${TODO_DB_PASSWORD}'", pg, "reads the app's own variables")
+        self.assertIn("TODO_DB_HOST=todo_postgres", pg, "the host is the jail's name")
+        self.assertIn("template: !ENV '${PWD}/postgres-template.conf'", pg)
+        self.assertIn("sysvshm: new", pg, "the jail template PostgreSQL needs ships with it")
+        self.assertIn("device: !ENV '${DATABASE_LOCATION}'", pg)
+        self.assertNotIn("- DATABASE_LOCATION: !ENV", pg, "a device variable is not handed to the app's jail")
+        sq = aj[aj.index("#### SQLite (default)"):aj.index("#### PostgreSQL")]
+        self.assertNotIn("postgres", sq)

From ede57b1142f663f535ac70ac501d89064737f014 Mon Sep 17 00:00:00 2001
From: Michael Johnson <buhnux@gmail.com>
Date: Thu, 1 Oct 2026 18:14:02 -0400
Subject: [PATCH 2/2] choices: import yaml lazily, the wheel build imports the
 package without it

---
 dbuild/choices.py | 6 +++++-
 dbuild/docs.py    | 4 ++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/dbuild/choices.py b/dbuild/choices.py
index 52aba7f..b040331 100644
--- a/dbuild/choices.py
+++ b/dbuild/choices.py
@@ -53,7 +53,11 @@
 from dataclasses import dataclass, field
 from typing import Any
 
-import yaml
+# Lazy: the wheel build imports the package without yaml installed.
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    yaml = None  # type: ignore[assignment]
 
 # The database engines dbuild knows how to run. One place: an app that
 # offers postgres gets this service, and a fix here fixes every app.
diff --git a/dbuild/docs.py b/dbuild/docs.py
index 6bf566c..1c828c2 100644
--- a/dbuild/docs.py
+++ b/dbuild/docs.py
@@ -19,8 +19,6 @@
 
 import dataclasses
 
-import yaml
-
 import dbuild
 from dbuild import choices as choices_mod
 from dbuild import log
@@ -379,6 +377,8 @@ def _choice_context(cfg: Config, context_env: list[dict[str, Any]]) -> list[dict
             # compose with their images, the jails under director, and the
             # host folders the data lands in. The page says this before any
             # YAML.
+            import yaml  # lazy, as everywhere in this module: the wheel build imports it without yaml
+
             parsed = (yaml.safe_load(ct) or {}).get("services") or {}
             engine_services = {ENGINE["service"] for ENGINE in choices_mod.ENGINES.values() if ENGINE.get("service")}
             parts, jails = [], []