@remixmate/cli 0.9.72 → 0.9.74

package/skills/template-registry/scripts/list_templates.py

@@ -1,82 +1,82 @@
 #!/usr/bin/env python3
-"""
-template-registry CLI — list available video templates.
-
-Single source of truth: registry loading, caching and stable/beta status
-gating all live in ``registry_loader.py`` (the same module ``render-video``
-and ``gen-script`` import in-process). This entry point only adds the CLI
-surface — flag parsing, tag/aspect/language filtering, and table/JSON
-rendering — that used to be re-implemented in TypeScript
-(``src/handlers/template-bind.ts``). Deleting that handler removes the
-TS↔Python duplication; this is now the only place the list verb is realized.
-
-The DSL → TemplateBinding logic stays in ``match_template.py`` and is invoked
-in-process by ``render-video``; it is intentionally NOT exposed as a CLI verb.
-
-List vs. detail (why ``--json-output`` no longer dumps everything):
-  A registry row is 4–17 KB of JSON (customPayloadSchema + slotMapping +
-  variants dominate), so ``--list-templates --json-output`` over a real
-  registry produced a six-figure-character blob. Every caller of this CLI is
-  an LLM tool call, and that blob overflowed the tool-result budget outright —
-  the agent got an "exceeds maximum allowed tokens" error instead of the
-  template definition it asked for, i.e. the mode that existed *to* read a
-  template's contract was the one mode that could never be read.
-
-  So the list verb emits **summaries** (identity + how to choose: name,
-  description, aspects, language, status, tags, variant ids, the capability
-  keys that drive authoring, a truncated llmHint) and ``--template-id <id>``
-  emits the **full definition** of the one
-  template the agent picked. That is the shape ``registry_loader``'s P1.2 note
-  already anticipated, realized CLI-side so it works before the backend
-  list/detail endpoints exist. ``--full`` still dumps whole definitions for
-  programmatic callers, guarded by a size check so it can't silently recreate
-  the overflow.
-
-Slide menu (why --template-id no longer returns every slideSchemas body):
-  slideSchemas is two thirds of a multi-layout template (html-slide: 24.6 K of
-  37.2 K chars, 26 layouts), while one video uses 5–9 layouts. Returning all of
-  it every time pushed the detail view past the agent's tool-result size cap
-  (the result got spilled to a file the agent cannot open, so it re-called
-  with other flags), and the agent re-read the whole thing on the next turn
-  anyway. So detail mode returns a per-layout *menu* — description, field
-  names, list key / item fields / maxItems, and whether narration must be
-  split into items — which is enough to choose layouts and draft a script;
-  ``--slide-id`` then returns the exact schemas of the chosen layouts for
-  writing ``templateData``. Registry consumers inside the pipeline (validator,
-  render) read the registry directly and are unaffected.
-
-Flags:
-  --list-templates                 (accepted; listing is the default verb)
-  --template-id <id>               print the FULL definition of this template
-                                   (repeatable); this is the detail verb.
-                                   Multi-layout templates come back with a
-                                   slideSchemas *menu* (see "Slide menu" below)
-  --slide-id <slideId|all>         detail mode: expand these layouts' full
-                                   templateData schemas (repeatable)
-  --full                           in list mode, emit full definitions instead
-                                   of summaries (size-guarded; prefer
-                                   --template-id)
-  --list-examples                  list *.dsl.json / *.binding.json reference
-                                   examples grouped by templateId (consumed
-                                   by downstream agents that want to read a
-                                   template's reference shape before producing
-                                   new DSL)
-  --filter-tag <substr>            keep templates whose styleTags match
-  --filter-aspect <ratio>          keep templates supporting this aspect ratio
-  --filter-language <zh|en|...>    keep templates tagged with this content lang
-                                   (templates with no contentLanguage are kept)
-  --include-beta                   also show beta templates (else stable-only)
-  --json-output                    emit {"templates": [...]} or {"examples": [...]}
-                                   instead of a table
-  --open <id>                      print the template's web detail page URL
-                                   (samples, layouts); also opens the browser
-                                   when stdout is an interactive terminal
-
-Links & samples: list and detail views add each template's web detail-page
-link (registry document-level ``pageUrls``, falling back to the samples
-endpoint) and sample count (showcase_loader.py) when ab-api serves them; when
-it does not, the views are unchanged apart from one stderr warning.
-"""
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 from __future__ import annotations
 
