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
  • An org connection (Connect Claude Code) authorized at read & write with a role that has agent:repos:write. The connection addresses apps by id or slug; if you don’t have a checkout yet, mint one with get_repo_access — see Work Across Every App.
  • 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

Blueprint tools are catalog tools, so 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 connection’s 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

Connect your local Claude Code to your organization’s MCP server

Work Across Every App

Clone and run any app in the org, then run its Blueprint update

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