Feat: Add old docs, begin adapting old docs to new format.

docs/Jibo Tools & Mod Installer/06 - Updater (How It Works).md

@@ -0,0 +1,79 @@
+# Updater (How It Works)
+
+The updater is a separate tool from the installer.
+
+- Installer: puts Jibo into developer mode by editing `/var/jibo/mode.json` via RCM + eMMC writes.
+- Updater: once you have SSH access, it downloads a JiboOs release and uploads a rootfs overlay to the robot over SFTP.
+
+Implementation: `../jibo_updater.py`
+
+## High-level flow
+
+1. Query the releases API (Gitea JSON) and pick a release:
+   - latest (default)
+   - stable-only (`--stable`)
+   - specific tag (`--tag`)
+
+2. Download the chosen release archive.
+
+3. Extract it safely (checks for path traversal in archives).
+
+4. Find the `build/` folder inside the extracted tree.
+   - You can override with `--build-path`.
+
+5. SSH into the Jibo using Paramiko.
+
+6. Ensure `/` is writable:
+   - tests with a `touch` on `/.jibo_rw_test`
+   - if needed, runs `mount -o remount,rw /`
+
+7. Upload the contents of `build/` into `/` using SFTP.
+   - Directories are created as needed.
+   - Files are uploaded and chmod is best-effort preserved.
+   - Symlinks are uploaded as symlinks if possible; otherwise it uploads dereferenced content.
+
+8. Optionally return Jibo to normal mode by changing `/var/jibo/mode.json` back to `normal`.
+
+9. Record the applied tag in a local state file so repeated runs can short-circuit.
+
+## What “build/” means
+
+Releases are expected to contain a “rootfs overlay” folder named `build/`.
+
+That directory typically includes paths like:
+
+- `etc/`
+- `opt/`
+- `usr/`
+- `var/`
+
+The updater essentially copies those files to the same locations on the robot.
+
+## State file
+
+By default, the updater stores last-applied tag per host in:
+
+- `../jibo_work/update_state.json`
+
+If the state file says the host already has the latest tag, it exits unless you pass `--force`.
+
+More: [[07 - Working Directory + State Files]]
+
+## Safety knobs
+
+- It prompts before upload unless `--yes` is passed.
+- `--dry-run` downloads/extracts and connects, but does not upload or edit mode.json.
+
+## Returning to normal mode
+
+At the end, the updater can switch the robot back to normal mode:
+
+- `--return-normal` (force it)
+- `--no-return-normal` (never prompt / never change)
+- otherwise it prompts (unless `--yes` is passed)
+
+Note: returning to normal mode can disable the “checkmark/dev” behavior depending on how JiboOs uses `mode.json`.
+
+## CLI reference
+
+See [[03 - CLI Arguments]] for the complete list and examples.