@@ -86,9 +86,9 @@ import os
 import sys
 from pathlib import Path
 
-# When run as `python3 <skillDir>/scripts/list_templates.py`, this script's own
-# directory is sys.path[0], so the sibling shared modules import directly.
-from registry_loader import (  # noqa: E402
+
+
+from registry_loader import (
     EXIT_BACKEND_UNREACHABLE,
     EXIT_NOT_AUTHENTICATED,
     RegistryAuthError,
@@ -97,40 +97,109 @@ from registry_loader import (  # noqa: E402
     list_templates as load_visible_templates,
     registry_page_urls,
 )
-from showcase_loader import load_showcases, summarize_group  # noqa: E402
+from showcase_loader import load_showcases, summarize_group
+
+
 
-# Samples per template in list views (table count + JSON items). The detail
-# view (--template-id) returns up to _DETAIL_SHOWCASES.
 _LIST_SHOWCASES = 3
 _DETAIL_SHOWCASES = 20
 
-# Summary llmHint budget: enough to tell templates apart when choosing, far
-# short of the multi-KB authoring contract (read that with --template-id).
+
+
 _SUMMARY_HINT_CHARS = 200
 
-# Upper bound for a multi-template full dump (--full). ~60 K chars ≈ 20 K
-# tokens: still large, but inside a tool-result budget, and the message it
-# fails with names the flag that replaces it.
+
+
+
 _MAX_FULL_DUMP_CHARS = 60_000
 
 
-def _matches(tpl: dict, tag: str | None, aspect: str | None, language: str | None) -> bool:
+_PAYLOAD_STYLES = ("visual-overlay", "slide", "carousel-caption")
+
+
+def _caps(tpl: dict) -> dict:
+    caps = tpl.get("capabilities")
+    return caps if isinstance(caps, dict) else {}
+
+
+def _effective_payload_style(tpl: dict) -> str:
+
+
+    declared = _caps(tpl).get("payloadStyle")
+    if declared in _PAYLOAD_STYLES:
+        return declared
+    reqs = tpl.get("assetRequirements") or []
+    return "visual-overlay" if ("image" in reqs or "video" in reqs) else "slide"
+
+
+def _source_doc_kind(tpl: dict) -> str | None:
+    hydration = _caps(tpl).get("payloadHydration")
+    if isinstance(hydration, dict):
+        kind = hydration.get("docKind")
+        return str(kind).lower() if kind else "any"
+    return None
+
+
+def _exclusion_reasons(
+    tpl: dict,
+    *,
+    tag: str | None = None,
+    aspect: str | None = None,
+    language: str | None = None,
+    user_media: str | None = None,
+    source_doc: str | None = None,
+    narration: str | None = None,
+) -> list[str]:
+
+
+
+
+
+
+    reasons: list[str] = []
     if tag:
         needle = tag.lower()
         tags = [str(t).lower() for t in (tpl.get("styleTags") or [])]
         if not any(needle in t or t in needle for t in tags):
-            return False
+            reasons.append(f"no styleTag matches {tag!r}")
     if aspect:
         want = aspect.lower()
         ratios = [str(r).lower() for r in (tpl.get("supportedAspectRatios") or [])]
         if want not in ratios:
-            return False
+            reasons.append(f"aspect ratio {aspect} not supported ({', '.join(ratios) or 'none declared'})")
     if language:
-        # Unknown language (absent/empty) is never excluded by a language filter.
+
         langs = [str(l).lower() for l in (tpl.get("contentLanguage") or [])]
         if langs and language.lower() not in langs:
-            return False
-    return True
+            reasons.append(f"content language {language} not supported ({', '.join(langs)})")
+
+    style = _effective_payload_style(tpl)
+    if user_media == "yes" and style == "slide":
+        reasons.append("no place for the user's own images/videos (payloadStyle=slide)")
+    if user_media == "no" and style == "carousel-caption":
+        reasons.append("needs the user's own images/videos (payloadStyle=carousel-caption)")
+
+    doc_kind = _source_doc_kind(tpl)
+    if source_doc:
+        want_doc = source_doc.lower()
+        if want_doc == "none":
+            if doc_kind is not None:
+                reasons.append("builds every scene from a source document the user has not given (capabilities.payloadHydration)")
+        elif doc_kind is None:
+            reasons.append(f"does not build scenes from a {want_doc} document")
+        elif doc_kind not in ("any", want_doc):
+            reasons.append(f"builds scenes from a {doc_kind} document, not {want_doc}")
+
+    needs_narration = _caps(tpl).get("needsNarration", True) is not False
+    if narration == "yes" and not needs_narration:
+        reasons.append("has no narration (capabilities.needsNarration=false)")
+    if narration == "no" and needs_narration:
+        reasons.append("is narration-driven (needsNarration is not false)")
+    return reasons
+
+
+def _matches(tpl: dict, tag: str | None, aspect: str | None, language: str | None) -> bool:
+    return not _exclusion_reasons(tpl, tag=tag, aspect=aspect, language=language)
 
 
 def _status_of(tpl: dict) -> str:
@@ -148,23 +217,25 @@ def _truncate(text: object, limit: int) -> str | None:
 
 
 def _summarize(tpl: dict) -> dict:
-    """The "choose a template" view: identity + selection criteria only.
 
-    Deliberately excludes the authoring contract (llmHint in full,
-    customPayloadSchema, slideSchemas, slotMapping, compositions, variants' style bodies) —
-    that is what ``--template-id`` returns, one template at a time.
-    """
+
+
+
+
+
     variants = tpl.get("variants")
-    # Only the scalar capability keys that change how a caller *drives* the
-    # template (narration vs typewriter caption, who decides duration). The
-    # rest of `capabilities` — payloadDefaults above all — is bulk that scales
-    # with the registry, so it stays in the detail view.
-    caps = tpl.get("capabilities") if isinstance(tpl.get("capabilities"), dict) else {}
+
+
+
+
+    caps = _caps(tpl)
     caps_summary = {
         k: caps[k]
-        for k in ("payloadStyle", "needsNarration", "durationStrategy", "narrationDriver")
+        for k in ("payloadStyle", "needsNarration", "durationStrategy", "narrationDriver", "sceneStrategy")
         if k in caps
     }
+    if (doc_kind := _source_doc_kind(tpl)) is not None:
+        caps_summary["sourceDocKind"] = doc_kind
     summary = {
         "templateId": tpl.get("templateId"),
         "name": tpl.get("name"),
@@ -177,6 +248,10 @@ def _summarize(tpl: dict) -> dict:
         "capabilities": caps_summary,
         "llmHintPreview": _truncate(tpl.get("llmHint"), _SUMMARY_HINT_CHARS),
     }
+
+
+    if isinstance(tpl.get("notFor"), str) and tpl["notFor"].strip():
+        summary["notFor"] = tpl["notFor"].strip()
     hint = tpl.get("llmHint")
     if isinstance(hint, str) and len(hint.strip()) > _SUMMARY_HINT_CHARS:
         summary["llmHintTruncated"] = True
@@ -184,30 +259,30 @@ def _summarize(tpl: dict) -> dict:
 
 
 def _open_in_browser(url: str) -> None:
-    """Best-effort browser open after the URL has already been printed.
 
-    Only when stdout is a TTY (a human at a terminal) and REMIXMATE_NO_BROWSER
-    is unset: agent hosts run commands through pipes / sandboxes, where the
-    printed URL is what they relay to the user. Failures are swallowed.
-    """
+
+
+
+
+
     if not sys.stdout.isatty() or os.environ.get("REMIXMATE_NO_BROWSER", "").strip():
         return
     try:
         import webbrowser
 
         webbrowser.open(url, new=2)
-    except Exception:  # noqa: BLE001
+    except Exception:
         pass
 
 
 def _page_url(template_id: object, page_urls: dict[str, str], groups: dict | None) -> str | None:
-    """Web detail page link for one template.
 
-    The registry's document-level ``pageUrls`` comes first: it rides on the call
-    every list makes anyway, so the link survives the samples endpoint being
-    down. The samples group's ``pageUrl`` is the fallback (same URL, built by
-    the same backend helper).
-    """
+
+
+
+
+
+
     if not isinstance(template_id, str):
         return None
     if page_urls.get(template_id):
@@ -219,9 +294,9 @@ def _page_url(template_id: object, page_urls: dict[str, str], groups: dict | Non
 
 def _report_unknown_ids(missing: list[str], templates: list[dict]) -> None:
     for tid in missing:
-        # Distinguish "gated out by status" from "does not exist" —
-        # otherwise a beta template reads as a typo and the caller
-        # retries the id instead of passing --include-beta.
+
+
+
         gated = get_template(tid, include_all_statuses=True)
         if gated is not None:
             print(
@@ -243,7 +318,7 @@ def _detail_hint(template_id: str = "<templateId>") -> str:
     )
 
 
-# ----- Slide menu (--template-id without --slide-id) -------------------------
+
 
 _SLIDE_EXPAND_ALL = "all"
 
@@ -256,7 +331,7 @@ def _slide_schema_ids(tpl: dict) -> list[str]:
 
 
 def _menu_entry(schema: dict, line_sync_key: str | None) -> dict:
-    """One layout's menu row: enough to pick it and draft a script, not to fill it."""
+
     props = schema.get("properties") if isinstance(schema.get("properties"), dict) else {}
     entry: dict = {}
     if schema.get("description"):
@@ -264,7 +339,7 @@ def _menu_entry(schema: dict, line_sync_key: str | None) -> dict:
     entry["fields"] = list(props.keys())
     if schema.get("required"):
         entry["required"] = schema["required"]
-    # The card list: the line-sync key when declared, else the first array of objects.
+
     list_key = line_sync_key if line_sync_key in props else None
     if list_key is None:
         for k, v in props.items():
@@ -283,8 +358,8 @@ def _menu_entry(schema: dict, line_sync_key: str | None) -> dict:
             lst["maxItems"] = arr["maxItems"]
         entry["list"] = lst
     if line_sync_key:
-        # The single most expensive miss in practice: authoring one narration
-        # block for a layout that lights cards one by one (validator rejects it).
+
+
         entry["narration"] = (
             f"items — one audio.narration.items line per templateData.{line_sync_key} entry, no text"
         )
@@ -295,7 +370,7 @@ def _menu_entry(schema: dict, line_sync_key: str | None) -> dict:
 
 
 def _apply_slide_view(tpl: dict, slide_ids: list[str] | None) -> dict:
-    """Return tpl with slideSchemas reduced to a menu, or to the requested layouts."""
+
     ss = tpl.get("slideSchemas")
     if not isinstance(ss, dict):
         return tpl
@@ -333,20 +408,20 @@ def _apply_slide_view(tpl: dict, slide_ids: list[str] | None) -> dict:
     return out
 
 
-# ----- Examples discovery (--list-examples) ---------------------------------
-#
-# Examples live under <SkillDir>/video_dsl/schema/examples/ as `*.dsl.json` and
-# `*.binding.json` files. Naming convention (per gen-script SKILL.md) is
-# `<templateId>.dsl.json` / `<templateId>.binding.json`, occasionally with
-# variant suffixes (`<templateId>.<variant>.dsl.json`).
-#
-# We do not parse the JSON content here (downstream agents read the raw files
-# they care about); we just enumerate paths so the agent doesn't have to guess
-# the directory layout. When the directory does not exist (e.g. inside a slim
-# package distribution), we return an empty list — non-fatal.
-
-# Resolve the examples directory relative to this script.
-#   <skill>/scripts/list_templates.py  →  <skill>/video_dsl/schema/examples/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 _EXAMPLES_DIR = Path(__file__).resolve().parent.parent / "video_dsl" / "schema" / "examples"
 
 
@@ -358,7 +433,7 @@ def _collect_examples() -> list[dict]:
         if not entry.is_file():
             continue
         name = entry.name
-        # Recognise *.dsl.json / *.binding.json
+
         if name.endswith(".dsl.json"):
             kind = "dsl"
             base = name[: -len(".dsl.json")]
@@ -367,7 +442,7 @@ def _collect_examples() -> list[dict]:
             base = name[: -len(".binding.json")]
         else:
             continue
-        # Variant: 'foo.bar.dsl.json' → templateId='foo', variant='bar'
+
         if "." in base:
             template_id, variant = base.split(".", 1)
         else:
@@ -376,7 +451,7 @@ def _collect_examples() -> list[dict]:
         bucket["files"].append({
             "kind": kind,
             "variant": variant,
-            "path": str(entry.relative_to(_EXAMPLES_DIR.parent.parent.parent)),  # relative to skill dir
+            "path": str(entry.relative_to(_EXAMPLES_DIR.parent.parent.parent)),
             "absolutePath": str(entry),
             "sizeBytes": entry.stat().st_size,
         })
@@ -402,6 +477,14 @@ def main() -> None:
     ap.add_argument("--filter-tag", help="Keep templates whose styleTags match this substring.")
     ap.add_argument("--filter-aspect", help="Keep templates supporting this aspect ratio (e.g. 9:16).")
     ap.add_argument("--filter-language", help="Keep templates tagged with this content language (zh|en|...).")
+    ap.add_argument("--user-media", choices=("yes", "no"),
+                    help="Shortlist: yes = the user handed over their own images/videos (drop templates "
+                         "with nowhere to put them); no = they did not (drop templates that need them).")
+    ap.add_argument("--source-doc", metavar="KIND",
+                    help="Shortlist: the user gave a source document of this kind (e.g. pptx) — keep only "
+                         "templates that build scenes from one; 'none' drops those templates.")
+    ap.add_argument("--narration", choices=("yes", "no"),
+                    help="Shortlist: yes = the video needs voice-over; no = the user wants none.")
     ap.add_argument("--include-beta", action="store_true", help="Also show beta templates (default: stable only).")
     ap.add_argument("--json-output", action="store_true", help='Emit JSON ({"templates":[...]} or {"examples":[...]}) instead of a table.')
     ap.add_argument("--open", dest="open_id", metavar="ID",
@@ -412,28 +495,28 @@ def main() -> None:
     if args.open_id and (args.template_ids or args.list_examples or args.list_templates):
         ap.error("--open cannot be combined with --template-id / --list-examples / --list-templates")
 
-    # --include-beta flips registry_loader's documented status gate via env, so
-    # the CLI and in-process callers share one gating implementation.
+
+
     if args.include_beta:
         os.environ["ENABLE_BETA_TEMPLATES"] = "1"
 
-    # ----- examples mode -----------------------------------------------------
+
     if args.list_examples:
         examples = _collect_examples()
         if args.json_output:
             print(json.dumps({"examples": examples}, ensure_ascii=False))
             return
         if not examples:
-            # 这**不是**异常状态,而是常态:该目录从未进过仓库,也就从未随包发布过。
-            #
-            # 旧文案("This package may have shipped without reference examples;
-            # check the cli source repo or upgrade @remixmate/cli")把常态说成了事故,
-            # 而 gen-script 的 SKILL.md 又把「先读这里的参考 DSL」列为强制第一步 ——
-            # 于是线上 agent 每次都在这里撞空,然后退回 gen_script 的骨架照抄,连模板
-            # 自己声明的版式都不去看。升级 CLI 修不了它,因为没有哪一版带过这些文件。
-            #
-            # 真正随包到达调用方的逐模板契约是 registry 里的 template.json,所以这里
-            # 直接把人指过去,而不是让它以为"该模板不受支持"。
+
+
+
+
+
+
+
+
+
+
             print(
                 f"ℹ️  No local reference DSLs under {_EXAMPLES_DIR} — that directory is "
                 "optional and is not part of the published package.\n"
@@ -465,12 +548,12 @@ def main() -> None:
     try:
         templates = load_visible_templates()
     except RegistryAuthError as exc:
-        # 退出码 4 = 需要授权（见 registry_loader.EXIT_NOT_AUTHENTICATED），宿主
-        # 据此引导用户重新登录，而不是把它当成一次普通失败。
+
+
         print(f"❌ {exc}", file=sys.stderr)
         sys.exit(EXIT_NOT_AUTHENTICATED)
     except RegistryUnreachableError as exc:
-        # 退出码 5 = 后端不可达；重试或修配置即可，不需要重新登录。
+
         print(f"❌ {exc}", file=sys.stderr)
         sys.exit(EXIT_BACKEND_UNREACHABLE)
     except RuntimeError as exc:
@@ -480,10 +563,10 @@ def main() -> None:
     by_id = {t.get("templateId"): t for t in templates}
     page_urls = registry_page_urls()
 
-    # ----- open mode (--open) -------------------------------------------------
-    #
-    # The URL goes to stdout first, unconditionally: in Codex / Claude Code the
-    # command runs through a pipe and the printed link is what the agent relays.
+
+
+
+
     if args.open_id:
         if args.open_id not in by_id:
             _report_unknown_ids([args.open_id], templates)
@@ -502,11 +585,11 @@ def main() -> None:
         _open_in_browser(page_url)
         return
 
-    # ----- detail mode (--template-id) ---------------------------------------
-    #
-    # Explicit ids win over --filter-*: the caller already chose, and silently
-    # returning nothing because a stale filter excluded the pick would read as
-    # "template does not exist".
+
+
+
+
+
     if args.template_ids:
         picked: list[dict] = []
         missing: list[str] = []
@@ -536,13 +619,13 @@ def main() -> None:
                                   or s == _SLIDE_EXPAND_ALL] or None)
             for t in picked
         ]
-        # Always compact, with or without --json-output. Every caller is an LLM
-        # tool call: indent=2 nearly doubled the size (html-slide 37 K → 65 K
-        # chars), which alone pushed the plain call past the tool-result cap and
-        # got it spilled to a file the agent cannot read. Humans can `| jq`.
+
+
+
+
         detail: dict = {"templates": picked}
-        # Samples and links sit beside the definitions, never inside them: the
-        # definition is the template's authoring contract, these are web content.
+
+
         groups = load_showcases([str(t.get("templateId")) for t in picked], _DETAIL_SHOWCASES)
         links = {
             str(t.get("templateId")): url
@@ -558,10 +641,26 @@ def main() -> None:
         print(json.dumps(detail, ensure_ascii=False))
         return
 
-    visible = [
-        t for t in templates
-        if _matches(t, args.filter_tag, args.filter_aspect, args.filter_language)
-    ]
+    constraints = {
+        "tag": args.filter_tag,
+        "aspect": args.filter_aspect,
+        "language": args.filter_language,
+        "user_media": args.user_media,
+        "source_doc": args.source_doc,
+        "narration": args.narration,
+    }
+    filtering = any(v for v in constraints.values())
+    visible: list[dict] = []
+
+
+
+    excluded: list[dict] = []
+    for t in templates:
+        reasons = _exclusion_reasons(t, **constraints)
+        if reasons:
+            excluded.append({"templateId": t.get("templateId"), "name": t.get("name"), "reasons": reasons})
+        else:
+            visible.append(t)
 
     if args.json_output:
         if args.full:
@@ -584,25 +683,26 @@ def main() -> None:
             s = _summarize(t)
             if url := _page_url(t.get("templateId"), page_urls, groups):
                 s["pageUrl"] = url
-            # Absent (not null) when the endpoint is unavailable, so a consumer
-            # never mistakes "unknown" for "zero samples".
+
+
             if groups is not None and t.get("templateId") in groups:
                 s["showcases"] = summarize_group(groups[t["templateId"]], _LIST_SHOWCASES)
             summaries.append(s)
-        print(json.dumps(
-            {
-                "templates": summaries,
-                "detailHint": _detail_hint(),
-            },
-            ensure_ascii=False,
-        ))
+        listing: dict = {
+            "templates": summaries,
+            "detailHint": _detail_hint(),
+        }
+        if filtering:
+            listing["excluded"] = excluded
+        print(json.dumps(listing, ensure_ascii=False))
         return
 
     if not visible:
         print(
             "⚠️  No templates match the current filters "
-            "(check --include-beta or relax --filter-*).",
+            "(check --include-beta or relax --filter-* / --user-media / --source-doc / --narration).",
         )
+        _print_excluded(excluded)
         return
 
     groups = load_showcases([str(t.get("templateId")) for t in visible], _LIST_SHOWCASES)
@@ -627,8 +727,11 @@ def main() -> None:
         hint = _truncate(tpl.get("llmHint"), _SUMMARY_HINT_CHARS)
         if hint:
             print(f"{' ' * 22}   ↳ {hint}")
-        # Two lines, link on its own: an agent summarizing the table keeps a
-        # labelled `detail:` line, a URL trailing a count reads as an aside.
+        not_for = tpl.get("notFor")
+        if isinstance(not_for, str) and not_for.strip():
+            print(f"{' ' * 22}   ↳ not for: {not_for.strip()}")
+
+
         group = (groups or {}).get(tpl.get("templateId"))
         if group is not None:
             print(f"{' ' * 22}   ↳ samples: {int(group.get('showcaseCount') or 0)}")
@@ -644,6 +747,15 @@ def main() -> None:
     )
     if any_link:
         print(f"Watch samples / layouts in the browser: open a detail link, or --open {first_id}")
+    _print_excluded(excluded)
+
+
+def _print_excluded(excluded: list[dict]) -> None:
+    if not excluded:
+        return
+    print(f"\nExcluded by the current filters ({len(excluded)}):")
+    for item in excluded:
+        print(f"  {item.get('templateId')}: {'; '.join(item.get('reasons') or [])}")
 
 
 if __name__ == "__main__":