@dylanpiercey/work 0.0.120 → 0.0.121

package/README.md

@@ -73,16 +73,43 @@ app port, so route the whole hostname to it. Set
 > `/term` rule from your tunnel/proxy config and send all traffic to the app
 > port, or terminals will fail to connect.
 
+## Backup, restore, join
+
+A `work` machine holds almost nothing that lives only there: branches are
+on origin, tools come from mise's registry, skills from their source repos.
+So a backup is a small manifest, not a filesystem copy — Settings → Backup
+→ **Export** (or `work export [file]`) writes one with the workspaces (ids,
+names, branches, repos), settings, GitHub hosts, skill sources and mise
+pins — a few KB, with every default left out (`owner/name@base` only when
+the base is not the remote's default, `tool@version` only when pinned). Auto-push (Settings → GitHub) keeps every workspace
+branch on origin so the manifest is enough; the export pre-flight lists
+anything it cannot carry — unpushed commits, uncommitted or untracked
+files, ignored files that are not build junk — and waits for a decision.
+
+**Restore** (Settings → Backup, or `work restore <file> --yes`) installs
+what the file names that the machine lacks and re-creates the workspaces
+as rows; each one's repos then clone in the background, one workspace at
+a time, on the branch the manifest recorded (from origin, or fresh from
+the base when it was never pushed). Archived workspaces clone when they
+are un-archived.
+
+**Share / Join**: the clipboard button on Manage (or `work share`) copies a workspace's
+invite — its backup-manifest entry (name, branch, repos) as JSON. Someone
+else pastes it into New workspace (the join button; or `work join <file>`, or pipes it
+in) and gets the same repos, checked out on their own lane
+(`<their-branch>-<them>`) of the workspace branch, with PRs and the review
+targeting that branch.
+
 ## Configuration
 
-| Variable             | Default                 | Purpose                              |
-| -------------------- | ----------------------- | ------------------------------------ |
-| `WORK_ROOT`          | `~/work`                | Workspaces root (+ `.cache` bare repos) |
-| `WORK_DATA_DIR`      | `~/.local/share/work`   | sqlite db and server state           |
-| `WORK_APP_PORT`      | `7171`                  | HTTP server (app, assets, and `/term` websockets) |
-| `WORK_ALLOWED_HOSTS` | —                       | Extra dev-server hostnames (comma-separated) |
-| `WORK_USER` / `WORK_HOST` | current user/host  | Branch-name prefix parts             |
-| `WORK_BRANCH_PREFIX` | `<user>-<host>`         | Whole branch-name prefix, overriding the parts |
+| Variable                  | Default               | Purpose                                           |
+| ------------------------- | --------------------- | ------------------------------------------------- |
+| `WORK_ROOT`               | `~/work`              | Workspaces root (+ `.cache` bare repos)           |
+| `WORK_DATA_DIR`           | `~/.local/share/work` | sqlite db and server state                        |
+| `WORK_APP_PORT`           | `7171`                | HTTP server (app, assets, and `/term` websockets) |
+| `WORK_ALLOWED_HOSTS`      | —                     | Extra dev-server hostnames (comma-separated)      |
+| `WORK_USER` / `WORK_HOST` | current user/host     | Branch-name prefix parts                          |
+| `WORK_BRANCH_PREFIX`      | `<user>-<host>`       | Whole branch-name prefix, overriding the parts    |
 
 Ports and paths can be exported before `scripts/setup-prod.sh` to bake them into
 the service. For settings that should outlive an update, put them in an untracked