From c0b01133e36063fdd69f5057500416dc9ed4d19b Mon Sep 17 00:00:00 2001
From: Michael Johnson <buhnux@gmail.com>
Date: Fri, 2 Oct 2026 06:49:13 -0400
Subject: [PATCH 1/2] generate: choices combine into one form

---
 dbuild/choices.py                 |  78 ++++++-
 dbuild/docs.py                    | 334 +++++++++++++++++++++---------
 dbuild/templates/README.j2        |  87 ++++++--
 dbuild/templates/README.mkdocs.j2 | 102 +++++----
 tests/test_docs.py                | 225 +++++++++++++++++++-
 5 files changed, 654 insertions(+), 172 deletions(-)

diff --git a/dbuild/choices.py b/dbuild/choices.py
index b040331..a6b7165 100644
--- a/dbuild/choices.py
+++ b/dbuild/choices.py
@@ -110,6 +110,9 @@ class Option:
     profile: str = ""
     env: dict[str, str] = field(default_factory=dict)
     ask: list[Ask] = field(default_factory=list)
+    # Services this option leaves out (a part the default runs and this
+    # option does without: immich without machine learning).
+    drop: list[str] = 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 = ""
@@ -242,6 +245,7 @@ def parse(meta: dict[str, Any], compose_data: dict[str, Any] | None = None) -> l
                     profile=str(o.get("profile", "")),
                     env={str(k): str(v) for k, v in (o.get("env") or {}).items()},
                     ask=asks,
+                    drop=[str(x) for x in (o.get("drop") or [])],
                 ))
         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,
@@ -287,6 +291,11 @@ def validate(choices: list[Choice], compose_data: dict[str, Any]) -> list[str]:
         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 d in o.drop:
+                if d not in services:
+                    errors.append(f"{where}.options.{o.id}: drops '{d}', which is not a service")
+            if c.default_option is o and o.drop:
+                errors.append(f"{where}: the default option '{o.id}' drops a service; the default is the compose as it stands")
             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")
@@ -298,19 +307,31 @@ def validate(choices: list[Choice], compose_data: dict[str, Any]) -> list[str]:
 _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:``.
+def _as_list(option) -> list[Option]:
+    if option is None:
+        return []
+    return list(option) if isinstance(option, (list, tuple)) else [option]
+
+
+def flatten_compose(text: str, compose_data: dict[str, Any], option) -> str:
+    """The compose for one option, or one option per choice taken together:
+    their profiles' services in, every other profiled service out, dropped
+    services gone, ``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.
+    the result has to hold exactly the services the options get.
     """
-    profile = option.profile if option else ""
+    options = _as_list(option)
+    profiles = {o.profile for o in options if o.profile}
+    drop = {d for o in options for d in o.drop}
+    option = next((o for o in options if o.service_yaml), None)
     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")]}
+            if n not in drop
+            and (not (s or {}).get("profiles") or profiles & {str(p) for p in (s or {}).get("profiles")})}
+    gone = set(services) - keep
     # 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.
@@ -320,6 +341,7 @@ def flatten_compose(text: str, compose_data: dict[str, Any], option: Option | No
     in_services = False
     dropping = False
     skipping_profiles = False
+    in_depends = False
     inserted = False
     for line in text.splitlines():
         top = bool(line) and not line[0].isspace() and not line.startswith("#")
@@ -351,6 +373,31 @@ def flatten_compose(text: str, compose_data: dict[str, Any], option: Option | No
                 if stripped.startswith("- "):
                     continue
                 skipping_profiles = False
+            # A service that is gone must leave the others' depends_on too, or
+            # compose refuses the file. Flow form ([a, b]) and block form.
+            if gone:
+                fm = re.match(r"^(\s*depends_on:\s*)\[(.*)\]\s*$", line)
+                if fm:
+                    left = [x.strip() for x in fm.group(2).split(",") if x.strip() and x.strip() not in gone]
+                    if not left:
+                        continue
+                    out.append(f"{fm.group(1)}[{', '.join(left)}]")
+                    continue
+                if re.match(r"^\s*depends_on:\s*$", line):
+                    in_depends = True
+                    depends_header = line
+                    depends_kept = 0
+                    continue
+                if in_depends:
+                    dm = re.match(r"^\s*-\s*([A-Za-z0-9_.-]+)\s*$", line)
+                    if dm:
+                        if dm.group(1) in gone:
+                            continue
+                        if depends_kept == 0:
+                            out.append(depends_header)
+                        depends_kept += 1
+                    else:
+                        in_depends = False
         out.append(line)
     if in_services and option and option.service_yaml and not inserted:
         out.append(option.service_yaml.rstrip("\n"))
@@ -362,11 +409,26 @@ def flatten_compose(text: str, compose_data: dict[str, Any], option: Option | No
         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)}, "
+        label = ", ".join(o.id for o in options) or "default"
+        raise ValueError(f"flattening for '{label}' kept {sorted(got)}, "
                          f"wanted {sorted(want)}; the compose's services need two-space indents")
     return result
 
 
+def env_with_options(example_env: str, pairs: list[tuple[Choice, Option]]) -> str:
+    """example.env with every (choice, option) pair applied in turn."""
+    out = example_env
+    for c, o in pairs:
+        out = env_with_option(out, c, o)
+    return out
+
+
+def variant_suffix(pairs: list[tuple[Choice, Option]]) -> str:
+    """``<choice>-<option>`` per non-default pair, joined by dots; "" when
+    every pair is its choice's default."""
+    return ".".join(f"{c.id}-{o.id}" for c, o in pairs if o.id != c.default)
+
+
 def env_with_option(example_env: str, choice: Choice, option: Option) -> str:
     """example.env with the option's values applied and its asks listed.
 
diff --git a/dbuild/docs.py b/dbuild/docs.py
index 1c828c2..3b45244 100644
--- a/dbuild/docs.py
+++ b/dbuild/docs.py
@@ -315,108 +315,243 @@ 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."""
+def _combinations(cfg: Config) -> list[list[tuple[Any, Any]]]:
+    """Every way of answering the choices: one option per choice, every
+    combination, the all-default one first."""
+    import itertools
+
+    cs = cfg.metadata.choices
+    if not cs:
+        return []
+    ordered = [sorted(c.options, key=lambda o: o.id != c.default) for c in cs]
+    return [list(zip(cs, picks)) for picks in itertools.product(*ordered)]
+
+
+def _choice_variants(cfg: Config) -> list[tuple[list[tuple[Any, Any]], str, str]]:
+    """(pairs, compose text, env text) for every combination that is not the
+    default. The files people copy, one per combination."""
     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)))
+    for pairs in _combinations(cfg):
+        if all(o.id == c.default for c, o in pairs):
+            continue
+        opts = [o for _, o in pairs]
+        compose_text = choices_mod.flatten_compose(cfg.compose_text, cfg.compose_data, opts)
+        out.append((pairs, compose_text, choices_mod.env_with_options(cfg.example_env, pairs)))
     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:
