Apply system artifact releases safely

Manage global setup components in System > Configuration > Setup. Workspace plans every change first and persists the following apply run. You can review the target release, operations, blockers, and outcome without editing existing workflow definitions in place.

Interpret status

The setup page shows a managed state for every system artifact:

State	Meaning	Next step
`Unmanaged`	No active release binding exists yet.	Create a plan.
`Update available`	The target differs from the active release.	Review and apply the plan.
`Blocked`	A prerequisite or overlay prevents apply.	Read the blocker and resolve its cause.
`Applying`	A persisted apply run owns the active lease.	Wait for its status; do not start a parallel apply.
`Drift detected`	The active release could not be verified completely.	Review the run and operational readiness.
`Ready`	The target release and effective binding are verified.	No action is required.
`Ready with overlay`	The target is verified and has a compatible active overlay.	Review the overlay with the next update.

The general readiness value remains compatible with older provisioning flows during rollout. Use the individual system artifact state for the managed release contract.

Plan and apply a change

Open System > Configuration > Setup.
Select the required system artifacts.
Run the check.
Review the target release, expiry, operations, and blockers.
Apply only a valid plan without blockers.
Review the apply run and refresh status.

A plan is valid for 15 minutes. Workspace rejects it if the target manifest, observed state, or binding generation changes. Create a new plan in that case. Repeating the same plan ID does not start a second run.

Workflow library and overlays

Managed workflow releases publish system workflows as versioned definitions. Once such a release is approved and activated, new instances use the effective global binding unless the tenant owns a workflow override. Existing instances keep their pinned workflow ID and version.

The workflow.library.managed capability enables this managed fallback per business tenant. Only the System Tenant may grant or revoke it for a target tenant; a business tenant cannot enable it for itself. A tenant-owned active workflow always takes precedence and does not require the capability. When the capability is enabled, a missing or drifting managed binding fails closed instead of starting a new instance through the legacy fallback.

For a newly provisioned business tenant, the workflows module creates the selection automatically when it is missing. Existing values, including an explicit false, remain unchanged. Workspace does not update existing tenants in the background. Only an explicitly started provisioning run for the current workflows module version may add a missing selection. If the following resolution or compilation fails, the run does not record the module as complete.

An active global overlay remains separate from the product release. If a new release changes the same workflow resource, Workspace blocks the complete apply. Rebase, replace, or remove the overlay explicitly; Workspace does not perform an automatic merge.

The workflow library publishes its complete managed target contract as a new immutable release even when an active legacy definition differs from the former foundation hash. Workspace changes neither the legacy graph nor instances already pinned to it. New instances use the effective managed binding after successful activation. A target version occupied by another manifest, workspace-authority conflicts, or active unsupported overlays still block the plan fail closed. Do not edit active workflow actions or use a forced apply in response to such a blocker.

For the managed Invoice V2 workflow, the target manifest also verifies both action descriptors and the bundle worker, retry/recovery, publication, and orphan contracts. Before activation, the business tenant must set commerce.invoices.documents_group_id to an existing tenant-local group. In the business tenant, open Access Groups and choose “Use for invoice documents” on a suitable group. You need permission to update access groups and write access to the selected group. A global value or a group from another tenant is not a substitute. The group receives read access to XML, HTML, and PDF; the triggering user receives no implicit individual grant.

The Setup Center and the invoice itself show missing prerequisites before finalization. This includes an invalid order currency and an existing document version that conflicts with initial finalization. Mail is not a finalization prerequisite, so creating the document does not send a message automatically.

After invoice finalization starts, the invoice may temporarily show Finalization pending. Only the joint publication of XML, HTML, PDF, permissions, the final document, workflow state, OSS, and accounting progress opens the invoice. A terminal error changes it to Finalization failed; the available retry action continues the same operation with a new bounded attempt cycle. manual_review requires administrative review and is not restarted automatically.

A blocked workflow-library plan still shows the intended sequence:

validate the complete workflow manifest and action contracts,
publish the immutable workflow release,
activate effective workflow bindings atomically,
verify the published release and bindings.

These operations describe the planned target flow. They do not authorize an apply. While the plan contains a blocker, Workspace starts no apply run and executes none of these operations.

A blocked managed target does not by itself tell you whether the currently effective legacy workflow is executable. Also inspect tenant workflow readiness. Workspace resolves the effective tenant or system workflow there and compiles its complete graph. Treat “workflow exists but is not executable” as an operational blocker; do not bypass it with force or direct database changes.

Inspect with `nucli`

Use a system-tenant session with system_init:read for status and planning, and system_init:apply for apply:

bash

nucli --tenant system system init status --json
nucli --tenant system system init plan --artifact workflow_library --json
nucli --tenant system system init apply --plan <PLAN_ID> --json
nucli --tenant system system init run <RUN_ID> --json

tenants:init does not grant access to these global operations. Do not bypass the server contract with direct database writes or a local offline administration tool.

Work with an agent

Show the built-in workflow to the agent first:

bash

nucli skills show system-artifacts

An MCP-capable agent can use these tools for the same workflow:

Tool	Purpose
`nucleus_system_artifacts_skill`	Returns the safe workflow instructions.
`nucleus_system_artifacts_status`	Reads the current managed state.
`nucleus_system_artifacts_plan`	Creates a plan for exactly one artifact.
`nucleus_system_artifacts_apply`	Applies exactly one approved plan ID.
`nucleus_system_artifacts_run`	Reads the apply run.

Require the agent to show you the target release, expiry, operations, and blockers before apply. Approve that exact plan ID. Only then may the agent call nucleus_system_artifacts_apply with approved: true. Without this value, nucli sends no apply request. The server still checks the System Tenant, scopes, plan binding, and blockers; local approval does not replace these checks.

Creating a plan does not activate a release and therefore does not require the apply approval. Do not automate force or retries for expired, stale, or blocked plans.

The task is complete when the apply run reports succeeded and the artifact then reports ready or ready_with_overlay. A blocked plan is a valid review finding instead: resolve the reported cause first.

Handle errors safely

Create a new plan for ERR_SYSTEM_ARTIFACT_PLAN_EXPIRED or ERR_SYSTEM_ARTIFACT_PLAN_STALE. Read the blocker for ERR_SYSTEM_ARTIFACT_PLAN_BLOCKED. Inspect the active run for ERR_SYSTEM_ARTIFACT_RUN_IN_PROGRESS. After ERR_SYSTEM_ARTIFACT_APPLY_FAILED, the previous binding remains active; review operational readiness and the run status. After ERR_SYSTEM_ARTIFACT_VERIFICATION_FAILED, the previous effective binding remains in place; review the run and operational readiness before planning again.