# Finalize TOML Schema for Tab Configs

Linear: [APP-3575](https://linear.app/warpdotdev/issue/APP-3575/finalize-toml-schema-for-tab-configs)

## Summary

Replace the recursive `[layout]` / `[[layout.panes]]` TOML nesting in tab configs with a flat `[[panes]]` array where nodes reference children by string ID. This makes deeply nested split layouts readable and hand-editable, and ships a bundled Oz skill so users can generate tab configs from natural language.

## Problem

The existing tab config layout format uses recursive TOML tables (`[[layout.panes]]`, `[[layout.panes.panes]]`, etc.). At depth 3+ this becomes unreadable and error-prone for hand-editing. Users who want a 2x2 grid or deeper nesting have to mentally track nested array-of-tables syntax, which is a significant barrier to adoption.

Additionally, there is no guided way for users to create tab configs — they must hand-author TOML from scratch.

## Goals

- A flat, ID-referenced pane tree format that supports arbitrarily deep nesting while remaining readable.
- A bundled Oz skill (`tab-configs`) that generates valid tab config TOML from natural language descriptions.
- A default template that is ready to use out of the box (single terminal pane, uncommitted, with `commands = []` pre-populated).
- Tab color support (`color` field) matching launch config parity.

## Non-goals

- Supporting non-terminal pane types beyond agent and cloud (notebook, code, settings, etc.).
- Multi-tab or multi-window configs (tab configs define a single tab by design).
- Proportional/flex sizing of children within a split.
- Converting existing launch configs to the new tab config format.

## Figma

Figma: none provided. This feature has no new UI — it changes the file format and adds an Oz skill.

## User experience

### Creating a new tab config

1. User clicks `+` → "Create new tab config..." in the tab bar menu.
2. Warp writes the default template to `~/.warp/tab_configs/my_tab_config.toml` and opens it in the user's configured editor.
3. The template contains an active single-pane config with `commands = []`, and commented-out examples for two-pane split, 2x2 grid, and parameterized configs.
4. The template header mentions the Oz skill: "Ask Oz to generate a tab config for you!"

### Using the Oz skill

- User invokes `/skills → tab-configs` or asks Oz naturally (e.g. "create me a 2x2 tab config with one pane running my dev server").
- Oz generates a valid `.toml` file and writes it to `~/.warp/tab_configs/`.
- The file immediately appears in the `+` menu (the filesystem watcher picks it up).

### Opening a tab config

- User clicks `+` → "New Tab: <config name>".
- If the config has `[params]`, a modal appears for the user to fill in values.
- Warp opens a new tab with the specified pane layout, running any configured commands.
- If the config has a `color` field, the tab gets that color.

### Format behavior

- Pane layout is defined with a flat `[[panes]]` array.
- The first `[[panes]]` entry is the root of the tree.
- Split nodes have `split` (horizontal/vertical) and `children` (ordered array of child IDs).
- Leaf nodes have `id`, required `type` (`"terminal"`, `"agent"`, or `"cloud"`), optional `cwd`, optional `commands`, and optional `is_focused`.
- `terminal` opens a standard shell session. `agent` opens a terminal in Agent Mode. `cloud` opens a cloud mode (ambient agent) pane with no local shell.
- `cwd` and `commands` apply to `terminal` and `agent` types; they are ignored for `cloud`.
- `worktree_name_autogenerated` (optional, bool, default false): when `true`, Warp auto-generates the worktree branch name instead of prompting the user. The app detects worktree configs by scanning `commands` for `git worktree`.
- All children within a split are equally sized.
- If no pane has `is_focused = true`, the first leaf pane gets focus automatically.

### Error handling

- If the flat pane tree has validation errors (missing child references, duplicate IDs, fewer than 2 children in a split), the config falls back to a single empty terminal pane and logs a warning.
- Invalid TOML or missing `name` field causes the file to be skipped with a warning logged.

## Success criteria

1. A tab config using the flat `[[panes]]` format with a horizontal 2-pane split opens correctly: two side-by-side terminal panes, each with the specified `cwd` and `commands`.
2. A tab config using the flat format with a 2x2 grid (horizontal split → two vertical splits → four terminals) opens correctly with four equal-sized panes.
3. A tab config with `color = "blue"` opens with a blue tab.
4. A tab config with `is_focused = true` on a specific pane gives that pane initial focus.
5. A tab config with no `is_focused` gives focus to the first (leftmost/topmost) leaf pane.
6. A tab config with `[params]` shows the param-fill modal before opening.
7. A tab config with a `[[panes]]` format that has an invalid child reference logs a warning and opens a single empty terminal pane.
8. The `tab-configs` bundled skill appears in `/skills` in Warp.
9. The default template, when uncommitted and left as-is, parses as a valid single-pane tab config named "My Tab Config".

## Validation

- Unit tests for parsing and rendering the flat format (single pane, split, 2x2, focus handling, error cases).
- Manual verification: create a 2x2 tab config TOML, open it from the `+` menu, confirm four panes appear with correct `cwd` and `commands`.
- Manual verification: invoke the `tab-configs` skill and confirm it generates a valid TOML file that opens correctly.

## Open questions

(None outstanding.)