Authoring

Pull existing Elementum solutions, edit typed source safely, and validate changes before planning.

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.

EDK authoring starts from the current deployed definition. Pull it into an organization workspace, edit the reconstructed TypeScript, and validate the complete workspace before reviewing a deployment plan.

Read the EDK overview first. An organization workspace must contain the files created by elementum pull org --data-only before you pull other entities.

The examples below assume you are working inside an organization workspace with one matching saved profile. See Authentication if the target is ambiguous.

Start from the Deployed Definition

Use a stable namespace, name, or handle supported by the pull command rather than copying platform IDs into authored source. First confirm that your profile points to the intended organization:

elementum auth status
elementum list apps
elementum list elements
elementum list tables

Refresh organization-level references, then pull the object you intend to edit:

elementum pull org --data-only
elementum pull app <namespace>

# Pull referenced Apps and Elements too:
elementum pull app <namespace> --with-dependencies

# Other organization roots:
elementum pull element <namespace>
elementum pull table <name-or-handle>
elementum pull task <namespace>

pull app reconstructs the App, its fields, and supported app-owned entities. pull element, pull table, and pull task reconstruct their supported children and references. Each command regenerates the applicable catalogs and automatically adopts existing resources into deployment state.

Use plain elementum pull org when you also want editable organization resources such as categories and groups in organization.ts. The --data-only form refreshes lookup bags in org.ts without managing those resources.

elementum pull automation <automation-id> is a targeted recovery command for one app-owned Automation. Normal App pulls remain the primary way to reconstruct a complete App.

Automatic adoption

Normal pulls automatically connect the exported resources to the workspace’s deployment state. This process verifies all of the following before it succeeds:

• The expected resources are imported.
• The adoption would create, update, or destroy nothing.
• A follow-up plan is clean.

These checks prevent an existing deployed object from being mistaken for a new one. Use --no-adopt only when you intentionally need source without binding it to this workspace.

Pull commands write one JSON summary to standard output. Review its diagnostics and skipped items. If the summary reports a part of the solution that the EDK cannot reconstruct, do not assume that part is managed by the generated source.

Understand the Workspace

An organization workspace has this core structure:

<instance>/<organization>/
├── org.ts
├── organization.ts
├── generated/
│   └── catalog.ts
├── apps/
│   └── <appRef>/
│       ├── <appRef>.ts
│       ├── agents/
│       ├── automations/
│       ├── skills/
│       ├── visual-flows/
│       └── ...
├── elements/
│   └── <elementRef>/
│       ├── <elementRef>.ts
│       ├── search-tables/
│       └── ...
├── tables/
│   └── <tableRef>/
│       ├── <tableRef>.ts
│       └── search-tables/
├── tasks/
│   └── <taskRef>/
│       └── <taskRef>.ts
├── backend.tf                 # optional user-owned backend declaration
├── terraform.tfstate         # local compatibility state when no backend is declared
└── .tf/
    ├── in/
    └── out/

Each path has a specific owner:

• organization.ts contains editable organization resources pulled by plain pull org.
• apps/, elements/, tables/, and tasks/ contain editable source.
• org.ts contains organization reference tokens, such as CloudLinks and connectors. Refresh it with pull org --data-only; do not edit it.
• generated/catalog.ts is a generated barrel over authored entities. Its @catalog alias provides typed cross-entity references. Do not edit it.
• .tf/in/ contains temporary pull input. Pull commands own it.
• .tf/out/ contains generated deployment configuration. elementum build owns it.
• Deployment state binds authored labels to deployed objects. Do not hand-edit it.

Do not commit .tf/ or .terraform/. A workspace without backend.tf uses the root terraform.tfstate compatibility mode. Shared workspaces and CI should use a committed, non-secret backend.tf with verified state locking; backend credentials belong in the backend’s environment or workload identity, not in source.

Author Typed Source

