Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -434,7 +434,7 @@ For changes under `src/`, `tests/` or `.github/`:
| --- | --- |
| Every resource setting, with examples | [Resource reference](docs/guides/resource-reference.md) |
| Minimal tested files | [File formats](docs/guides/file-formats.md), [`examples/starter/`](examples/starter/README.md) |
| Shared prompt text and config | [Blocks](docs/guides/blocks.md), [`examples/blocks/`](examples/blocks/README.md) |
| Shared prompt text and config | [Blocks](docs/guides/blocks.md), [`examples/blocks/`](examples/blocks/README.md), [many locations walk-through](docs/guides/many-locations.md) |
| System prompts | [Writing system prompts](docs/guides/writing-prompts.md), [Vapi Prompt Optimization Guide](docs/Vapi%20Prompt%20Optimization%20Guide.md) |
| Commands, flags, test-call output | [Commands](docs/guides/commands.md) |
| Sync, conflicts, drift, output icons | [How the engine works](docs/guides/how-it-works.md), [sync behavior](docs/learnings/sync-behavior.md) |
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,7 @@ when run without arguments. Full flags and examples:
| [Everyday workflows](docs/guides/workflows.md) | Deploy, pull safely, recover from a bad deploy, clean up |
| [File formats](docs/guides/file-formats.md) | Write assistants, tools, squads, structured outputs and simulations |
| [Blocks](docs/guides/blocks.md) | Share prompt text and config between assistants, squads and orgs |
| [Many locations, one set of prompts](docs/guides/many-locations.md) | Run several locations from shared wording: a worked path from pasted copies to a rolled-out edit |
| [Resource reference](docs/guides/resource-reference.md) | Look up every setting, with examples |
| [Writing system prompts](docs/guides/writing-prompts.md) | Structure a voice agent's prompt |
| [PR checks](docs/guides/pr-checks.md) | Test every pull request with simulations |
Expand Down
22 changes: 21 additions & 1 deletion docs/guides/blocks.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,10 @@ Every snippet below is a file from [`examples/blocks/`](../../examples/blocks/),
two clinics that share a red-flags block and a voice. CI checks that the
snippets match the files and that the example passes `validate`.

This page is the reference. For the whole job in order, from pasted copies
to an edit rolled out through a pull request, see
[Running many locations from one set of prompts](many-locations.md).

## Prompt blocks

Put the shared text in a Markdown file:
Expand Down Expand Up @@ -311,10 +315,26 @@ to yours, which git and the engine ignore. To resolve a dashboard edit:
2. If the change is in text that comes from your file, make the same change
in your file. If it is in text that comes from a block, change the block
(every resource that uses it changes too) or give this org its own block.
To discard the dashboard edit, change nothing.
To discard a dashboard edit to a value your file sets, change nothing.
3. Run `npm run apply -- <org> --resolve=ours <file>`. It pushes your
version over the dashboard's.

The push carries only the fields your file sets (see
[PATCH semantics](../learnings/assistants.md#patch-assistantid-semantics-shallow-replacement-at-the-top-level-field)),
so what it undoes depends on the field. This was seen on a local stand-in
for the API, not on a live org:

- **A value your file sets is put back.** A greeting changed in the dashboard
went back to the greeting in the file.
- **A field your file does not set stays as the dashboard left it.** A
greeting added in the dashboard to an assistant whose file has no
`firstMessage` was still there after the push, and the next `pull` no
longer reported a dashboard edit.
- **To clear such a field, name it in your file.** Give it the value you
want. With `firstMessage: null` in the file, the engine sent the `null` and
the stand-in cleared the greeting. Whether Vapi accepts `null` for a given
field was not tried, so open the assistant after the push and check.

## Limits

- The drift check compares the dashboard with the last state *your* checkout
Expand Down
4 changes: 3 additions & 1 deletion docs/guides/file-formats.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,9 @@ Text or settings that several files share can live in one file under
prompt, or a `$include: <name>` key in any mapping. An org can replace a
shared block with its own. Syntax, merge rules and how a block change is
rolled out: [Blocks](blocks.md), with a tested example in
[`examples/blocks/`](../../examples/blocks/README.md).
[`examples/blocks/`](../../examples/blocks/README.md). For several locations
that share most of their prompts, start with
[Running many locations from one set of prompts](many-locations.md).

## TypeScript resources (`.ts`)

Expand Down
Loading
Loading