paint_decoration_faces

        A deboss/emboss records which output triangles it created —
        recess floors and side-walls — in a face-provenance sidecar
        beside the decorated mesh.  This tool paints THOSE faces and
        nothing else, so a debossed logo with a closed outline (any
        mark with enclosed regions) colors only its carved strokes:
        the untouched surface island inside the outline stays the
        body color, where crease-angle segmentation would have
        "filled the logo in".

        Use after any decoration door (``decorate_surface``,
        ``apply_decoration``, ``apply_decoration_preset``,
        ``smart_decorate``, ``batch_decorate``…) — they all record
        the sidecar.  For meshes with no sidecar (older files,
        hand-made carves), fall back to ``segment_mesh_regions`` +
        ``paint_mesh_regions``.

        Writes a painted 3MF (one watertight object, per-triangle
        colors) via the same composer ``paint_mesh_regions`` uses,
        so the output slices identically.  A successful paint is
        also written back into the carve's face record (color,
        target, output file) so the design's provenance says
        "carved, then painted" — ``paint_recorded`` in the result
        reports whether that write-back landed.

        Says whether its colours are on the printer, as
        ``colour_availability`` (absent when Kiln cannot see what is
        loaded).  Relay its ``say`` as written and add nothing about
        filament: never suggest buying filament unless the person asks
        for one or says yes to the offer in ``say``.  On a yes, call
        ``find_closest_filaments`` with these colours and the print's
        material.

        :param model_path: The decorated mesh (STL/OBJ/3MF) whose
            ``<mesh>.decoration_faces.json`` sidecar to consume.
        :param color: Hex color for the carved faces (default red).
        :param base_color: Optional hex color for every other face.
            Empty = uncolored (renders neutral; slicer maps it to
            the base filament).
        :param target: ``"all"`` carved faces (default), or
            ``"floors"`` / ``"walls"`` when the record carries the
            split — floors are the recess bottoms (the visible mark),
            walls the carved sides.
        :param step_colors: Per-decoration colors for a chained
            carve, e.g. ``{"0": "#F72323", "1": "#FFFFFF"}`` — keys
            are step indices from the record's ``decorations`` list
            (every result of this tool lists them).  When given it
            is the COMPLETE paint spec: only the named steps are
            painted, the rest stay base — so "name red, title left
            plain" is one call.  Incompatible with a floors/walls
            ``target``; ``color`` is ignored.
        :param output_path: Where to write the painted 3MF.  Default:
            beside the model as ``<name>_painted.3mf``.
        :param material: Optional material the part will be printed in
            (e.g. ``"PETG"``).  A spool on record in a clearly
            different material is then not named as one to load.
        :param printer_id: Optional supported printer model id for
            bed placement of the composed 3MF.
        :returns: Dict with ``output_path``, ``painted_triangles``,
            ``total_triangles``, and the composer's color summary.
            Refuses loudly — no painting — when the sidecar is
            missing, malformed, or STALE (mesh content changed since
            the decoration was recorded).