> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan and Apply

> Preview EDK changes with `plan`, deploy them with `apply`, and stage cross-referenced changes safely.

<Warning>
  **Limited Release.** The EDK is currently in limited release and is not available to all customers. Commands, generated file layouts, and package APIs may change before general availability. Confirm you're on the latest EDK version before starting new projects.
</Warning>

Once you've authored changes in your EDK workspace, deploying them is a two-command loop: `plan` shows the structural diff between your source and the live environment, and `apply` executes it. This page covers both commands, the staged approach required when new fields are cross-referenced, and the design principles that keep deployments predictable.

<Info>
  This page assumes you have a working EDK workspace and pulled entities. If not, start with [Getting Started](/edk/getting-started) and then [EDK Authoring](/edk/authoring).
</Info>

## Plan Changes

`plan` compares your local source to the current state of the deployed environment and reports what would change. Always run `plan` before `apply` — even a clean TypeScript check doesn't guarantee that every referenced platform handle exists in the target environment.

### Target the Whole Workspace or a Single File

You can plan across the whole organization workspace:

```bash theme={null}
elementum plan <instance>/<organization>
```

Or narrow the target while iterating. Narrower targets run faster and produce smaller diffs:

```bash theme={null}
# One app
elementum plan <instance>/<organization>/apps/<appRef>

# A single automation file
elementum plan <instance>/<organization>/apps/<appRef>/automations/<automation>.ts
```

<Tip>
  Prefer the narrowest target that still covers your dependencies. A workspace-wide plan is only necessary when you want a full picture before a large release.
</Tip>

### Plan Symbols

A `plan` report uses four symbols to describe each entity's status:

