First-run setup

The ten setup steps, what each one checks and what it stores, when the page opens by itself, and how a fresh install restores from a backup.

The setup page walks a fresh install through ten steps (STEPS). Each step's check is a function over what the probes found. The checks write nothing; the page saves a step when you press next (;). "Not checked" means the source read for this page does not settle it. Windows behaviour is from code only.

01when it opens#

firstLaunchSetup returns true when the remembered recent list of folders is empty. The platform argument no longer changes the answer, so a first launch on Linux opens setup too, not only Windows. Every real folder open is remembered and recent is never pruned, so an empty list means no work folder was ever chosen.

On such a launch the shell waits in a throwaway smith-setup-* temp folder, never home or the data dir (firstLaunchFolder), loads #/setup, and writes setup_opened: true plus the parking folder into desktop.json. Opening a real folder removes the parking folder (leaveParked).

02the steps#

step name checks stores
1 claude, codex, grok any one of the three is installed and starts, and git is found (stepRuntimes). Claude is looked for on PATH and the usual install folders, claude --version is run. nothing in the check; marking the step set saves a claude found off PATH to desk.json conductor.command
2 signed in each installed program's own sign-in status; one signed in is enough (stepSignIn). Codex and grok are asked without a model call. nothing; the sign-in button starts the program's own sign-in
3 where smith keeps things the data folder is not a temporary one, has room (warns under 2 GB), and is writable by a test file (stepFolder; lowSpaceBytes). the data folder in settings, used when smith starts. A refused folder keeps the current one.
4 your conductor the conductor persona is found and the memories are counted; when more than one program is signed in it asks what the conductor runs on (stepConductor). Only claude can be picked for now. not checked
5 tickets the tracker on this computer, or a typed http(s) url, is called and its projects counted (stepTracker; checkTracker). a typed url is saved under its host name (trackerName); where exactly is not checked
6 link this install a pasted invite code links this install; without a link client the step says linking isn't in this build (stepLink;). the key stays in smith's data folder, never shown; linking marks step 6 set in setup.json
7 your first project a folder with a git repo (branch, clean or dirty), a folder of files, or nothing (stepProject; checkProject). /api/desk/setup/manager finds or starts the new project's chat and pins it as manager, keeping an existing pin (;)
8 search optional. The search model's folder and the room on its drive. It never contacts huggingface.co until fetch is pressed (stepSearch). the model files, only when fetched
9 skills and models optional. Looks for folders holding a SKILL.md (stepSkills). nothing on a read error; where found skills are imported is not checked
10 done shows what each step left and the conductor's hello; next reads "open the desk". nothing

Steps 1 and 2 are locked until they pass (lock: true). A step is recorded as set or skipped (stepSet, stepSkipped).

03the setup record#

setup.json in the data folder holds version, last_run, steps and programs (SetupRecord). POST /api/desk/setup/record writes it, and never memory, tickets or projects (;). Checks of steps 1 and 2 also remember what they found, so home's to-dos follow it without a probe of their own (remember).

04running setup again#

A re-run's new data folder is copied first; only then is desk.json data_dir switched, and the old folder stays where it is (setupMove;). The switch applies when smith restarts.

05restore from a backup#

A fresh install can start from a backup. The first-run page has a "backups folder" row: pick or type the folder smith made its backups in, list what is in it, and restore one. The list is GET /api/desk/setup/backups?dir= (route table). The folder must be absolute, and each snapshot comes back with a refused reason when a newer smith took it. The press is POST /api/desk/setup/restore (;). It goes through the same request and restart as settings: the restore is applied at the next start, before any store is opened. The snapshots, the refusal and the start-time apply are in backup and restore.

06see also#