# The .ondaclip folder

> Everything Ondaclip reads in your repository, file by file, how the formats are versioned, and what your AI agent does before changing them.

Ondaclip reads a single folder in your repository: `.ondaclip/`, at the root,
like `.github/`. You or your AI agent write it, so Ondaclip never has to
guess. Commit it, and change it through pull requests.

## The folder

For one product (one app in the repository):

```
.ondaclip/
  config.yaml            the settings: languages, the app, sign-in, voices, cloud
  publication.yaml       the published tutorials, in chapters
  tutorials/
    invite-a-colleague.yaml   one file per tutorial
  fixtures/              files a tutorial attaches (optional)
  tutorial.config.cjs    code for what YAML cannot say (optional)
  README.md              a short note for your team (optional)
  .gitignore             output/
  output/                what Ondaclip makes: videos, captures, reports. Never committed
```

Every product has a name in `.ondaclip/`, and the settings list it under
`products:`, starting with the first product. When a repository gets a second
product (an admin panel next to the app, a mobile app), you just add a block.
Nothing moves: the first product keeps its folders and keeps working.

```yaml
# .ondaclip/config.yaml
version: 1
locales: [en-US]
appEnvironment: dev
# … the settings every product shares
products:
  app:
    name: My app
    tutorials: tutorials           # the first product: .ondaclip/tutorials/
    publication: publication.yaml
  admin:                           # added later: .ondaclip/admin/tutorials/
    name: My admin
    appUrl: https://admin.example.com
    publish: { targets: { dev: gs://my-bucket/admin } }   # your infrastructure only
```

```
.ondaclip/
  config.yaml            shared keys, then products: { app: …, admin: … }
  tutorials/             the tutorials of app (tutorials: tutorials)
  publication.yaml
  admin/
    tutorials/
    publication.yaml
  output/app/  output/admin/
```

A product's own keys go in its block and override the shared ones (key
groups are merged one level deep). Each product publishes to its own
destination. The studio writes `products:` for every new product and names it
(`app` by default; see Settings, Source).

**Short form for a single product.** A `config.yaml` without `products:`
describes one product: every key at the top level, and its tutorials in
`tutorials/`. This is still valid. The studio can still give it a name
(Ondaclip v0.56.0 or later), so adding a second product later works the same
way: write `products:` with the first product as `tutorials: tutorials` and
`publication: publication.yaml`, then add the new one.

| File | What it holds | Page |
|---|---|---|
| `config.yaml` | All settings for the product, or for each product | [config.yaml](/docs/configuration/) |
| `tutorials/<id>.yaml` | One tutorial: its account, steps, shots and quiz | [The tutorial file](/docs/tutorial-format/), [Actions and targets](/docs/actions/) |
| `publication.yaml` | Which tutorials are published, in which chapters and sections | [The publication list](/docs/publication-list/) |
| `fixtures/` | Files for `attach` (an image, a PDF): fictitious data only | [Actions and targets](/docs/actions/) |
| `tutorial.config.cjs` | JavaScript for a sign-in or local startup that YAML can't describe. Ondaclip never runs it on Ondaclip Cloud | [config.yaml](/docs/configuration/) |

Never put secrets in the folder. Demo accounts are set in the studio and
stored encrypted: by Ondaclip on Ondaclip Cloud, or in your Secret Manager on
your infrastructure.

## Versions

There are two version numbers, and they mean different things:

- **The file format**: `version: 1` at the top of `config.yaml`. Format 1
  only grows: Ondaclip adds keys but never removes or changes them. A file
  that's valid today stays valid. A breaking change would become format 2,
  supported alongside format 1 for a while, with a migration page and
  `validate_config` telling you what to change.
- **Ondaclip itself**: v0.47.0, v0.48.0… Each version can add keys to
  format 1. Keys added after the `.ondaclip` folder was introduced (v0.22.0)
  are marked **since vX** in the docs. If a product runs an Ondaclip version
  older than a key in its files, it stops before the shoot, in Ready to film,
  and shows the key and the version you need. Update it in the studio
  (Settings, Where it runs). See [Ondaclip versions](/docs/versions/).

| Key | Since |
|---|---|
| `testIdAttribute`, `platform`, `android` | v0.42.0 |
| `pullRequests` | v0.43.4 |
| `appUrl`, `products` | v0.47.0 |
| A product name in the studio for a file without `products:` | v0.56.0 |
| `demoData` | v0.48.0 |

## Check a file before you commit it

- **JSON schemas**, for your editor and your agent:
  [config.schema.json](/docs/config.schema.json),
  [tutorial.schema.json](/docs/tutorial.schema.json),
  [publication.schema.json](/docs/publication.schema.json). Add the line
  `# yaml-language-server: $schema=https://ondaclip.com/docs/config.schema.json`
  at the top of a file, and VS Code, Cursor and other editors check it as you
  type.
- **The Ondaclip MCP server**: `validate_config`, `validate_tutorial`,
  `validate_publication` (see [your AI agent](/docs/for-ai-agents/)).
- **Quote any text with a comma inside `{ }`**:
  `{ en-US: "One video, many languages." }`. Without quotes, YAML cuts the
  text at the comma and turns the rest into a key.

## What your AI agent does

Before it changes anything in `.ondaclip/`:

1. Read this page, then the page for the file it's changing.
2. Write the change, touching only the products, tutorials and keys you asked
   for. Ondaclip films exactly what the files say, nothing more.
3. Check it against the file's schema, or with `validate_config`,
   `validate_tutorial` or `validate_publication` through MCP.
4. Open a pull request. Ondaclip checks it like the rest of your code, and a
   person reviews the videos in the studio before anything is published.

Source: https://ondaclip.com/docs/ondaclip-folder/