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

# EDK Authoring

> Pull existing Elementum entities, understand the workspace structure, and modify entities using builders and the typed `@catalog`.

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

Authoring in the EDK means editing TypeScript source that represents the entities in your Elementum organization. This page covers how to pull existing entities into your workspace, the structure of the generated files, and how to write changes using the EDK's builders and typed `@catalog` references.

<Info>
  If you haven't set up your workspace yet, start with the [Getting Started](/edk/getting-started) guide. You need a completed `elementum pull org --data-only` before you can pull individual entities.
</Info>

## Pull Existing Entities

The EDK is designed for iterating on Apps and Elements that already exist in your organization — not for creating them from scratch. Create new objects in the Elementum platform first, then pull them into your EDK workspace to continue authoring in TypeScript.

<Note>
  Starting in the platform lets Elementum assign the initial namespace, handle, and layout defaults, and gives the EDK a clean, deployed starting point. Creating an App or Element directly in EDK source is not the recommended workflow.
</Note>

`pull org --data-only` creates the organization workspace but does not pull every App and Element as editable source. Pull the specific entities you plan to modify with the commands below.

### Pull an App

Pulling an App requires its aspect ID. You can look this up from the CLI with [`elementum list apps`](/edk/cli-reference#list), or find it in the platform using your browser's developer tools:

<Steps>
  <Step title="Find the App's aspect ID">
    Open the App in the Elementum platform, then open your browser's developer tools and switch to the **Network** tab. Filter the requests for `graphql?apollo_op=GetAspectNamespace`.

    In the response, copy the `id` value nested under `aspect`. The response contains two IDs — one for the organization and one for the aspect — so make sure you copy the one under `aspect`, and leave out the surrounding quotation marks.
  </Step>

  <Step title="Pull the App into your workspace">
    Run `pull app` with the ID you copied:

    ```bash theme={null}
    elementum pull app --id <app-aspect-id>
    ```

    Depending on how much the App contains — automations, related objects, and so on — this can take some time. When it finishes, the App appears as a TypeScript file in your workspace under `apps/`.
  </Step>
</Steps>

### Pull an Element

```bash theme={null}
elementum pull element --id <element-id>
```

## Workspace Structure

After `pull org` and a few `pull` commands, your workspace looks like this:

```
<instance>/
└── <organization>/
    ├── generated/
    │   ├── catalog.ts
    │   ├── mapping.json
    │   └── state.<environment>.json
    ├── apps/
    │   └── <appRef>/
    │       ├── <appRef>.ts
    │       ├── generated/catalog.ts
    │       ├── agents/
    │       ├── automations/
    │       ├── skills/
    │       ├── flows/
    │       ├── search-tables/
    │       └── approvalChains/
    └── elements/
        └── <elementRef>/
            ├── <elementRef>.ts
            ├── generated/catalog.ts
            └── search-tables/
```

Each entity you pull becomes a folder under `apps/` or `elements/`, with the entity's TypeScript definition at the top and sub-folders for its child entities.

### Rules of the Workspace

These rules protect deployed identities and keep planning reliable:

* **Identity bindings live in `generated/state.<environment>.json`.** Do not hand-edit state or mapping files — they map your source to deployed UUIDs and are regenerated by the EDK.
* **Generated catalogs expose typed references for authoring.** The `generated/catalog.ts` files back the `@catalog` alias so you can reference fields, automations, and agents by their handle-tokens.
* **Do not place UUIDs in authored entity source.** UUIDs belong in generated state only. Use `@catalog` handle-tokens everywhere else.
* **Preserve existing `refName`s and handles** unless you're performing a deliberate identity migration. Changing a `refName` typically replaces the entity and can orphan existing records or relationships.

## Modify Entities with Builders and `@catalog`

The EDK exposes builder functions for each entity type. Import the builder you need from the appropriate subpath of `@elementumai/edk`, and reference other entities through the `@catalog` alias:

```ts theme={null}
import { defineAutomation, defineWorkflow } from "@elementumai/edk/automations";
import catalog from "@catalog";
```

Reference fields, automations, agents, and other entities by their handle-tokens — never by UUID:

```ts theme={null}
catalog.serviceRequestItsm.fields.status
catalog.managedEntities.fields.entityName
catalog.knowledgeItsm.automations.publishNewArticle
```

Because `@catalog` is typed, TypeScript will flag broken references before you plan. If a field or automation you expect to see is missing from `@catalog`, run `pull org` or `pull` again to refresh the generated catalog.

## Type-Check Your Changes

Run the standalone TypeScript check whenever you make changes:

```bash theme={null}
npx tsc --noEmit
```

A project-level `tsconfig.json` is required for this command to produce useful output.

The EDK also performs entity-specific TypeScript checks during `plan`, but `tsc --noEmit` catches most authoring mistakes faster and without hitting the platform.

<Warning>
  A clean `tsc --noEmit` does **not** guarantee that all referenced platform handles exist in the deployed environment. TypeScript only sees what's in your generated catalog. If a handle is present in your source but not yet deployed, `plan` will report it as blocked — see [Debug blocked plans](/edk/plan-and-apply#debug-blocked-plans).
</Warning>

## Work with the Authoring Agent

The EDK Authoring skill teaches your IDE's coding agent how to build EDK projects correctly. When you delegate authoring work to an agent, give it enough context to make good decisions:

1. **The business outcome and process lifecycle** — what the change is meant to accomplish.
2. **The exact workspace and target App or Element** — for example, `dev/my-org/apps/knowledgeItsm`.
3. **An instruction to inspect current source, generated catalogs, and deployment state first** — before writing new code.
4. **A requirement to preserve deployed identities** — no new `refName`s for existing entities, and use `@catalog` for all cross-references.
5. **A requirement to run `plan` before `apply`** — never apply without a reviewed plan.
6. **Whether new Automations should be `DRAFT` or `ACTIVE`** — the agent will otherwise guess.
7. **Permission boundaries** — for example, "no apply until I've reviewed the plan output."
8. **Available models and supporting entities** — tell the agent which models your organization has and which other Elements or Apps the change depends on. Pulling related entities into the workspace gives the agent the full context it needs to build a complete process.

<Tip>
  The EDK Authoring slash command in your code editor loads the current skill prompt automatically. Following that with the items above gives the agent the specific business and environment context the skill can't infer on its own.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Plan and Apply" icon="rocket" href="/edk/plan-and-apply">
    Preview the structural diff, deploy new fields in stages, and verify convergence.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/edk/cli-reference">
    Every `elementum` command grouped by prefix, with usage and flags.
  </Card>
</CardGroup>