Normalize generated docs and asset naming

build/scripts/build_readme_impl.py

@@ -196,27 +196,88 @@ def build_markdown(records: list[dict[str, Any]]) -> str:
 
 
 def build_readme(records: list[dict[str, Any]]) -> str:
-    total_cases = sum(len(record["cases"]) for record in records)
+    namespaces = sorted(
+        {
+            case_namespace(case)
+            for record in records
+            for case in record["cases"]
+            if case_namespace(case)
+        }
+    )
     lines: list[str] = []
 
     lines.append("# Renameable Item Catalog")
     lines.append("")
     lines.append("Generated from the resource pack item model JSON.")
     lines.append("")
+    lines.append("## Namespace catalogs")
+    lines.append("")
+    for namespace in namespaces:
+        lines.append(f"- [renameable-items-{namespace}.md](build/renameable-items-{namespace}.md)")
+
+    lines.append("")
+    lines.append("Each namespace catalog is generated from the matching model namespace in the resource pack.")
+
+    return "\n".join(lines)
+
+
+def case_namespace(case: dict[str, Any]) -> str | None:
+    resolved = namespace_and_path(case["model"])
+    if resolved is None:
+        return None
+
+    return resolved[0]
+
+
+def build_namespace_catalog(records: list[dict[str, Any]], namespace: str) -> str:
+    namespace_records = [
+        record
+        for record in records
+        if any(case_namespace(case) == namespace for case in record["cases"])
+    ]
+    total_cases = sum(1 for record in namespace_records for case in record["cases"] if case_namespace(case) == namespace)
+    lines: list[str] = []
+
+    lines.append(f"# Renameable Item Catalog - {namespace}")
+    lines.append("")
+    lines.append("Generated from the resource pack item model JSON.")
+    lines.append("")
     lines.append("## Summary")
     lines.append("")
-    lines.append(f"- Base items: {len(records)}")
+    lines.append(f"- Base items: {len(namespace_records)}")
     lines.append(f"- Rename variants: {total_cases}")
-    lines.append("- Full catalog: [build/renameable-items.md](build/renameable-items.md)")
-    lines.append("")
-    lines.append("## Item Index")
+    lines.append("- Render mode: local Python renderer")
     lines.append("")
 
-    for record in records:
-        lines.append(f"- [{record['item']}](build/renameable-items.md#{record['item']})")
+    for record in namespace_records:
+        lines.append(f"## {record['item']}")
+        lines.append("")
+        lines.append(f"- Generated from: `{record['source_file']}`")
+        lines.append(f"- Fallback model: `{record['fallback_model']}`")
 
+        lines.append("")
+        lines.append("### Rename variants")
+        lines.append("")
+
+        namespace_cases = [case for case in record["cases"] if case_namespace(case) == namespace]
+
+        if not namespace_cases:
+            lines.append("- None found")
+            lines.append("")
+            continue
+
+        for case in namespace_cases:
+            if case["render_path"]:
+                lines.append(f"- `{case['when']}` -> `{case['model']}`")
+                lines.append(f"  - Preview: <img src=\"{case['render_path']}\" alt=\"{case['when']}\" width=\"160\" />")
+            else:
+                lines.append(f"- `{case['when']}` -> `{case['model']}` (not present yet)")
+
+        lines.append("")
+
+    lines.append("---")
     lines.append("")
-    lines.append("The linked catalog contains the generated item sections and rename variants.")
+    lines.append("This file is generated. Add your renderer output under the matching `renders/` paths to populate image previews later.")
 
     return "\n".join(lines)
 
@@ -423,8 +484,18 @@ def main() -> int:
     readme_path = Path(args.readme_path).resolve()
     readme_path.write_text(build_readme(records), encoding="utf-8")
 
-    catalog_path = output_dir / "renameable-items.md"
-    catalog_path.write_text(build_markdown(records), encoding="utf-8")
+    namespace_names = sorted(
+        {
+            case_namespace(case)
+            for record in records
+            for case in record["cases"]
+            if case_namespace(case)
+        }
+    )
+
+    for namespace in namespace_names:
+        namespace_catalog = build_namespace_catalog(records, namespace)
+        (output_dir / f"renameable-items-{namespace}.md").write_text(namespace_catalog, encoding="utf-8")
 
     if args.copy_renders:
         copy_existing_renders(pack_root, output_dir)