From 968a3d6df54a12460e9cef8f2e482f9ae07cf7b5 Mon Sep 17 00:00:00 2001 From: TUNA_BIN <65464657+TUNA-NOPE@users.noreply.github.com> Date: Tue, 10 Nov 2026 08:17:35 +0000 Subject: [PATCH] An update guide and prompt; no logo above the site's title - AGENTS.md: an Updating section for an agent asked to bring an install to the latest version: pull, link the tools again, rebuild when src/versions.env or src/patches changed, compare the config with the defaults, restart only when the user says so, check, and how to go back. - docs/setup.md: the same steps by hand, and the prompt. - README and the website: the prompt to paste into an agent. - Website: the logo above "Give your agents a Mac." is gone (it stays in the header). Co-authored-by: Claude Opus 5.5 --- AGENTS.md | 30 ++++++++++++++++++++++++++++++ README.md | 11 +++++++++++ docs/setup.md | 33 +++++++++++++++++++++++++++++++++ docs/site/llms.txt | 1 + docs/site/pages/index.html | 8 +++++++- docs/site/style.css | 3 +-- 6 files changed, 83 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4fd728e..d56e2d2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,8 @@ You're asked to give this Linux host a macOS VM with Xcode, iOS Simulators and T panel. You can do almost all of it yourself, including the steps in macOS's GUI. Work through `./macbox next` until every line is ticked; [docs/setup.md](docs/setup.md) explains each step. +If macbox is already installed and you're asked to update it, skip to [Updating](#updating). + ## Sharing improvements upstream macbox welcomes contributions of any kind from users and coding agents: issues, ideas, @@ -78,3 +80,31 @@ mac-sim up && mac-sim run && mac-sim shot /tmp/home.png && mac-sim down Look at `/tmp/home.png`. If the user runs T3 Code, open the simulator in their Device panel with `device_open`, using the ids `mac-sim t3` prints. + +## Updating + +You're asked to bring an existing install to the latest version. The user's VM, simulators and +config stay; only macbox's checkout, its build and its links change. + +1. Find the checkout: `readlink -f "$(command -v macbox)"` points into it. `git status` there: if + there are local changes, show them to the user and ask before you stash or drop anything. +2. `git log -1 --format=%h` (note it, to go back), then `git pull --ff-only`. Read what changed: + `git log --oneline ORIG_HEAD..`. +3. `./macbox agents install`: tools, skills and user units are links into the checkout, and files + can move between versions (they moved to `src/` in November 2026). +4. `./macbox doctor`. Anything it reports about the host: show the user the commands and ask. +5. If `git diff --stat ORIG_HEAD -- src/versions.env src/patches` shows anything, run + `./macbox build` in the background (20 to 60 minutes) and report progress. The running VM keeps + its QEMU until it restarts. +6. Config: compare `~/.config/macbox/macbox.env` with the defaults in docs/setup.md ("2. Config + and checks"). Values `macbox init` wrote earlier stay as they were: `MACBOX_COHERENT=off` there + is what `init` wrote before the default became `auto` (on with an Arrow Lake iGPU). Tell the user what differs and ask before you change it. +7. Ask the user when the VM may restart: it closes the simulators and apps running in macOS. Then + `./macbox down && ./macbox up`. +8. Check: `./macbox status`, `./macbox coherent status`, `./macbox next` (every line still + ticked), and the end-to-end check under "When you're done". Tell the user the old and new + commit, and what the release changed. + +If the new build misbehaves, go back: point `qemu/current` in +`$MACBOX_HOME/home/.local/share/reims-ctl/qemu/` at the previous build (they stay installed), or +`git checkout ` and `./macbox build`, then restart. diff --git a/README.md b/README.md index 51751cf..e9a70d6 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,17 @@ git clone https://github.com/TUNA-NOPE/macbox && cd macbox `macbox next` walks you through the rest: installing macOS, Xcode, the simulator pool and the agent tools. [docs/setup.md](docs/setup.md) has every step. +## Update + +Already running macbox? Give your agent this: + +``` +Update macbox on this machine to the latest version: https://github.com/TUNA-NOPE/macbox. Follow the "Updating" section of its AGENTS.md and ask me before you restart the VM or change the host. +``` + +It pulls the new version, links the tools again, rebuilds if the GPU stack changed, and restarts the +VM when you say so. By hand: [docs/setup.md, Updating](docs/setup.md#updating). + ## Performance diff --git a/docs/setup.md b/docs/setup.md index 0196b44..2c5963a 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -226,6 +226,39 @@ mac-sim up && mac-sim run && mac-sim shot /tmp/home.png && mac-sim down `android-sim` runs a pool of Android emulators on the host itself, with KVM and the GPU. It needs the Android SDK; see [docs/agents.md](agents.md#android). +## Updating + +New versions come as commits on `main`. With an agent, paste this: + +``` +Update macbox on this machine to the latest version: https://github.com/TUNA-NOPE/macbox. Follow the "Updating" section of its AGENTS.md and ask me before you restart the VM or change the host. +``` + +By hand, in the checkout: + +```sh +git status # local changes? keep them aside first (git stash) +git pull --ff-only +./macbox agents install # links the tools, skills and units again (paths change between versions) +./macbox doctor +git diff --stat ORIG_HEAD -- src/versions.env src/patches # anything here: rebuild +./macbox build # 20 to 60 minutes; the running VM keeps its QEMU meanwhile +./macbox down && ./macbox up # the new build and switches; closes what runs in the VM +./macbox status && ./macbox coherent status +``` + +- **Your config stays yours.** `~/.config/macbox/macbox.env` keeps the values `macbox init` wrote, + so a new default doesn't reach you by itself. Compare it with the table in + [2. Config and checks](#2-config-and-checks). For example, `MACBOX_COHERENT=off` in it is what `init` wrote + before the default became `auto`, which turns on Coherent and the switches measured with it on + an Arrow Lake iGPU. +- **Nothing inside macOS needs redoing** unless the release notes say so (then `./macbox provision`). + After a T3 Code update, run `./macbox t3 fix-hub` again, as always. +- **Going back:** every build stays installed beside the others in + `$MACBOX_HOME/home/.local/share/reims-ctl/qemu/`, and `qemu/current` points at the one that + starts. Point it at the previous one (`ln -sfn .../qemu/current`), or check out the previous + commit and `./macbox build`, then `./macbox down && ./macbox up`. + ## Day to day ```sh diff --git a/docs/site/llms.txt b/docs/site/llms.txt index e5b4e53..4e9e142 100644 --- a/docs/site/llms.txt +++ b/docs/site/llms.txt @@ -22,6 +22,7 @@ publishing on their behalf. - [README](https://github.com/TUNA-NOPE/macbox/blob/main/README.md): what it is, requirements, quick start, performance, FAQ, comparison with Docker-OSX and cloud simulators - [AGENTS.md](https://github.com/TUNA-NOPE/macbox/blob/main/AGENTS.md): for an agent setting macbox up on a host, including the steps in macOS's GUI (macbox screenshot, click, type) - [Setup, step by step](https://github.com/TUNA-NOPE/macbox/blob/main/docs/setup.md) +- [Updating an existing install](https://github.com/TUNA-NOPE/macbox/blob/main/AGENTS.md#updating): for an agent asked to bring macbox to the latest version; by hand in docs/setup.md#updating ## Using it from an agent diff --git a/docs/site/pages/index.html b/docs/site/pages/index.html index d9dc75f..e9662c7 100644 --- a/docs/site/pages/index.html +++ b/docs/site/pages/index.html @@ -3,7 +3,7 @@ ---
-

macbox

+

macbox

Give your agents a Mac.

macOS, Xcode and real iPhone simulators at up to 120 fps, on your Linux machine and its own GPU. Your coding agent builds the app, taps through it and checks it for itself.

@@ -54,5 +54,11 @@

You'll need

./macbox next # what's done, and the next step

./macbox next always says what's done and what's next. The full walkthrough

+
+

Already have macbox? Update it

+

Paste this into your agent. It pulls the new version, rebuilds what changed, and asks before it restarts the VM:

+
Update macbox on this machine to the latest version: https://github.com/TUNA-NOPE/macbox. Follow the "Updating" section of its AGENTS.md and ask me before you restart the VM or change the host.
+

By hand: docs/setup.md, Updating.

+
diff --git a/docs/site/style.css b/docs/site/style.css index 64dff62..d933859 100644 --- a/docs/site/style.css +++ b/docs/site/style.css @@ -239,6 +239,5 @@ td strong { color: var(--ink); font-weight: 600; } @media (max-width: 760px) { .cols { grid-template-columns: 1fr 1fr; } .cols > div { grid-column: 1 / -1; } } @media (prefers-reduced-motion: no-preference) { html { scroll-behavior: smooth; } } -.hero .eyebrow{display:flex;flex-direction:column;align-items:center;gap:14px} -.hero .eyebrow .mark{width:72px;height:72px;filter:drop-shadow(0 8px 24px rgba(91,77,230,.28))} .brand img{display:block;border-radius:6px} +#update { margin-top: 40px; }