@fazer-ai/agents 1.0.0

package/dist/skills/agents-onboarding/scripts/gen-onboarding-env.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env bun
+import { randomBytes } from "node:crypto";
+import { chmodSync } from "node:fs";
+
+// Generates the secrets + connection URLs the platform-neutral stack (docker-compose.prod.yml) needs,
+// for Tier B/D onboarding (Portainer / EasyPanel / plain VM) where there is no Coolify to mint magic
+// vars. Writes a .env holding the TWO database roles (superuser + NON-superuser runtime), JWT_SECRET,
+// ENCRYPTION_KEY, and the derived MIGRATION_DATABASE_URL / DATABASE_URL / LANGGRAPH_DATABASE_URL /
+// PUBLIC_URL. For these tiers the .env IS the deploy destination for the secrets (Coolify keeps its
+// own store and ignores this script). See docs/deploy.md for the two-role contract.
+
+export interface OnboardingEnvOptions {
+  publicUrl: string;
+  dbHost?: string;
+  dbPort?: number;
+  dbName?: string;
+  pgUser?: string;
+  appUser?: string;
+  corsOrigin?: string;
+  appPort?: string;
+  // Bare hostname Caddy serves TLS for (docker-compose.portainer.yml). Defaults to PUBLIC_URL's host.
+  caddyDomain?: string;
+  // Optional ACME contact for expiry notices + better rate-limit standing. Caddy works without it.
+  acmeEmail?: string;
+}
+
+export interface OnboardingEnv {
+  PUBLIC_URL: string;
+  CORS_ORIGIN: string;
+  LOG_LEVEL: string;
+  APP_PORT: string;
+  // NOTE: disabled ONLY for this trusted first-run deploy (the operator drives /setup right after
+  // provisioning), removing token friction. The app-wide default in src/config.ts stays `true`.
+  SETUP_TOKEN_REQUIRED: string;
+  DATABASE_NAME: string;
+  POSTGRES_USER: string;
+  POSTGRES_PASSWORD: string;
+  JWT_SECRET: string;
+  ENCRYPTION_KEY: string;
+  MIGRATION_DATABASE_URL: string;
+  DATABASE_URL: string;
+  LANGGRAPH_DATABASE_URL: string;
+  // Consumed only by docker-compose.portainer.yml's bundled Caddy; harmless for the BYO-proxy stack.
+  CADDY_DOMAIN: string;
+  ACME_EMAIL?: string;
+}
+
+// URL-safe secret: hex has no characters that need escaping inside a postgres:// URL or a .env value.
+function secret(bytes: number): string {
+  return randomBytes(bytes).toString("hex");
+}
+
+const ROLE_NAME = /^[A-Za-z0-9_-]+$/;
+
+export function buildOnboardingEnv(opts: OnboardingEnvOptions): OnboardingEnv {
+  const publicUrl = opts.publicUrl.replace(/\/+$/, "");
+  if (!/^https?:\/\//.test(publicUrl)) {
+    throw new Error(
+      `PUBLIC_URL must start with http:// or https:// (got "${opts.publicUrl}")`,
+    );
+  }
+  const dbHost = opts.dbHost ?? "postgres";
+  const dbPort = opts.dbPort ?? 5432;
+  const dbName = opts.dbName ?? "secretaria_v4_db";
+  const pgUser = opts.pgUser ?? "postgres";
+  const appUser = opts.appUser ?? "secv4_app";
+  // db-bootstrap.ts interpolates the runtime role name into DDL as a quoted identifier; keep both
+  // role names to the safe charset it accepts so a generated .env can never break that out.
+  for (const [label, name] of [
+    ["postgres superuser", pgUser],
+    ["app role", appUser],
+  ] as const) {
+    if (!ROLE_NAME.test(name)) {
+      throw new Error(
+        `${label} name must match [A-Za-z0-9_-]+ (got "${name}")`,
+      );
+    }
+  }
+
+  const pgPassword = secret(24);
+  const appPassword = secret(24);
+  const authority = (user: string, pass: string) =>
+    `postgres://${user}:${pass}@${dbHost}:${dbPort}/${dbName}`;
+  // The checkpointer pool MUST be the runtime (non-superuser) role, never the migration URL.
+  const databaseUrl = authority(appUser, appPassword);
+
+  // Caddy serves TLS for the bare host; PUBLIC_URL carries the scheme so derive the host from it.
+  const caddyDomain = opts.caddyDomain ?? new URL(publicUrl).hostname;
+  const acmeEmail = opts.acmeEmail?.trim();
+  if (acmeEmail !== undefined && acmeEmail !== "" && !acmeEmail.includes("@")) {
+    throw new Error(`ACME_EMAIL must be an email address (got "${acmeEmail}")`);
+  }
+
+  return {
+    PUBLIC_URL: publicUrl,
+    CORS_ORIGIN: opts.corsOrigin ?? "*",
+    LOG_LEVEL: "info",
+    APP_PORT: opts.appPort ?? "3000",
+    SETUP_TOKEN_REQUIRED: "false",
+    DATABASE_NAME: dbName,
+    POSTGRES_USER: pgUser,
+    POSTGRES_PASSWORD: pgPassword,
+    JWT_SECRET: secret(32),
+    ENCRYPTION_KEY: secret(32),
+    MIGRATION_DATABASE_URL: authority(pgUser, pgPassword),
+    DATABASE_URL: databaseUrl,
+    LANGGRAPH_DATABASE_URL: databaseUrl,
+    CADDY_DOMAIN: caddyDomain,
+    ...(acmeEmail ? { ACME_EMAIL: acmeEmail } : {}),
+  };
+}
+
+function serializeEnv(env: OnboardingEnv): string {
+  const header = [
+    "# Generated by scripts/gen-onboarding-env.ts for docker-compose.prod.yml.",
+    "# SENSITIVE: holds DB passwords, JWT_SECRET and ENCRYPTION_KEY. Do NOT commit.",
+    "# Rotating ENCRYPTION_KEY invalidates all encrypted-at-rest data (vault, Chatwoot tokens).",
+    "",
+    "",
+  ].join("\n");
+  return `${header}${Object.entries(env)
+    .map(([k, v]) => `${k}=${v}`)
+    .join("\n")}\n`;
+}
+
+function flag(name: string): string | undefined {
+  const eq = `--${name}=`;
+  const hit = process.argv.find((a) => a.startsWith(eq));
+  if (hit) return hit.slice(eq.length);
+  const idx = process.argv.indexOf(`--${name}`);
+  const next = process.argv[idx + 1];
+  if (idx !== -1 && next && !next.startsWith("--")) return next;
+  return undefined;
+}
+
+async function main() {
+  const publicUrl = flag("public-url") ?? process.env.PUBLIC_URL;
+  if (!publicUrl) {
+    console.error(
+      "usage: bun scripts/gen-onboarding-env.ts --public-url https://agentes.example.com [--out .env] [--force]\n" +
+        "       [--db-host postgres] [--db-port 5432] [--db-name secretaria_v4_db] [--pg-user postgres] [--app-user secv4_app]\n" +
+        "       [--caddy-domain agentes.example.com] [--acme-email you@example.com]  # for docker-compose.portainer.yml",
+    );
+    process.exit(1);
+  }
+  const out = flag("out") ?? ".env";
+  const force = process.argv.includes("--force");
+  if (!force && (await Bun.file(out).exists())) {
+    console.error(
+      `refusing to overwrite existing ${out} (would rotate secrets and break a running deploy). Pass --force to replace.`,
+    );
+    process.exit(1);
+  }
+
+  const env = buildOnboardingEnv({
+    publicUrl,
+    dbHost: flag("db-host"),
+    dbPort: flag("db-port") ? Number(flag("db-port")) : undefined,
+    dbName: flag("db-name"),
+    pgUser: flag("pg-user"),
+    appUser: flag("app-user"),
+    corsOrigin: flag("cors-origin"),
+    appPort: flag("app-port"),
+    caddyDomain: flag("caddy-domain"),
+    acmeEmail: flag("acme-email"),
+  });
+
+  await Bun.write(out, serializeEnv(env));
+  try {
+    chmodSync(out, 0o600);
+  } catch {
+    // best-effort (e.g. a non-POSIX filesystem); the file is written regardless.
+  }
+
+  // Masked summary — never print the secret values (they would land in logs).
+  const appRole = new URL(env.DATABASE_URL).username;
+  console.log(
+    `wrote ${out} (chmod 600): PUBLIC_URL=${env.PUBLIC_URL}, db=${env.DATABASE_NAME}, superuser=${env.POSTGRES_USER}, runtime role=${appRole} (non-superuser).`,
+  );
+  console.log(
+    "Secrets (POSTGRES_PASSWORD, app-role password, JWT_SECRET, ENCRYPTION_KEY) were written to the file, not printed.",
+  );
+}
+
+if (import.meta.main) {
+  await main();
+}

