Skip to content

docs(blocks): a worked guide for running many locations from one set of prompts - #98

Closed
dhruva-vapi wants to merge 2 commits into
feat/blocksfrom
docs/many-locations-guide
Closed

dhruva-vapi wants to merge 2 commits into
feat/blocksfrom
docs/many-locations-guide

Conversation

@dhruva-vapi

@dhruva-vapi dhruva-vapi commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Value

V.A.L.U.E. tier: micro. One guide and the links to it. No engine change.

  • Problem: the blocks page is a reference. Someone who runs the same agent at several locations, with the shared wording pasted into every assistant, has no page that takes them in order from that state to "one edit, one command, every location". They also have to work out for themselves how a block edit moves through a pull request, PR checks and promotion. Small edit since first push: the blocks page said "to discard the dashboard edit, change nothing", which holds only for a value the file sets, so that sentence now says what the push puts back, what it leaves, and how to clear a field the file does not set.
  • Who it affects: teams running several locations from this repository, most of all people who have not worked with pull requests much.

What's in it

One new page, docs/guides/many-locations.md, that follows the example's two clinics through the whole job:

  1. Why pasted copies drift, and what a block changes.
  2. Moving shared wording into templates/blocks/ and shared settings into templates/config/, with the one-line marker for each.
  3. The first deploy.
  4. One location with its own wording (its own block under resources/<org>/templates/) and its own setting (a key beside $include), and what "the file's own keys win" does across later block edits.
  5. Changing a shared block: on a branch, in the pull request, after the merge, and when someone edited an assistant in the dashboard.
  6. Promotion between orgs.
  7. What pull does with a file that uses blocks.
  8. The limits: a marker with no block is refused, a Liquid variable nobody defines is not caught, and the Liquid file tag and the YAML merge key are warnings.

README, the blocks, promotion and file-formats pages, the example's README and AGENTS.md link to it. The reference pages keep their role, and the guide links to them instead of repeating them.

The guide also states three things the reference pages leave implicit. Each was seen in the run described below:

  • Promotion copies every file that matches the pipeline's patterns to the next org, so a location's own edit in such a file travels with it.
  • A block used only by files outside those patterns is not pushed by promotion, and stays on the sync-blocks list.
  • Pushing a file with --resolve=ours does not remove a setting that exists only in the dashboard.

Verification

  • Every command in the guide was run in a scratch copy of the branch below this one, with the example's two clinics, against a local stub of the API. The output in the guide is what those runs printed. Nothing was run against a live org, and the guide says so under "How this page was checked".
  • Not run: anything that happens during a call (filling a variable), the two GitHub workflows, and a live simulation. The guide lists these too.
  • The docs tests that cover the change pass: tests/docs-links.test.ts 1/1, tests/docs-commands.test.ts 2/2, tests/examples.test.ts 4/4, tests/agent-docs.test.ts 4/4. The full suite was left to CI.

Things to know

  • Docs only: nothing under src/ or tests/.
  • The names (@include, $include, templates/blocks/, templates/config/, sync-blocks) are written as the code has them today. If one changes, the guide changes with the reference page.
  • The note that a dashboard-only setting survives the push, and that null in the file clears it, rests on the stub. The first matches the PATCH rule in docs/learnings/assistants.md. Neither has been tried on a live org, and both pages say so.
  • The guide does not cover sharing one assistant between squads with different variable values per squad. That has not been tested, so it is not offered as a recipe.

Stack

Fourth of four. Sits on #94 (blocks), which sits on #96 and #97.

Copy link
Copy Markdown
Contributor Author

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

This stack of pull requests is managed by Graphite. Learn more about stacking.

@dhruva-vapi
dhruva-vapi force-pushed the docs/many-locations-guide branch from aa555eb to e71506f Compare November 19, 2026 16:31
@dhruva-vapi
dhruva-vapi marked this pull request as ready for review November 20, 2026 18:24
dhruva-vapi and others added 2 commits November 21, 2026 03:53
…of prompts

The blocks page is a reference. This adds the path through it for someone
who runs the same agent at several locations: move pasted wording and
settings into blocks, deploy, give one location its own wording or setting,
change a shared block through a pull request, roll it out, and what
promotion and pull do along the way.

Every command in the guide was run in a scratch copy with the example's two
clinics against a local stand-in for the API, and the page says so. It also
states three things the reference pages leave implicit: promotion copies
every file in the pipeline's patterns, a block used only outside those
patterns stays on the sync-blocks list after a promotion, and pushing a file
does not remove a setting that exists only in the dashboard.

The blocks page said "to discard the dashboard edit, change nothing". That
holds for a value the file sets. It now also says that a field the file does
not set stays as the dashboard left it, and that naming the field in the
file is how to clear it, marked as seen on the stand-in.

README, the blocks, promotion and file-formats pages, the example's README
and AGENTS.md link to the guide.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@devin-ai-integration

Copy link
Copy Markdown
Contributor

Replaced by #112 (same commits rebased onto main, opened as the Devin bot so it can be approved).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant