The operator owns the Lazurio version: ~/.local/bin/lazurio, hosted manual allows lazurio update, Folder refresh needed (F17 addendum)

docs/decisions.md

@@ -944,8 +944,8 @@ apply and an Update button fed by `Lazurio/t3code` releases; T3 always runs tool
 the operator's PATH, and recovery goes through `lazurio` from the recovery runtime, not
 through a PATH fallback (Machines, DEV-6624).
 
-**Platform.** The hosted manual section "Updates on this Machine" now says that the pin
-owns the product and the generated files, not the operator's tools, and that an agent
+**Platform.** The hosted manual section "Updates on this Machine" now says (until the
+addendum of 2026-09-28 below) that the pin owns the product and the generated files, not the operator's tools, and that an agent
 updates operator tools only on the Principal's explicit instruction in the thread and
 otherwise only reports versions (template revision `base-instructions-6`, so every
 Folder re-renders on its next refresh). `lazurio update` remains the only product
@@ -982,6 +982,71 @@ so agents on VMs keep the layout for further tools, and `tools status` reports
 
 **Not decided here:** the readback shape and the T3 launcher (Machines).
 
+**Addendum 2026-09-28 (Principal): the operator owns the Lazurio version; the pin
+is a minimum.** Recorded from the Principal's decisions of 2026-09-28. (1) There is
+**one updater**, `lazurio update`. The operator of an Environment updates Lazurio
+themselves, on a hosted Machine (Remote Environment) exactly as on their own computer,
+without any rollout: "updating Lazurio is the operator's update of a tool, not a
+rollout". (2) A rollout **may** still move a working Lazurio forward, because
+operators sometimes forget to update and sometimes it is needed. So the provider's pin
+is a **minimum**: a rollout installs Lazurio when it is absent or broken, raises a
+Machine that is below the pin to the pinned release, and never moves a Machine below
+what it already runs — the existing floor and high-water rule of F13
+([product update](update.md#offline-update)), which already refuses a lower pin with
+`below-floor`. (3) Forward repair over rollback: no new rollback machinery;
+`lazurio update rollback` stays what it is, the way back from a failed update.
+(4) Linux first, then macOS; Windows later.
+
+This changes one point of this decision: the installed Platform release leaves the
+pinned baseline for its **version**. The baseline still delivers the first
+installation and repairs a broken one; the version belongs to the operator like the
+tools of 0161 point 2, with the one difference that a rollout may raise it to the pin.
+
+*The standard entry `~/.local/bin/lazurio`* (0161 point 6) now exists. `lazurio
+install`, the first installation and the offline update alike, links it to the install
+base's selector `<base>/bin/lazurio` by one atomic rename, creating `~/.local/bin`
+(`0755`) when it is missing. An entry that already points to the selector is left
+alone; a link to the selector of a Lazurio install base (another base, or one that is gone) is replaced; a dangling link of any other shape is someone else's and stays; when `~/.local` or `~/.local/bin` is itself a link or not a directory, nothing is written through it (`conflict`, `parent`); a
+regular file, a directory or a link to anything else is **never** overwritten — the
+installation still succeeds and its result (`entry.state: "conflict"`, human and JSON)
+names what is there and what the operator or an agent should do. Shell profiles are
+never edited. The result reports whether `~/.local/bin` is on the process PATH (the
+directory it tells the operator to put on PATH is `~/.local/bin` when the link exists)
+and warns, with both paths, when another program named `lazurio` resolves first (the
+legacy root CLI linked by Bun into `~/.bun/bin`, for example); it changes nothing about
+that program.
+
+*"Folder refresh needed."* A product update never writes the Folder (F14). So
+`lazurio update`, `lazurio update status` and the installed Launchpad's update pill say
+"Folder refresh needed" with the exact command when the Folder records an older
+template revision than the active product renders: `lazurio machine folder-refresh`
+on a hosted Machine; on a workstation the unchanged profile applied again
+(`lazurio profile-update` with the recorded choices at the current revision, or
+preview and apply in the profile panel), which the one planner turns into the same
+template upgrade. It only reads; nothing is refreshed automatically, and an edited
+generated file still blocks the refresh with `drift`. The Folder is `--folder`, the
+supervised unit's, or on a hosted Machine the declared operator's from the handover.
+The updater learns the revision a new version renders from that version's own
+self-check report (`templateRevision`), before activating it; an executable older
+than this addendum does not state it and nothing is reported rather than a guess — so
+the first update performed by `v0.1.7` or older reports no refresh, and
+`lazurio update status` of the new version does.
+
+*The generated manual* no longer forbids `lazurio update`, `lazurio update rollback`
+or `lazurio install` on a hosted Machine and no longer says the pin owns the product
+version: the operator owns it; an agent runs `lazurio update` when the operator asks
+(a change of the Environment, never on its own initiative) and `update status` freely;
+the pin is a minimum and a rollout never lowers a version; the refresh command follows
+an update; `lazurio update rollback` is for a failed update. Template revision
+`base-instructions-9` (revision 8 shipped in `v0.1.7`), so every Folder re-renders on
+its next refresh. A unit test checks that no generated output, in any preset or
+locale, still forbids `lazurio update` or gives the product version to the pin.
+
+Root decision 0161 still lists "the installed release" among what the pin holds; it
+is amended by a separate pull request in the root repository. What the Machines role
+must do differently is the contract in
+[machine handover](machine-handover.md#what-the-machines-role-does-with-the-lazurio-version-f17-addendum-2026-09-28).
+
 ## F18 — Enabled tools of the Environment
 
 **Principal's decision 2026-09-27 (root decision 0162 and the F17 line), implemented

docs/environment-tools.md

@@ -4,8 +4,9 @@ Proposed bounded pilot procedure under accepted decision 0144. Apart from the cu
 installation and login of three catalog tools (decision F19, below), this document
 does not claim an implemented tool installer, authenticated harness or usable
 Environment.
-Machines delivers the online Machine and selected Platform release; local Platform
-operations and the operator prepare what is needed inside it.
+Machines delivers the online Machine and a first installation of the Platform; local
+Platform operations and the operator prepare what is needed inside it, including
+the Platform's own updates (F17 addendum 2026-09-28).
 
 ## Operator tools are the operator's (decision 0161, F17)
 
@@ -16,6 +17,9 @@ tools in the standard path below) and the **operator's tools** (Codex, Claude Co
 `gh`, Node, npm, Bun and whatever else is on the operator's PATH). The baseline is
 pinned through the Machines rollout; the tools are delivered once at Machine creation
 and then belong to the operator, who updates them with the official installers.
+Since the F17 addendum of 2026-09-28 the version of the Platform belongs to the
+operator too: they update it with `lazurio update`, and the pin is only a minimum a
+rollout installs, repairs or raises to, never a version it lowers to.
 Readback reports their versions as facts, not drift. A rollout is only a repair of the
 one installation (the exact scope is in "The standard path" below); the Machines apply
 starts no agent and returns the `lazurio doctor` and `lazurio tools status` readback,
@@ -224,7 +228,8 @@ One installation per tool, in one place, on every Machine: an operator tool is t
 first executable of its name in `~/.local/bin` on the operator's PATH. A tool's
 official installer may keep its own home (Codex `~/.codex/…`, Bun `~/.bun`); only a
 link or wrapper in `~/.local/bin` puts it on PATH. Lazurio lives in
-`~/.local/share/lazurio/` with `~/.local/bin/lazurio`; system tools (git, curl,
+`~/.local/share/lazurio/` with `~/.local/bin/lazurio`, the link `lazurio install`
+creates and reports ([product update](update.md#release-and-trust)); system tools (git, curl,
 python, ssh) belong to the OS package manager; T3 Code and its runtime belong to the
 service unit and run on the Node its version recommends. There is no second
 "recovery" copy of any tool: a rollout repairs the one installation in place, in two

docs/machine-handover.md

@@ -190,7 +190,8 @@ The Launchpad shows the refreshed binding on its next read; an open panel holdin
 old revision gets `stale-revision` on apply, as after any concurrent change. The
 refresh re-renders what the handover changes, and everything when the active product
 renders a newer template revision than the Folder records: after Machines installs a
-release with new templates, its next `folder-refresh` is `refreshed` with the new
+release with new templates, or the operator runs `lazurio update` (which then reports
+"Folder refresh needed"), the next `folder-refresh` is `refreshed` with the new
 `AGENTS.md` and `manual/`, provided no generated file was edited (otherwise `drift`
 and its path, nothing written). A Folder rendered by a newer revision than the active
 product stays `template-upgrade-required` and is never downgraded
@@ -313,12 +314,36 @@ nothing, and a pin lower than the active version or the high-water mark is refus
 (`release-invalid`, `below-floor`) — which the role records as a finding, never
 retries with force. Also a **finding, not a failure**: `blocked folder-binding-changed`
 on a Folder adopted before the identity-based comparison. The role never runs
-`lazurio update`. After writing the handover on a Machine whose Folder exists (and
-after `updated`), the role runs `lazurio machine folder-refresh` (added after v0.1.2;
-the role needs a pinned release that has it) so the Folder follows the current
-handover: exit 0 `refreshed` or `unchanged` is success, exit 2 `blocked` is a finding
-to report with its `reason` and `path`, not a failure to retry, and exit 1 is an
-operation failure.
+`lazurio update`: that is the operator's command (below). After writing the handover
+on a Machine whose Folder exists (and after `updated`), the role runs
+`lazurio machine folder-refresh` (added after v0.1.2; the role needs a pinned release
+that has it) so the Folder follows the current handover: exit 0 `refreshed` or
+`unchanged` is success, exit 2 `blocked` is a finding to report with its `reason` and
+`path`, not a failure to retry, and exit 1 is an operation failure.
+
+### What the Machines role does with the Lazurio version (F17 addendum 2026-09-28)
+
+The operator owns the version of Lazurio on their Machine and updates it with
+`lazurio update`; the pin in the owner overlay is a **minimum**
+([F17 addendum 2026-09-28](decisions.md#f17--operator-tools-belong-to-the-operator-the-rollout-pins-the-baseline-and-repairs)).
+This is the contract for the Machines role; this repository does not change Machines.
+Every step below uses only what the product already answers.
+
+| Situation the role reads | What the role does |
+| --- | --- |
+| No installation (`<base>/bin/lazurio` absent and no `update/high-water`) | Install the pinned release: `<staged>/lazurio install --base <base> --json`, result `installed` |
+| Broken installation: the selector `<base>/bin/lazurio` is missing or not a link of its shape, while `update/high-water` survives | Repair with the pinned release when it is at or above the mark (`install` self-checks it and switches); a pin **below** the mark is refused `below-floor` and is a finding: that Machine is repaired only by a release at or above the mark (question Q5 of the distribution shaping) |
+| Selector present but dangling, or its executable damaged (`<base>/bin/lazurio --version --json` fails) | Not repaired by `install` of the same version today: it answers `installed` and changes nothing; a lower pin is refused, and only a higher one moves it, as in the next row. A finding for a person; an open gap of the product, not something the role works around |
+| Working installation below the pin (`update status --json`: `active` lower than the pinned version) | Raise it: the same `install --base` is the offline update, result `updated` |
+| Working installation at or above the pin | Nothing. `install --base` with a lower pin answers `release-invalid` / `below-floor`, which the role records as the fact `ahead`, never a failure, retry or force |
+| Any case | Never lower a version; never run `lazurio update` or `lazurio update rollback` |
+| After `installed` or `updated` | Run `lazurio machine folder-refresh` as today (above) |
+| PATH entry | Verify, do not create: `install --json` returns `entry`. `state` `created`, `present` or `replaced` is correct; `conflict` or `failed` is a finding with `entry.next` in the readback, and the role never replaces the occupant. A Machine without the entry is repaired by the next `install`, not by a link the role writes itself. The operator's login shell has `~/.local/bin` on PATH (`workspace_tools` already provides it for npm); `entry.shadowedBy` not `null` is a finding |
+| Readback | `lazurio update status --json`: `active`, `highWater`, `lastCheck` and `folderRefresh` are facts to report; an active version above the pin is not drift |
+
+The role keeps its custody-staged, digest-pinned bytes and its attestation check for
+installing and raising. The operator's own `lazurio update` verifies inside the product
+(F13). The meaning of the overlay fields changes, not their shape.
 
 ## Bounded diagnosis and repair
 
@@ -338,9 +363,9 @@ edited output, damaged journal, partial write without a receipt or abandoned loc
 requires operator diagnosis. No automatic cleanup or universal recovery is
 promised. Recreating a disposable VM requires separate infrastructure approval.
 
-Product update follows the [product update contract](update.md); until it is
-implemented nothing installs a product release on a Machine: retain the previous
-working product. Folder handover does not change that rule.
+Product update follows the [product update contract](update.md): the operator runs
+`lazurio update`; the Machines role installs, repairs and raises to its pin (above).
+Folder handover does not change that rule.
 The local filesystem boundary assumes no hostile concurrent same-user/root
 directory replacement; ownership checks are not a sandbox.