# Bridge a repository you do not own {#root}

@status:doc/work @audience:author,user

[p01] Some text you want your agent to read lives in a repository whose author has never heard of vibe. A bridge package makes it installable anyway: you steward someone else's repository and publish an ordinary package that wraps it, with the original's authorship and licence kept apart from yours.

[p02]
```prompt
Create a bridge package org.example/spec-kit in this project that wraps the repository https://github.com/example/spec-kit at its current release tag as a reference-backed source, keep the upstream authors and licence separate from ours, and check the package before I publish it.
```

- needs: the vibevm skill installed for your agent; network access to the upstream repository

outcome: a package slot with `bridge = true` and one `[[embedded_source]]` naming the upstream URL, commit and source hash; `vibe check` reports no errors

- assert: `vibe check --path vibevm/vibepacks/org.example/spec-kit/v0.1.0 --quiet`

## What happens {#what-happens}

[p03] The agent scaffolds the package with `vibe init package`, marks it as a bridge in the manifest, and declares the upstream repository as an embedded source: its public address, the exact commit, the hash of the source tree and the upstream licence. Installing the package fetches that exact source into the consumer's machine [store](../glossary/index.xml#store) beside the package's own files. The bridge never becomes a second package: the wrapped repository is git content the resolver knows nothing about.

> [p04] A **bridge package** closes the gap without the author's involvement: a
>   *maintainer* volunteers to steward someone else's repository and publishes an
>   ordinary vibevm package that **wraps** it.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-023#BRIDGE-DEF>

> [p05] `[package].bridge = true` marks a package as a bridge.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-023#BRIDGE-FLAG>

