Bridge Overlay — subscribe to an org's config bundle

An org overlay is a git repo an organisation publishes so its members' Bridges can share config without each person hand-copying files. It mirrors a flat tree of files (tree/<path> → <path>), every file scope: org, declared by a root overlay.manifest.yaml. /overlay is the consumer side: it subscribes, materializes COPIES under a lockfile, and keeps them in sync.

It is the mirror-image of the push skills:

Read the referenced file ONLY when triggered.

When to use

• An org gives you a git URL: "subscribe your Bridge to our overlay"
• You want the org's shared contexts / projects / mandants / accounts / org skills materialized locally and kept current
• You already subscribed and want to pull updates (sync), preview them (diff), re-materialize offline (apply), check freshness (status), or end the subscription (remove)

NOT for:

• Publishing an overlay (that's the org's job — see references/authoring.md)
• Pushing YOUR changes upstream (/promote, /bridge-sync)
• One-off file copies with no ongoing subscription (just copy the file)

What an overlay carries

An overlay ships an org's scope: org building blocks as a flat tree/ mirror — config AND tools, so one git-URL is a complete org bridge, not just config:

Skills ship COMPLETE. A skill is a directory: SKILL.md declares the tier in its metadata.scope; the sibling scripts/, references/, assets/ carry no inline scope and inherit the tier of their SKILL.md (resolved from the overlay SOURCE, so a fresh add ships the scripts too — they are NOT refused as CORE). A markdown-only skill and a script-bearing skill both transfer whole. Exception: this only covers scripts living inside the skill's own directory (skills/<name>/scripts/). Several scope: core skills (e.g. tracker-sync, workspace, this skill) instead call a shared repo-root engine (scripts/<name>.py) that ships with the Bridge repo itself, outside any skill folder — that script is not part of the skill directory and is not materialized by an org-overlay add.

Don't ship framework as org. A skill/agent that already exists in the consumer's CORE (e.g. a generic bridge-* tool, or a scope:core sub-agent like archivist) must NOT be in the overlay — it collides (user-owned) and would clobber the canonical core copy. Carry only what is genuinely org-specific; leave framework to the framework. The CORE-refusal gate stops anything that classifies core, but a core tool mis-tagged scope: org in the source slips that gate — so exclude it at authoring time (the publish guard + a user-owned count in status are the backstops).

The 7 commands (/overlay <cmd>)

Engine: scripts/overlay.py — a shared repo-root utility shipped with the Bridge repo itself, not a file inside this skill's own directory (the deterministic implementation). The full 17-step sync algorithm, conflict/precedence model, and 3-way base recovery live in references/workflow.md.

HARD GATES (non-negotiable)

