Skip to main content
A Blueprint is an app that other apps are created from. When you create an app from a Blueprint, your app starts as a fork of the Blueprint’s repository and remembers its lineage. The Blueprint’s owner publishes versions from the Blueprint app’s Settings — a semver version, changelog, and change type (major, minor, or patch). Apps built from a Blueprint see a Blueprint update available indicator in the project toolbar when newer versions are published. You can run that update in-product — an agent-driven sync from the dashboard. This page covers the other path: doing the update from your local checkout, where you can review every changed line and resolve merge conflicts in your editor before anything lands on main.

​
When to use the local flow

Prefer the in-product sync when your fork is lightly customized and you want a hands-off update. Prefer the local flow when you want full control over the merge — especially for heavily customized forks where conflicts are likely. Your AI assistant runs the git steps for you; you review the diff, resolve conflicts locally, and only push when you’re satisfied.

​
Before you begin

You’ll need:
  • An app created from a Blueprint (not a standalone app)
  • A local checkout of that app’s repository — see GitHub Access
  • MCP access with repo access — either:
    • The per-project connection (Connect Claude Code) when your role grants repo access, or
    • The org-level connection (Connect Your AI Tool) authorized at read & write with a role that has agent:repos:write. Org connections address apps by id or slug; if you don’t have a checkout yet, mint one with get_repo_access — see Work Across Every App.
  • For org connections: the target app must have agent development enabled (on by default — the same gate as get_repo_access and get_project_dev_env)

​
The update flow

Ask your AI assistant something like “check whether this app has a Blueprint update”. It calls get_blueprint_update, which checks your app’s Blueprint lineage and whether newer published versions exist.

​
What get_blueprint_update returns

If no update is available, the tool returns available: false with a reason — for example the app is up to date, wasn’t created from a Blueprint, or the Blueprint has no published versions yet. If an update is available, the tool prepares a temporary fetch ref named blueprint-source-<full-commit-sha> in your app’s repository (a tracked fork shares history with its Blueprint source, so the exact published commit becomes fetchable with your repo’s credentials). It returns:
  • Current and target versions, baseline and target SHAs
  • The fetch ref name and changelog
  • The change type (major / minor / patch)
  • Step-by-step gitGuidance for merging the update
The tool is read-only apart from creating that narrow ref.

​
Merge the update locally

Your assistant walks through the git steps. Review the merge and resolve any conflicts in your editor before pushing:
1

Ensure a clean checkout

This should print nothing. Commit or stash local changes first.
2

Fetch the exact Blueprint commit

Replace <sha> with the full target commit SHA from the tool response:
3

Create an update branch from remote main

Replace <short-sha> with the first eight characters of the target SHA:
4

Merge the Blueprint ref

Resolve conflicts here, locally, with your AI assistant’s help. This is the whole point of the local flow — you see every changed line before anything lands.
5

Push to remote main

Pushing to main is live — Stardeck agents commit straight to main, and your push lands on the same branch. After you push, the cloud sandbox does not auto-pull your commit. Load the pushed commit into the sandbox from the dashboard’s git history tab — see Working alongside the Stardeck agent.

​
Record the update

Once the exact published Blueprint commit is merged into remote main, ask your assistant to call complete_blueprint_update with the target version, target SHA, and a short summary of what changed. The server independently verifies before recording anything:
  • The target version is really published on the Blueprint
  • The SHA matches that published version
  • The commit is an ancestor of remote main (you merged and pushed the right ref)
If verification passes, it atomically:
  • Records the new Blueprint baseline (so the update indicator clears)
  • Writes an audit entry
  • Posts a timeline event in the app’s chat history
  • Deletes the temporary blueprint-source-<sha> fetch ref
Baseline downgrades are refused. The call is safe to retry — if you call it again after a successful completion, it returns the existing completion without duplicating the timeline event.

​
Troubleshooting

​
”Not created from a Blueprint”

Only apps forked from a Blueprint can receive Blueprint updates. Standalone apps return not_a_blueprint_fork.

​
”Up to date”

Your app’s baseline already matches the latest published Blueprint version. No action needed.

​
Completion says the commit isn’t in remote main

You haven’t pushed yet, pushed to a different branch, or merged the wrong ref. Merge the exact blueprint-source-<sha> ref into main, push with git push origin HEAD:main, then retry complete_blueprint_update.

​
Blueprint tools don’t appear

  • Per-project connection: Blueprint tools are registered directly. Your role must grant repo access. See Tools & Permissions.
  • Org connection: Blueprint tools are long-tail catalog tools — they are not expected to appear in the client’s direct tool list. The client should find them via search_stardeck_tools. If search cannot find them, verify agent:repos:write on the role and read & write OAuth access. If the tool is found but refuses to act on the app, verify that agent development is enabled on the target app. See Tools & Permissions.

​
Next steps

Connect Claude Code

Per-project MCP connection for a single app’s checkout

Work Across Every App

Org connections can run Blueprint updates on any app in the org

Org Tools & Permissions

Repo access, dev environment, and Blueprint tools on the org gateway

GitHub Access

Get a local checkout of your app’s repository