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

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Automations

> Define durable business automation as ordinary TypeScript programs.

An automation is a TypeScript program exported from a `*.automation.ts` file.
Its description identifies the program during deployment and execution.

```ts automations/archive-receipts.automation.ts theme={null}
import { automation } from "automate.ax"
import { archive, onNewEmail } from "automate.ax/gmail"

export default automation("Archive incoming receipts", () => {
  const email = onNewEmail()

  archive({ messageIds: email.messageId })
})
```

The default export must be the value returned by `automation(description, fn)`.
The callback defines the triggers, actions, signals, and dependencies that make
up the automation.

## Automation code is direct TypeScript

Automate.ax does not compile your program into a user-authored JSON graph. You
can organize repeated logic with ordinary functions and modules:

```ts theme={null}
import { markAsImportant, star } from "automate.ax/gmail"
import type { Signal } from "automate.ax"

function flagMessage(messageId: Signal<string>) {
  markAsImportant({ messageIds: messageId })
  star({ messageIds: messageId })
}
```

Calling the helper registers both actions. Because neither action consumes the
other's result, they can execute independently once `messageId` materializes.

## Compose synchronously

The automation callback runs synchronously to describe durable work. Actions do
not return promises; they return [signals](/concepts/signals) for eventual
outputs.

```ts theme={null}
const message = getMessage({ messageId })
log({ value: message.subject })
```

Do not `await` an action. Passing `message.subject` into `log` records the
dependency and allows Automate.ax to execute `log` after `getMessage` succeeds.

## Keep composition deterministic

Automate.ax replays automation code while planning and resuming durable work.
The same inputs must produce the same action and trigger call structure.

* Keep action and trigger calls in stable positions.
* Use signals for decisions based on event data or action results.
* Do not choose which durable calls exist using ambient time, randomness, or
  process-local mutable state.
* Put side effects in actions, not directly in the automation callback.

Use signal-aware control flow such as `filter` or `branch` when execution should
depend on runtime data. See [Signals](/concepts/signals).

## Projects and files

`automate init` creates an `automate.config.ts` file that identifies the
project. `automate deploy` discovers every `*.automation.ts` file beneath that
configuration directory and deploys them together.

The relative source path is the automation's stable identity within the
project. Renaming or moving the file removes the old identity and creates a new
one on the next deployment.