Skip to content

glossary workshop

github-actions[bot] edited this page Nov 8, 2026 · 3 revisions

Workshop

DRAFT

What it is

A BOS instance enclosed in one folder: the root of all crafting on a host or partition. A directory named __WORKSHOP is a workshop.

  • Per user: ~/__WORKSHOP
  • Per partition: /media/**/__WORKSHOP

Every host in the setternet has its own workshop, and the workshop defines the host's role in the multi-host system.

Why it exists

A programmer's work gets scattered across machines, drives and servers, and copies drift apart: "variantogeddon". A workshop gives every host the same fixed shape, so:

  • people and tools (BOS, AI agents) always know where things belong
  • work in different states (tools, active, knowledge, at rest) is kept apart
  • routine work (sorting, syncing, archiving, publishing) can be automated

Contains

Dir Role
.BOS/ BOS itself: setup, data, nests, storylines, workshop descriptors
devarmory/ tools
forge/ active work
craftbook/ notes, recipes, procedures
archive/ work at rest

All five are mandatory. BOS creates any missing one at boot.

Rules

  • A machine can hold several workshops (home plus partitions). They are independent: nothing is moved or synced between them unless asked.
  • The active workshop is the one named by --workshop, else $BOS_WORKSHOP (the workshop itself), else $WORKSHOP_ROOT/__WORKSHOP (the directory that holds it, e.g. a partition), else the nearest parent directory named __WORKSHOP, else ~/__WORKSHOP.
  • A workshop is a directory named __WORKSHOP: a --workshop (or the library's { workshop }) or $BOS_WORKSHOP with another name is taken as the directory that holds it, like $WORKSHOP_ROOT. So a partition root never becomes a second workshop beside its own __WORKSHOP.
  • $WORKSHOP_RENAME gives the workshop directory another name (e.g. .__WORKSHOP); every rule above then looks for that name.
  • A development workshop: the core is developed, tested by hand and demonstrated on a workshop of its own (WORKSHOP_ROOT in the core's .env), so the home workshop is not exposed every time BOS is worked on.

Repair

A workshop lives only in a directory named __WORKSHOP (or $WORKSHOP_RENAME). When areas of a workshop lie beside it - in the directory that holds it, e.g. a partition root given where __WORKSHOP was meant - bos workshop status reports areas-beside-workshop (an error) and bos workshop bootstrap refuses to run, so the mistake does not spread. bos workshop repair brings them inside: what the workshop lacks is moved (whole directories, git repositories with them), duplicates and BOS's own scaffolding are removed, and anything that differs stays where it is for the owner to settle. It only plans until --confirm.

Lifecycle

Its origin (which host created it, and when) is recorded in .BOS/storylines/metadata.json. Launches, shutdowns, and project openings and closings are recorded in storylines.

Open questions

  • Is a workshop named (workshopName in model data)? [TODO]

Clone this wiki locally