Private Project Collaboration

Bridge Town supports private, invitation-only project collaboration. Multiple analysts in the same workspace can share a project, work on separate scenario branches, review each other’s changes through pull requests, and merge approved work into the main model.

This page explains the collaboration model and how it differs from the public publish/fork path.

Private collaboration vs. public templates

Bridge Town has two distinct ways to share model work.

	Private collaboration	Public templates
Audience	Named individuals, invited by email	All workspace members
Access control	Per-user role on the project	No role — anyone can clone
Entry point	invite_project_collaborator	publish_project_template
Result	Shared project with live edits	Independent copy with provenance link
Typical use	FP&A team co-owns a budget model	Finance shares a deal template for others to adapt

Private collaboration is for teams that need ongoing joint access to the same project. Public templates are for one-time reuse — the new project is independent and not linked to the original after cloning.

Roles

Every collaborator on a project has one of three roles.

Role	Permissions
Owner	Full control: manage collaborators, create and delete branches, merge pull requests, publish templates
Editor	Read and write: create branches, create models, open pull requests, submit reviews
Viewer	Read only: view models, branches, pull requests, and history

The project creator is automatically the first Owner. There must always be at least one active Owner — the last-owner guard prevents removing or demoting the sole owner.

Inviting collaborators requires Pro

invite_project_collaborator requires an active Pro subscription. Free-tier tenants can still manage existing collaborators (change roles, remove, cancel pending) but cannot send new invites.

Grant types

When you invite a collaborator, Bridge Town creates one of two grant types depending on whether the invitee is already a workspace member.

Active grant

The invitee’s email matches an existing workspace account. Access is granted immediately — no waiting, no invitation email required. The new collaborator can begin working right away. An in-app notification appears in their /dashboard page so they can open the project directly (the legacy /feed route redirects there).

Pending grant

The invitee’s email is not in the workspace. Bridge Town creates:

1. A pending project grant — records the intended role for this project.
2. A pending workspace invitation — invites the person to join the workspace.

Both grants are held in a pending state. When the invitee accepts the workspace invitation and completes sign-up, both grants are activated in a single transaction: the workspace membership becomes active, and all pending project grants for that email are resolved to active grants in one step.

If the invitee’s email matches an existing Bridge Town account (even one from a different workspace), an in-app notification is also created so it appears in their /dashboard page. The notification includes a link to accept the workspace invitation.

Until the invitee signs up, they appear in list_project_collaborators with pending: true.

Cancelling a pending invite

Use cancel_project_invite with the invite_id (the grant_id returned by invite_project_collaborator) to cancel a pending invite before the invitee signs up. This removes the pending project grant. The workspace invitation is left in place — other projects in the workspace may have also sent invites to the same email.

Invite idempotency

Calling invite_project_collaborator twice with the same pending email is safe. If a pending project grant already exists for that email on the same project, the existing grant is returned and no duplicate is created.

The MCP tool response reports this as workspace_invite: "reused". The REST API uses the same values under the field name workspace_invite_outcome.

Tenant isolation

All project grants are scoped to a single workspace (tenant). A user who is an Owner on project A in workspace X has no visibility into workspace Y — even if they have an account there. This is enforced at the database layer via row-level security.

Out of scope for this phase

Local Git clone and direct repository access are not supported in this release.

Collaboration in Bridge Town happens through the MCP tools and the web UI. There is no public Git remote, no SSH access, and no personal access token flow for local git clone. Analysts access model code and history through:

• list_versions and diff for version history
• read_file to inspect model source
• create_branch and merge_branch for scenario management
• The pull request workflow for code review

Separate power-user Git tooling is tracked as a future phase and is explicitly out of scope here.