| Symbol | Meaning                                                                                                                          |
| ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `+`    | Create — the entity exists in source but not in the environment.                                                                 |
| `~`    | Update — the entity differs between source and the environment.                                                                  |
| `=`    | Unchanged — source matches the environment.                                                                                      |
| `!`    | Blocked — the entity can't be planned. Usually a dependency isn't yet deployed. See [Debug blocked plans](#debug-blocked-plans). |

Always inspect the structural diff before applying. A blocked entry is information about dependencies, not a bug — see the debugging section below for how to interpret it.

## Apply Changes

After reviewing the plan, apply the same target:

```bash theme={null}
elementum apply <instance>/<organization>
```

For safer iteration, apply the narrowest complete dependency set — for example, an owning Element's file before its dependents:

```bash theme={null}
elementum apply <instance>/<organization>/elements/<elementRef>/<elementRef>.ts
```

<Warning>
  `apply` mutates the live environment. Confirm the active target with `elementum auth status` before applying — especially in a shared environment where the wrong `ELEMENTUM_ENVIRONMENT` can push development changes into production.
</Warning>

## Verify Convergence

After every `apply`, re-run `plan` against the same target:

```bash theme={null}
elementum plan <same-paths>
```

The expected result is:

```
Plan: 0 to create, 0 to update, N unchanged.
```

Anything else means the applied change didn't fully converge — for example, a field was created but a dependent layout still needs a follow-up apply. This is the primary signal for the [two-stage deployment](#two-stage-deployment) pattern below.

## Two-Stage Deployment

When a change introduces fields that are referenced by other new definitions in the same commit, a single `apply` cannot converge. New fields do not have platform field handles until the owning App or Element has been created or updated, so layouts, dynamic picklists, Automations, Agents, Skills, Search Tables, and dependent entities cannot resolve those handles before they exist.

A reliable sequence:

1. **Add and apply the owning App or Element fields.**
2. **Refresh the deployed bindings** — for example, by re-running `pull org` or an additional `pull`.
3. **Add or restore layouts** that reference the new fields.
4. **Apply the layouts.**
5. **Plan and apply dependent Automations, Agents, Skills, and Search Tables.**
6. **Plan the complete dependency set again** and verify convergence.

You can author the final design first — layouts, dependent Automations, and all — but deployment may still need to be staged. A common pattern during a first apply is to temporarily omit layouts that reference newly added fields, apply the fields, then restore and apply the layouts.

## Design Decisions

The following patterns keep EDK deployments safe, especially when multiple engineers share an organization.

### Preserve Identity During Renames

Change visible names and descriptions freely, but do not change deployed UUIDs, handles, or stable `refName`s unless you intend an identity migration. A display rename is safe. A `refName` change typically replaces the entity in the target environment and can orphan existing records or relationships.

### Separate Process Records from Authoritative Data

* **Apps** should own workflow records and process-specific stages.
* **Elements** should own reusable domain data that can be shared across processes.

Modeling process state on an Element (or authoritative data on an App) tends to force awkward cross-entity coupling later.

### Deploy Dependencies in Order

Rather than deploying an entire cross-entity design at once, deploy in dependency order and verify each stage before moving to the next:

1. Owning Apps and Elements
2. New fields
3. Layouts and cross-entity relationships
4. Automations, Agents, Skills, and Search Tables
5. Process orchestration

### Apply to the Lowest Environment First

Point the EDK at your lowest environment — typically development — and use [Elementum's platform deployments](/administration/deploy-apps-between-environments) to promote the resulting objects into higher environments. This keeps the EDK workflow focused on authoring against a single controlled target, and lets the platform handle environment-specific configuration when promoting between dev, test, and production.

Before every `apply`, confirm the active target with `elementum auth status` so you never accidentally apply development changes to production.

### Choose a Single Authoring Surface Per Project

Decide up front whether a given App or Element is authored from the EDK or from the Elementum platform, and keep the whole team on the same surface for that object. Mixed authoring — some team members editing in the EDK while others edit in the UI — creates conflicts in objects and automations: concurrent changes diverge, `plan` diffs repeatedly report unexpected updates when a UI edit lands between pulls, and it becomes unclear which surface is authoritative.

If some team members need to work in the platform while others use the EDK, agree on a clear ownership model per object type (for example, EDK owns automation logic while the platform owns layout tweaks) and pull frequently to stay in sync.

### Create New Objects in the Platform First

The EDK is designed for iterating on Apps and Elements that already exist. Create new objects in the Elementum platform first, then pull them into your workspace with `elementum pull app --id <id>` or `elementum pull element --id <id>`. This lets the platform assign namespaces, handles, and initial layout defaults, and gives the EDK a clean, deployed starting point for further authoring in TypeScript. See [Pull existing entities](/edk/authoring#pull-existing-entities) for the details.

## Debug Blocked Plans

A `!` in the plan output usually means a new field is being referenced before its platform handle exists. Common triggers:

* A layout references a field that hasn't been applied yet.
* An automation references an automation output that hasn't been created yet.
* A search table's `--aspect` or `--search-table` UUID has not been generated on the platform.

The fix is almost always a **staged field deployment**, not a hard-coded UUID or an edit to a generated state file. Follow the [two-stage deployment](#two-stage-deployment) sequence above:

1. Apply the field-only change first.
2. Re-plan — the blocked entries should now resolve to `+` or `~`.
3. Apply the dependents.

## Handle Transient Failures

If `apply` returns HTTP `0` or another transport failure mid-run, do not blindly retry the same apply. Instead:

1. Run `plan` against the same target to see what actually converged.
2. Trim your target to the entities that didn't apply.
3. Re-apply.

Blind retries after a transport failure can double-apply entities that already converged and produce misleading diffs.

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/edk/cli-reference">
    Every `elementum` command grouped by prefix, including `plan`, `apply`, `auth`, and `pull`.
  </Card>

  <Card title="EDK Authoring" icon="pen-to-square" href="/edk/authoring">
    Revisit builders, `@catalog` handle-tokens, and the authoring agent workflow.
  </Card>
</CardGroup>