package/dist/skills/agents-onboarding/scripts/harbor-login.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+# Harbor (private registry) login on the VPS for the fazer.ai agents onboarding. Runs `docker login
+# --password-stdin` over SSH so the robot secret never lands in argv / ps / shell history, and the robot
+# username (which contains a "$", e.g. robot$project, a shell-expansion footgun, same family as the
+# Coolify token's "|") is decoded in-shell from base64 and passed quoted. The credential comes from the
+# hub MCP (create_registry_credential / generate_install_script); write the secret to a 0600 file and
+# pass --secret-file. Python 3 stdlib only. SSH runs via Bash with dangerouslyDisableSandbox:true.
+import argparse
+import base64
+import json
+import os
+import re
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+# Git Bash/MSYS on Windows reports paths as "/c/Users/..." (or "/mnt/c/..." under WSL), but native Python on
+# Windows cannot open those: it needs "C:\Users\...". Match a leading drive segment so we can retranslate.
+MSYS_DRIVE_RE = re.compile(r"^/(?:mnt/)?([A-Za-z])/(.*)$")
+
+
+def out(obj, code=0):
+    print(json.dumps(obj))
+    sys.exit(code)
+
+
+def fail(msg, **extra):
+    out({"ok": False, "error": msg, **extra}, code=1)
+
+
+def msys_to_native(path):
+    # Translate a Git Bash/MSYS/WSL path ("/c/Users/me/x", "/mnt/c/Users/me/x") to the native Windows form
+    # ("C:\Users\me\x") so open() finds it. Returns None when the path is not drive-prefixed (nothing to
+    # translate). POSIX paths and already-native Windows paths ("C:\...", "C:/...") are left to open() as-is.
+    m = MSYS_DRIVE_RE.match(path)
+    if not m:
+        return None
+    drive, rest = m.group(1), m.group(2)
+    return f"{drive.upper()}:\\" + rest.replace("/", "\\")
+
+
+def read_text_file(path, what):
+    # Read a UTF-8 text file, retrying a Git Bash/MSYS path ("/c/Users/me/x") as its native Windows form when
+    # the first open fails (same footgun as remote.py's --script-file). `what` names the flag for the error.
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except OSError as exc:
+        native = msys_to_native(path)
+        if native is None:
+            fail(f"cannot read {what}: {exc}")
+        try:
+            return Path(native).read_text(encoding="utf-8")
+        except OSError as exc2:
+            fail(f"cannot read {what} (tried {native!r}): {exc2}")
+
+
+def split_ssh_opts(opts, _nt=None):
+    # POSIX shlex eats backslashes, mangling a Windows key path ("-i C:\Users\me\.ssh\key" ->
+    # "C:Usersme.sshkey"). On Windows, tokenize without escape processing and strip our own quotes so the
+    # backslashes survive. _nt is injectable for tests.
+    nt = (os.name == "nt") if _nt is None else _nt
+    if not opts:
+        return []
+    if nt:
+        toks = shlex.split(opts, posix=False)
+        return [t[1:-1] if len(t) >= 2 and t[0] == t[-1] and t[0] in "\"'" else t for t in toks]
+    return shlex.split(opts)
+
+
+def cmd_login(args):
+    secret = read_text_file(args.secret_file, "--secret-file").strip()
+    if not secret:
+        fail("--secret-file is empty")
+    user_b64 = base64.b64encode(args.username.encode("utf-8")).decode("ascii")
+    secret_b64 = base64.b64encode(secret.encode("utf-8")).decode("ascii")
+    # Decode the username in-shell (protects the "$") and feed the secret via --password-stdin.
+    remote = (
+        f"U=$(echo '{user_b64}' | base64 -d); "
+        f"echo '{secret_b64}' | base64 -d | docker login -u \"$U\" --password-stdin {args.registry}"
+    )
+    argv = ["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=15", *split_ssh_opts(args.ssh_opts), args.ssh, remote]
+    try:
+        proc = subprocess.run(argv, capture_output=True, text=True, timeout=args.timeout)
+    except FileNotFoundError:
+        fail("ssh not found on PATH")
+    except subprocess.TimeoutExpired:
+        fail(f"ssh timed out after {args.timeout}s")
+    combined = (proc.stdout or "") + (proc.stderr or "")
+    if proc.returncode != 0 or "Login Succeeded" not in combined:
+        fail("docker login failed", exit_code=proc.returncode, stderr=(proc.stderr or "")[-400:])
+    out({"ok": True, "registry": args.registry, "result": "Login Succeeded"})
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="harbor-login.py",
+        description="docker login to a private registry on the VPS; secret via stdin, robot '$' protected.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    login = sub.add_parser("login", help="docker login over SSH (secret via --password-stdin)")
+    login.add_argument("--ssh", required=True, metavar="USER@HOST")
+    login.add_argument("--username", required=True, help="robot account, e.g. 'robot$project+name'")
+    login.add_argument("--secret-file", required=True, help="file holding the robot secret (chmod 600)")
+    login.add_argument("--registry", default="harbor.fazer.ai")
+    login.add_argument("--ssh-opts", default="", help="extra ssh options, e.g. '-i ~/.ssh/key -p 2222'")
+    login.add_argument("--timeout", type=int, default=60)
+    login.set_defaults(fn=cmd_login)
+    return parser
+
+
+def main():
+    args = build_parser().parse_args()
+    args.fn(args)
+
+
+if __name__ == "__main__":
+    main()

