# Posting to Build from a coding agent

Drop this file into your repo as `AGENTS.md` (Codex, Cursor, Gemini CLI, and others read it)
or `CLAUDE.md` (Claude Code), or paste it into your agent's instructions.

Build is where this project's work is shared: every project has numbered updates
("Update #N"), milestones that set its progress, and a feedback question per update.
What you make lands in the owner's **Studio** in the Build app as a draft. The owner reviews it
and posts it; nothing you send is published on its own. The one exception is the owner's profile:
profile edits show right away (see "Fill out the profile").

## Not on Build yet?

Your assistant can walk you through it before you have an account: add the get-started connector,
`https://www.builderslive.org/mcp/start` (no sign-in), and ask it how to get set up on Build. It calls
`build_get_started`, which gives the steps in order. The same tool is on the main connector once you
are signed in. The steps:

1. Create a Build account at https://www.builderslive.org/signup (email, Apple or Google). It is your
   own account as a builder, whatever company you work for.
2. Add Build's main connector, `https://www.builderslive.org/mcp`, and sign it in: your assistant asks
   when you add it; sign in with your Build account and choose Allow. Nothing is copied or pasted.
3. For company paperwork and records, join your company in Build with the work email or phone it has
   for you (account menu, Join a company, or Settings, Accounts). A company new to Build is set up
   first; your company's admin adds you if you have no work login. Your own projects, posts and models
   need no company.
4. Your assistant then works in that company as you, with your role's limits (Settings, Accounts shows
   Agents on for each company; you can turn it off per company).
5. Optional: Build PlanReader on your computer (https://www.builderslive.org/download) lets your
   assistant reach job files there that are not in Build yet. The computer asks you the first time.

Never paste a password or a token to an assistant; you sign in on Build's own pages.

## Tools

- **Hosted MCP server, no install**: `https://www.builderslive.org/mcp`. One server: projects, posts,
  company records, and the 3D / live-takeoff tools (sheets, members, connections, `model_qc`,
  `model_publish`). Add it as a connector in Claude or ChatGPT, or
  `claude mcp add --scope user --transport http build https://www.builderslive.org/mcp`,
  and sign in with the owner's Build account when asked.
- **Before you publish a 3D model, run the code check** and fix every fail (or say why): `code_check
  { sceneId }` on the hosted server (`model_qc` runs it as `model.code`), or on your own computer with no
  sign-in, `apr_code_check { scene }` in Build PlanReader. Set `metadata.code_context.occupancy`
  (`dwelling`, `building` or `industrial`), `state` and `city` on the scene, and draw the stair under a
  raked guard (by-others treads and stringers) so its height above the nosings can be checked.
- **Local MCP server + CLI** (Claude Code, Codex CLI, Cursor, Gemini CLI, Windsurf, Cline, Continue):
  `curl -fsSL https://www.builderslive.org/mcp/build-mcp.js -o ~/.local/bin/build && chmod +x ~/.local/bin/build`
  (Windows: `node build-mcp.js <command>`), with the owner's token in `BUILD_API_TOKEN`. Run `build help`.
  Tools: `build_list_projects`, `build_get_project`, `build_create_project`, `build_update_project`,
  `build_add_milestones`, `build_update_milestone`, `build_post_update`, `build_post_feed`,
  `build_upload_file`, `build_post_artifact`, `build_list_artifacts`, `build_list_model_kinds`,
  `build_generate_model`, `build_get_profile`, `build_update_profile`, `build_add_experience`,
  `build_update_experience`, `build_remove_experience`, `build_add_education`, `build_update_education`,
  `build_remove_education`, `build_set_skills`, `build_api_request`.
- **Raw HTTP**: https://www.builderslive.org/api/v1/openapi.json (drafts: `POST /api/v1/drafts`).

## How to share progress

1. Find the project: `build projects` (or `build_list_projects`). If there isn't one for this
   work, start it with milestones: `build project create --name "…" --milestone "…" --milestone "…"`.
2. Draft the next update when something meaningful lands (a feature works, a model renders, a
   drawing set is done), not for every commit:
   `build post --project <id> --title "…" --body "what changed and why" --feedback "the one question you want answered" --complete <milestoneId>`
   It goes to the owner's Studio as a draft; it becomes "Update #N" and ticks the milestones when they post it.
   - Attach evidence: `build upload <file> --project <id> …` for screenshots, PDFs, models;
     `build artifact page.html --project <id> …` for a runnable demo. Up to 10 photos: `--image <url>` (repeat).
   - Use `build project <id>` to get milestone ids.
   - Steel work: `build model generate beam_column_frame --set bay_widths_ft_x=30,30,30 --project <id>`
     (also `stair`, `straight_railing`, `mono_slope_canopy`, `ornamental_picket_fence`; `build model kinds`
     lists every parameter). It drafts a 3D model with a member schedule that people can watch go up once posted.
     Every model comes back with `code_checks` (pass / fail / note, each citing the code section, e.g.
     IBC 2021 §1011.5.2); fix failures before drafting. The provisions themselves: GET /api/v1/codes.
     The code follows the project's stated location: set it with `build project update <id> --city … --state CA`
     (California projects are checked against the 2025 CBC).
3. When the last milestone is done: `build project finish <id>`.

## Fill out the profile

The owner can ask you to fill out their Build profile. Unlike posts, these changes are **not drafts**:
they show on the public profile as soon as they're saved, so confirm what you'll change first.

1. Read it: `build profile` (or `build_get_profile`). It returns the profile fields, the jobs,
   education and skills with their ids, and `can_edit_profile`.
2. Profile fields (send only what changes; `none` or `null` clears one):
   `build profile set --headline "…" --bio "…" --trade welder --years 12 --location "Oakland, CA"`
   (`build_update_profile`). Also: display name, website, the "Skills & tools" chips (`--chip`, up to 30),
   open to collaborate, available for work, "Currently building" (`--featured <projectId>`), the 3D
   header's name and project, and the theme song line (28 characters).
3. Jobs: `build job add --title "Foreman" --company "…" --start 2021-03 [--end 2024-06] [--private]`,
   `build job update <id> …`, `build job remove <id>`. No end date means they still work there;
   `--private` means only the owner sees that job.
4. Education: `build school add --school "…" --degree "…" --start-year 2012 --end-year 2016`,
   `build school update <id> …`, `build school remove <id>`.
5. Skills (the list friends endorse): `build skills set "Welding" "Blueprint reading"` replaces the whole
   list; skills you keep keep their endorsements.

Raw HTTP: `PATCH /api/v1/me`, `POST|PATCH|DELETE /api/v1/me/experiences[/<id>]`,
`POST|PATCH|DELETE /api/v1/me/educations[/<id>]`, `PUT /api/v1/me/skills`. Editing needs the
`profile:write` scope; an older connection says so, and the owner reconnects it in Build › Settings › Connections.

## Rules

- Drafts are the default. Only the owner, at their own shell, uses `--publish` to post directly.
- Drafts carry the "MCP assisted" label so people know the content was generated. Add `--no-label` only
  for something the owner wrote themselves. Artifacts are always labelled.
- Each connection is rate limited (60 requests a minute, 30 drafts and posts an hour, 500 MB of uploads
  a day). A `429` says when the limit resets; wait until then.
- Profile edits are live, not drafts: only change what the owner asked for, and never invent jobs,
  schools, dates or skills.
- Never paste secrets, tokens, customer data, or private URLs into drafts or the profile.
