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

# Config Files

> Define playbooks, agents, dashboards, and data apps as reviewed, version-controlled files in your Ontology.

Config files let you keep your organization's playbooks, agents, dashboards, and data apps as files in the Ontology, next to the definitions they depend on. Each file is the source of truth for one object. Change the file and the object follows; add a file and a new object appears; delete it and the object goes away.

Because they are Ontology files, config files get everything the rest of the Ontology already has: review before a change goes live whenever approval is required, a full history with diffs, folder-level access, and optional sync with a GitHub repository.

> [!NOTE]
>
> **Availability:** Config files are a **Beta** feature, turned on per organization. Contact your TextQL representative to turn them on for your org.

## Which Objects Can Be Files

| Object | File | Where new objects are placed |
| - | - | - |
| Playbook | `<name>.playbook` | `playbooks/<name>/` |
| Agent | `<name>.agent` | `agents/<name>/` |
| Dashboard | `<name>.dashboard` | `dashboards/<name>/` |
| Data app | `app.dataapp` inside the app's own folder | `apps/<name>/` |

A `.playbook`, `.agent`, or `.dashboard` file works in any folder; the folders above are only where TextQL puts the objects it writes for you. A data app is different: its folder is the app, so `app.dataapp` must sit in a folder of its own under `apps/`, with the app's code beside it.

Each object owns its folder. Supporting files, such as a playbook's prompt or a dashboard's Python code, live in the same folder, and one object's folder may not hold another object's file.

For the file format and every field, see the [Config File Reference](https://docs.textql.com/core/ontology/config-file-reference.md).

## A Minimal Example

A weekly playbook is two files in one folder:

```text playbooks/weekly-revenue/weekly-revenue.playbook theme={null}
Playbook {
  name = "Weekly revenue recap",
  prompt_file = "prompt.md",
  run_as = "sa:reporting-bot@acme.com",
  cron_string = "0 13 * * 1",
  schedule_timezone = "America/New_York",
  connectors = ["id:7"]
}
```

```markdown playbooks/weekly-revenue/prompt.md theme={null}
Summarize last week's bookings by region. Compare each region to the
prior four-week average and call out any region that moved more than 10%.
```

Once this change lands, the playbook exists and runs every Monday at 1 p.m. Eastern as the `reporting-bot` service account.

## How a Change Goes Live

**1. Edit**

Create or edit a config file in the Ontology editor, ask Ana to make the change in a Thread, or push it from a connected GitHub repository.

**2. Check**

Every change runs the same [checks](#checks) a save in the app runs. Errors block the change; warnings are shown but don't block it.

**3. Review**

If you may edit every file the change touches, it applies right away. Otherwise it waits in the **Reviews** tab for someone who can approve it. See [Permissions](#permissions).

**4. Sync**

Once the change lands, TextQL updates the objects it defines right away. A periodic sweep also catches anything missed, such as a change that arrived from GitHub.

## Editing From the App

A config-managed object stays editable on its own page. Its page shows that it is defined by a file in the Ontology, with a **View in Ontology** button that opens the file.

Saving on the object's page doesn't write to the object directly. It rewrites the file as a change:

* If the change passes its checks and you may land it, it applies immediately and the page reads **Saved**.
* Otherwise it is filed for review, and the page reads **Your change was filed as change #N and needs an approver**, with a link to the review.
* If someone else changed the object while you were editing, nothing is saved and the page reloads the latest version.

Either way the file stays the source of truth, so an edit made in the app and an edit made to the file are the same thing and show up in the same history.

A dashboard's **Publish** and **Discard** buttons don't apply to a config-managed dashboard: the file, not a draft, decides what it shows.

## Sync Status

Each config-managed object tracks whether it matches its file:

| State | Meaning |
| - | - |
| Syncing | A change landed and the object is being updated. |
| Synced | The object matches its file. |
| Sync error | The file couldn't be applied. The object is disabled and won't run until the error is fixed. |

A sync error is shown on the object's page with the reason, and flagged on the file in the Ontology file tree. Fix it by changing the file. Temporary infrastructure problems are retried automatically and are never recorded as a sync error.

## Checks

The same checks run on every save in the app and every change to a config file, so a file that passes is a file that runs. Some examples:

* The file parses, and its required fields are present.
* `run_as` names a real member or service account.
* Connectors, dashboards, and other objects the file refers to exist and the runner can use them.
* The model, schedule, and time zone are valid for your organization.
* Slack channels, Teams channels, and email recipients resolve.
* Long prompts live in a separate prompt file.

**Errors** block a change. **Warnings** are shown on the change and on the object but don't block it. A failing object shows a **checks failing** button listing each finding.

### Automatic fixes

Some warnings have a safe, mechanical fix, such as removing a reference to a connector that no longer exists or moving a long prompt into its own file. Once a day, TextQL applies those fixes for your organization as a single change authored by **Autofix**. A fix only rewrites what it matches exactly and leaves anything ambiguous for you. If the change can't land on its own, it waits in the **Reviews** tab like any other.

## Permissions

Editing a config file needs two things:

1. **Folder access:** Editor on the file's folder. See [Role & Access](https://docs.textql.com/core/ontology/ontology-rbac.md).
2. **The object's own write permission:** for example, the permission to edit playbooks for a `.playbook` file, set in **Settings → Roles**. This is the same permission the object's own page checks.

A role with general Ontology edit permission but without the object's permission sees config files as read-only, but can still propose a change for review.

Access to a config-managed object itself comes from its folder: Viewer on the folder makes a role a viewer of the object, and Editor makes it an editor. Admins always have access. An object created in the app is owned by its creator from the moment it exists.

### Runners

Every config file names a runner in `run_as`: the member or service account whose access the object uses when it runs. Because a runner grants the object that identity's access, a change that sets `run_as` needs consent:

* `run_as = "user:<email>"` must be approved or authored by that member, or by an admin.
* `run_as = "sa:<email>"` must be approved by someone who holds every role the service account holds.

### GitHub

If your Ontology syncs with a GitHub repository through pull requests, changes land through those pull requests, so a save in the app waits for review instead of applying immediately. Changes merged in GitHub are picked up automatically.

## Turning Config Files On and Off

When config files are turned on, TextQL writes your existing playbooks, agents, dashboards, and data apps into the Ontology for you, one folder per object, with no review needed. Each object keeps its id, history, and access; its existing sharing is carried into its folder's access. A dashboard moves once it is published and has no unpublished edits.

When config files are turned off, the files leave the Ontology and each object goes back to being edited only in the app, with the same id and history. Turning them on again writes the files back.

## Related

> **[Config File Reference](https://docs.textql.com/core/ontology/config-file-reference.md)**
>
> File syntax, references, and every field for each object.

> **[Role & Access](https://docs.textql.com/core/ontology/ontology-rbac.md)**
>
> Folder access and code owners.

> **[Build Your Ontology](https://docs.textql.com/core/ontology/build-your-ontology.md)**
>
> GitHub sync, the editor, and the Reviews and History tabs.

> **[Playbooks](https://docs.textql.com/core/how-it-works/playbooks.md)**
>
> What a playbook does and how it runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.