> [p06] Either way, the embedded repo is **not** a second vibevm package: it is git
> content, never entered into the dependency resolver
> ([PROP-002](PROP-002-decentralized-registry.xml): one git repo = one package;
>   the submodule is part of *this* package's content, not a node).
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-021#NOT-A-PACKAGE>

## Three ways to hold the upstream {#three-classes}

[p07] Vendored: you copied the upstream tree into the package and committed it. This is the cheapest bridge, plain files and the flag, with [hooks](../glossary/index.xml#hook) if the layout needs shaping. Submodule-backed: your workspace references the upstream through a git submodule, which a direct git install preserves live and which publication flattens into ordinary files. Reference-backed: the package repository holds only your metadata and adapters, and `[[embedded_source]]` names the upstream address, an immutable commit, the source-tree hash and the licence; installation fetches that exact source.

> [p08] **Vendored ("git in git")** — the maintainer copied the upstream tree into
>   the package and committed it. This needs **none** of PROP-021/022 machinery:
>   it is plain files in a `snapshot` package. A vendored bridge is therefore the
>   cheapest case — the flag (§2.1) plus, if the layout needs shaping, hooks.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-023#CLASS-VENDORED>

> [p09] **Submodule-backed authoring** — the maintainer workspace references upstream
>   through a Git submodule ([PROP-021](PROP-021-submodule-sources.xml)). A direct
>   Git-source install preserves that live Git composition. Registry publication
>   deliberately flattens a clean populated gitlink into ordinary package files,
>   removes `.gitmodules`, and reports `submodule <path> vendored at <sha>`;
>   the published package is therefore a truthful vendored snapshot, not a
>   dangling promise that consumers will recurse into the maintainer's repo.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-023#CLASS-SUBMODULE>

> [p10] **Reference-backed** — the package repository contains only maintainer-authored
>   metadata and adapters. `[[embedded_source]]` declares the original public Git
>   URL, an immutable full commit, an independently verified source-tree hash and
>   upstream licence provenance. Installation fetches that exact source directly
>   into the consumer's machine cache; selected `[[skill]]` content or
>   `[[skill.resource]]` files are projected from the authenticated cached tree.
>   The upstream is not copied into the bridge repository, is not resolved as a
>   vibevm dependency node, and its own `vibe.toml`, hooks and submodules are never
>   executed implicitly. The installed bridge itself remains a normal physical
>   `vibedeps` slot; source-aware loaders combine that owner root with named,
>   separately authenticated external roots without pretending the latter are
>   UPL package payload.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-023#CLASS-REFERENCE>

[p11]
```toml
[package]
name = "spec-kit"
group = "org.example"
kind = "flow"
version = "0.1.0"
bridge = true
license = "UPL-1.0"

[[embedded_source]]
name = "spec-kit"
url = "https://github.com/example/spec-kit"
commit = "0123456789abcdef0123456789abcdef01234567"
content_hash = "sha256:…"
upstream_authors = ["The Spec Kit contributors"]
upstream_license = "MIT"
```

[p12] A declared source is authenticated twice when it arrives: the checkout must be at the declared commit, and the hash of its tree must equal the declared one. A `ref_hint` such as a tag name is only for people to read and never chooses bytes.

> [p13] **dependency-declared** — a package's manifest uses `[[embedded_source]]`
>   to name an upstream Git source independently of the package repository. The
>   declaration carries a portable name, public credential-free HTTPS URL, full
>   immutable commit, expected `sha256:` source-tree hash, optional ref hint, and
>   upstream licence provenance. This supports snapshot/binary-distributed bridge
>   packages without copying the upstream tree into their repository.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-021#FORM-DEPENDENCY-DECLARED>

> [p14] A dependency-declared source is authenticated twice: its resolved checkout
>   must equal the declared commit and its deterministic source-tree hash must
>   equal `content_hash`. `ref_hint` is diagnostic only and never selects bytes.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-021#DECLARED-SOURCE-AUTH>

## Whose work it is {#whose-work}

[p15] `authors` in the manifest names the people who wrote the bridge, its metadata and adapters, never the authors of the wrapped bytes; every embedded source records its own `upstream_authors`, and listings, locks and [indexes](../glossary/index.xml#index-registry) keep the two lists apart. The same for licences: `license` describes the bridge alone, each source records its upstream licence and an immutable link to it, and a bridge never presents upstream bytes as relicensed. The [coordinate](../glossary/index.xml#coordinate) names the product a consumer installs, not the codebase the packaging was written in: a bridge of Spec Kit may live at `org.speckit/speckit` whoever maintains it.

> [p16] `[package].authors` names only the people or organisations that authored
>   the package's own metadata, adapters and other maintainer-owned payload. It
>   never absorbs the authors of referenced bytes. Every `[[embedded_source]]`
>   records those separately as a non-empty `upstream_authors` list. Listings,
>   locks and indexes preserve both lists under their own labels; they never
>   concatenate them into one ambiguous authorship claim.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-023#AUTHORSHIP-SEPARATION>

> [p17] A bridge records two distinct legal surfaces: `[package].license` describes
>   only the maintainer-authored bridge package, while every external embedded
>   source records its upstream licence and an immutable licence URL. A bridge
>   never presents upstream bytes as relicensed by the bridge maintainer.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-023#LICENSE-BOUNDARY>

> [p18] The package's qualified coordinate
>   ([PROP-008](PROP-008-qualified-naming.xml)) names the **product a consumer
>   installs**, not the codebase in which its packaging machinery happened to be
>   written. Packaging Spec Kit does not make it `org.vibevm/*`; its product
>   coordinate may be `org.speckit/speckit`. Packaging Matt Pocock's collection
>   may be `com.mattpocock/skills`. The distinct steward remains visible through
>   `[package].authors`, the package distribution `source_url`, `bridge = true`,
>   and the upstream repository/PURL recorded by `[[embedded_source]]` and
>   `describes`.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-023#GROUP-PROVENANCE>

## Submodules on the way in and out {#submodules}

[p19] vibe fetches a package's submodules when it fetches the package, updates them with it, and makes their content available wherever the package lands: copied into the snapshot for the copying modes, live for an in-place checkout. Publication is the boundary: a [registry](../glossary/index.xml#registry) repository is a self-contained snapshot, so the publisher checks that every populated submodule is at its indexed commit and clean, copies its files in, removes `.gitmodules` and reports what it flattened.

> [p20] vibevm fetches a package's submodules when it fetches the package, updates them
> when it updates the package, and makes the submodule content available wherever
> the package is materialised — embedded into the snapshot for the
> copy-based modes, or living natively for `in-place`
> ([PROP-022](../vibe-workspace/PROP-022-materialization-modes.xml)).
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-021#WHAT-VVM-DOES>

> [p21] **Publication boundary.** Workspace/direct Git source acquisition may carry
> real submodules, but a per-package registry repository is a self-contained
> package snapshot. Publish inspects each populated gitlink before copying,
> requires its checkout to match the indexed commit and be clean, copies its
> files as ordinary payload, drops `.git` and `.gitmodules`, and reports the
> path plus exact vendored commit. Registry consumers therefore fetch no hidden
> second repository; `resolved_commit` identifies the published package repo,
> while the publication report preserves the flattened upstream evidence.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-021#PUBLISH-FLATTENS-GITLINKS>

## Edge cases and rules {#edge-cases}

[p22] A bridge is published and installed like any package; what it adds is provenance. The upstream can move on without you: bumping the bridge means changing the declared commit and hash, and publishing a new version.