Sync from simready-oem-library-pm@c858e9dd

Dockerfile

@@ -1,112 +1,112 @@
-# SimReady Validator — HuggingFace Space image
-#
-# Base: nvcr.io/nvidia/isaac-sim:4.5.0. Ships Kit at /isaac-sim/ so
-# runner._kit_available() auto-selects --use-kit and the validator
-# runs PhysX / MDL rules without a code change.
-#
-# UID 1000 is required by HF Spaces. The Isaac Sim base already has
-# a user at UID 1000 (varies between releases — ubuntu / kit / etc.),
-# so we REUSE it rather than create one. /app is the workspace dir
-# with HOME=/app so Claude Code CLI finds skills under ~/.claude/skills
-# regardless of the existing user's name.
-
-FROM nvcr.io/nvidia/isaac-sim:4.5.0
-
-# Skip interactive prompts during apt-get (the deadsnakes PPA install
-# pulls tzdata in as a dep, which otherwise blocks the build asking
-# for a geographic area).
-ENV DEBIAN_FRONTEND=noninteractive
-ENV TZ=Etc/UTC
-
-# System deps (Ubuntu 22.04). Isaac Sim base may ship apt/pip configs
-# pointing at NVIDIA-internal mirrors (urm.nvidia.com) that HF Spaces'
-# build infra can't reach — wipe those before any install. The base
-# default Python is 3.10; simready-validate requires >=3.11, so we
-# install python3.11 from the deadsnakes PPA and use it explicitly
-# for everything below.
-RUN apt-get update && apt-get install -y --no-install-recommends \
-        git curl ca-certificates rsync gnupg software-properties-common \
-    && add-apt-repository -y ppa:deadsnakes/ppa \
-    && apt-get update && apt-get install -y --no-install-recommends \
-        python3.11 python3.11-venv python3.11-distutils \
-    && curl -fsSL https://bootstrap.pypa.io/get-pip.py | python3.11 \
-    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
-    && apt-get install -y --no-install-recommends nodejs \
-    && rm -rf /var/lib/apt/lists/*
-
-RUN npm config set registry https://registry.npmjs.org/ \
-    && rm -f /root/.npmrc /etc/npmrc \
-    && rm -f /root/.pip/pip.conf /etc/pip.conf
-
-# Claude Code CLI.
-RUN npm install -g --registry=https://registry.npmjs.org/ \
-        @anthropic-ai/claude-code@latest
-
-# Workspace nesting matches the legacy layout (/home/appuser/app)
-# because runner.py uses Path(__file__).resolve().parents[2] to find
-# tools/spec_sync/state.json — needs at least 3 levels of parent.
-# We don't create the appuser account (UID 1000 already exists in the
-# base image with a different name); we just use the path. HOME points
-# at the workspace's parent so Claude Code CLI finds ~/.claude/skills.
-RUN mkdir -p /home/appuser/app /home/appuser/.claude/skills
-WORKDIR /home/appuser/app
-ENV HOME=/home/appuser
-
-# Python deps (system Python, public PyPI). --break-system-packages
-# because Ubuntu 22.04 marks system Python as PEP-668 externally-
-# managed; on a build-once container image that's the right trade-off.
-COPY tools/hf_space/requirements.txt ./requirements.txt
-RUN python3.11 -m pip install --no-cache-dir --break-system-packages \
-        --index-url https://pypi.org/simple/ \
-        -r requirements.txt
-
-# Foundation specs.
-ENV SIMREADY_FOUNDATIONS_PATH=/opt/simready_foundations
-ENV SIMREADY_FOUNDATIONS_COMMIT=805d2c50179a9878c89b0f41baaa0ecafe47c3d7
-RUN git clone https://github.com/NVIDIA/simready-foundation \
-        ${SIMREADY_FOUNDATIONS_PATH} \
-    && cd ${SIMREADY_FOUNDATIONS_PATH} \
-    && git checkout ${SIMREADY_FOUNDATIONS_COMMIT}
-
-# Vendored simready-foundation-core wheel.
-COPY tools/hf_space/wheels/simready_foundation_core-0.2.0a1-py3-none-any.whl /tmp/
-RUN python3.11 -m pip install --no-cache-dir --break-system-packages \
-        --index-url https://pypi.org/simple/ \
-        /tmp/simready_foundation_core-0.2.0a1-py3-none-any.whl \
-    && rm /tmp/simready_foundation_core-0.2.0a1-py3-none-any.whl
-
-# Validator + Space code.
-COPY tools/validation /home/appuser/app/tools/validation
-COPY tools/hf_space/app.py     ./app.py
-COPY tools/hf_space/runner.py  ./runner.py
-COPY tools/hf_space/github_issues.py ./github_issues.py
-COPY tools/hf_space/agentic_issues.py ./agentic_issues.py
-COPY README.md ./README.md
-COPY VALIDATE.md ./VALIDATE.md
-
-# Claude Code skills (HOME=/home/appuser → ~/.claude/skills).
-COPY tools/hf_space/skills/simready-validator-agent /home/appuser/.claude/skills/simready-validator-agent
-COPY tools/validation/plugins/simready-report/skills/simready-report /home/appuser/.claude/skills/simready-report
-
-# UID 1000 owns the workspace + foundation clone.
-RUN chown -R 1000:1000 /home/appuser ${SIMREADY_FOUNDATIONS_PATH}
-
-# runner._kit_available() probes /isaac-sim/python.sh — present in the
-# base image — so the validator auto-selects --use-kit at runtime.
-# The validator's --use-kit path needs to know WHERE Kit's python lives;
-# wire it via SIMREADY_KIT_PYTHON so the auto-detect is fully self-
-# configuring (no per-call --kit-python flag needed).
-ENV SIMREADY_KIT_PYTHON=/isaac-sim/python.sh
-
-USER 1000:1000
-
-ENV GRADIO_SERVER_NAME=0.0.0.0
-ENV GRADIO_SERVER_PORT=7860
-EXPOSE 7860
-
-# Clear the Isaac Sim base's ENTRYPOINT (it runs /isaac-sim/runheadless.sh
-# and treats CMD as its args — fails with 'Permission denied' under
-# UID 1000). We invoke the Python app directly; Kit is invoked
-# explicitly by the validator via /isaac-sim/python.sh when needed.
-ENTRYPOINT []
-CMD ["python3.11", "app.py"]
+# SimReady Validator — HuggingFace Space image
+#
+# Base: nvcr.io/nvidia/isaac-sim:4.5.0. Ships Kit at /isaac-sim/ so
+# runner._kit_available() auto-selects --use-kit and the validator
+# runs PhysX / MDL rules without a code change.
+#
+# UID 1000 is required by HF Spaces. The Isaac Sim base already has
+# a user at UID 1000 (varies between releases — ubuntu / kit / etc.),
+# so we REUSE it rather than create one. /app is the workspace dir
+# with HOME=/app so Claude Code CLI finds skills under ~/.claude/skills
+# regardless of the existing user's name.
+
+FROM nvcr.io/nvidia/isaac-sim:4.5.0
+
+# Skip interactive prompts during apt-get (the deadsnakes PPA install
+# pulls tzdata in as a dep, which otherwise blocks the build asking
+# for a geographic area).
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TZ=Etc/UTC
+
+# System deps (Ubuntu 22.04). Isaac Sim base may ship apt/pip configs
+# pointing at NVIDIA-internal mirrors (urm.nvidia.com) that HF Spaces'
+# build infra can't reach — wipe those before any install. The base
+# default Python is 3.10; simready-validate requires >=3.11, so we
+# install python3.11 from the deadsnakes PPA and use it explicitly
+# for everything below.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git curl ca-certificates rsync gnupg software-properties-common \
+    && add-apt-repository -y ppa:deadsnakes/ppa \
+    && apt-get update && apt-get install -y --no-install-recommends \
+        python3.11 python3.11-venv python3.11-distutils \
+    && curl -fsSL https://bootstrap.pypa.io/get-pip.py | python3.11 \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN npm config set registry https://registry.npmjs.org/ \
+    && rm -f /root/.npmrc /etc/npmrc \
+    && rm -f /root/.pip/pip.conf /etc/pip.conf
+
+# Claude Code CLI.
+RUN npm install -g --registry=https://registry.npmjs.org/ \
+        @anthropic-ai/claude-code@latest
+
+# Workspace nesting matches the legacy layout (/home/appuser/app)
+# because runner.py uses Path(__file__).resolve().parents[2] to find
+# tools/spec_sync/state.json — needs at least 3 levels of parent.
+# We don't create the appuser account (UID 1000 already exists in the
+# base image with a different name); we just use the path. HOME points
+# at the workspace's parent so Claude Code CLI finds ~/.claude/skills.
+RUN mkdir -p /home/appuser/app /home/appuser/.claude/skills
+WORKDIR /home/appuser/app
+ENV HOME=/home/appuser
+
+# Python deps (system Python, public PyPI). --break-system-packages
+# because Ubuntu 22.04 marks system Python as PEP-668 externally-
+# managed; on a build-once container image that's the right trade-off.
+COPY tools/hf_space/requirements.txt ./requirements.txt
+RUN python3.11 -m pip install --no-cache-dir --break-system-packages \
+        --index-url https://pypi.org/simple/ \
+        -r requirements.txt
+
+# Foundation specs.
+ENV SIMREADY_FOUNDATIONS_PATH=/opt/simready_foundations
+ENV SIMREADY_FOUNDATIONS_COMMIT=805d2c50179a9878c89b0f41baaa0ecafe47c3d7
+RUN git clone https://github.com/NVIDIA/simready-foundation \
+        ${SIMREADY_FOUNDATIONS_PATH} \
+    && cd ${SIMREADY_FOUNDATIONS_PATH} \
+    && git checkout ${SIMREADY_FOUNDATIONS_COMMIT}
+
+# Vendored simready-foundation-core wheel.
+COPY tools/hf_space/wheels/simready_foundation_core-0.2.0a1-py3-none-any.whl /tmp/
+RUN python3.11 -m pip install --no-cache-dir --break-system-packages \
+        --index-url https://pypi.org/simple/ \
+        /tmp/simready_foundation_core-0.2.0a1-py3-none-any.whl \
+    && rm /tmp/simready_foundation_core-0.2.0a1-py3-none-any.whl
+
+# Validator + Space code.
+COPY tools/validation /home/appuser/app/tools/validation
+COPY tools/hf_space/app.py     ./app.py
+COPY tools/hf_space/runner.py  ./runner.py
+COPY tools/hf_space/github_issues.py ./github_issues.py
+COPY tools/hf_space/agentic_issues.py ./agentic_issues.py
+COPY README.md ./README.md
+COPY VALIDATE.md ./VALIDATE.md
+
+# Claude Code skills (HOME=/home/appuser → ~/.claude/skills).
+COPY tools/hf_space/skills/simready-validator-agent /home/appuser/.claude/skills/simready-validator-agent
+COPY tools/validation/plugins/simready-report/skills/simready-report /home/appuser/.claude/skills/simready-report
+
+# UID 1000 owns the workspace + foundation clone.
+RUN chown -R 1000:1000 /home/appuser ${SIMREADY_FOUNDATIONS_PATH}
+
+# runner._kit_available() probes /isaac-sim/python.sh — present in the
+# base image — so the validator auto-selects --use-kit at runtime.
+# The validator's --use-kit path needs to know WHERE Kit's python lives;
+# wire it via SIMREADY_KIT_PYTHON so the auto-detect is fully self-
+# configuring (no per-call --kit-python flag needed).
+ENV SIMREADY_KIT_PYTHON=/isaac-sim/python.sh
+
+USER 1000:1000
+
+ENV GRADIO_SERVER_NAME=0.0.0.0
+ENV GRADIO_SERVER_PORT=7860
+EXPOSE 7860
+
+# Clear the Isaac Sim base's ENTRYPOINT (it runs /isaac-sim/runheadless.sh
+# and treats CMD as its args — fails with 'Permission denied' under
+# UID 1000). We invoke the Python app directly; Kit is invoked
+# explicitly by the validator via /isaac-sim/python.sh when needed.
+ENTRYPOINT []
+CMD ["python3.11", "app.py"]

README.md

@@ -1,44 +1,44 @@
----
-title: Simready Validator
-emoji: 🏢
-colorFrom: indigo
-colorTo: gray
-sdk: docker
-pinned: false
----
-
-# SimReady Validator
-
-A hosted validator for [SimReady](https://github.com/NVIDIA/simready-foundation)
-asset packages. Submit a HuggingFace dataset, pick a profile, and the Space
-runs the SimReady foundation rules against it and reports back what passed,
-what failed, and why — without copying your assets off HuggingFace.
-
-## Using the validator
-
-Click the **App** tab above to open the validator UI. In the form:
-
-| Field | What to enter |
-|---|---|
-| **Dataset** | The HuggingFace dataset slug you want to validate (e.g. `your-org/your-asset-bundle`). The dataset must be readable by this Space's `HF_TOKEN`. |
-| **Profile** | The SimReady profile that matches your asset type — props vs. robots, neutral vs. PhysX vs. Isaac. See the validation guide for the full list. |
-| **Version** | Profile version. Leave at `1.0.0` unless your profile is pinned to a different release. |
-| **Open PR on dataset with verdict** | When ticked, the verdict is written back to the dataset as a `validation/results.json` pull request. Leave off for ad-hoc smoke tests. |
-
-Click **Validate** and the log streams in real time. When it finishes the
-results.json appears in the **HTML report** download.
-
-## Going deeper
-
-- **[Partner walkthrough → VALIDATE.md](./blob/main/VALIDATE.md)** — the full nine-step guide from cloning the foundation repo to submitting your assets. Read this first if you're packaging assets for SimReady for the first time.
-- **[NVIDIA/simready-foundation](https://github.com/NVIDIA/simready-foundation)** — public spec repo with profile authoring guides and sample assets.
-- **[WRAPP on NGC](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/omniverse/collections/wrapp)** — packaging tool referenced in the walkthrough.
-
-## About this Space
-
-The validator reads the requested HuggingFace dataset in place via
-`huggingface_hub.snapshot_download` — assets stay on HuggingFace, no
-transfer onto NVIDIA infrastructure. Running on a `t4-medium` GPU
-tier. PhysX / MDL rules that require an Isaac Sim runtime are not
-covered here yet (Isaac Sim isn't in the Space image — that's a
-separate workstream).
+---
+title: Simready Validator
+emoji: 🏢
+colorFrom: indigo
+colorTo: gray
+sdk: docker
+pinned: false
+---
+
+# SimReady Validator
+
+A hosted validator for [SimReady](https://github.com/NVIDIA/simready-foundation)
+asset packages. Submit a HuggingFace dataset, pick a profile, and the Space
+runs the SimReady foundation rules against it and reports back what passed,
+what failed, and why — without copying your assets off HuggingFace.
+
+## Using the validator
+
+Click the **App** tab above to open the validator UI. In the form:
+
+| Field | What to enter |
+|---|---|
+| **Dataset** | The HuggingFace dataset slug you want to validate (e.g. `your-org/your-asset-bundle`). The dataset must be readable by this Space's `HF_TOKEN`. |
+| **Profile** | The SimReady profile that matches your asset type — props vs. robots, neutral vs. PhysX vs. Isaac. See the validation guide for the full list. |
+| **Version** | Profile version. Leave at `1.0.0` unless your profile is pinned to a different release. |
+| **Open PR on dataset with verdict** | When ticked, the verdict is written back to the dataset as a `validation/results.json` pull request. Leave off for ad-hoc smoke tests. |
+
+Click **Validate** and the log streams in real time. When it finishes the
+results.json appears in the **HTML report** download.
+
+## Going deeper
+
+- **[Partner walkthrough → VALIDATE.md](./blob/main/VALIDATE.md)** — the full nine-step guide from cloning the foundation repo to submitting your assets. Read this first if you're packaging assets for SimReady for the first time.
+- **[NVIDIA/simready-foundation](https://github.com/NVIDIA/simready-foundation)** — public spec repo with profile authoring guides and sample assets.
+- **[WRAPP on NGC](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/omniverse/collections/wrapp)** — packaging tool referenced in the walkthrough.
+
+## About this Space
+
+The validator reads the requested HuggingFace dataset in place via
+`huggingface_hub.snapshot_download` — assets stay on HuggingFace, no
+transfer onto NVIDIA infrastructure. Running on a `t4-medium` GPU
+tier. PhysX / MDL rules that require an Isaac Sim runtime are not
+covered here yet (Isaac Sim isn't in the Space image — that's a
+separate workstream).

tools/hf_space/Dockerfile

@@ -1,112 +1,112 @@
-# SimReady Validator — HuggingFace Space image
-#
-# Base: nvcr.io/nvidia/isaac-sim:4.5.0. Ships Kit at /isaac-sim/ so
-# runner._kit_available() auto-selects --use-kit and the validator
-# runs PhysX / MDL rules without a code change.
-#
-# UID 1000 is required by HF Spaces. The Isaac Sim base already has
-# a user at UID 1000 (varies between releases — ubuntu / kit / etc.),
-# so we REUSE it rather than create one. /app is the workspace dir
-# with HOME=/app so Claude Code CLI finds skills under ~/.claude/skills
-# regardless of the existing user's name.
-
-FROM nvcr.io/nvidia/isaac-sim:4.5.0
-
-# Skip interactive prompts during apt-get (the deadsnakes PPA install
-# pulls tzdata in as a dep, which otherwise blocks the build asking
-# for a geographic area).
-ENV DEBIAN_FRONTEND=noninteractive
-ENV TZ=Etc/UTC
-
-# System deps (Ubuntu 22.04). Isaac Sim base may ship apt/pip configs
-# pointing at NVIDIA-internal mirrors (urm.nvidia.com) that HF Spaces'
-# build infra can't reach — wipe those before any install. The base
-# default Python is 3.10; simready-validate requires >=3.11, so we
-# install python3.11 from the deadsnakes PPA and use it explicitly
-# for everything below.
-RUN apt-get update && apt-get install -y --no-install-recommends \
-        git curl ca-certificates rsync gnupg software-properties-common \
-    && add-apt-repository -y ppa:deadsnakes/ppa \
-    && apt-get update && apt-get install -y --no-install-recommends \
-        python3.11 python3.11-venv python3.11-distutils \
-    && curl -fsSL https://bootstrap.pypa.io/get-pip.py | python3.11 \
-    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
-    && apt-get install -y --no-install-recommends nodejs \
-    && rm -rf /var/lib/apt/lists/*
-
-RUN npm config set registry https://registry.npmjs.org/ \
-    && rm -f /root/.npmrc /etc/npmrc \
-    && rm -f /root/.pip/pip.conf /etc/pip.conf
-
-# Claude Code CLI.
-RUN npm install -g --registry=https://registry.npmjs.org/ \
-        @anthropic-ai/claude-code@latest
-
-# Workspace nesting matches the legacy layout (/home/appuser/app)
-# because runner.py uses Path(__file__).resolve().parents[2] to find
-# tools/spec_sync/state.json — needs at least 3 levels of parent.
-# We don't create the appuser account (UID 1000 already exists in the
-# base image with a different name); we just use the path. HOME points
-# at the workspace's parent so Claude Code CLI finds ~/.claude/skills.
-RUN mkdir -p /home/appuser/app /home/appuser/.claude/skills
-WORKDIR /home/appuser/app
-ENV HOME=/home/appuser
-
-# Python deps (system Python, public PyPI). --break-system-packages
-# because Ubuntu 22.04 marks system Python as PEP-668 externally-
-# managed; on a build-once container image that's the right trade-off.
-COPY tools/hf_space/requirements.txt ./requirements.txt
-RUN python3.11 -m pip install --no-cache-dir --break-system-packages \
-        --index-url https://pypi.org/simple/ \
-        -r requirements.txt
-
-# Foundation specs.
-ENV SIMREADY_FOUNDATIONS_PATH=/opt/simready_foundations
-ENV SIMREADY_FOUNDATIONS_COMMIT=805d2c50179a9878c89b0f41baaa0ecafe47c3d7
-RUN git clone https://github.com/NVIDIA/simready-foundation \
-        ${SIMREADY_FOUNDATIONS_PATH} \
-    && cd ${SIMREADY_FOUNDATIONS_PATH} \
-    && git checkout ${SIMREADY_FOUNDATIONS_COMMIT}
-
-# Vendored simready-foundation-core wheel.
-COPY tools/hf_space/wheels/simready_foundation_core-0.2.0a1-py3-none-any.whl /tmp/
-RUN python3.11 -m pip install --no-cache-dir --break-system-packages \
-        --index-url https://pypi.org/simple/ \
-        /tmp/simready_foundation_core-0.2.0a1-py3-none-any.whl \
-    && rm /tmp/simready_foundation_core-0.2.0a1-py3-none-any.whl
-
-# Validator + Space code.
-COPY tools/validation /home/appuser/app/tools/validation
-COPY tools/hf_space/app.py     ./app.py
-COPY tools/hf_space/runner.py  ./runner.py
-COPY tools/hf_space/github_issues.py ./github_issues.py
-COPY tools/hf_space/agentic_issues.py ./agentic_issues.py
-COPY README.md ./README.md
-COPY VALIDATE.md ./VALIDATE.md
-
-# Claude Code skills (HOME=/home/appuser → ~/.claude/skills).
-COPY tools/hf_space/skills/simready-validator-agent /home/appuser/.claude/skills/simready-validator-agent
-COPY tools/validation/plugins/simready-report/skills/simready-report /home/appuser/.claude/skills/simready-report
-
-# UID 1000 owns the workspace + foundation clone.
-RUN chown -R 1000:1000 /home/appuser ${SIMREADY_FOUNDATIONS_PATH}
-
-# runner._kit_available() probes /isaac-sim/python.sh — present in the
-# base image — so the validator auto-selects --use-kit at runtime.
-# The validator's --use-kit path needs to know WHERE Kit's python lives;
-# wire it via SIMREADY_KIT_PYTHON so the auto-detect is fully self-
-# configuring (no per-call --kit-python flag needed).
-ENV SIMREADY_KIT_PYTHON=/isaac-sim/python.sh
-
-USER 1000:1000
-
-ENV GRADIO_SERVER_NAME=0.0.0.0
-ENV GRADIO_SERVER_PORT=7860
-EXPOSE 7860
-
-# Clear the Isaac Sim base's ENTRYPOINT (it runs /isaac-sim/runheadless.sh
-# and treats CMD as its args — fails with 'Permission denied' under
-# UID 1000). We invoke the Python app directly; Kit is invoked
-# explicitly by the validator via /isaac-sim/python.sh when needed.
-ENTRYPOINT []
-CMD ["python3.11", "app.py"]
+# SimReady Validator — HuggingFace Space image
+#
+# Base: nvcr.io/nvidia/isaac-sim:4.5.0. Ships Kit at /isaac-sim/ so
+# runner._kit_available() auto-selects --use-kit and the validator
+# runs PhysX / MDL rules without a code change.
+#
+# UID 1000 is required by HF Spaces. The Isaac Sim base already has
+# a user at UID 1000 (varies between releases — ubuntu / kit / etc.),
+# so we REUSE it rather than create one. /app is the workspace dir
+# with HOME=/app so Claude Code CLI finds skills under ~/.claude/skills
+# regardless of the existing user's name.
+
+FROM nvcr.io/nvidia/isaac-sim:4.5.0
+
+# Skip interactive prompts during apt-get (the deadsnakes PPA install
+# pulls tzdata in as a dep, which otherwise blocks the build asking
+# for a geographic area).
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TZ=Etc/UTC
+
+# System deps (Ubuntu 22.04). Isaac Sim base may ship apt/pip configs
+# pointing at NVIDIA-internal mirrors (urm.nvidia.com) that HF Spaces'
+# build infra can't reach — wipe those before any install. The base
+# default Python is 3.10; simready-validate requires >=3.11, so we
+# install python3.11 from the deadsnakes PPA and use it explicitly
+# for everything below.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git curl ca-certificates rsync gnupg software-properties-common \
+    && add-apt-repository -y ppa:deadsnakes/ppa \
+    && apt-get update && apt-get install -y --no-install-recommends \
+        python3.11 python3.11-venv python3.11-distutils \
+    && curl -fsSL https://bootstrap.pypa.io/get-pip.py | python3.11 \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN npm config set registry https://registry.npmjs.org/ \
+    && rm -f /root/.npmrc /etc/npmrc \
+    && rm -f /root/.pip/pip.conf /etc/pip.conf
+
+# Claude Code CLI.
+RUN npm install -g --registry=https://registry.npmjs.org/ \
+        @anthropic-ai/claude-code@latest
+
+# Workspace nesting matches the legacy layout (/home/appuser/app)
+# because runner.py uses Path(__file__).resolve().parents[2] to find
+# tools/spec_sync/state.json — needs at least 3 levels of parent.
+# We don't create the appuser account (UID 1000 already exists in the
+# base image with a different name); we just use the path. HOME points
+# at the workspace's parent so Claude Code CLI finds ~/.claude/skills.
+RUN mkdir -p /home/appuser/app /home/appuser/.claude/skills
+WORKDIR /home/appuser/app
+ENV HOME=/home/appuser
+
+# Python deps (system Python, public PyPI). --break-system-packages
+# because Ubuntu 22.04 marks system Python as PEP-668 externally-
+# managed; on a build-once container image that's the right trade-off.
+COPY tools/hf_space/requirements.txt ./requirements.txt
+RUN python3.11 -m pip install --no-cache-dir --break-system-packages \
+        --index-url https://pypi.org/simple/ \
+        -r requirements.txt
+
+# Foundation specs.
+ENV SIMREADY_FOUNDATIONS_PATH=/opt/simready_foundations
+ENV SIMREADY_FOUNDATIONS_COMMIT=805d2c50179a9878c89b0f41baaa0ecafe47c3d7
+RUN git clone https://github.com/NVIDIA/simready-foundation \
+        ${SIMREADY_FOUNDATIONS_PATH} \
+    && cd ${SIMREADY_FOUNDATIONS_PATH} \
+    && git checkout ${SIMREADY_FOUNDATIONS_COMMIT}
+
+# Vendored simready-foundation-core wheel.
+COPY tools/hf_space/wheels/simready_foundation_core-0.2.0a1-py3-none-any.whl /tmp/
+RUN python3.11 -m pip install --no-cache-dir --break-system-packages \
+        --index-url https://pypi.org/simple/ \
+        /tmp/simready_foundation_core-0.2.0a1-py3-none-any.whl \
+    && rm /tmp/simready_foundation_core-0.2.0a1-py3-none-any.whl
+
+# Validator + Space code.
+COPY tools/validation /home/appuser/app/tools/validation
+COPY tools/hf_space/app.py     ./app.py
+COPY tools/hf_space/runner.py  ./runner.py
+COPY tools/hf_space/github_issues.py ./github_issues.py
+COPY tools/hf_space/agentic_issues.py ./agentic_issues.py
+COPY README.md ./README.md
+COPY VALIDATE.md ./VALIDATE.md
+
+# Claude Code skills (HOME=/home/appuser → ~/.claude/skills).
+COPY tools/hf_space/skills/simready-validator-agent /home/appuser/.claude/skills/simready-validator-agent
+COPY tools/validation/plugins/simready-report/skills/simready-report /home/appuser/.claude/skills/simready-report
+
+# UID 1000 owns the workspace + foundation clone.
+RUN chown -R 1000:1000 /home/appuser ${SIMREADY_FOUNDATIONS_PATH}
+
+# runner._kit_available() probes /isaac-sim/python.sh — present in the
+# base image — so the validator auto-selects --use-kit at runtime.
+# The validator's --use-kit path needs to know WHERE Kit's python lives;
+# wire it via SIMREADY_KIT_PYTHON so the auto-detect is fully self-
+# configuring (no per-call --kit-python flag needed).
+ENV SIMREADY_KIT_PYTHON=/isaac-sim/python.sh
+
+USER 1000:1000
+
+ENV GRADIO_SERVER_NAME=0.0.0.0
+ENV GRADIO_SERVER_PORT=7860
+EXPOSE 7860
+
+# Clear the Isaac Sim base's ENTRYPOINT (it runs /isaac-sim/runheadless.sh
+# and treats CMD as its args — fails with 'Permission denied' under
+# UID 1000). We invoke the Python app directly; Kit is invoked
+# explicitly by the validator via /isaac-sim/python.sh when needed.
+ENTRYPOINT []
+CMD ["python3.11", "app.py"]

tools/hf_space/README_HEADER.md

@@ -1,44 +1,44 @@
----
-title: Simready Validator
-emoji: 🏢
-colorFrom: indigo
-colorTo: gray
-sdk: docker
-pinned: false
----
-
-# SimReady Validator
-
-A hosted validator for [SimReady](https://github.com/NVIDIA/simready-foundation)
-asset packages. Submit a HuggingFace dataset, pick a profile, and the Space
-runs the SimReady foundation rules against it and reports back what passed,
-what failed, and why — without copying your assets off HuggingFace.
-
-## Using the validator
-
-Click the **App** tab above to open the validator UI. In the form:
-
-| Field | What to enter |
-|---|---|
-| **Dataset** | The HuggingFace dataset slug you want to validate (e.g. `your-org/your-asset-bundle`). The dataset must be readable by this Space's `HF_TOKEN`. |
-| **Profile** | The SimReady profile that matches your asset type — props vs. robots, neutral vs. PhysX vs. Isaac. See the validation guide for the full list. |
-| **Version** | Profile version. Leave at `1.0.0` unless your profile is pinned to a different release. |
-| **Open PR on dataset with verdict** | When ticked, the verdict is written back to the dataset as a `validation/results.json` pull request. Leave off for ad-hoc smoke tests. |
-
-Click **Validate** and the log streams in real time. When it finishes the
-results.json appears in the **HTML report** download.
-
-## Going deeper
-
-- **[Partner walkthrough → VALIDATE.md](./blob/main/VALIDATE.md)** — the full nine-step guide from cloning the foundation repo to submitting your assets. Read this first if you're packaging assets for SimReady for the first time.
-- **[NVIDIA/simready-foundation](https://github.com/NVIDIA/simready-foundation)** — public spec repo with profile authoring guides and sample assets.
-- **[WRAPP on NGC](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/omniverse/collections/wrapp)** — packaging tool referenced in the walkthrough.
-
-## About this Space
-
-The validator reads the requested HuggingFace dataset in place via
-`huggingface_hub.snapshot_download` — assets stay on HuggingFace, no
-transfer onto NVIDIA infrastructure. Running on a `t4-medium` GPU
-tier. PhysX / MDL rules that require an Isaac Sim runtime are not
-covered here yet (Isaac Sim isn't in the Space image — that's a
-separate workstream).
+---
+title: Simready Validator
+emoji: 🏢
+colorFrom: indigo
+colorTo: gray
+sdk: docker
+pinned: false
+---
+
+# SimReady Validator
+
+A hosted validator for [SimReady](https://github.com/NVIDIA/simready-foundation)
+asset packages. Submit a HuggingFace dataset, pick a profile, and the Space
+runs the SimReady foundation rules against it and reports back what passed,
+what failed, and why — without copying your assets off HuggingFace.
+
+## Using the validator
+
+Click the **App** tab above to open the validator UI. In the form:
+
+| Field | What to enter |
+|---|---|
+| **Dataset** | The HuggingFace dataset slug you want to validate (e.g. `your-org/your-asset-bundle`). The dataset must be readable by this Space's `HF_TOKEN`. |
+| **Profile** | The SimReady profile that matches your asset type — props vs. robots, neutral vs. PhysX vs. Isaac. See the validation guide for the full list. |
+| **Version** | Profile version. Leave at `1.0.0` unless your profile is pinned to a different release. |
+| **Open PR on dataset with verdict** | When ticked, the verdict is written back to the dataset as a `validation/results.json` pull request. Leave off for ad-hoc smoke tests. |
+
+Click **Validate** and the log streams in real time. When it finishes the
+results.json appears in the **HTML report** download.
+
+## Going deeper
+
+- **[Partner walkthrough → VALIDATE.md](./blob/main/VALIDATE.md)** — the full nine-step guide from cloning the foundation repo to submitting your assets. Read this first if you're packaging assets for SimReady for the first time.
+- **[NVIDIA/simready-foundation](https://github.com/NVIDIA/simready-foundation)** — public spec repo with profile authoring guides and sample assets.
+- **[WRAPP on NGC](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/omniverse/collections/wrapp)** — packaging tool referenced in the walkthrough.
+
+## About this Space
+
+The validator reads the requested HuggingFace dataset in place via
+`huggingface_hub.snapshot_download` — assets stay on HuggingFace, no
+transfer onto NVIDIA infrastructure. Running on a `t4-medium` GPU
+tier. PhysX / MDL rules that require an Isaac Sim runtime are not
+covered here yet (Isaac Sim isn't in the Space image — that's a
+separate workstream).

tools/hf_space/app.py

@@ -1,426 +1,429 @@
-"""SimReady Validator — Gradio UI for the HuggingFace Space.
-
-Two surfaces, same engine:
-
-- **/run** (the on-screen button) — streams log lines to the UI for
-  interactive use by an operator in the browser.
-- **/run_api** (hidden, programmatic) — returns the full RunResult as
-  a JSON-serializable dict. This is what `tools/hf_watch/call_hf_space.py`
-  hits from the GitHub Actions runner so the workflow can patch
-  status.json and asset-status.json without scraping the UI's text.
-
-Both go through `runner.run()`. The split is purely about output
-shape (streaming text vs. one-shot dict).
-
-The Space is internal-pilot scope: HF_TOKEN comes from the Space's
-secrets, NOT from the requester. When a customer's dataset PR triggers
-this (next milestone), the webhook payload identifies the dataset and
-the Space's own token opens the verdict PR.
-"""
-from __future__ import annotations
-
-import json
-import os
-from pathlib import Path
-
-import gradio as gr
-
-from runner import (run as run_validator, progress_path_for, cancel_path_for,
-                    run_token_path_for, CANCEL_DIR)
-
-
-PROFILE_CHOICES = [
-    "Prop-Robotics-Neutral",
-    "Prop-Robotics-Physx",
-    "Prop-Robotics-Isaac",
-    "Robot-Body-Neutral",
-    "Robot-Body-Runnable",
-    "Robot-Body-Isaac",
-    "Package",
-    "Package-Candidate",
-]
-DEFAULT_PROFILE = "Prop-Robotics-Neutral"
-DEFAULT_VERSION = "1.0.0"
-
-
-def _run_api(dataset: str, profile: str, version: str, open_pr: bool,
-             submission_id: str = "", force: bool = False,
-             preliminary: bool = False) -> dict:
-    """Programmatic endpoint. Returns the RunResult as a JSON dict.
-
-    Caller is typically `tools/hf_watch/call_hf_space.py` running from
-    a GitHub Actions ubuntu-latest runner. Output shape must stay
-    stable — bump `schema_version` if you change it. The receiver
-    pattern-matches on the same field names `tools/hf_watch/validate.py`
-    produces, so status.json patching is identical regardless of which
-    backend ran the validation.
-
-    `submission_id` is optional — when set, the validator writes
-    per-asset progress to /tmp/sr-progress/<id>.json, which the
-    get_progress endpoint serves to the dashboard.
-
-    `preliminary` switches the runner to a structure-only sweep:
-    zip-bundled datasets are scanned (instead of failing
-    PKG.NO-ARCHIVES at the listing stage) and per-asset validation is
-    sliced to the first asset only. Used by the dashboard's
-    Preliminary scan tab.
-    """
-    print(f"[run_api] preliminary={preliminary!r} force={force!r} "
-          f"submission_id={submission_id!r}", flush=True)
-    # Untrusted callers can hit /run_api directly — profile/version flow
-    # into the validator's argv, so validate them before use. Empty
-    # falls back to the defaults (existing behavior).
-    import re
-    profile = profile or DEFAULT_PROFILE
-    if profile not in PROFILE_CHOICES and profile.lower() != "auto":
-        raise ValueError(f"invalid profile: {profile!r}")
-    version = (version or DEFAULT_VERSION).strip()
-    if not re.fullmatch(r"[\w.\-]+", version):
-        raise ValueError(f"invalid version: {version!r}")
-    result = run_validator(
-        dataset=(dataset or "").strip(),
-        profile=profile,
-        version=version,
-        open_pr=bool(open_pr),
-        submission_id=(submission_id or "").strip(),
-        force=bool(force),
-        preliminary=bool(preliminary),
-    )
-    return {
-        "schema_version": 1,
-        "dataset": result.dataset,
-        "profile": result.profile,
-        "version": result.version,
-        "status": result.status,
-        "summary": result.summary,
-        "results_json": _sanitize_results_json(result.results_json),
-        "pr_url": result.pr_url,
-    }
-
-
-def _list_profiles() -> dict:
-    """Return the set of profiles that actually load on this Space's
-    foundation+validator combination. The dashboard polls this to
-    populate its dropdown so operators can't pick a profile that
-    would fatally fail at registration time.
-
-    Uses --use-plugin since the default CLI loader has known
-    registration mismatches against the current foundation pin; the
-    plugin path is what runner.py's streaming-zip flow falls back
-    to and is the source of truth for "actually usable" here.
-
-    Output format from validate.py is `PROFILE: <id> v<version>`
-    per profile, one per line.
-    """
-    import subprocess, sys
-    from runner import VALIDATOR, _KIT_FLAG
-    try:
-        proc = subprocess.run(
-            # Kit flag is auto-selected at runtime by runner.py based on
-            # what's installed. Without Kit, --no-use-kit lets the
-            # --list-profiles loader run (the validator's Kit auto-enable
-            # would otherwise error before listing).
-            [sys.executable, str(VALIDATOR), "--list-profiles", "--use-plugin", _KIT_FLAG],
-            capture_output=True, text=True, timeout=300,
-        )
-        names: list[str] = []
-        for line in (proc.stdout or "").splitlines():
-            s = line.strip()
-            # Validator emits "PROFILE: <id> v<version>" — that's our
-            # only authoritative shape. Anything else is noise.
-            if s.startswith("PROFILE:"):
-                rest = s[len("PROFILE:"):].strip()
-                pid = rest.split()[0] if rest else ""
-                if pid:
-                    names.append(pid)
-        # Dedupe while preserving order.
-        seen = set()
-        unique = []
-        for n in names:
-            if n not in seen:
-                seen.add(n)
-                unique.append(n)
-        result: dict = {"profiles": unique, "schema_version": 1, "rc": proc.returncode}
-        if not unique:
-            # No profiles registered AND no parse hits — surface why so
-            # the dashboard can show something useful. Truncate so the
-            # JSON response stays small.
-            stderr_tail = "\n".join((proc.stderr or "").splitlines()[-20:])[:2000]
-            stdout_tail = "\n".join((proc.stdout or "").splitlines()[-20:])[:2000]
-            result["stderr_tail"] = stderr_tail
-            result["stdout_tail"] = stdout_tail
-        return result
-    except subprocess.TimeoutExpired:
-        return {"profiles": [], "error": "timeout after 300s (spec load >5 min)"}
-    except Exception as e:
-        return {"profiles": [], "error": f"{type(e).__name__}: {e}"}
-
-
-def _cancel_run(submission_id: str, run_token: str = "") -> dict:
-    """Write the cancel-signal file for a given submission. The
-    streaming-zip loop in runner.py checks for this file between zips
-    and aborts when present. Idempotent — calling multiple times has no
-    extra effect; consuming runner.py deletes it.
-
-    `run_token` is the per-run token the dashboard read from get_progress.
-    It becomes the flag's content so runner._is_cancelled only honors it
-    for the exact run it was issued against — a flag left over from a
-    prior run of this submission can never abort a fresh one."""
-    sid = (submission_id or "").strip()
-    if not sid:
-        return {"state": "no_id"}
-    path = cancel_path_for(sid)
-    if path is None:
-        return {"state": "no_id"}
-    try:
-        CANCEL_DIR.mkdir(parents=True, exist_ok=True)
-        path.write_text((run_token or "").strip(), encoding="utf-8")
-        return {"state": "signaled", "path": str(path)}
-    except OSError as e:
-        return {"state": "error", "error": f"{type(e).__name__}: {e}"}
-
-
-def _get_progress(submission_id: str) -> dict:
-    """Read the validator's per-asset progress file for this submission.
-
-    Polled by the dashboard ~every 3 s while a Validate-now click is
-    in-flight, so the "Validate now" button can fill up as the
-    validator works through the asset list.
-
-    Returns one of three shapes:
-      - {"state": "not_found"} — no progress file (Space restarted, or
-        the dashboard is polling a Space-run that never happened).
-      - {"state": "starting"}  — file seeded by runner.py before the
-        validator started its loop. processed/total are 0.
-      - {processed, total, current, started_at, updated_at} — live
-        per-asset progress written by validate.py._emit_progress.
-
-    Every shape also carries `run_token` (the current run's cancel
-    token, from the sidecar file) when one exists, so the dashboard can
-    echo it back to cancel_run and target the exact run.
-
-    Caller treats anything with total > 0 as "show the fill bar".
-    """
-    sid = (submission_id or "").strip()
-    if not sid:
-        return {"state": "no_id"}
-    # Per-run cancel token (sidecar; see runner.run_token_path_for).
-    # Surfaced on every shape so the dashboard can echo it back to
-    # cancel_run — a cancel then only aborts the run it was issued
-    # against, never a later one that reused the submission_id.
-    run_token = ""
-    tok_path = run_token_path_for(sid)
-    if tok_path and tok_path.is_file():
-        try:
-            run_token = tok_path.read_text(encoding="utf-8").strip()
-        except OSError:
-            pass
-    path = progress_path_for(sid)
-    if path is None or not path.is_file():
-        return {"state": "not_found", "run_token": run_token}
-    try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-        if isinstance(data, dict) and run_token:
-            data["run_token"] = run_token
-        return data
-    except (OSError, json.JSONDecodeError):
-        # Mid-write — caller will poll again in a few seconds.
-        return {"state": "transient", "run_token": run_token}
-
-
-def _sanitize_results_json(raw: dict) -> dict:
-    """Strip absolute filesystem paths from results_json before returning.
-
-    Gradio's JSON serializer treats string fields that resolve to files
-    on the Space's filesystem as downloadable references and tries to
-    serve them through `/gradio_api/file=...`. The validator's
-    results.json contains absolute paths (target dir + per-asset
-    `path`) which point into the Space's ephemeral tempdir and are
-    NOT exposed through gradio's allowed_paths — gradio_client then
-    fails with 403 trying to auto-fetch them after a successful run.
-
-    Callers don't need filesystem paths anyway — only `rel_path`
-    (dataset-relative), `passed`, and `issues` are used downstream.
-    Keep the rest of the report intact (profile_coverage, summary,
-    layout_findings, etc.).
-    """
-    if not isinstance(raw, dict):
-        return raw
-    sanitized = {k: v for k, v in raw.items() if k != "target"}
-    if "results" in sanitized and isinstance(sanitized["results"], list):
-        sanitized["results"] = [
-            {k: v for k, v in asset.items() if k != "path"}
-            for asset in sanitized["results"]
-            if isinstance(asset, dict)
-        ]
-    # Specs/dashboard dir paths are local to the Space, useless to caller.
-    for k in ("specs_docs_dir", "dashboard_docs_dir"):
-        sanitized.pop(k, None)
-    return sanitized
-
-
-def _run_streaming(dataset: str, profile: str, version: str, open_pr: bool):
-    """Generator that yields incremental log output to the UI as the
-    validator runs. Gradio streams each yielded tuple to the connected
-    outputs."""
-    lines: list[str] = []
-
-    def log(line: str) -> None:
-        lines.append(line)
-
-    yield "\n".join(lines), "", "(running…)", None
-
-    try:
-        result = run_validator(
-            dataset=dataset.strip(),
-            profile=profile,
-            version=version.strip() or DEFAULT_VERSION,
-            open_pr=open_pr,
-            log=log,
-        )
-    except Exception as e:
-        lines.append(f"\nERROR: {type(e).__name__}: {e}")
-        yield "\n".join(lines), "", f"error: {e}", None
-        return
-
-    status_badge = f"**{result.status.upper()}** — {result.summary}"
-    if result.pr_url:
-        status_badge += f"\n\nPR: {result.pr_url}"
-
-    report_index = result.report_path / "index.html"
-    report_url = str(report_index) if report_index.is_file() else None
-
-    yield (
-        "\n".join(lines),
-        status_badge,
-        result.summary,
-        report_url,
-    )
-
-
-def _read_md(name: str) -> str:
-    """Return the contents of name (relative to this file's dir),
-    stripping a leading YAML frontmatter block if present. Falls back
-    to a friendly stub when the file is missing — keeps the Space
-    bootable even before the space-deploy workflow has synced the
-    assembled docs into the container."""
-    from pathlib import Path
-    p = Path(__file__).resolve().parent / name
-    try:
-        src = p.read_text(encoding="utf-8")
-    except FileNotFoundError:
-        return f"_{name} not yet synced into this Space — check back after the next deploy._"
-    if src.startswith("---"):
-        end = src.find("\n---\n", 4)
-        if end > 0:
-            src = src[end + len("\n---\n"):].lstrip()
-    return src
-
-
-with gr.Blocks(title="SimReady Validator") as demo:
-    with gr.Tabs():
-        with gr.Tab("Overview"):
-            gr.Markdown(_read_md("README.md"))
-        with gr.Tab("Validator"):
-            gr.Markdown(
-                "Submit a HuggingFace dataset to validate against a SimReady "
-                "profile. With **Open PR** enabled, the verdict is uploaded "
-                "back to the dataset as a `validation/` pull request."
-            )
-            with gr.Row():
-                dataset = gr.Textbox(
-                    label="Dataset",
-                    placeholder="org/dataset (e.g. imagineio/PhysicalAI-SimReady-Kitchens-v1)",
-                )
-            with gr.Row():
-                profile = gr.Dropdown(
-                    choices=PROFILE_CHOICES, value=DEFAULT_PROFILE, label="Profile",
-                )
-                version = gr.Textbox(label="Version", value=DEFAULT_VERSION)
-                open_pr = gr.Checkbox(label="Open PR on dataset with verdict", value=False)
-            run_btn = gr.Button("Validate", variant="primary")
-            status_md = gr.Markdown(label="Verdict")
-            summary_box = gr.Textbox(label="Summary", interactive=False)
-            log_box = gr.Textbox(label="Log", lines=20, interactive=False)
-            report_link = gr.File(label="HTML report (download)", interactive=False)
-        with gr.Tab("Partner walkthrough"):
-            gr.Markdown(_read_md("VALIDATE.md"))
-
-    run_btn.click(
-        fn=_run_streaming,
-        inputs=[dataset, profile, version, open_pr],
-        outputs=[log_box, status_md, summary_box, report_link],
-        api_name="run",
-    )
-
-    # Programmatic endpoint — bound to invisible components so the UI
-    # doesn't render anything extra, but the Gradio queue still exposes
-    # an `/api/predict/run_api` route the gradio_client can hit. The
-    # outputs[0] is the JSON return; api_name turns it into a stable
-    # path the GitHub Actions caller depends on.
-    api_dataset = gr.Textbox(visible=False)
-    api_profile = gr.Textbox(visible=False)
-    api_version = gr.Textbox(visible=False)
-    api_open_pr = gr.Checkbox(visible=False)
-    api_submission_id = gr.Textbox(visible=False)
-    api_force = gr.Checkbox(visible=False)
-    api_preliminary = gr.Checkbox(visible=False)
-    api_output  = gr.JSON(visible=False)
-    api_button  = gr.Button(visible=False)
-    api_button.click(
-        fn=_run_api,
-        inputs=[api_dataset, api_profile, api_version, api_open_pr,
-                api_submission_id, api_force, api_preliminary],
-        outputs=api_output,
-        api_name="run_api",
-    )
-
-    # Progress endpoint — polled by the dashboard while a row is
-    # validating. CORS is open on /gradio_api/* by default, so the
-    # browser can fetch this from github.io directly without any
-    # GitHub-Actions side polling/commit churn.
-    prog_in     = gr.Textbox(visible=False)
-    prog_out    = gr.JSON(visible=False)
-    prog_button = gr.Button(visible=False)
-    prog_button.click(
-        fn=_get_progress,
-        inputs=[prog_in],
-        outputs=prog_out,
-        api_name="get_progress",
-    )
-
-    # Profile-listing endpoint — polled by the dashboard at startup
-    # so its dropdown reflects what's actually loadable on this Space
-    # right now (foundation+validator pin determines which profiles
-    # register). Stops the operator from picking something that
-    # would fatal at runtime.
-    profiles_out    = gr.JSON(visible=False)
-    profiles_button = gr.Button(visible=False)
-    profiles_button.click(
-        fn=_list_profiles,
-        inputs=None,
-        outputs=profiles_out,
-        api_name="list_profiles",
-    )
-
-    # Cancel endpoint — the dashboard's Cancel button calls this AFTER
-    # cancelling the GH Action so the in-flight server-side gradio call
-    # actually stops (cancelling the Action alone only kills the
-    # gradio_client wrapper, the Space's loop keeps going).
-    cancel_in     = gr.Textbox(visible=False)
-    cancel_token  = gr.Textbox(visible=False)
-    cancel_out    = gr.JSON(visible=False)
-    cancel_button = gr.Button(visible=False)
-    cancel_button.click(
-        fn=_cancel_run,
-        inputs=[cancel_in, cancel_token],
-        outputs=cancel_out,
-        api_name="cancel_run",
-    )
-
-
-if __name__ == "__main__":
-    demo.queue().launch(
-        server_name=os.environ.get("GRADIO_SERVER_NAME", "0.0.0.0"),
-        server_port=int(os.environ.get("GRADIO_SERVER_PORT", "7860")),
-    )
+"""SimReady Validator — Gradio UI for the HuggingFace Space.
+
+Two surfaces, same engine:
+
+- **/run** (the on-screen button) — streams log lines to the UI for
+  interactive use by an operator in the browser.
+- **/run_api** (hidden, programmatic) — returns the full RunResult as
+  a JSON-serializable dict. This is what `tools/hf_watch/call_hf_space.py`
+  hits from the GitHub Actions runner so the workflow can patch
+  status.json and asset-status.json without scraping the UI's text.
+
+Both go through `runner.run()`. The split is purely about output
+shape (streaming text vs. one-shot dict).
+
+The Space is internal-pilot scope: HF_TOKEN comes from the Space's
+secrets, NOT from the requester. When a customer's dataset PR triggers
+this (next milestone), the webhook payload identifies the dataset and
+the Space's own token opens the verdict PR.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import gradio as gr
+
+from runner import (run as run_validator, progress_path_for, cancel_path_for,
+                    run_token_path_for, CANCEL_DIR)
+
+
+PROFILE_CHOICES = [
+    "Prop-Robotics-Neutral",
+    "Prop-Robotics-Physx",
+    "Prop-Robotics-Isaac",
+    "Robot-Body-Neutral",
+    "Robot-Body-Runnable",
+    "Robot-Body-Isaac",
+    "Package",
+    "Package-Candidate",
+]
+DEFAULT_PROFILE = "Prop-Robotics-Neutral"
+DEFAULT_VERSION = "1.0.0"
+
+
+def _run_api(dataset: str, profile: str, version: str, open_pr: bool,
+             submission_id: str = "", force: bool = False,
+             preliminary: bool = False) -> dict:
+    """Programmatic endpoint. Returns the RunResult as a JSON dict.
+
+    Caller is typically `tools/hf_watch/call_hf_space.py` running from
+    a GitHub Actions ubuntu-latest runner. Output shape must stay
+    stable — bump `schema_version` if you change it. The receiver
+    pattern-matches on the same field names `tools/hf_watch/validate.py`
+    produces, so status.json patching is identical regardless of which
+    backend ran the validation.
+
+    `submission_id` is optional — when set, the validator writes
+    per-asset progress to /tmp/sr-progress/<id>.json, which the
+    get_progress endpoint serves to the dashboard.
+
+    `preliminary` switches the runner to a structure-only sweep:
+    zip-bundled datasets are scanned (instead of failing
+    PKG.NO-ARCHIVES at the listing stage) and per-asset validation is
+    sliced to the first asset only. Used by the dashboard's
+    Preliminary scan tab.
+    """
+    print(f"[run_api] preliminary={preliminary!r} force={force!r} "
+          f"submission_id={submission_id!r}", flush=True)
+    # Untrusted callers can hit /run_api directly — profile/version flow
+    # into the validator's argv, so validate them before use. Empty
+    # falls back to the defaults (existing behavior).
+    import re
+    profile = profile or DEFAULT_PROFILE
+    if profile not in PROFILE_CHOICES and profile.lower() != "auto":
+        raise ValueError(f"invalid profile: {profile!r}")
+    version = (version or DEFAULT_VERSION).strip()
+    if not re.fullmatch(r"[\w.\-]+", version):
+        raise ValueError(f"invalid version: {version!r}")
+    result = run_validator(
+        dataset=(dataset or "").strip(),
+        profile=profile,
+        version=version,
+        open_pr=bool(open_pr),
+        submission_id=(submission_id or "").strip(),
+        force=bool(force),
+        preliminary=bool(preliminary),
+    )
+    return {
+        "schema_version": 1,
+        "dataset": result.dataset,
+        "profile": result.profile,
+        "version": result.version,
+        "status": result.status,
+        "summary": result.summary,
+        "results_json": _sanitize_results_json(result.results_json),
+        "pr_url": result.pr_url,
+    }
+
+
+def _list_profiles() -> dict:
+    """Return the set of profiles that actually load on this Space's
+    foundation+validator combination. The dashboard polls this to
+    populate its dropdown so operators can't pick a profile that
+    would fatally fail at registration time.
+
+    Uses --use-plugin since the default CLI loader has known
+    registration mismatches against the current foundation pin; the
+    plugin path is what runner.py's streaming-zip flow falls back
+    to and is the source of truth for "actually usable" here.
+
+    Output format from validate.py is `PROFILE: <id> v<version>`
+    per profile, one per line.
+    """
+    import subprocess, sys
+    from runner import VALIDATOR
+    try:
+        proc = subprocess.run(
+            # --list-profiles only ENUMERATES registered profiles from the
+            # spec/plugin registry (--use-plugin) — it runs no validation
+            # rules, so it never needs Kit. Force --no-use-kit: on a
+            # Kit-enabled image the validator auto-enables --use-kit for the
+            # PhysX-bearing default profile and boots the full Isaac Sim
+            # runtime (~5 min) just to print the list, blowing the 300s
+            # timeout below. Actual validation (runner.py) still uses Kit.
+            [sys.executable, str(VALIDATOR), "--list-profiles", "--use-plugin", "--no-use-kit"],
+            capture_output=True, text=True, timeout=300,
+        )
+        names: list[str] = []
+        for line in (proc.stdout or "").splitlines():
+            s = line.strip()
+            # Validator emits "PROFILE: <id> v<version>" — that's our
+            # only authoritative shape. Anything else is noise.
+            if s.startswith("PROFILE:"):
+                rest = s[len("PROFILE:"):].strip()
+                pid = rest.split()[0] if rest else ""
+                if pid:
+                    names.append(pid)
+        # Dedupe while preserving order.
+        seen = set()
+        unique = []
+        for n in names:
+            if n not in seen:
+                seen.add(n)
+                unique.append(n)
+        result: dict = {"profiles": unique, "schema_version": 1, "rc": proc.returncode}
+        if not unique:
+            # No profiles registered AND no parse hits — surface why so
+            # the dashboard can show something useful. Truncate so the
+            # JSON response stays small.
+            stderr_tail = "\n".join((proc.stderr or "").splitlines()[-20:])[:2000]
+            stdout_tail = "\n".join((proc.stdout or "").splitlines()[-20:])[:2000]
+            result["stderr_tail"] = stderr_tail
+            result["stdout_tail"] = stdout_tail
+        return result
+    except subprocess.TimeoutExpired:
+        return {"profiles": [], "error": "timeout after 300s (spec load >5 min)"}
+    except Exception as e:
+        return {"profiles": [], "error": f"{type(e).__name__}: {e}"}
+
+
+def _cancel_run(submission_id: str, run_token: str = "") -> dict:
+    """Write the cancel-signal file for a given submission. The
+    streaming-zip loop in runner.py checks for this file between zips
+    and aborts when present. Idempotent — calling multiple times has no
+    extra effect; consuming runner.py deletes it.
+
+    `run_token` is the per-run token the dashboard read from get_progress.
+    It becomes the flag's content so runner._is_cancelled only honors it
+    for the exact run it was issued against — a flag left over from a
+    prior run of this submission can never abort a fresh one."""
+    sid = (submission_id or "").strip()
+    if not sid:
+        return {"state": "no_id"}
+    path = cancel_path_for(sid)
+    if path is None:
+        return {"state": "no_id"}
+    try:
+        CANCEL_DIR.mkdir(parents=True, exist_ok=True)
+        path.write_text((run_token or "").strip(), encoding="utf-8")
+        return {"state": "signaled", "path": str(path)}
+    except OSError as e:
+        return {"state": "error", "error": f"{type(e).__name__}: {e}"}
+
+
+def _get_progress(submission_id: str) -> dict:
+    """Read the validator's per-asset progress file for this submission.
+
+    Polled by the dashboard ~every 3 s while a Validate-now click is
+    in-flight, so the "Validate now" button can fill up as the
+    validator works through the asset list.
+
+    Returns one of three shapes:
+      - {"state": "not_found"} — no progress file (Space restarted, or
+        the dashboard is polling a Space-run that never happened).
+      - {"state": "starting"}  — file seeded by runner.py before the
+        validator started its loop. processed/total are 0.
+      - {processed, total, current, started_at, updated_at} — live
+        per-asset progress written by validate.py._emit_progress.
+
+    Every shape also carries `run_token` (the current run's cancel
+    token, from the sidecar file) when one exists, so the dashboard can
+    echo it back to cancel_run and target the exact run.
+
+    Caller treats anything with total > 0 as "show the fill bar".
+    """
+    sid = (submission_id or "").strip()
+    if not sid:
+        return {"state": "no_id"}
+    # Per-run cancel token (sidecar; see runner.run_token_path_for).
+    # Surfaced on every shape so the dashboard can echo it back to
+    # cancel_run — a cancel then only aborts the run it was issued
+    # against, never a later one that reused the submission_id.
+    run_token = ""
+    tok_path = run_token_path_for(sid)
+    if tok_path and tok_path.is_file():
+        try:
+            run_token = tok_path.read_text(encoding="utf-8").strip()
+        except OSError:
+            pass
+    path = progress_path_for(sid)
+    if path is None or not path.is_file():
+        return {"state": "not_found", "run_token": run_token}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if isinstance(data, dict) and run_token:
+            data["run_token"] = run_token
+        return data
+    except (OSError, json.JSONDecodeError):
+        # Mid-write — caller will poll again in a few seconds.
+        return {"state": "transient", "run_token": run_token}
+
+
+def _sanitize_results_json(raw: dict) -> dict:
+    """Strip absolute filesystem paths from results_json before returning.
+
+    Gradio's JSON serializer treats string fields that resolve to files
+    on the Space's filesystem as downloadable references and tries to
+    serve them through `/gradio_api/file=...`. The validator's
+    results.json contains absolute paths (target dir + per-asset
+    `path`) which point into the Space's ephemeral tempdir and are
+    NOT exposed through gradio's allowed_paths — gradio_client then
+    fails with 403 trying to auto-fetch them after a successful run.
+
+    Callers don't need filesystem paths anyway — only `rel_path`
+    (dataset-relative), `passed`, and `issues` are used downstream.
+    Keep the rest of the report intact (profile_coverage, summary,
+    layout_findings, etc.).
+    """
+    if not isinstance(raw, dict):
+        return raw
+    sanitized = {k: v for k, v in raw.items() if k != "target"}
+    if "results" in sanitized and isinstance(sanitized["results"], list):
+        sanitized["results"] = [
+            {k: v for k, v in asset.items() if k != "path"}
+            for asset in sanitized["results"]
+            if isinstance(asset, dict)
+        ]
+    # Specs/dashboard dir paths are local to the Space, useless to caller.
+    for k in ("specs_docs_dir", "dashboard_docs_dir"):
+        sanitized.pop(k, None)
+    return sanitized
+
+
+def _run_streaming(dataset: str, profile: str, version: str, open_pr: bool):
+    """Generator that yields incremental log output to the UI as the
+    validator runs. Gradio streams each yielded tuple to the connected
+    outputs."""
+    lines: list[str] = []
+
+    def log(line: str) -> None:
+        lines.append(line)
+
+    yield "\n".join(lines), "", "(running…)", None
+
+    try:
+        result = run_validator(
+            dataset=dataset.strip(),
+            profile=profile,
+            version=version.strip() or DEFAULT_VERSION,
+            open_pr=open_pr,
+            log=log,
+        )
+    except Exception as e:
+        lines.append(f"\nERROR: {type(e).__name__}: {e}")
+        yield "\n".join(lines), "", f"error: {e}", None
+        return
+
+    status_badge = f"**{result.status.upper()}** — {result.summary}"
+    if result.pr_url:
+        status_badge += f"\n\nPR: {result.pr_url}"
+
+    report_index = result.report_path / "index.html"
+    report_url = str(report_index) if report_index.is_file() else None
+
+    yield (
+        "\n".join(lines),
+        status_badge,
+        result.summary,
+        report_url,
+    )
+
+
+def _read_md(name: str) -> str:
+    """Return the contents of name (relative to this file's dir),
+    stripping a leading YAML frontmatter block if present. Falls back
+    to a friendly stub when the file is missing — keeps the Space
+    bootable even before the space-deploy workflow has synced the
+    assembled docs into the container."""
+    from pathlib import Path
+    p = Path(__file__).resolve().parent / name
+    try:
+        src = p.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return f"_{name} not yet synced into this Space — check back after the next deploy._"
+    if src.startswith("---"):
+        end = src.find("\n---\n", 4)
+        if end > 0:
+            src = src[end + len("\n---\n"):].lstrip()
+    return src
+
+
+with gr.Blocks(title="SimReady Validator") as demo:
+    with gr.Tabs():
+        with gr.Tab("Overview"):
+            gr.Markdown(_read_md("README.md"))
+        with gr.Tab("Validator"):
+            gr.Markdown(
+                "Submit a HuggingFace dataset to validate against a SimReady "
+                "profile. With **Open PR** enabled, the verdict is uploaded "
+                "back to the dataset as a `validation/` pull request."
+            )
+            with gr.Row():
+                dataset = gr.Textbox(
+                    label="Dataset",
+                    placeholder="org/dataset (e.g. imagineio/PhysicalAI-SimReady-Kitchens-v1)",
+                )
+            with gr.Row():
+                profile = gr.Dropdown(
+                    choices=PROFILE_CHOICES, value=DEFAULT_PROFILE, label="Profile",
+                )
+                version = gr.Textbox(label="Version", value=DEFAULT_VERSION)
+                open_pr = gr.Checkbox(label="Open PR on dataset with verdict", value=False)
+            run_btn = gr.Button("Validate", variant="primary")
+            status_md = gr.Markdown(label="Verdict")
+            summary_box = gr.Textbox(label="Summary", interactive=False)
+            log_box = gr.Textbox(label="Log", lines=20, interactive=False)
+            report_link = gr.File(label="HTML report (download)", interactive=False)
+        with gr.Tab("Partner walkthrough"):
+            gr.Markdown(_read_md("VALIDATE.md"))
+
+    run_btn.click(
+        fn=_run_streaming,
+        inputs=[dataset, profile, version, open_pr],
+        outputs=[log_box, status_md, summary_box, report_link],
+        api_name="run",
+    )
+
+    # Programmatic endpoint — bound to invisible components so the UI
+    # doesn't render anything extra, but the Gradio queue still exposes
+    # an `/api/predict/run_api` route the gradio_client can hit. The
+    # outputs[0] is the JSON return; api_name turns it into a stable
+    # path the GitHub Actions caller depends on.
+    api_dataset = gr.Textbox(visible=False)
+    api_profile = gr.Textbox(visible=False)
+    api_version = gr.Textbox(visible=False)
+    api_open_pr = gr.Checkbox(visible=False)
+    api_submission_id = gr.Textbox(visible=False)
+    api_force = gr.Checkbox(visible=False)
+    api_preliminary = gr.Checkbox(visible=False)
+    api_output  = gr.JSON(visible=False)
+    api_button  = gr.Button(visible=False)
+    api_button.click(
+        fn=_run_api,
+        inputs=[api_dataset, api_profile, api_version, api_open_pr,
+                api_submission_id, api_force, api_preliminary],
+        outputs=api_output,
+        api_name="run_api",
+    )
+
+    # Progress endpoint — polled by the dashboard while a row is
+    # validating. CORS is open on /gradio_api/* by default, so the
+    # browser can fetch this from github.io directly without any
+    # GitHub-Actions side polling/commit churn.
+    prog_in     = gr.Textbox(visible=False)
+    prog_out    = gr.JSON(visible=False)
+    prog_button = gr.Button(visible=False)
+    prog_button.click(
+        fn=_get_progress,
+        inputs=[prog_in],
+        outputs=prog_out,
+        api_name="get_progress",
+    )
+
+    # Profile-listing endpoint — polled by the dashboard at startup
+    # so its dropdown reflects what's actually loadable on this Space
+    # right now (foundation+validator pin determines which profiles
+    # register). Stops the operator from picking something that
+    # would fatal at runtime.
+    profiles_out    = gr.JSON(visible=False)
+    profiles_button = gr.Button(visible=False)
+    profiles_button.click(
+        fn=_list_profiles,
+        inputs=None,
+        outputs=profiles_out,
+        api_name="list_profiles",
+    )
+
+    # Cancel endpoint — the dashboard's Cancel button calls this AFTER
+    # cancelling the GH Action so the in-flight server-side gradio call
+    # actually stops (cancelling the Action alone only kills the
+    # gradio_client wrapper, the Space's loop keeps going).
+    cancel_in     = gr.Textbox(visible=False)
+    cancel_token  = gr.Textbox(visible=False)
+    cancel_out    = gr.JSON(visible=False)
+    cancel_button = gr.Button(visible=False)
+    cancel_button.click(
+        fn=_cancel_run,
+        inputs=[cancel_in, cancel_token],
+        outputs=cancel_out,
+        api_name="cancel_run",
+    )
+
+
+if __name__ == "__main__":
+    demo.queue().launch(
+        server_name=os.environ.get("GRADIO_SERVER_NAME", "0.0.0.0"),
+        server_port=int(os.environ.get("GRADIO_SERVER_PORT", "7860")),
+    )

tools/hf_space/github_issues.py

@@ -1,324 +1,324 @@
-"""Auto-file GitHub issues for validator-internal bugs.
-
-Mirror of `tools/hf_watch/validate.py::_ensure_validator_internal_issues`
-moved to the HF Space side so the Space can self-report tooling
-failures without depending on the GH Actions wrapper to do it.
-
-Policy reminder (from CLAUDE.md / project conventions):
-- GitHub Issues track NVIDIA-internal *tooling* problems only.
-- Customer-asset findings (real spec violations) stay on the dashboard;
-  they do NOT become issues.
-- Distinguishing the two is `is_validator_internal_issue`'s job.
-
-Token: GH_VALIDATOR_TOKEN (or GITHUB_TOKEN) — set as a Space secret.
-A fine-grained PAT with `issues: read+write` on
-`NVIDIA-dev/simready-oem-library-pm` is enough; no other scope needed.
-"""
-from __future__ import annotations
-
-import json
-import os
-import re
-import urllib.parse
-import urllib.request
-from typing import Any
-
-
-GH_REPO = "NVIDIA-dev/simready-oem-library-pm"
-
-# Redact token-shaped strings before they land in a (public-ish) issue.
-# Covers GitHub PATs (gh[ps]_…), HF tokens (hf_…), and long base64-ish
-# secrets. Validator log text passes through here on its way into bodies.
-_SECRET_RE = re.compile(r"gh[ps]_\w+|hf_\w+|[A-Za-z0-9+/]{40,}={0,2}")
-
-
-def scrub_secrets(text: str) -> str:
-    return _SECRET_RE.sub("[REDACTED]", text or "")
-
-
-def _gh_token() -> str | None:
-    return os.environ.get("GH_VALIDATOR_TOKEN") or os.environ.get("GITHUB_TOKEN")
-
-
-def is_validator_internal_issue(iss: dict) -> bool:
-    """Heuristic: distinguish validator-package crashes from real
-    asset findings."""
-    code = iss.get("code") or ""
-    msg = iss.get("msg") or ""
-    if code == "UNKNOWN" or code.startswith("SDK."):
-        return True
-    if "Uncaught error" in msg:
-        return True
-    if "is not registered to requirement" in msg:
-        return True
-    return False
-
-
-def _gh_request(method: str, path: str, payload: dict | None = None) -> dict | list:
-    token = _gh_token()
-    if not token:
-        raise RuntimeError("no GitHub token in env (GH_VALIDATOR_TOKEN or GITHUB_TOKEN)")
-    url = f"https://api.github.com/repos/{GH_REPO}{path}"
-    headers = {
-        "Accept": "application/vnd.github+json",
-        "Authorization": f"Bearer {token}",
-        "X-GitHub-Api-Version": "2022-11-28",
-        "User-Agent": "simready-validator-space/0.1",
-    }
-    body = None
-    if payload is not None:
-        body = json.dumps(payload).encode("utf-8")
-        headers["Content-Type"] = "application/json"
-    req = urllib.request.Request(url, data=body, headers=headers, method=method)
-    with urllib.request.urlopen(req, timeout=30) as r:
-        return json.loads(r.read() or "null")
-
-
-def _find_issue(title: str) -> dict | None:
-    # Strip `"` — title is untrusted and a quote would break the
-    # quoted-phrase search query (and could inject extra qualifiers).
-    safe_title = title.replace('"', "")
-    q = urllib.parse.quote(f'repo:{GH_REPO} in:title "{safe_title}" is:issue')
-    result = _gh_request("GET", f"/../../search/issues?q={q}")
-    items = (result or {}).get("items") or []
-    for it in items:
-        if it.get("title") == title:
-            return it
-    return None
-
-
-def _create_issue(title: str, body: str, labels: list[str]) -> int:
-    result = _gh_request("POST", "/issues",
-                         {"title": title, "body": body, "labels": labels})
-    return result.get("number", 0)
-
-
-def _add_comment(issue_num: int, body: str) -> None:
-    _gh_request("POST", f"/issues/{issue_num}/comments", {"body": body})
-
-
-def _build_dataset_issue_body(by_pair: dict, dataset: str, profile: str,
-                               total: int) -> str:
-    rows = "\n".join(
-        f"| `{rule}` | `{code}` | {g['severity'] or '?'} | {g['count']} | `{g['sample_msg']}` |"
-        for (rule, code), g in sorted(by_pair.items(), key=lambda kv: -kv[1]["count"])
-    )
-    return (
-        f"**Validator-internal bugs on a single dataset** — surfaced during "
-        f"automatic SimReady validation. NOT a customer-asset finding; the "
-        f"validator's own rule registration / spec loading is misbehaving "
-        f"on this dataset and emitting errors that don't map to any real "
-        f"spec violation.\n\n"
-        f"| Field | Value |\n|---|---|\n"
-        f"| Dataset | `{dataset}` |\n"
-        f"| Profile (first run) | `{profile}` |\n"
-        f"| Total internal occurrences (first run) | {total} |\n"
-        f"| Distinct (rule, code) pairs (first run) | {len(by_pair)} |\n\n"
-        f"**Breakdown** (sorted by occurrence count, descending):\n\n"
-        f"| Rule | Code | Severity | Count | Sample message |\n"
-        f"|---|---|---|---|---|\n{rows}\n\n"
-        f"---\n"
-        f"_Filed automatically by the HF Space (`tools/hf_space/github_issues.py`). "
-        f"One issue per dataset — re-validating the same dataset comments "
-        f"here with the new counts instead of opening a duplicate._"
-    )
-
-
-def _build_dataset_recurrence_comment(by_pair: dict, dataset: str, profile: str,
-                                       total: int) -> str:
-    rows = "\n".join(
-        f"| `{rule}` | `{code}` | {g['count']} |"
-        for (rule, code), g in sorted(by_pair.items(), key=lambda kv: -kv[1]["count"])
-    )
-    return (
-        f"Re-hit during validation of `{dataset}` (profile `{profile}`).\n"
-        f"This run: **{total}** internal occurrences across **{len(by_pair)}** "
-        f"distinct (rule, code) pairs.\n\n"
-        f"| Rule | Code | Count this run |\n|---|---|---|\n{rows}"
-    )
-
-
-def _list_existing_internal_issues() -> list[dict]:
-    """Pull every validator-internal issue (open + recently closed) so
-    the agent can dedupe semantically against them. Closed issues are
-    included because the same bug can come back after a fix is
-    reverted or after a regression."""
-    q = urllib.parse.quote(
-        f'repo:{GH_REPO} label:"validator-internal" is:issue')
-    try:
-        result = _gh_request("GET", f"/../../search/issues?q={q}&per_page=100")
-    except Exception:
-        return []
-    return (result or {}).get("items") or []
-
-
-def _execute_decisions(decisions: list[dict], by_pair: dict, dataset: str,
-                       profile: str, total: int, log_fn) -> dict:
-    """Carry out the agent's decisions. Returns counters."""
-    out = log_fn
-    created = updated = skipped = 0
-    aborted = False
-    # Map negative placeholder numbers → real issue numbers as `create`
-    # decisions resolve. The agent uses negatives to cross-reference
-    # decisions that share a parent issue when several groups roll up
-    # into one new bug.
-    placeholder_to_real: dict[int, int] = {}
-    # Two passes: creates first (so their numbers are known), then
-    # comments (so cross-references resolve). Skips are free.
-    creates = [d for d in decisions if d.get("action") == "create"]
-    comments = [d for d in decisions if d.get("action") == "comment"]
-    skips = [d for d in decisions if d.get("action") == "skip"]
-    for d in creates:
-        if aborted: break
-        title = d.get("title") or f"[validator-internal] {dataset} :: {d.get('rule')} / {d.get('code')}"
-        body = d.get("body") or "(agent did not provide a body)"
-        try:
-            existing = _find_issue(title)
-            if existing:
-                _add_comment(existing["number"],
-                             f"_Re-hit during validation of `{dataset}` "
-                             f"(profile `{profile}`)._\n\n{body}")
-                updated += 1
-                out(f"  internal-issue #{existing['number']}: comment added "
-                    f"(agent: create→existing match by title)")
-                placeholder_to_real.setdefault(-(creates.index(d) + 1), existing["number"])
-            else:
-                num = _create_issue(title, body, ["validator-internal", "process", "agent-reviewed"])
-                created += 1
-                out(f"  internal-issue #{num}: opened ({title!r}) — agent reasoning: "
-                    f"{d.get('reasoning', '')[:160]}")
-                placeholder_to_real[-(creates.index(d) + 1)] = num
-        except Exception as e:
-            msg = f"{type(e).__name__}: {e}"
-            if "404" in msg:
-                out(f"  ! internal-issue tracking aborted (404 — token lacks issues:write on {GH_REPO})")
-                aborted = True
-            else:
-                out(f"  ! create failed for {title!r}: {msg}")
-    for d in comments:
-        if aborted: break
-        target = d.get("target_issue")
-        if target is None:
-            out(f"  ! comment decision has no target_issue; skipping ({d.get('reasoning', '')[:100]})")
-            continue
-        if target < 0:
-            target = placeholder_to_real.get(target)
-            if target is None:
-                out(f"  ! comment decision cross-references an unresolved placeholder; skipping")
-                continue
-        body = d.get("body") or (
-            f"Re-hit during validation of `{dataset}` (profile `{profile}`). "
-            f"Same underlying bug as this issue — see agent reasoning: "
-            f"{d.get('reasoning', '')}"
-        )
-        try:
-            _add_comment(target, body)
-            updated += 1
-            out(f"  internal-issue #{target}: comment added (agent: comment) — {d.get('reasoning', '')[:120]}")
-        except Exception as e:
-            msg = f"{type(e).__name__}: {e}"
-            if "404" in msg:
-                out(f"  ! comment tracking aborted (404)")
-                aborted = True
-            else:
-                out(f"  ! comment failed for #{target}: {msg}")
-    for d in skips:
-        skipped += 1
-        out(f"  internal-issue {d.get('rule')}/{d.get('code')}: skipped — {d.get('reasoning', '')[:160]}")
-    return {"created": created, "updated": updated, "skipped": skipped,
-            "aborted_404": aborted}
-
-
-def _ensure_internal_issues_simple(by_pair: dict, dataset: str, profile: str,
-                                    total: int, log_fn) -> dict:
-    """Fallback (no agentic review): one issue per dataset, dedup by
-    exact title match. This is what we used before the agent was
-    wired up; kept as a backstop for when ANTHROPIC_API_KEY is unset,
-    the SDK is missing, or the Claude call fails."""
-    out = log_fn
-    title = f"[validator-internal] {dataset}"
-    try:
-        existing = _find_issue(title)
-        if existing:
-            _add_comment(existing["number"],
-                         _build_dataset_recurrence_comment(by_pair, dataset, profile, total))
-            out(f"  internal-issue #{existing['number']}: comment added for dataset "
-                f"{dataset} ({total} occurrences, {len(by_pair)} pairs) — fallback policy")
-            return {"created": 0, "updated": 1, "pairs": len(by_pair), "total": total,
-                    "fallback": True}
-        num = _create_issue(title,
-                            _build_dataset_issue_body(by_pair, dataset, profile, total),
-                            ["validator-internal", "process"])
-        out(f"  internal-issue #{num}: opened for dataset {dataset} "
-            f"({total} occurrences, {len(by_pair)} pairs) — fallback policy")
-        return {"created": 1, "updated": 0, "pairs": len(by_pair), "total": total,
-                "fallback": True}
-    except Exception as e:
-        msg = f"{type(e).__name__}: {e}"
-        if "404" in msg:
-            out(f"  ! internal-issue tracking aborted (404 — token lacks issues:write on {GH_REPO})")
-            return {"created": 0, "updated": 0, "aborted_404": True, "fallback": True}
-        out(f"  ! internal-issue tracking for dataset {dataset} failed: {msg}")
-        return {"created": 0, "updated": 0, "error": msg, "fallback": True}
-
-
-def ensure_internal_issues(results_json: dict, dataset: str, profile: str,
-                            log_fn=None) -> dict:
-    """Scan results.json for validator-internal bugs and route them to
-    GitHub issues via an agentic review pass (Claude) that classifies,
-    dedupes against existing issues, and writes plain-language
-    explanations. Falls back to a simple one-issue-per-dataset policy
-    if the agent is unavailable.
-
-    Best-effort — swallowed exceptions return {"error": ...} so the
-    validator's verdict is never blocked on GitHub being flaky."""
-    out = log_fn or (lambda s: print(s, flush=True))
-    if not _gh_token():
-        out("  (skipping internal-issue tracking: no GH token)")
-        return {"skipped": True, "reason": "no_token"}
-
-    # Group across the whole dataset: (rule, code) → {count, sample, severity}
-    by_pair: dict[tuple[str, str], dict[str, Any]] = {}
-    total = 0
-    for asset in results_json.get("results", []):
-        for iss in (asset.get("issues") or []):
-            if not is_validator_internal_issue(iss):
-                continue
-            rule = iss.get("rule") or "?"
-            code = iss.get("code") or "UNKNOWN"
-            key = (rule, code)
-            g = by_pair.setdefault(key, {
-                "count": 0,
-                "sample_msg": scrub_secrets((iss.get("msg") or "")[:200]),
-                "severity": (iss.get("severity") or "").lower(),
-            })
-            g["count"] += 1
-            total += 1
-
-    if not by_pair:
-        return {"created": 0, "updated": 0}
-
-    # Agentic path: Claude classifies + writes the issue body.
-    try:
-        from agentic_issues import is_available as _agent_available, review_and_decide
-    except Exception as e:
-        out(f"  (agentic_issues import failed: {type(e).__name__}: {str(e)[:120]}); "
-            f"using fallback policy")
-        return _ensure_internal_issues_simple(by_pair, dataset, profile, total, out)
-
-    if not _agent_available():
-        out("  (agentic review unavailable; using fallback policy)")
-        return _ensure_internal_issues_simple(by_pair, dataset, profile, total, out)
-
-    existing = _list_existing_internal_issues()
-    out(f"  agentic review: {len(by_pair)} group(s) vs {len(existing)} existing "
-        f"validator-internal issue(s)")
-    review = review_and_decide(by_pair, dataset, profile, total, existing, log_fn=out)
-    if review is None or not review.get("decisions"):
-        return _ensure_internal_issues_simple(by_pair, dataset, profile, total, out)
-
-    if review.get("summary"):
-        out(f"  agent summary: {review['summary'][:300]}")
-    result = _execute_decisions(review["decisions"], by_pair, dataset, profile, total, out)
-    result.update({"pairs": len(by_pair), "total": total, "agentic": True})
-    return result
+"""Auto-file GitHub issues for validator-internal bugs.
+
+Mirror of `tools/hf_watch/validate.py::_ensure_validator_internal_issues`
+moved to the HF Space side so the Space can self-report tooling
+failures without depending on the GH Actions wrapper to do it.
+
+Policy reminder (from CLAUDE.md / project conventions):
+- GitHub Issues track NVIDIA-internal *tooling* problems only.
+- Customer-asset findings (real spec violations) stay on the dashboard;
+  they do NOT become issues.
+- Distinguishing the two is `is_validator_internal_issue`'s job.
+
+Token: GH_VALIDATOR_TOKEN (or GITHUB_TOKEN) — set as a Space secret.
+A fine-grained PAT with `issues: read+write` on
+`NVIDIA-dev/simready-oem-library-pm` is enough; no other scope needed.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.parse
+import urllib.request
+from typing import Any
+
+
+GH_REPO = "NVIDIA-dev/simready-oem-library-pm"
+
+# Redact token-shaped strings before they land in a (public-ish) issue.
+# Covers GitHub PATs (gh[ps]_…), HF tokens (hf_…), and long base64-ish
+# secrets. Validator log text passes through here on its way into bodies.
+_SECRET_RE = re.compile(r"gh[ps]_\w+|hf_\w+|[A-Za-z0-9+/]{40,}={0,2}")
+
+
+def scrub_secrets(text: str) -> str:
+    return _SECRET_RE.sub("[REDACTED]", text or "")
+
+
+def _gh_token() -> str | None:
+    return os.environ.get("GH_VALIDATOR_TOKEN") or os.environ.get("GITHUB_TOKEN")
+
+
+def is_validator_internal_issue(iss: dict) -> bool:
+    """Heuristic: distinguish validator-package crashes from real
+    asset findings."""
+    code = iss.get("code") or ""
+    msg = iss.get("msg") or ""
+    if code == "UNKNOWN" or code.startswith("SDK."):
+        return True
+    if "Uncaught error" in msg:
+        return True
+    if "is not registered to requirement" in msg:
+        return True
+    return False
+
+
+def _gh_request(method: str, path: str, payload: dict | None = None) -> dict | list:
+    token = _gh_token()
+    if not token:
+        raise RuntimeError("no GitHub token in env (GH_VALIDATOR_TOKEN or GITHUB_TOKEN)")
+    url = f"https://api.github.com/repos/{GH_REPO}{path}"
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "Authorization": f"Bearer {token}",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "simready-validator-space/0.1",
+    }
+    body = None
+    if payload is not None:
+        body = json.dumps(payload).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+    with urllib.request.urlopen(req, timeout=30) as r:
+        return json.loads(r.read() or "null")
+
+
+def _find_issue(title: str) -> dict | None:
+    # Strip `"` — title is untrusted and a quote would break the
+    # quoted-phrase search query (and could inject extra qualifiers).
+    safe_title = title.replace('"', "")
+    q = urllib.parse.quote(f'repo:{GH_REPO} in:title "{safe_title}" is:issue')
+    result = _gh_request("GET", f"/../../search/issues?q={q}")
+    items = (result or {}).get("items") or []
+    for it in items:
+        if it.get("title") == title:
+            return it
+    return None
+
+
+def _create_issue(title: str, body: str, labels: list[str]) -> int:
+    result = _gh_request("POST", "/issues",
+                         {"title": title, "body": body, "labels": labels})
+    return result.get("number", 0)
+
+
+def _add_comment(issue_num: int, body: str) -> None:
+    _gh_request("POST", f"/issues/{issue_num}/comments", {"body": body})
+
+
+def _build_dataset_issue_body(by_pair: dict, dataset: str, profile: str,
+                               total: int) -> str:
+    rows = "\n".join(
+        f"| `{rule}` | `{code}` | {g['severity'] or '?'} | {g['count']} | `{g['sample_msg']}` |"
+        for (rule, code), g in sorted(by_pair.items(), key=lambda kv: -kv[1]["count"])
+    )
+    return (
+        f"**Validator-internal bugs on a single dataset** — surfaced during "
+        f"automatic SimReady validation. NOT a customer-asset finding; the "
+        f"validator's own rule registration / spec loading is misbehaving "
+        f"on this dataset and emitting errors that don't map to any real "
+        f"spec violation.\n\n"
+        f"| Field | Value |\n|---|---|\n"
+        f"| Dataset | `{dataset}` |\n"
+        f"| Profile (first run) | `{profile}` |\n"
+        f"| Total internal occurrences (first run) | {total} |\n"
+        f"| Distinct (rule, code) pairs (first run) | {len(by_pair)} |\n\n"
+        f"**Breakdown** (sorted by occurrence count, descending):\n\n"
+        f"| Rule | Code | Severity | Count | Sample message |\n"
+        f"|---|---|---|---|---|\n{rows}\n\n"
+        f"---\n"
+        f"_Filed automatically by the HF Space (`tools/hf_space/github_issues.py`). "
+        f"One issue per dataset — re-validating the same dataset comments "
+        f"here with the new counts instead of opening a duplicate._"
+    )
+
+
+def _build_dataset_recurrence_comment(by_pair: dict, dataset: str, profile: str,
+                                       total: int) -> str:
+    rows = "\n".join(
+        f"| `{rule}` | `{code}` | {g['count']} |"
+        for (rule, code), g in sorted(by_pair.items(), key=lambda kv: -kv[1]["count"])
+    )
+    return (
+        f"Re-hit during validation of `{dataset}` (profile `{profile}`).\n"
+        f"This run: **{total}** internal occurrences across **{len(by_pair)}** "
+        f"distinct (rule, code) pairs.\n\n"
+        f"| Rule | Code | Count this run |\n|---|---|---|\n{rows}"
+    )
+
+
+def _list_existing_internal_issues() -> list[dict]:
+    """Pull every validator-internal issue (open + recently closed) so
+    the agent can dedupe semantically against them. Closed issues are
+    included because the same bug can come back after a fix is
+    reverted or after a regression."""
+    q = urllib.parse.quote(
+        f'repo:{GH_REPO} label:"validator-internal" is:issue')
+    try:
+        result = _gh_request("GET", f"/../../search/issues?q={q}&per_page=100")
+    except Exception:
+        return []
+    return (result or {}).get("items") or []
+
+
+def _execute_decisions(decisions: list[dict], by_pair: dict, dataset: str,
+                       profile: str, total: int, log_fn) -> dict:
+    """Carry out the agent's decisions. Returns counters."""
+    out = log_fn
+    created = updated = skipped = 0
+    aborted = False
+    # Map negative placeholder numbers → real issue numbers as `create`
+    # decisions resolve. The agent uses negatives to cross-reference
+    # decisions that share a parent issue when several groups roll up
+    # into one new bug.
+    placeholder_to_real: dict[int, int] = {}
+    # Two passes: creates first (so their numbers are known), then
+    # comments (so cross-references resolve). Skips are free.
+    creates = [d for d in decisions if d.get("action") == "create"]
+    comments = [d for d in decisions if d.get("action") == "comment"]
+    skips = [d for d in decisions if d.get("action") == "skip"]
+    for d in creates:
+        if aborted: break
+        title = d.get("title") or f"[validator-internal] {dataset} :: {d.get('rule')} / {d.get('code')}"
+        body = d.get("body") or "(agent did not provide a body)"
+        try:
+            existing = _find_issue(title)
+            if existing:
+                _add_comment(existing["number"],
+                             f"_Re-hit during validation of `{dataset}` "
+                             f"(profile `{profile}`)._\n\n{body}")
+                updated += 1
+                out(f"  internal-issue #{existing['number']}: comment added "
+                    f"(agent: create→existing match by title)")
+                placeholder_to_real.setdefault(-(creates.index(d) + 1), existing["number"])
+            else:
+                num = _create_issue(title, body, ["validator-internal", "process", "agent-reviewed"])
+                created += 1
+                out(f"  internal-issue #{num}: opened ({title!r}) — agent reasoning: "
+                    f"{d.get('reasoning', '')[:160]}")
+                placeholder_to_real[-(creates.index(d) + 1)] = num
+        except Exception as e:
+            msg = f"{type(e).__name__}: {e}"
+            if "404" in msg:
+                out(f"  ! internal-issue tracking aborted (404 — token lacks issues:write on {GH_REPO})")
+                aborted = True
+            else:
+                out(f"  ! create failed for {title!r}: {msg}")
+    for d in comments:
+        if aborted: break
+        target = d.get("target_issue")
+        if target is None:
+            out(f"  ! comment decision has no target_issue; skipping ({d.get('reasoning', '')[:100]})")
+            continue
+        if target < 0:
+            target = placeholder_to_real.get(target)
+            if target is None:
+                out(f"  ! comment decision cross-references an unresolved placeholder; skipping")
+                continue
+        body = d.get("body") or (
+            f"Re-hit during validation of `{dataset}` (profile `{profile}`). "
+            f"Same underlying bug as this issue — see agent reasoning: "
+            f"{d.get('reasoning', '')}"
+        )
+        try:
+            _add_comment(target, body)
+            updated += 1
+            out(f"  internal-issue #{target}: comment added (agent: comment) — {d.get('reasoning', '')[:120]}")
+        except Exception as e:
+            msg = f"{type(e).__name__}: {e}"
+            if "404" in msg:
+                out(f"  ! comment tracking aborted (404)")
+                aborted = True
+            else:
+                out(f"  ! comment failed for #{target}: {msg}")
+    for d in skips:
+        skipped += 1
+        out(f"  internal-issue {d.get('rule')}/{d.get('code')}: skipped — {d.get('reasoning', '')[:160]}")
+    return {"created": created, "updated": updated, "skipped": skipped,
+            "aborted_404": aborted}
+
+
+def _ensure_internal_issues_simple(by_pair: dict, dataset: str, profile: str,
+                                    total: int, log_fn) -> dict:
+    """Fallback (no agentic review): one issue per dataset, dedup by
+    exact title match. This is what we used before the agent was
+    wired up; kept as a backstop for when ANTHROPIC_API_KEY is unset,
+    the SDK is missing, or the Claude call fails."""
+    out = log_fn
+    title = f"[validator-internal] {dataset}"
+    try:
+        existing = _find_issue(title)
+        if existing:
+            _add_comment(existing["number"],
+                         _build_dataset_recurrence_comment(by_pair, dataset, profile, total))
+            out(f"  internal-issue #{existing['number']}: comment added for dataset "
+                f"{dataset} ({total} occurrences, {len(by_pair)} pairs) — fallback policy")
+            return {"created": 0, "updated": 1, "pairs": len(by_pair), "total": total,
+                    "fallback": True}
+        num = _create_issue(title,
+                            _build_dataset_issue_body(by_pair, dataset, profile, total),
+                            ["validator-internal", "process"])
+        out(f"  internal-issue #{num}: opened for dataset {dataset} "
+            f"({total} occurrences, {len(by_pair)} pairs) — fallback policy")
+        return {"created": 1, "updated": 0, "pairs": len(by_pair), "total": total,
+                "fallback": True}
+    except Exception as e:
+        msg = f"{type(e).__name__}: {e}"
+        if "404" in msg:
+            out(f"  ! internal-issue tracking aborted (404 — token lacks issues:write on {GH_REPO})")
+            return {"created": 0, "updated": 0, "aborted_404": True, "fallback": True}
+        out(f"  ! internal-issue tracking for dataset {dataset} failed: {msg}")
+        return {"created": 0, "updated": 0, "error": msg, "fallback": True}
+
+
+def ensure_internal_issues(results_json: dict, dataset: str, profile: str,
+                            log_fn=None) -> dict:
+    """Scan results.json for validator-internal bugs and route them to
+    GitHub issues via an agentic review pass (Claude) that classifies,
+    dedupes against existing issues, and writes plain-language
+    explanations. Falls back to a simple one-issue-per-dataset policy
+    if the agent is unavailable.
+
+    Best-effort — swallowed exceptions return {"error": ...} so the
+    validator's verdict is never blocked on GitHub being flaky."""
+    out = log_fn or (lambda s: print(s, flush=True))
+    if not _gh_token():
+        out("  (skipping internal-issue tracking: no GH token)")
+        return {"skipped": True, "reason": "no_token"}
+
+    # Group across the whole dataset: (rule, code) → {count, sample, severity}
+    by_pair: dict[tuple[str, str], dict[str, Any]] = {}
+    total = 0
+    for asset in results_json.get("results", []):
+        for iss in (asset.get("issues") or []):
+            if not is_validator_internal_issue(iss):
+                continue
+            rule = iss.get("rule") or "?"
+            code = iss.get("code") or "UNKNOWN"
+            key = (rule, code)
+            g = by_pair.setdefault(key, {
+                "count": 0,
+                "sample_msg": scrub_secrets((iss.get("msg") or "")[:200]),
+                "severity": (iss.get("severity") or "").lower(),
+            })
+            g["count"] += 1
+            total += 1
+
+    if not by_pair:
+        return {"created": 0, "updated": 0}
+
+    # Agentic path: Claude classifies + writes the issue body.
+    try:
+        from agentic_issues import is_available as _agent_available, review_and_decide
+    except Exception as e:
+        out(f"  (agentic_issues import failed: {type(e).__name__}: {str(e)[:120]}); "
+            f"using fallback policy")
+        return _ensure_internal_issues_simple(by_pair, dataset, profile, total, out)
+
+    if not _agent_available():
+        out("  (agentic review unavailable; using fallback policy)")
+        return _ensure_internal_issues_simple(by_pair, dataset, profile, total, out)
+
+    existing = _list_existing_internal_issues()
+    out(f"  agentic review: {len(by_pair)} group(s) vs {len(existing)} existing "
+        f"validator-internal issue(s)")
+    review = review_and_decide(by_pair, dataset, profile, total, existing, log_fn=out)
+    if review is None or not review.get("decisions"):
+        return _ensure_internal_issues_simple(by_pair, dataset, profile, total, out)
+
+    if review.get("summary"):
+        out(f"  agent summary: {review['summary'][:300]}")
+    result = _execute_decisions(review["decisions"], by_pair, dataset, profile, total, out)
+    result.update({"pairs": len(by_pair), "total": total, "agentic": True})
+    return result

tools/hf_space/plugin.json

@@ -1,11 +1,11 @@
-{
-  "$schema": "https://json.schemastore.org/claude-code-plugin",
-  "name": "deploy-hf-space",
-  "version": "0.1.0",
-  "description": "Deploy the SimReady validator HuggingFace Space (phase-3 of the PRD). Ships one slash command: /deploy-hf-space — clones the Space repo, vendors in the code from this checkout, pushes, and confirms the build went green.",
-  "author": {
-    "name": "loginowskid",
-    "email": "dloginowski@nvidia.com"
-  },
-  "homepage": "https://github.com/NVIDIA-dev/simready-oem-library-pm"
-}
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin",
+  "name": "deploy-hf-space",
+  "version": "0.1.0",
+  "description": "Deploy the SimReady validator HuggingFace Space (phase-3 of the PRD). Ships one slash command: /deploy-hf-space — clones the Space repo, vendors in the code from this checkout, pushes, and confirms the build went green.",
+  "author": {
+    "name": "loginowskid",
+    "email": "dloginowski@nvidia.com"
+  },
+  "homepage": "https://github.com/NVIDIA-dev/simready-oem-library-pm"
+}

tools/hf_space/skills/deploy-hf-space/SKILL.md

@@ -1,257 +1,257 @@
----
-name: deploy-hf-space
-description: Stand up or update the SimReady validator HuggingFace Space (nvidia/simready-validator or wherever the operator points). Handles the cp-dance the Dockerfile's COPY paths require, the hf CLI launcher gotcha, secret/hardware setup, and post-push build verification. Invoke with /deploy-hf-space [<space-slug>].
----
-
-# /deploy-hf-space
-
-Deploy or update the HuggingFace Space that runs the SimReady validator
-on HF-hosted datasets (PRD phase-3). Use this when the operator wants
-the dashboard validator running on HF infrastructure instead of (or in
-addition to) the DGXC self-hosted runner.
-
-## When to use
-
-- First-time stand-up of a new SimReady-validator Space
-- Pushing updated `tools/hf_space/runner.py`, `tools/hf_space/app.py`,
-  or `tools/validation/` after fixing something in the validator engine
-- Diagnosing a green-build-but-broken-runtime situation (the skill's
-  verification step pulls the run logs)
-
-## When NOT to use
-
-- The Space repo lives at `https://huggingface.co/spaces/<owner>/<name>`
-  — that's a separate git repo from this monorepo. This skill clones
-  it, vendors files in, and pushes. It does **not** make any changes
-  to this repo. If you're changing validator code, commit it here
-  first; this skill just sync-deploys the snapshot.
-- Customer-facing per-tenant deployments — the current Dockerfile
-  uses the Space's own `HF_TOKEN` to open verdict PRs. For
-  multi-tenant deployment (one Space per partner), additional work is
-  needed (see Open issues below).
-
-## Pre-flight
-
-The operator needs:
-
-1. **`huggingface_hub` Python package installed.** Verify with:
-   ```
-   <py> -c "import huggingface_hub; print(huggingface_hub.__version__)"
-   ```
-   where `<py>` is whichever python actually owns it. On Windows the
-   `hf.exe` launcher often points at a non-existent `C:\Python314\`
-   path — use the python directly instead of trusting `hf.exe`.
-
-2. **HF auth.** The `hf auth whoami` (or `<py> -m huggingface_hub.cli.hf
-   auth whoami`) should return the user + orgs. If not, log in:
-   ```
-   <py> -m huggingface_hub.cli.hf auth login
-   ```
-   Paste a **write-scoped** PAT from https://huggingface.co/settings/tokens
-   at the interactive prompt. **Never echo a PAT into the chat input
-   itself** — that puts it in the transcript. If the operator does, tell
-   them to immediately rotate it.
-
-3. **A Space already exists at the target slug.** This skill expects
-   the Space to be created via the HF UI first:
-   - https://huggingface.co/new-space
-   - **SDK**: Docker (required — the validator's deps don't fit
-     Gradio's default Python SDK)
-   - **Hardware**: `cpu-basic` (free) is enough for the spike; the
-     validator runs without Kit and the work is CPU-bound USD parsing
-   - **Visibility**: Private while internal-pilot
-
-4. **The `HF_TOKEN` secret is set on the Space.** Settings → Variables
-   and secrets → New secret. Required for `Open PR` mode to commit
-   verdicts back to customer datasets.
-
-If pre-flight 3 or 4 isn't done, ask the operator to do them in the
-browser, then resume. Don't attempt to create the Space via the API —
-the manual flow is what the team is set up for.
-
-## Steps for Claude when `/deploy-hf-space [<slug>]` is invoked
-
-The skill operates on the slug `<owner>/<name>` (e.g.
-`nvidia/simready-validator`). If the operator omits the slug,
-default to `nvidia/simready-validator` for the current spike.
-
-1. **Verify the Space exists and runtime is queryable.**
-   ```
-   <py> -c "
-   from huggingface_hub import HfApi
-   api = HfApi()
-   info = api.space_info('<slug>')
-   print(info.runtime, info.sdk)
-   "
-   ```
-   `sdk` must be `docker`. If it's `gradio` or `static`, refuse to
-   continue and tell the operator to recreate as Docker.
-
-2. **Stage the Space repo at `/tmp/space-stage` (or equivalent).**
-   ```
-   git clone https://huggingface.co/spaces/<slug> /tmp/space-stage
-   ```
-   The HF git-credential helper that `hf auth login --add-to-git-credential`
-   sets up handles auth. If clone prompts for a password, the operator's
-   git creds aren't wired — back to pre-flight.
-
-3. **Vendor in the deployable files.** The Dockerfile inside
-   `tools/hf_space/Dockerfile` COPYs from these paths in the build
-   context, so the Space repo root needs them mirrored:
-
-   - `tools/hf_space/Dockerfile` → Space `Dockerfile` (root)
-   - `tools/hf_space/` → Space `tools/hf_space/`
-   - `tools/validation/` → Space `tools/validation/`
-
-   In Bash:
-   ```
-   cp tools/hf_space/Dockerfile /tmp/space-stage/Dockerfile
-   mkdir -p /tmp/space-stage/tools
-   cp -r tools/hf_space /tmp/space-stage/tools/
-   cp -r tools/validation /tmp/space-stage/tools/
-   ```
-
-   **DO NOT** drop a wholesale copy of this monorepo into the Space —
-   it'd include unrelated subtrees (`docs/`, `goals/`, `clients.yaml`)
-   that don't belong in a Space and may contain secrets-shaped content.
-   Keep the COPY surface minimal.
-
-4. **Preserve the HF-side README frontmatter.** HF auto-generates a
-   `README.md` with the Space's title/emoji/sdk YAML frontmatter on
-   creation. **Keep that frontmatter intact** — rewriting the README
-   body is fine, but blowing away the frontmatter de-registers the
-   Space card. The shipped README in `tools/hf_space/README.md` is the
-   internal-docs version, NOT what should land at the Space root.
-   Build a fresh `/tmp/space-stage/README.md` that keeps HF's
-   frontmatter and adds a short body pointing back at this repo as the
-   source of truth.
-
-5. **Commit + push.**
-   ```
-   cd /tmp/space-stage
-   git add -A
-   git -c user.email=<op-email> -c user.name=<op-name> commit -m \\
-     "Update from <sha> in simready-oem-library-pm"
-   git push
-   ```
-   Use the **operator's** identity, not a bot — Spaces are usually
-   personal accounts in this team. The commit message should reference
-   the source-repo sha so the Space's history maps back.
-
-6. **Verify the build.**
-   ```
-   <py> -c "
-   from huggingface_hub import HfApi
-   info = HfApi().space_info('<slug>')
-   print(f'stage: {info.runtime.stage}')
-   print(f'sha:   {info.sha}')
-   "
-   ```
-   Stages of interest:
-   - `BUILDING` / `RUNNING_BUILDING` — wait. First build ~5 min;
-     incremental builds (when only `runner.py` / `app.py` changed,
-     not `requirements.txt` or `Dockerfile`) finish in ~1 min thanks
-     to layer cache.
-   - `RUNNING` — done. Open `https://huggingface.co/spaces/<slug>`
-     in the browser to interact.
-   - `BUILD_ERROR` / `RUNTIME_ERROR` — pull the build/run logs (see
-     step 7) and report the failing lines to the operator.
-
-7. **Pull logs if needed.** The HF API exposes the logs at:
-   ```
-   GET https://huggingface.co/api/spaces/<slug>/logs/{build,run}
-   ```
-   This is a Server-Sent Events stream — not a static endpoint. With
-   the SDK >= 1.16 use `api.fetch_logs(...)` if available; otherwise
-   open the URL via `urllib.request` with an `Authorization: Bearer
-   <token>` header and read with a short idle timeout (the stream
-   blocks indefinitely once it catches up to head).
-
-   For a one-shot dump, this Python snippet works on Windows:
-   ```python
-   import http.client, socket, json
-   from huggingface_hub import get_token
-   conn = http.client.HTTPSConnection("huggingface.co", timeout=15)
-   conn.request("GET", "/api/spaces/<slug>/logs/run",
-                headers={"Authorization": f"Bearer {get_token()}"})
-   resp = conn.getresponse()
-   buf = b""
-   try:
-       while True:
-           chunk = resp.read(2048)
-           if not chunk: break
-           buf += chunk
-   except (socket.timeout, TimeoutError):
-       pass
-   # parse SSE: each `data: {...}` line carries one log line.
-   ```
-
-## Verification of the deploy
-
-After the push lands and runtime flips to `RUNNING`:
-
-1. Open `https://huggingface.co/spaces/<slug>` in a browser.
-2. Enter a USD-native (not zip-bundled) dataset in the **Dataset** box.
-   Good smoke-test candidates:
-   - `nvidia/PhysicalAI-SimReady-Warehouse-01`
-   - Anything from the `nvidia/PhysicalAI-SimReady-*` family that ships
-     `.usd` files directly (not in archives)
-3. Leave **Profile = Robot-Body-Runnable**, **Version = 1.0.0**,
-   **Open PR unchecked** for the first run.
-4. Click **Validate**. Watch the **Log** box. Expected progression:
-   ```
-   [...] validating dataset=... profile=Robot-Body-Runnable v1.0.0
-     workdir: /tmp/hfsp-<safe-name>-XXXX
-     $ snapshot_download <repo> ...
-     validator target: /tmp/hfsp-<safe-name>-XXXX/raw
-     $ python /home/appuser/app/tools/validation/.../validate.py ...
-   [validator spec loading — ~243 lines of "Registering feature ..."]
-     Discovered N USD asset(s) under ...
-     layout: M asset(s) deviate from SimReady packaging spec ...   (if any)
-   [per-asset "validate: ..." lines]
-     PASS: K/N assets passed
-   ```
-5. If the verdict matches DGXC's verdict on the same dataset
-   (byte-for-byte on `results.json`), the cutover criterion in
-   `tools/hf_space/README.md` is met for that dataset.
-
-## Known limitations
-
-These are real constraints that bit the spike — flag them to the
-operator if the dataset they're trying to validate hits one:
-
-- **Zip-bundled datasets fail with "no USD assets".** `HF_DOWNLOAD_EXCLUDES`
-  in `runner.py` skips `.zip`, and even if we kept them, 800 × 600 MB
-  doesn't fit on `cpu-basic`'s ephemeral disk (~50 GiB). The
-  imagineio Kitchens-v1 dataset is the canonical example. Fix is to
-  add zip-streaming validation (download one zip, extract, validate,
-  delete, next) — a separate workstream.
-- **PhysX-bearing profiles are partially validated.** `--no-use-kit`
-  is hard-coded because Spaces don't have Isaac Sim. The validator's
-  P2 patch drops the resulting `physxschema_unavailable` /
-  `omnipbr_unresolved` issues so the verdict isn't artificially
-  failing, but PhysX/MDL rules that need Kit are silently not
-  exercised. To restore them, bake an `a10g-small` tier with Isaac
-  Sim wheels in the Dockerfile — different workstream.
-- **One Space, one HF_TOKEN.** Every customer's verdict PR is opened
-  by the Space's own token. Fine for internal pilot, not safe for
-  customer-facing deployment where customers shouldn't see each
-  other's commit identities. Refactor `runner.run()` to accept a
-  caller-provided token before exposing the Space externally.
-- **Validator subprocess is a single Claude-less Python invocation.**
-  The DGXC path runs the validator inside a Claude Code subprocess
-  (`tools/hf_watch/validate.py` does this) so the simready-report
-  skill's agentic decisions (profile selection, error recovery) are
-  exercised. The Space bypasses Claude entirely — calls
-  `validate.py` directly. If/when we want the agentic decisions on
-  HF too, bundle Claude Code into the Dockerfile + add an
-  `ANTHROPIC_API_KEY` Space secret.
-
-## Session memory hooks
-
-This skill is the source of truth for the deployment workflow. If the
-operator hits a step that doesn't match what's documented here (e.g.
-HF changes their Space API, hf CLI launcher works again, a new
-hardware tier appears), update **this file** rather than just patching
-the conversation. The next session that invokes `/deploy-hf-space`
-reads this file, not the old transcript.
+---
+name: deploy-hf-space
+description: Stand up or update the SimReady validator HuggingFace Space (nvidia/simready-validator or wherever the operator points). Handles the cp-dance the Dockerfile's COPY paths require, the hf CLI launcher gotcha, secret/hardware setup, and post-push build verification. Invoke with /deploy-hf-space [<space-slug>].
+---
+
+# /deploy-hf-space
+
+Deploy or update the HuggingFace Space that runs the SimReady validator
+on HF-hosted datasets (PRD phase-3). Use this when the operator wants
+the dashboard validator running on HF infrastructure instead of (or in
+addition to) the DGXC self-hosted runner.
+
+## When to use
+
+- First-time stand-up of a new SimReady-validator Space
+- Pushing updated `tools/hf_space/runner.py`, `tools/hf_space/app.py`,
+  or `tools/validation/` after fixing something in the validator engine
+- Diagnosing a green-build-but-broken-runtime situation (the skill's
+  verification step pulls the run logs)
+
+## When NOT to use
+
+- The Space repo lives at `https://huggingface.co/spaces/<owner>/<name>`
+  — that's a separate git repo from this monorepo. This skill clones
+  it, vendors files in, and pushes. It does **not** make any changes
+  to this repo. If you're changing validator code, commit it here
+  first; this skill just sync-deploys the snapshot.
+- Customer-facing per-tenant deployments — the current Dockerfile
+  uses the Space's own `HF_TOKEN` to open verdict PRs. For
+  multi-tenant deployment (one Space per partner), additional work is
+  needed (see Open issues below).
+
+## Pre-flight
+
+The operator needs:
+
+1. **`huggingface_hub` Python package installed.** Verify with:
+   ```
+   <py> -c "import huggingface_hub; print(huggingface_hub.__version__)"
+   ```
+   where `<py>` is whichever python actually owns it. On Windows the
+   `hf.exe` launcher often points at a non-existent `C:\Python314\`
+   path — use the python directly instead of trusting `hf.exe`.
+
+2. **HF auth.** The `hf auth whoami` (or `<py> -m huggingface_hub.cli.hf
+   auth whoami`) should return the user + orgs. If not, log in:
+   ```
+   <py> -m huggingface_hub.cli.hf auth login
+   ```
+   Paste a **write-scoped** PAT from https://huggingface.co/settings/tokens
+   at the interactive prompt. **Never echo a PAT into the chat input
+   itself** — that puts it in the transcript. If the operator does, tell
+   them to immediately rotate it.
+
+3. **A Space already exists at the target slug.** This skill expects
+   the Space to be created via the HF UI first:
+   - https://huggingface.co/new-space
+   - **SDK**: Docker (required — the validator's deps don't fit
+     Gradio's default Python SDK)
+   - **Hardware**: `cpu-basic` (free) is enough for the spike; the
+     validator runs without Kit and the work is CPU-bound USD parsing
+   - **Visibility**: Private while internal-pilot
+
+4. **The `HF_TOKEN` secret is set on the Space.** Settings → Variables
+   and secrets → New secret. Required for `Open PR` mode to commit
+   verdicts back to customer datasets.
+
+If pre-flight 3 or 4 isn't done, ask the operator to do them in the
+browser, then resume. Don't attempt to create the Space via the API —
+the manual flow is what the team is set up for.
+
+## Steps for Claude when `/deploy-hf-space [<slug>]` is invoked
+
+The skill operates on the slug `<owner>/<name>` (e.g.
+`nvidia/simready-validator`). If the operator omits the slug,
+default to `nvidia/simready-validator` for the current spike.
+
+1. **Verify the Space exists and runtime is queryable.**
+   ```
+   <py> -c "
+   from huggingface_hub import HfApi
+   api = HfApi()
+   info = api.space_info('<slug>')
+   print(info.runtime, info.sdk)
+   "
+   ```
+   `sdk` must be `docker`. If it's `gradio` or `static`, refuse to
+   continue and tell the operator to recreate as Docker.
+
+2. **Stage the Space repo at `/tmp/space-stage` (or equivalent).**
+   ```
+   git clone https://huggingface.co/spaces/<slug> /tmp/space-stage
+   ```
+   The HF git-credential helper that `hf auth login --add-to-git-credential`
+   sets up handles auth. If clone prompts for a password, the operator's
+   git creds aren't wired — back to pre-flight.
+
+3. **Vendor in the deployable files.** The Dockerfile inside
+   `tools/hf_space/Dockerfile` COPYs from these paths in the build
+   context, so the Space repo root needs them mirrored:
+
+   - `tools/hf_space/Dockerfile` → Space `Dockerfile` (root)
+   - `tools/hf_space/` → Space `tools/hf_space/`
+   - `tools/validation/` → Space `tools/validation/`
+
+   In Bash:
+   ```
+   cp tools/hf_space/Dockerfile /tmp/space-stage/Dockerfile
+   mkdir -p /tmp/space-stage/tools
+   cp -r tools/hf_space /tmp/space-stage/tools/
+   cp -r tools/validation /tmp/space-stage/tools/
+   ```
+
+   **DO NOT** drop a wholesale copy of this monorepo into the Space —
+   it'd include unrelated subtrees (`docs/`, `goals/`, `clients.yaml`)
+   that don't belong in a Space and may contain secrets-shaped content.
+   Keep the COPY surface minimal.
+
+4. **Preserve the HF-side README frontmatter.** HF auto-generates a
+   `README.md` with the Space's title/emoji/sdk YAML frontmatter on
+   creation. **Keep that frontmatter intact** — rewriting the README
+   body is fine, but blowing away the frontmatter de-registers the
+   Space card. The shipped README in `tools/hf_space/README.md` is the
+   internal-docs version, NOT what should land at the Space root.
+   Build a fresh `/tmp/space-stage/README.md` that keeps HF's
+   frontmatter and adds a short body pointing back at this repo as the
+   source of truth.
+
+5. **Commit + push.**
+   ```
+   cd /tmp/space-stage
+   git add -A
+   git -c user.email=<op-email> -c user.name=<op-name> commit -m \\
+     "Update from <sha> in simready-oem-library-pm"
+   git push
+   ```
+   Use the **operator's** identity, not a bot — Spaces are usually
+   personal accounts in this team. The commit message should reference
+   the source-repo sha so the Space's history maps back.
+
+6. **Verify the build.**
+   ```
+   <py> -c "
+   from huggingface_hub import HfApi
+   info = HfApi().space_info('<slug>')
+   print(f'stage: {info.runtime.stage}')
+   print(f'sha:   {info.sha}')
+   "
+   ```
+   Stages of interest:
+   - `BUILDING` / `RUNNING_BUILDING` — wait. First build ~5 min;
+     incremental builds (when only `runner.py` / `app.py` changed,
+     not `requirements.txt` or `Dockerfile`) finish in ~1 min thanks
+     to layer cache.
+   - `RUNNING` — done. Open `https://huggingface.co/spaces/<slug>`
+     in the browser to interact.
+   - `BUILD_ERROR` / `RUNTIME_ERROR` — pull the build/run logs (see
+     step 7) and report the failing lines to the operator.
+
+7. **Pull logs if needed.** The HF API exposes the logs at:
+   ```
+   GET https://huggingface.co/api/spaces/<slug>/logs/{build,run}
+   ```
+   This is a Server-Sent Events stream — not a static endpoint. With
+   the SDK >= 1.16 use `api.fetch_logs(...)` if available; otherwise
+   open the URL via `urllib.request` with an `Authorization: Bearer
+   <token>` header and read with a short idle timeout (the stream
+   blocks indefinitely once it catches up to head).
+
+   For a one-shot dump, this Python snippet works on Windows:
+   ```python
+   import http.client, socket, json
+   from huggingface_hub import get_token
+   conn = http.client.HTTPSConnection("huggingface.co", timeout=15)
+   conn.request("GET", "/api/spaces/<slug>/logs/run",
+                headers={"Authorization": f"Bearer {get_token()}"})
+   resp = conn.getresponse()
+   buf = b""
+   try:
+       while True:
+           chunk = resp.read(2048)
+           if not chunk: break
+           buf += chunk
+   except (socket.timeout, TimeoutError):
+       pass
+   # parse SSE: each `data: {...}` line carries one log line.
+   ```
+
+## Verification of the deploy
+
+After the push lands and runtime flips to `RUNNING`:
+
+1. Open `https://huggingface.co/spaces/<slug>` in a browser.
+2. Enter a USD-native (not zip-bundled) dataset in the **Dataset** box.
+   Good smoke-test candidates:
+   - `nvidia/PhysicalAI-SimReady-Warehouse-01`
+   - Anything from the `nvidia/PhysicalAI-SimReady-*` family that ships
+     `.usd` files directly (not in archives)
+3. Leave **Profile = Robot-Body-Runnable**, **Version = 1.0.0**,
+   **Open PR unchecked** for the first run.
+4. Click **Validate**. Watch the **Log** box. Expected progression:
+   ```
+   [...] validating dataset=... profile=Robot-Body-Runnable v1.0.0
+     workdir: /tmp/hfsp-<safe-name>-XXXX
+     $ snapshot_download <repo> ...
+     validator target: /tmp/hfsp-<safe-name>-XXXX/raw
+     $ python /home/appuser/app/tools/validation/.../validate.py ...
+   [validator spec loading — ~243 lines of "Registering feature ..."]
+     Discovered N USD asset(s) under ...
+     layout: M asset(s) deviate from SimReady packaging spec ...   (if any)
+   [per-asset "validate: ..." lines]
+     PASS: K/N assets passed
+   ```
+5. If the verdict matches DGXC's verdict on the same dataset
+   (byte-for-byte on `results.json`), the cutover criterion in
+   `tools/hf_space/README.md` is met for that dataset.
+
+## Known limitations
+
+These are real constraints that bit the spike — flag them to the
+operator if the dataset they're trying to validate hits one:
+
+- **Zip-bundled datasets fail with "no USD assets".** `HF_DOWNLOAD_EXCLUDES`
+  in `runner.py` skips `.zip`, and even if we kept them, 800 × 600 MB
+  doesn't fit on `cpu-basic`'s ephemeral disk (~50 GiB). The
+  imagineio Kitchens-v1 dataset is the canonical example. Fix is to
+  add zip-streaming validation (download one zip, extract, validate,
+  delete, next) — a separate workstream.
+- **PhysX-bearing profiles are partially validated.** `--no-use-kit`
+  is hard-coded because Spaces don't have Isaac Sim. The validator's
+  P2 patch drops the resulting `physxschema_unavailable` /
+  `omnipbr_unresolved` issues so the verdict isn't artificially
+  failing, but PhysX/MDL rules that need Kit are silently not
+  exercised. To restore them, bake an `a10g-small` tier with Isaac
+  Sim wheels in the Dockerfile — different workstream.
+- **One Space, one HF_TOKEN.** Every customer's verdict PR is opened
+  by the Space's own token. Fine for internal pilot, not safe for
+  customer-facing deployment where customers shouldn't see each
+  other's commit identities. Refactor `runner.run()` to accept a
+  caller-provided token before exposing the Space externally.
+- **Validator subprocess is a single Claude-less Python invocation.**
+  The DGXC path runs the validator inside a Claude Code subprocess
+  (`tools/hf_watch/validate.py` does this) so the simready-report
+  skill's agentic decisions (profile selection, error recovery) are
+  exercised. The Space bypasses Claude entirely — calls
+  `validate.py` directly. If/when we want the agentic decisions on
+  HF too, bundle Claude Code into the Dockerfile + add an
+  `ANTHROPIC_API_KEY` Space secret.
+
+## Session memory hooks
+
+This skill is the source of truth for the deployment workflow. If the
+operator hits a step that doesn't match what's documented here (e.g.
+HF changes their Space API, hf CLI launcher works again, a new
+hardware tier appears), update **this file** rather than just patching
+the conversation. The next session that invokes `/deploy-hf-space`
+reads this file, not the old transcript.

tools/hf_space/test_discover_dgxc.py

@@ -1,142 +1,142 @@
-"""DGXC discovery verifier — exercise the new recursive discover_assets
-against four synthetic layouts. Self-contained: imports validate.py with
-SIMREADY_INSIDE_KIT + SIMREADY_FOUNDATIONS_PATH already set so the bootstrap
-gate clears.
-
-Usage on the pod:
-    export SIMREADY_FOUNDATIONS_PATH=/home/horde/.simready/simready_foundations
-    /home/horde/.simready/venv/bin/python3 test_discover_dgxc.py
-"""
-from __future__ import annotations
-
-import os
-import sys
-import tempfile
-from pathlib import Path
-
-# Skip the Kit re-exec gate (we're testing pure-Python discovery, no Kit).
-os.environ.setdefault("SIMREADY_INSIDE_KIT", "1")
-
-# Resolve the repo: env var first (DGXC ad-hoc run), then assume the
-# script lives inside a checkout (workflow / local).
-_env_repo = os.environ.get("SIMREADY_REPO")
-if _env_repo:
-    REPO = Path(_env_repo)
-else:
-    REPO = Path(__file__).resolve().parents[2]
-SKILL = REPO / "tools" / "validation" / "plugins" / "simready-report" / "skills" / "simready-report"
-if not SKILL.is_dir():
-    raise SystemExit(
-        f"Validator skill dir not found at {SKILL}. "
-        f"Set SIMREADY_REPO to the simready-oem-library-pm checkout root."
-    )
-sys.path.insert(0, str(SKILL))
-
-import validate as v  # noqa: E402
-
-CASES = [
-    # (label, build_tree, expected_assets, expected_finding_codes)
-    ("well_shaped",
-     lambda root: [
-         (root / "well_shaped" / "well_shaped.usda", "interface"),
-         (root / "well_shaped" / "Geometry" / "mesh.usda", "sublayer (Geometry)"),
-         (root / "well_shaped" / "Materials" / "mat.usda", "sublayer (Materials)"),
-     ],
-     # Old behavior preserved: only the bundle interface is returned.
-     ["well_shaped/well_shaped.usda"],
-     []),
-    ("flat",
-     lambda root: [
-         (root / "flat" / "scene_a.usda", "root-level USD, no bundle"),
-         (root / "flat" / "scene_b.usda", "root-level USD, no bundle"),
-     ],
-     # New behavior: both found, both tagged as non-standard.
-     ["flat/scene_a.usda", "flat/scene_b.usda"],
-     ["LAYOUT.NON_STANDARD_BUNDLE", "LAYOUT.NON_STANDARD_BUNDLE"]),
-    ("deep",
-     lambda root: [
-         (root / "deep" / "team1" / "v1" / "scenes" / "render_target.usda",
-          "deeply-nested USD, no bundle wrapper"),
-     ],
-     # New behavior: found at depth, flagged.
-     ["deep/team1/v1/scenes/render_target.usda"],
-     ["LAYOUT.NON_STANDARD_BUNDLE"]),
-    ("mixed",
-     lambda root: [
-         (root / "mixed" / "proper_bundle" / "proper_bundle.usda", "interface"),
-         (root / "mixed" / "proper_bundle" / "Geometry" / "g.usda", "sublayer"),
-         (root / "mixed" / "orphan.usda", "standalone — not a bundle"),
-     ],
-     # Bundle interface and the orphan validate; sublayer excluded; orphan flagged.
-     ["mixed/orphan.usda", "mixed/proper_bundle/proper_bundle.usda"],
-     ["LAYOUT.NON_STANDARD_BUNDLE"]),
-    # Real-world layout from Aperdata's Kitchen-01 dataset:
-    # `<top_dir>/<asset>.usd` for the top-level interface plus a
-    # `<top_dir>/SubUSDs/<many>.usd` sublayer tree. The interface
-    # stem (`Indoor`) doesn't match the dir name (`0_Kitchen_Indoor`),
-    # so older logic missed the SubUSDs filter and counted them as
-    # standalone assets — Aperdata went from 23 expected to 933
-    # validated. New logic excludes anything under a SUBLAYER_DIR
-    # ancestor structurally, regardless of bundle naming.
-    ("aperdata_kitchen",
-     lambda root: [
-         (root / "aperdata_kitchen" / "0_Kitchen_Indoor" / "Indoor.usda", "interface (stem != parent dir)"),
-         (root / "aperdata_kitchen" / "0_Kitchen_Indoor" / "SubUSDs" / "CL06.usda", "sublayer (under SubUSDs)"),
-         (root / "aperdata_kitchen" / "0_Kitchen_Indoor" / "SubUSDs" / "CL06_1.usda", "sublayer (under SubUSDs)"),
-         (root / "aperdata_kitchen" / "0_Kitchen_Indoor" / "SubUSDs" / "DEC_large_leaf.usda", "sublayer (under SubUSDs)"),
-         (root / "aperdata_kitchen" / "mug_handheld" / "Collected_dining_mug_handheld" / "dining_mug_handheld.usda",
-          "interface in nested Collected_* dir"),
-     ],
-     # Only the two interface USDs validate. SubUSDs/* are excluded
-     # structurally. The deep mug_handheld interface IS the only
-     # candidate in its top-level dir, so it counts as a bundle
-     # interface (no layout warning). Indoor.usd is also the only
-     # candidate under 0_Kitchen_Indoor → no warning.
-     [
-         "aperdata_kitchen/0_Kitchen_Indoor/Indoor.usda",
-         "aperdata_kitchen/mug_handheld/Collected_dining_mug_handheld/dining_mug_handheld.usda",
-     ],
-     []),
-]
-
-
-def _normalize(paths: list[Path], root: Path) -> list[str]:
-    return sorted(str(p.relative_to(root)).replace("\\", "/") for p in paths)
-
-
-def main() -> int:
-    failures = 0
-    with tempfile.TemporaryDirectory(prefix="sr-discover-test-") as td:
-        root = Path(td)
-        for label, build, expected_assets, expected_codes in CASES:
-            case_dir = root / label
-            case_dir.mkdir(parents=True, exist_ok=True)
-            for usd_path, _why in build(root):
-                usd_path.parent.mkdir(parents=True, exist_ok=True)
-                usd_path.write_text("()")  # empty stage — discover_assets is pure FS walk
-            assets, findings = v.discover_assets(case_dir)
-            got_assets = _normalize(assets, root)
-            got_codes = sorted([f["code"] for f in findings])
-            exp_assets = sorted(expected_assets)
-            exp_codes = sorted(expected_codes)
-            ok = (got_assets == exp_assets and got_codes == exp_codes)
-            mark = "PASS" if ok else "FAIL"
-            print(f"  [{mark}] {label}")
-            print(f"        expected assets:   {exp_assets}")
-            print(f"        got assets:        {got_assets}")
-            print(f"        expected findings: {exp_codes}")
-            print(f"        got findings:      {got_codes}")
-            if not ok:
-                failures += 1
-                for f in findings:
-                    print(f"        finding detail: {f}")
-    print()
-    if failures:
-        print(f"{failures} case(s) FAILED")
-        return 1
-    print("all cases passed — recursive discovery + layout findings working end-to-end on DGXC")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+"""DGXC discovery verifier — exercise the new recursive discover_assets
+against four synthetic layouts. Self-contained: imports validate.py with
+SIMREADY_INSIDE_KIT + SIMREADY_FOUNDATIONS_PATH already set so the bootstrap
+gate clears.
+
+Usage on the pod:
+    export SIMREADY_FOUNDATIONS_PATH=/home/horde/.simready/simready_foundations
+    /home/horde/.simready/venv/bin/python3 test_discover_dgxc.py
+"""
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+# Skip the Kit re-exec gate (we're testing pure-Python discovery, no Kit).
+os.environ.setdefault("SIMREADY_INSIDE_KIT", "1")
+
+# Resolve the repo: env var first (DGXC ad-hoc run), then assume the
+# script lives inside a checkout (workflow / local).
+_env_repo = os.environ.get("SIMREADY_REPO")
+if _env_repo:
+    REPO = Path(_env_repo)
+else:
+    REPO = Path(__file__).resolve().parents[2]
+SKILL = REPO / "tools" / "validation" / "plugins" / "simready-report" / "skills" / "simready-report"
+if not SKILL.is_dir():
+    raise SystemExit(
+        f"Validator skill dir not found at {SKILL}. "
+        f"Set SIMREADY_REPO to the simready-oem-library-pm checkout root."
+    )
+sys.path.insert(0, str(SKILL))
+
+import validate as v  # noqa: E402
+
+CASES = [
+    # (label, build_tree, expected_assets, expected_finding_codes)
+    ("well_shaped",
+     lambda root: [
+         (root / "well_shaped" / "well_shaped.usda", "interface"),
+         (root / "well_shaped" / "Geometry" / "mesh.usda", "sublayer (Geometry)"),
+         (root / "well_shaped" / "Materials" / "mat.usda", "sublayer (Materials)"),
+     ],
+     # Old behavior preserved: only the bundle interface is returned.
+     ["well_shaped/well_shaped.usda"],
+     []),
+    ("flat",
+     lambda root: [
+         (root / "flat" / "scene_a.usda", "root-level USD, no bundle"),
+         (root / "flat" / "scene_b.usda", "root-level USD, no bundle"),
+     ],
+     # New behavior: both found, both tagged as non-standard.
+     ["flat/scene_a.usda", "flat/scene_b.usda"],
+     ["LAYOUT.NON_STANDARD_BUNDLE", "LAYOUT.NON_STANDARD_BUNDLE"]),
+    ("deep",
+     lambda root: [
+         (root / "deep" / "team1" / "v1" / "scenes" / "render_target.usda",
+          "deeply-nested USD, no bundle wrapper"),
+     ],
+     # New behavior: found at depth, flagged.
+     ["deep/team1/v1/scenes/render_target.usda"],
+     ["LAYOUT.NON_STANDARD_BUNDLE"]),
+    ("mixed",
+     lambda root: [
+         (root / "mixed" / "proper_bundle" / "proper_bundle.usda", "interface"),
+         (root / "mixed" / "proper_bundle" / "Geometry" / "g.usda", "sublayer"),
+         (root / "mixed" / "orphan.usda", "standalone — not a bundle"),
+     ],
+     # Bundle interface and the orphan validate; sublayer excluded; orphan flagged.
+     ["mixed/orphan.usda", "mixed/proper_bundle/proper_bundle.usda"],
+     ["LAYOUT.NON_STANDARD_BUNDLE"]),
+    # Real-world layout from Aperdata's Kitchen-01 dataset:
+    # `<top_dir>/<asset>.usd` for the top-level interface plus a
+    # `<top_dir>/SubUSDs/<many>.usd` sublayer tree. The interface
+    # stem (`Indoor`) doesn't match the dir name (`0_Kitchen_Indoor`),
+    # so older logic missed the SubUSDs filter and counted them as
+    # standalone assets — Aperdata went from 23 expected to 933
+    # validated. New logic excludes anything under a SUBLAYER_DIR
+    # ancestor structurally, regardless of bundle naming.
+    ("aperdata_kitchen",
+     lambda root: [
+         (root / "aperdata_kitchen" / "0_Kitchen_Indoor" / "Indoor.usda", "interface (stem != parent dir)"),
+         (root / "aperdata_kitchen" / "0_Kitchen_Indoor" / "SubUSDs" / "CL06.usda", "sublayer (under SubUSDs)"),
+         (root / "aperdata_kitchen" / "0_Kitchen_Indoor" / "SubUSDs" / "CL06_1.usda", "sublayer (under SubUSDs)"),
+         (root / "aperdata_kitchen" / "0_Kitchen_Indoor" / "SubUSDs" / "DEC_large_leaf.usda", "sublayer (under SubUSDs)"),
+         (root / "aperdata_kitchen" / "mug_handheld" / "Collected_dining_mug_handheld" / "dining_mug_handheld.usda",
+          "interface in nested Collected_* dir"),
+     ],
+     # Only the two interface USDs validate. SubUSDs/* are excluded
+     # structurally. The deep mug_handheld interface IS the only
+     # candidate in its top-level dir, so it counts as a bundle
+     # interface (no layout warning). Indoor.usd is also the only
+     # candidate under 0_Kitchen_Indoor → no warning.
+     [
+         "aperdata_kitchen/0_Kitchen_Indoor/Indoor.usda",
+         "aperdata_kitchen/mug_handheld/Collected_dining_mug_handheld/dining_mug_handheld.usda",
+     ],
+     []),
+]
+
+
+def _normalize(paths: list[Path], root: Path) -> list[str]:
+    return sorted(str(p.relative_to(root)).replace("\\", "/") for p in paths)
+
+
+def main() -> int:
+    failures = 0
+    with tempfile.TemporaryDirectory(prefix="sr-discover-test-") as td:
+        root = Path(td)
+        for label, build, expected_assets, expected_codes in CASES:
+            case_dir = root / label
+            case_dir.mkdir(parents=True, exist_ok=True)
+            for usd_path, _why in build(root):
+                usd_path.parent.mkdir(parents=True, exist_ok=True)
+                usd_path.write_text("()")  # empty stage — discover_assets is pure FS walk
+            assets, findings = v.discover_assets(case_dir)
+            got_assets = _normalize(assets, root)
+            got_codes = sorted([f["code"] for f in findings])
+            exp_assets = sorted(expected_assets)
+            exp_codes = sorted(expected_codes)
+            ok = (got_assets == exp_assets and got_codes == exp_codes)
+            mark = "PASS" if ok else "FAIL"
+            print(f"  [{mark}] {label}")
+            print(f"        expected assets:   {exp_assets}")
+            print(f"        got assets:        {got_assets}")
+            print(f"        expected findings: {exp_codes}")
+            print(f"        got findings:      {got_codes}")
+            if not ok:
+                failures += 1
+                for f in findings:
+                    print(f"        finding detail: {f}")
+    print()
+    if failures:
+        print(f"{failures} case(s) FAILED")
+        return 1
+    print("all cases passed — recursive discovery + layout findings working end-to-end on DGXC")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/validation/.claude-plugin/marketplace.json

@@ -1,16 +1,16 @@
-{
-  "$schema": "https://json.schemastore.org/claude-code-marketplace",
-  "name": "simready-playbook",
-  "description": "SimReady asset pipeline plugins for Claude Code.",
-  "owner": {
-    "name": "dloginowski",
-    "email": "dloginowski@nvidia.com"
-  },
-  "plugins": [
-    {
-      "name": "simready-report",
-      "source": "./plugins/simready-report",
-      "description": "SimReady asset pipeline tooling. Provides /simready-report (validation + HTML dashboard) and /simready-package (standalone simready ingest packaging)."
-    }
-  ]
-}
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace",
+  "name": "simready-playbook",
+  "description": "SimReady asset pipeline plugins for Claude Code.",
+  "owner": {
+    "name": "dloginowski",
+    "email": "dloginowski@nvidia.com"
+  },
+  "plugins": [
+    {
+      "name": "simready-report",
+      "source": "./plugins/simready-report",
+      "description": "SimReady asset pipeline tooling. Provides /simready-report (validation + HTML dashboard) and /simready-package (standalone simready ingest packaging)."
+    }
+  ]
+}

tools/validation/PROBLEMS.md

@@ -1,327 +1,327 @@
-# Known problems
-
-Issues encountered with the validation pipeline, the foundation specs, or the
-SimReady SDK that aren't bugs in this repo's code but affect the report
-output. Each entry: **symptom → root cause → workaround / how to address →
-status**.
-
-When you hit a new issue, add it here. Keep the list short — fold resolved
-items into git history once they're fixed.
-
----
-
-## P1 — Profiles silently drop features that aren't registered
-
-**Symptom.** A profile loads with far fewer features than its
-`profiles.toml` declares. Concretely on the current foundations checkout:
-
-| Profile | Declared in `profiles.toml` | Loaded by validator | Dropped feature IDs |
-|---|---|---|---|
-| `Robot-Body-Runnable` v1.0.0 | 5 | **1** | `FET004_ROBOT_PHYSX` v0.2.0, `FET021_ROBOT_CORE_RUNNABLE` v0.2.0, `FET022_DRIVEN_JOINTS_PHYSX` v0.1.0, `FET024_BASE_ARTICULATION_PHYSX` v0.1.0 |
-| `Robot-Body-Isaac` v1.0.0 | 6 | 2 | `FET004_ROBOT_PHYSX` v0.2.0, `FET021_ROBOT_CORE_ISAAC` v0.2.0, `FET022_DRIVEN_JOINTS_ISAAC` v0.1.0, `FET024_BASE_ARTICULATION_PHYSX` v0.1.0 |
-| `Robot-Body-Neutral` v1.0.0 | 5 | 3 | `FET022_DRIVEN_JOINTS_NEUTRAL` v0.1.0, `FET024_BASE_ARTICULATION_NEUTRAL` v0.1.0 |
-| `Prop-Robotics-Neutral` v2.0.0 | 6 | 5 | `FET006_BASE_MDL` v0.1.0 |
-
-What's actually registered for the FET02x family (after `repo
-usd_profiles_codegen`):
-
-- `fet_021_robot_core` v0.2.0 (no variant suffix)
-- `fet_022_driven_joints` v0.1.0
-- `fet_023_robot_materials` v0.1.0
-- `fet_024_base_articulation` v0.1.0
-
-And for FET004/FET006 the only `_BASE_NEUTRAL` / `_BASE_USDPREVIEW`
-forms are registered, not the `_ROBOT_PHYSX` / `_BASE_MDL` variants the
-profiles ask for.
-
-**Root cause.** Profile entries in
-`<foundations>/nv_core/sr_specs/docs/profiles/profiles.toml` reference
-variant feature IDs that the local foundations registry doesn't ship — e.g.
-profiles ask for `FET021_ROBOT_CORE_RUNNABLE`, `FET022_DRIVEN_JOINTS_PHYSX`,
-`FET004_ROBOT_PHYSX`, `FET024_BASE_ARTICULATION_NEUTRAL`. What is actually
-registered (after `repo usd_profiles_codegen` runs against our checkout) is
-only the unsuffixed `_BASE_NEUTRAL` / `_BASE_USDPREVIEW` / `_CORE` /
-`_BASE_ISAACSIM` variants. The variant features the profiles ask for are
-silently absent.
-
-`omni.asset_validator.ProfileRegistry` resolves features by ID + version and
-silently drops any it can't find. There's no warning emitted at profile
-load time.
-
-**Verified the gap is local, not universal.** Sample reports from another
-SimReady environment (Fanuc content, sr9iar.usd.usd) show all five
-declared `Robot-Body-Runnable` features actually loaded —
-`FET001_BASE_NEUTRAL` (failed), plus `FET004_ROBOT_PHYSX`,
-`FET021_ROBOT_CORE_RUNNABLE`, `FET022_DRIVEN_JOINTS_PHYSX`,
-`FET024_BASE_ARTICULATION_PHYSX`, `FET024_BASE_ARTICULATION_NEUTRAL`
-(passed). So the variants *are* registrable; our local codegen output
-just doesn't include them.
-
-**Where the variants live.** The foundation source ships JSON variant
-definitions next to each feature's markdown. For FET004:
-
-```
-docs/features/FET_004-simulate_multi_body_physics.md           (md, _BASE_NEUTRAL only)
-docs/features/FET_004_base_neutral-0.1.0-...json
-docs/features/FET_004_base_physx-0.1.0-...json
-docs/features/FET_004_base_physx-0.2.0-...json
-docs/features/FET_004_robot_physx-0.1.0-...json    <- this is the one profiles ask for
-docs/features/FET_004_robot_physx-0.2.0-...json
-```
-
-Each JSON declares an `id` (e.g. `FET004_ROBOT_PHYSX`), `version`, `path`,
-and a `requirements` list. **Our `repo usd_profiles_codegen` run only
-parses the `.md` files** — the generated
-`_build/python/omni/capabilities/_features.py` contains zero
-`_ROBOT_PHYSX` / `_BASE_PHYSX` / `_RUNNABLE` entries even though the JSON
-sources are right there.
-
-**How to address.** Three paths, in priority order:
-
-1. **Codegen — pick up the JSON variant files.** The foundations
-   `repo usd_profiles_codegen` tool needs to also enumerate
-   `FET_*_*-*-...json` files in the features directory and emit Feature
-   entries for each, not just the `Internal ID` declared in the `.md`.
-   This closes the gap without changing source data — the variants
-   already exist.
-2. **Validator — emit a warning when a profile entry doesn't resolve.**
-   `omni.asset_validator.ProfileRegistry` silently drops missing
-   features. A `WARNING:` log at profile-load time would have made this
-   bug visible from day one.
-3. **Documentation** — once #1 lands, `repo.toml`'s codegen description
-   should call out that JSON variants are part of the source of truth so
-   downstream tooling doesn't repeat the mistake.
-
-Open this with the SimReady foundations team
-(`#omni-simready` / `#simready-next-support`); cite the discrepancy
-between our local codegen output and the working Fanuc environment
-sample.
-
-**In-repo workaround.** The dashboard now surfaces the coverage gap
-explicitly: when a profile declares more features than the validator
-loaded, a banner at the top lists the missing IDs and tells the user which
-ones got silently dropped. The validation result the report shows is
-genuinely against the *loaded* feature set — running with
-`Robot-Body-Runnable` does *not* check the four declared-but-missing
-features.
-
-**Status.** Local patch applied — see "Local patch applied" below.
-Upstream codegen fix still needed. Banner workaround still in place
-for environments without the patch.
-
-### Local patch applied
-
-A patch lives in
-`plugins/simready-report/skills/simready-report/validate.py` —
-function `_patch_register_json_variant_features()`. It runs at module
-load (so worker processes pick it up too) right after
-`import omni.asset_validator as oav`. It is loud about itself: every
-run prints a `[PATCH P1] FeatureRegistry: +N JSON-variant feature(s)
-... ProfileRegistry: rebuilt feature lists for M profile(s) ...`
-line so it's never invisible.
-
-**Concretely on the Yaskawa-local checkout** the patch lifts:
-- FeatureRegistry: 11 features → 30 features (+19 from JSON variants).
-- Robot-Body-Runnable v1.0.0: 1 feature / 8 requirements → **5 / 41**.
-- 11 profiles got their `.features` lists rebuilt; +24 feature
-  references appended in total.
-
-**Exactly what the patch does**, step by step:
-
-1. **Discover variant JSON files.** Globs
-   `<foundations>/nv_core/sr_specs/docs/features/FET_*.json`. The
-   filename styles in this repo are inconsistent
-   (`FET_021-robot_core_isaac-0.1.0.json`,
-   `FET_021_robot_core_runnable_0.2.0.json`,
-   `FET_004_base_physx-0.2.0-simulate_multi_body_phyics.json`), so we
-   ignore the filename and read the `id` + `version` fields from the
-   JSON content.
-
-2. **Build a Requirement code lookup.** `r.code -> r` for every
-   `Requirement` in `omni.asset_validator.RequirementsRegistry()`.
-   The JSON variants list dotted code strings like `"RB.COL.003"`,
-   `"DJ.001"`, `"BA.002"` — those are looked up here.
-
-3. **Construct a Feature-protocol object per JSON variant.**
-   `omni.asset_validator._features.Feature` is a `typing.Protocol`
-   declaring `id: str, version: str, path: str, requirements: list`.
-   We use a frozen dataclass that satisfies the protocol structurally:
-
-   ```python
-   @dataclass(frozen=True)
-   class _PatchedFeature:
-       id: str
-       version: str
-       path: str
-       requirements: list
-   ```
-
-4. **Skip duplicates and unresolvable variants.** If
-   `FeatureRegistry.find(fid, fver)` already returns something, skip
-   (don't double-register). If any of the JSON's requirement code
-   strings doesn't resolve in the code lookup, skip the whole feature
-   and record it in `unresolved_codes`. (Currently zero unresolved on
-   our checkout — every JSON variant's required codes exist.)
-
-5. **Register via `FeatureRegistry().add(feat)`.** The internal
-   `create_key` uses `.id` + `.version` so our dataclass satisfies it.
-
-6. **Re-resolve every profile's feature list — the critical step.**
-   `Profile` is a frozen dataclass, so we can't reassign
-   `profile.features`. But the field is a *mutable list*, and the
-   freeze only prevents field reassignment, not mutation of held
-   collections. So for every entry in `profiles.toml`'s declared
-   features that isn't already in the live profile, we look it up in
-   the now-fuller `FeatureRegistry` and `profile.features.append(...)`
-   in place. **Without this step the patch is invisible** — adding to
-   `FeatureRegistry` after profiles are already built doesn't
-   retroactively join existing Profile objects.
-
-**What the patch does NOT touch**: foundation source files, the
-codegen tool, generated `_features.py`, profile definitions in
-`profiles.toml`, or any rule code. The local patch is purely in our
-validation runner.
-
-**Remove the patch when**: the foundation `repo usd_profiles_codegen`
-tool is updated to enumerate JSON variant files alongside the
-markdown. Once `_features.py` carries every variant on its own,
-delete `_patch_register_json_variant_features()` and its call site.
-
----
-
-## P2 — Public ur10 sample asset fails current foundation specs
-
-**Symptom.** Running `/simready-report` against the public ur10 sample
-in
-`simready_foundations/sample_content/common_assets/robots_general/ur10/`
-(release `2026.04.0`, commit `805d2c5`) reports failures on every
-variant when validated against its declared profile (or against
-Robot-Body-Runnable cross-profile). Concretely, against each interface
-USD's declared profile, with `--use-kit` so PhysX rules actually run:
-
-| Variant interface | Declared profile | Result | Failing requirements |
-|---|---|---|---|
-| `simready_usd/ur10.usda` | Robot-Body-Neutral v1.0.0 | **PASS** | — |
-| `simready_physx_usd/ur10.usda` | Robot-Body-Physx v1.0.0 | **FAIL** | (profile evaluates 0 features against the asset; `features_summary` empty in JSON output) |
-| `simready_isaac_usd/ur10.usda` | Robot-Body-Isaac v1.0.0 | **FAIL** | `RC.005` (`VerifyRobotPhysicsAttributesSourceLayer`), `RC.008` (`robot-type`), `RC.009` (`root-joint-pinned`), `DJ.010`, `ISA.001` |
-
-Under the cross-profile `Robot-Body-Runnable` run, Neutral and PhysX
-variants additionally light up with `RC.007` (`robot-schema` — no
-`IsaacRobotAPI` on the default prim) because neither of those variants
-applies `IsaacRobotAPI`, only the Isaac variant does.
-
-**Root cause.** Asset-side metadata gaps and layer-organization issues
-in the shipped public sample, *not* validator or skill code. The asset
-file is tracked by Git LFS at the same OID as the release (`b30f9c1b…`
-for `simready_isaac_usd/payloads/base.usda`), so no in-tree edit
-caused this. Each asset's `customLayerData.SimReady_Metadata.validation`
-records `validated_features` against a snapshot dated **2026-01-09**;
-between then and the current `805d2c5` foundation specs the rules in
-question were tightened (or added), so the asset that passed in
-January no longer passes today. Specifically:
-
-- **`RC.008` (`robot-type`)** — `simready_isaac_usd/payloads/base.usda`
-  lines 81-83 declare `token isaac:robotType` with **no value**. The
-  current rule requires a valid schema-defined token (e.g.
-  `"Manipulator"`, `"End Effector"`); the placeholder `"Default"` and
-  the absent-value case both fail.
-- **`RC.009` (`root-joint-pinned`)** — depends on `isaac:robotType`
-  to decide whether the root joint must be pinned. The asset's
-  `root_joint` *is* a `PhysicsFixedJoint` with empty `physics:body0`
-  (pinned to world, correct for a Manipulator), but without a valid
-  `robotType` value the rule can't evaluate and fails.
-- **`RC.005` (`VerifyRobotPhysicsAttributesSourceLayer`)** — physics
-  attributes (`physics:axis`, `physics:mass`, `physics:centerOfMass`,
-  `physics:diagonalInertia`, `physics:principalAxes`) on each robot
-  link are authored in *both* `payloads/base.usda` and
-  `payloads/Physics/physics.usda`. The current rule wants them in the
-  physics payload only.
-- **PhysX variant empty `features_summary`** — Robot-Body-Physx v1.0.0
-  evaluates zero features against the asset, suggesting the profile's
-  declared feature set no longer matches what the asset has stamped
-  (related to P1, but for a different feature family).
-
-**How to address.** Asset fixes belong in
-`github.com/NVIDIA/simready-foundation`, not here:
-
-1. **`RC.008`/`RC.009`** — *verified one-liner*. In
-   `simready_isaac_usd/payloads/base.usda` line 81, change
-   `token isaac:robotType (…)` to
-   `token isaac:robotType = "Manipulator" (…)`. Verified locally with
-   `--use-kit`:
-   - Against `Robot-Body-Isaac`, `FET021_ROBOT_CORE_ISAAC` failing
-     codes went from `[RC.005, RC.008, RC.009]` →
-     **`[RC.003, RC.005]`** (RC.008 and RC.009 cleared; RC.003 was
-     previously cascade-suppressed and now surfaces).
-   - Against `Robot-Body-Runnable` cross-profile, the **Isaac variant
-     now PASSES** (`FET021_ROBOT_CORE_RUNNABLE` only requires
-     RC.007/008/009 — all three OK once `isaac:robotType` is set,
-     because IsaacRobotAPI is already applied with the correct
-     joints/links relationships and the root joint is pinned via
-     empty `physics:body0`). Cross-profile summary moved from
-     `0 passed / 3 failed` → `1 passed / 2 failed` (Isaac passes,
-     Neutral and PhysX still fail RC.007/008/009 because they don't
-     apply IsaacRobotAPI at all).
-2. **`RC.005`**: move every `physics:*` attribute currently authored
-   on links in `payloads/base.usda` into `payloads/Physics/physics.usda`
-   only (or refactor so `base.usda` carries no physics attributes at
-   all). This is a meaningful layer-organization change, not a
-   one-liner. Still failing after fix 1 (88 RC.005 issues remain).
-3. **`RC.003` (`RobotNaming`)** — surfaced *only after* fix 1. The
-   rule compares the **immediate folder name** (`simready_isaac_usd`)
-   to the **interface USD stem** (`ur10`). Under the standard SimReady
-   packaging convention these never match — every Isaac variant of
-   every SimReady asset fails RC.003. Likely a rule bug (should
-   probably look at the *bundle* parent, e.g. `ur10/`, not the
-   variant folder) or a misalignment between rule and packaging spec.
-   Worth raising upstream.
-4. **`RC.007` (cross-profile only)**: if the intent is that the
-   Neutral and PhysX variants should also satisfy Robot-Body-Runnable,
-   apply `IsaacRobotAPI` to their default prims with the same
-   `isaac:physics:robotJoints`/`robotLinks` relationships used in the
-   Isaac variant. If the intent is that each variant only ever
-   validates against its own declared profile, this is not needed.
-5. **PhysX empty features**: align the variant USDs and Robot-Body-Physx
-   profile's expected feature set — likely needs the assets to carry
-   the variant feature IDs that the profile declares (intersect with
-   P1's missing-feature list once that's resolved). Also: `validate.py`
-   currently emits an empty `.reports/<…>/` dir when zero features
-   match (no `index.html` / `results.json` written). Tracked
-   separately as a `validate.py` robustness issue.
-
-**In-repo workaround.** None — this is downstream of the validator. The
-`simready-report` skill faithfully reports what the rules say. The
-dashboard's "Failing requirements" panel surfaces the offending codes
-so users can map each failure back to its requirement doc.
-
-**Status.** Open against the foundations repo. Filed for tracking via
-this MR; no action in `simready-explorer` is needed beyond surfacing
-the issue here. Fix 1 above is **verified to work locally** (one-line
-edit to `base.usda`) — upstream PR against `NVIDIA/simready-foundation`
-is the right channel to land it. Fixes 2–5 still open. Re-validate
-after the foundation team updates the sample assets, the rule code
-(notably `RC.003 RobotNaming`), or relaxes the unmatched-feature
-behavior.
-
----
-
-## How to file a new entry here
-
-Use this skeleton:
-
-```
-## P<N> — <one-line title>
-
-**Symptom.** What the user/reader sees that's wrong.
-
-**Root cause.** Where the bug actually lives (which repo / file / step).
-
-**How to address.** Concrete fix path(s), upstream or local.
-
-**In-repo workaround.** What this repo does today to mitigate, if anything.
-
-**Status.** Open / mitigated / fixed (link to commit).
-```
-
-Bump the number; don't reuse retired ones — the git history is the
-canonical record once an entry is resolved and removed.
+# Known problems
+
+Issues encountered with the validation pipeline, the foundation specs, or the
+SimReady SDK that aren't bugs in this repo's code but affect the report
+output. Each entry: **symptom → root cause → workaround / how to address →
+status**.
+
+When you hit a new issue, add it here. Keep the list short — fold resolved
+items into git history once they're fixed.
+
+---
+
+## P1 — Profiles silently drop features that aren't registered
+
+**Symptom.** A profile loads with far fewer features than its
+`profiles.toml` declares. Concretely on the current foundations checkout:
+
+| Profile | Declared in `profiles.toml` | Loaded by validator | Dropped feature IDs |
+|---|---|---|---|
+| `Robot-Body-Runnable` v1.0.0 | 5 | **1** | `FET004_ROBOT_PHYSX` v0.2.0, `FET021_ROBOT_CORE_RUNNABLE` v0.2.0, `FET022_DRIVEN_JOINTS_PHYSX` v0.1.0, `FET024_BASE_ARTICULATION_PHYSX` v0.1.0 |
+| `Robot-Body-Isaac` v1.0.0 | 6 | 2 | `FET004_ROBOT_PHYSX` v0.2.0, `FET021_ROBOT_CORE_ISAAC` v0.2.0, `FET022_DRIVEN_JOINTS_ISAAC` v0.1.0, `FET024_BASE_ARTICULATION_PHYSX` v0.1.0 |
+| `Robot-Body-Neutral` v1.0.0 | 5 | 3 | `FET022_DRIVEN_JOINTS_NEUTRAL` v0.1.0, `FET024_BASE_ARTICULATION_NEUTRAL` v0.1.0 |
+| `Prop-Robotics-Neutral` v2.0.0 | 6 | 5 | `FET006_BASE_MDL` v0.1.0 |
+
+What's actually registered for the FET02x family (after `repo
+usd_profiles_codegen`):
+
+- `fet_021_robot_core` v0.2.0 (no variant suffix)
+- `fet_022_driven_joints` v0.1.0
+- `fet_023_robot_materials` v0.1.0
+- `fet_024_base_articulation` v0.1.0
+
+And for FET004/FET006 the only `_BASE_NEUTRAL` / `_BASE_USDPREVIEW`
+forms are registered, not the `_ROBOT_PHYSX` / `_BASE_MDL` variants the
+profiles ask for.
+
+**Root cause.** Profile entries in
+`<foundations>/nv_core/sr_specs/docs/profiles/profiles.toml` reference
+variant feature IDs that the local foundations registry doesn't ship — e.g.
+profiles ask for `FET021_ROBOT_CORE_RUNNABLE`, `FET022_DRIVEN_JOINTS_PHYSX`,
+`FET004_ROBOT_PHYSX`, `FET024_BASE_ARTICULATION_NEUTRAL`. What is actually
+registered (after `repo usd_profiles_codegen` runs against our checkout) is
+only the unsuffixed `_BASE_NEUTRAL` / `_BASE_USDPREVIEW` / `_CORE` /
+`_BASE_ISAACSIM` variants. The variant features the profiles ask for are
+silently absent.
+
+`omni.asset_validator.ProfileRegistry` resolves features by ID + version and
+silently drops any it can't find. There's no warning emitted at profile
+load time.
+
+**Verified the gap is local, not universal.** Sample reports from another
+SimReady environment (Fanuc content, sr9iar.usd.usd) show all five
+declared `Robot-Body-Runnable` features actually loaded —
+`FET001_BASE_NEUTRAL` (failed), plus `FET004_ROBOT_PHYSX`,
+`FET021_ROBOT_CORE_RUNNABLE`, `FET022_DRIVEN_JOINTS_PHYSX`,
+`FET024_BASE_ARTICULATION_PHYSX`, `FET024_BASE_ARTICULATION_NEUTRAL`
+(passed). So the variants *are* registrable; our local codegen output
+just doesn't include them.
+
+**Where the variants live.** The foundation source ships JSON variant
+definitions next to each feature's markdown. For FET004:
+
+```
+docs/features/FET_004-simulate_multi_body_physics.md           (md, _BASE_NEUTRAL only)
+docs/features/FET_004_base_neutral-0.1.0-...json
+docs/features/FET_004_base_physx-0.1.0-...json
+docs/features/FET_004_base_physx-0.2.0-...json
+docs/features/FET_004_robot_physx-0.1.0-...json    <- this is the one profiles ask for
+docs/features/FET_004_robot_physx-0.2.0-...json
+```
+
+Each JSON declares an `id` (e.g. `FET004_ROBOT_PHYSX`), `version`, `path`,
+and a `requirements` list. **Our `repo usd_profiles_codegen` run only
+parses the `.md` files** — the generated
+`_build/python/omni/capabilities/_features.py` contains zero
+`_ROBOT_PHYSX` / `_BASE_PHYSX` / `_RUNNABLE` entries even though the JSON
+sources are right there.
+
+**How to address.** Three paths, in priority order:
+
+1. **Codegen — pick up the JSON variant files.** The foundations
+   `repo usd_profiles_codegen` tool needs to also enumerate
+   `FET_*_*-*-...json` files in the features directory and emit Feature
+   entries for each, not just the `Internal ID` declared in the `.md`.
+   This closes the gap without changing source data — the variants
+   already exist.
+2. **Validator — emit a warning when a profile entry doesn't resolve.**
+   `omni.asset_validator.ProfileRegistry` silently drops missing
+   features. A `WARNING:` log at profile-load time would have made this
+   bug visible from day one.
+3. **Documentation** — once #1 lands, `repo.toml`'s codegen description
+   should call out that JSON variants are part of the source of truth so
+   downstream tooling doesn't repeat the mistake.
+
+Open this with the SimReady foundations team
+(`#omni-simready` / `#simready-next-support`); cite the discrepancy
+between our local codegen output and the working Fanuc environment
+sample.
+
+**In-repo workaround.** The dashboard now surfaces the coverage gap
+explicitly: when a profile declares more features than the validator
+loaded, a banner at the top lists the missing IDs and tells the user which
+ones got silently dropped. The validation result the report shows is
+genuinely against the *loaded* feature set — running with
+`Robot-Body-Runnable` does *not* check the four declared-but-missing
+features.
+
+**Status.** Local patch applied — see "Local patch applied" below.
+Upstream codegen fix still needed. Banner workaround still in place
+for environments without the patch.
+
+### Local patch applied
+
+A patch lives in
+`plugins/simready-report/skills/simready-report/validate.py` —
+function `_patch_register_json_variant_features()`. It runs at module
+load (so worker processes pick it up too) right after
+`import omni.asset_validator as oav`. It is loud about itself: every
+run prints a `[PATCH P1] FeatureRegistry: +N JSON-variant feature(s)
+... ProfileRegistry: rebuilt feature lists for M profile(s) ...`
+line so it's never invisible.
+
+**Concretely on the Yaskawa-local checkout** the patch lifts:
+- FeatureRegistry: 11 features → 30 features (+19 from JSON variants).
+- Robot-Body-Runnable v1.0.0: 1 feature / 8 requirements → **5 / 41**.
+- 11 profiles got their `.features` lists rebuilt; +24 feature
+  references appended in total.
+
+**Exactly what the patch does**, step by step:
+
+1. **Discover variant JSON files.** Globs
+   `<foundations>/nv_core/sr_specs/docs/features/FET_*.json`. The
+   filename styles in this repo are inconsistent
+   (`FET_021-robot_core_isaac-0.1.0.json`,
+   `FET_021_robot_core_runnable_0.2.0.json`,
+   `FET_004_base_physx-0.2.0-simulate_multi_body_phyics.json`), so we
+   ignore the filename and read the `id` + `version` fields from the
+   JSON content.
+
+2. **Build a Requirement code lookup.** `r.code -> r` for every
+   `Requirement` in `omni.asset_validator.RequirementsRegistry()`.
+   The JSON variants list dotted code strings like `"RB.COL.003"`,
+   `"DJ.001"`, `"BA.002"` — those are looked up here.
+
+3. **Construct a Feature-protocol object per JSON variant.**
+   `omni.asset_validator._features.Feature` is a `typing.Protocol`
+   declaring `id: str, version: str, path: str, requirements: list`.
+   We use a frozen dataclass that satisfies the protocol structurally:
+
+   ```python
+   @dataclass(frozen=True)
+   class _PatchedFeature:
+       id: str
+       version: str
+       path: str
+       requirements: list
+   ```
+
+4. **Skip duplicates and unresolvable variants.** If
+   `FeatureRegistry.find(fid, fver)` already returns something, skip
+   (don't double-register). If any of the JSON's requirement code
+   strings doesn't resolve in the code lookup, skip the whole feature
+   and record it in `unresolved_codes`. (Currently zero unresolved on
+   our checkout — every JSON variant's required codes exist.)
+
+5. **Register via `FeatureRegistry().add(feat)`.** The internal
+   `create_key` uses `.id` + `.version` so our dataclass satisfies it.
+
+6. **Re-resolve every profile's feature list — the critical step.**
+   `Profile` is a frozen dataclass, so we can't reassign
+   `profile.features`. But the field is a *mutable list*, and the
+   freeze only prevents field reassignment, not mutation of held
+   collections. So for every entry in `profiles.toml`'s declared
+   features that isn't already in the live profile, we look it up in
+   the now-fuller `FeatureRegistry` and `profile.features.append(...)`
+   in place. **Without this step the patch is invisible** — adding to
+   `FeatureRegistry` after profiles are already built doesn't
+   retroactively join existing Profile objects.
+
+**What the patch does NOT touch**: foundation source files, the
+codegen tool, generated `_features.py`, profile definitions in
+`profiles.toml`, or any rule code. The local patch is purely in our
+validation runner.
+
+**Remove the patch when**: the foundation `repo usd_profiles_codegen`
+tool is updated to enumerate JSON variant files alongside the
+markdown. Once `_features.py` carries every variant on its own,
+delete `_patch_register_json_variant_features()` and its call site.
+
+---
+
+## P2 — Public ur10 sample asset fails current foundation specs
+
+**Symptom.** Running `/simready-report` against the public ur10 sample
+in
+`simready_foundations/sample_content/common_assets/robots_general/ur10/`
+(release `2026.04.0`, commit `805d2c5`) reports failures on every
+variant when validated against its declared profile (or against
+Robot-Body-Runnable cross-profile). Concretely, against each interface
+USD's declared profile, with `--use-kit` so PhysX rules actually run:
+
+| Variant interface | Declared profile | Result | Failing requirements |
+|---|---|---|---|
+| `simready_usd/ur10.usda` | Robot-Body-Neutral v1.0.0 | **PASS** | — |
+| `simready_physx_usd/ur10.usda` | Robot-Body-Physx v1.0.0 | **FAIL** | (profile evaluates 0 features against the asset; `features_summary` empty in JSON output) |
+| `simready_isaac_usd/ur10.usda` | Robot-Body-Isaac v1.0.0 | **FAIL** | `RC.005` (`VerifyRobotPhysicsAttributesSourceLayer`), `RC.008` (`robot-type`), `RC.009` (`root-joint-pinned`), `DJ.010`, `ISA.001` |
+
+Under the cross-profile `Robot-Body-Runnable` run, Neutral and PhysX
+variants additionally light up with `RC.007` (`robot-schema` — no
+`IsaacRobotAPI` on the default prim) because neither of those variants
+applies `IsaacRobotAPI`, only the Isaac variant does.
+
+**Root cause.** Asset-side metadata gaps and layer-organization issues
+in the shipped public sample, *not* validator or skill code. The asset
+file is tracked by Git LFS at the same OID as the release (`b30f9c1b…`
+for `simready_isaac_usd/payloads/base.usda`), so no in-tree edit
+caused this. Each asset's `customLayerData.SimReady_Metadata.validation`
+records `validated_features` against a snapshot dated **2026-01-09**;
+between then and the current `805d2c5` foundation specs the rules in
+question were tightened (or added), so the asset that passed in
+January no longer passes today. Specifically:
+
+- **`RC.008` (`robot-type`)** — `simready_isaac_usd/payloads/base.usda`
+  lines 81-83 declare `token isaac:robotType` with **no value**. The
+  current rule requires a valid schema-defined token (e.g.
+  `"Manipulator"`, `"End Effector"`); the placeholder `"Default"` and
+  the absent-value case both fail.
+- **`RC.009` (`root-joint-pinned`)** — depends on `isaac:robotType`
+  to decide whether the root joint must be pinned. The asset's
+  `root_joint` *is* a `PhysicsFixedJoint` with empty `physics:body0`
+  (pinned to world, correct for a Manipulator), but without a valid
+  `robotType` value the rule can't evaluate and fails.
+- **`RC.005` (`VerifyRobotPhysicsAttributesSourceLayer`)** — physics
+  attributes (`physics:axis`, `physics:mass`, `physics:centerOfMass`,
+  `physics:diagonalInertia`, `physics:principalAxes`) on each robot
+  link are authored in *both* `payloads/base.usda` and
+  `payloads/Physics/physics.usda`. The current rule wants them in the
+  physics payload only.
+- **PhysX variant empty `features_summary`** — Robot-Body-Physx v1.0.0
+  evaluates zero features against the asset, suggesting the profile's
+  declared feature set no longer matches what the asset has stamped
+  (related to P1, but for a different feature family).
+
+**How to address.** Asset fixes belong in
+`github.com/NVIDIA/simready-foundation`, not here:
+
+1. **`RC.008`/`RC.009`** — *verified one-liner*. In
+   `simready_isaac_usd/payloads/base.usda` line 81, change
+   `token isaac:robotType (…)` to
+   `token isaac:robotType = "Manipulator" (…)`. Verified locally with
+   `--use-kit`:
+   - Against `Robot-Body-Isaac`, `FET021_ROBOT_CORE_ISAAC` failing
+     codes went from `[RC.005, RC.008, RC.009]` →
+     **`[RC.003, RC.005]`** (RC.008 and RC.009 cleared; RC.003 was
+     previously cascade-suppressed and now surfaces).
+   - Against `Robot-Body-Runnable` cross-profile, the **Isaac variant
+     now PASSES** (`FET021_ROBOT_CORE_RUNNABLE` only requires
+     RC.007/008/009 — all three OK once `isaac:robotType` is set,
+     because IsaacRobotAPI is already applied with the correct
+     joints/links relationships and the root joint is pinned via
+     empty `physics:body0`). Cross-profile summary moved from
+     `0 passed / 3 failed` → `1 passed / 2 failed` (Isaac passes,
+     Neutral and PhysX still fail RC.007/008/009 because they don't
+     apply IsaacRobotAPI at all).
+2. **`RC.005`**: move every `physics:*` attribute currently authored
+   on links in `payloads/base.usda` into `payloads/Physics/physics.usda`
+   only (or refactor so `base.usda` carries no physics attributes at
+   all). This is a meaningful layer-organization change, not a
+   one-liner. Still failing after fix 1 (88 RC.005 issues remain).
+3. **`RC.003` (`RobotNaming`)** — surfaced *only after* fix 1. The
+   rule compares the **immediate folder name** (`simready_isaac_usd`)
+   to the **interface USD stem** (`ur10`). Under the standard SimReady
+   packaging convention these never match — every Isaac variant of
+   every SimReady asset fails RC.003. Likely a rule bug (should
+   probably look at the *bundle* parent, e.g. `ur10/`, not the
+   variant folder) or a misalignment between rule and packaging spec.
+   Worth raising upstream.
+4. **`RC.007` (cross-profile only)**: if the intent is that the
+   Neutral and PhysX variants should also satisfy Robot-Body-Runnable,
+   apply `IsaacRobotAPI` to their default prims with the same
+   `isaac:physics:robotJoints`/`robotLinks` relationships used in the
+   Isaac variant. If the intent is that each variant only ever
+   validates against its own declared profile, this is not needed.
+5. **PhysX empty features**: align the variant USDs and Robot-Body-Physx
+   profile's expected feature set — likely needs the assets to carry
+   the variant feature IDs that the profile declares (intersect with
+   P1's missing-feature list once that's resolved). Also: `validate.py`
+   currently emits an empty `.reports/<…>/` dir when zero features
+   match (no `index.html` / `results.json` written). Tracked
+   separately as a `validate.py` robustness issue.
+
+**In-repo workaround.** None — this is downstream of the validator. The
+`simready-report` skill faithfully reports what the rules say. The
+dashboard's "Failing requirements" panel surfaces the offending codes
+so users can map each failure back to its requirement doc.
+
+**Status.** Open against the foundations repo. Filed for tracking via
+this MR; no action in `simready-explorer` is needed beyond surfacing
+the issue here. Fix 1 above is **verified to work locally** (one-line
+edit to `base.usda`) — upstream PR against `NVIDIA/simready-foundation`
+is the right channel to land it. Fixes 2–5 still open. Re-validate
+after the foundation team updates the sample assets, the rule code
+(notably `RC.003 RobotNaming`), or relaxes the unmatched-feature
+behavior.
+
+---
+
+## How to file a new entry here
+
+Use this skeleton:
+
+```
+## P<N> — <one-line title>
+
+**Symptom.** What the user/reader sees that's wrong.
+
+**Root cause.** Where the bug actually lives (which repo / file / step).
+
+**How to address.** Concrete fix path(s), upstream or local.
+
+**In-repo workaround.** What this repo does today to mitigate, if anything.
+
+**Status.** Open / mitigated / fixed (link to commit).
+```
+
+Bump the number; don't reuse retired ones — the git history is the
+canonical record once an entry is resolved and removed.

tools/validation/README.md

@@ -1,139 +1,139 @@
-# Validation reporting — staging branch
-
-## Install the Claude Code plugin
-
-The `simready-report` plugin ships as a Claude Code marketplace under
-`validation/.claude-plugin/`. From a checkout of this repo, run inside Claude Code:
-
-```
-/plugin marketplace add <path-to-repo>/validation
-/plugin install simready-report@simready-playbook
-```
-
-That registers two slash commands: `/simready-report` and `/simready-package`.
-You still need a Python with the SimReady runtime deps and the foundations + sdk
-checkouts on disk — see [To run the demo as-is](#to-run-the-demo-as-is) below.
-
-> [!IMPORTANT]
-> ## Read [`PROBLEMS.md`](PROBLEMS.md) before trusting any report
->
-> Reports produced by this prototype lean on a **local patch** for
-> [PROBLEMS.md P1](PROBLEMS.md): without it, every Robot-Body profile
-> silently drops 4 of its 5 declared features at load time, because
-> the foundation `repo usd_profiles_codegen` step doesn't read the
-> JSON variant definitions next to each feature's markdown. A
-> "passing" report against `Robot-Body-Runnable` would only have
-> checked 1 feature out of 5.
->
-> The patch lives in
-> `plugins/simready-report/skills/simready-report/validate.py` and is
-> loud about itself — every run prints a `[PATCH P1]` line. With the
-> patch active, `Robot-Body-Runnable` resolves to **5/5 features, 41
-> requirements** instead of 1/8.
->
-> The dashboard's **Caveats** panel still surfaces the gap if anyone
-> runs without the patch.
->
-> [`PROBLEMS.md`](PROBLEMS.md) **P1** has the full root cause, the
-> patch walkthrough, and the upstream fix path. The patch is meant to
-> be temporary — once foundations codegen is fixed, delete
-> `_patch_register_json_variant_features()` and its call site.
-
----
-
-> **Status: demo / review staging.** Not part of `simready-explorer` proper yet.
->
-> This directory is a verbatim copy of the prototype work currently living at
-> [`loginowskid/simready-playbook`](https://github.com/loginowskid/simready-playbook),
-> dropped here on the `dev/dloginowski/validation-reporting` branch so the
-> SimReady team can review the artifact before we refactor it into the repo's
-> existing library + skills patterns.
-
-## What this is
-
-A Claude-Code-driven validation reporting pipeline for SimReady customer assets.
-On top of the existing `omni.asset_validator` engine and SimReady profile registry,
-it adds:
-
-- **HTML dashboard** with summary cards, per-asset feature pass/fail, an
-  asset filter, and a "Other failed requirements" panel for issues outside the
-  loaded profile.
-- **External-dependencies provenance report** — walks USD composition arcs per
-  asset, classifies each layer as internal/external relative to the target,
-  records actions taken to obtain each.
-- **Foundation doc rendering** — renders the markdown source for every
-  feature/requirement code referenced by the report into HTML inside the output.
-- **Auto-packaging convenience** — for a raw asset bundle under
-  `assets_to_validate/<name>/`, runs `simready ingest usd` per interface USD
-  before validating against the packaged tree.
-- **Spec selector** — `--list-profiles` enumerates registered profiles so the
-  user can pick a SimReady profile interactively.
-- **Parallel asset validation** — `ProcessPoolExecutor` workers, default auto.
-
-Two slash commands ship together as a single Claude Code plugin:
-
-- `/simready-report` — validate + dashboard + provenance + docs.
-- `/simready-package` — standalone packaging (no validation).
-
-## Layout (mirrors the source repo)
-
-```
-validation/
-├── bootstrap.ps1                    # Windows convenience installer
-├── marketplace.json                 # Claude Code marketplace manifest
-├── plugins/simready-report/
-│   ├── plugin.json
-│   └── skills/
-│       ├── simready-report/         # HTML dashboard + validation
-│       └── simready-package/        # standalone packaging
-└── playbooks/
-    └── foundations-deviations.md    # observed gaps between specs and asset_validator
-```
-
-## Why it doesn't fit the repo's existing patterns yet
-
-`simready-explorer` already ships `source/libraries/validate/` with a clean
-public API (`validate_asset`, `validate_asset_list`, etc.) and three skills in
-the `agentskills.io/specification` format (`validate-asset`, `validate-batch`,
-`validate-metadata`). The work in this `validation/` directory:
-
-- Reinvents a thinner version of `simready.validate.validate_asset_list` —
-  this is duplication that should be removed during integration.
-- Uses a different skill format (Claude Code marketplace plugin) — should be
-  rewritten as `agentskills.io` skills that call into the library.
-- Is a standalone-script architecture (`python validate.py …`) — should be
-  exposed via the existing `repo.bat` / library entry points.
-
-## Proposed integration after review
-
-1. New skill `validate-report` under
-   `source/libraries/validate/src/validate/skills/validate-report/` —
-   instructional doc that drives a new `simready.validate.report` module.
-2. New module `source/libraries/validate/src/validate/report/` containing the
-   dashboard renderer, doc renderer, external-deps tracker, thumbnail mirrorer
-   — extracted from `report.py` + `external_deps.py` and adapted to consume
-   `AssetValidationResult` instead of the raw `omni.asset_validator` issue
-   stream.
-3. Optional new skill `validate-package` — thin wrapper around
-   `simready ingest usd` (independent of validation).
-4. Drop `bootstrap.ps1` / `marketplace.json` / Claude-Code-plugin layout — not
-   relevant here; the team uses `repo.bat` + `_build/` flow.
-
-## To run the demo as-is
-
-The scripts in this directory are self-contained and need a Python with the
-SimReady runtime deps installed plus the foundations + sdk checkouts on disk.
-Easiest path on Windows: `& bootstrap.ps1` (creates a venv at
-`%LOCALAPPDATA%\simready\` and persists `SIMREADY_PYTHON` /
-`SIMREADY_FOUNDATIONS_PATH` / `SIMREADY_SDK_PATH` env vars). On other systems
-or custom layouts, install the deps into your Python and set those env vars
-manually.
-
-After that:
-
-```
-python plugins/simready-report/skills/simready-report/validate.py \
-    <path-to-asset-bundle> --profile Robot-Body-Isaac --version 1.0.0
-```
-
-Output lands at `<bundle>/.reports/<bundle-name>.<profile>/index.html`.
+# Validation reporting — staging branch
+
+## Install the Claude Code plugin
+
+The `simready-report` plugin ships as a Claude Code marketplace under
+`validation/.claude-plugin/`. From a checkout of this repo, run inside Claude Code:
+
+```
+/plugin marketplace add <path-to-repo>/validation
+/plugin install simready-report@simready-playbook
+```
+
+That registers two slash commands: `/simready-report` and `/simready-package`.
+You still need a Python with the SimReady runtime deps and the foundations + sdk
+checkouts on disk — see [To run the demo as-is](#to-run-the-demo-as-is) below.
+
+> [!IMPORTANT]
+> ## Read [`PROBLEMS.md`](PROBLEMS.md) before trusting any report
+>
+> Reports produced by this prototype lean on a **local patch** for
+> [PROBLEMS.md P1](PROBLEMS.md): without it, every Robot-Body profile
+> silently drops 4 of its 5 declared features at load time, because
+> the foundation `repo usd_profiles_codegen` step doesn't read the
+> JSON variant definitions next to each feature's markdown. A
+> "passing" report against `Robot-Body-Runnable` would only have
+> checked 1 feature out of 5.
+>
+> The patch lives in
+> `plugins/simready-report/skills/simready-report/validate.py` and is
+> loud about itself — every run prints a `[PATCH P1]` line. With the
+> patch active, `Robot-Body-Runnable` resolves to **5/5 features, 41
+> requirements** instead of 1/8.
+>
+> The dashboard's **Caveats** panel still surfaces the gap if anyone
+> runs without the patch.
+>
+> [`PROBLEMS.md`](PROBLEMS.md) **P1** has the full root cause, the
+> patch walkthrough, and the upstream fix path. The patch is meant to
+> be temporary — once foundations codegen is fixed, delete
+> `_patch_register_json_variant_features()` and its call site.
+
+---
+
+> **Status: demo / review staging.** Not part of `simready-explorer` proper yet.
+>
+> This directory is a verbatim copy of the prototype work currently living at
+> [`loginowskid/simready-playbook`](https://github.com/loginowskid/simready-playbook),
+> dropped here on the `dev/dloginowski/validation-reporting` branch so the
+> SimReady team can review the artifact before we refactor it into the repo's
+> existing library + skills patterns.
+
+## What this is
+
+A Claude-Code-driven validation reporting pipeline for SimReady customer assets.
+On top of the existing `omni.asset_validator` engine and SimReady profile registry,
+it adds:
+
+- **HTML dashboard** with summary cards, per-asset feature pass/fail, an
+  asset filter, and a "Other failed requirements" panel for issues outside the
+  loaded profile.
+- **External-dependencies provenance report** — walks USD composition arcs per
+  asset, classifies each layer as internal/external relative to the target,
+  records actions taken to obtain each.
+- **Foundation doc rendering** — renders the markdown source for every
+  feature/requirement code referenced by the report into HTML inside the output.
+- **Auto-packaging convenience** — for a raw asset bundle under
+  `assets_to_validate/<name>/`, runs `simready ingest usd` per interface USD
+  before validating against the packaged tree.
+- **Spec selector** — `--list-profiles` enumerates registered profiles so the
+  user can pick a SimReady profile interactively.
+- **Parallel asset validation** — `ProcessPoolExecutor` workers, default auto.
+
+Two slash commands ship together as a single Claude Code plugin:
+
+- `/simready-report` — validate + dashboard + provenance + docs.
+- `/simready-package` — standalone packaging (no validation).
+
+## Layout (mirrors the source repo)
+
+```
+validation/
+��── bootstrap.ps1                    # Windows convenience installer
+├── marketplace.json                 # Claude Code marketplace manifest
+├── plugins/simready-report/
+│   ├── plugin.json
+│   └── skills/
+│       ├── simready-report/         # HTML dashboard + validation
+│       └── simready-package/        # standalone packaging
+└── playbooks/
+    └── foundations-deviations.md    # observed gaps between specs and asset_validator
+```
+
+## Why it doesn't fit the repo's existing patterns yet
+
+`simready-explorer` already ships `source/libraries/validate/` with a clean
+public API (`validate_asset`, `validate_asset_list`, etc.) and three skills in
+the `agentskills.io/specification` format (`validate-asset`, `validate-batch`,
+`validate-metadata`). The work in this `validation/` directory:
+
+- Reinvents a thinner version of `simready.validate.validate_asset_list` —
+  this is duplication that should be removed during integration.
+- Uses a different skill format (Claude Code marketplace plugin) — should be
+  rewritten as `agentskills.io` skills that call into the library.
+- Is a standalone-script architecture (`python validate.py …`) — should be
+  exposed via the existing `repo.bat` / library entry points.
+
+## Proposed integration after review
+
+1. New skill `validate-report` under
+   `source/libraries/validate/src/validate/skills/validate-report/` —
+   instructional doc that drives a new `simready.validate.report` module.
+2. New module `source/libraries/validate/src/validate/report/` containing the
+   dashboard renderer, doc renderer, external-deps tracker, thumbnail mirrorer
+   — extracted from `report.py` + `external_deps.py` and adapted to consume
+   `AssetValidationResult` instead of the raw `omni.asset_validator` issue
+   stream.
+3. Optional new skill `validate-package` — thin wrapper around
+   `simready ingest usd` (independent of validation).
+4. Drop `bootstrap.ps1` / `marketplace.json` / Claude-Code-plugin layout — not
+   relevant here; the team uses `repo.bat` + `_build/` flow.
+
+## To run the demo as-is
+
+The scripts in this directory are self-contained and need a Python with the
+SimReady runtime deps installed plus the foundations + sdk checkouts on disk.
+Easiest path on Windows: `& bootstrap.ps1` (creates a venv at
+`%LOCALAPPDATA%\simready\` and persists `SIMREADY_PYTHON` /
+`SIMREADY_FOUNDATIONS_PATH` / `SIMREADY_SDK_PATH` env vars). On other systems
+or custom layouts, install the deps into your Python and set those env vars
+manually.
+
+After that:
+
+```
+python plugins/simready-report/skills/simready-report/validate.py \
+    <path-to-asset-bundle> --profile Robot-Body-Isaac --version 1.0.0
+```
+
+Output lands at `<bundle>/.reports/<bundle-name>.<profile>/index.html`.

tools/validation/UPSTREAM.md

@@ -1,66 +1,66 @@
-# Upstream sync
-
-`tools/validation/` is a **verbatim fork** of the `validation/` tree from:
-
-- **Repo:** `omniverse/kit-extensions/simready-explorer`
-- **Host:** `gitlab-master.nvidia.com`
-- **Branch:** `dev/dloginowski/validation-reporting`
-- **URL:** https://gitlab-master.nvidia.com/omniverse/kit-extensions/simready-explorer/-/tree/dev/dloginowski/validation-reporting
-
-It is **not** a git submodule. Upstream changes do not flow here automatically.
-
-## Current pin
-
-```
-upstream_sha: 4bd42394685156d97f3e3bf371117f53e8dd8ab1
-synced_at:    2026-05-22
-synced_by:    dloginowski
-```
-
-> Bump these three fields whenever you re-run `_sync.sh`.
-
-## Check for drift
-
-```bash
-git ls-remote https://gitlab-master.nvidia.com/omniverse/kit-extensions/simready-explorer.git \
-  refs/heads/dev/dloginowski/validation-reporting
-```
-
-Compare the printed SHA to `upstream_sha` above. If they differ, upstream has
-new commits we don't have.
-
-## Pull a new version
-
-```bash
-bash tools/validation/_sync.sh
-```
-
-The script:
-
-1. Shallow-clones the upstream branch to a temp dir.
-2. Reports the new SHA and how many commits ahead of `upstream_sha` it is.
-3. Rsyncs upstream `validation/*` over `tools/validation/*`, preserving
-   `UPSTREAM.md` and `_sync.sh` themselves.
-4. Prints a diff stat so you can see what changed.
-
-After running, review the diff, **manually update the pin block above**, then
-commit:
-
-```bash
-git add tools/validation/
-git commit -m "Sync tools/validation/ from upstream <short-sha>"
-```
-
-## When upstream lands in `simready-explorer` proper
-
-The upstream README (`tools/validation/README.md`) calls this directory
-"demo / review staging" and outlines the intended integration into
-`simready-explorer`'s existing library + skills patterns. Once that lands:
-
-1. Delete `tools/validation/`.
-2. Replace the runner-side driver `tools/hf_watch/validate.py` with calls
-   into `simready-explorer`'s public CLI (likely `repo.bat validate` or
-   the `simready.validate` library entry points).
-3. Drop this file.
-
-Until then, treat this fork as a snapshot.
+# Upstream sync
+
+`tools/validation/` is a **verbatim fork** of the `validation/` tree from:
+
+- **Repo:** `omniverse/kit-extensions/simready-explorer`
+- **Host:** `gitlab-master.nvidia.com`
+- **Branch:** `dev/dloginowski/validation-reporting`
+- **URL:** https://gitlab-master.nvidia.com/omniverse/kit-extensions/simready-explorer/-/tree/dev/dloginowski/validation-reporting
+
+It is **not** a git submodule. Upstream changes do not flow here automatically.
+
+## Current pin
+
+```
+upstream_sha: 4bd42394685156d97f3e3bf371117f53e8dd8ab1
+synced_at:    2026-05-22
+synced_by:    dloginowski
+```
+
+> Bump these three fields whenever you re-run `_sync.sh`.
+
+## Check for drift
+
+```bash
+git ls-remote https://gitlab-master.nvidia.com/omniverse/kit-extensions/simready-explorer.git \
+  refs/heads/dev/dloginowski/validation-reporting
+```
+
+Compare the printed SHA to `upstream_sha` above. If they differ, upstream has
+new commits we don't have.
+
+## Pull a new version
+
+```bash
+bash tools/validation/_sync.sh
+```
+
+The script:
+
+1. Shallow-clones the upstream branch to a temp dir.
+2. Reports the new SHA and how many commits ahead of `upstream_sha` it is.
+3. Rsyncs upstream `validation/*` over `tools/validation/*`, preserving
+   `UPSTREAM.md` and `_sync.sh` themselves.
+4. Prints a diff stat so you can see what changed.
+
+After running, review the diff, **manually update the pin block above**, then
+commit:
+
+```bash
+git add tools/validation/
+git commit -m "Sync tools/validation/ from upstream <short-sha>"
+```
+
+## When upstream lands in `simready-explorer` proper
+
+The upstream README (`tools/validation/README.md`) calls this directory
+"demo / review staging" and outlines the intended integration into
+`simready-explorer`'s existing library + skills patterns. Once that lands:
+
+1. Delete `tools/validation/`.
+2. Replace the runner-side driver `tools/hf_watch/validate.py` with calls
+   into `simready-explorer`'s public CLI (likely `repo.bat validate` or
+   the `simready.validate` library entry points).
+3. Drop this file.
+
+Until then, treat this fork as a snapshot.

tools/validation/_sync.sh

@@ -1,98 +1,98 @@
-#!/usr/bin/env bash
-# Sync tools/validation/ from the upstream GitLab branch.
-#
-# Run from the repo root:
-#   bash tools/validation/_sync.sh
-#
-# After running, review the diff, bump the pin block in
-# tools/validation/UPSTREAM.md, and commit.
-
-set -euo pipefail
-
-UPSTREAM_URL="https://gitlab-master.nvidia.com/omniverse/kit-extensions/simready-explorer.git"
-UPSTREAM_BRANCH="dev/dloginowski/validation-reporting"
-UPSTREAM_PATH="validation"
-LOCAL_PATH="tools/validation"
-KEEP=(UPSTREAM.md _sync.sh)
-
-if [[ ! -d "${LOCAL_PATH}" ]]; then
-  echo "expected ${LOCAL_PATH} to exist; are you in the repo root?" >&2
-  exit 1
-fi
-
-# Compare current pin to upstream HEAD.
-current_pin="$(grep -oE 'upstream_sha:\s*[0-9a-f]+' "${LOCAL_PATH}/UPSTREAM.md" \
-                | awk '{print $2}' | head -n1 || true)"
-upstream_sha="$(git ls-remote "${UPSTREAM_URL}" "refs/heads/${UPSTREAM_BRANCH}" \
-                | awk '{print $1}')"
-
-if [[ -z "${upstream_sha}" ]]; then
-  echo "could not resolve upstream branch SHA — check network / auth" >&2
-  exit 2
-fi
-
-echo "current pin:   ${current_pin:-(unset)}"
-echo "upstream HEAD: ${upstream_sha}"
-
-if [[ "${current_pin}" == "${upstream_sha}" ]]; then
-  echo "already in sync — nothing to do"
-  exit 0
-fi
-
-tmpdir="$(mktemp -d)"
-trap 'rm -rf "${tmpdir}"' EXIT
-
-echo ">> shallow-clone upstream"
-git clone --depth 50 --branch "${UPSTREAM_BRANCH}" --single-branch \
-  "${UPSTREAM_URL}" "${tmpdir}/upstream" >/dev/null
-
-# How many commits ahead of the current pin (best-effort; falls back to "?")
-ahead="?"
-if [[ -n "${current_pin}" ]]; then
-  if git -C "${tmpdir}/upstream" cat-file -e "${current_pin}" 2>/dev/null; then
-    ahead="$(git -C "${tmpdir}/upstream" rev-list --count "${current_pin}..HEAD")"
-  fi
-fi
-echo "commits ahead of pin: ${ahead}"
-
-upstream_dir="${tmpdir}/upstream/${UPSTREAM_PATH}"
-if [[ ! -d "${upstream_dir}" ]]; then
-  echo "upstream ${UPSTREAM_PATH}/ missing in branch ${UPSTREAM_BRANCH}" >&2
-  exit 3
-fi
-
-echo ">> rsync upstream → ${LOCAL_PATH}"
-# Stash KEEP files so rsync --delete doesn't remove them.
-keep_stash="$(mktemp -d)"
-for f in "${KEEP[@]}"; do
-  if [[ -f "${LOCAL_PATH}/${f}" ]]; then
-    cp -p "${LOCAL_PATH}/${f}" "${keep_stash}/${f}"
-  fi
-done
-
-rsync -a --delete "${upstream_dir}/" "${LOCAL_PATH}/"
-
-for f in "${KEEP[@]}"; do
-  if [[ -f "${keep_stash}/${f}" ]]; then
-    cp -p "${keep_stash}/${f}" "${LOCAL_PATH}/${f}"
-  fi
-done
-rm -rf "${keep_stash}"
-
-echo
-echo ">> changes:"
-git -c color.ui=always diff --stat -- "${LOCAL_PATH}" | tail -20 || true
-
-cat <<EOF
-
-Sync staged. Next steps:
-
-  1. Bump the pin block in ${LOCAL_PATH}/UPSTREAM.md:
-
-       upstream_sha: ${upstream_sha}
-       synced_at:    $(date -u +%Y-%m-%d)
-       synced_by:    \$(git config user.name)
-
-  2. Review the diff:    git diff -- ${LOCAL_PATH}
-  3. Commit:             git add ${LOCAL_PATH} && git commit -m "Sync tools/validation/ from upstream ${upstream_sha:0:12}"
-EOF
+#!/usr/bin/env bash
+# Sync tools/validation/ from the upstream GitLab branch.
+#
+# Run from the repo root:
+#   bash tools/validation/_sync.sh
+#
+# After running, review the diff, bump the pin block in
+# tools/validation/UPSTREAM.md, and commit.
+
+set -euo pipefail
+
+UPSTREAM_URL="https://gitlab-master.nvidia.com/omniverse/kit-extensions/simready-explorer.git"
+UPSTREAM_BRANCH="dev/dloginowski/validation-reporting"
+UPSTREAM_PATH="validation"
+LOCAL_PATH="tools/validation"
+KEEP=(UPSTREAM.md _sync.sh)
+
+if [[ ! -d "${LOCAL_PATH}" ]]; then
+  echo "expected ${LOCAL_PATH} to exist; are you in the repo root?" >&2
+  exit 1
+fi
+
+# Compare current pin to upstream HEAD.
+current_pin="$(grep -oE 'upstream_sha:\s*[0-9a-f]+' "${LOCAL_PATH}/UPSTREAM.md" \
+                | awk '{print $2}' | head -n1 || true)"
+upstream_sha="$(git ls-remote "${UPSTREAM_URL}" "refs/heads/${UPSTREAM_BRANCH}" \
+                | awk '{print $1}')"
+
+if [[ -z "${upstream_sha}" ]]; then
+  echo "could not resolve upstream branch SHA — check network / auth" >&2
+  exit 2
+fi
+
+echo "current pin:   ${current_pin:-(unset)}"
+echo "upstream HEAD: ${upstream_sha}"
+
+if [[ "${current_pin}" == "${upstream_sha}" ]]; then
+  echo "already in sync — nothing to do"
+  exit 0
+fi
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "${tmpdir}"' EXIT
+
+echo ">> shallow-clone upstream"
+git clone --depth 50 --branch "${UPSTREAM_BRANCH}" --single-branch \
+  "${UPSTREAM_URL}" "${tmpdir}/upstream" >/dev/null
+
+# How many commits ahead of the current pin (best-effort; falls back to "?")
+ahead="?"
+if [[ -n "${current_pin}" ]]; then
+  if git -C "${tmpdir}/upstream" cat-file -e "${current_pin}" 2>/dev/null; then
+    ahead="$(git -C "${tmpdir}/upstream" rev-list --count "${current_pin}..HEAD")"
+  fi
+fi
+echo "commits ahead of pin: ${ahead}"
+
+upstream_dir="${tmpdir}/upstream/${UPSTREAM_PATH}"
+if [[ ! -d "${upstream_dir}" ]]; then
+  echo "upstream ${UPSTREAM_PATH}/ missing in branch ${UPSTREAM_BRANCH}" >&2
+  exit 3
+fi
+
+echo ">> rsync upstream → ${LOCAL_PATH}"
+# Stash KEEP files so rsync --delete doesn't remove them.
+keep_stash="$(mktemp -d)"
+for f in "${KEEP[@]}"; do
+  if [[ -f "${LOCAL_PATH}/${f}" ]]; then
+    cp -p "${LOCAL_PATH}/${f}" "${keep_stash}/${f}"
+  fi
+done
+
+rsync -a --delete "${upstream_dir}/" "${LOCAL_PATH}/"
+
+for f in "${KEEP[@]}"; do
+  if [[ -f "${keep_stash}/${f}" ]]; then
+    cp -p "${keep_stash}/${f}" "${LOCAL_PATH}/${f}"
+  fi
+done
+rm -rf "${keep_stash}"
+
+echo
+echo ">> changes:"
+git -c color.ui=always diff --stat -- "${LOCAL_PATH}" | tail -20 || true
+
+cat <<EOF
+
+Sync staged. Next steps:
+
+  1. Bump the pin block in ${LOCAL_PATH}/UPSTREAM.md:
+
+       upstream_sha: ${upstream_sha}
+       synced_at:    $(date -u +%Y-%m-%d)
+       synced_by:    \$(git config user.name)
+
+  2. Review the diff:    git diff -- ${LOCAL_PATH}
+  3. Commit:             git add ${LOCAL_PATH} && git commit -m "Sync tools/validation/ from upstream ${upstream_sha:0:12}"
+EOF

tools/validation/bootstrap.ps1

@@ -1,207 +1,207 @@
-<#
-.SYNOPSIS
-  Bootstrap the SimReady Pipeline Bot runtime dependencies.
-
-.DESCRIPTION
-  Idempotent. Run once on a fresh machine, or re-run any time to fix a
-  missing dependency. Creates a Python venv, clones the foundation + SDK
-  repos, and pip-installs everything the /simready-report skill needs.
-
-  The foundation specs are *not* editable-installed any more. validate.py
-  now defaults to populating the OAV registries via the simready-validate
-  CLI loader against on-disk paths under the foundations checkout.
-  Avoids the `repo usd_profiles_codegen` codegen step (which depends on
-  internal packman tooling not shipped in the public GitHub repo) and the
-  Forced-include trap in nv_core/sr_specs/pyproject.toml.
-
-  Layout produced (all under -DepsRoot, default $env:LOCALAPPDATA\simready):
-
-    <DepsRoot>\
-      ├── venv\                     # Python venv (created if missing)
-      ├── simready_foundations\     # cloned from NVIDIA GitHub
-      └── simready-oem-sdk-poc\     # cloned from NVIDIA-dev GitHub
-
-  After a successful install the script writes three User-level environment
-  variables so the /simready-report skill can locate everything from any shell:
-
-    SIMREADY_PYTHON           = <DepsRoot>\venv\Scripts\python.exe
-    SIMREADY_FOUNDATIONS_PATH = <DepsRoot>\simready_foundations
-    SIMREADY_SDK_PATH         = <DepsRoot>\simready-oem-sdk-poc
-
-  Override the location with -DepsRoot, e.g.:
-    .\bootstrap.ps1 -DepsRoot D:\simready-deps
-
-  Already have these repos checked out elsewhere? Skip this script and
-  set the two env vars manually.
-
-  Optional (not bootstrapped): a `usd_validation_dashboard_final\` clone —
-  used only to copy Sphinx _static\ assets into rendered doc pages. If
-  absent, the dashboard's doc pages fall back to minimal inline styling.
-
-.NOTES
-  - Reversible: the dirs created here are safe to delete; rerun this
-    script to re-create them. The two env vars can be cleared with
-    `[Environment]::SetEnvironmentVariable("SIMREADY_FOUNDATIONS_PATH", $null, "User")`.
-  - Requires: git, python (3.11+ recommended), and access to
-    github.com/NVIDIA + github.com/NVIDIA-dev (creds via the user's
-    existing git/gh auth).
-  - Never elevates / never modifies system PATH.
-#>
-[CmdletBinding()]
-param(
-  [switch]$Force,                                  # re-clone even if dirs exist
-  [string]$Python = "python",                      # python interpreter to seed the venv
-  [string]$DepsRoot = (Join-Path $env:LOCALAPPDATA "simready"),
-  [string]$FoundationsRepo = "https://github.com/NVIDIA/simready-foundation.git",
-  [string]$SdkRepo         = "https://github.com/NVIDIA-dev/simready-oem-sdk-poc.git"
-)
-
-$ErrorActionPreference = "Stop"
-
-if (-not (Test-Path $DepsRoot)) {
-  New-Item -ItemType Directory -Path $DepsRoot -Force | Out-Null
-}
-$DepsRoot = (Resolve-Path $DepsRoot).Path
-
-$VenvPath        = Join-Path $DepsRoot "venv"
-$FoundationsPath = Join-Path $DepsRoot "simready_foundations"
-$SdkPath         = Join-Path $DepsRoot "simready-oem-sdk-poc"
-
-function Step($msg) { Write-Host ""; Write-Host "==> $msg" -ForegroundColor Cyan }
-function Note($msg) { Write-Host "    $msg" -ForegroundColor DarkGray }
-function Done($msg) { Write-Host "    OK: $msg" -ForegroundColor Green }
-function Fail($msg) { Write-Host "    FAIL: $msg" -ForegroundColor Red; exit 1 }
-
-Write-Host "DepsRoot: $DepsRoot" -ForegroundColor Yellow
-
-# ---- Pre-flight ----------------------------------------------------------
-
-Step "Pre-flight"
-foreach ($cmd in @("git", $Python)) {
-  $found = Get-Command $cmd -ErrorAction SilentlyContinue
-  if (-not $found) { Fail "$cmd not on PATH" }
-  Note "$cmd  -> $($found.Source)"
-}
-
-# ---- Clone the repos -----------------------------------------------------
-
-function Ensure-Repo($name, $url, $path) {
-  if ((Test-Path $path) -and -not $Force) {
-    if (Test-Path (Join-Path $path ".git")) {
-      $existingUrl = $null
-      Push-Location $path
-      try { $existingUrl = (git remote get-url origin 2>$null) } finally { Pop-Location }
-      if ($existingUrl -and ($existingUrl.Trim() -ne $url.Trim())) {
-        Fail "$name at $path has origin '$($existingUrl.Trim())' but expected '$url'. Re-run with -Force to re-clone, or fix manually: git -C `"$path`" remote set-url origin `"$url`""
-      }
-      Note "$name already cloned at $path  (use -Force to re-clone)"
-      return
-    } else {
-      Fail "$path exists but is not a git checkout. Move or delete it first."
-    }
-  }
-  if ((Test-Path $path) -and $Force) {
-    Note "Removing $path (-Force)"
-    Remove-Item -Recurse -Force $path
-  }
-  Note "git clone $url $path"
-  git clone $url $path
-  if ($LASTEXITCODE -ne 0) { Fail "git clone $name failed" }
-  Done "$name cloned"
-}
-
-Step "simready_foundations"
-Ensure-Repo "simready_foundations" $FoundationsRepo $FoundationsPath
-
-Step "simready-oem-sdk-poc"
-Ensure-Repo "simready-oem-sdk-poc" $SdkRepo $SdkPath
-
-# ---- Python venv ---------------------------------------------------------
-
-Step "Python venv at $VenvPath"
-if (-not (Test-Path (Join-Path $VenvPath "Scripts\python.exe"))) {
-  & $Python -m venv $VenvPath
-  if ($LASTEXITCODE -ne 0) { Fail "venv creation failed" }
-  Done "venv created"
-} else {
-  Note "venv already present"
-}
-$VenvPython = Join-Path $VenvPath "Scripts\python.exe"
-$VenvPip    = Join-Path $VenvPath "Scripts\pip.exe"
-
-# ---- Pip installs --------------------------------------------------------
-
-Step "Upgrade pip / install runtime deps"
-& $VenvPython -m pip install --upgrade pip wheel setuptools | Out-Null
-if ($LASTEXITCODE -ne 0) { Fail "pip self-upgrade failed" }
-
-$Pkgs = @(
-  "usd-core==26.5",
-  "omniverse-asset-validator==1.15.1",
-  "omniverse-usd-profiles==1.11.0",
-  "markdown-it-py>=3.0",
-  "click>=8.0",
-  "simready-validate>=2026.4.8"
-)
-& $VenvPip install @Pkgs
-if ($LASTEXITCODE -ne 0) { Fail "pip install (runtime deps) failed" }
-Done "runtime deps installed (incl. simready-validate from PyPI — provides the CLI loader)"
-
-# Editable install of nv_core/sr_specs is no longer required. validate.py
-# now defaults to populating the OAV registries via
-# simready.validate.impl.loader.load_validation_implementation against
-# on-disk paths under the foundations checkout. The legacy editable
-# install + repo usd_profiles_codegen flow is reachable via the
-# --use-plugin opt-in flag if needed.
-
-Step "Editable install of simready-oem-sdk-poc (for auto-package step)"
-& $VenvPip install -e $SdkPath
-if ($LASTEXITCODE -ne 0) { Fail "pip install -e simready-oem-sdk-poc failed" }
-Done "SDK editable install complete"
-
-# ---- Smoke check ---------------------------------------------------------
-
-Step "Smoke check"
-& $VenvPython -c @"
-import omni.asset_validator as oav
-from pxr import Usd
-from markdown_it import MarkdownIt
-import simready_sdk
-from simready.validate.impl.loader import load_validation_implementation
-from pathlib import Path
-import os
-foundations = Path(os.environ.get('SIMREADY_FOUNDATIONS_PATH') or r'$FoundationsPath')
-load_validation_implementation(
-    rules_and_requirements_paths=[foundations / 'nv_core/sr_specs/docs/capabilities'],
-    features_paths=[foundations / 'nv_core/sr_specs/docs/features'],
-    profiles_paths=[foundations / 'nv_core/sr_specs/docs/profiles/profiles.toml'],
-)
-pr = oav.ProfileRegistry()
-profiles = list(pr.values())
-print(f'  asset-validator: {oav.__version__ if hasattr(oav,"__version__") else "(no version attr)"}')
-print(f'  profiles loaded: {len(profiles)}')
-print(f'  simready_sdk:    {simready_sdk.__file__}')
-"@
-if ($LASTEXITCODE -ne 0) { Fail "smoke check failed" }
-Done "imports + CLI-loader populated ProfileRegistry working"
-
-# ---- Persist env vars so validate.py finds the deps without args -------
-
-Step "Persist locator env vars (User scope)"
-[Environment]::SetEnvironmentVariable("SIMREADY_PYTHON",           $VenvPython,      "User")
-[Environment]::SetEnvironmentVariable("SIMREADY_FOUNDATIONS_PATH", $FoundationsPath, "User")
-[Environment]::SetEnvironmentVariable("SIMREADY_SDK_PATH",         $SdkPath,         "User")
-$env:SIMREADY_PYTHON           = $VenvPython
-$env:SIMREADY_FOUNDATIONS_PATH = $FoundationsPath
-$env:SIMREADY_SDK_PATH         = $SdkPath
-Note "SIMREADY_PYTHON           = $VenvPython"
-Note "SIMREADY_FOUNDATIONS_PATH = $FoundationsPath"
-Note "SIMREADY_SDK_PATH         = $SdkPath"
-Done "env vars set for current user"
-
-# ---- Done ---------------------------------------------------------------
-
-Write-Host ""
-Write-Host "Bootstrap complete." -ForegroundColor Green
-Write-Host "DepsRoot: $DepsRoot" -ForegroundColor Green
-Write-Host "Next: invoke /simready-report against any asset directory." -ForegroundColor Green
+<#
+.SYNOPSIS
+  Bootstrap the SimReady Pipeline Bot runtime dependencies.
+
+.DESCRIPTION
+  Idempotent. Run once on a fresh machine, or re-run any time to fix a
+  missing dependency. Creates a Python venv, clones the foundation + SDK
+  repos, and pip-installs everything the /simready-report skill needs.
+
+  The foundation specs are *not* editable-installed any more. validate.py
+  now defaults to populating the OAV registries via the simready-validate
+  CLI loader against on-disk paths under the foundations checkout.
+  Avoids the `repo usd_profiles_codegen` codegen step (which depends on
+  internal packman tooling not shipped in the public GitHub repo) and the
+  Forced-include trap in nv_core/sr_specs/pyproject.toml.
+
+  Layout produced (all under -DepsRoot, default $env:LOCALAPPDATA\simready):
+
+    <DepsRoot>\
+      ├── venv\                     # Python venv (created if missing)
+      ├── simready_foundations\     # cloned from NVIDIA GitHub
+      └── simready-oem-sdk-poc\     # cloned from NVIDIA-dev GitHub
+
+  After a successful install the script writes three User-level environment
+  variables so the /simready-report skill can locate everything from any shell:
+
+    SIMREADY_PYTHON           = <DepsRoot>\venv\Scripts\python.exe
+    SIMREADY_FOUNDATIONS_PATH = <DepsRoot>\simready_foundations
+    SIMREADY_SDK_PATH         = <DepsRoot>\simready-oem-sdk-poc
+
+  Override the location with -DepsRoot, e.g.:
+    .\bootstrap.ps1 -DepsRoot D:\simready-deps
+
+  Already have these repos checked out elsewhere? Skip this script and
+  set the two env vars manually.
+
+  Optional (not bootstrapped): a `usd_validation_dashboard_final\` clone —
+  used only to copy Sphinx _static\ assets into rendered doc pages. If
+  absent, the dashboard's doc pages fall back to minimal inline styling.
+
+.NOTES
+  - Reversible: the dirs created here are safe to delete; rerun this
+    script to re-create them. The two env vars can be cleared with
+    `[Environment]::SetEnvironmentVariable("SIMREADY_FOUNDATIONS_PATH", $null, "User")`.
+  - Requires: git, python (3.11+ recommended), and access to
+    github.com/NVIDIA + github.com/NVIDIA-dev (creds via the user's
+    existing git/gh auth).
+  - Never elevates / never modifies system PATH.
+#>
+[CmdletBinding()]
+param(
+  [switch]$Force,                                  # re-clone even if dirs exist
+  [string]$Python = "python",                      # python interpreter to seed the venv
+  [string]$DepsRoot = (Join-Path $env:LOCALAPPDATA "simready"),
+  [string]$FoundationsRepo = "https://github.com/NVIDIA/simready-foundation.git",
+  [string]$SdkRepo         = "https://github.com/NVIDIA-dev/simready-oem-sdk-poc.git"
+)
+
+$ErrorActionPreference = "Stop"
+
+if (-not (Test-Path $DepsRoot)) {
+  New-Item -ItemType Directory -Path $DepsRoot -Force | Out-Null
+}
+$DepsRoot = (Resolve-Path $DepsRoot).Path
+
+$VenvPath        = Join-Path $DepsRoot "venv"
+$FoundationsPath = Join-Path $DepsRoot "simready_foundations"
+$SdkPath         = Join-Path $DepsRoot "simready-oem-sdk-poc"
+
+function Step($msg) { Write-Host ""; Write-Host "==> $msg" -ForegroundColor Cyan }
+function Note($msg) { Write-Host "    $msg" -ForegroundColor DarkGray }
+function Done($msg) { Write-Host "    OK: $msg" -ForegroundColor Green }
+function Fail($msg) { Write-Host "    FAIL: $msg" -ForegroundColor Red; exit 1 }
+
+Write-Host "DepsRoot: $DepsRoot" -ForegroundColor Yellow
+
+# ---- Pre-flight ----------------------------------------------------------
+
+Step "Pre-flight"
+foreach ($cmd in @("git", $Python)) {
+  $found = Get-Command $cmd -ErrorAction SilentlyContinue
+  if (-not $found) { Fail "$cmd not on PATH" }
+  Note "$cmd  -> $($found.Source)"
+}
+
+# ---- Clone the repos -----------------------------------------------------
+
+function Ensure-Repo($name, $url, $path) {
+  if ((Test-Path $path) -and -not $Force) {
+    if (Test-Path (Join-Path $path ".git")) {
+      $existingUrl = $null
+      Push-Location $path
+      try { $existingUrl = (git remote get-url origin 2>$null) } finally { Pop-Location }
+      if ($existingUrl -and ($existingUrl.Trim() -ne $url.Trim())) {
+        Fail "$name at $path has origin '$($existingUrl.Trim())' but expected '$url'. Re-run with -Force to re-clone, or fix manually: git -C `"$path`" remote set-url origin `"$url`""
+      }
+      Note "$name already cloned at $path  (use -Force to re-clone)"
+      return
+    } else {
+      Fail "$path exists but is not a git checkout. Move or delete it first."
+    }
+  }
+  if ((Test-Path $path) -and $Force) {
+    Note "Removing $path (-Force)"
+    Remove-Item -Recurse -Force $path
+  }
+  Note "git clone $url $path"
+  git clone $url $path
+  if ($LASTEXITCODE -ne 0) { Fail "git clone $name failed" }
+  Done "$name cloned"
+}
+
+Step "simready_foundations"
+Ensure-Repo "simready_foundations" $FoundationsRepo $FoundationsPath
+
+Step "simready-oem-sdk-poc"
+Ensure-Repo "simready-oem-sdk-poc" $SdkRepo $SdkPath
+
+# ---- Python venv ---------------------------------------------------------
+
+Step "Python venv at $VenvPath"
+if (-not (Test-Path (Join-Path $VenvPath "Scripts\python.exe"))) {
+  & $Python -m venv $VenvPath
+  if ($LASTEXITCODE -ne 0) { Fail "venv creation failed" }
+  Done "venv created"
+} else {
+  Note "venv already present"
+}
+$VenvPython = Join-Path $VenvPath "Scripts\python.exe"
+$VenvPip    = Join-Path $VenvPath "Scripts\pip.exe"
+
+# ---- Pip installs --------------------------------------------------------
+
+Step "Upgrade pip / install runtime deps"
+& $VenvPython -m pip install --upgrade pip wheel setuptools | Out-Null
+if ($LASTEXITCODE -ne 0) { Fail "pip self-upgrade failed" }
+
+$Pkgs = @(
+  "usd-core==26.5",
+  "omniverse-asset-validator==1.15.1",
+  "omniverse-usd-profiles==1.11.0",
+  "markdown-it-py>=3.0",
+  "click>=8.0",
+  "simready-validate>=2026.4.8"
+)
+& $VenvPip install @Pkgs
+if ($LASTEXITCODE -ne 0) { Fail "pip install (runtime deps) failed" }
+Done "runtime deps installed (incl. simready-validate from PyPI — provides the CLI loader)"
+
+# Editable install of nv_core/sr_specs is no longer required. validate.py
+# now defaults to populating the OAV registries via
+# simready.validate.impl.loader.load_validation_implementation against
+# on-disk paths under the foundations checkout. The legacy editable
+# install + repo usd_profiles_codegen flow is reachable via the
+# --use-plugin opt-in flag if needed.
+
+Step "Editable install of simready-oem-sdk-poc (for auto-package step)"
+& $VenvPip install -e $SdkPath
+if ($LASTEXITCODE -ne 0) { Fail "pip install -e simready-oem-sdk-poc failed" }
+Done "SDK editable install complete"
+
+# ---- Smoke check ---------------------------------------------------------
+
+Step "Smoke check"
+& $VenvPython -c @"
+import omni.asset_validator as oav
+from pxr import Usd
+from markdown_it import MarkdownIt
+import simready_sdk
+from simready.validate.impl.loader import load_validation_implementation
+from pathlib import Path
+import os
+foundations = Path(os.environ.get('SIMREADY_FOUNDATIONS_PATH') or r'$FoundationsPath')
+load_validation_implementation(
+    rules_and_requirements_paths=[foundations / 'nv_core/sr_specs/docs/capabilities'],
+    features_paths=[foundations / 'nv_core/sr_specs/docs/features'],
+    profiles_paths=[foundations / 'nv_core/sr_specs/docs/profiles/profiles.toml'],
+)
+pr = oav.ProfileRegistry()
+profiles = list(pr.values())
+print(f'  asset-validator: {oav.__version__ if hasattr(oav,"__version__") else "(no version attr)"}')
+print(f'  profiles loaded: {len(profiles)}')
+print(f'  simready_sdk:    {simready_sdk.__file__}')
+"@
+if ($LASTEXITCODE -ne 0) { Fail "smoke check failed" }
+Done "imports + CLI-loader populated ProfileRegistry working"
+
+# ---- Persist env vars so validate.py finds the deps without args -------
+
+Step "Persist locator env vars (User scope)"
+[Environment]::SetEnvironmentVariable("SIMREADY_PYTHON",           $VenvPython,      "User")
+[Environment]::SetEnvironmentVariable("SIMREADY_FOUNDATIONS_PATH", $FoundationsPath, "User")
+[Environment]::SetEnvironmentVariable("SIMREADY_SDK_PATH",         $SdkPath,         "User")
+$env:SIMREADY_PYTHON           = $VenvPython
+$env:SIMREADY_FOUNDATIONS_PATH = $FoundationsPath
+$env:SIMREADY_SDK_PATH         = $SdkPath
+Note "SIMREADY_PYTHON           = $VenvPython"
+Note "SIMREADY_FOUNDATIONS_PATH = $FoundationsPath"
+Note "SIMREADY_SDK_PATH         = $SdkPath"
+Done "env vars set for current user"
+
+# ---- Done ---------------------------------------------------------------
+
+Write-Host ""
+Write-Host "Bootstrap complete." -ForegroundColor Green
+Write-Host "DepsRoot: $DepsRoot" -ForegroundColor Green
+Write-Host "Next: invoke /simready-report against any asset directory." -ForegroundColor Green

tools/validation/playbooks/foundations-deviations.md

@@ -1,591 +1,591 @@
-# SimReady Foundations — process deviations
-
-Issues encountered while running the `/simready-report` skill against `yaskawa_local`
-that require changes in **`simready_foundations`** (or a clearly documented
-client-side workaround). These are not playbook bugs — the playbook is working
-around upstream gaps.
-
-Source data for each item: paths/codes observed during the validation run on
-`packages/yaskawa_local/` against `Robot-Body-Isaac` v1.0.0.
-
----
-
-## 1. `Profile.capabilities` returns an empty list for every profile
-
-**Where:** `omni.asset_validator` profile schema (Python registry).
-
-**Observed:**
-```python
-profile = oav.ProfileRegistry().find('Robot-Body-Isaac', '1.0.0')
-profile.capabilities  # → []
-profile.features      # → 2 features, 8 requirements
-```
-Every profile in the registry returns `[]` for `.capabilities`. Profiles now
-declare scope through `.features` — each feature owns its requirements
-directly. The `capabilities` attribute is a leftover from an older schema.
-
-**Impact:** `validate_yaskawa.py` and earlier versions of this playbook's
-`validate.py` filtered the engine's enabled capabilities against
-`profile.capabilities`. Because the latter is always empty, the filter
-disabled **every** capability and reported `enabled capabilities: 0` while
-producing 6,551 issues from rules that ignored the disable calls (see #2).
-
-**Required:** remove `Profile.capabilities`, or populate it from the union of
-the features' capabilities, and update all reference scripts/docs that still
-use it.
-
----
-
-## 2. `engine.enable_*` / `disable_*` do not constrain rule execution
-
-**Where:** `omni.asset_validator.ValidationEngine`.
-
-**Observed:** `engine.enable_feature(f)` and `engine.enable_requirement(r)`
-update `engine.enabled_features` / `engine.enabled_requirements` counters,
-but `engine.validate(stage)` still runs every rule registered via
-`@register_rule`. `engine.enabled_rules` stays at 0 even after enabling
-features and requirements; rules execute regardless.
-
-**Impact:** profile-scoping has to happen post-hoc, by filtering issues
-against the profile's requirement codes. The current playbook does this in
-`validate_one()` (filters failures by `code in profile_codes`).
-
-**Required:** either
-1. make `enable_*` / `disable_*` actually scope rule execution, or
-2. document explicitly that they are display-only and that callers must
-   filter results themselves. Today the API name strongly implies (1).
-
----
-
-## 3. `Robot-Body-Isaac` v1.0.0 silently drops 4 of 6 declared features
-   (TOML ↔ Python registry mismatch)
-
-**Where:** `simready_foundations/_build/target-deps/pip_prebundle/simready/foundation/core/profiles/profiles.toml`
-vs the `Features` enum loaded from
-`simready.foundation.core.features`.
-
-**Observed:** `profiles.toml` declares Robot-Body-Isaac v1.0.0 with six
-features:
-
-| TOML entry | Loads? | Notes |
-|---|---|---|
-| `FET001_BASE_NEUTRAL` v0.1.0 | ✓ | 8 requirements |
-| `FET004_ROBOT_PHYSX` v0.2.0 | ✗ | No such name in `Features` enum (only `FET004_BASE_NEUTRAL`) |
-| `FET021_ROBOT_CORE_ISAAC` v0.2.0 | ✗ | Closest is `FET_021_ROBOT_CORE` v0.2.0 (note underscore + missing `_ISAAC`) |
-| `FET022_DRIVEN_JOINTS_ISAAC` v0.1.0 | ✗ | Closest is `FET_022_DRIVEN_JOINTS` v0.1.0 |
-| `FET024_BASE_ARTICULATION_PHYSX` v0.1.0 | ✗ | Closest is `FET_024_BASE_ARTICULATION` v0.1.0 |
-| `FET100_BASE_ISAACSIM` v0.1.0 | ✓ | 0 requirements |
-
-`pr.find('Robot-Body-Isaac', '1.0.0').features` therefore returns only the
-two features that successfully resolve. Four features (Robot Core, Driven
-Joints, Base Articulation, Robot Physx) are silently dropped — no warning,
-no error.
-
-The rules associated with the dropped features (RC.*, JT.*, RB.*, AT.*) still
-execute (per #2 the engine ignores feature gating), so they appear in the
-raw issue list, but they cannot be attributed to a profile feature for
-roll-up reporting.
-
-**Required:** reconcile the names. Either rename the TOML entries to match
-the `Features` enum (`FET_021_ROBOT_CORE` etc.), or add the `_ISAAC` /
-`_PHYSX` variants to the foundation as real feature implementations. Also
-make profile-feature lookup *fail loudly* when a declared feature can't be
-resolved — silent drop is the worst outcome.
-
-Validation also surfaced real failures with codes from features that
-**aren't even declared in the TOML profile**:
-
-| Code(s) | Source | Notes |
-|---|---|---|
-| `RC.002`, `RC.004` (`thumbnail-exist`), `RC.008`, `RC.009` | `capabilities/isaac_sim/robot_core` | Robot-core rules registered & raising issues, but no profile feature includes them |
-| `NP.001`, `NP.005`, `NP.006`, `NP.008` | `capabilities/visualization/nonvisual_materials` | |
-| `HI.001`, `HI.002` | `capabilities/hierarchy` | (`HI.004` is in profile, others aren't) |
-| `VG.007`, `VG.009`, `VG.016`, `VG.019`, `VG.MESH.001` | `capabilities/visualization/geometry` | (`VG.001` is in profile, the rest aren't) |
-| `EX.01`, `EX.03`, `GSP.001`, `ISA.001`, `VM.MDL.001` | various | |
-
-A "Robot-Body-Isaac" profile that does not require the asset to have a
-thumbnail, robot type, or pinned root joint, but the foundations repo ships
-those as registered rules, is a process gap.
-
-**Required:** extend the profile's features to include the robot-core,
-nonvisual-materials, hierarchy-completeness, and geometry-completeness
-features that are already authored in the foundation; align the JSON capability
-configs (`config/robot-core.json` etc.) with the Python `Profiles` enum.
-
----
-
-## 4. JSON capability config and Python profile registry are not linked
-
-**Where:** `simready_foundations/nv_core/sr_specs/config/robot-core.json` vs
-`simready.foundation.core` Python plugin.
-
-**Observed:** `robot-core.json` declares `RobotCore` capability v1.0.0 with
-the `thumbnail-exist` requirement (and others). The Python registry exposes
-that requirement to the rule machinery (issues with `RC.004` are emitted),
-but no `Profile` exposes `RobotCore` as a feature, so client code that
-introspects `profile.features` to compute pass/fail per feature can't see it.
-
-**Impact:** validation reports list `RC.*` codes in raw issues but cannot map
-them to a feature, so they appear as "uncategorized" failures.
-
-**Required:** wire the JSON capability declarations into the `Features` /
-`Profiles` enums (or into a new `profile.capabilities` accessor that returns
-real entries — see #1).
-
----
-
-## 5. ~87% of issues report `code: UNKNOWN`
-
-**Where:** rules registered in `omni.asset_validator` and SimReady plugins.
-
-**Observed:** of 6,551 issues across 7 robots, **5,695** have `iss.requirement
-is None`, so the issue cannot be attributed to any requirement code:
-```
-  5695  UNKNOWN
-   129  NP.001
-   116  HI.002
-   116  VG.009
-    96  VG.007
-    ...
-```
-These come from rules that don't decorate with `@register_requirements`, so
-they run but have no requirement linkage.
-
-**Impact:** profile-scoped filtering (#2's workaround) drops 87% of the signal;
-those failures appear in the raw issue list but never roll up to a feature
-pass/fail.
-
-**Required:** every rule registered in foundations should declare the
-requirement(s) it enforces via `@register_requirements`, so issues are
-attributable.
-
----
-
-## 6. `init_rules` defaults are inconsistent across consumers
-
-**Where:** `omni.asset_validator.ValidationEngine` constructor and the
-SimReady SDK's engine wrapper.
-
-**Observed:** `validate_yaskawa.py` (top-level reference) explicitly passes
-`init_rules=True` and notes that `simready_sdk.core.engine` passes
-`init_rules=False`, which leaves the engine empty:
-```
-The SDK passes init_rules=False which leaves the engine with no checks,
-producing 'No rules or requirements have been enabled.' for every asset.
-```
-With `init_rules=True` the engine has 124 rules / 118 requirements. With
-`False` it has 0 / 0.
-
-**Required:** make `init_rules=True` the default in the engine, or remove the
-parameter; update `simready_sdk.core.engine` to call it correctly. Today
-choosing the wrong path silently produces a "passes everything" report.
-
----
-
-## 7. Foundation has the wrapper but ships no runnable thumbnail generator
-
-**Where:** `simready_foundations/nv_core/testing_tools/testing_framework/source/job_runner/core/engines/usdrecord/`
-plus lighting rigs at `simready_foundations/nv_core/common_tools/thumbnails/auto_thumbnail_indoor_lighting_rig_{small,medium,large}.usd`.
-
-**Observed:** the foundation defines `UsdRecordCommandBuilder` which builds
-the command `<usdrecord_exe> <asset.usd> <output.png>` and references three
-preset lighting USDs intended to be composed with the asset before rendering.
-But:
-- The `<usdrecord_exe>` is taken from `job.runner_config.executable`. The
-  foundation does not bundle the binary, the venv does not have it, and
-  `pxr.UsdAppUtils` (the Python library backing `usdrecord`) is absent.
-- The `auto_thumbnail_indoor_lighting_rig_*.usd` rigs have no documented
-  composition recipe — there is no published "open the rig, payload the
-  asset, render to 256×256" wrapper script.
-
-`usdrecord` is part of OpenUSD; on this machine it must be installed
-externally. Three working install paths (commands documented for the record;
-none are run automatically by the validator):
-
-1. **Kit Kernel from NGC** (the user already has `ngc` on PATH):
-   ```powershell
-   $env:KIT_VERSION = "106.5.0"
-   ngc registry resource download-version "nvidia/omniverse/kit:$env:KIT_VERSION" `
-     --dest "$env:USERPROFILE\.kit"
-   # `usdrecord.bat` lives at <kit_root>\dev\tools\packman\repo\bld\target-deps\usd\release\bin\usdrecord.bat
-   $env:USDRECORD_BIN = "$env:USERPROFILE\.kit\kit-$env:KIT_VERSION\...\usdrecord.bat"
-   ```
-2. **OpenUSD prebuilt** (NVIDIA developer release):
-   ```powershell
-   # Download from https://developer.nvidia.com/usd (signed-in NGC link),
-   # extract, and point to the binary:
-   $env:USDRECORD_BIN = "C:\openusd\bin\usdrecord.cmd"
-   ```
-3. **Build OpenUSD from source** (heaviest, only if the prebuilt isn't
-   acceptable):
-   ```powershell
-   git clone https://github.com/PixarAnimationStudios/OpenUSD.git C:\src\OpenUSD
-   python C:\src\OpenUSD\build_scripts\build_usd.py --tools C:\openusd
-   $env:USDRECORD_BIN = "C:\openusd\bin\usdrecord.cmd"
-   ```
-
-Once `USDRECORD_BIN` is set (or the binary is on PATH), `validate.py`'s
-`_find_usdrecord()` will pick it up and the validator will invoke it for
-each asset missing a thumbnail at the spec path. Generated PNGs go to
-`report/<set>/_generated_thumbs/<filename>.png` — never into the
-packaged asset tree. Every command run is logged in `results.json` under
-`thumbnail_generation.attempts` and surfaced in the dashboard's "External
-tooling used" panel.
-
-For `yaskawa_local`, six of seven thumbnails were instead pulled from
-`Assets/Isaac/6.0/Isaac/Robots/Yaskawa/Motoman Next/.../.thumbs/256x256/`
-on the Omniverse content S3 bucket (free; no install required). One robot
-(`NHC10DE-A00`) has no S3 thumbnail; without `usdrecord` installed, its tile
-renders the inline SVG "no thumbnail" placeholder.
-
-**Required:** either ship `usdrecord` in the foundation's bundled toolchain,
-or distribute a foundation-side wrapper (e.g. a Kit ext that does
-`UsdAppUtils.framerec.FrameRecorder` programmatically) so `simready ingest
-usd` can produce the spec thumbnail without external installs.
-
----
-
-## 8. Spec docs disagree on the thumbnail filename
-
-**Where:**
-- Spec doc: `nv_core/sr_specs/docs/capabilities/isaac_sim/robot_core/requirements/thumbnail-exist.md`
-- Validation rule: `nv_core/sr_specs/docs/capabilities/isaac_sim/robot_core/validation.py:213`
-- OEM publishing guide: `simready-oem-sdk-poc/docs/oem-publishing-guide-hf.md`
-
-**Observed:**
-- The spec doc's example uses `…/Robot_Name/.thumbs/256x256/Robot.png`
-  (filename = USD stem only, no `.usd` suffix).
-- The rule code computes `…/<filename>.png` where `<filename>` is the full
-  USD filename **including** the `.usd` extension, e.g. `nex4_c00.usd.png`.
-- The OEM publishing guide also uses `robot-a.usd.png` (with `.usd.`).
-- The Isaac S3 bucket uses `NEX4_C00.usd.png` (with `.usd.`).
-
-The rule and most published assets agree (`<filename>.png` with `.usd`); the
-spec doc's example is wrong.
-
-**Required:** fix the spec example in `thumbnail-exist.md` to match the rule.
-
----
-
-## 9. `simready ingest usd` does not lift companion thumbnails
-
-**Where:** `simready-oem-sdk-poc/src/simready_sdk/packager/organizer.py`.
-
-**Observed:** `simready ingest usd ./robot/robot.usd` produces the spec
-layout (`<name>/<name>.usd`, `configuration/`, `materials/`,
-`.thumbs/256x256/` folder) but **does not** copy/rename a thumbnail from any
-companion location into `.thumbs/256x256/<file>.usd.png`. The packager docs
-(`SKILL.md`) call it "thumbnail placeholder" — the directory is created
-empty.
-
-For `yaskawa_local/images/<stem>.usd.usd.png`, no automated path exists for
-the packager to know that file should land at the spec's thumbnail path.
-
-**Required:** the packager should accept a companion-images directory hint
-(e.g. `--thumbs-from <dir>` or a sibling `images/` convention) and lift
-matching files into `.thumbs/256x256/<file>.usd.png` during organize.
-
----
-
-## 10. A foundation rule crashes with `'NoneType' object has no attribute 'JointStateAPI'`
-
-**Where:** somewhere in the `simready.foundation.core` plugin's joint-state
-checker (rule not yet pinned down — issue is reported as `code: UNKNOWN`,
-`rule: None`).
-
-**Observed:** the rule fires on every prim it visits and produces an
-*Uncaught error* issue, accounting for between **566 and 698 issues per
-asset** in our run — i.e., most of what makes the report look noisy:
-```
-UNKNOWN  ×668  Uncaught error: 'NoneType' object has no attribute 'JointStateAPI'
-UNKNOWN  ×566  Uncaught error: 'NoneType' object has no attribute 'JointStateAPI'
-UNKNOWN  ×698  Uncaught error: 'NoneType' object has no attribute 'JointStateAPI'
-```
-The remaining ~150 issues per asset (HI.*, NP.*, RC.*, etc.) are the *real*
-findings.
-
-The crash strongly suggests the rule reads
-`stage.GetPrimAtPath(...).GetAPISchemas()`-style and assumes the result is
-non-`None`. A defensive `if foo is None: continue` would silence the noise;
-the underlying joint-state coverage is presumably what the rule was meant to
-be checking, but currently it produces nothing useful.
-
-**Required:** pin down the rule (grep `JointStateAPI` across
-`simready.foundation.core`), add the missing None-guard, and either register
-the rule's requirement properly or remove it from the engine until it works.
-
----
-
-## 11. `NP.005` — layout mismatch between the rule's spec and `simready ingest usd`, plus a path-printing bug
-
-**Where:**
-- Rule code: `simready_foundations/nv_core/sr_specs/docs/capabilities/core/naming_paths/validation.py:271-320` (`AssetFolderStructureChecker`).
-- Rule spec doc: `simready_foundations/nv_core/sr_specs/docs/capabilities/core/naming_paths/requirements/asset-folder-structure.md`.
-- Packager output: `simready-oem-sdk-poc/src/simready_sdk/packager/organizer.py` (invoked via `simready ingest usd`).
-
-### 11a. Layout mismatch
-
-The NP.005 spec doc requires this structure:
-
-```
-<asset>/                  ← asset folder
-  ├── <intermediate>/     ← exactly ONE intermediate folder (any name)
-  │   └── <main>.usd      ← main USD; NO other .usd files here or below
-  └── materials/          ← supporting folders are SIBLINGS of <intermediate>/
-```
-
-The reference dashboard's FANUC content follows this exactly:
-
-```
-robots/CR/cr_50f_16b/isaac_ready_usd/cr_50f_16b.usd.usd
-robots/CR/cr_50f_16b/configuration/...
-```
-
-But `simready ingest usd` produces a *flat* layout — main USD at the asset
-root, sublayers nested inside the same dir:
-
-```
-<asset>/
-  ├── <asset>.usd
-  └── configuration/
-      ├── <asset>_base.usd
-      ├── <asset>_physics.usd
-      └── <asset>_sensor.usd
-```
-
-The rule walks `os.path.dirname(stage_path)` (which is `<asset>/` in the
-flat layout) and flags every sublayer as "stray". The sublayers aren't
-stray — they're the spec-required configuration files — but the rule's
-walk-set includes them because the packager produced an
-NP.005-non-compliant layout.
-
-So: **two foundation artifacts disagree on the canonical asset layout.**
-The packaging spec (`simready-packaging`'s SKILL.md) and `simready ingest
-usd` produce one layout; NP.005's spec doc and the FANUC reference content
-use a different layout.
-
-### 11b. Path-printing bug (independent)
-
-```python
-# capabilities/core/naming_paths/validation.py:308-313
-for root, dirs, files in os.walk(current_dir):
-    for file in files:
-        found_file = os.path.join(root, file).replace("\\", "/")
-        if file.endswith((".usd", ".usda")) and found_file != stage_path:
-            relative_path = os.path.relpath(file, current_dir)   # ← bug
-            other_usd_files.append(relative_path)
-```
-
-`file` here is just the basename returned by `os.walk` (e.g.
-`nex10_c00_base.usd`). `os.path.relpath` resolves it against
-`os.getcwd()`, not against `root`. With CWD =
-`<workspace>/.claude/skills/simready-report/`, the rule prints:
-
-```
-..\..\..\.claude\skills\simready-report\nex10_c00_base.usd
-```
-
-— a path back to the validator's CWD, where the file emphatically does not
-exist. Should be `os.path.relpath(found_file, current_dir)` (`found_file`
-is the correct joined path, already computed on the line above and
-otherwise unused). With that one-character fix the cited path becomes
-`configuration/nex10_c00_base.usd` — pointing at the real file.
-
-### Required
-
-**Pick one canonical layout and reconcile both sides.** Either:
-
-- **Update the packager** (`simready ingest usd`) to emit the
-  NP.005-compliant `<asset>/<intermediate>/<main>.usd` structure with
-  `configuration/` and `materials/` as siblings of `<intermediate>/`. This
-  is what the FANUC reference content already uses. The packaging skill
-  doc and any consumers (manifest tooling, dashboard, etc.) need updating
-  in lockstep.
-
-- **Or update NP.005's spec doc and rule** to bless the flat layout that
-  `simready ingest usd` actually produces — i.e., explicitly whitelist the
-  spec-mandated subdirectories (`configuration/`, `materials/`,
-  `.thumbs/`, `.simready/`) when scanning for stray USDs.
-
-Whichever is chosen, fix the path-printing bug at the same time
-(`relpath(file, …)` → `relpath(found_file, …)`) so the message names a
-real on-disk path.
-
----
-
-## 12. The "example" capability is active in production validation
-
-**Where:**
-`simready_foundations/nv_core/sr_specs/docs/capabilities/example/example.py`,
-codes `EX.01`, `EX.02`, `EX.03`.
-
-**Observed:** every asset fails:
-- `EX.01` — *"Stage has no mesh prims."*
-- `EX.03` — *"Test prim 'TestBlob' not found under default prim."*
-
-The source comment on this capability is literally `"example"` and the
-rule docs (`example.md`) describe it as a tutorial — `EX.03` requires a
-prim named `TestBlob` to exist as a child of the default prim. That's
-clearly not an asset requirement; it's pedagogical scaffolding to teach
-plugin authors how to register a rule.
-
-**Required:** unregister the `Example` capability from production rule
-loading (move it to test fixtures, gate it behind an env var, or delete it
-from the shipped plugin). Today every real asset takes 2–3 spurious EX
-failures.
-
----
-
-## 13. `EX.01` and `VG.MESH.001` are duplicate checks under different codes
-
-**Where:**
-- `capabilities/example/example.py:52` — `EX.01`: *"Stage has no mesh prims."*
-- `capabilities/visualization/geometry/validation.py:836` — `VG.MESH.001`:
-  *"Stage does not contain any meshes."*
-
-**Observed:** both fire on every asset, with effectively identical
-semantics. `EX.01` is the example/tutorial version; `VG.MESH.001` is the
-real version. Reporting both is noise.
-
-**Required:** when #12 is fixed, this disappears for free. Otherwise,
-`EX.01` should be retired and any consumer that still references it should
-be redirected to `VG.MESH.001`.
-
----
-
-## 14. `HI.002` rejects valid USD xform-op decompositions
-
-**Where:** `capabilities/hierarchy/validation.py:62-104`
-(`ExclusiveXFormParentChecker`).
-
-**Observed:** ~14 issues per asset, message *"Prim Parent has no
-xformOp:rotate."* The rule requires every Gprim parent to author both
-`xformOp:translate` and (a substring-matching) `xformOp:rotate*`:
-
-```python
-if not any("xformOp:rotate" in op.GetAttr().GetName() for op in xform_ops):
-    self._AddFailedCheck("Prim Parent has no xformOp:rotate.", …)
-```
-
-That's an over-strict reading of USD. Valid alternatives the rule rejects:
-
-- `xformOp:transform` (single 4×4 matrix — encodes translate + rotate +
-  scale together).
-- No xform ops at all (identity transform — also a valid stateless prim).
-- Any combination authored on an inherited parent and overridden by the
-  Gprim's own ops.
-
-Yaskawa's robots author matrix transforms in many places, which is what
-trips this. The check should accept *any* xformable spec that resolves to a
-defined transform — likely via `Xformable.GetLocalTransformation()`
-returning a non-error result — rather than pattern-matching specific op
-names.
-
-**Required:** rewrite the check to validate *that the prim resolves to a
-defined transform*, not that it authored a particular op vocabulary.
-
----
-
-## 15. `NP.001` flags the conventional `/Looks` scope as a naming violation
-
-**Where:** `capabilities/core/naming_paths/validation.py:125-160`
-(`PrimNamingConventionChecker`).
-
-**Observed:** every asset fails NP.001 ×8 with *"Prim 'Looks' does not
-follow consistent naming convention (camelCase or snake_case)."*
-
-`Looks` is the long-established USD convention for the materials scope
-under an asset's default prim — it's used by Pixar's published USD
-samples, NVIDIA's Isaac/Omniverse content, and most authoring tools
-(Houdini, Maya USD, Kit). The rule's `CAMEL_CASE_PATTERN` and
-`SNAKE_CASE_PATTERN` regexes don't accept the `Looks` PascalCase
-single-word, so it reports a violation on a name the broader USD ecosystem
-treats as canonical.
-
-**Required:** either whitelist the well-known USD scope names (`Looks`,
-`Geometry`, `Cameras`, `Lights`, `Animation`, `Render`, etc.) or accept
-PascalCase as a valid convention alongside camelCase / snake_case.
-
----
-
-## 16. `VM.MDL.001` and `NP.008` double-report the same MDL resolution failure
-
-**Where:**
-- `capabilities/visualization/materials/...` (VM.MDL.001 — *"The path
-  OmniPBR.mdl does not exist."*)
-- `capabilities/core/naming_paths/...` (NP.008 — *"Asset path 'OmniPBR.mdl'
-  on attribute 'info:mdl:sourceAsset' at prim '/.../Looks/.../...' does not
-  resolve to an existing file."*)
-
-**Observed:** every asset emits the same number of VM.MDL.001 and NP.008
-issues (9 each on `nex10_c00`, 6 each on `nex20_c00`, etc.) — both rules
-fire on the same `info:mdl:sourceAsset = @OmniPBR.mdl@` attribute. NP.008
-gives a useful prim path; VM.MDL.001 just says "doesn't exist".
-
-Separately: `OmniPBR.mdl` is a **standard NVIDIA MDL** that ships with Kit
-and Isaac. The validator's asset resolver doesn't know where to find it
-(likely missing an MDL search path in the SimReady plugin's resolver
-config), so a perfectly portable, NVIDIA-blessed material reference is
-flagged as broken on every asset.
-
-**Required:**
-1. Configure the SimReady validator plugin to register Kit's standard MDL
-   search paths (`mdl/`, `omni/mdl/`, etc.) so `OmniPBR.mdl` and other
-   shipped MDLs resolve without the customer having to vendor them.
-2. Pick one of VM.MDL.001 / NP.008 as the canonical "MDL doesn't resolve"
-   code. Have the other defer when the first has fired against the same
-   attribute.
-
----
-
-## 17. `RC.002` flags spec-mandated robot metadata as "overrides"
-
-**Where:** `capabilities/isaac_sim/robot_core/...`, `RC.002`.
-
-**Observed:** every asset fails RC.002 with messages like:
-
-```
-Prim is overridden: /nex10_c00, ['isaac:description', 'isaac:license',
-'isaac:namespace', 'isaac:robotType']
-```
-
-`isaac:description`, `isaac:license`, `isaac:namespace`,
-`isaac:robotType` look like exactly the kind of metadata the SimReady
-robot spec wants you to author on the robot's default prim — but RC.002
-is treating any authored override of the default prim's properties as a
-violation.
-
-If those four `isaac:*` attributes are spec-mandated, the rule should
-*require* them, not flag their presence. If they're optional metadata, the
-rule should ignore them — overriding metadata fields on the default prim
-is a normal authoring pattern, not a layout error.
-
-**Required:** clarify the spec around the `isaac:*` namespace on the
-robot default prim and update RC.002 to either require those fields, or
-exclude them from the "this prim shouldn't be overridden" check, or split
-into two rules (one for "structural" overrides, one for the spec
-metadata).
-
----
-
-## Summary
-
-| # | Severity | Area | One-line |
-|---|---|---|---|
-| 1 | high | profile schema | `Profile.capabilities` is dead; should be removed or populated |
-| 2 | high | engine API | `enable_*`/`disable_*` don't actually scope rule execution |
-| 3 | high | profile content | Robot-Body-Isaac v1.0.0 silently drops 4 of 6 declared features |
-| 4 | high | profile schema | JSON capability configs aren't linked to the Python profile registry |
-| 5 | high | rule registration | Most rules don't declare `@register_requirements` → 87% UNKNOWN |
-| 6 | medium | engine API | `init_rules` defaults inconsistent; SDK silently turns off all checks |
-| 7 | medium | tooling | No headless thumbnail generator ships with foundations |
-| 8 | low | spec docs | `thumbnail-exist.md` example contradicts the actual rule |
-| 9 | medium | packaging | `simready ingest usd` doesn't lift companion thumbnails into spec layout |
-| 10 | high | rule reliability | Rule crashes on `JointStateAPI` access → ~600 UNKNOWN issues per asset |
-| 11 | high | spec/packager mismatch | NP.005 expects `<asset>/<intermediate>/<main>.usd`; packager produces flat layout. Plus `relpath(file,…)` should be `relpath(found_file,…)` |
-| 12 | high | rule scoping | "Example" tutorial capability (`EX.*`) is active in production validation |
-| 13 | medium | rule duplication | `EX.01` and `VG.MESH.001` are the same check |
-| 14 | high | rule correctness | `HI.002` rejects matrix transforms (`xformOp:transform`) and identity transforms |
-| 15 | medium | rule correctness | `NP.001` rejects the conventional `/Looks` scope name |
-| 16 | high | rule correctness | `OmniPBR.mdl` (standard NVIDIA MDL) doesn't resolve; both VM.MDL.001 and NP.008 fire on the same attribute |
-| 17 | medium | spec ambiguity | `RC.002` flags spec-looking `isaac:*` metadata as illegal "overrides" |
+# SimReady Foundations — process deviations
+
+Issues encountered while running the `/simready-report` skill against `yaskawa_local`
+that require changes in **`simready_foundations`** (or a clearly documented
+client-side workaround). These are not playbook bugs — the playbook is working
+around upstream gaps.
+
+Source data for each item: paths/codes observed during the validation run on
+`packages/yaskawa_local/` against `Robot-Body-Isaac` v1.0.0.
+
+---
+
+## 1. `Profile.capabilities` returns an empty list for every profile
+
+**Where:** `omni.asset_validator` profile schema (Python registry).
+
+**Observed:**
+```python
+profile = oav.ProfileRegistry().find('Robot-Body-Isaac', '1.0.0')
+profile.capabilities  # → []
+profile.features      # → 2 features, 8 requirements
+```
+Every profile in the registry returns `[]` for `.capabilities`. Profiles now
+declare scope through `.features` — each feature owns its requirements
+directly. The `capabilities` attribute is a leftover from an older schema.
+
+**Impact:** `validate_yaskawa.py` and earlier versions of this playbook's
+`validate.py` filtered the engine's enabled capabilities against
+`profile.capabilities`. Because the latter is always empty, the filter
+disabled **every** capability and reported `enabled capabilities: 0` while
+producing 6,551 issues from rules that ignored the disable calls (see #2).
+
+**Required:** remove `Profile.capabilities`, or populate it from the union of
+the features' capabilities, and update all reference scripts/docs that still
+use it.
+
+---
+
+## 2. `engine.enable_*` / `disable_*` do not constrain rule execution
+
+**Where:** `omni.asset_validator.ValidationEngine`.
+
+**Observed:** `engine.enable_feature(f)` and `engine.enable_requirement(r)`
+update `engine.enabled_features` / `engine.enabled_requirements` counters,
+but `engine.validate(stage)` still runs every rule registered via
+`@register_rule`. `engine.enabled_rules` stays at 0 even after enabling
+features and requirements; rules execute regardless.
+
+**Impact:** profile-scoping has to happen post-hoc, by filtering issues
+against the profile's requirement codes. The current playbook does this in
+`validate_one()` (filters failures by `code in profile_codes`).
+
+**Required:** either
+1. make `enable_*` / `disable_*` actually scope rule execution, or
+2. document explicitly that they are display-only and that callers must
+   filter results themselves. Today the API name strongly implies (1).
+
+---
+
+## 3. `Robot-Body-Isaac` v1.0.0 silently drops 4 of 6 declared features
+   (TOML ↔ Python registry mismatch)
+
+**Where:** `simready_foundations/_build/target-deps/pip_prebundle/simready/foundation/core/profiles/profiles.toml`
+vs the `Features` enum loaded from
+`simready.foundation.core.features`.
+
+**Observed:** `profiles.toml` declares Robot-Body-Isaac v1.0.0 with six
+features:
+
+| TOML entry | Loads? | Notes |
+|---|---|---|
+| `FET001_BASE_NEUTRAL` v0.1.0 | ✓ | 8 requirements |
+| `FET004_ROBOT_PHYSX` v0.2.0 | ✗ | No such name in `Features` enum (only `FET004_BASE_NEUTRAL`) |
+| `FET021_ROBOT_CORE_ISAAC` v0.2.0 | ✗ | Closest is `FET_021_ROBOT_CORE` v0.2.0 (note underscore + missing `_ISAAC`) |
+| `FET022_DRIVEN_JOINTS_ISAAC` v0.1.0 | ✗ | Closest is `FET_022_DRIVEN_JOINTS` v0.1.0 |
+| `FET024_BASE_ARTICULATION_PHYSX` v0.1.0 | ✗ | Closest is `FET_024_BASE_ARTICULATION` v0.1.0 |
+| `FET100_BASE_ISAACSIM` v0.1.0 | ✓ | 0 requirements |
+
+`pr.find('Robot-Body-Isaac', '1.0.0').features` therefore returns only the
+two features that successfully resolve. Four features (Robot Core, Driven
+Joints, Base Articulation, Robot Physx) are silently dropped — no warning,
+no error.
+
+The rules associated with the dropped features (RC.*, JT.*, RB.*, AT.*) still
+execute (per #2 the engine ignores feature gating), so they appear in the
+raw issue list, but they cannot be attributed to a profile feature for
+roll-up reporting.
+
+**Required:** reconcile the names. Either rename the TOML entries to match
+the `Features` enum (`FET_021_ROBOT_CORE` etc.), or add the `_ISAAC` /
+`_PHYSX` variants to the foundation as real feature implementations. Also
+make profile-feature lookup *fail loudly* when a declared feature can't be
+resolved — silent drop is the worst outcome.
+
+Validation also surfaced real failures with codes from features that
+**aren't even declared in the TOML profile**:
+
+| Code(s) | Source | Notes |
+|---|---|---|
+| `RC.002`, `RC.004` (`thumbnail-exist`), `RC.008`, `RC.009` | `capabilities/isaac_sim/robot_core` | Robot-core rules registered & raising issues, but no profile feature includes them |
+| `NP.001`, `NP.005`, `NP.006`, `NP.008` | `capabilities/visualization/nonvisual_materials` | |
+| `HI.001`, `HI.002` | `capabilities/hierarchy` | (`HI.004` is in profile, others aren't) |
+| `VG.007`, `VG.009`, `VG.016`, `VG.019`, `VG.MESH.001` | `capabilities/visualization/geometry` | (`VG.001` is in profile, the rest aren't) |
+| `EX.01`, `EX.03`, `GSP.001`, `ISA.001`, `VM.MDL.001` | various | |
+
+A "Robot-Body-Isaac" profile that does not require the asset to have a
+thumbnail, robot type, or pinned root joint, but the foundations repo ships
+those as registered rules, is a process gap.
+
+**Required:** extend the profile's features to include the robot-core,
+nonvisual-materials, hierarchy-completeness, and geometry-completeness
+features that are already authored in the foundation; align the JSON capability
+configs (`config/robot-core.json` etc.) with the Python `Profiles` enum.
+
+---
+
+## 4. JSON capability config and Python profile registry are not linked
+
+**Where:** `simready_foundations/nv_core/sr_specs/config/robot-core.json` vs
+`simready.foundation.core` Python plugin.
+
+**Observed:** `robot-core.json` declares `RobotCore` capability v1.0.0 with
+the `thumbnail-exist` requirement (and others). The Python registry exposes
+that requirement to the rule machinery (issues with `RC.004` are emitted),
+but no `Profile` exposes `RobotCore` as a feature, so client code that
+introspects `profile.features` to compute pass/fail per feature can't see it.
+
+**Impact:** validation reports list `RC.*` codes in raw issues but cannot map
+them to a feature, so they appear as "uncategorized" failures.
+
+**Required:** wire the JSON capability declarations into the `Features` /
+`Profiles` enums (or into a new `profile.capabilities` accessor that returns
+real entries — see #1).
+
+---
+
+## 5. ~87% of issues report `code: UNKNOWN`
+
+**Where:** rules registered in `omni.asset_validator` and SimReady plugins.
+
+**Observed:** of 6,551 issues across 7 robots, **5,695** have `iss.requirement
+is None`, so the issue cannot be attributed to any requirement code:
+```
+  5695  UNKNOWN
+   129  NP.001
+   116  HI.002
+   116  VG.009
+    96  VG.007
+    ...
+```
+These come from rules that don't decorate with `@register_requirements`, so
+they run but have no requirement linkage.
+
+**Impact:** profile-scoped filtering (#2's workaround) drops 87% of the signal;
+those failures appear in the raw issue list but never roll up to a feature
+pass/fail.
+
+**Required:** every rule registered in foundations should declare the
+requirement(s) it enforces via `@register_requirements`, so issues are
+attributable.
+
+---
+
+## 6. `init_rules` defaults are inconsistent across consumers
+
+**Where:** `omni.asset_validator.ValidationEngine` constructor and the
+SimReady SDK's engine wrapper.
+
+**Observed:** `validate_yaskawa.py` (top-level reference) explicitly passes
+`init_rules=True` and notes that `simready_sdk.core.engine` passes
+`init_rules=False`, which leaves the engine empty:
+```
+The SDK passes init_rules=False which leaves the engine with no checks,
+producing 'No rules or requirements have been enabled.' for every asset.
+```
+With `init_rules=True` the engine has 124 rules / 118 requirements. With
+`False` it has 0 / 0.
+
+**Required:** make `init_rules=True` the default in the engine, or remove the
+parameter; update `simready_sdk.core.engine` to call it correctly. Today
+choosing the wrong path silently produces a "passes everything" report.
+
+---
+
+## 7. Foundation has the wrapper but ships no runnable thumbnail generator
+
+**Where:** `simready_foundations/nv_core/testing_tools/testing_framework/source/job_runner/core/engines/usdrecord/`
+plus lighting rigs at `simready_foundations/nv_core/common_tools/thumbnails/auto_thumbnail_indoor_lighting_rig_{small,medium,large}.usd`.
+
+**Observed:** the foundation defines `UsdRecordCommandBuilder` which builds
+the command `<usdrecord_exe> <asset.usd> <output.png>` and references three
+preset lighting USDs intended to be composed with the asset before rendering.
+But:
+- The `<usdrecord_exe>` is taken from `job.runner_config.executable`. The
+  foundation does not bundle the binary, the venv does not have it, and
+  `pxr.UsdAppUtils` (the Python library backing `usdrecord`) is absent.
+- The `auto_thumbnail_indoor_lighting_rig_*.usd` rigs have no documented
+  composition recipe — there is no published "open the rig, payload the
+  asset, render to 256×256" wrapper script.
+
+`usdrecord` is part of OpenUSD; on this machine it must be installed
+externally. Three working install paths (commands documented for the record;
+none are run automatically by the validator):
+
+1. **Kit Kernel from NGC** (the user already has `ngc` on PATH):
+   ```powershell
+   $env:KIT_VERSION = "106.5.0"
+   ngc registry resource download-version "nvidia/omniverse/kit:$env:KIT_VERSION" `
+     --dest "$env:USERPROFILE\.kit"
+   # `usdrecord.bat` lives at <kit_root>\dev\tools\packman\repo\bld\target-deps\usd\release\bin\usdrecord.bat
+   $env:USDRECORD_BIN = "$env:USERPROFILE\.kit\kit-$env:KIT_VERSION\...\usdrecord.bat"
+   ```
+2. **OpenUSD prebuilt** (NVIDIA developer release):
+   ```powershell
+   # Download from https://developer.nvidia.com/usd (signed-in NGC link),
+   # extract, and point to the binary:
+   $env:USDRECORD_BIN = "C:\openusd\bin\usdrecord.cmd"
+   ```
+3. **Build OpenUSD from source** (heaviest, only if the prebuilt isn't
+   acceptable):
+   ```powershell
+   git clone https://github.com/PixarAnimationStudios/OpenUSD.git C:\src\OpenUSD
+   python C:\src\OpenUSD\build_scripts\build_usd.py --tools C:\openusd
+   $env:USDRECORD_BIN = "C:\openusd\bin\usdrecord.cmd"
+   ```
+
+Once `USDRECORD_BIN` is set (or the binary is on PATH), `validate.py`'s
+`_find_usdrecord()` will pick it up and the validator will invoke it for
+each asset missing a thumbnail at the spec path. Generated PNGs go to
+`report/<set>/_generated_thumbs/<filename>.png` — never into the
+packaged asset tree. Every command run is logged in `results.json` under
+`thumbnail_generation.attempts` and surfaced in the dashboard's "External
+tooling used" panel.
+
+For `yaskawa_local`, six of seven thumbnails were instead pulled from
+`Assets/Isaac/6.0/Isaac/Robots/Yaskawa/Motoman Next/.../.thumbs/256x256/`
+on the Omniverse content S3 bucket (free; no install required). One robot
+(`NHC10DE-A00`) has no S3 thumbnail; without `usdrecord` installed, its tile
+renders the inline SVG "no thumbnail" placeholder.
+
+**Required:** either ship `usdrecord` in the foundation's bundled toolchain,
+or distribute a foundation-side wrapper (e.g. a Kit ext that does
+`UsdAppUtils.framerec.FrameRecorder` programmatically) so `simready ingest
+usd` can produce the spec thumbnail without external installs.
+
+---
+
+## 8. Spec docs disagree on the thumbnail filename
+
+**Where:**
+- Spec doc: `nv_core/sr_specs/docs/capabilities/isaac_sim/robot_core/requirements/thumbnail-exist.md`
+- Validation rule: `nv_core/sr_specs/docs/capabilities/isaac_sim/robot_core/validation.py:213`
+- OEM publishing guide: `simready-oem-sdk-poc/docs/oem-publishing-guide-hf.md`
+
+**Observed:**
+- The spec doc's example uses `…/Robot_Name/.thumbs/256x256/Robot.png`
+  (filename = USD stem only, no `.usd` suffix).
+- The rule code computes `…/<filename>.png` where `<filename>` is the full
+  USD filename **including** the `.usd` extension, e.g. `nex4_c00.usd.png`.
+- The OEM publishing guide also uses `robot-a.usd.png` (with `.usd.`).
+- The Isaac S3 bucket uses `NEX4_C00.usd.png` (with `.usd.`).
+
+The rule and most published assets agree (`<filename>.png` with `.usd`); the
+spec doc's example is wrong.
+
+**Required:** fix the spec example in `thumbnail-exist.md` to match the rule.
+
+---
+
+## 9. `simready ingest usd` does not lift companion thumbnails
+
+**Where:** `simready-oem-sdk-poc/src/simready_sdk/packager/organizer.py`.
+
+**Observed:** `simready ingest usd ./robot/robot.usd` produces the spec
+layout (`<name>/<name>.usd`, `configuration/`, `materials/`,
+`.thumbs/256x256/` folder) but **does not** copy/rename a thumbnail from any
+companion location into `.thumbs/256x256/<file>.usd.png`. The packager docs
+(`SKILL.md`) call it "thumbnail placeholder" — the directory is created
+empty.
+
+For `yaskawa_local/images/<stem>.usd.usd.png`, no automated path exists for
+the packager to know that file should land at the spec's thumbnail path.
+
+**Required:** the packager should accept a companion-images directory hint
+(e.g. `--thumbs-from <dir>` or a sibling `images/` convention) and lift
+matching files into `.thumbs/256x256/<file>.usd.png` during organize.
+
+---
+
+## 10. A foundation rule crashes with `'NoneType' object has no attribute 'JointStateAPI'`
+
+**Where:** somewhere in the `simready.foundation.core` plugin's joint-state
+checker (rule not yet pinned down — issue is reported as `code: UNKNOWN`,
+`rule: None`).
+
+**Observed:** the rule fires on every prim it visits and produces an
+*Uncaught error* issue, accounting for between **566 and 698 issues per
+asset** in our run — i.e., most of what makes the report look noisy:
+```
+UNKNOWN  ×668  Uncaught error: 'NoneType' object has no attribute 'JointStateAPI'
+UNKNOWN  ×566  Uncaught error: 'NoneType' object has no attribute 'JointStateAPI'
+UNKNOWN  ×698  Uncaught error: 'NoneType' object has no attribute 'JointStateAPI'
+```
+The remaining ~150 issues per asset (HI.*, NP.*, RC.*, etc.) are the *real*
+findings.
+
+The crash strongly suggests the rule reads
+`stage.GetPrimAtPath(...).GetAPISchemas()`-style and assumes the result is
+non-`None`. A defensive `if foo is None: continue` would silence the noise;
+the underlying joint-state coverage is presumably what the rule was meant to
+be checking, but currently it produces nothing useful.
+
+**Required:** pin down the rule (grep `JointStateAPI` across
+`simready.foundation.core`), add the missing None-guard, and either register
+the rule's requirement properly or remove it from the engine until it works.
+
+---
+
+## 11. `NP.005` — layout mismatch between the rule's spec and `simready ingest usd`, plus a path-printing bug
+
+**Where:**
+- Rule code: `simready_foundations/nv_core/sr_specs/docs/capabilities/core/naming_paths/validation.py:271-320` (`AssetFolderStructureChecker`).
+- Rule spec doc: `simready_foundations/nv_core/sr_specs/docs/capabilities/core/naming_paths/requirements/asset-folder-structure.md`.
+- Packager output: `simready-oem-sdk-poc/src/simready_sdk/packager/organizer.py` (invoked via `simready ingest usd`).
+
+### 11a. Layout mismatch
+
+The NP.005 spec doc requires this structure:
+
+```
+<asset>/                  ← asset folder
+  ├── <intermediate>/     ← exactly ONE intermediate folder (any name)
+  │   └── <main>.usd      ← main USD; NO other .usd files here or below
+  └── materials/          ← supporting folders are SIBLINGS of <intermediate>/
+```
+
+The reference dashboard's FANUC content follows this exactly:
+
+```
+robots/CR/cr_50f_16b/isaac_ready_usd/cr_50f_16b.usd.usd
+robots/CR/cr_50f_16b/configuration/...
+```
+
+But `simready ingest usd` produces a *flat* layout — main USD at the asset
+root, sublayers nested inside the same dir:
+
+```
+<asset>/
+  ├── <asset>.usd
+  └── configuration/
+      ├── <asset>_base.usd
+      ├── <asset>_physics.usd
+      └── <asset>_sensor.usd
+```
+
+The rule walks `os.path.dirname(stage_path)` (which is `<asset>/` in the
+flat layout) and flags every sublayer as "stray". The sublayers aren't
+stray — they're the spec-required configuration files — but the rule's
+walk-set includes them because the packager produced an
+NP.005-non-compliant layout.
+
+So: **two foundation artifacts disagree on the canonical asset layout.**
+The packaging spec (`simready-packaging`'s SKILL.md) and `simready ingest
+usd` produce one layout; NP.005's spec doc and the FANUC reference content
+use a different layout.
+
+### 11b. Path-printing bug (independent)
+
+```python
+# capabilities/core/naming_paths/validation.py:308-313
+for root, dirs, files in os.walk(current_dir):
+    for file in files:
+        found_file = os.path.join(root, file).replace("\\", "/")
+        if file.endswith((".usd", ".usda")) and found_file != stage_path:
+            relative_path = os.path.relpath(file, current_dir)   # ← bug
+            other_usd_files.append(relative_path)
+```
+
+`file` here is just the basename returned by `os.walk` (e.g.
+`nex10_c00_base.usd`). `os.path.relpath` resolves it against
+`os.getcwd()`, not against `root`. With CWD =
+`<workspace>/.claude/skills/simready-report/`, the rule prints:
+
+```
+..\..\..\.claude\skills\simready-report\nex10_c00_base.usd
+```
+
+— a path back to the validator's CWD, where the file emphatically does not
+exist. Should be `os.path.relpath(found_file, current_dir)` (`found_file`
+is the correct joined path, already computed on the line above and
+otherwise unused). With that one-character fix the cited path becomes
+`configuration/nex10_c00_base.usd` — pointing at the real file.
+
+### Required
+
+**Pick one canonical layout and reconcile both sides.** Either:
+
+- **Update the packager** (`simready ingest usd`) to emit the
+  NP.005-compliant `<asset>/<intermediate>/<main>.usd` structure with
+  `configuration/` and `materials/` as siblings of `<intermediate>/`. This
+  is what the FANUC reference content already uses. The packaging skill
+  doc and any consumers (manifest tooling, dashboard, etc.) need updating
+  in lockstep.
+
+- **Or update NP.005's spec doc and rule** to bless the flat layout that
+  `simready ingest usd` actually produces — i.e., explicitly whitelist the
+  spec-mandated subdirectories (`configuration/`, `materials/`,
+  `.thumbs/`, `.simready/`) when scanning for stray USDs.
+
+Whichever is chosen, fix the path-printing bug at the same time
+(`relpath(file, …)` → `relpath(found_file, …)`) so the message names a
+real on-disk path.
+
+---
+
+## 12. The "example" capability is active in production validation
+
+**Where:**
+`simready_foundations/nv_core/sr_specs/docs/capabilities/example/example.py`,
+codes `EX.01`, `EX.02`, `EX.03`.
+
+**Observed:** every asset fails:
+- `EX.01` — *"Stage has no mesh prims."*
+- `EX.03` — *"Test prim 'TestBlob' not found under default prim."*
+
+The source comment on this capability is literally `"example"` and the
+rule docs (`example.md`) describe it as a tutorial — `EX.03` requires a
+prim named `TestBlob` to exist as a child of the default prim. That's
+clearly not an asset requirement; it's pedagogical scaffolding to teach
+plugin authors how to register a rule.
+
+**Required:** unregister the `Example` capability from production rule
+loading (move it to test fixtures, gate it behind an env var, or delete it
+from the shipped plugin). Today every real asset takes 2–3 spurious EX
+failures.
+
+---
+
+## 13. `EX.01` and `VG.MESH.001` are duplicate checks under different codes
+
+**Where:**
+- `capabilities/example/example.py:52` — `EX.01`: *"Stage has no mesh prims."*
+- `capabilities/visualization/geometry/validation.py:836` — `VG.MESH.001`:
+  *"Stage does not contain any meshes."*
+
+**Observed:** both fire on every asset, with effectively identical
+semantics. `EX.01` is the example/tutorial version; `VG.MESH.001` is the
+real version. Reporting both is noise.
+
+**Required:** when #12 is fixed, this disappears for free. Otherwise,
+`EX.01` should be retired and any consumer that still references it should
+be redirected to `VG.MESH.001`.
+
+---
+
+## 14. `HI.002` rejects valid USD xform-op decompositions
+
+**Where:** `capabilities/hierarchy/validation.py:62-104`
+(`ExclusiveXFormParentChecker`).
+
+**Observed:** ~14 issues per asset, message *"Prim Parent has no
+xformOp:rotate."* The rule requires every Gprim parent to author both
+`xformOp:translate` and (a substring-matching) `xformOp:rotate*`:
+
+```python
+if not any("xformOp:rotate" in op.GetAttr().GetName() for op in xform_ops):
+    self._AddFailedCheck("Prim Parent has no xformOp:rotate.", …)
+```
+
+That's an over-strict reading of USD. Valid alternatives the rule rejects:
+
+- `xformOp:transform` (single 4×4 matrix — encodes translate + rotate +
+  scale together).
+- No xform ops at all (identity transform — also a valid stateless prim).
+- Any combination authored on an inherited parent and overridden by the
+  Gprim's own ops.
+
+Yaskawa's robots author matrix transforms in many places, which is what
+trips this. The check should accept *any* xformable spec that resolves to a
+defined transform — likely via `Xformable.GetLocalTransformation()`
+returning a non-error result — rather than pattern-matching specific op
+names.
+
+**Required:** rewrite the check to validate *that the prim resolves to a
+defined transform*, not that it authored a particular op vocabulary.
+
+---
+
+## 15. `NP.001` flags the conventional `/Looks` scope as a naming violation
+
+**Where:** `capabilities/core/naming_paths/validation.py:125-160`
+(`PrimNamingConventionChecker`).
+
+**Observed:** every asset fails NP.001 ×8 with *"Prim 'Looks' does not
+follow consistent naming convention (camelCase or snake_case)."*
+
+`Looks` is the long-established USD convention for the materials scope
+under an asset's default prim — it's used by Pixar's published USD
+samples, NVIDIA's Isaac/Omniverse content, and most authoring tools
+(Houdini, Maya USD, Kit). The rule's `CAMEL_CASE_PATTERN` and
+`SNAKE_CASE_PATTERN` regexes don't accept the `Looks` PascalCase
+single-word, so it reports a violation on a name the broader USD ecosystem
+treats as canonical.
+
+**Required:** either whitelist the well-known USD scope names (`Looks`,
+`Geometry`, `Cameras`, `Lights`, `Animation`, `Render`, etc.) or accept
+PascalCase as a valid convention alongside camelCase / snake_case.
+
+---
+
+## 16. `VM.MDL.001` and `NP.008` double-report the same MDL resolution failure
+
+**Where:**
+- `capabilities/visualization/materials/...` (VM.MDL.001 — *"The path
+  OmniPBR.mdl does not exist."*)
+- `capabilities/core/naming_paths/...` (NP.008 — *"Asset path 'OmniPBR.mdl'
+  on attribute 'info:mdl:sourceAsset' at prim '/.../Looks/.../...' does not
+  resolve to an existing file."*)
+
+**Observed:** every asset emits the same number of VM.MDL.001 and NP.008
+issues (9 each on `nex10_c00`, 6 each on `nex20_c00`, etc.) — both rules
+fire on the same `info:mdl:sourceAsset = @OmniPBR.mdl@` attribute. NP.008
+gives a useful prim path; VM.MDL.001 just says "doesn't exist".
+
+Separately: `OmniPBR.mdl` is a **standard NVIDIA MDL** that ships with Kit
+and Isaac. The validator's asset resolver doesn't know where to find it
+(likely missing an MDL search path in the SimReady plugin's resolver
+config), so a perfectly portable, NVIDIA-blessed material reference is
+flagged as broken on every asset.
+
+**Required:**
+1. Configure the SimReady validator plugin to register Kit's standard MDL
+   search paths (`mdl/`, `omni/mdl/`, etc.) so `OmniPBR.mdl` and other
+   shipped MDLs resolve without the customer having to vendor them.
+2. Pick one of VM.MDL.001 / NP.008 as the canonical "MDL doesn't resolve"
+   code. Have the other defer when the first has fired against the same
+   attribute.
+
+---
+
+## 17. `RC.002` flags spec-mandated robot metadata as "overrides"
+
+**Where:** `capabilities/isaac_sim/robot_core/...`, `RC.002`.
+
+**Observed:** every asset fails RC.002 with messages like:
+
+```
+Prim is overridden: /nex10_c00, ['isaac:description', 'isaac:license',
+'isaac:namespace', 'isaac:robotType']
+```
+
+`isaac:description`, `isaac:license`, `isaac:namespace`,
+`isaac:robotType` look like exactly the kind of metadata the SimReady
+robot spec wants you to author on the robot's default prim — but RC.002
+is treating any authored override of the default prim's properties as a
+violation.
+
+If those four `isaac:*` attributes are spec-mandated, the rule should
+*require* them, not flag their presence. If they're optional metadata, the
+rule should ignore them — overriding metadata fields on the default prim
+is a normal authoring pattern, not a layout error.
+
+**Required:** clarify the spec around the `isaac:*` namespace on the
+robot default prim and update RC.002 to either require those fields, or
+exclude them from the "this prim shouldn't be overridden" check, or split
+into two rules (one for "structural" overrides, one for the spec
+metadata).
+
+---
+
+## Summary
+
+| # | Severity | Area | One-line |
+|---|---|---|---|
+| 1 | high | profile schema | `Profile.capabilities` is dead; should be removed or populated |
+| 2 | high | engine API | `enable_*`/`disable_*` don't actually scope rule execution |
+| 3 | high | profile content | Robot-Body-Isaac v1.0.0 silently drops 4 of 6 declared features |
+| 4 | high | profile schema | JSON capability configs aren't linked to the Python profile registry |
+| 5 | high | rule registration | Most rules don't declare `@register_requirements` → 87% UNKNOWN |
+| 6 | medium | engine API | `init_rules` defaults inconsistent; SDK silently turns off all checks |
+| 7 | medium | tooling | No headless thumbnail generator ships with foundations |
+| 8 | low | spec docs | `thumbnail-exist.md` example contradicts the actual rule |
+| 9 | medium | packaging | `simready ingest usd` doesn't lift companion thumbnails into spec layout |
+| 10 | high | rule reliability | Rule crashes on `JointStateAPI` access → ~600 UNKNOWN issues per asset |
+| 11 | high | spec/packager mismatch | NP.005 expects `<asset>/<intermediate>/<main>.usd`; packager produces flat layout. Plus `relpath(file,…)` should be `relpath(found_file,…)` |
+| 12 | high | rule scoping | "Example" tutorial capability (`EX.*`) is active in production validation |
+| 13 | medium | rule duplication | `EX.01` and `VG.MESH.001` are the same check |
+| 14 | high | rule correctness | `HI.002` rejects matrix transforms (`xformOp:transform`) and identity transforms |
+| 15 | medium | rule correctness | `NP.001` rejects the conventional `/Looks` scope name |
+| 16 | high | rule correctness | `OmniPBR.mdl` (standard NVIDIA MDL) doesn't resolve; both VM.MDL.001 and NP.008 fire on the same attribute |
+| 17 | medium | spec ambiguity | `RC.002` flags spec-looking `isaac:*` metadata as illegal "overrides" |

tools/validation/plugins/simready-report/plugin.json

@@ -1,11 +1,11 @@
-{
-  "$schema": "https://json.schemastore.org/claude-code-plugin",
-  "name": "simready-report",
-  "version": "0.2.0",
-  "description": "SimReady asset pipeline tooling. Ships two slash commands: /simready-report (validate customer USD assets and emit an HTML dashboard + external-deps provenance report) and /simready-package (run the simready ingest packaging step alone, no validation).",
-  "author": {
-    "name": "loginowskid",
-    "email": "dloginowski@nvidia.com"
-  },
-  "homepage": "https://github.com/loginowskid/simready-playbook"
-}
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin",
+  "name": "simready-report",
+  "version": "0.2.0",
+  "description": "SimReady asset pipeline tooling. Ships two slash commands: /simready-report (validate customer USD assets and emit an HTML dashboard + external-deps provenance report) and /simready-package (run the simready ingest packaging step alone, no validation).",
+  "author": {
+    "name": "loginowskid",
+    "email": "dloginowski@nvidia.com"
+  },
+  "homepage": "https://github.com/loginowskid/simready-playbook"
+}

tools/validation/plugins/simready-report/skills/simready-package/SKILL.md

@@ -1,62 +1,62 @@
----
-name: simready-package
-description: Package SimReady customer assets by running `simready ingest usd` per interface USD. Standalone alternative to /simready-report's auto-package step. Invoke with /simready-package <name-or-path>.
----
-
-# /simready-package
-
-Run the SimReady packaging step on a directory of customer asset subfolders, without running validation or generating a dashboard.
-
-## Usage
-
-- `/simready-package` (no arg) — package the **current working directory**.
-- `/simready-package <path>` — package the given directory by absolute or relative path.
-
-## When to use
-
-- You have a directory like `assets_to_validate/<name>/` with one subfolder per asset (each containing an interface USD), and want to produce a packaged tree without running validation.
-- You want to inspect the packaged output before invoking `/simready-report`.
-- You're iterating on packaging configuration and don't want the validation overhead each time.
-
-`/simready-report` still auto-packages when its target sits under an `assets_to_validate/` dir, so you don't *need* `/simready-package` to use the report. They're independent.
-
-## Steps for Claude when `/simready-package` is invoked
-
-1. **Resolve the target.** No arg → CWD. With an arg, pass it through to the script.
-2. **Run the packager** from this skill directory using whatever Python the user's environment provides — prefer `$env:SIMREADY_PYTHON` (set by `bootstrap.ps1`) over `python` on PATH:
-
-   PowerShell:
-   ```
-   $py = if ($env:SIMREADY_PYTHON) { $env:SIMREADY_PYTHON } else { "python" }
-   & $py package.py "<arg-or-empty>"
-   ```
-   Bash/zsh:
-   ```
-   "${SIMREADY_PYTHON:-python}" package.py "<arg-or-empty>"
-   ```
-   Add `--profile NAME` only if the user explicitly asked for a non-default profile. Add `--output DIR` only if the user explicitly asked for a non-default output.
-3. **Surface results.** Echo the script's `SUMMARY:` line and the absolute `OUTPUT:` path.
-4. **If the script exits with "simready CLI not found"**, relay verbatim. The user needs `simready-oem-sdk-poc` installed into the active Python, or to run `bootstrap.ps1`. Don't run the bootstrap on the user's behalf without explicit confirmation.
-
-## Default output location
-
-- When the target sits under an `assets_to_validate/<name>/` directory, output goes to the sibling `packages/<name>/`.
-- Otherwise, output goes to `<target>.parent/packages/<target.name>/`.
-- Override with `--output <path>`.
-
-## What the packager does
-
-- **Interface discovery.** For each immediate subfolder of the target, picks one interface USD per asset:
-  - exactly one USD at root → that one
-  - otherwise → the USD whose stem matches the folder name (case- and hyphen/underscore-insensitive)
-  - otherwise → all USDs (rare)
-  - subfolders starting with `.` or `_` are ignored
-- **Idempotent.** Skips assets already packaged (existing `<output>/<stem>/<filename>.usd`).
-- **Per-asset invocation.** Calls `simready ingest usd <interface> -o <output> -p <profile> --no-validate` for each interface, with a 120s timeout.
-- **Summary.** Prints `SUMMARY: packaged=N skipped=N failed=N` and the resolved `OUTPUT:` path. Exits non-zero if any asset failed to ingest (the rest still get packaged).
-
-## Configuration
-
-- `SIMREADY_PYTHON` (recommended): full path to the Python interpreter that has `simready-oem-sdk-poc` installed. Set automatically by `bootstrap.ps1`.
-- Default profile: `Robot-Body-Runnable`. Override with `--profile NAME`.
-- Default output: see above. Override with `--output DIR`.
+---
+name: simready-package
+description: Package SimReady customer assets by running `simready ingest usd` per interface USD. Standalone alternative to /simready-report's auto-package step. Invoke with /simready-package <name-or-path>.
+---
+
+# /simready-package
+
+Run the SimReady packaging step on a directory of customer asset subfolders, without running validation or generating a dashboard.
+
+## Usage
+
+- `/simready-package` (no arg) — package the **current working directory**.
+- `/simready-package <path>` — package the given directory by absolute or relative path.
+
+## When to use
+
+- You have a directory like `assets_to_validate/<name>/` with one subfolder per asset (each containing an interface USD), and want to produce a packaged tree without running validation.
+- You want to inspect the packaged output before invoking `/simready-report`.
+- You're iterating on packaging configuration and don't want the validation overhead each time.
+
+`/simready-report` still auto-packages when its target sits under an `assets_to_validate/` dir, so you don't *need* `/simready-package` to use the report. They're independent.
+
+## Steps for Claude when `/simready-package` is invoked
+
+1. **Resolve the target.** No arg → CWD. With an arg, pass it through to the script.
+2. **Run the packager** from this skill directory using whatever Python the user's environment provides — prefer `$env:SIMREADY_PYTHON` (set by `bootstrap.ps1`) over `python` on PATH:
+
+   PowerShell:
+   ```
+   $py = if ($env:SIMREADY_PYTHON) { $env:SIMREADY_PYTHON } else { "python" }
+   & $py package.py "<arg-or-empty>"
+   ```
+   Bash/zsh:
+   ```
+   "${SIMREADY_PYTHON:-python}" package.py "<arg-or-empty>"
+   ```
+   Add `--profile NAME` only if the user explicitly asked for a non-default profile. Add `--output DIR` only if the user explicitly asked for a non-default output.
+3. **Surface results.** Echo the script's `SUMMARY:` line and the absolute `OUTPUT:` path.
+4. **If the script exits with "simready CLI not found"**, relay verbatim. The user needs `simready-oem-sdk-poc` installed into the active Python, or to run `bootstrap.ps1`. Don't run the bootstrap on the user's behalf without explicit confirmation.
+
+## Default output location
+
+- When the target sits under an `assets_to_validate/<name>/` directory, output goes to the sibling `packages/<name>/`.
+- Otherwise, output goes to `<target>.parent/packages/<target.name>/`.
+- Override with `--output <path>`.
+
+## What the packager does
+
+- **Interface discovery.** For each immediate subfolder of the target, picks one interface USD per asset:
+  - exactly one USD at root → that one
+  - otherwise → the USD whose stem matches the folder name (case- and hyphen/underscore-insensitive)
+  - otherwise → all USDs (rare)
+  - subfolders starting with `.` or `_` are ignored
+- **Idempotent.** Skips assets already packaged (existing `<output>/<stem>/<filename>.usd`).
+- **Per-asset invocation.** Calls `simready ingest usd <interface> -o <output> -p <profile> --no-validate` for each interface, with a 120s timeout.
+- **Summary.** Prints `SUMMARY: packaged=N skipped=N failed=N` and the resolved `OUTPUT:` path. Exits non-zero if any asset failed to ingest (the rest still get packaged).
+
+## Configuration
+
+- `SIMREADY_PYTHON` (recommended): full path to the Python interpreter that has `simready-oem-sdk-poc` installed. Set automatically by `bootstrap.ps1`.
+- Default profile: `Robot-Body-Runnable`. Override with `--profile NAME`.
+- Default output: see above. Override with `--output DIR`.

tools/validation/plugins/simready-report/skills/simready-package/package.py

@@ -1,143 +1,143 @@
-"""SimReady asset packaging — entry point for the /simready-package skill.
-
-Usage:
-    python package.py <target_dir> [--profile NAME] [--output DIR]
-
-For each immediate subfolder of <target_dir> containing a USD file, picks
-the interface USD and runs `simready ingest usd` on it, producing a
-packaged tree under <output_dir>. Independent of /simready-report — runs
-the packaging step alone, without validation or dashboard generation.
-"""
-from __future__ import annotations
-
-import argparse
-import os
-import shutil
-import subprocess
-import sys
-from pathlib import Path
-
-USD_EXTS = (".usd", ".usda", ".usdc", ".usdz")
-
-
-def _find_simready_cli() -> str | None:
-    """Locate the `simready` CLI in a layout-agnostic way.
-
-    Order: (1) on PATH, (2) alongside `sys.executable` (covers any active
-    venv/conda regardless of OS).
-    """
-    on_path = shutil.which("simready")
-    if on_path:
-        return on_path
-    py_bin = Path(sys.executable).parent
-    for candidate in (py_bin / "simready.exe", py_bin / "simready"):
-        if candidate.is_file():
-            return str(candidate)
-    return None
-
-
-def _discover_interface_usds(target: Path) -> list[Path]:
-    """Pick one interface USD per immediate subfolder of `target`.
-
-    Heuristic per subfolder:
-      - If exactly one USD at root, that's the interface.
-      - Else prefer the USD whose stem matches the folder name (case- and
-        hyphen/underscore-insensitive).
-      - Else fall back to packaging all of them.
-    Subfolders starting with "." or "_" are ignored.
-    """
-    interface_files: list[Path] = []
-    for sub in sorted(target.iterdir()):
-        if not sub.is_dir() or sub.name.startswith((".", "_")):
-            continue
-        usds = [p for ext in USD_EXTS for p in sub.glob(f"*{ext}")]
-        if not usds:
-            continue
-        if len(usds) == 1:
-            interface_files.append(usds[0])
-            continue
-        named = [p for p in usds if p.stem.lower() == sub.name.lower().replace("-", "_")]
-        if named:
-            interface_files.append(named[0])
-        else:
-            interface_files.extend(usds)
-    return interface_files
-
-
-def _default_output(target: Path) -> Path:
-    """Pick a default output dir based on target location."""
-    target_str = str(target).replace("\\", "/")
-    if "/assets_to_validate/" in target_str:
-        # Workspace-style layout: <X>/assets_to_validate/<name>
-        # → output at sibling packages dir: <X>/packages/<name>
-        return target.parent.parent / "packages" / target.name
-    return target.parent / "packages" / target.name
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description="Package SimReady assets via `simready ingest usd`.")
-    ap.add_argument("target", nargs="?", default=None,
-                    help="Directory containing one or more asset subfolders (default: cwd)")
-    ap.add_argument("--profile", default="Robot-Body-Runnable",
-                    help="Profile passed to `simready ingest usd -p` (default: Robot-Body-Runnable)")
-    ap.add_argument("--output", default=None,
-                    help="Output dir (default: <target>.parent/packages/<target.name>, "
-                         "or sibling-of-assets_to_validate/packages/<name> when applicable)")
-    args = ap.parse_args()
-
-    target = Path(args.target).resolve() if args.target else Path.cwd().resolve()
-    if not target.is_dir():
-        print(f"ERROR: target is not a directory: {target}", flush=True)
-        return 2
-
-    simready_exe = _find_simready_cli()
-    if simready_exe is None:
-        print("ERROR: `simready` CLI not found on PATH or alongside the active Python.", flush=True)
-        print("       Install simready-oem-sdk-poc into the active Python, or run bootstrap.ps1.", flush=True)
-        return 2
-
-    interface_files = _discover_interface_usds(target)
-    if not interface_files:
-        print(f"ERROR: no USD files found in immediate subfolders of {target}.", flush=True)
-        print("       /simready-package expects each asset to live in its own subfolder "
-              "with an interface USD.", flush=True)
-        return 2
-
-    output = Path(args.output).resolve() if args.output else _default_output(target)
-    output.mkdir(parents=True, exist_ok=True)
-
-    print(f"Target:  {target}", flush=True)
-    print(f"Output:  {output}", flush=True)
-    print(f"Profile: {args.profile}", flush=True)
-    print(f"CLI:     {simready_exe}", flush=True)
-    print(f"Discovered {len(interface_files)} interface USD(s).", flush=True)
-
-    env = {**os.environ, "PYTHONIOENCODING": "utf-8", "PYTHONUTF8": "1"}
-    packaged = 0
-    skipped = 0
-    failures: list[tuple[str, str]] = []
-
-    for usd in interface_files:
-        already = output / usd.stem / usd.name
-        if already.is_file():
-            print(f"  skip (already packaged): {usd.name}", flush=True)
-            skipped += 1
-            continue
-        print(f"  package: {usd.name}", flush=True)
-        cmd = [simready_exe, "ingest", "usd", str(usd),
-               "-o", str(output), "-p", args.profile, "--no-validate"]
-        try:
-            subprocess.run(cmd, env=env, check=True, capture_output=True, text=True, timeout=120)
-            packaged += 1
-        except subprocess.CalledProcessError as e:
-            err = (e.stderr or "")[-300:] or str(e)
-            failures.append((usd.name, err))
-            print(f"  FAILED: {usd.name} - {err}", flush=True)
-
-    print(f"\nSUMMARY: packaged={packaged} skipped={skipped} failed={len(failures)}", flush=True)
-    print(f"OUTPUT: {output}", flush=True)
-    return 0 if not failures else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())
+"""SimReady asset packaging — entry point for the /simready-package skill.
+
+Usage:
+    python package.py <target_dir> [--profile NAME] [--output DIR]
+
+For each immediate subfolder of <target_dir> containing a USD file, picks
+the interface USD and runs `simready ingest usd` on it, producing a
+packaged tree under <output_dir>. Independent of /simready-report — runs
+the packaging step alone, without validation or dashboard generation.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+USD_EXTS = (".usd", ".usda", ".usdc", ".usdz")
+
+
+def _find_simready_cli() -> str | None:
+    """Locate the `simready` CLI in a layout-agnostic way.
+
+    Order: (1) on PATH, (2) alongside `sys.executable` (covers any active
+    venv/conda regardless of OS).
+    """
+    on_path = shutil.which("simready")
+    if on_path:
+        return on_path
+    py_bin = Path(sys.executable).parent
+    for candidate in (py_bin / "simready.exe", py_bin / "simready"):
+        if candidate.is_file():
+            return str(candidate)
+    return None
+
+
+def _discover_interface_usds(target: Path) -> list[Path]:
+    """Pick one interface USD per immediate subfolder of `target`.
+
+    Heuristic per subfolder:
+      - If exactly one USD at root, that's the interface.
+      - Else prefer the USD whose stem matches the folder name (case- and
+        hyphen/underscore-insensitive).
+      - Else fall back to packaging all of them.
+    Subfolders starting with "." or "_" are ignored.
+    """
+    interface_files: list[Path] = []
+    for sub in sorted(target.iterdir()):
+        if not sub.is_dir() or sub.name.startswith((".", "_")):
+            continue
+        usds = [p for ext in USD_EXTS for p in sub.glob(f"*{ext}")]
+        if not usds:
+            continue
+        if len(usds) == 1:
+            interface_files.append(usds[0])
+            continue
+        named = [p for p in usds if p.stem.lower() == sub.name.lower().replace("-", "_")]
+        if named:
+            interface_files.append(named[0])
+        else:
+            interface_files.extend(usds)
+    return interface_files
+
+
+def _default_output(target: Path) -> Path:
+    """Pick a default output dir based on target location."""
+    target_str = str(target).replace("\\", "/")
+    if "/assets_to_validate/" in target_str:
+        # Workspace-style layout: <X>/assets_to_validate/<name>
+        # → output at sibling packages dir: <X>/packages/<name>
+        return target.parent.parent / "packages" / target.name
+    return target.parent / "packages" / target.name
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Package SimReady assets via `simready ingest usd`.")
+    ap.add_argument("target", nargs="?", default=None,
+                    help="Directory containing one or more asset subfolders (default: cwd)")
+    ap.add_argument("--profile", default="Robot-Body-Runnable",
+                    help="Profile passed to `simready ingest usd -p` (default: Robot-Body-Runnable)")
+    ap.add_argument("--output", default=None,
+                    help="Output dir (default: <target>.parent/packages/<target.name>, "
+                         "or sibling-of-assets_to_validate/packages/<name> when applicable)")
+    args = ap.parse_args()
+
+    target = Path(args.target).resolve() if args.target else Path.cwd().resolve()
+    if not target.is_dir():
+        print(f"ERROR: target is not a directory: {target}", flush=True)
+        return 2
+
+    simready_exe = _find_simready_cli()
+    if simready_exe is None:
+        print("ERROR: `simready` CLI not found on PATH or alongside the active Python.", flush=True)
+        print("       Install simready-oem-sdk-poc into the active Python, or run bootstrap.ps1.", flush=True)
+        return 2
+
+    interface_files = _discover_interface_usds(target)
+    if not interface_files:
+        print(f"ERROR: no USD files found in immediate subfolders of {target}.", flush=True)
+        print("       /simready-package expects each asset to live in its own subfolder "
+              "with an interface USD.", flush=True)
+        return 2
+
+    output = Path(args.output).resolve() if args.output else _default_output(target)
+    output.mkdir(parents=True, exist_ok=True)
+
+    print(f"Target:  {target}", flush=True)
+    print(f"Output:  {output}", flush=True)
+    print(f"Profile: {args.profile}", flush=True)
+    print(f"CLI:     {simready_exe}", flush=True)
+    print(f"Discovered {len(interface_files)} interface USD(s).", flush=True)
+
+    env = {**os.environ, "PYTHONIOENCODING": "utf-8", "PYTHONUTF8": "1"}
+    packaged = 0
+    skipped = 0
+    failures: list[tuple[str, str]] = []
+
+    for usd in interface_files:
+        already = output / usd.stem / usd.name
+        if already.is_file():
+            print(f"  skip (already packaged): {usd.name}", flush=True)
+            skipped += 1
+            continue
+        print(f"  package: {usd.name}", flush=True)
+        cmd = [simready_exe, "ingest", "usd", str(usd),
+               "-o", str(output), "-p", args.profile, "--no-validate"]
+        try:
+            subprocess.run(cmd, env=env, check=True, capture_output=True, text=True, timeout=120)
+            packaged += 1
+        except subprocess.CalledProcessError as e:
+            err = (e.stderr or "")[-300:] or str(e)
+            failures.append((usd.name, err))
+            print(f"  FAILED: {usd.name} - {err}", flush=True)
+
+    print(f"\nSUMMARY: packaged={packaged} skipped={skipped} failed={len(failures)}", flush=True)
+    print(f"OUTPUT: {output}", flush=True)
+    return 0 if not failures else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tools/validation/plugins/simready-report/skills/simready-report/SKILL.md

@@ -1,137 +1,137 @@
----
-name: simready-report
-description: Validate SimReady customer assets against the foundation specs. Produces a dashboard HTML report and an external-dependencies provenance report. Invoke with /simready-report <name-or-path>.
----
-
-# /simready-report
-
-Validate a SimReady customer asset set.
-
-## Usage
-
-- `/simready-report` (no arg) — validate the **current working directory**. This is the normal way to run the skill: `cd` into the directory holding the customer asset(s) and invoke.
-- `/simready-report <path>` — validate any directory by absolute or relative path. Override for the no-arg default.
-- `/simready-report <name>` — bare name (no path separators). Tries `<cwd>/<name>` first; if running inside a playbook clone, also tries `<workspace>/assets_to_validate/<name>` for back-compat.
-
-## Install paths
-
-The skill is layout-agnostic — it auto-detects whether it's running inside a playbook clone (`BOT.md` in an ancestor directory) and adjusts defaults accordingly.
-
-**Plugin marketplace install (no clone needed):**
-```
-/plugin marketplace add loginowskid/simready-playbook
-/plugin install simready-report
-```
-Then `/simready-report` works from any directory. Reports default to `<cwd>/report/<target-name>/`. Foundation specs and SDK locations come from env vars (see Configuration).
-
-**Cloned playbook (project skill or local marketplace):**
-If `simready-playbook` is cloned, the skill walks up from its own location to find `BOT.md` and uses workspace-relative defaults: reports under `<workspace>/report/`, optional auto-package into `<workspace>/packages/`, default foundations/sdk lookup at `<workspace>/../simready_foundations` and `<workspace>/../simready-oem-sdk-poc`.
-
-## Runtime dependencies
-
-Wherever the skill is installed, it needs:
-
-- A Python with `usd-core`, `omniverse-asset-validator`, `markdown-it-py`, and `simready-validate>=2026.4.8` importable. Any Python works (system, venv, conda). The default validation path populates the OAV registries via `simready.validate.impl.loader.load_validation_implementation`, matching the official `simready-validate` CLI workflow — no editable install of the foundation specs is required.
-- A `simready_foundations` checkout cloned from `github.com/NVIDIA/simready-foundation` (or the `simready-foundation-staging` mirror). Override default lookup with `SIMREADY_FOUNDATIONS_PATH=<path>`.
-- The `simready-oem-sdk-poc` checkout (only if the user wants the auto-package step for raw asset trees). Override with `SIMREADY_SDK_PATH=<path>`. The `simready` CLI itself is found via `PATH` first, then alongside the active Python.
-
-Legacy fallback: pass `--use-plugin` to load via the `simready.foundation.core:SimReadyPlugin` setuptools entry-point instead (requires the editable install of `nv_core/sr_specs` + the internal `repo usd_profiles_codegen` step). Kept for the GitLab-era workflow; not needed for GitHub-based runs.
-
-For a Windows convenience setup that creates a sibling venv + clones, run `bootstrap.ps1` from a cloned playbook. **Don't run it without confirming with the user first** — they may already have these dependencies elsewhere, or be on a non-Windows system.
-
-Optional: a `usd_validation_dashboard_final/` clone next to the playbook supplies a Sphinx `_static/` theme for rendered doc pages. Without it, doc pages use minimal inline styling — the dashboard still works.
-
-## Steps for Claude when `/simready-report` is invoked
-
-The Python invocation pattern (used in steps 2 and 3 below) — prefer `$env:SIMREADY_PYTHON` (set by `bootstrap.ps1`), fall back to `python` on PATH:
-
-   PowerShell: `$py = if ($env:SIMREADY_PYTHON) { $env:SIMREADY_PYTHON } else { "python" }; & $py …`
-   Bash/zsh:   `"${SIMREADY_PYTHON:-python}" …`
-
-1. **Resolve the target.**
-   - No arg → CWD.
-   - With an arg: pass it through. The script tries it as a path, then `<cwd>/<name>`, then `<workspace>/assets_to_validate/<name>` (clone only) for back-compat.
-2. **Pick the profile (spec selector).** Unless the user already named a specific profile in their request, list the registered profiles and ask them to pick before validating:
-   ```
-   <py> validate.py --list-profiles
-   ```
-   This emits one `PROFILE: <id> v<version>` line per registered profile (typically ~11 across the Robot-Body / Prop-Robotics / Package families). Present them grouped by family with `Robot-Body-Runnable v1.0.0` marked as the default; let the user accept the default or pick another. Pass the chosen `<id>` and `<version>` through as `--profile` and `--version` in step 3.
-3. **Run the validator** from the skill directory:
-   ```
-   <py> validate.py "<arg-or-empty>" --profile <id> --version <version>
-   ```
-   If you skipped the selector because the user named a profile up front, use that. If the user said something like "just use the default", pass `Robot-Body-Runnable` v1.0.0 without prompting.
-4. **Surface results.** Echo the script's `SUMMARY:` line and the absolute path to the report's `index.html`.
-5. **If `validate.py` exits with "runtime prerequisites missing"**, relay the message verbatim. If running inside a clone on Windows, suggest `bootstrap.ps1` (after confirming with the user). Otherwise direct the user to install the deps into their Python and/or set `SIMREADY_FOUNDATIONS_PATH` / `SIMREADY_SDK_PATH` to existing checkouts. Do not run the bootstrap on the user's behalf without explicit confirmation.
-6. **If `validate.py` exits with "target … failed sanity check"**, relay the listed problems verbatim. Don't retry without an explicit user instruction — the check is there to prevent accidental whole-drive scans, output-dir self-validation, and empty-dir runs.
-
-## What `validate.py` does on its own
-
-- **Workspace detection.** Walks up from the skill's directory and treats the first ancestor containing `BOT.md` as the workspace. None of these defaults matter when overridden by env vars / `--output`.
-- **Prerequisite check.** Verifies `omni.asset_validator` / `pxr` / `markdown_it` import in the active Python and that the foundations checkout is findable. On miss: prints actionable error and exits 2.
-- **Sanity check on the resolved target.** Refuses (exit 2) if any of:
-  - Inside a clone: target is the workspace root, or under `<workspace>/.claude/`, `playbooks/`, `report/`, `packages/`, or `plugins/`.
-  - Target is too high in the filesystem (≤2 path components — e.g. `C:\` or `C:\Users\`).
-  - Target has no USD files at root **and** none in any of its immediate subfolders.
-- **Auto-package.** When the resolved target lives under an `assets_to_validate/<name>/` directory, calls `simready ingest usd` per interface USD into a sibling `packages/<name>/` (workspace-anchored when in a clone, else sibling-of-`assets_to_validate/`). Skipped per asset if already packaged. Skipped with a warning if the `simready` CLI isn't on PATH.
-- **Asset thumbnails.** For each validated asset, copies `<asset_dir>/.thumbs/256x256/<filename>.png` (if present at the spec path) into `<out_dir>/images/<filename>.png`. Missing thumbnails render the inline placeholder.
-- **Doc rendering.** For every feature/requirement code referenced by the report, renders the foundation's source markdown to HTML inside `<out_dir>/docs/<rel_path>`. If `usd_validation_dashboard_final/_static/` exists, it's copied once so pages match the reference Sphinx theme; otherwise pages use minimal inline CSS.
-
-## Outputs
-
-Written to the resolved output directory. **Default**: `<target>/.reports/<target-name>.<profile>/` — i.e. dropped inside the asset dir the user pointed at, in a `.reports/` subdir. Examples:
-
-- `/simready-report yaskawa_local` (default profile) → `yaskawa_local/.reports/yaskawa_local.Robot-Body-Runnable/`
-- `/simready-report yaskawa_local` (with `--profile Prop-Robotics-Neutral --version 2.0.0`) → `yaskawa_local/.reports/yaskawa_local.Prop-Robotics-Neutral/`
-
-The `.reports/` prefix starts with `.`, so `discover_assets` automatically skips it on subsequent runs — re-running `/simready-report` from inside the target is safe. Multiple profiles against the same target produce sibling subfolders under `.reports/`, never overwriting each other. Override the whole path with `--output`.
-
-- `index.html` — dashboard: summary cards, asset filter, per-asset failed/passed features, "Other failed requirements" panel, compliance footer.
-- `results.json` — raw issues per asset, plus thumbnail provenance.
-- `images/<filename>.png` — per-asset thumbnails (mirrored from the spec path inside the packaged tree).
-- `docs/` — foundation feature/requirement docs rendered to HTML; `_static/` carries the Sphinx theme assets so pages match the reference dashboard.
-- `external_dependencies_report.html` + `.json` — **only emitted when there's something to report** (one or more externally-resolved layers, or one or more scan-time issues). Anonymous in-memory layers are not counted as external. Three sections when present:
-  1. External assets needed (anything resolved outside the target dir).
-  2. What was done to obtain each (provenance log per layer).
-  3. Issues encountered while building the report.
-
-## Kit-rooted mode (`--use-kit`)
-
-**Auto-default:** `validate.py` auto-enables `--use-kit` whenever the chosen profile is in the PhysX-bearing set (`Robot-Body-Physx`, `Robot-Body-Isaac`, `Robot-Body-Runnable`, `Prop-Robotics-Physx`, `Prop-Robotics-Isaac`). The pip-only path's P2 filter silently drops `physxschema_unavailable` / `omnipbr_unresolved` findings, which makes a "passed" result misleading on those profiles — the checks that matter never actually ran. Pass `--no-use-kit` to opt out (e.g. when you knowingly want the fast filtered run); pass `--use-kit` explicitly to force it on a Neutral-family profile.
-
-Under the hood: when `--use-kit` is on, the script re-execs itself through `_kit_wrapper.py` using a Kit-rooted Python that boots `isaacsim.SimulationApp({"headless": True})` before importing `pxr`, so `PhysxSchema`, the PhysX joint rules, and Kit's stock MDL resolution all work for real. When off (Neutral-family profiles by default, or after `--no-use-kit`), the pip-only venv runs and the P2 filter trims the resulting noise (~900 issues dropped on a typical robot asset) so reports stay readable.
-
-- Resolution order for the Kit Python: `--kit-python <path>` → `$SIMREADY_KIT_PYTHON` → `C:\isaacsim6\_build\windows-x86_64\release\python.bat` (Isaac Sim 6 source build on this team's machines).
-- Cost: ~10–30 s of SimulationApp boot on top of normal validation time. The script automatically forces `--workers 1` in Kit mode so we don't pay the boot again per worker.
-- One-time setup: the Kit-rooted Python needs the same runtime deps the pip venv has. From within the Kit Python:
-  ```
-  <kit-python.bat> -m pip install omniverse-asset-validator markdown-it-py
-  <kit-python.bat> -m pip install -e <foundations>/nv_core/sr_specs
-  <kit-python.bat> -m pip install -e <simready-oem-sdk-poc>    # only if auto-packaging is needed
-  ```
-  If `validate.py` aborts with "runtime prerequisites missing" inside Kit mode, the error includes a copy-pasteable hint pointing at the active Kit Python.
-
-See `PROBLEMS.md` P2 for the architectural context behind the env-blocked-issue filter and the Kit-vs-pip split.
-
-## Loader paths
-
-The plugin can populate the OAV registries two ways. The default matches the GitHub-canonical workflow.
-
-**Default — CLI loader (no flag).** `validate.py` calls `simready.validate.impl.loader.load_validation_implementation` against on-disk paths under `$SIMREADY_FOUNDATIONS_PATH` — the same loader the official `simready-validate` CLI uses. Requires only `simready-validate>=2026.4.8` (PyPI) and a foundations checkout from `github.com/NVIDIA/simready-foundation*`. No editable install of `nv_core/sr_specs`, no `repo usd_profiles_codegen` step. The loader generates `omni.capabilities` at runtime via `omni.usd_profiles.codegen`.
-
-**Legacy — `--use-plugin`.** Loads via the `simready.foundation.core:SimReadyPlugin` setuptools entry-point. Requires the editable install of `nv_core/sr_specs` after running `repo usd_profiles_codegen`. Useful only for the GitLab-era workflow on machines that still have that editable install in place; not a recommended path for new setups. When this mode is active, the P1 JSON-variant patch in `validate.py` is also applied (it's redundant under the default loader).
-
-Compose with `--use-kit`: e.g. `python validate.py … --use-kit` runs PhysX checks inside Kit using the default loader path.
-
-See `PROBLEMS.md` P2 for the env-blocked-issue filter that runs alongside both paths.
-
-## Configuration
-
-- `SIMREADY_PYTHON` (recommended): full path to the Python interpreter that has the runtime deps installed. Set automatically by `bootstrap.ps1`. If unset, the skill falls back to `python` on PATH.
-- `SIMREADY_KIT_PYTHON` (optional, used only with `--use-kit`): full path to a Kit-rooted `python.bat`. Default: `C:\isaacsim6\_build\windows-x86_64\release\python.bat`.
-- Default profile: `Robot-Body-Runnable` v1.0.0
-- `SIMREADY_FOUNDATIONS_PATH` (optional): override the foundations checkout location. Default in a clone: `<workspace>/../simready_foundations`. Required when running outside a clone (set automatically by `bootstrap.ps1`).
-- `SIMREADY_SDK_PATH` (optional): override the SDK checkout location. Default in a clone: `<workspace>/../simready-oem-sdk-poc`. Only relevant for auto-packaging (set automatically by `bootstrap.ps1`).
-- `SIMREADY_SPECS_PATH` is set automatically from the resolved foundations path so the validator's spec loader picks it up.
-- `SIMREADY_INSIDE_KIT` is set automatically by `_kit_wrapper.py` to `1` once SimulationApp is booted; `validate.py` uses it to skip the pip-only assumptions and force sequential workers.
-- `OMNI_ASSET_VALIDATOR_ISOLATE_ENTRYPOINTS` is set automatically to `omni.asset_validator:DefaultPlugin,simready.foundation.core:SimReadyPlugin`
+---
+name: simready-report
+description: Validate SimReady customer assets against the foundation specs. Produces a dashboard HTML report and an external-dependencies provenance report. Invoke with /simready-report <name-or-path>.
+---
+
+# /simready-report
+
+Validate a SimReady customer asset set.
+
+## Usage
+
+- `/simready-report` (no arg) — validate the **current working directory**. This is the normal way to run the skill: `cd` into the directory holding the customer asset(s) and invoke.
+- `/simready-report <path>` — validate any directory by absolute or relative path. Override for the no-arg default.
+- `/simready-report <name>` — bare name (no path separators). Tries `<cwd>/<name>` first; if running inside a playbook clone, also tries `<workspace>/assets_to_validate/<name>` for back-compat.
+
+## Install paths
+
+The skill is layout-agnostic — it auto-detects whether it's running inside a playbook clone (`BOT.md` in an ancestor directory) and adjusts defaults accordingly.
+
+**Plugin marketplace install (no clone needed):**
+```
+/plugin marketplace add loginowskid/simready-playbook
+/plugin install simready-report
+```
+Then `/simready-report` works from any directory. Reports default to `<cwd>/report/<target-name>/`. Foundation specs and SDK locations come from env vars (see Configuration).
+
+**Cloned playbook (project skill or local marketplace):**
+If `simready-playbook` is cloned, the skill walks up from its own location to find `BOT.md` and uses workspace-relative defaults: reports under `<workspace>/report/`, optional auto-package into `<workspace>/packages/`, default foundations/sdk lookup at `<workspace>/../simready_foundations` and `<workspace>/../simready-oem-sdk-poc`.
+
+## Runtime dependencies
+
+Wherever the skill is installed, it needs:
+
+- A Python with `usd-core`, `omniverse-asset-validator`, `markdown-it-py`, and `simready-validate>=2026.4.8` importable. Any Python works (system, venv, conda). The default validation path populates the OAV registries via `simready.validate.impl.loader.load_validation_implementation`, matching the official `simready-validate` CLI workflow — no editable install of the foundation specs is required.
+- A `simready_foundations` checkout cloned from `github.com/NVIDIA/simready-foundation` (or the `simready-foundation-staging` mirror). Override default lookup with `SIMREADY_FOUNDATIONS_PATH=<path>`.
+- The `simready-oem-sdk-poc` checkout (only if the user wants the auto-package step for raw asset trees). Override with `SIMREADY_SDK_PATH=<path>`. The `simready` CLI itself is found via `PATH` first, then alongside the active Python.
+
+Legacy fallback: pass `--use-plugin` to load via the `simready.foundation.core:SimReadyPlugin` setuptools entry-point instead (requires the editable install of `nv_core/sr_specs` + the internal `repo usd_profiles_codegen` step). Kept for the GitLab-era workflow; not needed for GitHub-based runs.
+
+For a Windows convenience setup that creates a sibling venv + clones, run `bootstrap.ps1` from a cloned playbook. **Don't run it without confirming with the user first** — they may already have these dependencies elsewhere, or be on a non-Windows system.
+
+Optional: a `usd_validation_dashboard_final/` clone next to the playbook supplies a Sphinx `_static/` theme for rendered doc pages. Without it, doc pages use minimal inline styling — the dashboard still works.
+
+## Steps for Claude when `/simready-report` is invoked
+
+The Python invocation pattern (used in steps 2 and 3 below) — prefer `$env:SIMREADY_PYTHON` (set by `bootstrap.ps1`), fall back to `python` on PATH:
+
+   PowerShell: `$py = if ($env:SIMREADY_PYTHON) { $env:SIMREADY_PYTHON } else { "python" }; & $py …`
+   Bash/zsh:   `"${SIMREADY_PYTHON:-python}" …`
+
+1. **Resolve the target.**
+   - No arg → CWD.
+   - With an arg: pass it through. The script tries it as a path, then `<cwd>/<name>`, then `<workspace>/assets_to_validate/<name>` (clone only) for back-compat.
+2. **Pick the profile (spec selector).** Unless the user already named a specific profile in their request, list the registered profiles and ask them to pick before validating:
+   ```
+   <py> validate.py --list-profiles
+   ```
+   This emits one `PROFILE: <id> v<version>` line per registered profile (typically ~11 across the Robot-Body / Prop-Robotics / Package families). Present them grouped by family with `Robot-Body-Runnable v1.0.0` marked as the default; let the user accept the default or pick another. Pass the chosen `<id>` and `<version>` through as `--profile` and `--version` in step 3.
+3. **Run the validator** from the skill directory:
+   ```
+   <py> validate.py "<arg-or-empty>" --profile <id> --version <version>
+   ```
+   If you skipped the selector because the user named a profile up front, use that. If the user said something like "just use the default", pass `Robot-Body-Runnable` v1.0.0 without prompting.
+4. **Surface results.** Echo the script's `SUMMARY:` line and the absolute path to the report's `index.html`.
+5. **If `validate.py` exits with "runtime prerequisites missing"**, relay the message verbatim. If running inside a clone on Windows, suggest `bootstrap.ps1` (after confirming with the user). Otherwise direct the user to install the deps into their Python and/or set `SIMREADY_FOUNDATIONS_PATH` / `SIMREADY_SDK_PATH` to existing checkouts. Do not run the bootstrap on the user's behalf without explicit confirmation.
+6. **If `validate.py` exits with "target … failed sanity check"**, relay the listed problems verbatim. Don't retry without an explicit user instruction — the check is there to prevent accidental whole-drive scans, output-dir self-validation, and empty-dir runs.
+
+## What `validate.py` does on its own
+
+- **Workspace detection.** Walks up from the skill's directory and treats the first ancestor containing `BOT.md` as the workspace. None of these defaults matter when overridden by env vars / `--output`.
+- **Prerequisite check.** Verifies `omni.asset_validator` / `pxr` / `markdown_it` import in the active Python and that the foundations checkout is findable. On miss: prints actionable error and exits 2.
+- **Sanity check on the resolved target.** Refuses (exit 2) if any of:
+  - Inside a clone: target is the workspace root, or under `<workspace>/.claude/`, `playbooks/`, `report/`, `packages/`, or `plugins/`.
+  - Target is too high in the filesystem (≤2 path components — e.g. `C:\` or `C:\Users\`).
+  - Target has no USD files at root **and** none in any of its immediate subfolders.
+- **Auto-package.** When the resolved target lives under an `assets_to_validate/<name>/` directory, calls `simready ingest usd` per interface USD into a sibling `packages/<name>/` (workspace-anchored when in a clone, else sibling-of-`assets_to_validate/`). Skipped per asset if already packaged. Skipped with a warning if the `simready` CLI isn't on PATH.
+- **Asset thumbnails.** For each validated asset, copies `<asset_dir>/.thumbs/256x256/<filename>.png` (if present at the spec path) into `<out_dir>/images/<filename>.png`. Missing thumbnails render the inline placeholder.
+- **Doc rendering.** For every feature/requirement code referenced by the report, renders the foundation's source markdown to HTML inside `<out_dir>/docs/<rel_path>`. If `usd_validation_dashboard_final/_static/` exists, it's copied once so pages match the reference Sphinx theme; otherwise pages use minimal inline CSS.
+
+## Outputs
+
+Written to the resolved output directory. **Default**: `<target>/.reports/<target-name>.<profile>/` — i.e. dropped inside the asset dir the user pointed at, in a `.reports/` subdir. Examples:
+
+- `/simready-report yaskawa_local` (default profile) → `yaskawa_local/.reports/yaskawa_local.Robot-Body-Runnable/`
+- `/simready-report yaskawa_local` (with `--profile Prop-Robotics-Neutral --version 2.0.0`) → `yaskawa_local/.reports/yaskawa_local.Prop-Robotics-Neutral/`
+
+The `.reports/` prefix starts with `.`, so `discover_assets` automatically skips it on subsequent runs — re-running `/simready-report` from inside the target is safe. Multiple profiles against the same target produce sibling subfolders under `.reports/`, never overwriting each other. Override the whole path with `--output`.
+
+- `index.html` — dashboard: summary cards, asset filter, per-asset failed/passed features, "Other failed requirements" panel, compliance footer.
+- `results.json` — raw issues per asset, plus thumbnail provenance.
+- `images/<filename>.png` — per-asset thumbnails (mirrored from the spec path inside the packaged tree).
+- `docs/` — foundation feature/requirement docs rendered to HTML; `_static/` carries the Sphinx theme assets so pages match the reference dashboard.
+- `external_dependencies_report.html` + `.json` — **only emitted when there's something to report** (one or more externally-resolved layers, or one or more scan-time issues). Anonymous in-memory layers are not counted as external. Three sections when present:
+  1. External assets needed (anything resolved outside the target dir).
+  2. What was done to obtain each (provenance log per layer).
+  3. Issues encountered while building the report.
+
+## Kit-rooted mode (`--use-kit`)
+
+**Auto-default:** `validate.py` auto-enables `--use-kit` whenever the chosen profile is in the PhysX-bearing set (`Robot-Body-Physx`, `Robot-Body-Isaac`, `Robot-Body-Runnable`, `Prop-Robotics-Physx`, `Prop-Robotics-Isaac`). The pip-only path's P2 filter silently drops `physxschema_unavailable` / `omnipbr_unresolved` findings, which makes a "passed" result misleading on those profiles — the checks that matter never actually ran. Pass `--no-use-kit` to opt out (e.g. when you knowingly want the fast filtered run); pass `--use-kit` explicitly to force it on a Neutral-family profile.
+
+Under the hood: when `--use-kit` is on, the script re-execs itself through `_kit_wrapper.py` using a Kit-rooted Python that boots `isaacsim.SimulationApp({"headless": True})` before importing `pxr`, so `PhysxSchema`, the PhysX joint rules, and Kit's stock MDL resolution all work for real. When off (Neutral-family profiles by default, or after `--no-use-kit`), the pip-only venv runs and the P2 filter trims the resulting noise (~900 issues dropped on a typical robot asset) so reports stay readable.
+
+- Resolution order for the Kit Python: `--kit-python <path>` → `$SIMREADY_KIT_PYTHON` → `C:\isaacsim6\_build\windows-x86_64\release\python.bat` (Isaac Sim 6 source build on this team's machines).
+- Cost: ~10–30 s of SimulationApp boot on top of normal validation time. The script automatically forces `--workers 1` in Kit mode so we don't pay the boot again per worker.
+- One-time setup: the Kit-rooted Python needs the same runtime deps the pip venv has. From within the Kit Python:
+  ```
+  <kit-python.bat> -m pip install omniverse-asset-validator markdown-it-py
+  <kit-python.bat> -m pip install -e <foundations>/nv_core/sr_specs
+  <kit-python.bat> -m pip install -e <simready-oem-sdk-poc>    # only if auto-packaging is needed
+  ```
+  If `validate.py` aborts with "runtime prerequisites missing" inside Kit mode, the error includes a copy-pasteable hint pointing at the active Kit Python.
+
+See `PROBLEMS.md` P2 for the architectural context behind the env-blocked-issue filter and the Kit-vs-pip split.
+
+## Loader paths
+
+The plugin can populate the OAV registries two ways. The default matches the GitHub-canonical workflow.
+
+**Default — CLI loader (no flag).** `validate.py` calls `simready.validate.impl.loader.load_validation_implementation` against on-disk paths under `$SIMREADY_FOUNDATIONS_PATH` — the same loader the official `simready-validate` CLI uses. Requires only `simready-validate>=2026.4.8` (PyPI) and a foundations checkout from `github.com/NVIDIA/simready-foundation*`. No editable install of `nv_core/sr_specs`, no `repo usd_profiles_codegen` step. The loader generates `omni.capabilities` at runtime via `omni.usd_profiles.codegen`.
+
+**Legacy — `--use-plugin`.** Loads via the `simready.foundation.core:SimReadyPlugin` setuptools entry-point. Requires the editable install of `nv_core/sr_specs` after running `repo usd_profiles_codegen`. Useful only for the GitLab-era workflow on machines that still have that editable install in place; not a recommended path for new setups. When this mode is active, the P1 JSON-variant patch in `validate.py` is also applied (it's redundant under the default loader).
+
+Compose with `--use-kit`: e.g. `python validate.py … --use-kit` runs PhysX checks inside Kit using the default loader path.
+
+See `PROBLEMS.md` P2 for the env-blocked-issue filter that runs alongside both paths.
+
+## Configuration
+
+- `SIMREADY_PYTHON` (recommended): full path to the Python interpreter that has the runtime deps installed. Set automatically by `bootstrap.ps1`. If unset, the skill falls back to `python` on PATH.
+- `SIMREADY_KIT_PYTHON` (optional, used only with `--use-kit`): full path to a Kit-rooted `python.bat`. Default: `C:\isaacsim6\_build\windows-x86_64\release\python.bat`.
+- Default profile: `Robot-Body-Runnable` v1.0.0
+- `SIMREADY_FOUNDATIONS_PATH` (optional): override the foundations checkout location. Default in a clone: `<workspace>/../simready_foundations`. Required when running outside a clone (set automatically by `bootstrap.ps1`).
+- `SIMREADY_SDK_PATH` (optional): override the SDK checkout location. Default in a clone: `<workspace>/../simready-oem-sdk-poc`. Only relevant for auto-packaging (set automatically by `bootstrap.ps1`).
+- `SIMREADY_SPECS_PATH` is set automatically from the resolved foundations path so the validator's spec loader picks it up.
+- `SIMREADY_INSIDE_KIT` is set automatically by `_kit_wrapper.py` to `1` once SimulationApp is booted; `validate.py` uses it to skip the pip-only assumptions and force sequential workers.
+- `OMNI_ASSET_VALIDATOR_ISOLATE_ENTRYPOINTS` is set automatically to `omni.asset_validator:DefaultPlugin,simready.foundation.core:SimReadyPlugin`

tools/validation/plugins/simready-report/skills/simready-report/_kit_wrapper.py

@@ -1,33 +1,33 @@
-"""Kit-rooted entry point for validate.py.
-
-Boots `isaacsim.SimulationApp({"headless": True})` once in the calling
-process so `pxr.PhysxSchema` and Kit's MDL search path are registered,
-then hands control to `validate.py` via `runpy`. Used by `--use-kit`
-in validate.py — see PROBLEMS.md P2 for why this exists.
-
-This file is intentionally tiny so SimulationApp's boot happens before
-*any* pxr / omni.asset_validator import. Don't add other imports above
-the SimulationApp() call.
-"""
-from __future__ import annotations
-
-import os
-import runpy
-import sys
-from pathlib import Path
-
-from isaacsim import SimulationApp
-
-_sim = SimulationApp({"headless": True})
-os.environ["SIMREADY_INSIDE_KIT"] = "1"
-
-_this_dir = Path(__file__).resolve().parent
-_target = _this_dir / "validate.py"
-sys.argv = [str(_target)] + sys.argv[1:]
-try:
-    runpy.run_path(str(_target), run_name="__main__")
-finally:
-    try:
-        _sim.close()
-    except Exception:
-        pass
+"""Kit-rooted entry point for validate.py.
+
+Boots `isaacsim.SimulationApp({"headless": True})` once in the calling
+process so `pxr.PhysxSchema` and Kit's MDL search path are registered,
+then hands control to `validate.py` via `runpy`. Used by `--use-kit`
+in validate.py — see PROBLEMS.md P2 for why this exists.
+
+This file is intentionally tiny so SimulationApp's boot happens before
+*any* pxr / omni.asset_validator import. Don't add other imports above
+the SimulationApp() call.
+"""
+from __future__ import annotations
+
+import os
+import runpy
+import sys
+from pathlib import Path
+
+from isaacsim import SimulationApp
+
+_sim = SimulationApp({"headless": True})
+os.environ["SIMREADY_INSIDE_KIT"] = "1"
+
+_this_dir = Path(__file__).resolve().parent
+_target = _this_dir / "validate.py"
+sys.argv = [str(_target)] + sys.argv[1:]
+try:
+    runpy.run_path(str(_target), run_name="__main__")
+finally:
+    try:
+        _sim.close()
+    except Exception:
+        pass

tools/validation/plugins/simready-report/skills/simready-report/external_deps.py

@@ -1,259 +1,259 @@
-"""External-dependency tracker for the /simready-report skill.
-
-For each USD stage, walks all used layers (sublayers, references, payloads,
-clips) and classifies each as internal (under target_root) or external.
-Tracks per-layer provenance ("what was done to obtain it") and any issues
-encountered while scanning.
-
-Outputs:
-  external_dependencies_report.json
-  external_dependencies_report.html
-"""
-from __future__ import annotations
-
-import html
-import json
-from dataclasses import dataclass, field, asdict
-from datetime import datetime, timezone
-from pathlib import Path
-
-from pxr import Usd
-
-
-@dataclass
-class ExternalLayerRecord:
-    layer_identifier: str
-    resolved_path: str
-    referenced_by: list[str] = field(default_factory=list)
-    actions: list[str] = field(default_factory=list)
-    status: str = "resolved"  # resolved | missing | error
-
-
-@dataclass
-class IssueRecord:
-    asset: str
-    message: str
-
-
-class ExternalDepsTracker:
-    """Collects external-layer references across all validated stages."""
-
-    def __init__(self, target_root: Path):
-        self.target_root = target_root.resolve()
-        self.external: dict[str, ExternalLayerRecord] = {}
-        self.issues: list[IssueRecord] = []
-
-    # ---- public API ----
-
-    def scan_stage(self, stage: Usd.Stage, asset_path: Path, target_root: Path) -> None:
-        try:
-            used = stage.GetUsedLayers(includeClipLayers=True)
-        except Exception as e:
-            self.record_issue(str(asset_path), f"GetUsedLayers failed: {type(e).__name__}: {e}")
-            return
-
-        root_layer = stage.GetRootLayer()
-        for layer in used:
-            try:
-                if layer is None or layer == root_layer:
-                    continue
-                identifier = layer.identifier
-                # Skip anonymous (in-memory) layers — `anon:0x...` identifiers
-                # are USD-internal handles, not external dependencies.
-                if identifier.startswith("anon:") or (hasattr(layer, "anonymous") and layer.anonymous):
-                    continue
-                resolved = layer.realPath or (layer.resolvedPath.GetPathString() if hasattr(layer, "resolvedPath") else "")
-
-                if self._is_internal(resolved):
-                    continue
-
-                rec = self.external.get(identifier)
-                if rec is None:
-                    rec = ExternalLayerRecord(
-                        layer_identifier=identifier,
-                        resolved_path=resolved or "",
-                    )
-                    if resolved and Path(resolved).exists():
-                        rec.actions.append(f"Resolved by USD asset resolver to: {resolved}")
-                        rec.status = "resolved"
-                    elif not resolved:
-                        rec.actions.append(
-                            f"Could not resolve layer identifier '{identifier}' to a filesystem path."
-                        )
-                        rec.status = "missing"
-                    else:
-                        rec.actions.append(f"Resolved to '{resolved}' but path does not exist on disk.")
-                        rec.status = "missing"
-                    self.external[identifier] = rec
-
-                ref = str(asset_path.relative_to(self.target_root)) if asset_path.is_relative_to(self.target_root) else str(asset_path)
-                if ref not in rec.referenced_by:
-                    rec.referenced_by.append(ref)
-            except Exception as e:
-                self.record_issue(str(asset_path), f"Error scanning layer {layer}: {type(e).__name__}: {e}")
-
-    def record_issue(self, asset: str, message: str) -> None:
-        self.issues.append(IssueRecord(asset=asset, message=message))
-
-    def external_count(self) -> int:
-        return len(self.external)
-
-    def write_reports(self, out_dir: Path) -> None:
-        # Skip emitting the report entirely when there's nothing to say —
-        # no external assets resolved AND no issues encountered.
-        if not self.external and not self.issues:
-            for stale in ("external_dependencies_report.json", "external_dependencies_report.html"):
-                p = out_dir / stale
-                if p.is_file():
-                    p.unlink()
-            return
-        payload = {
-            "generated": datetime.now(timezone.utc).isoformat(),
-            "target_root": str(self.target_root),
-            "external_assets": [asdict(r) for r in self.external.values()],
-            "issues": [asdict(i) for i in self.issues],
-            "summary": {
-                "external_count": len(self.external),
-                "missing_count": sum(1 for r in self.external.values() if r.status == "missing"),
-                "issue_count": len(self.issues),
-            },
-        }
-        (out_dir / "external_dependencies_report.json").write_text(
-            json.dumps(payload, indent=2), encoding="utf-8"
-        )
-        (out_dir / "external_dependencies_report.html").write_text(
-            self._render_html(payload), encoding="utf-8"
-        )
-
-    # ---- internal ----
-
-    def _is_internal(self, resolved_path: str) -> bool:
-        if not resolved_path:
-            return False
-        try:
-            p = Path(resolved_path).resolve()
-        except Exception:
-            return False
-        try:
-            return p.is_relative_to(self.target_root)
-        except AttributeError:
-            try:
-                p.relative_to(self.target_root)
-                return True
-            except ValueError:
-                return False
-
-    def _render_html(self, payload: dict) -> str:
-        s = payload["summary"]
-        rows = []
-        for rec in payload["external_assets"]:
-            actions_html = "".join(f"<li>{html.escape(a)}</li>" for a in rec["actions"]) or "<li>(none)</li>"
-            refs_html = "".join(f"<li><code>{html.escape(r)}</code></li>" for r in rec["referenced_by"]) or "<li>(unknown)</li>"
-            status_class = "status-" + rec["status"]
-            rows.append(f"""
-<tr>
-  <td><code>{html.escape(rec['layer_identifier'])}</code></td>
-  <td><code>{html.escape(rec['resolved_path'] or '')}</code></td>
-  <td><span class="badge {status_class}">{html.escape(rec['status'])}</span></td>
-  <td><ul>{refs_html}</ul></td>
-  <td><ul>{actions_html}</ul></td>
-</tr>""")
-
-        issues_html = "".join(
-            f"<tr><td><code>{html.escape(i['asset'])}</code></td><td>{html.escape(i['message'])}</td></tr>"
-            for i in payload["issues"]
-        )
-        if not issues_html:
-            issues_html = '<tr><td colspan="2" class="muted">No issues recorded.</td></tr>'
-
-        return f"""<!doctype html>
-<html lang="en"><head><meta charset="utf-8" />
-<title>External Dependencies Report</title>
-<script>(function(){{var t=null;try{{t=localStorage.getItem('vr-theme');}}catch(e){{}}if(t==='dark'||t==='light')document.documentElement.setAttribute('data-theme',t);}})();</script>
-<style>
-  :root {{ --bg:#f4f6fb; --panel:#fff; --text:#1f2a44; --muted:#7280a7; --border:#e6ebf5; --resolved:#0a0; --missing:#c00; --error:#b35900; }}
-  @media (prefers-color-scheme: dark) {{
-    :root:not([data-theme="light"]) {{ --bg:#0f1320; --panel:#1a2030; --text:#e6ebf5; --muted:#8a93b3; --border:#2a3142; --resolved:#4ade80; --missing:#ff6b6b; --error:#fbbf24; }}
-  }}
-  :root[data-theme="dark"] {{ --bg:#0f1320; --panel:#1a2030; --text:#e6ebf5; --muted:#8a93b3; --border:#2a3142; --resolved:#4ade80; --missing:#ff6b6b; --error:#fbbf24; }}
-  * {{ box-sizing: border-box; }}
-  body {{ font-family: "Segoe UI", Arial, sans-serif; margin:0; padding:16px; background:var(--bg); color:var(--text); }}
-  header {{ background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:12px 16px; margin-bottom:16px; display:flex; align-items:center; gap:12px; }}
-  header .header-text {{ flex:1; }}
-  header h1 {{ margin:0; font-size:18px; }}
-  header .meta {{ color:var(--muted); font-size:12px; margin-top:4px; }}
-  .theme-toggle {{ padding:6px 12px; background:transparent; border:1px solid var(--border); border-radius:8px; color:var(--text); cursor:pointer; font-size:13px; }}
-  .theme-toggle:hover {{ background:var(--bg); }}
-  .summary {{ display:grid; grid-template-columns:repeat(3,1fr); gap:12px; margin-bottom:20px; }}
-  .summary .card {{ background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:14px; }}
-  .summary .label {{ color:var(--muted); font-size:12px; }}
-  .summary .value {{ font-size:20px; font-weight:700; }}
-  section {{ background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:14px; margin-bottom:14px; }}
-  section h2 {{ margin:0 0 10px 0; font-size:15px; }}
-  table {{ width:100%; border-collapse:collapse; font-size:13px; }}
-  th, td {{ text-align:left; vertical-align:top; padding:8px 10px; border-bottom:1px solid var(--border); }}
-  th {{ color:var(--muted); font-weight:600; font-size:12px; text-transform:uppercase; letter-spacing:0.04em; }}
-  ul {{ margin:0; padding-left:18px; }}
-  code {{ font-family: ui-monospace, monospace; font-size:12px; word-break:break-all; }}
-  .badge {{ display:inline-block; padding:2px 8px; border-radius:999px; font-size:11px; font-weight:700; color:#fff; }}
-  .status-resolved {{ background:var(--resolved); }}
-  .status-missing  {{ background:var(--missing); }}
-  .status-error    {{ background:var(--error); }}
-  .muted {{ color:var(--muted); }}
-</style></head>
-<body>
-<header>
-  <div class="header-text">
-    <h1>External Dependencies Report</h1>
-    <div class="meta">Target: <code>{html.escape(payload['target_root'])}</code> &middot; Generated: {html.escape(payload['generated'])}</div>
-  </div>
-  <button type="button" id="themeToggle" class="theme-toggle" aria-label="Toggle theme">Dark mode</button>
-</header>
-<div class="summary">
-  <div class="card"><div class="label">External assets</div><div class="value">{s['external_count']}</div></div>
-  <div class="card"><div class="label">Missing</div><div class="value">{s['missing_count']}</div></div>
-  <div class="card"><div class="label">Issues</div><div class="value">{s['issue_count']}</div></div>
-</div>
-
-<section>
-  <h2>External assets &mdash; what was needed and how it was obtained</h2>
-  <table>
-    <thead><tr><th>Layer identifier</th><th>Resolved path</th><th>Status</th><th>Referenced by</th><th>Actions taken</th></tr></thead>
-    <tbody>{''.join(rows) or '<tr><td colspan="5" class="muted">No external assets referenced.</td></tr>'}</tbody>
-  </table>
-</section>
-
-<section>
-  <h2>Issues encountered while building this report</h2>
-  <table>
-    <thead><tr><th>Asset</th><th>Message</th></tr></thead>
-    <tbody>{issues_html}</tbody>
-  </table>
-</section>
-<script>
-(function() {{
-  var btn = document.getElementById("themeToggle");
-  var mq = window.matchMedia ? window.matchMedia("(prefers-color-scheme: dark)") : null;
-  function isDark() {{
-    var attr = document.documentElement.getAttribute("data-theme");
-    if (attr === "dark") return true;
-    if (attr === "light") return false;
-    return mq ? mq.matches : false;
-  }}
-  function syncLabel() {{
-    if (btn) btn.textContent = isDark() ? "Light mode" : "Dark mode";
-  }}
-  syncLabel();
-  if (mq && mq.addEventListener) mq.addEventListener("change", syncLabel);
-  if (btn) {{
-    btn.addEventListener("click", function() {{
-      var next = isDark() ? "light" : "dark";
-      document.documentElement.setAttribute("data-theme", next);
-      try {{ localStorage.setItem("vr-theme", next); }} catch(e) {{}}
-      syncLabel();
-    }});
-  }}
-}})();
-</script>
-</body></html>
-"""
+"""External-dependency tracker for the /simready-report skill.
+
+For each USD stage, walks all used layers (sublayers, references, payloads,
+clips) and classifies each as internal (under target_root) or external.
+Tracks per-layer provenance ("what was done to obtain it") and any issues
+encountered while scanning.
+
+Outputs:
+  external_dependencies_report.json
+  external_dependencies_report.html
+"""
+from __future__ import annotations
+
+import html
+import json
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from pxr import Usd
+
+
+@dataclass
+class ExternalLayerRecord:
+    layer_identifier: str
+    resolved_path: str
+    referenced_by: list[str] = field(default_factory=list)
+    actions: list[str] = field(default_factory=list)
+    status: str = "resolved"  # resolved | missing | error
+
+
+@dataclass
+class IssueRecord:
+    asset: str
+    message: str
+
+
+class ExternalDepsTracker:
+    """Collects external-layer references across all validated stages."""
+
+    def __init__(self, target_root: Path):
+        self.target_root = target_root.resolve()
+        self.external: dict[str, ExternalLayerRecord] = {}
+        self.issues: list[IssueRecord] = []
+
+    # ---- public API ----
+
+    def scan_stage(self, stage: Usd.Stage, asset_path: Path, target_root: Path) -> None:
+        try:
+            used = stage.GetUsedLayers(includeClipLayers=True)
+        except Exception as e:
+            self.record_issue(str(asset_path), f"GetUsedLayers failed: {type(e).__name__}: {e}")
+            return
+
+        root_layer = stage.GetRootLayer()
+        for layer in used:
+            try:
+                if layer is None or layer == root_layer:
+                    continue
+                identifier = layer.identifier
+                # Skip anonymous (in-memory) layers — `anon:0x...` identifiers
+                # are USD-internal handles, not external dependencies.
+                if identifier.startswith("anon:") or (hasattr(layer, "anonymous") and layer.anonymous):
+                    continue
+                resolved = layer.realPath or (layer.resolvedPath.GetPathString() if hasattr(layer, "resolvedPath") else "")
+
+                if self._is_internal(resolved):
+                    continue
+
+                rec = self.external.get(identifier)
+                if rec is None:
+                    rec = ExternalLayerRecord(
+                        layer_identifier=identifier,
+                        resolved_path=resolved or "",
+                    )
+                    if resolved and Path(resolved).exists():
+                        rec.actions.append(f"Resolved by USD asset resolver to: {resolved}")
+                        rec.status = "resolved"
+                    elif not resolved:
+                        rec.actions.append(
+                            f"Could not resolve layer identifier '{identifier}' to a filesystem path."
+                        )
+                        rec.status = "missing"
+                    else:
+                        rec.actions.append(f"Resolved to '{resolved}' but path does not exist on disk.")
+                        rec.status = "missing"
+                    self.external[identifier] = rec
+
+                ref = str(asset_path.relative_to(self.target_root)) if asset_path.is_relative_to(self.target_root) else str(asset_path)
+                if ref not in rec.referenced_by:
+                    rec.referenced_by.append(ref)
+            except Exception as e:
+                self.record_issue(str(asset_path), f"Error scanning layer {layer}: {type(e).__name__}: {e}")
+
+    def record_issue(self, asset: str, message: str) -> None:
+        self.issues.append(IssueRecord(asset=asset, message=message))
+
+    def external_count(self) -> int:
+        return len(self.external)
+
+    def write_reports(self, out_dir: Path) -> None:
+        # Skip emitting the report entirely when there's nothing to say —
+        # no external assets resolved AND no issues encountered.
+        if not self.external and not self.issues:
+            for stale in ("external_dependencies_report.json", "external_dependencies_report.html"):
+                p = out_dir / stale
+                if p.is_file():
+                    p.unlink()
+            return
+        payload = {
+            "generated": datetime.now(timezone.utc).isoformat(),
+            "target_root": str(self.target_root),
+            "external_assets": [asdict(r) for r in self.external.values()],
+            "issues": [asdict(i) for i in self.issues],
+            "summary": {
+                "external_count": len(self.external),
+                "missing_count": sum(1 for r in self.external.values() if r.status == "missing"),
+                "issue_count": len(self.issues),
+            },
+        }
+        (out_dir / "external_dependencies_report.json").write_text(
+            json.dumps(payload, indent=2), encoding="utf-8"
+        )
+        (out_dir / "external_dependencies_report.html").write_text(
+            self._render_html(payload), encoding="utf-8"
+        )
+
+    # ---- internal ----
+
+    def _is_internal(self, resolved_path: str) -> bool:
+        if not resolved_path:
+            return False
+        try:
+            p = Path(resolved_path).resolve()
+        except Exception:
+            return False
+        try:
+            return p.is_relative_to(self.target_root)
+        except AttributeError:
+            try:
+                p.relative_to(self.target_root)
+                return True
+            except ValueError:
+                return False
+
+    def _render_html(self, payload: dict) -> str:
+        s = payload["summary"]
+        rows = []
+        for rec in payload["external_assets"]:
+            actions_html = "".join(f"<li>{html.escape(a)}</li>" for a in rec["actions"]) or "<li>(none)</li>"
+            refs_html = "".join(f"<li><code>{html.escape(r)}</code></li>" for r in rec["referenced_by"]) or "<li>(unknown)</li>"
+            status_class = "status-" + rec["status"]
+            rows.append(f"""
+<tr>
+  <td><code>{html.escape(rec['layer_identifier'])}</code></td>
+  <td><code>{html.escape(rec['resolved_path'] or '')}</code></td>
+  <td><span class="badge {status_class}">{html.escape(rec['status'])}</span></td>
+  <td><ul>{refs_html}</ul></td>
+  <td><ul>{actions_html}</ul></td>
+</tr>""")
+
+        issues_html = "".join(
+            f"<tr><td><code>{html.escape(i['asset'])}</code></td><td>{html.escape(i['message'])}</td></tr>"
+            for i in payload["issues"]
+        )
+        if not issues_html:
+            issues_html = '<tr><td colspan="2" class="muted">No issues recorded.</td></tr>'
+
+        return f"""<!doctype html>
+<html lang="en"><head><meta charset="utf-8" />
+<title>External Dependencies Report</title>
+<script>(function(){{var t=null;try{{t=localStorage.getItem('vr-theme');}}catch(e){{}}if(t==='dark'||t==='light')document.documentElement.setAttribute('data-theme',t);}})();</script>
+<style>
+  :root {{ --bg:#f4f6fb; --panel:#fff; --text:#1f2a44; --muted:#7280a7; --border:#e6ebf5; --resolved:#0a0; --missing:#c00; --error:#b35900; }}
+  @media (prefers-color-scheme: dark) {{
+    :root:not([data-theme="light"]) {{ --bg:#0f1320; --panel:#1a2030; --text:#e6ebf5; --muted:#8a93b3; --border:#2a3142; --resolved:#4ade80; --missing:#ff6b6b; --error:#fbbf24; }}
+  }}
+  :root[data-theme="dark"] {{ --bg:#0f1320; --panel:#1a2030; --text:#e6ebf5; --muted:#8a93b3; --border:#2a3142; --resolved:#4ade80; --missing:#ff6b6b; --error:#fbbf24; }}
+  * {{ box-sizing: border-box; }}
+  body {{ font-family: "Segoe UI", Arial, sans-serif; margin:0; padding:16px; background:var(--bg); color:var(--text); }}
+  header {{ background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:12px 16px; margin-bottom:16px; display:flex; align-items:center; gap:12px; }}
+  header .header-text {{ flex:1; }}
+  header h1 {{ margin:0; font-size:18px; }}
+  header .meta {{ color:var(--muted); font-size:12px; margin-top:4px; }}
+  .theme-toggle {{ padding:6px 12px; background:transparent; border:1px solid var(--border); border-radius:8px; color:var(--text); cursor:pointer; font-size:13px; }}
+  .theme-toggle:hover {{ background:var(--bg); }}
+  .summary {{ display:grid; grid-template-columns:repeat(3,1fr); gap:12px; margin-bottom:20px; }}
+  .summary .card {{ background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:14px; }}
+  .summary .label {{ color:var(--muted); font-size:12px; }}
+  .summary .value {{ font-size:20px; font-weight:700; }}
+  section {{ background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:14px; margin-bottom:14px; }}
+  section h2 {{ margin:0 0 10px 0; font-size:15px; }}
+  table {{ width:100%; border-collapse:collapse; font-size:13px; }}
+  th, td {{ text-align:left; vertical-align:top; padding:8px 10px; border-bottom:1px solid var(--border); }}
+  th {{ color:var(--muted); font-weight:600; font-size:12px; text-transform:uppercase; letter-spacing:0.04em; }}
+  ul {{ margin:0; padding-left:18px; }}
+  code {{ font-family: ui-monospace, monospace; font-size:12px; word-break:break-all; }}
+  .badge {{ display:inline-block; padding:2px 8px; border-radius:999px; font-size:11px; font-weight:700; color:#fff; }}
+  .status-resolved {{ background:var(--resolved); }}
+  .status-missing  {{ background:var(--missing); }}
+  .status-error    {{ background:var(--error); }}
+  .muted {{ color:var(--muted); }}
+</style></head>
+<body>
+<header>
+  <div class="header-text">
+    <h1>External Dependencies Report</h1>
+    <div class="meta">Target: <code>{html.escape(payload['target_root'])}</code> &middot; Generated: {html.escape(payload['generated'])}</div>
+  </div>
+  <button type="button" id="themeToggle" class="theme-toggle" aria-label="Toggle theme">Dark mode</button>
+</header>
+<div class="summary">
+  <div class="card"><div class="label">External assets</div><div class="value">{s['external_count']}</div></div>
+  <div class="card"><div class="label">Missing</div><div class="value">{s['missing_count']}</div></div>
+  <div class="card"><div class="label">Issues</div><div class="value">{s['issue_count']}</div></div>
+</div>
+
+<section>
+  <h2>External assets &mdash; what was needed and how it was obtained</h2>
+  <table>
+    <thead><tr><th>Layer identifier</th><th>Resolved path</th><th>Status</th><th>Referenced by</th><th>Actions taken</th></tr></thead>
+    <tbody>{''.join(rows) or '<tr><td colspan="5" class="muted">No external assets referenced.</td></tr>'}</tbody>
+  </table>
+</section>
+
+<section>
+  <h2>Issues encountered while building this report</h2>
+  <table>
+    <thead><tr><th>Asset</th><th>Message</th></tr></thead>
+    <tbody>{issues_html}</tbody>
+  </table>
+</section>
+<script>
+(function() {{
+  var btn = document.getElementById("themeToggle");
+  var mq = window.matchMedia ? window.matchMedia("(prefers-color-scheme: dark)") : null;
+  function isDark() {{
+    var attr = document.documentElement.getAttribute("data-theme");
+    if (attr === "dark") return true;
+    if (attr === "light") return false;
+    return mq ? mq.matches : false;
+  }}
+  function syncLabel() {{
+    if (btn) btn.textContent = isDark() ? "Light mode" : "Dark mode";
+  }}
+  syncLabel();
+  if (mq && mq.addEventListener) mq.addEventListener("change", syncLabel);
+  if (btn) {{
+    btn.addEventListener("click", function() {{
+      var next = isDark() ? "light" : "dark";
+      document.documentElement.setAttribute("data-theme", next);
+      try {{ localStorage.setItem("vr-theme", next); }} catch(e) {{}}
+      syncLabel();
+    }});
+  }}
+}})();
+</script>
+</body></html>
+"""

tools/validation/plugins/simready-report/skills/simready-report/report.py

@@ -1,860 +1,860 @@
-"""Dashboard HTML generator for the /simready-report skill.
-
-Given the per-asset results produced by validate.py, emits index.html in the
-style of usd_validation_dashboard_final/: summary cards, asset filter,
-per-asset blocks (failed/passed features, affected prims), compliance footer.
-
-Thumbnails are embedded inline (base64 data URI) from the spec path
-<asset_dir>/.thumbs/256x256/<filename>.png — matching the ThumbnailExists rule.
-"""
-from __future__ import annotations
-
-import html
-from datetime import datetime, timezone
-from pathlib import Path
-
-
-def _ensure_static_copied(out_docs_dir: Path, dashboard_docs_dir: Path | None) -> bool:
-    """Mirror the reference dashboard's `_static/` into `<out_docs_dir>/_static/` once.
-
-    Returns True if the static tree is available (so pages can link to it),
-    False if the dashboard isn't present or the copy failed.
-    """
-    if dashboard_docs_dir is None:
-        return False
-    src = dashboard_docs_dir / "_static"
-    if not src.is_dir():
-        return False
-    dest = out_docs_dir / "_static"
-    if dest.exists():
-        return True
-    import shutil
-    try:
-        shutil.copytree(src, dest)
-        return True
-    except Exception:
-        return False
-
-
-def _render_md_page(title: str, rel_path: str, source_path: Path, body_html: str,
-                    has_static: bool) -> str:
-    """Render a markdown page using the reference dashboard's Sphinx assets.
-
-    `rel_path` is the doc's path relative to `out_docs_dir` (e.g.
-    `features/FET_001-minimal.html`); we compute how many `../` are needed to
-    reach `_static/` based on its depth.
-    """
-    depth = rel_path.replace("\\", "/").count("/")
-    static_prefix = "../" * depth + "_static/"
-    if has_static:
-        head_links = f"""
-  <link rel="stylesheet" href="{static_prefix}styles/theme.css" />
-  <link rel="stylesheet" href="{static_prefix}styles/bootstrap.css" />
-  <link rel="stylesheet" href="{static_prefix}styles/pydata-sphinx-theme.css" />
-  <link rel="stylesheet" href="{static_prefix}styles/nvidia-sphinx-theme.css" />
-  <link rel="stylesheet" href="{static_prefix}pygments.css" />
-  <link rel="stylesheet" href="{static_prefix}_style.css" />
-  <link rel="stylesheet" href="{static_prefix}custom.css" />
-  <link rel="stylesheet" href="{static_prefix}sphinx-design.min.css" />
-  <link rel="stylesheet" href="{static_prefix}vendor/fontawesome/6.5.2/css/all.min.css" />
-"""
-        body_open = '<main class="bd-main"><div class="bd-content"><div class="bd-article-container"><article class="bd-article">'
-        body_close = '</article></div></div></main>'
-    else:
-        head_links = ""
-        body_open = '<article style="max-width:880px;margin:24px auto;padding:24px 28px;font-family:Segoe UI,Arial,sans-serif;line-height:1.55;">'
-        body_close = '</article>'
-
-    # `source_path` is an absolute machine-specific path inside the foundations
-    # checkout — don't render it. Show the source's path relative to the
-    # foundation docs root (i.e. `rel_path` minus the .html for the .md form),
-    # which is portable across machines that share the same foundations layout.
-    source_md_rel = (rel_path[:-5] + ".md") if rel_path.endswith(".html") else rel_path
-    return f"""<!DOCTYPE html>
-<html lang="en" data-content_root="{'../' * depth}">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>{html.escape(title)}</title>
-  <script>document.documentElement.dataset.mode = localStorage.getItem("mode") || "";document.documentElement.dataset.theme = localStorage.getItem("theme") || "";</script>{head_links}
-</head>
-<body data-bs-spy="scroll">
-{body_open}
-<p class="text-muted" style="font-size:12px;margin-bottom:14px;">Source: <code>nv_core/sr_specs/docs/{html.escape(source_md_rel)}</code></p>
-{body_html}
-{body_close}
-</body>
-</html>
-"""
-
-
-_NO_SPEC_TAG = ' <span class="no-spec">(no spec source)</span>'
-
-
-def _relativize_msg(msg: str, target: Path | None) -> str:
-    """Strip machine-specific absolute path prefixes from validator messages.
-
-    `omni.asset_validator` rule messages embed the absolute path of each USD
-    being inspected. We replace the target's path prefix (and the path up to
-    `packages/` / `assets_to_validate/`) with relative tokens so reports
-    don't leak the report-author's user dir.
-    """
-    if not msg or target is None:
-        return msg
-    out = msg
-    target_fwd = str(target).replace("\\", "/")
-    target_bwd = str(target).replace("/", "\\")
-    for prefix in (target_fwd, target_bwd):
-        if prefix and prefix in out:
-            out = out.replace(prefix, "<target>")
-    # Catch absolute paths that point at the workspace's packages/ or
-    # assets_to_validate/ — same machine-specificity, different anchor.
-    for marker in ("/packages/", "\\packages\\", "/assets_to_validate/", "\\assets_to_validate\\"):
-        idx = out.find(marker)
-        while idx != -1:
-            # Find the start of the absolute path containing this marker
-            # (a drive letter "X:\" or POSIX "/" boundary going left).
-            start = idx
-            while start > 0 and out[start - 1] not in (" ", "<", "(", "[", '"', "'", "\n", "\t"):
-                start -= 1
-            # Replace from `start` through the marker with the marker's tail.
-            anchor = marker.strip("/\\").replace("\\", "/")  # "packages" / "assets_to_validate"
-            tail_pos = idx + len(marker)
-            out = out[:start] + f"<{anchor}>/" + out[tail_pos:]
-            idx = out.find(marker, start + len(anchor) + 3)
-    return out
-
-_md_renderer = None
-
-
-def _md_to_html(md_text: str) -> str:
-    global _md_renderer
-    if _md_renderer is None:
-        from markdown_it import MarkdownIt
-        # html:True passes raw HTML through unescaped — safe only because the
-        # markdown comes from the trusted foundations repo, not user input.
-        _md_renderer = MarkdownIt("commonmark", {"html": True, "linkify": True, "typographer": True}).enable("table")
-    return _md_renderer.render(md_text)
-
-
-_IMG_PLACEHOLDER_SVG = (
-    "data:image/svg+xml;utf8,"
-    "<svg xmlns='http://www.w3.org/2000/svg' width='320' height='180' viewBox='0 0 320 180'>"
-    "<rect width='320' height='180' fill='%23f0f2f8' stroke='%23c7cee0' stroke-dasharray='6 4' stroke-width='2'/>"
-    "<text x='50%25' y='50%25' dominant-baseline='middle' text-anchor='middle' "
-    "font-family='Segoe UI,Arial,sans-serif' font-size='14' fill='%237280a7'>image missing</text>"
-    "</svg>"
-)
-
-
-def _localize_images(body_html: str, md_source: Path, out_html_path: Path) -> str:
-    """Walk every `<img src="...">` in `body_html`. If src is a relative path,
-    copy the source file (relative to `md_source.parent`) into the equivalent
-    location next to `out_html_path`. When the source file is missing, replace
-    the src with an inline SVG placeholder so the page never 404s.
-    """
-    import re
-    import shutil
-
-    md_dir = md_source.parent
-    out_dir = out_html_path.parent
-
-    def repl(match):
-        full_tag = match.group(0)
-        src_match = re.search(r'src="([^"]+)"', full_tag)
-        if not src_match:
-            return full_tag
-        src = src_match.group(1)
-        if src.startswith(("http://", "https://", "data:", "//", "/")):
-            return full_tag  # absolute / data URI / protocol-relative — leave alone
-        rel = src.lstrip("./").replace("\\", "/")
-        source_file = (md_dir / src).resolve()
-        # Containment guard on the SOURCE: a crafted ../ src must not read
-        # files outside the markdown tree. Escape -> skip to placeholder.
-        try:
-            source_file.relative_to(md_dir.resolve())
-        except ValueError:
-            import sys
-            print(f"[report] skipping out-of-tree image src: {src!r}", file=sys.stderr)
-            return re.sub(r'src="[^"]+"', f'src="{_IMG_PLACEHOLDER_SVG}"', full_tag)
-        if source_file.is_file():
-            dest_file = (out_dir / rel).resolve()
-            try:
-                dest_file.relative_to(out_dir.resolve())  # guard against ../ escape
-                dest_file.parent.mkdir(parents=True, exist_ok=True)
-                if not dest_file.exists() or dest_file.stat().st_size != source_file.stat().st_size:
-                    shutil.copy2(source_file, dest_file)
-                return full_tag
-            except (ValueError, OSError):
-                pass
-        # Missing source — swap to placeholder
-        return re.sub(r'src="[^"]+"', f'src="{_IMG_PLACEHOLDER_SVG}"', full_tag)
-
-    return re.sub(r"<img\b[^>]*>", repl, body_html)
-
-
-_A_TAG_RE = None
-
-
-def _localize_links(body_html: str, md_source: Path, out_html_path: Path,
-                    specs_docs_dir: Path, out_docs_root: Path,
-                    resolver) -> str:
-    """Rewrite relative <a href="..."> targets so the docs tree is self-contained.
-
-    - .md targets that resolve to a file inside `specs_docs_dir`: rewrite href
-      to .html and recursively render via `resolver(<rel>.html)`.
-    - non-.md targets inside `specs_docs_dir`: copy verbatim into the mirrored
-      location under `out_docs_root` and rewrite href to that copy.
-    - root-relative ("/...") hrefs treated as relative to `specs_docs_dir`;
-      bare paths without an extension are tried as `.md`.
-    - links pointing outside `specs_docs_dir` or at non-existent targets are
-      replaced with <span class="docref-disabled" title="...">TEXT</span> so
-      the visible text remains but no href can 404.
-    """
-    import os
-    import re
-    import shutil
-
-    global _A_TAG_RE
-    if _A_TAG_RE is None:
-        _A_TAG_RE = re.compile(r'<a\s+([^>]*?)>(.*?)</a>', re.DOTALL | re.IGNORECASE)
-
-    md_dir = md_source.parent
-    out_dir = out_html_path.parent
-    specs_root = specs_docs_dir.resolve()
-    out_docs_resolved = out_docs_root.resolve()
-
-    def _disable(inner: str, why: str = "link target not available in report") -> str:
-        return f'<span class="docref-disabled" title="{html.escape(why)}">{inner}</span>'
-
-    def _resolve_target(href_path: str) -> Path | None:
-        if href_path.startswith("/"):
-            base = specs_root / href_path.lstrip("/")
-            if not base.suffix:
-                base = base.with_suffix(".md")
-            return base
-        return (md_dir / href_path)
-
-    def repl(m: "re.Match[str]") -> str:
-        attrs = m.group(1)
-        inner = m.group(2)
-        href_m = re.search(r'href\s*=\s*"([^"]*)"', attrs)
-        if not href_m:
-            return m.group(0)
-        href = href_m.group(1).strip()
-        if not href:
-            return m.group(0)
-        if href.startswith(("http://", "https://", "data:", "mailto:", "//", "#", "javascript:")):
-            return m.group(0)
-
-        if "#" in href:
-            path_part, frag = href.split("#", 1)
-            frag = "#" + frag
-        else:
-            path_part, frag = href, ""
-        if not path_part:
-            return m.group(0)
-
-        target = _resolve_target(path_part)
-        if target is None:
-            return _disable(inner)
-        try:
-            target = target.resolve()
-        except OSError:
-            return _disable(inner)
-        try:
-            rel_to_specs = target.relative_to(specs_root)
-        except ValueError:
-            return _disable(inner, "link target outside foundation docs")
-        if not target.exists():
-            return _disable(inner, "link target missing in foundation docs")
-
-        rel_str = str(rel_to_specs).replace("\\", "/")
-
-        if target.suffix.lower() == ".md":
-            html_rel = rel_str[:-3] + ".html"
-            url = resolver(html_rel)
-            if url is None:
-                return _disable(inner)
-            target_out = out_docs_resolved / html_rel
-        else:
-            target_out = out_docs_resolved / rel_str
-            try:
-                target_out.parent.mkdir(parents=True, exist_ok=True)
-                if not target_out.exists() or target_out.stat().st_size != target.stat().st_size:
-                    shutil.copy2(target, target_out)
-            except OSError:
-                return _disable(inner, "could not copy link target into report")
-
-        try:
-            new_href = os.path.relpath(target_out, out_dir).replace("\\", "/") + frag
-        except ValueError:
-            return _disable(inner)
-        new_attrs = re.sub(r'href\s*=\s*"[^"]*"', f'href="{new_href}"', attrs, count=1)
-        return f'<a {new_attrs}>{inner}</a>'
-
-    return _A_TAG_RE.sub(repl, body_html)
-
-
-def _make_doc_url_resolver(out_dir: Path, dashboard_docs_dir: Path | None,
-                           specs_docs_dir: Path | None):
-    """Build a `_doc_url(rel_path)` callable.
-
-    Every resolvable doc is rendered from the foundation markdown source into
-    `<out_dir>/docs/<rel_path>` so the dashboard has a single, self-contained
-    docs tree. The reference-dashboard pre-built HTML is no longer used as a
-    link target — it would split the source of truth.
-
-    `dashboard_docs_dir` is kept on the signature for API stability but not
-    consulted here.
-    """
-    rendered_cache: dict[str, str] = {}
-    out_docs_dir = out_dir / "docs"
-    out_docs_dir.mkdir(parents=True, exist_ok=True)
-    has_static = _ensure_static_copied(out_docs_dir, dashboard_docs_dir)
-
-    def resolve(rel_path: str | None) -> str | None:
-        if not rel_path or specs_docs_dir is None:
-            return None
-        if rel_path in rendered_cache:
-            return rendered_cache[rel_path]
-        md_rel = rel_path[:-5] + ".md" if rel_path.endswith(".html") else rel_path
-        md_source = specs_docs_dir / md_rel
-        if not md_source.is_file():
-            return None
-        # Cache the URL before rendering body so cycles in the foundation's
-        # cross-doc links (e.g. profile -> feature -> profile) terminate.
-        url = "docs/" + rel_path.replace("\\", "/")
-        rendered_cache[rel_path] = url
-        out_path = out_docs_dir / rel_path
-        out_path.parent.mkdir(parents=True, exist_ok=True)
-        body = _md_to_html(md_source.read_text(encoding="utf-8"))
-        body = _localize_images(body, md_source, out_path)
-        body = _localize_links(body, md_source, out_path, specs_docs_dir, out_docs_dir, resolve)
-        out_path.write_text(
-            _render_md_page(rel_path, rel_path, md_source, body, has_static),
-            encoding="utf-8",
-        )
-        return url
-
-    return resolve
-
-
-CSS = """
-:root { --bg:#f4f6fb; --panel:#fff; --text:#1f2a44; --muted:#7280a7; --border:#e6ebf5; --fail:#c00; --pass:#0a0; --link:#2b6de2; --note-bg:#fff8e6; --note-border:#f1d38a; --note-text:#6b4f00; --note-code:#fff3cc; --thumb-bg:#f4f6fb; }
-@media (prefers-color-scheme: dark) {
-  :root:not([data-theme="light"]) { --bg:#0f1320; --panel:#1a2030; --text:#e6ebf5; --muted:#8a93b3; --border:#2a3142; --fail:#ff6b6b; --pass:#4ade80; --link:#7ba9ff; --note-bg:#2a2410; --note-border:#5a4a1f; --note-text:#f1d38a; --note-code:#3a3018; --thumb-bg:#0f1320; }
-}
-:root[data-theme="dark"] { --bg:#0f1320; --panel:#1a2030; --text:#e6ebf5; --muted:#8a93b3; --border:#2a3142; --fail:#ff6b6b; --pass:#4ade80; --link:#7ba9ff; --note-bg:#2a2410; --note-border:#5a4a1f; --note-text:#f1d38a; --note-code:#3a3018; --thumb-bg:#0f1320; }
-* { box-sizing: border-box; }
-body { font-family: "Segoe UI", Arial, sans-serif; margin:0; background:var(--bg); color:var(--text); padding:16px; }
-header { display:flex; align-items:center; gap:10px; margin-bottom:16px; padding:12px 16px; background:var(--panel); border-radius:12px; border:1px solid var(--border); }
-header .logo { width:36px; height:36px; border-radius:10px; background:#2b6de2; color:#fff; display:grid; place-items:center; font-weight:700; }
-header h1 { margin:0; font-size:18px; }
-header .meta { color:var(--muted); font-size:12px; }
-.summary { display:grid; grid-template-columns:repeat(3,1fr); gap:12px; margin-bottom:20px; }
-.summary .card { background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:14px; }
-.summary .card .label { color:var(--muted); font-size:12px; }
-.summary .card .value { font-size:20px; font-weight:700; }
-.asset-block { background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:14px; margin-bottom:14px; display:flex; gap:14px; align-items:flex-start; }
-.asset-block .asset-thumb-wrap { flex-shrink:0; width:140px; }
-.asset-block .asset-thumb { width:100%; height:auto; aspect-ratio:1; object-fit:cover; border-radius:8px; background:var(--border); display:block; }
-.asset-block .asset-thumb-missing { background:var(--thumb-bg); border:1px dashed var(--border); display:grid; place-items:center; color:var(--muted); font-size:11px; text-align:center; padding:8px; }
-.asset-block .asset-thumb-missing span { line-height:1.3; }
-.code { font-family: ui-monospace, monospace; font-size:12px; padding:1px 6px; border-radius:4px; background:var(--note-code); color:var(--note-text); margin-right:4px; }
-.feat-id { font-family: ui-monospace, monospace; font-size:13px; }
-a.docref { color:var(--link); text-decoration:underline; text-decoration-style:dotted; text-underline-offset:2px; font-size:12px; }
-a.docref:hover { text-decoration-style:solid; }
-a.code { text-decoration:underline; text-decoration-style:dotted; text-underline-offset:2px; }
-a.code:hover { text-decoration-style:solid; }
-.failed-features .feat-id { color:var(--fail); }
-.passed-features .feat-id { color:var(--pass); }
-.asset-block .asset-body { flex:1; min-width:0; }
-.asset-block h2 { margin:0 0 6px 0; font-size:15px; }
-.asset-block .path { font-size:12px; color:var(--muted); margin-bottom:10px; word-break:break-all; }
-.asset-block section { margin-top:10px; }
-.asset-block section h3 { margin:0 0 6px 0; font-size:13px; color:var(--muted); }
-.asset-block ul { margin:0; padding-left:20px; }
-.asset-block li { margin:4px 0; }
-.failed-features { color:var(--fail); }
-.passed-features { color:var(--pass); }
-.filter { margin-bottom:12px; }
-.filter input { padding:8px 12px; width:100%; max-width:320px; border:1px solid var(--border); border-radius:8px; font-size:14px; }
-.compliance { margin-top:28px; background:var(--panel); border-radius:12px; padding:18px; border:1px solid var(--border); }
-.compliance h2 { margin:0 0 12px 0; font-size:16px; }
-.compliance-list { margin:0; padding-left:20px; }
-.compliance-list li { margin:8px 0; }
-.compliance-list .code { font-weight:700; }
-.affected-prims { font-size:12px; color:var(--muted); margin:8px 0; }
-.affected-prims .label { font-weight:600; color:var(--text); }
-.prim-list-inline { list-style:none; padding-left:0; margin:4px 0 0 0; display:flex; flex-wrap:wrap; gap:6px 12px; }
-.prim-list-inline li { font-family: ui-monospace, monospace; font-size:11px; word-break:break-all; }
-.muted { color:var(--muted); }
-.no-spec { color:var(--muted); font-style:italic; font-size:11px; }
-.packaging-note { background:var(--note-bg); border:1px solid var(--note-border); border-radius:8px; padding:10px 14px; margin:0 0 16px 0; font-size:13px; color:var(--note-text); }
-.packaging-note code { background:var(--note-code); padding:1px 5px; border-radius:4px; font-size:12px; }
-.coverage-banner { background:var(--note-bg); border:1px solid var(--note-border); border-radius:8px; padding:10px 14px; margin:0 0 16px 0; font-size:13px; color:var(--note-text); }
-.coverage-banner code { background:var(--note-code); padding:1px 5px; border-radius:4px; font-size:12px; }
-.coverage-banner details { margin-top:8px; }
-.coverage-banner summary { cursor:pointer; font-weight:600; }
-.coverage-banner ul { margin:6px 0 0 0; padding-left:20px; }
-.outside-spec-banner { background:var(--note-bg); border:1px solid var(--note-border); border-radius:8px; padding:10px 14px; margin:0 0 16px 0; font-size:13px; color:var(--note-text); }
-.outside-spec-banner code { background:var(--note-code); padding:1px 5px; border-radius:4px; font-size:12px; }
-.thumbnail-banner { background:var(--note-bg); border:1px solid var(--note-border); border-radius:8px; padding:10px 14px; margin:0 0 16px 0; font-size:13px; color:var(--note-text); }
-.thumbnail-banner code { background:var(--note-code); padding:1px 5px; border-radius:4px; font-size:11px; word-break:break-all; }
-.thumbnail-banner details { margin-top:8px; }
-.thumbnail-banner summary { cursor:pointer; font-weight:600; }
-.thumbnail-banner ul { margin:6px 0 0 0; padding-left:20px; }
-.header-actions { margin-left:auto; display:flex; gap:8px; align-items:center; }
-.caveat-toggle { padding:6px 12px; background:var(--note-bg); border:1px solid var(--note-border); border-radius:8px; color:var(--note-text); cursor:pointer; font-size:13px; font-weight:600; display:inline-flex; align-items:center; gap:6px; animation:caveat-pulse 1.6s ease-in-out infinite; }
-.caveat-toggle:hover { filter:brightness(1.05); }
-.caveat-toggle .caveat-count { background:var(--note-text); color:var(--note-bg); border-radius:999px; padding:1px 8px; font-size:11px; font-weight:700; line-height:1.4; min-width:18px; text-align:center; }
-.caveat-toggle.open { animation:none; box-shadow:none; }
-@keyframes caveat-pulse {
-  0%, 100% { box-shadow:0 0 0 0 var(--note-border); }
-  50%      { box-shadow:0 0 0 6px transparent; }
-}
-#caveats[hidden] { display:none; }
-.theme-toggle { padding:6px 12px; background:transparent; border:1px solid var(--border); border-radius:8px; color:var(--text); cursor:pointer; font-size:13px; }
-.theme-toggle:hover { background:var(--bg); }
-""".strip()
-
-
-def write_dashboard(out_dir: Path, target: Path, profile: str, profile_version: str,
-                    results: list[dict],
-                    specs_docs_dir: Path | None = None,
-                    dashboard_docs_dir: Path | None = None,
-                    thumbnail_provenance: list[dict] | None = None,
-                    profile_coverage: dict | None = None) -> Path:
-    total = len(results)
-    failed = sum(1 for r in results if not r["passed"])
-    passed_checks = sum(len(r.get("passed_features", [])) for r in results)
-
-    doc_url = _make_doc_url_resolver(out_dir, dashboard_docs_dir, specs_docs_dir)
-    # Map asset name -> relative path under <out_dir>/images/, only when actually
-    # copied. Reference relatively so the dashboard contains no external URLs.
-    thumb_rel_by_asset = {
-        e["asset"]: e["rel"]
-        for e in (thumbnail_provenance or [])
-        if e.get("present")
-    }
-    asset_blocks = "\n".join(_render_asset_block(r, doc_url, thumb_rel_by_asset, target) for r in results)
-    thumbnail_banner = _render_thumbnail_banner(thumbnail_provenance or [], target)
-    coverage_banner = _render_coverage_banner(profile_coverage)
-    outside_spec_banner = _render_outside_spec_banner(results)
-    env_blocked_banner = _render_env_blocked_banner(results)
-    compliance = _render_compliance(results, doc_url, target)
-    generated = datetime.now(timezone.utc).isoformat()
-    target_str = str(target).replace("\\", "/")
-    # Show only the packages-relative tail, never the absolute path —
-    # absolute paths leak machine-specific user dirs into shared reports.
-    if "/packages/" in target_str:
-        raw_hint = target_str.split("/packages/", 1)[1]
-        packaging_note = (
-            f'<div class="packaging-note">'
-            f'<strong>Packaged tree.</strong> This report validates assets after the '
-            f'<code>simready ingest usd</code> step. Raw inputs live at '
-            f'<code>assets_to_validate/{html.escape(raw_hint)}</code>; '
-            f'packaged output lives at <code>packages/{html.escape(raw_hint)}</code>.'
-            f'</div>'
-        )
-    else:
-        packaging_note = ""
-
-    # Group all the yellow-warning banners under a single `Caveats` toggle so
-    # the dashboard stays clean by default and the user opts in to read them.
-    caveats_list = [b for b in (env_blocked_banner, coverage_banner, outside_spec_banner, packaging_note, thumbnail_banner) if b]
-    caveats_count = len(caveats_list)
-    if caveats_count > 0:
-        caveats_button = (
-            f'<button type="button" id="caveatsToggle" class="caveat-toggle" '
-            f'aria-expanded="false" aria-controls="caveats" aria-label="Show caveats">'
-            f'<span>Caveats</span>'
-            f'<span class="caveat-count">{caveats_count}</span>'
-            f'</button>'
-        )
-        caveats_section = (
-            '<div id="caveats" hidden>' + "".join(caveats_list) + '</div>'
-        )
-    else:
-        caveats_button = ""
-        caveats_section = ""
-
-    html_doc = f"""<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <title>Validation Report &mdash; {html.escape(target.name)}</title>
-  <script>(function(){{var t=null;try{{t=localStorage.getItem('vr-theme');}}catch(e){{}}if(t==='dark'||t==='light')document.documentElement.setAttribute('data-theme',t);}})();</script>
-  <style>{CSS}</style>
-</head>
-<body>
-  <header>
-    <div class="logo">V</div>
-    <div>
-      <h1>Validation Report &mdash; {html.escape(target.name)}</h1>
-      <div class="meta">Profile: <strong>{html.escape(profile)}</strong> v{html.escape(profile_version)} &middot; Generated: {html.escape(generated)}</div>
-    </div>
-    <div class="header-actions">
-      {caveats_button}
-      <button type="button" id="themeToggle" class="theme-toggle" aria-label="Toggle theme">Dark mode</button>
-    </div>
-  </header>
-  {caveats_section}
-  <div class="summary">
-    <div class="card"><div class="label">Total assets</div><div class="value">{total}</div></div>
-    <div class="card"><div class="label">Failed assets</div><div class="value">{failed}</div></div>
-    <div class="card"><div class="label">Passed feature checks</div><div class="value">{passed_checks}</div></div>
-  </div>
-  <div class="filter"><input type="text" id="filterInput" placeholder="Filter by asset name..." /></div>
-  {asset_blocks}
-  {compliance}
-  <script>
-  (function() {{
-    var input = document.getElementById("filterInput");
-    var blocks = document.querySelectorAll(".asset-block");
-    if (input) {{
-      function filter() {{
-        var q = (input.value || "").trim().toLowerCase();
-        for (var i = 0; i < blocks.length; i++) {{
-          var name = (blocks[i].getAttribute("data-asset-name") || "");
-          blocks[i].style.display = (!q || name.indexOf(q) !== -1) ? "" : "none";
-        }}
-      }}
-      input.addEventListener("input", filter);
-      input.addEventListener("keyup", filter);
-    }}
-    var caveatsBtn = document.getElementById("caveatsToggle");
-    var caveatsBox = document.getElementById("caveats");
-    if (caveatsBtn && caveatsBox) {{
-      caveatsBtn.addEventListener("click", function() {{
-        var open = caveatsBox.hidden;
-        caveatsBox.hidden = !open;
-        caveatsBtn.setAttribute("aria-expanded", open ? "true" : "false");
-        caveatsBtn.classList.toggle("open", open);
-      }});
-    }}
-    var btn = document.getElementById("themeToggle");
-    var mq = window.matchMedia ? window.matchMedia("(prefers-color-scheme: dark)") : null;
-    function isDark() {{
-      var attr = document.documentElement.getAttribute("data-theme");
-      if (attr === "dark") return true;
-      if (attr === "light") return false;
-      return mq ? mq.matches : false;
-    }}
-    function syncLabel() {{
-      if (btn) btn.textContent = isDark() ? "Light mode" : "Dark mode";
-    }}
-    syncLabel();
-    if (mq && mq.addEventListener) mq.addEventListener("change", syncLabel);
-    if (btn) {{
-      btn.addEventListener("click", function() {{
-        var next = isDark() ? "light" : "dark";
-        document.documentElement.setAttribute("data-theme", next);
-        try {{ localStorage.setItem("vr-theme", next); }} catch(e) {{}}
-        syncLabel();
-      }});
-    }}
-  }})();
-  </script>
-</body>
-</html>
-"""
-    out = out_dir / "index.html"
-    out.write_text(html_doc, encoding="utf-8")
-    return out
-
-
-def _render_outside_spec_banner(results: list[dict]) -> str:
-    """Banner summarizing how many issues the validator reported against
-    requirements that aren't part of the loaded profile's feature set.
-    These are deliberately suppressed from the per-asset blocks and the
-    compliance footer — the report scope is the chosen spec only — so we
-    surface the count here for transparency.
-    """
-    total_issues = 0
-    unique_codes: set[str] = set()
-    affected_assets: set[str] = set()
-    for r in results:
-        if not r.get("extra_failures"):
-            continue
-        affected_assets.add(r["name"])
-        for e in r["extra_failures"]:
-            total_issues += int(e.get("count") or 0)
-            if e.get("code"):
-                unique_codes.add(e["code"])
-    if total_issues == 0:
-        return ""
-    return f'''
-<div class="outside-spec-banner">
-  <strong>Out-of-spec issues hidden.</strong> The validator reported
-  <strong>{total_issues}</strong> issue(s) against
-  <strong>{len(unique_codes)}</strong> requirement code(s) that aren\'t
-  part of this profile\'s feature set, across
-  <strong>{len(affected_assets)}</strong> asset(s). These are not listed
-  in the report — the displayed pass/fail is scoped to the loaded profile
-  only. See <code>PROBLEMS.md</code> for why this filter exists.
-</div>
-'''
-
-
-def _render_coverage_banner(coverage: dict | None) -> str:
-    """Banner shown when the loaded profile has fewer features than its
-    `profiles.toml` entry declares. The validator silently drops feature
-    entries whose ID + version aren't in the registry, which can leave a
-    profile reporting against a tiny subset of what it claims to check.
-    See PROBLEMS.md P1.
-    """
-    if not coverage or coverage.get("declared") is None:
-        return ""
-    missing = coverage.get("missing") or []
-    if not missing:
-        return ""
-    declared = coverage["declared"]
-    loaded = coverage["loaded"]
-    missing_items = "".join(
-        f'<li><code>{html.escape(m["id"])}</code> '
-        f'<span class="muted">v{html.escape(m["version"])}</span></li>'
-        for m in missing
-    )
-    return f'''
-<div class="coverage-banner">
-  <strong>Coverage gap.</strong> This profile declares <strong>{declared}</strong> features
-  in <code>profiles.toml</code> but the validator loaded only <strong>{loaded}</strong>.
-  The remaining {len(missing)} were silently dropped because their ID + version
-  isn\'t registered in the foundation specs. The pass/fail numbers below reflect
-  only the loaded set — the dropped features were <em>not</em> checked.
-  See <code>PROBLEMS.md</code> P1 for root cause and fix path.
-  <details><summary>Dropped feature IDs ({len(missing)})</summary>
-  <ul>{missing_items}</ul></details>
-</div>
-'''
-
-
-def _render_env_blocked_banner(results: list[dict]) -> str:
-    """Banner shown when validate.py's P2 filter dropped env-blocked issues.
-
-    Aggregates per-asset env_blocked counts so the user sees both that a
-    suppression happened and roughly how much was suppressed. See PROBLEMS.md P2.
-    """
-    physx_total = 0
-    mdl_total = 0
-    for r in results:
-        eb = r.get("env_blocked") or {}
-        physx_total += int(eb.get("physxschema_unavailable") or 0)
-        mdl_total += int(eb.get("omnipbr_unresolved") or 0)
-    if not (physx_total or mdl_total):
-        return ""
-    parts = []
-    if physx_total:
-        parts.append(
-            f'<strong>{physx_total}</strong> PhysX-rule errors '
-            f'(<code>PhysxSchema is not available in this environment</code>)'
-        )
-    if mdl_total:
-        parts.append(
-            f'<strong>{mdl_total}</strong> stock MDL-reference failures '
-            f'(<code>OmniPBR.mdl</code> not resolvable outside Kit)'
-        )
-    return f'''
-<div class="coverage-banner">
-  <strong>Environment-blocked checks suppressed.</strong>
-  This run dropped {" and ".join(parts)} because the active Python venv has
-  <code>usd-core</code> but not the Kit-bundled <code>PhysxSchema</code> /
-  Kit MDL search path. These checks couldn\'t produce useful results here,
-  so they would otherwise have inflated the issue count without telling you
-  anything about the asset. Pass/fail below reflects only checks that ran
-  meaningfully. See <code>PROBLEMS.md</code> P2 for root cause and fix path.
-</div>
-'''
-
-
-def _render_thumbnail_banner(provenance: list[dict], target: Path | None = None) -> str:
-    """Banner explaining where the asset thumbnails came from (since they
-    weren't produced by this run's packaging step)."""
-    present = [p for p in provenance if p.get("present")]
-    if not present:
-        return ""
-    items = "".join(
-        f'<li><code>{html.escape(p["rel"])}</code> &mdash; copied from <code>{html.escape(_relativize_msg(p.get("copied_from",""), target))}</code></li>'
-        for p in present
-    )
-    return f'''
-<div class="thumbnail-banner">
-  <strong>Asset thumbnails — sourced externally.</strong>
-  These tiles were copied into this report\'s <code>images/</code> directory from
-  per-asset spec paths (<code>&lt;asset_dir&gt;/.thumbs/256x256/&lt;filename&gt;.png</code>) populated
-  earlier from NVIDIA\'s Isaac 6.0 content S3 bucket
-  (<code>Assets/Isaac/6.0/Isaac/Robots/Yaskawa/Motoman Next/...</code>).
-  They are <strong>not</strong> the output of this run\'s packaging step;
-  the customer\'s pipeline should generate authoritative thumbnails before the
-  validation reports them as spec-compliant.
-  <details><summary>Per-tile source ({len(present)} of {len(provenance)})</summary>
-  <ul>{items}</ul></details>
-</div>
-'''
-
-
-def _render_asset_block(r: dict, doc_url, thumb_rel_by_asset: dict | None = None,
-                        target: Path | None = None) -> str:
-    name = r["name"]
-    rel = r.get("rel_path") or r.get("path", "")
-    affected = r.get("affected_prims", [])
-    failed = r.get("failed_features", [])
-    passed = r.get("passed_features", [])
-
-    if affected:
-        prims_html = (
-            '<div class="affected-prims"><span class="label">Affected prims:</span>'
-            '<ul class="prim-list-inline">'
-            + "".join(f"<li>{html.escape(p)}</li>" for p in affected)
-            + "</ul></div>"
-        )
-    else:
-        prims_html = ""
-
-    def _feature_link(rel_path: str | None) -> str:
-        """Inline 'View feature doc.' link — empty string when no doc available."""
-        url = doc_url(rel_path)
-        if not url:
-            return ''
-        return f' <a class="docref" href="{html.escape(url)}" target="_blank" rel="noopener">View feature doc.</a>'
-
-    def _capability_link(rel_path: str | None) -> str:
-        """Inline 'View capability doc' link — empty string when no doc available."""
-        url = doc_url(rel_path)
-        if not url:
-            return ''
-        return f' <a class="docref" href="{html.escape(url)}" target="_blank" rel="noopener">View capability doc</a>'
-
-    if failed:
-        items = []
-        for f in failed:
-            req_paths = f.get("requirement_paths") or {}
-            feat_link = _feature_link(f.get("path"))
-            codes_parts = []
-            for c in f.get("failed_codes", []):
-                codes_parts.append(
-                    f'<span class="code">{html.escape(c)}</span>'
-                    f'{_capability_link(req_paths.get(c))}'
-                )
-            items.append(
-                f'<li><strong class="feat-id">{html.escape(f["id"])}</strong>'
-                f'{feat_link} '
-                + " ".join(codes_parts)
-                + '</li>'
-            )
-        failed_html = "<ul>" + "".join(items) + "</ul>"
-    else:
-        failed_html = '<p class="muted" style="margin:0">None</p>'
-
-    if passed:
-        # Passed features render as plain IDs — no doc link, matching the
-        # reference dashboard. Users only need quick access to docs when
-        # something failed.
-        items = [
-            f'<li><strong class="feat-id">{html.escape(f["id"])}</strong></li>'
-            for f in passed
-        ]
-        passed_html = "<ul>" + "".join(items) + "</ul>"
-    else:
-        passed_html = '<p class="muted" style="margin:0">None</p>'
-
-    thumb_rel = (thumb_rel_by_asset or {}).get(name)
-    if thumb_rel:
-        thumb_html = (
-            f'<div class="asset-thumb-wrap">'
-            f'<img class="asset-thumb" src="{html.escape(thumb_rel)}" alt="{html.escape(name)} thumbnail" />'
-            f'</div>'
-        )
-    else:
-        thumb_html = (
-            '<div class="asset-thumb-wrap">'
-            '<div class="asset-thumb asset-thumb-missing" aria-label="no thumbnail">'
-            '<span>missing image</span>'
-            '</div></div>'
-        )
-
-    # `extra_failures` (issues against requirements outside the loaded
-    # profile) are intentionally NOT rendered per-asset. They get summarized
-    # as a count in the Caveats panel; the report scope is the chosen
-    # profile only.
-    extras_html = ""
-
-    return f"""
-<div class="asset-block" data-asset-name="{html.escape(name.lower())}">
-  {thumb_html}
-  <div class="asset-body">
-    <h2>{html.escape(name)}</h2>
-    <div class="path">{html.escape(rel)}</div>
-    {prims_html}
-    <section class="failed-features">
-      <h3>Failed features</h3>
-      {failed_html}
-    </section>
-    <section class="passed-features">
-      <h3>Passed features</h3>
-      {passed_html}
-    </section>{extras_html}
-  </div>
-</div>"""
-
-
-def _render_compliance(results: list[dict], doc_url=None, target: Path | None = None) -> str:
-    """Footer listing every in-profile requirement code that failed, with its
-    short message and (when available) a link to the foundation spec doc
-    that defines it. Codes outside the loaded profile are NOT listed here —
-    the report scope is the chosen spec only; out-of-spec failure counts
-    surface in the Caveats panel instead. Codes without a `path` get a
-    "(no spec source)" tag so the accountability gap is visible."""
-    # Build the set of in-profile failure codes from `failed_features`.
-    # Anything not in this set is an "extra" outside the loaded profile and
-    # is intentionally suppressed from the per-asset and footer views.
-    profile_failure_codes: set[str] = set()
-    for r in results:
-        for ff in r.get("failed_features", []):
-            profile_failure_codes.update(ff.get("failed_codes", []))
-    code_to_entry: dict[str, dict] = {}
-    for r in results:
-        for issue in r.get("issues", []):
-            if issue["severity"] not in ("failure", "error"):
-                continue
-            code = issue.get("code") or "UNKNOWN"
-            if code not in profile_failure_codes:
-                continue
-            if code not in code_to_entry:
-                code_to_entry[code] = {
-                    "msg": issue.get("msg", ""),
-                    "path": issue.get("path"),
-                }
-    if not code_to_entry:
-        return ""
-
-    items_html_parts: list[str] = []
-    accounted = 0
-    for code, e in sorted(code_to_entry.items()):
-        url = doc_url(e["path"]) if doc_url else None
-        if url:
-            code_html = f'<a class="code" href="{html.escape(url)}" target="_blank" rel="noopener">{html.escape(code)}</a>'
-            accounted += 1
-            no_spec_tag = ""
-        else:
-            code_html = f'<span class="code">{html.escape(code)}</span>'
-            no_spec_tag = ' <span class="no-spec">(no spec source)</span>'
-        msg = _relativize_msg(e["msg"], target)
-        items_html_parts.append(
-            f'<li>{code_html}: {html.escape(msg) if msg else "No guidance available."}{no_spec_tag}</li>'
-        )
-    items_html = "".join(items_html_parts)
-    coverage = (
-        f'<p class="muted">{accounted} of {len(code_to_entry)} requirement '
-        f'code(s) link to a foundation spec source. The rest are flagged '
-        f'<em>(no spec source)</em>.</p>'
-    )
-    return f"""
-<section class="compliance">
-  <h2>How to comply with failed requirements</h2>
-  <p class="muted">Each requirement code below is shown with the first message recorded for it.</p>
-  {coverage}
-  <ul class="compliance-list">{items_html}</ul>
-</section>"""
+"""Dashboard HTML generator for the /simready-report skill.
+
+Given the per-asset results produced by validate.py, emits index.html in the
+style of usd_validation_dashboard_final/: summary cards, asset filter,
+per-asset blocks (failed/passed features, affected prims), compliance footer.
+
+Thumbnails are embedded inline (base64 data URI) from the spec path
+<asset_dir>/.thumbs/256x256/<filename>.png — matching the ThumbnailExists rule.
+"""
+from __future__ import annotations
+
+import html
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _ensure_static_copied(out_docs_dir: Path, dashboard_docs_dir: Path | None) -> bool:
+    """Mirror the reference dashboard's `_static/` into `<out_docs_dir>/_static/` once.
+
+    Returns True if the static tree is available (so pages can link to it),
+    False if the dashboard isn't present or the copy failed.
+    """
+    if dashboard_docs_dir is None:
+        return False
+    src = dashboard_docs_dir / "_static"
+    if not src.is_dir():
+        return False
+    dest = out_docs_dir / "_static"
+    if dest.exists():
+        return True
+    import shutil
+    try:
+        shutil.copytree(src, dest)
+        return True
+    except Exception:
+        return False
+
+
+def _render_md_page(title: str, rel_path: str, source_path: Path, body_html: str,
+                    has_static: bool) -> str:
+    """Render a markdown page using the reference dashboard's Sphinx assets.
+
+    `rel_path` is the doc's path relative to `out_docs_dir` (e.g.
+    `features/FET_001-minimal.html`); we compute how many `../` are needed to
+    reach `_static/` based on its depth.
+    """
+    depth = rel_path.replace("\\", "/").count("/")
+    static_prefix = "../" * depth + "_static/"
+    if has_static:
+        head_links = f"""
+  <link rel="stylesheet" href="{static_prefix}styles/theme.css" />
+  <link rel="stylesheet" href="{static_prefix}styles/bootstrap.css" />
+  <link rel="stylesheet" href="{static_prefix}styles/pydata-sphinx-theme.css" />
+  <link rel="stylesheet" href="{static_prefix}styles/nvidia-sphinx-theme.css" />
+  <link rel="stylesheet" href="{static_prefix}pygments.css" />
+  <link rel="stylesheet" href="{static_prefix}_style.css" />
+  <link rel="stylesheet" href="{static_prefix}custom.css" />
+  <link rel="stylesheet" href="{static_prefix}sphinx-design.min.css" />
+  <link rel="stylesheet" href="{static_prefix}vendor/fontawesome/6.5.2/css/all.min.css" />
+"""
+        body_open = '<main class="bd-main"><div class="bd-content"><div class="bd-article-container"><article class="bd-article">'
+        body_close = '</article></div></div></main>'
+    else:
+        head_links = ""
+        body_open = '<article style="max-width:880px;margin:24px auto;padding:24px 28px;font-family:Segoe UI,Arial,sans-serif;line-height:1.55;">'
+        body_close = '</article>'
+
+    # `source_path` is an absolute machine-specific path inside the foundations
+    # checkout — don't render it. Show the source's path relative to the
+    # foundation docs root (i.e. `rel_path` minus the .html for the .md form),
+    # which is portable across machines that share the same foundations layout.
+    source_md_rel = (rel_path[:-5] + ".md") if rel_path.endswith(".html") else rel_path
+    return f"""<!DOCTYPE html>
+<html lang="en" data-content_root="{'../' * depth}">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>{html.escape(title)}</title>
+  <script>document.documentElement.dataset.mode = localStorage.getItem("mode") || "";document.documentElement.dataset.theme = localStorage.getItem("theme") || "";</script>{head_links}
+</head>
+<body data-bs-spy="scroll">
+{body_open}
+<p class="text-muted" style="font-size:12px;margin-bottom:14px;">Source: <code>nv_core/sr_specs/docs/{html.escape(source_md_rel)}</code></p>
+{body_html}
+{body_close}
+</body>
+</html>
+"""
+
+
+_NO_SPEC_TAG = ' <span class="no-spec">(no spec source)</span>'
+
+
+def _relativize_msg(msg: str, target: Path | None) -> str:
+    """Strip machine-specific absolute path prefixes from validator messages.
+
+    `omni.asset_validator` rule messages embed the absolute path of each USD
+    being inspected. We replace the target's path prefix (and the path up to
+    `packages/` / `assets_to_validate/`) with relative tokens so reports
+    don't leak the report-author's user dir.
+    """
+    if not msg or target is None:
+        return msg
+    out = msg
+    target_fwd = str(target).replace("\\", "/")
+    target_bwd = str(target).replace("/", "\\")
+    for prefix in (target_fwd, target_bwd):
+        if prefix and prefix in out:
+            out = out.replace(prefix, "<target>")
+    # Catch absolute paths that point at the workspace's packages/ or
+    # assets_to_validate/ — same machine-specificity, different anchor.
+    for marker in ("/packages/", "\\packages\\", "/assets_to_validate/", "\\assets_to_validate\\"):
+        idx = out.find(marker)
+        while idx != -1:
+            # Find the start of the absolute path containing this marker
+            # (a drive letter "X:\" or POSIX "/" boundary going left).
+            start = idx
+            while start > 0 and out[start - 1] not in (" ", "<", "(", "[", '"', "'", "\n", "\t"):
+                start -= 1
+            # Replace from `start` through the marker with the marker's tail.
+            anchor = marker.strip("/\\").replace("\\", "/")  # "packages" / "assets_to_validate"
+            tail_pos = idx + len(marker)
+            out = out[:start] + f"<{anchor}>/" + out[tail_pos:]
+            idx = out.find(marker, start + len(anchor) + 3)
+    return out
+
+_md_renderer = None
+
+
+def _md_to_html(md_text: str) -> str:
+    global _md_renderer
+    if _md_renderer is None:
+        from markdown_it import MarkdownIt
+        # html:True passes raw HTML through unescaped — safe only because the
+        # markdown comes from the trusted foundations repo, not user input.
+        _md_renderer = MarkdownIt("commonmark", {"html": True, "linkify": True, "typographer": True}).enable("table")
+    return _md_renderer.render(md_text)
+
+
+_IMG_PLACEHOLDER_SVG = (
+    "data:image/svg+xml;utf8,"
+    "<svg xmlns='http://www.w3.org/2000/svg' width='320' height='180' viewBox='0 0 320 180'>"
+    "<rect width='320' height='180' fill='%23f0f2f8' stroke='%23c7cee0' stroke-dasharray='6 4' stroke-width='2'/>"
+    "<text x='50%25' y='50%25' dominant-baseline='middle' text-anchor='middle' "
+    "font-family='Segoe UI,Arial,sans-serif' font-size='14' fill='%237280a7'>image missing</text>"
+    "</svg>"
+)
+
+
+def _localize_images(body_html: str, md_source: Path, out_html_path: Path) -> str:
+    """Walk every `<img src="...">` in `body_html`. If src is a relative path,
+    copy the source file (relative to `md_source.parent`) into the equivalent
+    location next to `out_html_path`. When the source file is missing, replace
+    the src with an inline SVG placeholder so the page never 404s.
+    """
+    import re
+    import shutil
+
+    md_dir = md_source.parent
+    out_dir = out_html_path.parent
+
+    def repl(match):
+        full_tag = match.group(0)
+        src_match = re.search(r'src="([^"]+)"', full_tag)
+        if not src_match:
+            return full_tag
+        src = src_match.group(1)
+        if src.startswith(("http://", "https://", "data:", "//", "/")):
+            return full_tag  # absolute / data URI / protocol-relative — leave alone
+        rel = src.lstrip("./").replace("\\", "/")
+        source_file = (md_dir / src).resolve()
+        # Containment guard on the SOURCE: a crafted ../ src must not read
+        # files outside the markdown tree. Escape -> skip to placeholder.
+        try:
+            source_file.relative_to(md_dir.resolve())
+        except ValueError:
+            import sys
+            print(f"[report] skipping out-of-tree image src: {src!r}", file=sys.stderr)
+            return re.sub(r'src="[^"]+"', f'src="{_IMG_PLACEHOLDER_SVG}"', full_tag)
+        if source_file.is_file():
+            dest_file = (out_dir / rel).resolve()
+            try:
+                dest_file.relative_to(out_dir.resolve())  # guard against ../ escape
+                dest_file.parent.mkdir(parents=True, exist_ok=True)
+                if not dest_file.exists() or dest_file.stat().st_size != source_file.stat().st_size:
+                    shutil.copy2(source_file, dest_file)
+                return full_tag
+            except (ValueError, OSError):
+                pass
+        # Missing source — swap to placeholder
+        return re.sub(r'src="[^"]+"', f'src="{_IMG_PLACEHOLDER_SVG}"', full_tag)
+
+    return re.sub(r"<img\b[^>]*>", repl, body_html)
+
+
+_A_TAG_RE = None
+
+
+def _localize_links(body_html: str, md_source: Path, out_html_path: Path,
+                    specs_docs_dir: Path, out_docs_root: Path,
+                    resolver) -> str:
+    """Rewrite relative <a href="..."> targets so the docs tree is self-contained.
+
+    - .md targets that resolve to a file inside `specs_docs_dir`: rewrite href
+      to .html and recursively render via `resolver(<rel>.html)`.
+    - non-.md targets inside `specs_docs_dir`: copy verbatim into the mirrored
+      location under `out_docs_root` and rewrite href to that copy.
+    - root-relative ("/...") hrefs treated as relative to `specs_docs_dir`;
+      bare paths without an extension are tried as `.md`.
+    - links pointing outside `specs_docs_dir` or at non-existent targets are
+      replaced with <span class="docref-disabled" title="...">TEXT</span> so
+      the visible text remains but no href can 404.
+    """
+    import os
+    import re
+    import shutil
+
+    global _A_TAG_RE
+    if _A_TAG_RE is None:
+        _A_TAG_RE = re.compile(r'<a\s+([^>]*?)>(.*?)</a>', re.DOTALL | re.IGNORECASE)
+
+    md_dir = md_source.parent
+    out_dir = out_html_path.parent
+    specs_root = specs_docs_dir.resolve()
+    out_docs_resolved = out_docs_root.resolve()
+
+    def _disable(inner: str, why: str = "link target not available in report") -> str:
+        return f'<span class="docref-disabled" title="{html.escape(why)}">{inner}</span>'
+
+    def _resolve_target(href_path: str) -> Path | None:
+        if href_path.startswith("/"):
+            base = specs_root / href_path.lstrip("/")
+            if not base.suffix:
+                base = base.with_suffix(".md")
+            return base
+        return (md_dir / href_path)
+
+    def repl(m: "re.Match[str]") -> str:
+        attrs = m.group(1)
+        inner = m.group(2)
+        href_m = re.search(r'href\s*=\s*"([^"]*)"', attrs)
+        if not href_m:
+            return m.group(0)
+        href = href_m.group(1).strip()
+        if not href:
+            return m.group(0)
+        if href.startswith(("http://", "https://", "data:", "mailto:", "//", "#", "javascript:")):
+            return m.group(0)
+
+        if "#" in href:
+            path_part, frag = href.split("#", 1)
+            frag = "#" + frag
+        else:
+            path_part, frag = href, ""
+        if not path_part:
+            return m.group(0)
+
+        target = _resolve_target(path_part)
+        if target is None:
+            return _disable(inner)
+        try:
+            target = target.resolve()
+        except OSError:
+            return _disable(inner)
+        try:
+            rel_to_specs = target.relative_to(specs_root)
+        except ValueError:
+            return _disable(inner, "link target outside foundation docs")
+        if not target.exists():
+            return _disable(inner, "link target missing in foundation docs")
+
+        rel_str = str(rel_to_specs).replace("\\", "/")
+
+        if target.suffix.lower() == ".md":
+            html_rel = rel_str[:-3] + ".html"
+            url = resolver(html_rel)
+            if url is None:
+                return _disable(inner)
+            target_out = out_docs_resolved / html_rel
+        else:
+            target_out = out_docs_resolved / rel_str
+            try:
+                target_out.parent.mkdir(parents=True, exist_ok=True)
+                if not target_out.exists() or target_out.stat().st_size != target.stat().st_size:
+                    shutil.copy2(target, target_out)
+            except OSError:
+                return _disable(inner, "could not copy link target into report")
+
+        try:
+            new_href = os.path.relpath(target_out, out_dir).replace("\\", "/") + frag
+        except ValueError:
+            return _disable(inner)
+        new_attrs = re.sub(r'href\s*=\s*"[^"]*"', f'href="{new_href}"', attrs, count=1)
+        return f'<a {new_attrs}>{inner}</a>'
+
+    return _A_TAG_RE.sub(repl, body_html)
+
+
+def _make_doc_url_resolver(out_dir: Path, dashboard_docs_dir: Path | None,
+                           specs_docs_dir: Path | None):
+    """Build a `_doc_url(rel_path)` callable.
+
+    Every resolvable doc is rendered from the foundation markdown source into
+    `<out_dir>/docs/<rel_path>` so the dashboard has a single, self-contained
+    docs tree. The reference-dashboard pre-built HTML is no longer used as a
+    link target — it would split the source of truth.
+
+    `dashboard_docs_dir` is kept on the signature for API stability but not
+    consulted here.
+    """
+    rendered_cache: dict[str, str] = {}
+    out_docs_dir = out_dir / "docs"
+    out_docs_dir.mkdir(parents=True, exist_ok=True)
+    has_static = _ensure_static_copied(out_docs_dir, dashboard_docs_dir)
+
+    def resolve(rel_path: str | None) -> str | None:
+        if not rel_path or specs_docs_dir is None:
+            return None
+        if rel_path in rendered_cache:
+            return rendered_cache[rel_path]
+        md_rel = rel_path[:-5] + ".md" if rel_path.endswith(".html") else rel_path
+        md_source = specs_docs_dir / md_rel
+        if not md_source.is_file():
+            return None
+        # Cache the URL before rendering body so cycles in the foundation's
+        # cross-doc links (e.g. profile -> feature -> profile) terminate.
+        url = "docs/" + rel_path.replace("\\", "/")
+        rendered_cache[rel_path] = url
+        out_path = out_docs_dir / rel_path
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        body = _md_to_html(md_source.read_text(encoding="utf-8"))
+        body = _localize_images(body, md_source, out_path)
+        body = _localize_links(body, md_source, out_path, specs_docs_dir, out_docs_dir, resolve)
+        out_path.write_text(
+            _render_md_page(rel_path, rel_path, md_source, body, has_static),
+            encoding="utf-8",
+        )
+        return url
+
+    return resolve
+
+
+CSS = """
+:root { --bg:#f4f6fb; --panel:#fff; --text:#1f2a44; --muted:#7280a7; --border:#e6ebf5; --fail:#c00; --pass:#0a0; --link:#2b6de2; --note-bg:#fff8e6; --note-border:#f1d38a; --note-text:#6b4f00; --note-code:#fff3cc; --thumb-bg:#f4f6fb; }
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) { --bg:#0f1320; --panel:#1a2030; --text:#e6ebf5; --muted:#8a93b3; --border:#2a3142; --fail:#ff6b6b; --pass:#4ade80; --link:#7ba9ff; --note-bg:#2a2410; --note-border:#5a4a1f; --note-text:#f1d38a; --note-code:#3a3018; --thumb-bg:#0f1320; }
+}
+:root[data-theme="dark"] { --bg:#0f1320; --panel:#1a2030; --text:#e6ebf5; --muted:#8a93b3; --border:#2a3142; --fail:#ff6b6b; --pass:#4ade80; --link:#7ba9ff; --note-bg:#2a2410; --note-border:#5a4a1f; --note-text:#f1d38a; --note-code:#3a3018; --thumb-bg:#0f1320; }
+* { box-sizing: border-box; }
+body { font-family: "Segoe UI", Arial, sans-serif; margin:0; background:var(--bg); color:var(--text); padding:16px; }
+header { display:flex; align-items:center; gap:10px; margin-bottom:16px; padding:12px 16px; background:var(--panel); border-radius:12px; border:1px solid var(--border); }
+header .logo { width:36px; height:36px; border-radius:10px; background:#2b6de2; color:#fff; display:grid; place-items:center; font-weight:700; }
+header h1 { margin:0; font-size:18px; }
+header .meta { color:var(--muted); font-size:12px; }
+.summary { display:grid; grid-template-columns:repeat(3,1fr); gap:12px; margin-bottom:20px; }
+.summary .card { background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:14px; }
+.summary .card .label { color:var(--muted); font-size:12px; }
+.summary .card .value { font-size:20px; font-weight:700; }
+.asset-block { background:var(--panel); border:1px solid var(--border); border-radius:12px; padding:14px; margin-bottom:14px; display:flex; gap:14px; align-items:flex-start; }
+.asset-block .asset-thumb-wrap { flex-shrink:0; width:140px; }
+.asset-block .asset-thumb { width:100%; height:auto; aspect-ratio:1; object-fit:cover; border-radius:8px; background:var(--border); display:block; }
+.asset-block .asset-thumb-missing { background:var(--thumb-bg); border:1px dashed var(--border); display:grid; place-items:center; color:var(--muted); font-size:11px; text-align:center; padding:8px; }
+.asset-block .asset-thumb-missing span { line-height:1.3; }
+.code { font-family: ui-monospace, monospace; font-size:12px; padding:1px 6px; border-radius:4px; background:var(--note-code); color:var(--note-text); margin-right:4px; }
+.feat-id { font-family: ui-monospace, monospace; font-size:13px; }
+a.docref { color:var(--link); text-decoration:underline; text-decoration-style:dotted; text-underline-offset:2px; font-size:12px; }
+a.docref:hover { text-decoration-style:solid; }
+a.code { text-decoration:underline; text-decoration-style:dotted; text-underline-offset:2px; }
+a.code:hover { text-decoration-style:solid; }
+.failed-features .feat-id { color:var(--fail); }
+.passed-features .feat-id { color:var(--pass); }
+.asset-block .asset-body { flex:1; min-width:0; }
+.asset-block h2 { margin:0 0 6px 0; font-size:15px; }
+.asset-block .path { font-size:12px; color:var(--muted); margin-bottom:10px; word-break:break-all; }
+.asset-block section { margin-top:10px; }
+.asset-block section h3 { margin:0 0 6px 0; font-size:13px; color:var(--muted); }
+.asset-block ul { margin:0; padding-left:20px; }
+.asset-block li { margin:4px 0; }
+.failed-features { color:var(--fail); }
+.passed-features { color:var(--pass); }
+.filter { margin-bottom:12px; }
+.filter input { padding:8px 12px; width:100%; max-width:320px; border:1px solid var(--border); border-radius:8px; font-size:14px; }
+.compliance { margin-top:28px; background:var(--panel); border-radius:12px; padding:18px; border:1px solid var(--border); }
+.compliance h2 { margin:0 0 12px 0; font-size:16px; }
+.compliance-list { margin:0; padding-left:20px; }
+.compliance-list li { margin:8px 0; }
+.compliance-list .code { font-weight:700; }
+.affected-prims { font-size:12px; color:var(--muted); margin:8px 0; }
+.affected-prims .label { font-weight:600; color:var(--text); }
+.prim-list-inline { list-style:none; padding-left:0; margin:4px 0 0 0; display:flex; flex-wrap:wrap; gap:6px 12px; }
+.prim-list-inline li { font-family: ui-monospace, monospace; font-size:11px; word-break:break-all; }
+.muted { color:var(--muted); }
+.no-spec { color:var(--muted); font-style:italic; font-size:11px; }
+.packaging-note { background:var(--note-bg); border:1px solid var(--note-border); border-radius:8px; padding:10px 14px; margin:0 0 16px 0; font-size:13px; color:var(--note-text); }
+.packaging-note code { background:var(--note-code); padding:1px 5px; border-radius:4px; font-size:12px; }
+.coverage-banner { background:var(--note-bg); border:1px solid var(--note-border); border-radius:8px; padding:10px 14px; margin:0 0 16px 0; font-size:13px; color:var(--note-text); }
+.coverage-banner code { background:var(--note-code); padding:1px 5px; border-radius:4px; font-size:12px; }
+.coverage-banner details { margin-top:8px; }
+.coverage-banner summary { cursor:pointer; font-weight:600; }
+.coverage-banner ul { margin:6px 0 0 0; padding-left:20px; }
+.outside-spec-banner { background:var(--note-bg); border:1px solid var(--note-border); border-radius:8px; padding:10px 14px; margin:0 0 16px 0; font-size:13px; color:var(--note-text); }
+.outside-spec-banner code { background:var(--note-code); padding:1px 5px; border-radius:4px; font-size:12px; }
+.thumbnail-banner { background:var(--note-bg); border:1px solid var(--note-border); border-radius:8px; padding:10px 14px; margin:0 0 16px 0; font-size:13px; color:var(--note-text); }
+.thumbnail-banner code { background:var(--note-code); padding:1px 5px; border-radius:4px; font-size:11px; word-break:break-all; }
+.thumbnail-banner details { margin-top:8px; }
+.thumbnail-banner summary { cursor:pointer; font-weight:600; }
+.thumbnail-banner ul { margin:6px 0 0 0; padding-left:20px; }
+.header-actions { margin-left:auto; display:flex; gap:8px; align-items:center; }
+.caveat-toggle { padding:6px 12px; background:var(--note-bg); border:1px solid var(--note-border); border-radius:8px; color:var(--note-text); cursor:pointer; font-size:13px; font-weight:600; display:inline-flex; align-items:center; gap:6px; animation:caveat-pulse 1.6s ease-in-out infinite; }
+.caveat-toggle:hover { filter:brightness(1.05); }
+.caveat-toggle .caveat-count { background:var(--note-text); color:var(--note-bg); border-radius:999px; padding:1px 8px; font-size:11px; font-weight:700; line-height:1.4; min-width:18px; text-align:center; }
+.caveat-toggle.open { animation:none; box-shadow:none; }
+@keyframes caveat-pulse {
+  0%, 100% { box-shadow:0 0 0 0 var(--note-border); }
+  50%      { box-shadow:0 0 0 6px transparent; }
+}
+#caveats[hidden] { display:none; }
+.theme-toggle { padding:6px 12px; background:transparent; border:1px solid var(--border); border-radius:8px; color:var(--text); cursor:pointer; font-size:13px; }
+.theme-toggle:hover { background:var(--bg); }
+""".strip()
+
+
+def write_dashboard(out_dir: Path, target: Path, profile: str, profile_version: str,
+                    results: list[dict],
+                    specs_docs_dir: Path | None = None,
+                    dashboard_docs_dir: Path | None = None,
+                    thumbnail_provenance: list[dict] | None = None,
+                    profile_coverage: dict | None = None) -> Path:
+    total = len(results)
+    failed = sum(1 for r in results if not r["passed"])
+    passed_checks = sum(len(r.get("passed_features", [])) for r in results)
+
+    doc_url = _make_doc_url_resolver(out_dir, dashboard_docs_dir, specs_docs_dir)
+    # Map asset name -> relative path under <out_dir>/images/, only when actually
+    # copied. Reference relatively so the dashboard contains no external URLs.
+    thumb_rel_by_asset = {
+        e["asset"]: e["rel"]
+        for e in (thumbnail_provenance or [])
+        if e.get("present")
+    }
+    asset_blocks = "\n".join(_render_asset_block(r, doc_url, thumb_rel_by_asset, target) for r in results)
+    thumbnail_banner = _render_thumbnail_banner(thumbnail_provenance or [], target)
+    coverage_banner = _render_coverage_banner(profile_coverage)
+    outside_spec_banner = _render_outside_spec_banner(results)
+    env_blocked_banner = _render_env_blocked_banner(results)
+    compliance = _render_compliance(results, doc_url, target)
+    generated = datetime.now(timezone.utc).isoformat()
+    target_str = str(target).replace("\\", "/")
+    # Show only the packages-relative tail, never the absolute path —
+    # absolute paths leak machine-specific user dirs into shared reports.
+    if "/packages/" in target_str:
+        raw_hint = target_str.split("/packages/", 1)[1]
+        packaging_note = (
+            f'<div class="packaging-note">'
+            f'<strong>Packaged tree.</strong> This report validates assets after the '
+            f'<code>simready ingest usd</code> step. Raw inputs live at '
+            f'<code>assets_to_validate/{html.escape(raw_hint)}</code>; '
+            f'packaged output lives at <code>packages/{html.escape(raw_hint)}</code>.'
+            f'</div>'
+        )
+    else:
+        packaging_note = ""
+
+    # Group all the yellow-warning banners under a single `Caveats` toggle so
+    # the dashboard stays clean by default and the user opts in to read them.
+    caveats_list = [b for b in (env_blocked_banner, coverage_banner, outside_spec_banner, packaging_note, thumbnail_banner) if b]
+    caveats_count = len(caveats_list)
+    if caveats_count > 0:
+        caveats_button = (
+            f'<button type="button" id="caveatsToggle" class="caveat-toggle" '
+            f'aria-expanded="false" aria-controls="caveats" aria-label="Show caveats">'
+            f'<span>Caveats</span>'
+            f'<span class="caveat-count">{caveats_count}</span>'
+            f'</button>'
+        )
+        caveats_section = (
+            '<div id="caveats" hidden>' + "".join(caveats_list) + '</div>'
+        )
+    else:
+        caveats_button = ""
+        caveats_section = ""
+
+    html_doc = f"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Validation Report &mdash; {html.escape(target.name)}</title>
+  <script>(function(){{var t=null;try{{t=localStorage.getItem('vr-theme');}}catch(e){{}}if(t==='dark'||t==='light')document.documentElement.setAttribute('data-theme',t);}})();</script>
+  <style>{CSS}</style>
+</head>
+<body>
+  <header>
+    <div class="logo">V</div>
+    <div>
+      <h1>Validation Report &mdash; {html.escape(target.name)}</h1>
+      <div class="meta">Profile: <strong>{html.escape(profile)}</strong> v{html.escape(profile_version)} &middot; Generated: {html.escape(generated)}</div>
+    </div>
+    <div class="header-actions">
+      {caveats_button}
+      <button type="button" id="themeToggle" class="theme-toggle" aria-label="Toggle theme">Dark mode</button>
+    </div>
+  </header>
+  {caveats_section}
+  <div class="summary">
+    <div class="card"><div class="label">Total assets</div><div class="value">{total}</div></div>
+    <div class="card"><div class="label">Failed assets</div><div class="value">{failed}</div></div>
+    <div class="card"><div class="label">Passed feature checks</div><div class="value">{passed_checks}</div></div>
+  </div>
+  <div class="filter"><input type="text" id="filterInput" placeholder="Filter by asset name..." /></div>
+  {asset_blocks}
+  {compliance}
+  <script>
+  (function() {{
+    var input = document.getElementById("filterInput");
+    var blocks = document.querySelectorAll(".asset-block");
+    if (input) {{
+      function filter() {{
+        var q = (input.value || "").trim().toLowerCase();
+        for (var i = 0; i < blocks.length; i++) {{
+          var name = (blocks[i].getAttribute("data-asset-name") || "");
+          blocks[i].style.display = (!q || name.indexOf(q) !== -1) ? "" : "none";
+        }}
+      }}
+      input.addEventListener("input", filter);
+      input.addEventListener("keyup", filter);
+    }}
+    var caveatsBtn = document.getElementById("caveatsToggle");
+    var caveatsBox = document.getElementById("caveats");
+    if (caveatsBtn && caveatsBox) {{
+      caveatsBtn.addEventListener("click", function() {{
+        var open = caveatsBox.hidden;
+        caveatsBox.hidden = !open;
+        caveatsBtn.setAttribute("aria-expanded", open ? "true" : "false");
+        caveatsBtn.classList.toggle("open", open);
+      }});
+    }}
+    var btn = document.getElementById("themeToggle");
+    var mq = window.matchMedia ? window.matchMedia("(prefers-color-scheme: dark)") : null;
+    function isDark() {{
+      var attr = document.documentElement.getAttribute("data-theme");
+      if (attr === "dark") return true;
+      if (attr === "light") return false;
+      return mq ? mq.matches : false;
+    }}
+    function syncLabel() {{
+      if (btn) btn.textContent = isDark() ? "Light mode" : "Dark mode";
+    }}
+    syncLabel();
+    if (mq && mq.addEventListener) mq.addEventListener("change", syncLabel);
+    if (btn) {{
+      btn.addEventListener("click", function() {{
+        var next = isDark() ? "light" : "dark";
+        document.documentElement.setAttribute("data-theme", next);
+        try {{ localStorage.setItem("vr-theme", next); }} catch(e) {{}}
+        syncLabel();
+      }});
+    }}
+  }})();
+  </script>
+</body>
+</html>
+"""
+    out = out_dir / "index.html"
+    out.write_text(html_doc, encoding="utf-8")
+    return out
+
+
+def _render_outside_spec_banner(results: list[dict]) -> str:
+    """Banner summarizing how many issues the validator reported against
+    requirements that aren't part of the loaded profile's feature set.
+    These are deliberately suppressed from the per-asset blocks and the
+    compliance footer — the report scope is the chosen spec only — so we
+    surface the count here for transparency.
+    """
+    total_issues = 0
+    unique_codes: set[str] = set()
+    affected_assets: set[str] = set()
+    for r in results:
+        if not r.get("extra_failures"):
+            continue
+        affected_assets.add(r["name"])
+        for e in r["extra_failures"]:
+            total_issues += int(e.get("count") or 0)
+            if e.get("code"):
+                unique_codes.add(e["code"])
+    if total_issues == 0:
+        return ""
+    return f'''
+<div class="outside-spec-banner">
+  <strong>Out-of-spec issues hidden.</strong> The validator reported
+  <strong>{total_issues}</strong> issue(s) against
+  <strong>{len(unique_codes)}</strong> requirement code(s) that aren\'t
+  part of this profile\'s feature set, across
+  <strong>{len(affected_assets)}</strong> asset(s). These are not listed
+  in the report — the displayed pass/fail is scoped to the loaded profile
+  only. See <code>PROBLEMS.md</code> for why this filter exists.
+</div>
+'''
+
+
+def _render_coverage_banner(coverage: dict | None) -> str:
+    """Banner shown when the loaded profile has fewer features than its
+    `profiles.toml` entry declares. The validator silently drops feature
+    entries whose ID + version aren't in the registry, which can leave a
+    profile reporting against a tiny subset of what it claims to check.
+    See PROBLEMS.md P1.
+    """
+    if not coverage or coverage.get("declared") is None:
+        return ""
+    missing = coverage.get("missing") or []
+    if not missing:
+        return ""
+    declared = coverage["declared"]
+    loaded = coverage["loaded"]
+    missing_items = "".join(
+        f'<li><code>{html.escape(m["id"])}</code> '
+        f'<span class="muted">v{html.escape(m["version"])}</span></li>'
+        for m in missing
+    )
+    return f'''
+<div class="coverage-banner">
+  <strong>Coverage gap.</strong> This profile declares <strong>{declared}</strong> features
+  in <code>profiles.toml</code> but the validator loaded only <strong>{loaded}</strong>.
+  The remaining {len(missing)} were silently dropped because their ID + version
+  isn\'t registered in the foundation specs. The pass/fail numbers below reflect
+  only the loaded set — the dropped features were <em>not</em> checked.
+  See <code>PROBLEMS.md</code> P1 for root cause and fix path.
+  <details><summary>Dropped feature IDs ({len(missing)})</summary>
+  <ul>{missing_items}</ul></details>
+</div>
+'''
+
+
+def _render_env_blocked_banner(results: list[dict]) -> str:
+    """Banner shown when validate.py's P2 filter dropped env-blocked issues.
+
+    Aggregates per-asset env_blocked counts so the user sees both that a
+    suppression happened and roughly how much was suppressed. See PROBLEMS.md P2.
+    """
+    physx_total = 0
+    mdl_total = 0
+    for r in results:
+        eb = r.get("env_blocked") or {}
+        physx_total += int(eb.get("physxschema_unavailable") or 0)
+        mdl_total += int(eb.get("omnipbr_unresolved") or 0)
+    if not (physx_total or mdl_total):
+        return ""
+    parts = []
+    if physx_total:
+        parts.append(
+            f'<strong>{physx_total}</strong> PhysX-rule errors '
+            f'(<code>PhysxSchema is not available in this environment</code>)'
+        )
+    if mdl_total:
+        parts.append(
+            f'<strong>{mdl_total}</strong> stock MDL-reference failures '
+            f'(<code>OmniPBR.mdl</code> not resolvable outside Kit)'
+        )
+    return f'''
+<div class="coverage-banner">
+  <strong>Environment-blocked checks suppressed.</strong>
+  This run dropped {" and ".join(parts)} because the active Python venv has
+  <code>usd-core</code> but not the Kit-bundled <code>PhysxSchema</code> /
+  Kit MDL search path. These checks couldn\'t produce useful results here,
+  so they would otherwise have inflated the issue count without telling you
+  anything about the asset. Pass/fail below reflects only checks that ran
+  meaningfully. See <code>PROBLEMS.md</code> P2 for root cause and fix path.
+</div>
+'''
+
+
+def _render_thumbnail_banner(provenance: list[dict], target: Path | None = None) -> str:
+    """Banner explaining where the asset thumbnails came from (since they
+    weren't produced by this run's packaging step)."""
+    present = [p for p in provenance if p.get("present")]
+    if not present:
+        return ""
+    items = "".join(
+        f'<li><code>{html.escape(p["rel"])}</code> &mdash; copied from <code>{html.escape(_relativize_msg(p.get("copied_from",""), target))}</code></li>'
+        for p in present
+    )
+    return f'''
+<div class="thumbnail-banner">
+  <strong>Asset thumbnails — sourced externally.</strong>
+  These tiles were copied into this report\'s <code>images/</code> directory from
+  per-asset spec paths (<code>&lt;asset_dir&gt;/.thumbs/256x256/&lt;filename&gt;.png</code>) populated
+  earlier from NVIDIA\'s Isaac 6.0 content S3 bucket
+  (<code>Assets/Isaac/6.0/Isaac/Robots/Yaskawa/Motoman Next/...</code>).
+  They are <strong>not</strong> the output of this run\'s packaging step;
+  the customer\'s pipeline should generate authoritative thumbnails before the
+  validation reports them as spec-compliant.
+  <details><summary>Per-tile source ({len(present)} of {len(provenance)})</summary>
+  <ul>{items}</ul></details>
+</div>
+'''
+
+
+def _render_asset_block(r: dict, doc_url, thumb_rel_by_asset: dict | None = None,
+                        target: Path | None = None) -> str:
+    name = r["name"]
+    rel = r.get("rel_path") or r.get("path", "")
+    affected = r.get("affected_prims", [])
+    failed = r.get("failed_features", [])
+    passed = r.get("passed_features", [])
+
+    if affected:
+        prims_html = (
+            '<div class="affected-prims"><span class="label">Affected prims:</span>'
+            '<ul class="prim-list-inline">'
+            + "".join(f"<li>{html.escape(p)}</li>" for p in affected)
+            + "</ul></div>"
+        )
+    else:
+        prims_html = ""
+
+    def _feature_link(rel_path: str | None) -> str:
+        """Inline 'View feature doc.' link — empty string when no doc available."""
+        url = doc_url(rel_path)
+        if not url:
+            return ''
+        return f' <a class="docref" href="{html.escape(url)}" target="_blank" rel="noopener">View feature doc.</a>'
+
+    def _capability_link(rel_path: str | None) -> str:
+        """Inline 'View capability doc' link — empty string when no doc available."""
+        url = doc_url(rel_path)
+        if not url:
+            return ''
+        return f' <a class="docref" href="{html.escape(url)}" target="_blank" rel="noopener">View capability doc</a>'
+
+    if failed:
+        items = []
+        for f in failed:
+            req_paths = f.get("requirement_paths") or {}
+            feat_link = _feature_link(f.get("path"))
+            codes_parts = []
+            for c in f.get("failed_codes", []):
+                codes_parts.append(
+                    f'<span class="code">{html.escape(c)}</span>'
+                    f'{_capability_link(req_paths.get(c))}'
+                )
+            items.append(
+                f'<li><strong class="feat-id">{html.escape(f["id"])}</strong>'
+                f'{feat_link} '
+                + " ".join(codes_parts)
+                + '</li>'
+            )
+        failed_html = "<ul>" + "".join(items) + "</ul>"
+    else:
+        failed_html = '<p class="muted" style="margin:0">None</p>'
+
+    if passed:
+        # Passed features render as plain IDs — no doc link, matching the
+        # reference dashboard. Users only need quick access to docs when
+        # something failed.
+        items = [
+            f'<li><strong class="feat-id">{html.escape(f["id"])}</strong></li>'
+            for f in passed
+        ]
+        passed_html = "<ul>" + "".join(items) + "</ul>"
+    else:
+        passed_html = '<p class="muted" style="margin:0">None</p>'
+
+    thumb_rel = (thumb_rel_by_asset or {}).get(name)
+    if thumb_rel:
+        thumb_html = (
+            f'<div class="asset-thumb-wrap">'
+            f'<img class="asset-thumb" src="{html.escape(thumb_rel)}" alt="{html.escape(name)} thumbnail" />'
+            f'</div>'
+        )
+    else:
+        thumb_html = (
+            '<div class="asset-thumb-wrap">'
+            '<div class="asset-thumb asset-thumb-missing" aria-label="no thumbnail">'
+            '<span>missing image</span>'
+            '</div></div>'
+        )
+
+    # `extra_failures` (issues against requirements outside the loaded
+    # profile) are intentionally NOT rendered per-asset. They get summarized
+    # as a count in the Caveats panel; the report scope is the chosen
+    # profile only.
+    extras_html = ""
+
+    return f"""
+<div class="asset-block" data-asset-name="{html.escape(name.lower())}">
+  {thumb_html}
+  <div class="asset-body">
+    <h2>{html.escape(name)}</h2>
+    <div class="path">{html.escape(rel)}</div>
+    {prims_html}
+    <section class="failed-features">
+      <h3>Failed features</h3>
+      {failed_html}
+    </section>
+    <section class="passed-features">
+      <h3>Passed features</h3>
+      {passed_html}
+    </section>{extras_html}
+  </div>
+</div>"""
+
+
+def _render_compliance(results: list[dict], doc_url=None, target: Path | None = None) -> str:
+    """Footer listing every in-profile requirement code that failed, with its
+    short message and (when available) a link to the foundation spec doc
+    that defines it. Codes outside the loaded profile are NOT listed here —
+    the report scope is the chosen spec only; out-of-spec failure counts
+    surface in the Caveats panel instead. Codes without a `path` get a
+    "(no spec source)" tag so the accountability gap is visible."""
+    # Build the set of in-profile failure codes from `failed_features`.
+    # Anything not in this set is an "extra" outside the loaded profile and
+    # is intentionally suppressed from the per-asset and footer views.
+    profile_failure_codes: set[str] = set()
+    for r in results:
+        for ff in r.get("failed_features", []):
+            profile_failure_codes.update(ff.get("failed_codes", []))
+    code_to_entry: dict[str, dict] = {}
+    for r in results:
+        for issue in r.get("issues", []):
+            if issue["severity"] not in ("failure", "error"):
+                continue
+            code = issue.get("code") or "UNKNOWN"
+            if code not in profile_failure_codes:
+                continue
+            if code not in code_to_entry:
+                code_to_entry[code] = {
+                    "msg": issue.get("msg", ""),
+                    "path": issue.get("path"),
+                }
+    if not code_to_entry:
+        return ""
+
+    items_html_parts: list[str] = []
+    accounted = 0
+    for code, e in sorted(code_to_entry.items()):
+        url = doc_url(e["path"]) if doc_url else None
+        if url:
+            code_html = f'<a class="code" href="{html.escape(url)}" target="_blank" rel="noopener">{html.escape(code)}</a>'
+            accounted += 1
+            no_spec_tag = ""
+        else:
+            code_html = f'<span class="code">{html.escape(code)}</span>'
+            no_spec_tag = ' <span class="no-spec">(no spec source)</span>'
+        msg = _relativize_msg(e["msg"], target)
+        items_html_parts.append(
+            f'<li>{code_html}: {html.escape(msg) if msg else "No guidance available."}{no_spec_tag}</li>'
+        )
+    items_html = "".join(items_html_parts)
+    coverage = (
+        f'<p class="muted">{accounted} of {len(code_to_entry)} requirement '
+        f'code(s) link to a foundation spec source. The rest are flagged '
+        f'<em>(no spec source)</em>.</p>'
+    )
+    return f"""
+<section class="compliance">
+  <h2>How to comply with failed requirements</h2>
+  <p class="muted">Each requirement code below is shown with the first message recorded for it.</p>
+  {coverage}
+  <ul class="compliance-list">{items_html}</ul>
+</section>"""