+def _authored_director(cfg: Config) -> dict | None:
+    """The complete appjail.director an author wrote (immich), or None."""
+    aj = cfg.metadata.appjail if isinstance(cfg.metadata.appjail, dict) else None
+    d = (aj or {}).get("director")
+    return d if isinstance(d, dict) and d.get("services") else None
+
+
+def _director_for_option(director: dict, cfg: Config, option) -> dict:
+    """An authored director with only the services the chosen options run:
+    the dropped ones out, profiled ones in only when an option names their
+    profile. Service names match the compose's, so the compose's profiles
+    say which is which."""
+    services = cfg.compose_data.get("services") or {}
+    options = choices_mod._as_list(option)
+    profiles = {o.profile for o in options if o.profile}
+    drop = {d for o in options for d in o.drop}
+    out = dict(director)
+    kept = {}
+    for name, svc in (director.get("services") or {}).items():
+        if name in drop:
+            continue
+        svc_profiles = {str(p) for p in ((services.get(name) or {}).get("profiles") or [])}
+        if svc_profiles and not (svc_profiles & profiles):
+            continue
+        kept[name] = svc
+    out["services"] = kept
+    # Volumes only the kept services mount.
+    used = set()
+    for svc in kept.values():
+        for v in (svc or {}).get("volumes") or []:
+            if isinstance(v, dict):
+                used.update(v.keys())
+            elif isinstance(v, str):
+                used.add(v.split(":")[0].strip())
+    if isinstance(director.get("volumes"), dict):
+        out["volumes"] = {k: v for k, v in director["volumes"].items() if k in used}
+    return out
+
+
+def _sidecar_templates(cfg: Config) -> list[dict[str, str]]:
+    """Jail templates the authored bundle ships beside director.yml
+    (appjail.depends_on[].template), with their text, for the README."""
+    aj = cfg.metadata.appjail if isinstance(cfg.metadata.appjail, dict) else {}
+    out = []
+    for dep in (aj or {}).get("depends_on") or []:
+        tpl = dep.get("template") if isinstance(dep, dict) else None
+        if not tpl:
+            continue
+        path = Path.cwd() / tpl
+        if path.is_file():
+            out.append({"file": tpl, "text": path.read_text().rstrip("\n")})
+    return out
+
+
+def _stack_parts(cfg: Config) -> list[dict[str, str]]:
+    """The services of a stack with their images and roles (docs.services),
+    for the Parts table; a daemonless image links to its own page."""
+    if not cfg.compose_text:
         return []
-    variants = {(c.id, o.id): (ct, et) for c, o, ct, et in _choice_variants(cfg)}
+    docs = cfg.metadata.docs if isinstance(cfg.metadata.docs, dict) else {}
+    roles = {str(k): str(v) for k, v in (docs.get("services") or {}).items()}
     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 {}
+    for name, svc in (cfg.compose_data.get("services") or {}).items():
+        img = str((svc or {}).get("image", ""))
+        repo = img.split(":")[0]
+        page = repo.split("/")[-1] if repo.startswith("ghcr.io/daemonless/") else ""
+        profiles = [str(p) for p in ((svc or {}).get("profiles") or [])]
+        out.append({"name": name, "image": img, "desc": roles.get(name, ""), "page": page,
+                    "when": "" if not profiles else "with " + ", ".join(profiles)})
+    return out
+
+
+def _choice_context(cfg: Config, context_env: list[dict[str, Any]]) -> dict[str, Any]:
+    """The choices as the templates read them.
+
+    ``combos`` is one entry per way of answering every choice, the default
+    first, each with the files it needs in both renderings. ``tree`` nests
+    them choice by choice for the site's tabs: pick the first choice, then
+    the next inside it, and the leaf is the combination's files. The GitHub
+    README lists ``combos`` flat. ``choices`` is the declaration itself.
+    """
+    if not cfg.metadata.choices or not cfg.compose_text:
+        return {"choices": [], "combos": [], "tree": None}
+    import re as _re
+
+    import yaml  # lazy, as everywhere in this module: the wheel build imports it without yaml
+
+    variants = {choices_mod.variant_suffix(pairs): (ct, et) for pairs, ct, et in _choice_variants(cfg)}
+    engine_services = {ENGINE["service"] for ENGINE in choices_mod.ENGINES.values() if ENGINE.get("service")}
+    authored = _authored_director(cfg)
+    combos = []
+    for pairs in _combinations(cfg):
+        opts = [o for _, o in pairs]
+        suffix = choices_mod.variant_suffix(pairs)
+        is_default = suffix == ""
+        if is_default:
+            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[suffix]
+            compose_file, env_file = f"compose.{suffix}.yaml", f"example.{suffix}.env"
+        # The AppJail side: the template director grows each engine's jail,
+        # the .env takes every option's values with the host being the jail's
+        # name.
+        aj = dict(cfg.metadata.appjail) if isinstance(cfg.metadata.appjail, dict) else {}
+        values: dict[str, str] = {}
+        asks = []
+        for o in opts:
             if o.director_dep:
                 aj["depends_on"] = [*(aj.get("depends_on") or []), o.director_dep]
