The .ondaclip folder

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.

.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
tutorials/<id>.yaml	One tutorial: its account, steps, shots and quiz	The tutorial file, Actions and targets
publication.yaml	Which tutorials are published, in which chapters and sections	The publication list
fixtures/	Files for attach (an image, a PDF): fictitious data only	Actions and targets
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

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.

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, tutorial.schema.json, 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).
• 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.