> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update from a Blueprint > Pull published Blueprint updates into your app from your local workspace — review every changed line and resolve conflicts before anything lands. 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](/github-access) * MCP access with **repo access** — either: * The **per-project connection** ([Connect Claude Code](/local-claude-code/connect)) when your role grants **repo access**, or * The **org-level connection** ([Connect Your AI Tool](/ai-integrations/connect)) 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](/local-claude-code/cross-project). * 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-` 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: ```bash theme={null} git status --short ``` This should print nothing. Commit or stash local changes first. Replace `` with the full target commit SHA from the tool response: ```bash theme={null} git fetch origin refs/heads/blueprint-source-:refs/remotes/origin/blueprint-source- ``` Replace `` with the first eight characters of the target SHA: ```bash theme={null} git switch -c blueprint-update- origin/main ``` ```bash theme={null} git merge --no-ff origin/blueprint-source- ``` 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. ```bash theme={null} git push origin HEAD: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](/local-claude-code/connect#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-` 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. ```mermaid theme={null} flowchart LR A["get_blueprint_update"] --> B["Fetch + merge locally"] B --> C["git push origin HEAD:main"] C --> D["complete_blueprint_update"] D --> E["Baseline updated · 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-` 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](/local-claude-code/tools). * **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](/ai-integrations/tools). ## Next steps Per-project MCP connection for a single app's checkout Org connections can run Blueprint updates on any app in the org Repo access, dev environment, and Blueprint tools on the org gateway Get a local checkout of your app's repository