Initial Space scaffold from simready-oem-library-pm@e82c2b6

Dockerfile

@@ -0,0 +1,59 @@
+# SimReady Validator — HuggingFace Space image
+#
+# Phase-3 of the PRD: validation runs where the dataset lives. The Space
+# downloads a target dataset via huggingface_hub, runs the bundled
+# simready-report validator with `--no-use-kit` (no Isaac Sim on HF
+# hardware), and writes the verdict back to the dataset as a PR.
+#
+# Image strategy: pre-bake all heavy deps (usd-core, omni.asset_validator,
+# simready-validate) and the simready-foundation specs checkout into the
+# image so cold-start is fast — the per-validation cost is just the
+# dataset download + USD parsing, not pip resolution.
+
+FROM python:3.11-slim
+
+# Base build deps. usd-core ships wheels for x86_64 so we don't need
+# build-essential, but git is required to clone simready-foundation at
+# build time and rsync is handy for the dashboard `_static/` mirror.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git curl ca-certificates rsync \
+    && rm -rf /var/lib/apt/lists/*
+
+# HF Spaces run as a non-root user (UID 1000). Match it so the volume
+# mounts are writable without permission gymnastics.
+ARG USER=appuser
+RUN useradd -m -u 1000 ${USER}
+
+WORKDIR /home/${USER}/app
+
+# Python deps first so they layer-cache independently of the validator
+# code. Pinned to the same versions install-simready-sdk.sh uses on the
+# DGXC runner (single source of truth for "what runs the validator").
+COPY tools/hf_space/requirements.txt ./requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Foundation specs: the validator wants SIMREADY_FOUNDATIONS_PATH to
+# point at a checkout. Pinned tag avoids surprise spec churn between
+# Space builds. Bump the tag deliberately when foundation rules change.
+ENV SIMREADY_FOUNDATIONS_PATH=/opt/simready_foundations
+RUN git clone --depth 1 https://github.com/NVIDIA/simready-foundation \
+        ${SIMREADY_FOUNDATIONS_PATH} \
+    && chown -R ${USER}:${USER} ${SIMREADY_FOUNDATIONS_PATH}
+
+# Copy the bundled validator (the same code our DGXC runner uses) and
+# the Space's own entry points. Keep the in-repo path so the validator's
+# relative imports (report.py, external_deps.py) still resolve.
+COPY tools/validation /home/${USER}/app/tools/validation
+COPY tools/hf_space/app.py     ./app.py
+COPY tools/hf_space/runner.py  ./runner.py
+RUN chown -R ${USER}:${USER} /home/${USER}/app
+
+USER ${USER}
+
+# HF Spaces with the Docker SDK serve whatever listens on $PORT
+# (default 7860). Gradio honors GRADIO_SERVER_PORT.
+ENV GRADIO_SERVER_NAME=0.0.0.0
+ENV GRADIO_SERVER_PORT=7860
+EXPOSE 7860
+
+CMD ["python", "app.py"]

tools/hf_space/.gitignore

@@ -0,0 +1,6 @@
+# Local artifacts when iterating on the Space outside Docker.
+__pycache__/
+*.pyc
+.gradio/
+gradio_cached_examples/
+flagged/

tools/hf_space/Dockerfile

@@ -0,0 +1,59 @@
+# SimReady Validator — HuggingFace Space image
+#
+# Phase-3 of the PRD: validation runs where the dataset lives. The Space
+# downloads a target dataset via huggingface_hub, runs the bundled
+# simready-report validator with `--no-use-kit` (no Isaac Sim on HF
+# hardware), and writes the verdict back to the dataset as a PR.
+#
+# Image strategy: pre-bake all heavy deps (usd-core, omni.asset_validator,
+# simready-validate) and the simready-foundation specs checkout into the
+# image so cold-start is fast — the per-validation cost is just the
+# dataset download + USD parsing, not pip resolution.
+
+FROM python:3.11-slim
+
+# Base build deps. usd-core ships wheels for x86_64 so we don't need
+# build-essential, but git is required to clone simready-foundation at
+# build time and rsync is handy for the dashboard `_static/` mirror.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git curl ca-certificates rsync \
+    && rm -rf /var/lib/apt/lists/*
+
+# HF Spaces run as a non-root user (UID 1000). Match it so the volume
+# mounts are writable without permission gymnastics.
+ARG USER=appuser
+RUN useradd -m -u 1000 ${USER}
+
+WORKDIR /home/${USER}/app
+
+# Python deps first so they layer-cache independently of the validator
+# code. Pinned to the same versions install-simready-sdk.sh uses on the
+# DGXC runner (single source of truth for "what runs the validator").
+COPY tools/hf_space/requirements.txt ./requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Foundation specs: the validator wants SIMREADY_FOUNDATIONS_PATH to
+# point at a checkout. Pinned tag avoids surprise spec churn between
+# Space builds. Bump the tag deliberately when foundation rules change.
+ENV SIMREADY_FOUNDATIONS_PATH=/opt/simready_foundations
+RUN git clone --depth 1 https://github.com/NVIDIA/simready-foundation \
+        ${SIMREADY_FOUNDATIONS_PATH} \
+    && chown -R ${USER}:${USER} ${SIMREADY_FOUNDATIONS_PATH}
+
+# Copy the bundled validator (the same code our DGXC runner uses) and
+# the Space's own entry points. Keep the in-repo path so the validator's
+# relative imports (report.py, external_deps.py) still resolve.
+COPY tools/validation /home/${USER}/app/tools/validation
+COPY tools/hf_space/app.py     ./app.py
+COPY tools/hf_space/runner.py  ./runner.py
+RUN chown -R ${USER}:${USER} /home/${USER}/app
+
+USER ${USER}
+
+# HF Spaces with the Docker SDK serve whatever listens on $PORT
+# (default 7860). Gradio honors GRADIO_SERVER_PORT.
+ENV GRADIO_SERVER_NAME=0.0.0.0
+ENV GRADIO_SERVER_PORT=7860
+EXPOSE 7860
+
+CMD ["python", "app.py"]

tools/hf_space/README.md

@@ -0,0 +1,178 @@
+# SimReady Validator — HuggingFace Space (Phase-3 Spike)
+
+This directory scaffolds an HF Space that runs the bundled
+[`simready-report`](../validation/plugins/simready-report/) validator
+against any HF dataset, then opens a verdict PR back on the dataset.
+
+It is the **phase-3 prove-it step** described in [PRD §3](../../PRD.md):
+move validation execution to where the dataset already lives, so we stop
+paying to copy 20 GiB of customer assets onto NVIDIA-controlled
+infrastructure on every run.
+
+| | DGXC runner today | HF Space (this dir) |
+|---|---|---|
+| Asset transfer | 10–20 GiB per submission onto a 49 GiB PVC | None — `huggingface_hub.snapshot_download` reads from HF storage directly |
+| Cost model | NVIDIA pays for the runner | Customer pays for their Space's hardware hours |
+| Concurrency | Single runner, jobs serialized | One Space per dataset → scales linearly |
+| Where verdicts land | `docs/dashboard/data/status.json` in this repo | `validation/results.json` in the dataset, via PR |
+| Trigger | GitHub Actions `workflow_dispatch` | Gradio UI (spike) → HF Hub webhook (next) |
+
+The Space is **internal pilot scope**: the HF_TOKEN that opens the verdict
+PR is the Space's own secret, not the requester's. A customer-facing
+end-state would either (a) deploy one Space per partner under their org,
+or (b) keep a single multi-tenant Space and have customers pass their own
+token explicitly.
+
+---
+
+## What's here
+
+| File | Purpose |
+|---|---|
+| `Dockerfile` | Docker SDK image: pip-installs the validator runtime, clones `NVIDIA/simready-foundation` for `SIMREADY_FOUNDATIONS_PATH`, bakes in the in-repo `tools/validation/` skill |
+| `requirements.txt` | Python deps. Pinned to match `tools/runner/install-simready-sdk.sh` so verdicts are byte-for-byte reproducible across environments |
+| `app.py` | Gradio UI. Single form: dataset name + profile + version + open-PR checkbox |
+| `runner.py` | Orchestration. `run(dataset, profile, version, open_pr) → RunResult` — also the entry point a future webhook handler will call |
+
+The validator engine itself is **unchanged** — the Space invokes the same
+`tools/validation/plugins/simready-report/skills/simready-report/validate.py`
+that Windows users run locally and that the DGXC runner runs in CI.
+That's the whole point of phase 3: the verdict logic is portable; only
+the trigger surface changes.
+
+---
+
+## Hardware tier choice
+
+The validator's heavy work is USD parsing + composition-arc traversal,
+which is CPU-bound. **GPU is only required if a profile re-execs under
+Kit (Isaac Sim)**, which the Space's `--no-use-kit` flag explicitly
+disables. The validator's P2 patch drops the
+`physxschema_unavailable` / `omnipbr_unresolved` issues that the
+no-Kit path produces, so PhysX-bearing profiles still report a clean
+verdict for everything that can be checked without Kit.
+
+| Tier | $/hr | Verdict |
+|---|---|---|
+| `cpu-basic` (2 vCPU, 16 GB) | $0.03 | Marginal — small datasets OK, 50+ asset bundles will time out |
+| **`cpu-upgrade`** (8 vCPU, 32 GB) | **$0.05** | **Recommended for the spike.** Comfortable headroom; the validator's parallel worker pool actually scales here |
+| `t4-small` (1 × T4, 4 vCPU, 15 GB) | $0.40 | Only needed once we add Kit; overkill for `--no-use-kit` |
+| `a10g-small` (1 × A10G, 4 vCPU, 15 GB) | $1.05 | Future state: enables Kit-rooted PhysX/MDL rules (currently filtered out by the P2 patch) |
+
+Set the tier in the Space's **Settings → Hardware** page (or in
+`README.md` frontmatter when the Space repo is created — see Deploy).
+
+---
+
+## Deploy
+
+The Space is **not deployed yet** — this is a scaffold living in the
+internal repo. To stand it up:
+
+### 1. Create the Space `[BROWSER]`
+
+1. Sign in at https://huggingface.co with an account that has write
+   access to wherever the Space will live (an NVIDIA org for the
+   internal pilot).
+2. New → Space.
+3. Name: `simready-validator` (or any name).
+4. SDK: **Docker**.
+5. Hardware: **CPU upgrade** (~$0.05/hr) for the spike.
+6. Visibility: **Private** while internal-pilot.
+
+### 2. Set the HF_TOKEN secret `[BROWSER]`
+
+The Space needs a write-scoped token to open the verdict PR on customer
+datasets.
+
+1. https://huggingface.co/settings/tokens → New token → **Write** scope.
+2. Space → Settings → Variables and secrets → New secret.
+3. Name: `HF_TOKEN`. Value: paste the token.
+
+Tokens are not exposed in the build log. The `runner.py` code reads it
+via `os.environ["HF_TOKEN"]` (with `HUGGING_FACE_HUB_TOKEN` as a
+fallback for compatibility with the HF SDK's standard env name).
+
+### 3. Push the code `[LOCAL]`
+
+The Space is a git repo of its own. From this checkout:
+
+```bash
+# Replace <space-name> with the Space you created (e.g. nvidia/simready-validator)
+hf auth login   # one-time
+git clone https://huggingface.co/spaces/<space-name> /tmp/space
+cp -r tools/hf_space/* /tmp/space/
+# Important: the Dockerfile COPYs tools/validation/ from the repo root,
+# so we have to vendor that subtree into the Space repo too.
+mkdir -p /tmp/space/tools
+cp -r tools/validation /tmp/space/tools/
+cd /tmp/space
+git add .
+git commit -m "Initial Space scaffold from simready-oem-library-pm@main"
+git push
+```
+
+The Space will start building automatically. First build takes ~5 min
+(usd-core + omniverse-asset-validator wheels + the foundation clone).
+Subsequent builds reuse Docker layer cache and finish in ~1 min if only
+`app.py` or `runner.py` changed.
+
+### 4. Smoke-test `[BROWSER]`
+
+Open the Space's URL. Enter a known-good dataset (the foundation
+clone's bundled examples work well — point at something small like a
+single-asset dataset first), pick **Robot-Body-Runnable**, leave
+**Open PR** unchecked, click **Validate**. Watch the log stream.
+
+Expected output ends with:
+
+```
+  PASS: 1/1 assets passed
+```
+
+…and a downloadable `index.html` report.
+
+If the verdict makes sense, re-run with **Open PR** checked against a
+dataset you have write access to. A new PR appears on the dataset under
+`https://huggingface.co/datasets/<dataset>/discussions` with the
+verdict body + the `validation/` subtree.
+
+---
+
+## What this spike intentionally does NOT do
+
+To stay scoped to "prove the engine works on HF":
+
+- **No HF Hub webhook.** Triggering is Gradio-only. Phase 3.2 wires
+  `https://<space>/api/run` to `dataset.commit.push` events.
+- **No status callback into this repo.** The DGXC dashboard's
+  `hf-watch.yml` already polls dataset commits — once the Space lands
+  verdicts as `validation/results.json` on the dataset, the existing
+  watcher picks them up. No new integration needed.
+- **No Kit re-exec.** Profiles requiring PhysX/MDL rules currently
+  report partial verdicts (the P2 patch drops env-blocked rules). A
+  future iteration with an `a10g-small` tier + Isaac Sim wheels in the
+  Dockerfile unlocks these.
+- **No multi-tenant token isolation.** The Space's own `HF_TOKEN` opens
+  every PR. Fine for internal pilot; needs rework before exposing the
+  Space outside NVIDIA.
+
+These are tracked in [PRD §7 — roadmap](../../PRD.md).
+
+---
+
+## Cutover criteria (when do we retire the DGXC runner?)
+
+Stop using `hf-validate.yml` once **all three** are true:
+
+1. The Space verdict matches the DGXC verdict on the same dataset for
+   the top three onboarded clients (imagineio kitchens, plus two TBD).
+   Byte-for-byte equality on `results.json` is the bar.
+2. The HF Hub webhook handler (phase 3.2) is in place and a customer
+   can open a dataset PR and see a verdict comment without anyone at
+   NVIDIA pressing a button.
+3. The PRD §7 roadmap items 3.3 (auto-merge on pass) and 3.4 (block-on-fail
+   gate at the GitHub side) are wired through, so the GitHub coordinator
+   only deals with state — never validation.
+
+Until then both paths coexist; the DGXC runner is the source of truth.

tools/hf_space/app.py

@@ -0,0 +1,108 @@
+"""SimReady Validator — Gradio UI for the HuggingFace Space.
+
+Manual-trigger surface for the spike. A future webhook handler (HF Hub
+webhook → `/api/run`) reuses `runner.run()` directly without the UI.
+
+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 os
+from pathlib import Path
+
+import gradio as gr
+
+from runner import run as run_validator
+
+
+PROFILE_CHOICES = [
+    "Robot-Body-Runnable",
+    "Robot-Body-Physx",
+    "Robot-Body-Isaac",
+    "Prop-Robotics-Physx",
+    "Prop-Robotics-Isaac",
+    "Prop-Static",
+]
+DEFAULT_PROFILE = "Robot-Body-Runnable"
+DEFAULT_VERSION = "1.0.0"
+
+
+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,
+    )
+
+
+with gr.Blocks(title="SimReady Validator") as demo:
+    gr.Markdown(
+        "# SimReady Validator\n"
+        "Validate a HuggingFace dataset against a SimReady profile. "
+        "Reads the dataset directly from HF storage — no copy onto NVIDIA "
+        "infrastructure. 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)
+
+    run_btn.click(
+        fn=_run_streaming,
+        inputs=[dataset, profile, version, open_pr],
+        outputs=[log_box, status_md, summary_box, report_link],
+    )
+
+
+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/requirements.txt

@@ -0,0 +1,12 @@
+# Runtime deps for the SimReady validator on HuggingFace Spaces.
+# Match the versions install-simready-sdk.sh pins on the DGXC runner so
+# verdicts are byte-for-byte reproducible across environments.
+
+gradio>=4.0
+huggingface_hub>=0.34
+
+# Validator runtime
+usd-core
+omniverse-asset-validator
+markdown-it-py
+simready-validate>=2026.4.8

tools/hf_space/runner.py

@@ -0,0 +1,279 @@
+"""Orchestrator: dataset name → validator → verdict PR on the dataset.
+
+Phase-3 of the PRD. Same flow the DGXC `tools/hf_watch/validate.py`
+performs, minus:
+  - the Claude Code subprocess wrapper (we call the validator directly,
+    keeping the agentic-decision layer for our internal coordinator path)
+  - the status.json patching (the HF Space is per-dataset; the
+    coordinator dashboard polls verdicts back via its existing watcher)
+  - the GitHub commit step (we open an HF Dataset PR instead)
+
+The validator engine itself is unchanged — it's the same simready-report
+skill that runs on Windows, on DGXC, and now here.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterator
+
+from huggingface_hub import HfApi, snapshot_download
+
+VALIDATOR = (
+    Path(__file__).resolve().parent
+    / "tools" / "validation" / "plugins" / "simready-report"
+    / "skills" / "simready-report" / "validate.py"
+)
+
+# Same exclude set the DGXC path uses. HF datasets ship a lot of bulk the
+# validator doesn't open; skipping shrinks downloads from tens-of-GB to
+# hundreds-of-MB on assets like nvidia/PhysicalAI-SimReady-Warehouse-01.
+HF_DOWNLOAD_EXCLUDES = (
+    ".thumbs/*",
+    "images/*",
+    "*_renders/*", "renders/*",
+    "*.mp4", "*.mov", "*.webm",
+    "*.jpg", "*.jpeg", "*.png", "*.gif", "*.tiff", "*.tif",
+    "*.zip", "*.tar", "*.tgz",
+)
+USD_EXTS = (".usd", ".usda", ".usdc", ".usdz")
+
+
+@dataclasses.dataclass
+class RunResult:
+    dataset: str
+    profile: str
+    version: str
+    status: str         # "pass" | "warn" | "fail" | "error"
+    summary: str        # one-line human-readable digest
+    results_json: dict  # the validator's results.json contents
+    report_path: Path   # local path to the HTML report tree
+    pr_url: str | None  # discussion URL when --open-pr was used
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _wrap_layout_for_validator(downloaded: Path, work: Path) -> Path:
+    """Adapt HF's flat dataset layout to the validator's expected shape.
+
+    The validator iterates *subdirectories* of its target and finds the
+    interface USD inside each. HF datasets ship flat — root USD plus
+    Geometry/Materials/SubLayers — so the unmodified validator finds
+    zero assets when pointed at the download root.
+
+    If there's a root-level USD, wrap the download in a parent dir so the
+    validator sees exactly one asset (the download itself). If the
+    download already has subdirs with their own interface USDs (rare),
+    pass it through.
+    """
+    root_usds = [p for ext in USD_EXTS for p in downloaded.glob(f"*{ext}")]
+    subdir_with_usds = 0
+    for sub in downloaded.iterdir():
+        if not sub.is_dir() or sub.name.startswith((".", "_")):
+            continue
+        if any(sub.glob(f"*{ext}") for ext in USD_EXTS):
+            subdir_with_usds += 1
+            break
+
+    if subdir_with_usds and not root_usds:
+        return downloaded  # already SimReady-shaped
+
+    target_parent = work / "target"
+    target_parent.mkdir(parents=True, exist_ok=True)
+    asset_dir = target_parent / downloaded.name
+    if asset_dir.exists():
+        shutil.rmtree(asset_dir)
+    shutil.move(str(downloaded), str(asset_dir))
+    return target_parent
+
+
+def _summarize(results_json: dict) -> tuple[str, str]:
+    """Return (status, one-line summary)."""
+    counts = {"error": 0, "failure": 0, "warning": 0}
+    total = len(results_json.get("results", []))
+    failed = 0
+    for asset in results_json.get("results", []):
+        if not asset.get("passed"):
+            failed += 1
+        for issue in asset.get("issues", []):
+            sev = (issue.get("severity") or "").lower()
+            if sev in counts:
+                counts[sev] += 1
+    if counts["error"] or counts["failure"]:
+        status = "fail"
+    elif counts["warning"]:
+        status = "warn"
+    elif total > 0:
+        status = "pass"
+    else:
+        status = "warn"
+    parts = [f"{total - failed}/{total} assets passed"]
+    parts += [f"{k}={v}" for k, v in counts.items() if v]
+    coverage = results_json.get("profile_coverage") or {}
+    if coverage.get("missing"):
+        parts.append(f"coverage {coverage.get('loaded')}/{coverage.get('declared')} features")
+    return status, " · ".join(parts)
+
+
+def _open_verdict_pr(
+    api: HfApi, dataset: str, results_path: Path, report_dir: Path,
+    profile: str, version: str, status: str, summary: str,
+) -> str | None:
+    """Upload `validation/results.json` + `validation/report/` to the dataset
+    as a PR. Returns the discussion URL.
+
+    Why PR rather than commit-to-main: the dataset owner reviews the
+    verdict like any other change. The HF Hub PR flow is exactly the
+    surface the production end-state assumes — see PRD §3.
+    """
+    import io
+
+    pr_branch = f"simready-validate/{profile}-v{version}-{_now().replace(':', '-')}"
+    body_md = (
+        f"### SimReady validation\n\n"
+        f"- **Profile**: `{profile}` v{version}\n"
+        f"- **Status**: **{status.upper()}**\n"
+        f"- **Summary**: {summary}\n"
+        f"- **Generated**: {_now()}\n\n"
+        f"Run by the SimReady Validator HF Space. The full HTML report "
+        f"is in `validation/report/index.html`; machine-readable "
+        f"results in `validation/results.json`.\n"
+    )
+
+    # Stage everything that should land in the dataset under a single
+    # tree we can iterate. `validation/results.json` plus the entire
+    # `validation/report/` directory.
+    additions: list[tuple[str, bytes]] = []
+    additions.append(("validation/results.json", results_path.read_bytes()))
+    for path in report_dir.rglob("*"):
+        if path.is_file():
+            rel = path.relative_to(report_dir.parent)  # keep `report/...`
+            additions.append((f"validation/{rel.as_posix()}", path.read_bytes()))
+
+    from huggingface_hub import CommitOperationAdd
+    operations = [
+        CommitOperationAdd(path_in_repo=p, path_or_fileobj=io.BytesIO(b))
+        for p, b in additions
+    ]
+    commit = api.create_commit(
+        repo_id=dataset, repo_type="dataset",
+        operations=operations,
+        commit_message=f"simready-validate: {profile} v{version} → {status}",
+        create_pr=True,
+    )
+    # `create_pr=True` returns the PR's revision; the discussion URL is
+    # derivable from it. HfApi exposes the field but its key name has
+    # varied across versions — fall back gracefully.
+    return getattr(commit, "pr_url", None) or getattr(commit, "discussion_url", None)
+
+
+def run(
+    dataset: str,
+    profile: str = "Robot-Body-Runnable",
+    version: str = "1.0.0",
+    open_pr: bool = False,
+    hf_token: str | None = None,
+    log: Iterator[str] | None = None,
+) -> RunResult:
+    """Validate a single HF dataset. Yields log lines via the `log` callable.
+
+    The Space's Gradio UI passes a callable that streams lines to the
+    output panel; the test harness can pass `print` directly.
+    """
+    out = log or (lambda s: print(s, flush=True))
+    out(f"[{_now()}] validating dataset={dataset} profile={profile} v{version}")
+
+    token = hf_token or os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+    api = HfApi(token=token)
+
+    with tempfile.TemporaryDirectory(prefix=f"hfsp-{dataset.replace('/', '_')}-") as td:
+        work = Path(td)
+        out(f"  workdir: {work}")
+
+        # 1. Materialize. `snapshot_download` writes into a deterministic
+        #    subdir; we hold a stable reference for the layout-wrap step.
+        local = work / "raw"
+        local.mkdir(parents=True, exist_ok=True)
+        out(f"  $ snapshot_download {dataset} ignore_patterns={list(HF_DOWNLOAD_EXCLUDES)}")
+        snapshot_download(
+            repo_id=dataset,
+            repo_type="dataset",
+            local_dir=str(local),
+            ignore_patterns=list(HF_DOWNLOAD_EXCLUDES),
+            token=token,
+        )
+
+        # 2. Wrap layout. The validator expects parent-of-asset-dirs; HF
+        #    datasets land flat.
+        target = _wrap_layout_for_validator(local, work)
+        out(f"  validator target: {target}")
+
+        # 3. Run the validator. `--no-use-kit` skips the Isaac Sim re-exec
+        #    (no Kit on HF hardware); the P2 patch inside the validator
+        #    drops physxschema-unavailable issues so the asset isn't
+        #    penalized for the missing runtime.
+        out_dir = work / "out"
+        out_dir.mkdir(parents=True, exist_ok=True)
+        cmd = [
+            sys.executable, str(VALIDATOR),
+            str(target),
+            "--profile", profile,
+            "--version", version,
+            "--output", str(out_dir),
+            "--no-use-kit",
+        ]
+        out(f"  $ {shlex.join(cmd)}")
+        rc = subprocess.call(cmd)
+        results_path = out_dir / "results.json"
+        if rc != 0 and not results_path.exists():
+            return RunResult(
+                dataset=dataset, profile=profile, version=version,
+                status="error",
+                summary=f"validator exited {rc}; no results.json produced",
+                results_json={}, report_path=out_dir, pr_url=None,
+            )
+        results_json = json.loads(results_path.read_text(encoding="utf-8"))
+        status, summary = _summarize(results_json)
+        out(f"  {status.upper()}: {summary}")
+
+        # 4. (Optional) open the verdict PR on the dataset.
+        pr_url = None
+        if open_pr:
+            if not token:
+                out("  ! HF_TOKEN missing; cannot open PR")
+            else:
+                try:
+                    pr_url = _open_verdict_pr(
+                        api=api, dataset=dataset,
+                        results_path=results_path, report_dir=out_dir,
+                        profile=profile, version=version,
+                        status=status, summary=summary,
+                    )
+                    out(f"  PR opened: {pr_url}")
+                except Exception as e:
+                    out(f"  ! PR creation failed: {type(e).__name__}: {e}")
+
+        # 5. Copy the report tree OUT of the tempdir so the caller can
+        #    keep displaying it after this function returns and the
+        #    tempdir is cleaned.
+        persisted = Path("/tmp") / f"hfsp-report-{dataset.replace('/', '_')}"
+        if persisted.exists():
+            shutil.rmtree(persisted)
+        shutil.copytree(out_dir, persisted)
+
+        return RunResult(
+            dataset=dataset, profile=profile, version=version,
+            status=status, summary=summary,
+            results_json=results_json,
+            report_path=persisted, pr_url=pr_url,
+        )

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

@@ -0,0 +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)."
+    }
+  ]
+}

tools/validation/PROBLEMS.md

@@ -0,0 +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.

tools/validation/README.md

@@ -0,0 +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`.

tools/validation/UPSTREAM.md

@@ -0,0 +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.

tools/validation/_sync.sh

@@ -0,0 +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

tools/validation/bootstrap.ps1

@@ -0,0 +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

tools/validation/playbooks/foundations-deviations.md

@@ -0,0 +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" |

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

@@ -0,0 +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"
+}

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

@@ -0,0 +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`.

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

@@ -0,0 +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())

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

@@ -0,0 +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`

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

@@ -0,0 +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

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

@@ -0,0 +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 (layer.realPath or "")
+
+                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

@@ -0,0 +1,850 @@
+"""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
+        _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()
+        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>"""

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

@@ -0,0 +1,1243 @@
+"""SimReady asset validator — entry point for the /simready-report skill.
+
+Usage:
+    python validate.py <target_dir> [--profile NAME] [--version X.Y.Z] [--output DIR]
+
+Discovers every USD file under <target_dir>, validates each against the named
+profile via omni.asset_validator, walks composition arcs for external deps,
+and writes the dashboard + provenance reports into <output> (default
+<target_dir>/validation_output).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import shutil
+import sys
+import tomllib
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+SKILL_DIR = Path(__file__).resolve().parent
+
+# Profiles whose validation rules need a real Kit runtime (PhysxSchema +
+# Kit's MDL search path). Used both by the early Kit re-exec gate and by
+# the auto-default in main(). Keep these in sync.
+_PHYSX_PROFILES = frozenset({
+    "Robot-Body-Physx", "Robot-Body-Isaac", "Robot-Body-Runnable",
+    "Prop-Robotics-Physx", "Prop-Robotics-Isaac",
+})
+
+
+def _sniff_arg(argv: list[str], name: str, default: str | None = None) -> str | None:
+    """Pull `--<name> <value>` out of argv without argparse. Returns default if absent."""
+    flag = f"--{name}"
+    if flag in argv:
+        i = argv.index(flag)
+        if i + 1 < len(argv):
+            return argv[i + 1]
+    return default
+
+
+# ---- Kit re-exec gate ---------------------------------------------------
+# When --use-kit is on and we're not already inside a Kit-rooted process,
+# re-exec this script through _kit_wrapper.py using the Kit-rooted Python.
+# Must run BEFORE any pxr / omni.asset_validator import attempt below
+# (otherwise _check_bootstrap fires against the pip venv first). Argparse
+# is too heavy here — sniff sys.argv directly.
+def _maybe_reexec_under_kit() -> None:
+    if __name__ != "__main__":
+        return
+    if os.environ.get("SIMREADY_INSIDE_KIT") == "1":
+        return
+    # Explicit opt-in/out takes precedence. Otherwise auto-enable for
+    # PhysX-bearing profiles. Mirror this in main() — keep _PHYSX_PROFILES
+    # the source of truth.
+    if "--no-use-kit" in sys.argv:
+        return
+    auto = False
+    if "--use-kit" not in sys.argv:
+        profile = _sniff_arg(sys.argv, "profile", default="Robot-Body-Runnable")
+        if profile in _PHYSX_PROFILES:
+            print(f"[skill] auto-enabled --use-kit for PhysX-bearing profile "
+                  f"{profile}; pass --no-use-kit to override.", flush=True)
+            auto = True
+        else:
+            return
+    # Resolve the Kit-rooted Python.
+    kit_python = os.environ.get("SIMREADY_KIT_PYTHON") or ""
+    if not kit_python:
+        # Best-known default on this team's machines (Isaac Sim 6 source build).
+        default = r"C:\isaacsim6\_build\windows-x86_64\release\python.bat"
+        if Path(default).is_file():
+            kit_python = default
+    # Allow --kit-python <path> override (sniff without argparse).
+    if "--kit-python" in sys.argv:
+        i = sys.argv.index("--kit-python")
+        if i + 1 < len(sys.argv):
+            kit_python = sys.argv[i + 1]
+    if not kit_python or not Path(kit_python).is_file():
+        print(
+            "ERROR: --use-kit requested but no Kit-rooted Python found.\n"
+            "       Set SIMREADY_KIT_PYTHON to an Isaac Sim 6 python.bat,\n"
+            "       or pass --kit-python <path>.",
+            flush=True,
+        )
+        sys.exit(2)
+    # Drop --use-kit and --kit-python from the child's argv. The child runs
+    # validate.py via _kit_wrapper.py, which sets SIMREADY_INSIDE_KIT=1 so
+    # this gate is a no-op the second time around.
+    child_argv: list[str] = []
+    skip_next = False
+    for a in sys.argv[1:]:
+        if skip_next:
+            skip_next = False
+            continue
+        if a == "--use-kit":
+            continue
+        if a == "--kit-python":
+            skip_next = True
+            continue
+        child_argv.append(a)
+    wrapper = SKILL_DIR / "_kit_wrapper.py"
+    print(f"  --use-kit: re-exec via {kit_python}", flush=True)
+    print(f"             (SimulationApp boot — expect 10-30s of Kit startup)", flush=True)
+    import subprocess
+    rc = subprocess.call([kit_python, str(wrapper), *child_argv])
+    sys.exit(rc)
+
+
+_maybe_reexec_under_kit()
+
+
+def _find_workspace() -> Path | None:
+    """Locate the simready-playbook workspace by walking up from this script.
+
+    The workspace is identified by a `BOT.md` marker at its root. This works
+    when the skill is loaded from the cloned playbook (the historical layout
+    AND the new plugin-in-repo layout). When the plugin is installed via
+    marketplace into a user-global location, no `BOT.md` is in the ancestry,
+    so this returns None and the script falls back to CWD-anchored defaults.
+    """
+    for ancestor in SKILL_DIR.parents:
+        if (ancestor / "BOT.md").is_file():
+            return ancestor
+    return None
+
+
+WORKSPACE_ROOT = _find_workspace()
+# Reports default to <target>/.reports/<name>--<profile>/ — i.e. dropped
+# next to the assets they describe. The `.reports/` prefix starts with `.`
+# so `discover_assets` automatically skips it on subsequent runs even when
+# the report dir lives inside the target. The default is computed in main()
+# from the *pre-packaging* target so the report ends up where the user
+# pointed, not under packages/.
+DEFAULT_TARGET_DIR = (WORKSPACE_ROOT / "assets_to_validate") if WORKSPACE_ROOT else None
+# Foundation specs + SDK checkouts: env var first; otherwise sibling-of-workspace
+# fallback (the layout `bootstrap.ps1` produces). When WORKSPACE_ROOT is None,
+# only the env vars matter — there's nothing to fall back to.
+_specs_env = os.environ.get("SIMREADY_FOUNDATIONS_PATH")
+_sdk_env = os.environ.get("SIMREADY_SDK_PATH")
+SPECS_DIR = Path(_specs_env) if _specs_env else (
+    WORKSPACE_ROOT.parent / "simready_foundations" if WORKSPACE_ROOT else None
+)
+SDK_DIR = Path(_sdk_env) if _sdk_env else (
+    WORKSPACE_ROOT.parent / "simready-oem-sdk-poc" if WORKSPACE_ROOT else None
+)
+# Optional reference dashboard checkout — used only for its `_static/` (theme
+# CSS/JS/fonts) so generated doc pages match the reference look. Resolution order:
+# 1. SIMREADY_DASHBOARD_PATH env var (points at the inner `.../docs` dir or
+#    the outer `usd_validation_dashboard_final/` — both forms accepted)
+# 2. sibling-of-workspace (what bootstrap.ps1 produces)
+# 3. ~/Downloads/usd_validation_dashboard_final/usd_validation_dashboard_final/docs
+def _resolve_dashboard_docs_dir() -> Path | None:
+    env = os.environ.get("SIMREADY_DASHBOARD_PATH")
+    candidates: list[Path] = []
+    if env:
+        p = Path(env)
+        # Accept both <root>/usd_validation_dashboard_final/docs and the docs dir directly.
+        candidates += [p, p / "docs", p / "usd_validation_dashboard_final" / "docs"]
+    if WORKSPACE_ROOT:
+        candidates.append(WORKSPACE_ROOT.parent / "usd_validation_dashboard_final" / "usd_validation_dashboard_final" / "docs")
+    home = Path.home()
+    candidates.append(home / "Downloads" / "usd_validation_dashboard_final" / "usd_validation_dashboard_final" / "docs")
+    for c in candidates:
+        if c and c.is_dir() and (c / "_static").is_dir():
+            return c
+    return None
+
+
+DASHBOARD_DOCS_DIR = _resolve_dashboard_docs_dir()
+
+
+
+# Default to loading only the OAV plugin; SimReadyPlugin's entry-point
+# isn't needed because we populate the registries from on-disk paths via
+# `simready.validate.impl.loader.load_validation_implementation` (matching
+# the official simready-validate CLI). Pass `--use-plugin` to opt back in
+# to the entry-point flow (requires the simready-foundation-core editable
+# install — kept as a fallback during the GitHub migration).
+os.environ.setdefault(
+    "OMNI_ASSET_VALIDATOR_ISOLATE_ENTRYPOINTS",
+    "omni.asset_validator:DefaultPlugin",
+)
+if "--use-plugin" in sys.argv:
+    os.environ["OMNI_ASSET_VALIDATOR_ISOLATE_ENTRYPOINTS"] = (
+        "omni.asset_validator:DefaultPlugin,simready.foundation.core:SimReadyPlugin"
+    )
+os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+if SPECS_DIR and SPECS_DIR.is_dir():
+    os.environ.setdefault("SIMREADY_SPECS_PATH", str(SPECS_DIR))
+
+
+def _check_bootstrap() -> None:
+    """Verify the runtime can do its job before importing foundation modules.
+
+    What matters is that the Python imports work and the foundation specs are
+    findable; we don't care *where* they came from (sibling venv, system
+    Python, an active venv, conda, etc.). Missing pieces are reported with
+    actionable hints rather than a raw ImportError.
+    """
+    missing: list[str] = []
+    try:
+        import omni.asset_validator  # noqa: F401
+        import pxr  # noqa: F401
+        import markdown_it  # noqa: F401
+        import simready.validate.impl.loader  # noqa: F401  -- the CLI loader the default path depends on
+    except ImportError as e:
+        missing.append(
+            f"Python package not importable: {e.name or e}. "
+            f"Install runtime deps: pip install usd-core omniverse-asset-validator "
+            f"markdown-it-py 'simready-validate>=2026.4.8'."
+        )
+    if SPECS_DIR is None or not SPECS_DIR.is_dir():
+        missing.append(
+            "simready_foundations checkout not findable"
+            + (f" at {SPECS_DIR}" if SPECS_DIR else "")
+            + ". Clone github.com/NVIDIA/simready-foundation (or -staging) and set "
+            "SIMREADY_FOUNDATIONS_PATH to the checkout."
+        )
+
+    if missing:
+        print("ERROR: runtime prerequisites missing:", flush=True)
+        for m in missing:
+            print(f"  - {m}", flush=True)
+        print("", flush=True)
+        if os.environ.get("SIMREADY_INSIDE_KIT") == "1":
+            print(
+                "Running inside Kit (SIMREADY_INSIDE_KIT=1) but the validator stack "
+                "isn't installed in this Kit-rooted Python.\n"
+                f"Install once with: \"{sys.executable}\" -m pip install omniverse-asset-validator markdown-it-py "
+                "-e <foundations>/nv_core/sr_specs (and -e <sdk> if auto-packaging is needed).",
+                flush=True,
+            )
+        elif WORKSPACE_ROOT is not None:
+            bootstrap = WORKSPACE_ROOT / "bootstrap.ps1"
+            print(f"On Windows, the canned setup is: & '{bootstrap}'", flush=True)
+        print("Install the runtime deps (usd-core, omniverse-asset-validator, "
+              "markdown-it-py) into your active Python and set SIMREADY_FOUNDATIONS_PATH "
+              "(and optionally SIMREADY_SDK_PATH) to existing checkouts.", flush=True)
+        raise SystemExit(2)
+
+
+_check_bootstrap()
+
+from pxr import Usd  # noqa: E402  (deferred until _check_bootstrap verifies env)
+import omni.asset_validator as oav  # noqa: E402
+
+import report  # noqa: E402
+import external_deps  # noqa: E402
+
+
+def _patch_register_json_variant_features() -> None:
+    """LOCAL PATCH for PROBLEMS.md P1 — remove once foundations codegen is fixed.
+
+    The foundations `repo usd_profiles_codegen` tool only emits Feature
+    entries from each `.md` file's declared `Internal ID`, missing the
+    JSON variant feature definitions next to the markdown
+    (`<features>/FET_*.json`). This patch does two things:
+
+      1. Read every `FET_*.json` and register each variant in
+         `omni.asset_validator.FeatureRegistry()` (skipping ones already
+         registered by codegen).
+      2. Re-resolve every profile's feature list against the now-fuller
+         registry. Profiles are built once at plugin-load time with
+         eager feature resolution, so features added after the fact
+         never join existing Profile objects unless we mutate them
+         directly. `Profile` is a frozen dataclass but `.features` is a
+         mutable list, so we append in place.
+
+    Step 2 is what actually makes profiles like `Robot-Body-Runnable`
+    resolve their `_ROBOT_PHYSX` / `_RUNNABLE` / `_DRIVEN_JOINTS_PHYSX`
+    entries. Without it, registering features alone is invisible to
+    the validator.
+    """
+    if SPECS_DIR is None or not SPECS_DIR.is_dir():
+        return
+    features_dir = SPECS_DIR / "nv_core" / "sr_specs" / "docs" / "features"
+    profiles_toml = SPECS_DIR / "nv_core" / "sr_specs" / "docs" / "profiles" / "profiles.toml"
+    if not features_dir.is_dir() or not profiles_toml.is_file():
+        return
+
+    # Force plugin init so codegen-derived features + profiles are in
+    # their respective registries first; we additively patch on top.
+    fr = oav.FeatureRegistry()
+    pr = oav.ProfileRegistry()
+    rr = oav.RequirementsRegistry()
+    code_to_req = {r.code: r for r in rr.values() if getattr(r, "code", None)}
+
+    @dataclass(frozen=True)
+    class _PatchedFeature:
+        id: str
+        version: str
+        path: str
+        requirements: list
+
+    # ---- Step 1: register JSON variant features ----
+    added = 0
+    skipped_existing = 0
+    unresolved_codes: dict[str, list[str]] = {}
+    # Glob is intentionally permissive — JSON variant filenames in this
+    # repo use a mix of `FET_021-robot_core_isaac-0.1.0.json`,
+    # `FET_021_robot_core_runnable_0.2.0.json`, and
+    # `FET_004_base_physx-0.2.0-simulate_multi_body_phyics.json` styles.
+    # We rely on `id` + `version` from the JSON content, not the filename.
+    for jf in sorted(features_dir.glob("FET_*.json")):
+        try:
+            data = json.loads(jf.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+        fid = data.get("id")
+        fver = data.get("version")
+        if not fid or not fver:
+            continue
+        if fr.find(fid, fver) is not None:
+            skipped_existing += 1
+            continue
+        resolved, missing = [], []
+        for code in data.get("requirements", []):
+            if code in code_to_req:
+                resolved.append(code_to_req[code])
+            else:
+                missing.append(code)
+        if missing:
+            unresolved_codes[f"{fid} v{fver}"] = missing
+            continue
+        feat = _PatchedFeature(
+            id=fid, version=fver, path=data.get("path", ""), requirements=resolved
+        )
+        try:
+            fr.add(feat)
+            added += 1
+        except Exception:
+            pass
+
+    # ---- Step 2: re-resolve each profile's feature list ----
+    try:
+        with profiles_toml.open("rb") as fh:
+            toml_data = tomllib.load(fh)
+    except Exception:
+        toml_data = {}
+    profiles_patched = 0
+    profile_features_appended = 0
+    for profile_id, versions in toml_data.items():
+        if not isinstance(versions, dict):
+            continue
+        for ver, body in versions.items():
+            if not isinstance(body, dict) or "features" not in body:
+                continue
+            try:
+                profile = pr.find(profile_id, ver)
+            except Exception:
+                continue
+            if profile is None:
+                continue
+            existing = {(f.id, str(f.version)) for f in profile.features}
+            appended_here = 0
+            for entry in body["features"]:
+                if not isinstance(entry, dict) or len(entry) != 1:
+                    continue
+                fid, meta = next(iter(entry.items()))
+                fver_decl = str((meta or {}).get("version", ""))
+                if (fid, fver_decl) in existing:
+                    continue
+                feat = fr.find(fid, fver_decl)
+                if feat is None:
+                    continue
+                profile.features.append(feat)  # mutate the list inside the frozen dataclass
+                appended_here += 1
+            if appended_here:
+                profiles_patched += 1
+                profile_features_appended += appended_here
+
+    if added or unresolved_codes or profiles_patched:
+        msg = (
+            f"  [PATCH P1] FeatureRegistry: +{added} JSON-variant feature(s) "
+            f"({skipped_existing} already registered, "
+            f"{len(unresolved_codes)} skipped on missing requirement codes); "
+            f"ProfileRegistry: rebuilt feature lists for {profiles_patched} profile(s) "
+            f"(+{profile_features_appended} feature(s))."
+        )
+        print(msg, flush=True)
+
+
+# P1 patch is no longer applied unconditionally. It runs only when
+# --use-plugin is set (the legacy SimReadyPlugin entry-point path). The
+# default CLI-loader path populates the registry from JSON variant files
+# natively, making this patch redundant. Kept callable here so workers
+# can invoke it through _pool_init when the legacy path is selected.
+
+
+logging.basicConfig(level=logging.WARNING, format="%(levelname)s %(name)s: %(message)s")
+log = logging.getLogger("validate")
+
+USD_EXTS = (".usd", ".usda", ".usdc", ".usdz")
+SEVERITY_NAMES = {
+    oav.IssueSeverity.ERROR:   "error",
+    oav.IssueSeverity.FAILURE: "failure",
+    oav.IssueSeverity.WARNING: "warning",
+}
+
+
+def _find_simready_cli() -> str | None:
+    """Locate the `simready` CLI in a layout-agnostic way.
+
+    Order: (1) on PATH, (2) in the same bin/ or Scripts/ dir as `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 maybe_package_target(target: Path) -> Path:
+    """If `target` is a raw asset set under assets_to_validate/, run
+    `simready ingest usd` per interface file into packages/<name>/ and
+    return the packaged path. Otherwise return `target` unchanged.
+
+    A raw set is detected by the path containing `/assets_to_validate/`.
+    The packaged tree is built only if absent (idempotent). Each subfolder
+    of the raw set is treated as one asset; the interface file is the USD
+    inside it whose stem matches the folder name (case-insensitive,
+    `-`/`_` normalized), or — if there's exactly one USD — that one.
+    """
+    target_str = str(target).replace("\\", "/")
+    if "/assets_to_validate/" not in target_str:
+        return target
+
+    name = target.name
+    # Anchor the packaged tree to the workspace when present; otherwise to the
+    # parent of the assets_to_validate/ dir so the layout is preserved without
+    # requiring a workspace.
+    if WORKSPACE_ROOT is not None:
+        packaged = WORKSPACE_ROOT / "packages" / name
+    else:
+        # target is <X>/assets_to_validate/<name>; sibling-of-X for packages.
+        packaged = target.parent.parent / "packages" / name
+    packaged.mkdir(parents=True, exist_ok=True)
+
+    simready_exe = _find_simready_cli()
+    if simready_exe is None:
+        print("  WARNING: `simready` CLI not found on PATH or in the active Python's bin/ "
+              "directory. Cannot auto-package; validating the raw tree instead.", flush=True)
+        return target
+
+    import subprocess
+    print(f"  auto-package: {target} -> {packaged}", flush=True)
+    interface_files = []
+    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)
+
+    env = {**os.environ, "PYTHONIOENCODING": "utf-8", "PYTHONUTF8": "1"}
+    packaged_count = 0
+    for usd in interface_files:
+        already = packaged / usd.stem / usd.name
+        if already.is_file():
+            continue
+        cmd = [simready_exe, "ingest", "usd", str(usd),
+               "-o", str(packaged), "-p", "Robot-Body-Runnable", "--no-validate"]
+        try:
+            subprocess.run(cmd, env=env, check=True, capture_output=True, text=True, timeout=120)
+            packaged_count += 1
+        except subprocess.CalledProcessError as e:
+            print(f"  WARNING: simready ingest failed for {usd.name}: {e.stderr[-300:] if e.stderr else e}", flush=True)
+    if packaged_count:
+        print(f"  auto-package: {packaged_count} asset(s) packaged", flush=True)
+    return packaged
+
+
+def resolve_target(arg: str | None) -> Path | None:
+    """Map the user's argument to a concrete asset directory.
+
+    Rules:
+      - No arg: use the current working directory.
+      - Absolute or existing relative path: use as-is.
+      - Bare name `<name>` (no path separators): try CWD/<name>, then the
+        workspace's `assets_to_validate/<name>` as a fallback for users still
+        using the original layout.
+    """
+    if arg is None:
+        cwd = Path.cwd().resolve()
+        print(f"  target: {cwd} (cwd)", flush=True)
+        return cwd
+
+    candidate = Path(arg)
+    if candidate.is_absolute() and candidate.is_dir():
+        return candidate.resolve()
+    if candidate.is_dir():
+        return candidate.resolve()
+    # Bare name — try CWD-relative first, then the workspace's
+    # assets_to_validate/<arg> when running inside a playbook clone.
+    cwd_fallback = (Path.cwd() / arg).resolve()
+    if cwd_fallback.is_dir():
+        return cwd_fallback
+    workspace_fallback = DEFAULT_TARGET_DIR / arg if DEFAULT_TARGET_DIR else None
+    if workspace_fallback and workspace_fallback.is_dir():
+        return workspace_fallback.resolve()
+    print(f"ERROR: target dir does not exist: {arg}", flush=True)
+    print(f"       Tried: {candidate.resolve()}", flush=True)
+    print(f"       Tried: {cwd_fallback}", flush=True)
+    if workspace_fallback:
+        print(f"       Tried: {workspace_fallback}", flush=True)
+    return None
+
+
+def sanity_check_target(target: Path) -> list[str]:
+    """Refuse obviously-wrong invocations before any work happens.
+
+    Returns a list of human-readable problems. Empty list means OK.
+    Used to interrupt `/simready-report` (especially when it ran with no arg and
+    fell back to CWD) when the resolved target couldn't sensibly be an
+    asset directory.
+    """
+    problems: list[str] = []
+    target = target.resolve()
+
+    def _under(child: Path, parent: Path) -> bool:
+        try:
+            child.relative_to(parent)
+            return True
+        except ValueError:
+            return False
+
+    # Workspace-aware guards only apply when running inside a playbook clone.
+    if WORKSPACE_ROOT is not None:
+        workspace = WORKSPACE_ROOT.resolve()
+        if target == workspace:
+            problems.append(
+                f"target is the workspace root ({target}). "
+                f"cd into an asset directory or pass a path."
+            )
+        for guard in (".claude", "playbooks", "report", "_reports", "packages", "plugins"):
+            guard_path = (workspace / guard).resolve()
+            if target == guard_path or _under(target, guard_path):
+                problems.append(
+                    f"target sits under <workspace>/{guard}/ ({target}). "
+                    f"that's not an asset directory — pick a customer-asset folder."
+                )
+                break
+
+    # Refuse anything close to a drive root or user home — likely a stray cd.
+    if len(target.parts) <= 2:
+        problems.append(
+            f"target ({target}) is too high in the filesystem. "
+            f"cd into a specific asset directory before running /simready-report."
+        )
+
+    # Refuse if the target has no USDs at root and no USDs in immediate subfolders.
+    if target.is_dir():
+        root_usds = [p for ext in USD_EXTS for p in target.glob(f"*{ext}")]
+        sub_with_usds = 0
+        for sub in target.iterdir():
+            if not sub.is_dir() or sub.name.startswith((".", "_")):
+                continue
+            if any(sub.glob(f"*{ext}") for ext in USD_EXTS):
+                sub_with_usds += 1
+                if sub_with_usds >= 1:
+                    break
+        if not root_usds and sub_with_usds == 0:
+            problems.append(
+                f"no USD files found in {target} or its immediate subfolders. "
+                f"`/simready-report` expects either a single asset directory containing "
+                f"<name>.usd, or a parent directory whose subfolders each contain "
+                f"an interface USD."
+            )
+
+    return problems
+
+
+def discover_assets(root: Path, exclude: Path | None = None) -> list[Path]:
+    """Return one interface USD per top-level subdirectory of root.
+
+    Per the SimReady packaging spec, each asset lives under <root>/<name>/
+    with an interface file at <root>/<name>/<name>.usd (and sublayers under
+    configuration/). We validate only the interface file — never individual
+    config layers — per BOT.md.
+
+    Heuristic: in each top-level subfolder, take the single top-level USD if
+    there is one, otherwise the one whose stem matches the folder name.
+    """
+    found: list[Path] = []
+    for sub in sorted(root.iterdir()):
+        if not sub.is_dir() or sub.name.startswith(".") or sub.name.startswith("_"):
+            continue
+        if exclude is not None and (sub == exclude or exclude in sub.parents):
+            continue
+        if sub.name in ("validation_output", "validations", "report", "images"):
+            continue
+        usds = [p for ext in USD_EXTS for p in sub.glob(f"*{ext}")]
+        if not usds:
+            continue
+        if len(usds) == 1:
+            found.append(usds[0])
+            continue
+        named = [p for p in usds if p.stem.lower() == sub.name.lower().replace("-", "_")]
+        if named:
+            found.append(named[0])
+        else:
+            found.extend(usds)
+    return sorted(set(found))
+
+
+# Issue rule + message patterns we drop because they're produced by the validator
+# detecting that its own runtime is incomplete (PhysX schema not available,
+# Kit-bundled MDL not resolvable in a pip-only venv), NOT by an asset defect.
+# Documented in PROBLEMS.md P2.
+_P2_PHYSX_RULES = {
+    "JointHasJointStateAPI",
+    "PhysicsDriveAndJointState",
+    "PhysicsJointHasDriveOrMimicAPI",
+    "MimicAPICheck",
+    "PhysicsJointMaxVelocity",
+    "DriveJointValueReasonable",
+}
+_P2_MDL_RULES = {
+    "MissingReferenceChecker",
+    "MaterialPathChecker",
+    "PathsExistChecker",
+}
+
+
+def _drop_env_blocked_issues(issues: list[dict]) -> tuple[list[dict], dict]:
+    """LOCAL PATCH for PROBLEMS.md P2 — drop env-blocked issues.
+
+    The PhysX rules raise `"PhysxSchema is not available in this environment"`
+    once per joint when `from pxr import PhysxSchema` fails (i.e. running in
+    a pip-only venv without Kit). The MDL checkers report `OmniPBR.mdl` as
+    unresolvable for the same reason — `OmniPBR.mdl` ships with Kit, not with
+    `usd-core`. Both are environment limitations, not asset defects, and the
+    asset's own SimReady_Metadata records that these features previously
+    passed in a Kit-rooted environment.
+
+    We only drop when the rule + message pattern match precisely, so real
+    findings from these same checkers (e.g. a different unresolvable
+    reference, or a genuine path that doesn't exist) are preserved.
+
+    Returns (kept_issues, dropped_counts) where dropped_counts is a dict like
+    `{"physxschema_unavailable": int, "omnipbr_unresolved": int}`.
+    """
+    kept: list[dict] = []
+    dropped = {"physxschema_unavailable": 0, "omnipbr_unresolved": 0}
+    for iss in issues:
+        rule = iss.get("rule") or ""
+        msg = iss.get("msg") or ""
+        if rule in _P2_PHYSX_RULES and msg.startswith("PhysxSchema is not available"):
+            dropped["physxschema_unavailable"] += 1
+            continue
+        if rule in _P2_MDL_RULES and "OmniPBR.mdl" in msg:
+            dropped["omnipbr_unresolved"] += 1
+            continue
+        kept.append(iss)
+    return kept, dropped
+
+
+def issue_to_dict(iss) -> dict:
+    sev = SEVERITY_NAMES.get(iss.severity, str(iss.severity))
+    req = getattr(iss.requirement, "code", None) if iss.requirement else None
+    # Pull the requirement's spec-doc rel path so the dashboard can link every
+    # issue (including ones outside the loaded profile) back to the foundation
+    # markdown that defines it.
+    req_path = getattr(iss.requirement, "path", None) if iss.requirement else None
+    rule = iss.rule.__name__ if iss.rule else None
+    at = None
+    try:
+        if hasattr(iss.at, "GetPath"):
+            at = str(iss.at.GetPath())
+    except Exception:
+        pass
+    msg = iss.message if hasattr(iss, "message") else str(iss)
+    return {
+        "code": req or "UNKNOWN",
+        "path": req_path,
+        "severity": sev,
+        "msg": msg,
+        "prim": at or "/",
+        "rule": rule,
+    }
+
+
+def compute_profile_coverage(profile_id: str, profile_version: str,
+                              loaded_profile: oav.Profile) -> dict:
+    """Compare what `profiles.toml` declares for this profile against what
+    the validator actually loaded. The validator silently drops feature
+    entries whose ID + version aren't in the registry; this helper surfaces
+    that delta so the dashboard can warn the user.
+
+    Returns:
+        {
+          "declared": int,                # feature count in profiles.toml
+          "loaded":   int,                # feature count on `loaded_profile`
+          "missing":  [{"id": str, "version": str}, ...],  # declared but not loaded
+        }
+    Or an empty `{"declared": None, ...}` shape if profiles.toml can't be
+    located (best-effort — coverage display is suppressed when unknown).
+    """
+    none_result = {"declared": None, "loaded": len(loaded_profile.features),
+                   "missing": [], "specs_path": None}
+    if SPECS_DIR is None or not SPECS_DIR.is_dir():
+        return none_result
+    profiles_toml = SPECS_DIR / "nv_core" / "sr_specs" / "docs" / "profiles" / "profiles.toml"
+    if not profiles_toml.is_file():
+        return none_result
+    try:
+        with profiles_toml.open("rb") as fh:
+            data = tomllib.load(fh)
+    except Exception:
+        return none_result
+    block = data.get(profile_id, {}).get(profile_version)
+    if not block or "features" not in block:
+        return none_result
+    declared: list[dict] = []
+    for entry in block["features"]:
+        # Each entry is a single-key table: {"FET_ID": {"version": "X"}}.
+        if not isinstance(entry, dict) or len(entry) != 1:
+            continue
+        fid, meta = next(iter(entry.items()))
+        version = (meta or {}).get("version", "")
+        declared.append({"id": fid, "version": str(version)})
+    loaded_keys = {(f.id, str(f.version)) for f in loaded_profile.features}
+    missing = [d for d in declared if (d["id"], d["version"]) not in loaded_keys]
+    return {
+        "declared": len(declared),
+        "loaded": len(loaded_profile.features),
+        "missing": missing,
+        "specs_path": str(profiles_toml.relative_to(SPECS_DIR)) if SPECS_DIR else None,
+    }
+
+
+def _load_via_cli_loader() -> None:
+    """Populate OAV registries by file paths, the way `simready-validate` does.
+
+    Used by `--use-cli-loader`. Mirrors what
+    `simready.validate.impl.loader.load_validation_implementation` does:
+    clears the OAV registries, then loads rules/requirements (Python),
+    features (JSON/TOML), and profiles (TOML) from filesystem paths under
+    the foundations checkout. No dependency on the
+    `simready.foundation.core:SimReadyPlugin` entry point.
+
+    The loader handles JSON variant feature files natively, so the P1
+    patch is redundant when this path is active (we just skip calling it
+    from the call-site).
+    """
+    if SPECS_DIR is None or not SPECS_DIR.is_dir():
+        raise SystemExit(
+            "ERROR: --use-cli-loader requires SIMREADY_FOUNDATIONS_PATH "
+            "(or a sibling-of-workspace simready_foundations/ checkout). "
+            "Nothing to load."
+        )
+    try:
+        from simready.validate.impl.loader import load_validation_implementation
+    except ImportError as e:
+        raise SystemExit(
+            f"ERROR: --use-cli-loader needs `simready-validate` installed in "
+            f"the active Python (the PyPI package, not just the editable "
+            f"foundations). pip install simready-validate>=2026.4.8 . "
+            f"Underlying: {e}"
+        )
+    rules_path = SPECS_DIR / "nv_core" / "sr_specs" / "docs" / "capabilities"
+    features_path = SPECS_DIR / "nv_core" / "sr_specs" / "docs" / "features"
+    profiles_toml = SPECS_DIR / "nv_core" / "sr_specs" / "docs" / "profiles" / "profiles.toml"
+    for p, label in ((rules_path, "rules"), (features_path, "features"), (profiles_toml, "profiles.toml")):
+        if not p.exists():
+            raise SystemExit(f"ERROR: --use-cli-loader: {label} path not found at {p}")
+    print(f"  [CLI-loader] rules={rules_path}", flush=True)
+    print(f"  [CLI-loader] features={features_path}", flush=True)
+    print(f"  [CLI-loader] profiles={profiles_toml}", flush=True)
+    load_validation_implementation(
+        rules_and_requirements_paths=[rules_path],
+        features_paths=[features_path],
+        profiles_paths=[profiles_toml],
+    )
+    pr = oav.ProfileRegistry()
+    # The loader creates Profile objects with `.capabilities`; the rest of
+    # validate.py expects `.features` (the older OAV plugin API). Alias so
+    # the call sites keep working without a sweeping rename. Profile is a
+    # frozen dataclass, so bypass via object.__setattr__.
+    for profile in pr.values():
+        if not hasattr(profile, "features") and hasattr(profile, "capabilities"):
+            object.__setattr__(profile, "features", profile.capabilities)
+    cr = oav.CapabilityRegistry()
+    print(f"  [CLI-loader] loaded: profiles={len(pr)} capabilities={len(cr)}", flush=True)
+
+
+def build_engine(profile_id: str, profile_version: str) -> tuple[oav.ValidationEngine, oav.Profile]:
+    pr = oav.ProfileRegistry()
+    profile = pr.find(profile_id, profile_version)
+    if profile is None:
+        raise SystemExit(f"FATAL: profile {profile_id} v{profile_version} not registered")
+
+    # Engine runs every registered rule regardless of enable_*/disable_* state
+    # (those only adjust counters), so don't bother filtering the engine. We
+    # scope to the profile by filtering issues against profile requirements
+    # in validate_one / derive_features.
+    engine = oav.ValidationEngine(init_rules=True, variants=False)
+    return engine, profile
+
+
+# ---- Parallel-validation worker plumbing ---------------------------------
+# Each worker process initializes its own engine + profile once via
+# `_pool_init`, then handles N tasks via `_pool_validate`. The engine isn't
+# picklable so we can't share a single one across processes; instead the
+# init cost is amortized over multiple assets per worker.
+
+_pool_engine: oav.ValidationEngine | None = None
+_pool_profile: oav.Profile | None = None
+
+
+def _pool_init(profile_id: str, profile_version: str, use_plugin: bool = False) -> None:
+    global _pool_engine, _pool_profile
+    if use_plugin:
+        _patch_register_json_variant_features()
+    else:
+        _load_via_cli_loader()
+    _pool_engine, _pool_profile = build_engine(profile_id, profile_version)
+
+
+def _pool_validate(asset_path_str: str, target_root_str: str,
+                   profile_id: str, profile_version: str) -> tuple[dict, dict, list]:
+    """Validate one asset in a worker process.
+
+    Returns: (result_dict, external_records_by_identifier, issue_records).
+    The tracker pieces are returned (not the live tracker) so they can be
+    merged into the main process's tracker without sharing state.
+    """
+    asset = Path(asset_path_str)
+    target_root = Path(target_root_str)
+    tracker = external_deps.ExternalDepsTracker(target_root=target_root)
+    try:
+        result = validate_one(_pool_engine, asset, target_root, _pool_profile,
+                              profile_id, profile_version, tracker)
+    except Exception as e:
+        rel = asset.relative_to(target_root) if asset.is_relative_to(target_root) else asset
+        tracker.record_issue(str(asset), f"Validator crashed: {type(e).__name__}: {e}")
+        result = {
+            "name": asset.name, "path": str(asset),
+            "rel_path": str(rel),
+            "profile": profile_id, "profile_version": profile_version,
+            "passed": False,
+            "issues": [{"code": "SDK.CRASH", "severity": "error",
+                        "msg": f"{type(e).__name__}: {e}", "prim": "/", "rule": None}],
+            "passed_features": [], "failed_features": [], "affected_prims": [],
+        }
+    return result, dict(tracker.external), list(tracker.issues)
+
+
+def _merge_tracker(dst: external_deps.ExternalDepsTracker,
+                   ext_records: dict, issues: list) -> None:
+    """Fold a worker's tracker state into the main tracker."""
+    for key, rec in ext_records.items():
+        existing = dst.external.get(key)
+        if existing is None:
+            dst.external[key] = rec
+        else:
+            for ref in rec.referenced_by:
+                if ref not in existing.referenced_by:
+                    existing.referenced_by.append(ref)
+            for action in rec.actions:
+                if action not in existing.actions:
+                    existing.actions.append(action)
+    dst.issues.extend(issues)
+
+
+def validate_one(engine: oav.ValidationEngine, asset_path: Path, target_root: Path,
+                 profile: oav.Profile, profile_id: str, profile_version: str,
+                 ext_tracker: external_deps.ExternalDepsTracker) -> dict:
+    rel = asset_path.relative_to(target_root) if asset_path.is_relative_to(target_root) else asset_path
+    name = asset_path.name
+    print(f"  validate: {rel}", flush=True)
+
+    stage = Usd.Stage.Open(str(asset_path))
+    if not stage:
+        ext_tracker.record_issue(str(asset_path), "Failed to open USD stage")
+        return {
+            "name": name,
+            "path": str(asset_path),
+            "rel_path": str(rel),
+            "profile": profile_id,
+            "profile_version": profile_version,
+            "passed": False,
+            "issues": [{"code": "SDK.STAGE_OPEN", "severity": "error",
+                        "msg": f"Failed to open USD stage: {asset_path}", "prim": "/", "rule": None}],
+            "passed_features": [],
+            "failed_features": [],
+            "affected_prims": [],
+        }
+
+    ext_tracker.scan_stage(stage, asset_path, target_root)
+
+    profile_codes = {r.code for f in profile.features for r in f.requirements}
+
+    oav_results = engine.validate(stage)
+    issues = [issue_to_dict(i) for i in oav_results.issues()]
+    issues, env_blocked = _drop_env_blocked_issues(issues)
+    if any(env_blocked.values()):
+        parts = [f"{n} {k}" for k, n in env_blocked.items() if n]
+        print(f"    [PATCH P2] env-blocked: dropped " + ", ".join(parts), flush=True)
+    all_failures = [i for i in issues if i["severity"] in ("failure", "error")]
+    profile_failures = [i for i in all_failures if i["code"] in profile_codes]
+    extra_failures = [i for i in all_failures if i["code"] not in profile_codes]
+    # An asset passes only if no profile requirement fails. Issues from rules
+    # outside the loaded profile (per deviations.md #3) are reported separately
+    # but don't drive the pass/fail flag.
+    passed = not profile_failures
+
+    failed_codes = sorted({i["code"] for i in profile_failures})
+    passed_features, failed_features = derive_features(profile, failed_codes)
+
+    # Bucket extra failures by code -> example message + count + spec path,
+    # for the "outside-profile" panel in the report. The path lets the
+    # dashboard link each code back to its foundation markdown.
+    extra_by_code: dict[str, dict] = {}
+    for i in extra_failures:
+        bucket = extra_by_code.setdefault(i["code"], {
+            "code": i["code"],
+            "msg": i["msg"],
+            "path": i.get("path"),
+            "count": 0,
+        })
+        bucket["count"] += 1
+    extra_failures_summary = sorted(extra_by_code.values(), key=lambda x: -x["count"])
+
+    affected_prims = sorted({i["prim"] for i in all_failures if i["prim"] and i["prim"] != "/"})
+
+    return {
+        "name": name,
+        "path": str(asset_path),
+        "rel_path": str(rel),
+        "profile": profile_id,
+        "profile_version": profile_version,
+        "passed": passed,
+        "issues": issues,
+        "passed_features": passed_features,
+        "failed_features": failed_features,
+        "extra_failures": extra_failures_summary,
+        "affected_prims": affected_prims,
+        "env_blocked": env_blocked,
+    }
+
+
+def derive_features(profile: oav.Profile, failed_codes: list[str]) -> tuple[list[dict], list[dict]]:
+    """Map profile features to passed/failed feature entries based on requirement codes."""
+    passed: list[dict] = []
+    failed: list[dict] = []
+    for feat in profile.features:
+        feat_path = getattr(feat, "path", None)
+        req_path_by_code = {r.code: getattr(r, "path", None) for r in feat.requirements}
+        feat_codes = sorted(req_path_by_code.keys())
+        feat_failed = [c for c in feat_codes if c in failed_codes]
+        entry = {
+            "id": feat.id,
+            "version": str(feat.version),
+            "path": feat_path,
+            "requirement_codes": feat_codes,
+            "requirement_paths": req_path_by_code,
+        }
+        if feat_failed:
+            entry["failed_codes"] = feat_failed
+            failed.append(entry)
+        else:
+            passed.append(entry)
+    return passed, failed
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Validate SimReady customer assets in a directory.")
+    ap.add_argument("target", nargs="?", default=None,
+                    help=f"Directory containing customer assets (default: {DEFAULT_TARGET_DIR})")
+    ap.add_argument("--profile", default="Robot-Body-Runnable", help="Profile ID (default: Robot-Body-Runnable)")
+    ap.add_argument("--version", default="1.0.0", help="Profile version (default: 1.0.0)")
+    ap.add_argument("--output", default=None,
+                    help="Output dir (default: <target>/.reports/<target-name>.<profile>)")
+    ap.add_argument("--workers", type=int, default=0,
+                    help="Number of parallel worker processes. 0=auto "
+                         "(min(cpu_count, asset_count, 8)); 1=sequential.")
+    ap.add_argument("--list-profiles", action="store_true",
+                    help="Print every registered profile (one `PROFILE: <id> v<version>` line each), "
+                         "then exit. Used by /simready-report to drive the spec selector before validating.")
+    ap.add_argument("--use-kit", action=argparse.BooleanOptionalAction, default=None,
+                    help="Re-exec this script through a Kit-rooted Python (Isaac Sim 6) via "
+                         "_kit_wrapper.py so `pxr.PhysxSchema` and Kit's MDL search path are "
+                         "registered for real, instead of the pip-only venv falling back to "
+                         "the P2 filter. Adds ~10-30s of SimulationApp boot to the main process "
+                         "(plus per worker, so prefer --workers 1 in Kit mode). Default: auto-enabled "
+                         "for PhysX-bearing profiles (Robot-Body-Physx/Isaac/Runnable, "
+                         "Prop-Robotics-Physx/Isaac); pass --no-use-kit to override. "
+                         "See PROBLEMS.md P2.")
+    ap.add_argument("--kit-python", default=None,
+                    help="Path to the Kit-rooted python.bat used by --use-kit. "
+                         "Defaults to $SIMREADY_KIT_PYTHON or "
+                         r"C:\isaacsim6\_build\windows-x86_64\release\python.bat.")
+    ap.add_argument("--use-plugin", action="store_true",
+                    help="Fall back to loading rules/features/profiles via the "
+                         "simready.foundation.core:SimReadyPlugin entry-point (the "
+                         "pre-GitHub-migration flow). Requires the editable install "
+                         "of nv_core/sr_specs in the active Python. Default behavior "
+                         "is to load from on-disk paths via "
+                         "simready.validate.impl.loader.load_validation_implementation, "
+                         "matching the official simready-validate CLI. See PROBLEMS.md P2.")
+    args = ap.parse_args()
+
+    # Auto-enable --use-kit for profiles that pull in PhysX features. The
+    # pip-only path's P2 filter silently drops physxschema_unavailable /
+    # omnipbr_unresolved findings, which makes "passed" misleading for these
+    # profiles — the rules that matter never actually ran. The same auto
+    # logic runs earlier in _maybe_reexec_under_kit() so this just keeps
+    # args.use_kit truthful for the rest of main() (e.g. logging, worker
+    # forcing). _PHYSX_PROFILES is the module-level source of truth.
+    if args.use_kit is None:
+        args.use_kit = args.profile in _PHYSX_PROFILES
+
+    # Default path: populate the OAV registries via the CLI loader. The
+    # legacy --use-plugin route keeps the SimReadyPlugin entry-point as a
+    # fallback, in which case we also run the P1 JSON-variant patch on top
+    # (the loader makes P1 redundant on the default path).
+    if not args.use_plugin:
+        _load_via_cli_loader()
+    else:
+        _patch_register_json_variant_features()
+
+    if args.list_profiles:
+        pr = oav.ProfileRegistry()
+        profiles = sorted(pr.values(), key=lambda p: (p.id, str(p.version)))
+        for p in profiles:
+            print(f"PROFILE: {p.id} v{p.version}", flush=True)
+        return 0
+
+    target = resolve_target(args.target)
+    if target is None:
+        return 2
+    if not target.is_dir():
+        print(f"ERROR: target dir does not exist: {target}", flush=True)
+        return 2
+
+    problems = sanity_check_target(target)
+    if problems:
+        print(f"ERROR: target {target} failed sanity check; nothing to validate.", flush=True)
+        for p in problems:
+            print(f"  - {p}", flush=True)
+        if args.target is None:
+            print("  hint: /simready-report inferred the current working directory. "
+                  "cd into an asset directory or pass an explicit path.", flush=True)
+        return 2
+
+    # Capture the pre-packaging target so the default output lands where
+    # the user pointed (inside their asset dir), not under packages/.
+    original_target = target
+    # If the user pointed at raw assets under assets_to_validate/, auto-package
+    # into packages/<name>/ first and validate the packaged tree.
+    target = maybe_package_target(target)
+
+    # Default output: <original_target>/.reports/<name>.<profile>/. The
+    # `.reports/` prefix is auto-skipped by discover_assets so re-running
+    # /simready-report from inside the target is safe. The `.` separator
+    # between target name and profile id is unambiguous because asset bundle
+    # names use snake_case (no dots) and profile ids use Title-Case-Hyphens
+    # (no dots either). No PASS/FAIL suffix — status belongs inside the report.
+    default_out_name = f"{original_target.name}.{args.profile}"
+    out_dir = Path(args.output).resolve() if args.output else original_target / ".reports" / default_out_name
+
+    if SPECS_DIR is None or not SPECS_DIR.is_dir():
+        print(
+            "WARNING: spec source not found"
+            + (f" at {SPECS_DIR}" if SPECS_DIR else "")
+            + ". Set SIMREADY_FOUNDATIONS_PATH so doc rendering can locate the markdown source.",
+            flush=True,
+        )
+
+    print(f"Target: {target}", flush=True)
+    print(f"Output: {out_dir}", flush=True)
+    print(f"Profile: {args.profile} v{args.version}", flush=True)
+
+    assets = discover_assets(target, exclude=out_dir)
+    print(f"Discovered {len(assets)} USD asset(s) under {target}", flush=True)
+    if not assets:
+        print(f"ERROR: no USD assets (.usd/.usda/.usdc/.usdz) found under {target}. "
+              f"Add assets and re-run.", flush=True)
+        return 2
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # Resolve worker count. Default: cap at cpu_count, asset count, and 8 (each
+    # worker re-imports the validator stack at startup, so wider isn't always
+    # faster).
+    if args.workers <= 0:
+        workers = max(1, min(os.cpu_count() or 1, len(assets), 8))
+    else:
+        workers = args.workers
+    # In Kit mode each worker would have to re-boot SimulationApp (10-30 s of
+    # Kit startup per worker — net slowdown). Force sequential.
+    if os.environ.get("SIMREADY_INSIDE_KIT") == "1" and workers > 1:
+        print(f"  --use-kit: forcing workers=1 (Kit-rooted runs avoid per-worker SimulationApp boot)", flush=True)
+        workers = 1
+    print(f"Workers: {workers} ({'parallel' if workers > 1 else 'sequential'})", flush=True)
+
+    ext_tracker = external_deps.ExternalDepsTracker(target_root=target)
+    results: list[dict] = []
+
+    if workers <= 1 or len(assets) <= 1:
+        # Sequential path. One engine, all assets.
+        engine, profile = build_engine(args.profile, args.version)
+        profile_req_count = sum(len(f.requirements) for f in profile.features)
+        print(f"  profile features: {len(profile.features)}", flush=True)
+        print(f"  profile requirements: {profile_req_count}", flush=True)
+        for asset in assets:
+            try:
+                results.append(validate_one(engine, asset, target, profile, args.profile, args.version, ext_tracker))
+            except Exception as e:
+                log.exception("Validation failed for %s", asset)
+                ext_tracker.record_issue(str(asset), f"Validator crashed: {type(e).__name__}: {e}")
+                results.append({
+                    "name": asset.name, "path": str(asset),
+                    "rel_path": str(asset.relative_to(target)) if asset.is_relative_to(target) else str(asset),
+                    "profile": args.profile, "profile_version": args.version,
+                    "passed": False,
+                    "issues": [{"code": "SDK.CRASH", "severity": "error", "msg": str(e), "prim": "/", "rule": None}],
+                    "passed_features": [], "failed_features": [], "affected_prims": [],
+                })
+    else:
+        # Parallel path. Each worker initializes its own engine via _pool_init.
+        # Profile metadata is logged from the main process (also constructs an
+        # engine here just for the print; cheap relative to parallel speedup).
+        _, profile = build_engine(args.profile, args.version)
+        profile_req_count = sum(len(f.requirements) for f in profile.features)
+        print(f"  profile features: {len(profile.features)}", flush=True)
+        print(f"  profile requirements: {profile_req_count}", flush=True)
+        with ProcessPoolExecutor(
+            max_workers=workers,
+            initializer=_pool_init,
+            initargs=(args.profile, args.version, args.use_plugin),
+        ) as ex:
+            futures = {
+                ex.submit(_pool_validate, str(a), str(target), args.profile, args.version): a
+                for a in assets
+            }
+            for fut in as_completed(futures):
+                asset = futures[fut]
+                try:
+                    result, ext_records, issues = fut.result()
+                except Exception as e:
+                    log.exception("Worker failed for %s", asset)
+                    ext_tracker.record_issue(str(asset), f"Worker crashed: {type(e).__name__}: {e}")
+                    results.append({
+                        "name": asset.name, "path": str(asset),
+                        "rel_path": str(asset.relative_to(target)) if asset.is_relative_to(target) else str(asset),
+                        "profile": args.profile, "profile_version": args.version,
+                        "passed": False,
+                        "issues": [{"code": "SDK.WORKER_CRASH", "severity": "error",
+                                    "msg": str(e), "prim": "/", "rule": None}],
+                        "passed_features": [], "failed_features": [], "affected_prims": [],
+                    })
+                    continue
+                results.append(result)
+                _merge_tracker(ext_tracker, ext_records, issues)
+        # Sort results to match the assets list order (parallel completion is
+        # arbitrary; stable order makes the dashboard reproducible).
+        order = {str(a): i for i, a in enumerate(assets)}
+        results.sort(key=lambda r: order.get(r["path"], len(order)))
+
+    # Mirror per-asset thumbnails from <asset_dir>/.thumbs/256x256/<filename>.png
+    # into <out_dir>/images/<filename>.png so the dashboard can reference them
+    # via a relative path (matches the reference dashboard's `images/` layout).
+    # The source PNGs were sourced externally (e.g. NVIDIA Isaac content
+    # bucket) and are not produced by the packaging pipeline — `thumbnail_provenance`
+    # records each so the dashboard can surface that fact.
+    images_dir = out_dir / "images"
+    images_dir.mkdir(parents=True, exist_ok=True)
+    thumbnail_provenance: list[dict] = []
+    import shutil as _shutil
+    for r in results:
+        usd_path = Path(r["path"])
+        spec_thumb = usd_path.parent / ".thumbs" / "256x256" / f"{usd_path.name}.png"
+        local_thumb = images_dir / f"{usd_path.name}.png"
+        rel = f"images/{usd_path.name}.png"
+        entry = {"asset": r["name"], "rel": rel}
+        if spec_thumb.is_file():
+            try:
+                _shutil.copy2(spec_thumb, local_thumb)
+                entry.update({"present": True, "copied_from": str(spec_thumb)})
+            except Exception as e:
+                entry.update({"present": False, "error": f"{type(e).__name__}: {e}"})
+        else:
+            entry["present"] = False
+        thumbnail_provenance.append(entry)
+
+    specs_docs_dir = (SPECS_DIR / "nv_core" / "sr_specs" / "docs") if (SPECS_DIR and SPECS_DIR.is_dir()) else None
+    dashboard_docs_dir = DASHBOARD_DOCS_DIR if (DASHBOARD_DOCS_DIR and DASHBOARD_DOCS_DIR.is_dir()) else None
+    coverage = compute_profile_coverage(args.profile, args.version, profile)
+    if coverage["declared"] is not None and coverage["missing"]:
+        print(f"  profile coverage: {coverage['loaded']}/{coverage['declared']} features loaded "
+              f"({len(coverage['missing'])} silently dropped — see PROBLEMS.md P1)", flush=True)
+    (out_dir / "results.json").write_text(json.dumps({
+        "generated": datetime.now(timezone.utc).isoformat(),
+        "target": str(target),
+        "profile": args.profile,
+        "profile_version": args.version,
+        "specs_docs_dir": str(specs_docs_dir) if specs_docs_dir else None,
+        "dashboard_docs_dir": str(dashboard_docs_dir) if dashboard_docs_dir else None,
+        "profile_coverage": coverage,
+        "thumbnail_provenance": thumbnail_provenance,
+        "results": results,
+    }, indent=2), encoding="utf-8")
+
+    report.write_dashboard(out_dir, target, args.profile, args.version, results,
+                           specs_docs_dir=specs_docs_dir,
+                           dashboard_docs_dir=dashboard_docs_dir,
+                           thumbnail_provenance=thumbnail_provenance,
+                           profile_coverage=coverage)
+    ext_tracker.write_reports(out_dir)
+
+    summary = {
+        "total":    len(results),
+        "passed":   sum(1 for r in results if r["passed"]),
+        "failed":   sum(1 for r in results if not r["passed"]),
+        "issues":   sum(len(r["issues"]) for r in results),
+        "external": ext_tracker.external_count(),
+    }
+    print(f"\nReport: {out_dir / 'index.html'}", flush=True)
+    print(f"SUMMARY: {summary}", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())