-            values = dict(o.env)
+            values.update(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.
-            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 = [], []
-            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)
+                asks.append({"name": a.name, "label": a.label, "default": a.default, "type": a.type, "values": a.values})
+        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:
+                aj_env.append({"name": k, "default": v, "env_only": True})
+        # What this combination runs, in words, before any YAML. Compose
+        # references resolve the way compose would: the .env value, else the
+        # ${VAR:-fallback}, else nothing.
+        env_values: dict[str, str] = {}
+        for ln in et.splitlines():
+            k, sep, v = ln.partition("=")
+            if sep and k.strip() and not k.lstrip().startswith("#"):
+                env_values[k.strip()] = v.partition("  #")[0].strip()
+        resolve = lambda text: _re.sub(  # noqa: E731
+            r"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}",
+            lambda m: env_values.get(m.group(1)) or (m.group(2) or ""), text)
+        parsed = (yaml.safe_load(ct) or {}).get("services") or {}
+        parts, jails = [], []
+        for sname, svc in parsed.items():
+            img = resolve(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 any(o.id == "external" for o in opts):
+            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 []:
+                if isinstance(v, str):
+                    bits = v.split(":")
+                    src, ro = resolve(bits[0]), len(bits) > 2 and "ro" in bits[2].split(",")
+                else:
+                    src, ro = resolve(str((v or {}).get("source", ""))), bool((v or {}).get("read_only"))
+                if ro or not src.startswith("/") or src.startswith(("/etc/", "/dev/", "/var/run/", "/usr/")):
+                    continue
+                if src not in folders:
+                    folders.append(src)
+        for o in opts:
             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
+        folders = [f.replace("/containers", "@CONTAINER_CONFIG_ROOT@") for f in folders]
+        director_text = director_env_text = ""
+        if authored is not None:
+            sliced = _director_for_option(authored, cfg, None if is_default else opts)
+            director_text = _render_director_override(sliced)
+            director_env_text = _render_override_env(sliced, {"name": cfg.image, "env": aj_env})
+            jails = [{"name": str((svc or {}).get("name", n)), "image": next((p["image"] for p in parts if p["name"] == n), ""), "kind": "app"}
+                     for n, svc in sliced["services"].items()]
+        tpl = next((o for o in opts if o.jail_template_file), None)
+        combos.append({
+            "id": suffix or "default", "default": is_default,
+            "selections": [{"choice": c.id, "choice_label": c.label, "option": o.id, "label": o.label, "default": o.id == c.default} for c, o in pairs],
+            "label": ", ".join(o.label for _, o in pairs),
+            "doc": " ".join(o.doc for _, o in pairs if o.doc),
+            "parts": parts, "jails": jails, "folders": folders,
+            "appjail": aj, "appjail_env": aj_env,
+            "director_text": director_text, "director_env_text": director_env_text,
+            "jail_template_file": tpl.jail_template_file if tpl else "", "jail_template": tpl.jail_template if tpl else "",
+            "ask": asks,
+            "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 is_default else "-" + suffix.replace(".", "-")),
+        })
+    by_key = {tuple(sel["option"] for sel in cb["selections"]): cb for cb in combos}
+
+    def tree(level: int, picked: tuple) -> dict | None:
+        cs = cfg.metadata.choices
+        if level >= len(cs):
+            return None
+        c = cs[level]
+        nodes = []
+        for o in sorted(c.options, key=lambda o: o.id != c.default):
+            key = (*picked, o.id)
+            nodes.append({"id": o.id, "label": o.label, "doc": o.doc, "default": o.id == c.default,
+                          "children": tree(level + 1, key),
+                          "combo": by_key.get(key) if level == len(cs) - 1 else None})
+        return {"id": c.id, "label": c.label, "doc": c.doc, "options": nodes}
+
+    declared = [{"id": c.id, "label": c.label, "doc": c.doc, "default": c.default,
+                 "options": [{"id": o.id, "label": o.label, "doc": o.doc, "default": o.id == c.default} for o in c.options]}
+                for c in cfg.metadata.choices]
+    return {"choices": declared, "combos": combos, "tree": tree(0, ())}
 
 
 def _enrich_metadata(cfg: Config, community_override: str | None = None) -> dict[str, Any]:
@@ -640,7 +775,15 @@ def _enrich_metadata(cfg: Config, community_override: str | None = None) -> dict
             "target": tgt
         })
 
-    context["choices"] = _choice_context(cfg, context["env"])
+    cc = _choice_context(cfg, context["env"])
+    context["choices"], context["combos"], context["choice_tree"] = cc["choices"], cc["combos"], cc["tree"]
+    # A stack whose author wrote the whole director: the README shows that,
+    # not the one-service template, with the jail templates it ships.
+    authored = _authored_director(cfg)
+    context["director_override_text"] = _render_director_override(authored) if authored else ""
+    context["director_override_env"] = _render_override_env(authored, context) if authored else ""
+    context["sidecar_templates"] = _sidecar_templates(cfg)
+    context["stack_parts"] = _stack_parts(cfg)
     return context
 
 
@@ -723,7 +866,10 @@ def generate_appjail_files(
     if aj_meta:
         d = aj_meta.get("director")
         if isinstance(d, dict) and d.get("services"):
-            director_override = d
+            # The bundle is the default answer to every choice: a jail behind
+            # a profile (immich's public proxy) stays out, as its service does
+            # under `podman-compose up` with no --profile.
+            director_override = _director_for_option(d, cfg, None)
 
     # Every bundle file must end in exactly one newline. AppJail's Makejail
     # parser is line-based and silently DROPS a final line with no trailing
@@ -881,18 +1027,10 @@ 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}")
-
+    # Stack choices render into the README (a section or a form per
+    # combination, each with its zip on the site); nothing lands on disk for
+    # them. Six generated files in a repo's root for two choices was clutter
+    # nobody copied from.
     # 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/templates/README.j2 b/dbuild/templates/README.j2
index 163dee7..c9606b6 100644
--- a/dbuild/templates/README.j2
+++ b/dbuild/templates/README.j2
@@ -87,9 +87,49 @@ services:
 {%- 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 "") %}
