add a project

what a project is made of, the shared record and the local file, which fields live in each, where runs build, and how an edit gets made after the project exists.

a project is two halves. one is a shared record in the tracker, and the other is a local file on your machine. no field is in both, so nothing is merged or overridden between them. see two halves.

01the first project#

the setup page has a step for your first project: a folder with a git repo (it reads the branch, and whether it's clean or dirty), a folder of files, or nothing. the step finds or starts the new project's chat and pins it as the manager, keeping an existing pin. the setup docs cover it as step 7 in the steps.

the docs don't spell out a separate walk for adding a second project, so this guide stops at what a project holds and how you change it.

02the record#

the record lives in the tracker, not on disk. it holds:

• checks
• branch
• color
• repo_remote
• sync_mode
• root_hosts

checks are described on checks. with no record settings at all, the checks are what smith detects from the repo, and they aren't saved until you adopt them. a launch card has an "add these" press to save the detected checks, see draft and go.

the branch is the record's branch. when the record's branch is empty it falls back to the repo's current branch. sync_mode is push or pr, and unset means push. see push mode and pr mode.

03the local file#

the local half is a file at <desk dir>/projects/<tracker>/<project id>.json. it's keyed by tracker and project id, never by slug, and never kept inside a repo. it holds:

• path
• workspace
• assets and main_asset
• max_parallel
• mcp_servers
• overrides
• discord
• tools
• areas

assets lists the project's member assets, and main_asset is the one launch-card suggestions never offer. see assets.

04where runs build#

workspace unset defaults to <work home>/<project name>. runs build in worktrees at <workspace>.runs/ followed by the first 12 characters of the launch id. a run on an asset builds at <workspace>.runs/asset- followed by 12 characters. that's under which wins.

05changing a project#

the conductor edits a project by drafting a card with propose_config_edit, and the change is made when you click. the record's name is records/<project name>.json, which is a virtual name for the tracker record and not a file. the local half is projects/<tracker>/<project id>.json. the projects tool with a name returns four things: settings (both halves together), record, detected (what smith would detect from the repo) and halves.

an area's brief is the text a run reads as "your area is …", after the project's brief. it's capped at 2,000 characters, and a longer one is refused with an error that names the area and its length. see area brief.

a launch card drafted before you change a project's settings has to be drafted again.

06where to go next#

projects has the whole page, and checks covers what goes in checks.