1. Refuse off user/*. CORE branches (main / development) never materialize. An overlay writes USER-tier files onto a user branch only.
2. CORE-refusal (path-authoritative). Never materialize a dest that classifies core, is _-prefixed, is a cluster-wrapper README.md, is a _template/_schema, or path-escapes the tree. Path classification wins: an inline scope: org line can only re-tier a dest on a frontmatter-bearing path (skills/, .claude/agents/, identity/agent/{IDENTITY,SOUL}) — it can never smuggle a CORE file (rules/, docs/, scripts/, …) past the gate. An overlay ships scope: org content only — it can never overwrite CORE. Entry files (CLAUDE.md, CLAUDE.local.md, .claude/CLAUDE.md, AGENTS.md) and identity/agent/INSTANCE.md are refused by name, before classification.
3. Behavioural [y], one per unit. A skill / agent / standing-order requires an explicit [y] when a file of it arrives for the first time (shown in the preview). A skill folder is one unit, all or none, so a SKILL.md never lands without the reference it routes to. config / rule files batch-confirm. --yes is valid non-interactively for non-behavioural files only; a behavioural unit is then withheld whole, and status counts it as pending-confirm. Interactively, a answers yes to every remaining gate of the run; an unknown answer repeats the question. Deleting a file or overwriting the consumer's own file is asked one by one, a never covers it.
4. Leak gate BEFORE write. Every staged file passes a raw-secret regex (accounts = azure-keyvault:// / keychain:// / 1password:// URI refs only) on the staged temp file; the no-scrub-leak.py CORE-boundary scan runs only when the materialize target is itself core (never for an org overlay — its org names/emails are not a leak). A hit refuses that file, surfaces it, and continues the rest.
5. Never clobber a user edit. A locally-modified dest goes through 3-way merge (overlay = lower layer, user = upper). Markers / a GC'd base escalate to a prompt — the engine never silently overwrites your edit.
6. Never push. /overlay reads from the overlay and writes into your working tree. It never pushes your branch anywhere and never opens a PR.
7. Never auto-merge config, never write an entry file. The fragment lands at the root and Phase 1 indexes it (context-index.py --registries), never block-merged into ecosystem.yaml. The engine writes no import and never touches AGENTS.md or CLAUDE.md; a leftover line in a legacy CLAUDE.md is reported, not edited. A root CLAUDE.md is always refused. No config file is structurally merged. The fragment itself is a managed file like any other: in the lock, 3-way merged on a local edit, listed by diff, deleted by remove only while clean.
8. Exclude the managed dests from git — by default. At materialize, the engine writes a marked, idempotent # >>> overlay:<name> block into the local, untracked .git/info/exclude (never the tracked .gitignore) listing every managed dest — because skills/agents land in tracked paths (skills/, .claude/agents/) that config patterns don't cover, and a fork of a public repo is itself public: without this a git add -A would publish org-internal content. Using .git/info/exclude keeps the dests ignored without touching any tracked file, so neither the content nor the org filenames can be published. The block is dropped on remove. Org content is consumed, not re-committed — unless the subscription sets materialize.track_managed_dests: true (off by default, /overlay add --track-managed-dests or a hand-edit + sync/apply): an explicit, per-overlay, self-service opt-in for a consumer (typically private) that wants its consumed org content backed up in its own git history instead of relying solely on the overlay's source repo. Never auto-derived from the consumer repo's visibility. Flipping the switch on drops any exclude block already written for that overlay on the next materialize, so it takes effect without a manual .git/info/exclude edit. Full model: docs/org-overlays.md § Git tracking of managed dests.

Authoring note — org facts mirror VERBATIM, not as prompt-fields

A prompt_field in the manifest marks a value a consumer may override (it is prompted interactively; under --yes the source value is kept). Do not mark a shared org fact — a GitHub board number, an org recipient email — as a prompt-field: it is the same for every consumer, so it must mirror verbatim. Mis-modelling an org fact as a prompt-field is a real footgun (an automated/--yes run, or a fat-fingered y at the value prompt, silently overwrites the org fact — and it is valid YAML, so parse checks sail past it). Reserve prompt-fields for genuinely per-consumer values; ship org facts plain. A consumer that must diverge edits the file locally — the 3-way merge protects that edit on re-sync.

Testing (required) — the engine is test-locked

The engine scripts/overlay.py is covered by scripts/tests/test-overlay.sh (deterministic, model-free — it drives the REAL engine against a throwaway copy of the tree). Any engine change MUST keep the suite green AND add a case for the new behaviour. Run before every commit:

bash scripts/tests/test-overlay.sh        # must end "N passed, 0 failed"

The suite's 25 sections assert, among others:

• subscribe + materialize (every dest exists · inline scope: org · lock hashes); idempotent re-apply; dry-run writes nothing; remove restores a clean tree
• 3-way merge (clean + conflict) · precedence · CORE-refusal · path-traversal
• §16 prompt-field override survives a re-sync — scalar restore, no silent clobber; §18 a wildcard [*] override never cross-wires to the wrong element
• §17 leak gate — real secrets (base32/hex, AccountKey=, totp_secret) refused; URI / ${} / comment / prose pass; code files skip the assignment heuristic but still get the format scan (api_key = get() passes, an AKIA… literal in a .py is caught)
• §19 a scope:org skill ships COMPLETE — its scripts materialize (inherit the SKILL.md tier), never CORE-refused
• §21 CORE-refusal is path-authoritative — an inline scope: org on a core path (rules/, scripts/) is still refused; a real org SKILL.md/agent still ships (the carve-out doesn't over-refuse); every entry file and identity/agent/INSTANCE.md is refused by name
• §22 ecosystem_fragment name is enforced in-engine (flat ecosystem.<org>.yaml) even on a consumer without check-jsonschema
• §25 the ecosystem fragment is a managed file: in the lock, listed by diff and --dry-run, a local edit survives a sync and the next upstream change (a merged edit is never laundered into materialized_sha256, tree files included), a conflict keeps the local side, remove keeps an edited fragment, a pre-fix lock is adopted without clobbering (also when its pinned blob is gone), a consumer's own registry from before the subscription is never merged into or removed, a fragment also shipped under tree/ is still materialized and indexed, a dropped fragment is pruned and leaves --registries
• §28 the overlay never writes an entry file: add, sync, --dry-run and remove create no CLAUDE.md and leave AGENTS.md byte-identical, with or without a declared card; a legacy CLAUDE.md that still imports the fragment stays byte-identical and each run prints a WARN naming scripts/migrate-entry-file.py
• §20 the default git-exclude guard — managed dests land in .git/info/exclude, git check-ignore confirms them ignored, .gitignore untouched; §23 the track_managed_dests opt-in — off by default is byte-identical to §20; --track-managed-dests writes no exclude block and the dests are normal trackable files; flipping an existing subscription's switch on and re-syncing drops its stale exclude block automatically

When carrying skills/agents in a real overlay, also smoke-test a full materialize before you publish — add --dry-run then status — and confirm zero user-owned (no framework skill rode along), zero leak-refused, and every skill's scripts/ present on disk. A user-owned count > 0 means a CORE tool is mis-tagged in the overlay; pull it out.

Decision Tree

User wants to...
├── Subscribe to an org overlay (git URL)   → references/workflow.md § add (Steps 1–17)
├── Pull updates / re-sync                   → references/workflow.md § sync
├── Re-materialize offline                   → references/workflow.md § apply
├── See freshness / drift counts             → references/workflow.md § status
├── Preview the next sync/apply              → references/workflow.md § diff
├── Unsubscribe (keep or drop files)         → references/workflow.md § remove
├── List subscriptions                       → references/workflow.md § list
├── PACKAGE an overlay for an org to ship    → references/authoring.md
└── Schemas (manifest / lock)                → docs/schemas/overlay-manifest.schema.yaml
                                                docs/schemas/overlays-lock.schema.yaml

Reference Files

Related Files

• docs/org-overlays.md — narrative + architecture for org overlays
• docs/schemas/overlay-manifest.schema.yaml — overlay.manifest.yaml schema
• docs/schemas/overlays-lock.schema.yaml — generated overlays.lock.yaml schema
• scripts/overlay.py — the engine /overlay drives
• infra/instances/_template.yaml — fleet record; the engine updates subscribes_overlays on the active instance