+{%- set zip = name ~ "-appjail" ~ ("-" ~ option.id | replace(".", "-") if option and not option.default else "") %}
+{%- set authored_dir = option.director_text if option else director_override_text %}
+{%- set authored_env = option.director_env_text if option else director_override_env %}
+{%- if authored_dir %}
+{#- The author wrote the whole director (a stack): show it, its .env and the
+    jail templates it ships, not the one-service derivation. #}
 {%- if render_mode == "mkdocs" %}
 ``` { data-zip-bundle="{{ zip }}" data-zip-filename=".env" }
+{{ authored_env | trim }}
+```
+
+```yaml { data-zip-bundle="{{ zip }}" data-zip-filename="appjail-director.yml" }
+{{ authored_dir | trim }}
+```
+{%- for t in sidecar_templates %}
+{{ '\n' }}
+``` { data-zip-bundle="{{ zip }}" data-zip-filename="{{ t.file }}" }
+{{ t.text }}
+```
+{%- endfor %}
+{%- else %}
+**.env**:
+
+```
+{{ authored_env | trim }}
+```
+
+**appjail-director.yml**:
+
+```yaml
+{{ authored_dir | trim }}
+```
+{%- for t in sidecar_templates %}
+{{ '\n' }}
+**{{ t.file }}**:
+
+```
+{{ t.text }}
+```
+{%- endfor %}
+{%- endif %}
+{%- elif render_mode == "mkdocs" %}
+``` { data-zip-bundle="{{ zip }}" data-zip-filename=".env" }
 {% include 'appjail.env.j2' %}
 ```
 
@@ -285,7 +325,9 @@ Source: dbuild templates
 
 [![Build Status](https://img.shields.io/github/actions/workflow/status/daemonless/{{ name }}/build.yaml?style=flat-square&label=Build&color=green)](https://github.com/daemonless/{{ name }}/actions)
 [![Last Commit](https://img.shields.io/github/last-commit/daemonless/{{ name }}?style=flat-square&label=Last+Commit&color=blue)](https://github.com/daemonless/{{ name }}/commits)
+{%- if variants %}
 [![OCI Pulls](https://img.shields.io/docker/pulls/daemonless/{{ name }}?style=flat-square&label=OCI+Pulls&color=blue)](https://hub.docker.com/r/daemonless/{{ name }})
+{%- endif %}
 {%- if mlock %}
 [![mlock Required](https://img.shields.io/badge/mlock-required-orange?style=flat-square&logo=freebsd&logoColor=white)]({% if render_mode == "mkdocs" %}/guides/ocijail-patch/{% else %}https://daemonless.io/guides/ocijail-patch/{% endif %})
 {%- endif %}
@@ -314,10 +356,14 @@ Source: dbuild templates
 {%- endif %}
 {%- endblock %}
 
+{%- if variants or (readme and readme.version_tags) %}
+
 ## Version Tags
+{%- endif %}
 
 {%- if readme and readme.version_tags %}
 {{ readme.version_tags }}
+{%- elif not variants %}
 {%- elif render_mode == "mkdocs" and 'aarch64' in (architectures | default(['amd64'])) %}
 
 === "Shared (recommended)"
@@ -338,6 +384,17 @@ Source: dbuild templates
 {%- endif %}
 {%- endblock %}
 
+{%- if stack_parts | length > 1 %}
+
+## Parts
+
+| Service | Image | Role | |
+|---|---|---|---|
+{%- for p in stack_parts %}
+| **{{ p.name }}** | `{{ p.image }}` | {{ p.desc }}{% if p.when %} ({{ p.when }}){% endif %} | {% if p.page %}[docs]({% if render_mode == "mkdocs" %}{{ p.page }}.md{% else %}https://github.com/daemonless/{{ p.page }}{% endif %}){% endif %} |
+{%- endfor %}
+{%- endif %}
+
 {%- block prerequisites -%}
 {%- if image_class == "service" %}
 
@@ -364,29 +421,29 @@ Before deploying, ensure your host environment is ready. See the [Quick Start Gu
 {%- for c in choices %}
 
 **{{ c.label }}.** {{ c.doc }}
-{%- for o in c.options %}
+{%- endfor %}
+{%- for cb in combos %}
 
-#### {{ o.label }}{% if o.default %} (default){% endif %}
-{%- if o.doc %}
+#### {{ cb.label }}{% if cb.default %} (default){% endif %}
+{%- if cb.doc %}
 
-{{ o.doc }}
+{{ cb.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 %}:
+**1.** Save as `.env`{% if cb.ask %} and fill in {{ cb.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 }}
+```env { data-zip-bundle="{{ cb.zip }}" data-zip-filename=".env" }
+{{ cb.example_env | trim }}
 ```
 
 **2.** Save as `compose.yaml`:
 
-```yaml { data-zip-bundle="{{ o.zip }}" data-zip-filename="compose.yaml" }
-{{ o.compose_text | trim }}
+```yaml { data-zip-bundle="{{ cb.zip }}" data-zip-filename="compose.yaml" }
+{{ cb.compose_text | trim }}
 ```
 
 Then run `podman-compose up -d`.
 {%- endfor %}
-{%- endfor %}
 {%- elif compose_text %}
 {%- if example_env %}
 
@@ -431,16 +488,14 @@ Save as `compose.yaml`, then run `podman-compose up -d`.
 {%- if appjail_enabled and choices %}
 
 ### AppJail Director
-{%- for c in choices %}
-{%- for o in c.options %}
+{%- for cb in combos %}
 
-#### {{ o.label }}{% if o.default %} (default){% endif %}
+#### {{ cb.label }}{% if cb.default %} (default){% endif %}
 
-{{ appjail_director_snippet(option=o) }}
+{{ appjail_director_snippet(option=cb) }}
 
 Save the files above, then run `appjail-director up`.
 {%- endfor %}
-{%- endfor %}
 {%- elif appjail_enabled and (not compose_text or appjail_sidecar) %}
 
 ### AppJail Director
diff --git a/dbuild/templates/README.mkdocs.j2 b/dbuild/templates/README.mkdocs.j2
index 5d164b2..246663d 100644
--- a/dbuild/templates/README.mkdocs.j2
+++ b/dbuild/templates/README.mkdocs.j2
@@ -4,6 +4,62 @@
     the data lands in. Plain words; 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). #}
+{#- The choices as one form: a card with a row of pills per choice, and
+    under it one block of files per combination, all but the default hidden.
+    deploy-choices.js on the site shows the block that matches the pills and
+    keeps Podman and AppJail on the same answers. Markdown inside the HTML
+    (md_in_html) so the fences keep their zip attributes. #}
+{%- macro choice_form(runtime) -%}
+<div class="deploy-choices" data-app="{{ name }}" data-runtime="{{ runtime }}" markdown>
+{% for c in choices %}
+
+**{{ c.label }}** {{ c.doc }}
+{: .choice data-choice="{{ c.id }}" }
+
+<div class="opts" data-choice="{{ c.id }}">{% for o in c.options %}<button type="button" data-option="{{ o.id }}"{% if o.default %} data-default aria-pressed="true"{% else %} aria-pressed="false"{% endif %}{% if o.doc %} title="{{ o.doc | replace('"', "'") }}"{% endif %}>{{ o.label }}</button>{% endfor %}</div>
+{% endfor %}
+
+</div>
+{% for cb in combos %}
+
+<div class="deploy-combo" data-key="{% for sel in cb.selections %}{{ sel.choice }}={{ sel.option }}{{ ";" if not loop.last }}{% endfor %}"{% if not cb.default %} hidden{% endif %} markdown>
+
+{{ combo_files(cb, runtime) }}
+
+</div>
+{% endfor %}
+{%- endmacro %}
+
+{%- macro combo_files(cb, runtime) -%}
+{% if runtime == "podman" %}
+{{ you_get(cb, cb.parts, "container") }}
+{% if cb.doc %}
+{{ cb.doc }}
+{% endif %}
+**1.** Save as `.env`{% if cb.ask %} and fill in {{ cb.ask | map(attribute='label') | join(', ') }}{% else %} and fill in what is empty{% endif %}:
+
+```env { data-zip-bundle="{{ cb.zip }}" data-zip-filename=".env" }
+{{ cb.example_env_site | trim }}
+```
+
+**2.** Save as `compose.yaml`:
+
+```yaml { data-zip-bundle="{{ cb.zip }}" data-zip-filename="compose.yaml" }
+{{ cb.compose_text_site | trim }}
+```
+
+Then run `podman-compose up -d`.
+{% else %}
+{{ you_get(cb, cb.jails, "jail") }}
+{% if cb.doc %}
+{{ cb.doc }}
+{% endif %}
+{{ appjail_director_snippet(port_var, cb) }}
+
+Save the files above, then run `appjail-director up`.
+{% endif %}
+{%- endmacro %}
+
 {%- macro you_get(o, parts, unit) -%}
 {%- set imgs = [] -%}
 {%- for p in parts %}{% if p.kind == "none" %}{% set _ = imgs.append("your own " ~ p.name | replace("your database", "database")) %}{% else %}{% set _ = imgs.append("`" ~ p.image ~ "`") %}{% endif %}{% endfor -%}
@@ -73,7 +129,9 @@ description: "{{ description }} Built natively for FreeBSD with s6 supervision,
 {%- if ports %}
 | :material-lan-connect: **Port** | `{{ ports[0].port }}` |
 {%- endif %}
+{%- if variants %}
 | :material-docker: **Registry** | [`{{ registry }}/{{ name }}`](https://github.com/daemonless/{{ name }}/pkgs/container/{{ name }}) |
+{%- endif %}
 | :fontawesome-brands-github: **Daemonless** | [daemonless/{{ name }}](https://github.com/daemonless/{{ name }}) |
 | :material-code-tags: **Source** | [{{ upstream_url | replace('https://github.com/', '') | replace('https://', '') | truncate(40, true, '…') }}]({{ upstream_url }}) |
 {%- if web_url %}
@@ -100,32 +158,7 @@ Before deploying, ensure your host environment is ready. See the [Quick Start Gu
     (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 %}
+{{ choice_form("podman") | indent(4, first=True) }}
 {% elif example_env %}
     **1.** Save as `.env` and fill in what is empty:
 
@@ -144,22 +177,7 @@ Before deploying, ensure your host environment is ready. See the [Quick Start Gu
 {% 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 }}"
-
-        {{ you_get(o, o.jails, "jail") | indent(8) }}
-
-{% if o.doc %}
-        {{ o.doc }}
-{% endif %}
-        {{ appjail_director_snippet(port_var, o) | indent(8) }}
-
-        Save the files above, then run `appjail-director up`.
-{% endfor %}
-{% endfor %}
+{{ choice_form("appjail") | indent(4, first=True) }}
 {% elif appjail_enabled and appjail_sidecar %}
 === ":appjail-appjail: AppJail"
 
diff --git a/tests/test_docs.py b/tests/test_docs.py
index 41418e0..74909e8 100644
--- a/tests/test_docs.py
+++ b/tests/test_docs.py
@@ -351,8 +351,8 @@ def test_repo_compose_and_env_get_site_placeholders(self):
       label: Search
       default: "off"
       options:
-        "off": { label: Off }
-        "on":  { label: On, profile: search, env: { TODO_SEARCH: "true" } }
+        "off": { label: "Off" }
+        "on":  { label: "On", profile: search, env: { TODO_SEARCH: "true" } }
 services:
   todo:
     image: ghcr.io/daemonless/todo:latest
@@ -375,6 +375,15 @@ def test_repo_compose_and_env_get_site_placeholders(self):
 CHOICES_ENV = "TZ=UTC\nTODO_DB_TYPE=sqlite\n"
 
 
+def _combo(ctx, **picks):
+    """The combination answering the given choices as picked, the rest default."""
+    for cb in ctx["combos"]:
+        sel = {s["choice"]: s["option"] for s in cb["selections"]}
+        if all(sel[k] == v for k, v in picks.items()) and all(s["default"] for s in cb["selections"] if s["choice"] not in picks):
+            return cb
+    raise AssertionError(f"no combination for {picks}")
+
+
 class TestStackChoices(unittest.TestCase):
     def _render(self, tmp: Path):
         (tmp / "compose.yaml").write_text(CHOICES_COMPOSE)
@@ -382,7 +391,14 @@ def _render(self, tmp: Path):
         (tmp / "Containerfile.j2").write_text(CONTAINERFILE_J2)
         with _chdir(tmp):
             cfg = dbuild_config.load(tmp)
+            ctx = docs._enrich_metadata(cfg, None)
             outputs, errors = docs.render_generated(cfg, argparse.Namespace(community=None), tmp)
+        # Nothing but the README is written for choices; the combinations'
+        # files live in the context, keyed by name here for the asserts.
+        self.assertEqual([k for k in outputs if k.startswith(("compose.", "example."))], [])
+        for cb in ctx["combos"]:
+            outputs[cb["compose_file"]] = cb["compose_text"]
+            outputs[cb["env_file"]] = cb["example_env"]
         return outputs, errors
 
     def test_database_services_come_from_dbuild(self):
@@ -424,14 +440,17 @@ def test_you_get_names_what_runs_and_where_data_lands(self):
             (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")
+        pg = _combo(ctx, database="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")
+        ext = _combo(ctx, database="external")
         self.assertEqual(ext["parts"][-1]["kind"], "none")
+        both = _combo(ctx, database="postgres", search="on")
+        self.assertIn("  meili:", both["compose_text"], "two choices answered at once, in one file")
+        self.assertIn("  postgres:", both["compose_text"])
+        self.assertEqual(both["compose_file"], "compose.database-postgres.search-on.yaml")
 
     def test_a_part_choice_switches_a_profile(self):
         with tempfile.TemporaryDirectory() as d:
@@ -446,7 +465,7 @@ 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"))
+        i_sql, i_pg, i_ext = (readme.index(h) for h in ("#### SQLite, Off (default)", "#### PostgreSQL, Off", "#### Your own, Off"))
         self.assertTrue(i_sql < i_pg < i_ext)
         self.assertIn("fill in Kind, Host, User, Password, Database", readme)
 
@@ -480,7 +499,7 @@ def test_director_per_option_from_the_same_engine_table(self):
         self.assertEqual(errors, [])
         readme = outputs["README.md"]
         aj = readme[readme.index("### AppJail Director"):]
-        pg = aj[aj.index("#### PostgreSQL"):aj.index("#### MariaDB")]
+        pg = aj[aj.index("#### PostgreSQL, Off"):aj.index("#### MariaDB, Off")]
         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")
@@ -488,5 +507,195 @@ def test_director_per_option_from_the_same_engine_table(self):
         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")]
+        sq = aj[aj.index("#### SQLite, Off (default)"):aj.index("#### PostgreSQL, Off")]
         self.assertNotIn("postgres", sq)
+
+
+# ── A stack with an authored director and part choices (immich-shaped) ──
+
+STACK_COMPOSE = """\
+name: photos
+x-daemonless:
+  title: "Photos"
+  description: "A photo stack."
+  category: "Photos & Media"
+  icon: ":test:"
+  upstream_url: "https://example.com"
+  user: "bsd"
+  type: stack
+  choices:
+    machine_learning:
+      label: Machine learning
+      doc: Faces and search. Needs memory.
+      default: "on"
+      options:
+        "on":  { label: "On" }
+        "off": { label: "Off", drop: [ml], env: { ML_ENABLED: "false" } }
+    public_proxy:
+      label: Public sharing
+      default: "off"
+      options:
+        "off": { label: "Off" }
+        "on":  { label: "On", profile: proxy }
+  docs:
+    services:
+      server: "Web UI and API"
+      ml: "Faces and search"
+      proxy: "Public links"
+    env:
+      DB_PASSWORD: "Database password"
+  appjail:
+    depends_on:
+      - name: db
+        template: db-template.conf
+    director:
+      options:
+        - alias:
+      services:
+        server:
+          name: photos_server
+          priority: 100
+          options:
+            - from: ghcr.io/daemonless/photos-server:latest
+          oci:
+            environment:
+              - ML_ENABLED: "!ENV '${ML_ENABLED}'"
+          volumes:
+            - data: /data
+        ml:
+          name: photos_ml
+          options:
+            - from: ghcr.io/daemonless/photos-ml:latest
+          volumes:
+            - cache: /cache
+        proxy:
+          name: photos_proxy
+          options:
+            - from: ghcr.io/daemonless/photos-proxy:latest
+        db:
+          name: photos_db
+          options:
+            - from: ghcr.io/daemonless/postgres:17
+            - template: "!ENV '${PWD}/db-template.conf'"
+      volumes:
+        data:
+          device: "!ENV '${UPLOAD_LOCATION}'"
+        cache:
+          device: "!ENV '${CACHE_LOCATION}'"
+services:
+  server:
+    image: ghcr.io/daemonless/photos-server:latest
+    network_mode: host
+    environment:
+      ML_ENABLED: ${ML_ENABLED:-true}
+    depends_on:
+      - db
+      - ml
+    volumes:
+      - ${UPLOAD_LOCATION}:/data
+  ml:
+    image: ghcr.io/daemonless/photos-ml:latest
+    network_mode: host
+    volumes:
+      - ${CACHE_LOCATION}:/cache
+  proxy:
+    image: ghcr.io/daemonless/photos-proxy:latest
+    network_mode: host
+    profiles: [proxy]
+  db:
+    image: ghcr.io/daemonless/postgres:17
+    network_mode: host
+    environment:
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+"""
+
+STACK_ENV = "UPLOAD_LOCATION=/containers/photos/library\nCACHE_LOCATION=/containers/photos/cache\nDB_PASSWORD=change-me\n"
+
+
+class TestStackWithAuthoredDirector(unittest.TestCase):
+    def _render(self, tmp: Path):
+        (tmp / "compose.yaml").write_text(STACK_COMPOSE)
+        (tmp / "example.env").write_text(STACK_ENV)
+        (tmp / "db-template.conf").write_text("sysvshm: new\n")
+        with _chdir(tmp):
+            cfg = dbuild_config.load(tmp)
+            ctx = docs._enrich_metadata(cfg, None)
+            outputs, errors = docs.render_generated(cfg, argparse.Namespace(community=None), tmp)
+        self.assertEqual([k for k in outputs if k.startswith(("compose.", "example."))], [], "choices write nothing to disk")
+        for cb in ctx["combos"]:
+            outputs[cb["compose_file"]] = cb["compose_text"]
+            outputs[cb["env_file"]] = cb["example_env"]
+        return ctx, outputs, errors
+
+    def test_a_part_can_be_dropped_and_depends_on_follows(self):
+        with tempfile.TemporaryDirectory() as d:
+            ctx, outputs, errors = self._render(Path(d))
+        self.assertEqual(errors, [])
+        off = outputs["compose.machine_learning-off.yaml"]
+        self.assertNotIn("\n  ml:", off)
+        self.assertIn("    depends_on:\n      - db\n", off, "the dropped service left the others' depends_on")
+        self.assertNotIn("- ml", off)
+        self.assertIn("ML_ENABLED=false", outputs["example.machine_learning-off.env"])
+        on = outputs["compose.public_proxy-on.yaml"]
+        self.assertIn("\n  proxy:", on)
+        self.assertNotIn("profiles", on)
+
+    def test_authored_director_is_sliced_per_option(self):
+        with tempfile.TemporaryDirectory() as d:
+            ctx, outputs, _ = self._render(Path(d))
+        off = _combo(ctx, machine_learning="off")
+        self.assertNotIn("photos_ml", off["director_text"])
+        self.assertNotIn("cache:", off["director_text"], "a volume only the dropped jail used is gone too")
+        self.assertIn("photos_db", off["director_text"])
+        self.assertIn("ML_ENABLED=false", off["director_env_text"])
+        on = _combo(ctx, machine_learning="on")
+        self.assertIn("photos_ml", on["director_text"])
+        both = _combo(ctx, machine_learning="off", public_proxy="on")
+        self.assertEqual([j["name"] for j in both["jails"]], ["photos_server", "photos_proxy", "photos_db"])
+        self.assertNotIn("photos_proxy", on["director_text"], "a profiled jail is out unless its option is picked")
+        self.assertEqual([j["name"] for j in off["jails"]], ["photos_server", "photos_db"])
+        self.assertIn("priority: 100", ctx["director_override_text"], "the author's director, verbatim, for the stack")
+        self.assertEqual(ctx["sidecar_templates"][0]["file"], "db-template.conf")
+
+    def test_readme_has_parts_and_the_authored_director(self):
+        with tempfile.TemporaryDirectory() as d:
+            ctx, outputs, _ = self._render(Path(d))
+        readme = outputs["README.md"]
+        self.assertIn("## Parts", readme)
+        self.assertIn("| **ml** | `ghcr.io/daemonless/photos-ml:latest` | Faces and search |", readme)
+        self.assertIn("| **proxy** | `ghcr.io/daemonless/photos-proxy:latest` | Public links (with proxy) |", readme)
+        self.assertNotIn("## Version Tags", readme, "a stack has no tags of its own")
+        aj = readme[readme.index("### AppJail Director"):]
+        self.assertIn("priority: 100", aj)
+        self.assertIn("**db-template.conf**", aj)
+        self.assertIn("sysvshm: new", aj)
+
+    def test_the_line_resolves_tags_and_skips_the_clock_mount(self):
+        compose = STACK_COMPOSE.replace("    image: ghcr.io/daemonless/photos-server:latest\n    network_mode: host\n",
+                                        "    image: ghcr.io/daemonless/photos-server:${TAG:-latest}\n    network_mode: host\n", 1)
+        compose = compose.replace("      - ${UPLOAD_LOCATION}:/data\n", "      - ${UPLOAD_LOCATION}:/data\n      - /etc/localtime:/etc/localtime:ro\n")
+        with tempfile.TemporaryDirectory() as d:
+            t = Path(d)
+            (t / "compose.yaml").write_text(compose)
+            (t / "example.env").write_text(STACK_ENV)
+            (t / "db-template.conf").write_text("sysvshm: new\n")
+            with _chdir(t):
+                ctx = docs._enrich_metadata(dbuild_config.load(t), None)
+        on = ctx["combos"][0]
+        self.assertTrue(on["default"])
+        self.assertEqual(on["parts"][0]["image"], "photos-server:latest", "the compose fallback resolves")
+        self.assertEqual(on["folders"], ["@CONTAINER_CONFIG_ROOT@/photos/library", "@CONTAINER_CONFIG_ROOT@/photos/cache"])
+
+    def test_bundle_on_disk_is_the_default_answer(self):
+        with tempfile.TemporaryDirectory() as d:
+            t = Path(d)
+            (t / "compose.yaml").write_text(STACK_COMPOSE)
+            (t / "example.env").write_text(STACK_ENV)
+            (t / "db-template.conf").write_text("sysvshm: new\n")
+            with _chdir(t):
+                cfg = dbuild_config.load(t)
+                docs.generate_appjail_files(cfg, t / "bundle")
+            director = (t / "bundle" / "appjail-director.yml").read_text()
+        self.assertIn("photos_ml", director, "a part on by default is in")
+        self.assertNotIn("photos_proxy", director, "a part behind a profile is out of the default bundle")
+        self.assertIn("photos_db", director)

From dc3642586c9bbd0f8c3fcf38e49bd7fad900c32b Mon Sep 17 00:00:00 2001
From: Michael Johnson <buhnux@gmail.com>
Date: Fri, 2 Oct 2026 17:32:08 -0400
Subject: [PATCH 2/2] lint: a stack builds no image; dbuild choices for the
 catalog; release v1.10.1

A type: stack repo was asked for a Containerfile and a user; it runs other images and has neither. Hidden until v1.9.17 made lint errors fail the job, so immich went red on its first push since. dbuild choices prints a stack's choices resolved for fjord's catalog (per option: env, services to add or drop, defaults, secrets, asks), and the on-disk AppJail bundle is the default answer. Version 1.10.1 and the workflow pin.
---
 .github/workflows/daemonless-build.yaml |  2 +-
 dbuild/__init__.py                      |  2 +-
 dbuild/choices.py                       | 83 +++++++++++++++++++++++++
 dbuild/cli.py                           | 27 ++++++++
 dbuild/lint.py                          | 12 +++-
 docs/dbuild.1                           | 13 +++-
 tests/test_docs.py                      | 36 +++++++++++
 tests/test_lint.py                      | 19 ++++++
 8 files changed, 190 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/daemonless-build.yaml b/.github/workflows/daemonless-build.yaml
index 83e3c75..42c5ff1 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.10.0
+  DBUILD_REF: v1.10.1
 
 jobs:
   # Detect which variants exist and build dynamic matrix
diff --git a/dbuild/__init__.py b/dbuild/__init__.py
index a8c4b3a..28173a3 100644
--- a/dbuild/__init__.py
+++ b/dbuild/__init__.py
@@ -1,4 +1,4 @@
 """dbuild: FreeBSD OCI container image build tool.
 """
 
-VERSION = "1.10.0"
+VERSION = "1.10.1"
diff --git a/dbuild/choices.py b/dbuild/choices.py
index a6b7165..fd39882 100644
--- a/dbuild/choices.py
+++ b/dbuild/choices.py
@@ -474,3 +474,86 @@ 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"
+
+
+# --- for fjord ---------------------------------------------------------
+
+def service_block(text: str, name: str) -> str:
+    """One service's block as written in the compose (two-space indent under
+    ``services:``), its ``profiles:`` lines left out. What a consumer adds
+    back when the option that owns the service is picked."""
+    out: list[str] = []
+    in_services = False
+    in_block = False
+    skipping_profiles = False
+    for line in text.splitlines():
+        top = bool(line) and not line[0].isspace() and not line.startswith("#")
+        if top:
+            if in_block:
+                break
+            in_services = line.startswith("services:")
+            continue
+        if not in_services:
+            continue
+        m = _SERVICE_RE.match(line)
+        if m:
+            if in_block:
+                break
+            in_block = m.group(1) == name
+            if in_block:
+                out.append(line)
+            continue
+        if not in_block:
+            continue
+        stripped = line.strip()
+        if re.match(r"^profiles:\s*(\[.*\])?\s*$", stripped):
+            skipping_profiles = stripped.endswith("profiles:")
+            continue
+        if skipping_profiles:
+            if stripped.startswith("- "):
+                continue
+            skipping_profiles = False
+        out.append(line)
+    return "\n".join(out).rstrip("\n") + ("\n" if out else "")
+
+
+def to_fjord(choices: list[Choice], compose_text: str, compose_data: dict[str, Any]) -> dict[str, Any]:
+    """The choices as fjord's catalog carries them (x-fjord.choices): per
+    option, the env it sets, the services to add (its own block text, or the
+    one dbuild supplies), the services to drop, the values to ask for, the
+    defaults the extra services need and the secrets to make up."""
+    services = compose_data.get("services") or {}
+    app = next(iter(services), "")
+    out = []
+    for c in choices:
+        opts = []
+        for o in c.options:
+            add = o.service_yaml
+            depends: dict[str, list[str]] = {}
+            if o.profile:
+                for name, svc in services.items():
+                    if o.profile in [str(p) for p in ((svc or {}).get("profiles") or [])]:
+                        add += service_block(compose_text, name)
+            if o.service_yaml and app:
+                depends[app] = [_SERVICE_RE.match(o.service_yaml.splitlines()[0]).group(1)]
+            defaults, secrets = {}, []
+            for ln in o.env_lines:
+                k, _, rest = ln.partition("=")
+                v = rest.partition("  #")[0].strip()
+                if "set one" in rest:
+                    secrets.append(k)
+                else:
+                    # A data folder belongs to the stack, not the app: two
+                    # installs of one app must not share a postgres directory.
+                    # fjord expands {{base}} and {{stack}} at install.
+                    if app and v.startswith(f"/containers/{app}/"):
+                        v = "{{base}}/{{stack}}/" + v[len(f"/containers/{app}/"):]
+                    defaults[k] = v
+            opts.append({
+                "id": o.id, "label": o.label, "doc": o.doc,
+                "env": dict(o.env), "defaults": defaults, "secrets": secrets,
+                "services": add, "depends_on": depends, "drop": list(o.drop),
+                "ask": [{"name": a.name, "label": a.label, "default": a.default, "type": a.type, "values": dict(a.values)} for a in o.ask],
+            })
+        out.append({"id": c.id, "kind": c.kind, "label": c.label, "doc": c.doc, "default": c.default, "options": opts})
+    return {"choices": out}
diff --git a/dbuild/cli.py b/dbuild/cli.py
index 652d489..a5b9b07 100644
--- a/dbuild/cli.py
+++ b/dbuild/cli.py
@@ -285,6 +285,18 @@ def _make_parser() -> argparse.ArgumentParser:
         ),
     )
 
+    # -- choices --
+    choices_parser = sub.add_parser(
+        "choices",
+        help="print the stack's choices (x-daemonless.choices) as JSON, for fjord's catalog",
+        description=(
+            "The choices resolved for a consumer: per option the env it sets, the "
+            "services to add or drop, the values to ask for, the defaults and the "
+            "secrets the extra services need. Empty when the compose declares none."
+        ),
+    )
+    choices_parser.add_argument("--out", default="-", metavar="FILE", help="write here instead of stdout")
+
     # -- appjail-bundle --
     appjail_parser = sub.add_parser(
         "appjail-bundle",
@@ -597,6 +609,20 @@ def _dispatch_ci_run(cfg: Config, args: argparse.Namespace) -> int:
     return rc if rc else 0
 
 
+def _dispatch_choices(cfg: Config, args: argparse.Namespace) -> int:
+    """Print the choices as fjord's catalog carries them."""
+    import json
+
+    from dbuild import choices as choices_mod
+    data = choices_mod.to_fjord(cfg.metadata.choices, cfg.compose_text, cfg.compose_data)
+    text = json.dumps(data, indent=2) + "\n"
+    if args.out == "-":
+        sys.stdout.write(text)
+    else:
+        Path(args.out).write_text(text)
+    return 0
+
+
 def _dispatch_appjail_bundle(cfg: Config, args: argparse.Namespace) -> int:
     """Render the AppJail deploy bundle into --out (nothing if appjail disabled)."""
     from pathlib import Path
@@ -642,6 +668,7 @@ def _dispatch_prune(cfg: Config, args: argparse.Namespace) -> int:
     "generate": _dispatch_docs,
     "docs": _dispatch_docs,
     "appjail-bundle": _dispatch_appjail_bundle,
+    "choices": _dispatch_choices,
 }
 
 # Commands that run without loading project config
diff --git a/dbuild/lint.py b/dbuild/lint.py
index 3d0e44d..1d08894 100644
--- a/dbuild/lint.py
+++ b/dbuild/lint.py
@@ -77,7 +77,12 @@ def lint_repo(repo_path: Path, verbose: bool = False) -> tuple[list[str], list[s
             # Fields that become optional (warnings only) for deprecated images
             OPTIONAL_WHEN_DEPRECATED = {"upstream_url", "description"}
 
+            # A stack (type: stack) builds no image of its own: it runs other
+            # images, so it has no user to name and no Containerfile.
+            is_stack = meta.get("type") == "stack"
             for field in REQUIRED_X_DAEMONLESS_FIELDS:
+                if is_stack and field == "user":
+                    continue
                 if field not in meta or not meta[field]:
                     if is_deprecated and field in OPTIONAL_WHEN_DEPRECATED:
                         warnings.append(
@@ -344,6 +349,11 @@ def lint_repo(repo_path: Path, verbose: bool = False) -> tuple[list[str], list[s
 
     if verbose:
         print("  checking Containerfile")
+    is_stack_repo = False
+    try:
+        is_stack_repo = ((yaml.safe_load((repo_path / "compose.yaml").read_text()) or {}).get("x-daemonless") or {}).get("type") == "stack"
+    except Exception:
+        pass
     has_containerfile = any(
         (repo_path / name).exists()
         for name in (
@@ -351,7 +361,7 @@ def lint_repo(repo_path: Path, verbose: bool = False) -> tuple[list[str], list[s
             *variant_containerfiles,
         )
     )
-    if not has_containerfile:
+    if not has_containerfile and not is_stack_repo:
         errors.append("Missing Containerfile")
 
     if verbose:
diff --git a/docs/dbuild.1 b/docs/dbuild.1
index 08867bb..60339e4 100644
--- a/docs/dbuild.1
+++ b/docs/dbuild.1
@@ -1,4 +1,4 @@
-.TH DBUILD 1 "2026-10-01" "dbuild 1.10.0" "User Commands"
+.TH DBUILD 1 "2026-10-02" "dbuild 1.10.1" "User Commands"
 .SH NAME
 dbuild \- FreeBSD OCI container image build tool
 .SH SYNOPSIS
@@ -62,6 +62,17 @@ tag directly as the final tag(s) instead of build-{tag}, skipping the staging st
 Mount a host directory into containers when executing RUN instructions during the build (pased as --volume). If the `build.variants.[].cache_dirs` parameter is defined, dbuild will use those directories and the ones specified in this parameter as cache directories.
 .RE
 .TP
+\fBchoices\fR
+The choices resolved for a consumer: per option the env it sets, the services to add or drop, the values to ask for, the defaults and the secrets the extra services need. Empty when the compose declares none.
+.RS
+.TP
+\fB-h\fR, \fB--help\fR
+show this help message and exit
+.TP
+\fB--out\fR
+write here instead of stdout
+.RE
+.TP
 \fBci-prepare\fR
 Set up a FreeBSD CI runner with all build dependencies.
 .RS
diff --git a/tests/test_docs.py b/tests/test_docs.py
index 74909e8..a2199da 100644
--- a/tests/test_docs.py
+++ b/tests/test_docs.py
@@ -699,3 +699,39 @@ def test_bundle_on_disk_is_the_default_answer(self):
         self.assertIn("photos_ml", director, "a part on by default is in")
         self.assertNotIn("photos_proxy", director, "a part behind a profile is out of the default bundle")
         self.assertIn("photos_db", director)
+
+    def test_choices_for_fjord(self):
+        from dbuild import choices as choices_mod
+        with tempfile.TemporaryDirectory() as d:
+            t = Path(d)
+            (t / "compose.yaml").write_text(STACK_COMPOSE)
+            (t / "example.env").write_text(STACK_ENV)
+            with _chdir(t):
+                cfg = dbuild_config.load(t)
+                data = choices_mod.to_fjord(cfg.metadata.choices, cfg.compose_text, cfg.compose_data)
+        ml, proxy = data["choices"]
+        off = next(o for o in ml["options"] if o["id"] == "off")
+        self.assertEqual(off["drop"], ["ml"])
+        self.assertEqual(off["env"], {"ML_ENABLED": "false"})
+        on = next(o for o in proxy["options"] if o["id"] == "on")
+        self.assertTrue(on["services"].startswith("  proxy:\n    image: ghcr.io/daemonless/photos-proxy:latest\n"), on["services"])
+        self.assertNotIn("profiles", on["services"], "the profile line is dbuild's business, not the consumer's")
+
+    def test_choices_for_fjord_database_kind(self):
+        from dbuild import choices as choices_mod
+        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):
+                cfg = dbuild_config.load(t)
+                data = choices_mod.to_fjord(cfg.metadata.choices, cfg.compose_text, cfg.compose_data)
+        db = data["choices"][0]
+        pg = next(o for o in db["options"] if o["id"] == "postgres")
+        self.assertIn("  postgres:\n    image: ghcr.io/daemonless/postgres:17", pg["services"])
+        self.assertEqual(pg["depends_on"], {"todo": ["postgres"]})
+        self.assertEqual(pg["secrets"], ["TODO_DB_PASSWORD"])
+        self.assertEqual(pg["defaults"]["DATABASE_LOCATION"], "{{base}}/{{stack}}/postgres", "the folder follows the stack, not the app")
+        ext = next(o for o in db["options"] if o["id"] == "external")
+        self.assertEqual([a["name"] for a in ext["ask"]][:2], ["TODO_DB_TYPE", "TODO_DB_HOST"])
diff --git a/tests/test_lint.py b/tests/test_lint.py
index 2469a4e..a05558f 100644
--- a/tests/test_lint.py
+++ b/tests/test_lint.py
@@ -299,3 +299,22 @@ def test_no_config_no_crash(self):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestStackRepoLint(unittest.TestCase):
+    """A stack (type: stack) builds no image: no Containerfile, no user."""
+
+    def test_stack_needs_no_containerfile_or_user(self):
+        import tempfile
+        from pathlib import Path
+
+        from dbuild.lint import lint_repo
+        with tempfile.TemporaryDirectory() as d:
+            p = Path(d)
+            (p / "compose.yaml").write_text(
+                "name: photos\nx-daemonless:\n  title: Photos\n  icon: ':x:'\n  category: Photos & Media\n"
+                "  description: d\n  upstream_url: https://example.com\n  type: stack\n"
+                "services:\n  app:\n    image: ghcr.io/daemonless/app:latest\n")
+            errors, _ = lint_repo(p)
+        self.assertNotIn("Missing Containerfile", errors)
+        self.assertFalse([e for e in errors if "x-daemonless.user" in e], errors)