nvidia-omniverse/usd-content-agents/content-workflow-articulation

content-workflow-articulation

Use this workflow skill to sequence four reusable atomic skills: content-articulation-inspection, content-articulation-proposal, content-articulation-review, and content-articulation-authoring. usd-cli provides source inspection; Joint Agent is an optional proposal leaf and owns Stage 2 readiness only when selected; deterministic workflow code owns exact saved-readback preparation, review bindings, accepted-only authoring, resume, cancellation, saved-stage readback, and publication.

The default public CLI launches exactly one long-running child with a compact task. The child invokes focused prepare and apply steps through the shared runner. --execution-mode fixed is an explicit compatibility controller only.

For a shared outer-selected asset graph, obtain the stable articulation.preparation-publisher.v1 and articulation.proposal-provider.v1 descriptors from articulation_asset_leaf_catalog(). The domain adapter binds their exact invocation/result schemas and the proposal-to-preparation dependency only. It does not select, order, invoke, or terminalize graph nodes; those operations remain owned by the sole outer coordinator. Put the selected typed invocation below its leaf-attempt directory and call the descriptor entrypoint with --invocation; preparation derives articulation-preparation-publication/ and proposal derives articulation-proposal-attempt/ beside that host-chosen envelope. Both are create-only, so retry or replacement requires a fresh host-selected attempt directory. Never put an output path, HTTP endpoint, or credential source in selected-leaf data, and never mix that artifact with direct CLI flags.

When embedded under content-workflow-asset, the outer asset coordinator is the only reasoning loop. Invoke the first articulation run with the active --embedded-run-state, inspect articulation_agent_observation.json, and use the same focused apply step. The native request binds the exact outer request, coordinator plan, attempt, input handoff, and nested domain-run root. Never launch a nested coding agent or replace the bound request after its exact outer review or any selected human review.

When to Use

Use for prompt-driven articulation work that must expose uncertain candidates, survive interruption, or prove that the saved joint graph exactly matches the approved candidate set. Typical requests mention drawers, hinges, sliders, doors, mechanisms, joints, or articulated components.

Limitations

• Articulation-v1 authors only revolute and prismatic joints.
• Provider-neutral preparation does not create render or usd-cli evidence. Its

public producer derives all six preparation records from an exact retained source/dependency/configuration closure plus complete saved readback. Exact per-prim ownership/disposition authority comes from the retained configuration and must match the saved observation. The create-only publisher fails closed on unsafe paths, links, stale bytes, incomplete coverage, destination reuse, or readback drift.

• A selected replacement proposal provider is a separate public leaf. Its

invocation binds one retained artifact-json payload; trusted standalone operators may instead call the explicit http-json direct adapter. Both are advisory only and never fall back to Joint inference or classic execution. Every invoked attempt writes one immutable terminal receipt for success, provider failure, invalid response, or bound replacement while create-only storage remains writable. Irrecoverable terminal storage failure is an infrastructure error that poisons the root. Preserve a failed attempt root and use a new root for every retry or replacement.

• Current provider-neutral runs must produce canonical post-authoring visual evidence

through the shared OVRTX leaf, bind its exact output/dependency/report/image identities, and include those image digests in the outer post-readback review. This evidence is a review input, never a deterministic visual pass.

• Human approval does not promote a native Stage 2 review_required candidate.

Re-run Joint Agent adjudication or reject that candidate.

• Authoring is topology-only: masses and colliders remain false.
• Provider-backed preparation requires a healthy workflow-owned usd-cli session and captures

digest-bound source, topology, property, camera, response, and focused-render evidence before review.

• Source inspection is fail-closed at 4,096 snapshot prims. Split or simplify a

larger inspection scope before retrying; renders do not start for a truncated snapshot.

• One collection supports at most 8 configured view directions and 256 focused

renders. Reduce directions or candidate moving-part coverage before retrying.

• Skill-routed execution sends every candidate through its evidence-bound agent

decision patch. --review-policy none publishes that decision as the review receipt; both uncertain and all retain the fail-closed all-candidate operator review gate. Frozen v1/v2 deserialization retains its historical review semantics; the current provider-neutral leaf does not emit that legacy compatibility shape.

• usd-cli and the workflow host must resolve the same source and run paths.
• Provider-backed inference and rendering still depend on the backends selected by the

copied Joint Agent config.

Prerequisites

• From the repository root, set up and activate the Python 3.12 environment:

``bash ./scripts/setup_content_agent.sh uv pip install --python .venv/bin/python -e "apps/joint_agent[dev]" mkdir -p runs/configs cp apps/joint_agent/configs/byoa_joint_rigger.yaml \ runs/configs/file-cabinet-joint.yaml source .venv/bin/activate ``

• For provider-backed runs, load usd-cli for source inspection and evidence

renders. The workflow owns one local sidecar for the session.

• Load usd-cli and the four atomic Articulation skills named above.
• Provide a local USD-family source. For provider-backed runs, also provide a

copied Joint Agent BYOA config and configure its model/render backends. For a provider-neutral standalone or embedded run, provide either a validated EmbeddedArticulationPreparation or publish one from a complete retained ArticulationPreparationInspectionReadback.

Instructions

Before the numbered workflow, provider-neutral callers that begin from saved inspection readback run:

content-workflow-cli articulation publish-preparation \
  --readback path/to/articulation_preparation_readback.json \
  --retained-root path/to/retained-inspection \
  --output-dir runs/preparation-publication
 
content-workflow-cli articulation validate-preparation \
  --publication runs/preparation-publication/articulation_preparation_publication.json

The producer takes no source_members or authoritative_owners arguments; it derives both from exact retained configuration membership rows, rejects a saved readback observation that differs from them, and publishes articulation_preparation_publication.json beside the preparation in a fresh directory. Revalidate the returned publication path before passing its preparation onward. The exact models, artifacts, and terminal rules are specified in agentic/docs/articulation_preparation_attempt_contract.md.