> ## 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.

# Authoring

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

<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>

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.

<Info>
  Read the [EDK overview](/edk/getting-started) first. An organization workspace must contain the files created by `elementum pull org --data-only` before you pull other entities.
</Info>

The examples below assume you are working inside an organization workspace with one matching saved profile. See [Authentication](/edk/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:

```bash theme={null}
elementum auth status
elementum list apps
elementum list elements
elementum list tables
```

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

```bash theme={null}
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:

```text theme={null}
<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`:

```ts theme={null}
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:

```ts theme={null}
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.

<Note>
  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.
</Note>

## Scaffold New Source

Create new authoring files without contacting the platform:

```bash theme={null}
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:

```bash theme={null}
elementum generate
elementum generate apps/support
```

Do not hand-edit `generated/catalog.ts`.

<Info>
  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.
</Info>

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:

```bash theme={null}
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.