package/dist/skills/agents-onboarding/scripts/langfuse-verify.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+# Langfuse ingestion smoke test for the fazer.ai agents onboarding. POSTs a tiny batch to
+# /api/public/ingestion with HTTP Basic auth and asserts 207/200, NOT 500. This is the load-bearing
+# check: a naive "test connection" hits /api/public/projects, which reads only Postgres and returns 200
+# even when blob storage (MinIO/S3) is missing, masking a broken ingestion that silently drops every
+# trace. The Langfuse keys come from --keys-file (JSON {publicKey, secretKey}); the secret key never
+# touches argv. Python 3 stdlib only.
+import argparse
+import base64
+import json
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+# Git Bash/MSYS on Windows reports paths as "/c/Users/..." (or "/mnt/c/..." under WSL), but native Python on
+# Windows cannot open those: it needs "C:\Users\...". Match a leading drive segment so we can retranslate.
+MSYS_DRIVE_RE = re.compile(r"^/(?:mnt/)?([A-Za-z])/(.*)$")
+
+BATCH = {
+    "batch": [
+        {
+            "id": "verify-1",
+            "type": "trace-create",
+            "timestamp": "2026-01-01T00:00:00.000Z",
+            "body": {"id": "verify-1", "name": "onboarding-verify"},
+        }
+    ]
+}
+
+
+def out(obj, code=0):
+    print(json.dumps(obj))
+    sys.exit(code)
+
+
+def fail(msg, **extra):
+    out({"ok": False, "error": msg, **extra}, code=1)
+
+
+def msys_to_native(path):
+    # Translate a Git Bash/MSYS/WSL path ("/c/Users/me/x", "/mnt/c/Users/me/x") to the native Windows form
+    # ("C:\Users\me\x") so open() finds it. Returns None when the path is not drive-prefixed (nothing to
+    # translate). POSIX paths and already-native Windows paths ("C:\...", "C:/...") are left to open() as-is.
+    m = MSYS_DRIVE_RE.match(path)
+    if not m:
+        return None
+    drive, rest = m.group(1), m.group(2)
+    return f"{drive.upper()}:\\" + rest.replace("/", "\\")
+
+
+def read_text_file(path, what):
+    # Read a UTF-8 text file, retrying a Git Bash/MSYS path ("/c/Users/me/x") as its native Windows form when
+    # the first open fails (same footgun as remote.py's --script-file). `what` names the flag for the error.
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except OSError as exc:
+        native = msys_to_native(path)
+        if native is None:
+            fail(f"cannot read {what}: {exc}")
+        try:
+            return Path(native).read_text(encoding="utf-8")
+        except OSError as exc2:
+            fail(f"cannot read {what} (tried {native!r}): {exc2}")
+
+
+def cmd_ingestion(args):
+    try:
+        keys = json.loads(read_text_file(args.keys_file, "--keys-file"))
+    except ValueError as exc:
+        fail(f"--keys-file is not valid JSON (expects {{publicKey, secretKey}}): {exc}")
+    public_key, secret_key = keys.get("publicKey"), keys.get("secretKey")
+    if not public_key or not secret_key:
+        fail("--keys-file must hold both publicKey and secretKey")
+    url = args.base_url.rstrip("/") + "/api/public/ingestion"
+    auth = base64.b64encode(f"{public_key}:{secret_key}".encode("utf-8")).decode("ascii")
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(BATCH).encode("utf-8"),
+        method="POST",
+        headers={"Authorization": "Basic " + auth, "Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=args.timeout) as resp:
+            status, raw = resp.status, resp.read().decode("utf-8", "replace")
+    except urllib.error.HTTPError as exc:
+        status, raw = exc.code, exc.read().decode("utf-8", "replace")
+    except urllib.error.URLError as exc:
+        fail(f"request failed: {exc.reason}", url=url)
+    ok = status in (200, 207)
+    result = {"ok": ok, "status": status, "expected": "207/200", "body": raw[:300]}
+    if not ok:
+        result["hint"] = "500 usually means missing MinIO/S3 blob storage (LANGFUSE_S3_* empty); traces are dropped"
+    out(result, code=0 if ok else 1)
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="langfuse-verify.py",
+        description="Verify Langfuse ingestion actually works (207/200, not the masked 500).",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    ing = sub.add_parser("ingestion", help="POST a tiny batch to /api/public/ingestion and assert 207/200")
+    ing.add_argument("--base-url", required=True, metavar="URL", help="e.g. https://langfuse.example.com:3000")
+    ing.add_argument("--keys-file", required=True, help="JSON file with {publicKey, secretKey} (chmod 600)")
+    ing.add_argument("--timeout", type=int, default=30)
+    ing.set_defaults(fn=cmd_ingestion)
+    return parser
+
+
+def main():
+    args = build_parser().parse_args()
+    args.fn(args)
+
+
+if __name__ == "__main__":
+    main()

package/dist/skills/agents-onboarding/scripts/portainer-brownfield.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+# Portainer brownfield discovery (read-only): inventory the existing Portainer + its containers,
+# fingerprint each by image, and decide per-service (reuse healthy / install missing / flag incompatible)
+# for the fazer.ai agents onboarding. Mirror of the Coolify brownfield-probe.sh, but Portainer-API-native.
+# Env: PORTAINER_API_KEY, PORTAINER_ENDPOINT_ID, optional PORTAINER_URL (default https://localhost:9443).
+import json, ssl, os, urllib.request
+
+B = os.environ.get("PORTAINER_URL", "https://localhost:9443")
+API = os.environ["PORTAINER_API_KEY"]
+EP = os.environ.get("PORTAINER_ENDPOINT_ID", "1")
+ctx = ssl.create_default_context()
+ctx.check_hostname = False
+ctx.verify_mode = ssl.CERT_NONE
+
+
+def get(path):
+    req = urllib.request.Request(B + path, headers={"X-API-Key": API})
+    return json.loads(urllib.request.urlopen(req, context=ctx, timeout=30).read())
+
+
+# image substring -> logical service name (order matters: most specific first)
+FINGERPRINTS = [
+    ("agents", "agents"),
+    ("chatwoot-pro", "chatwoot-pro"),
+    ("chatwoot", "chatwoot-oss"),
+    ("langfuse", "langfuse"),
+    ("baileys", "baileys"),
+    ("pgvector", "postgres-pgvector"),
+    ("postgres", "postgres"),
+    ("clickhouse", "clickhouse"),
+    ("redis", "redis"),
+    ("minio", "minio"),
+    ("caddy", "proxy-caddy"),
+    ("traefik", "proxy-traefik"),
+    ("nginx", "proxy-nginx"),
+    ("haproxy", "proxy-haproxy"),
+    ("portainer", "portainer"),
+]
+
+
+def fingerprint(image):
+    il = image.lower()
+    for key, name in FINGERPRINTS:
+        if key in il:
+            return name
+    return "unknown:" + image.split("/")[-1]
+
+
+def health_of(state, status):
+    if "healthy" in status:
+        return "healthy"
+    if "health: starting" in status:
+        return "starting"
+    return state
+
+
+stacks = get("/api/stacks")
+conts = get("/api/endpoints/%s/docker/containers/json?all=1" % EP)
+
+print("=== Portainer-managed stacks ===")
+for s in stacks:
+    print("  #%s %-16s status=%s type=%s" % (s["Id"], s["Name"], s.get("Status"), s.get("Type")))
+
+print("\n=== Containers (image fingerprint) ===")
+inv = {}
+for c in conts:
+    name = fingerprint(c["Image"])
+    proj = c.get("Labels", {}).get("com.docker.compose.project", "-")
+    h = health_of(c["State"], c["Status"])
+    inv.setdefault(name, []).append({"proj": proj, "health": h, "image": c["Image"]})
+    print("  %-18s proj=%-18s %s" % (name, proj, c["Status"]))
+
+print("\n=== Ingress: who publishes 80/443/9443 ===")
+ingress = []
+for c in conts:
+    pubs = sorted({p.get("PublicPort") for p in c.get("Ports", []) if p.get("PublicPort") in (80, 443, 9443)})
+    if pubs:
+        nm = c["Names"][0].lstrip("/")
+        ingress.append((nm, pubs, fingerprint(c["Image"])))
+        print("  %-34s -> %s (%s)" % (nm, pubs, fingerprint(c["Image"])))
+proxy_on_443 = any(80 in p or 443 in p for _, p, _ in ingress)
+print("  => 80/443 %s" % ("OCCUPIED (an ingress exists; agents's bundled-Caddy stack would conflict -> reuse it or use docker-compose.prod.yml BYO-proxy)" if proxy_on_443 else "FREE (bundled-Caddy stack can bind)"))
+
+
+def decide(service):
+    hits = inv.get(service, [])
+    if not hits:
+        return "ABSENT -> install"
+    healthy = [h for h in hits if h["health"] == "healthy"]
+    if healthy:
+        return "PRESENT+healthy -> REUSE (proj=%s)" % healthy[0]["proj"]
+    return "PRESENT+unhealthy -> flag/investigate (%s)" % [h["health"] for h in hits]
+
+
+print("\n=== Per-service decision for the agents onboarding ===")
+# Chatwoot has TWO valid variants: chatwoot-pro (Harbor image, hub subscription) and chatwoot OSS
+# (public image). Both satisfy the agents integration (Agent Bot API). Pro adds Baileys WhatsApp + Kanban.
+# So OSS is REUSABLE, not incompatible; an absent Chatwoot installs pro-if-subscribed else oss.
+def decide_chatwoot():
+    pro = [h for h in inv.get("chatwoot-pro", []) if h["health"] == "healthy"]
+    oss = [h for h in inv.get("chatwoot-oss", []) if h["health"] == "healthy"]
+    if pro:
+        return "PRESENT(pro)+healthy -> REUSE (Baileys/Kanban available)"
+    if oss:
+        return "PRESENT(oss)+healthy -> REUSE (OSS; no Baileys/Kanban, use official WA channels)"
+    if inv.get("chatwoot-pro") or inv.get("chatwoot-oss"):
+        return "PRESENT+unhealthy -> flag/investigate"
+    return "ABSENT -> install (pro if hub subscription, else oss)"
+TARGETS = [
+    ("agents", decide("agents"), "required (the app)"),
+    ("chatwoot", decide_chatwoot(), "required (integration); pro=Harbor/hub-sub, oss=public"),
+    ("langfuse", decide("langfuse"), "optional (tracing)"),
+]
+for name, dec, note in TARGETS:
+    print("  %-16s %-46s | %s" % (name, dec, note))