Skip to main content
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.
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

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.

​
A Minimal Example

A weekly playbook is two files in one folder:
playbooks/weekly-revenue/weekly-revenue.playbook
playbooks/weekly-revenue/prompt.md
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 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.
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: 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.
  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.

Config File Reference

File syntax, references, and every field for each object.

Role & Access

Folder access and code owners.

Build Your Ontology

GitHub sync, the editor, and the Reviews and History tabs.

Playbooks

What a playbook does and how it runs.