Import builders from public EDK package subpaths and cross-entity references from @catalog:

import { app } from "@elementumai/edk/app";
import { element } from "@elementumai/edk/elements";
import { actions, automation, onDemand } from "@elementumai/edk/automations";
import { agent } from "@elementumai/edk/agents";
import { skill } from "@elementumai/edk/agents/skills";
import { organization } from "@elementumai/edk/organization";
import { table } from "@elementumai/edk/tables";
import { task } from "@elementumai/edk/tasks";
import { visualFlow } from "@elementumai/edk/visualFlows";
import catalog from "@catalog";

Ownership is explicit:

• Organization resources live in organization.ts; Tables and standalone Tasks live at the organization root.
• Apps own Agents, platform agentic Skills, Approval Processes, Visual Flows, and app-owned Automations.
• Elements and Tables can own Search Tables; Apps cannot.
• Apps and Elements can own File Readers.

Typical references include:

catalog.support
catalog.support.fields.status
catalog.support.automations.notifyOwner
catalog.aiProviders.anthropic.models.claudeHaiku_4_5

Use names and typed tokens in authored source. Do not paste UUIDs into TypeScript. If a reference is missing, refresh organization references or pull the owning App instead of guessing an identifier.

Identity follows the source structure:

• The App or Element directory and root filename supply its source ref.
• An app-owned file’s stem supplies that entity’s ref.
• A field’s key in fields is its stable authored identity; name is its display label.

Changing a display name is different from changing a file stem, namespace, handle, or field key. Treat the latter as an identity change and review any replacement or removal in the plan.

Preserve unrelated pulled fields, layouts, list views, and child entities. Build diagnostics may identify options that cannot be represented safely. Resolve or report those diagnostics; do not silence them with casts, guessed tokens, or generated-file edits.

Scaffold New Source

Create new authoring files without contacting the platform:

elementum new app \
  --name "Support Tickets" \
  --namespace support \
  --category "Operations"

elementum new element \
  --name "Locations" \
  --namespace locations \
  --category "Operations"

elementum new automation --app supportTickets --name "Assign New Ticket"

new app and new element register their catalog references immediately. Use elementum new agent or elementum new skill for other app-owned authoring files.

Run elementum generate after hand edits that change the catalog surface, such as adding an Automation output or copying an authoring file:

elementum generate
elementum generate apps/support

Do not hand-edit generated/catalog.ts.

The new automation and pull automation commands support app-owned Automations only; element-owned Automation authoring is not yet supported. Some Automation trigger and action kinds are reported but skipped during pull, and dynamic picklist filtering and sorting are not supported on the build/pull path.

Treat the pulled TypeScript as the authoritative authoring surface for each EDK-managed object. Coordinate platform UI edits with the team and pull again before continuing in code; simultaneous edits can produce unexpected plan changes.

Validate in Order

Run each layer separately from the organization workspace:

npx tsc --noEmit
elementum plan

1. tsc checks the authored TypeScript and typed references.
2. plan builds the current source, then compares the complete workspace with the state and target environment.

plan does not replace the standalone TypeScript check. It also does not deploy an individual file when you pass a nested path; the path locates the organization root, and the complete workspace is planned.

Run elementum build separately only when you want to generate and inspect .tf/out/ without contacting the platform.

Review every create, update, replacement, and removal before running elementum apply. Stop if the plan contains an unexplained replacement, removal, or recreation of an object that already exists.

Work with the Authoring Agent

When you delegate EDK work to a coding agent, provide:

• The business outcome and affected personas.
• The profile, organization workspace, and App or Element namespace.
• The source that must remain unchanged.
• Required dependencies, available models, and expected automation publication behavior.
• A requirement to pull before editing and preserve existing identities.
• A requirement to run tsc and plan before applying.
• A clear approval boundary for apply.

Ask the agent to explain diagnostics and every planned lifecycle action in business terms. A clean plan is still subject to your review before apply.