# Connect your preferred builder

For a workspace connection, open **Settings → AI builders**, choose your builder and select the Projects it can access. Copy the prepared prompt into Codex, Claude or Cursor, then approve the matching code yourself. The prompt includes the [AI-builder guide](/docs/ai-tools) and connection tool. It gives access to selected Projects plus ones it creates. You can revoke it or change the selected Projects later. The same connection supports optional athlete creation and ride imports: enable those permissions explicitly and select the athletes. See [file intake commands](/docs/ai-tools#put-ride-files-into-an-athlete). It is also offered after payment as **Connect builder**; **+ Page** keeps building inside MovePacket.

The instructions below describe the existing single-Project connection.


Keep using Codex, Cursor, Claude Code or another builder that can work with local files and run commands. MovePacket supplies the connection to your project; your builder supplies the coding experience.

A builder name saved during setup is a preference. It becomes a verified connection only after that builder successfully contacts the project's API.

## The simplest connection

1. Open your ready project from **Projects**, then choose **Foundation** under **Project options**.
2. Under **Bring your idea to life**, choose the builder in **Build with**, then **Copy prompt for** that builder, such as **Copy prompt for Codex**. If the page first asks who the project is for, answer and choose **Continue**.
3. Paste that prompt into your builder. It prepares the connection and shows an approval link and matching code.
4. Open the approval link, sign in with the MovePacket account that owns the project, check the code and approve it yourself.
5. Let the builder finish preparing the project folder and verifying the connection. Ask it to show a local preview and help with your first change.

The prompt contains no API secret. The helper keeps the credential in private local configuration outside the project folder. It does not publish anything during connection setup.

The current helper requires Node.js 22 or later and a tool able to run it. A browser-only chat may not support this flow. Ask your builder to check its environment rather than pasting a credential into chat to work around it.

## What the connection can do

It belongs to one hosted project and can work with that project's files, saved updates, private app records and analytics. It does not grant access to other projects, provider credentials or the shared athlete library. It cannot change the project's public/private audience.

The connection expires after 30 days. Creating a replacement invalidates the previous project connection, including another local builder using it. Revoke it through the project's connection controls when it is no longer needed.

Keep credentials out of chat, source code and Git. A local AI builder can execute commands on your computer; this connection flow reduces accidental exposure but does not make an untrusted local tool safe.

## Your first instruction

> Read this project's AGENTS.md and START-HERE.md. Inspect the MovePacket connection and explain what is available. Show me a local preview, then help me make one useful change. Use labelled example data until an authorised real-data path is connected. Do not publish until I have reviewed the saved preview.

If you already have a local project, tell the builder before it begins. The handoff prepares a new folder; it does not automatically import or overwrite your existing work. Ask the builder to bring the relevant files into the connected project's supported publishing format.

## If setup stalls

An expired request needs a fresh connection prompt. An account mismatch needs the MovePacket account that owns this project. If the tool cannot run the helper, use **Manual connection options** under **Your project details** on the project's **Foundation**: download the project folder and the private connection file, then tell your builder where the file is. Do not paste its contents.

The [Builder reference](/docs/ai-tools) includes manual commands, publishing limits and troubleshooting. Your external builder's subscription or API charges remain with that provider.

## Continue in another builder

For a hosted static project, MovePacket keeps a selected **working version** separately from what is **live**. The project workspace, a new connected folder and the project ZIP open that same working version. Saving an update with `node publish.mjs stage` selects it for the next visit without publishing it.

In an existing connected folder, run `node publish.mjs status` before editing. Use `node publish.mjs pull NEW-FOLDER` to download the selected working files into a new folder. Bring across any local changes you still want; existing folders are never overwritten. If another builder saves first, your stale save is rejected. Simultaneous uploads remain in **Versions**, where you can deliberately choose **Use as working version**. Reload the workspace or choose **Refresh working version** to see a save made elsewhere.

These downloads contain the saved static website files. Unsaved local changes, framework source outside `site/`, installed dependencies and private credentials do not travel with them. The internal starter editor can show an external working version and answer project questions; editing that version continues in your connected builder. It will not silently edit the original starter draft instead.

A working preview can also be behind a newer live release. Its download preserves that original live base. Ask your builder to compare the live source (`GET /v1/software/APP_ID/source`) with the working files and reconcile in a new folder. Only after reconciliation should it update the local `movepacket.json` live `version` from `status`; it must not replace the working version/generation to bypass a conflict. Download the current publishing tool when upgrading an older connected folder.

## What happens next

Work locally for quick feedback. When a change is ready to review, ask the builder to save a MovePacket update and give you its private preview link. Follow [Preview & publish](/docs/publishing) to make that exact version live.

## Ask your builder to check the project

The downloaded builder tool supports `node publish.mjs diagnose`. A connected builder can use it to read the same project evidence as the Technical teammate. Choose a specific check with `diagnose hosting`, `storage`, `builder`, `backups`, `releases`, `access` or `attention`.

These commands are read-only. They return the source and observation time for supported evidence, and can check whether the current release file exists. They do not test every feature, retrieve private record contents, repair infrastructure or establish backup coverage from a plan inclusion. The connection remains limited to its approved project and stops working when revoked or expired.