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.

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 remains blocked while a target definition requires a persisted external document-effect contract that is not available yet. Do not edit active workflow actions or use a forced apply. The blocker protects existing instances and prevents a false successful target state.

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.