An explainer for pacphi/workstation-steward · v0.2.2

Your Mac's software supply chain,
kept current on your terms.

One command, steward, answers a single question each week: what needs updating, is it safe yet, and what changes if I say yes? Nothing changes without a plan, a yes, a backup and a way back.

View the repo → macOS · Node 26+ · MIT · 0.x

1 · Why it exists

A Mac runs hundreds of tools. Each one updates itself.

Language runtimes, Homebrew formulae, global npm CLIs, desktop apps that bundle their own runtimes, AI coding tools that quietly install their own updates, and every project's dependencies. Each follows its own schedule, and some updates are attacks. The repo's guide cites October 2026 incidents: hijacked Docker tags, advisories landing mid-rollout, and launchers fetching @latest on every start.

The steward is the one place that decides what is allowed on your machine, and when, and makes each change reversible. The goal is safe, explained and reversible, not merely newest.

Nothing changes without asking
Plan → your yes → backup → receipt. No background jobs, no auto-updates.
New releases wait
3 days old before they come in. Majors are always your call.
The old version stays
A 3-day soak keeps the previous install, so back is a config restore.
Releases you can verify
Built by GitHub Actions with a provenance attestation, never a laptop.
2 · Try it: the release-age gate

Would the steward take this version today?

Drag the age of a new release. Toggle the exceptions. This models the policy described in the README (min_release_age_days = 3, set once in steward.toml); it does not run the real tool.

THE GATE · day 3 time for the community to catch a bad release eligible to come in v patched release: gate skipped

Per the README: "The exception is the first patched release for an advisory in the GitHub Advisory Database, RustSec or OSV. Majors are always your call. Even the steward itself waits."

3 · The four areas

Click a node: what it owns, and how it meets the others.

A machine has several supply chains that drift in different ways. Giving each its own area, policy file and commands makes the drift visible and the rules enforceable (design decision D1). Supply chain decides when; AI tooling decides whether.

steward.toml (your instance) roots · paths · release-age · soak · profiles Supply chainsteward sc … AI toolingsteward ai … · add-on Projectssteward projects … · add-on Fleetsteward fleet … when ↔ whether onboarding a project runs the per-project steps of both areas Same rails everywhere plan → yes → backup → receipt → soak → rollback
Select an area. The add-ons (dashed) are off until you enable them in steward init or steward.toml.
4 · The safe-change loop

Every command that writes follows the same six beats.

steward sc rollback · --undo · --rollback
Press Next step or Play to walk through steward sc upgrade.
5 · Engine and instance

The tool holds none of your data.

The engine (the npm package) is generic. Everything about your machine lives in an instance: a folder holding steward.toml and policy files, best kept in a private Git repo. That gives you history, Renovate, and a second Mac in minutes. State (receipts and backups) lives in ~/.local/state/workstation-steward/ with mode 0700, and your mise config is copied to ~/.config/mise/backups/ before every change.

Engine npm: workstation-steward no data · provenance-signed upgraded under its own gate Your instance ~/.config/workstation-steward steward.toml mise/ · renovate.json supply-chain/host.toml ai-tooling/ai-tooling.toml projects/registry.toml State (0700) ~/.local/state/… receipts backups · soak clocks reads writes Keep the instance in a private Git repo: it names your projects.
6 · Or just ask

Claude Code skills, one per area.

The steward ships as a Claude Code plugin. Ask in plain words and the skill picks the runbook step, runs the read-only checks, explains the result, and asks before anything changes.

SkillWhat to ask
/steward:supply-chain"what needs updating", "audit the machine", "a Node security release is out"
/steward:ai-tooling"is the AI tooling OK", "qualify AQE 3.15.x"
/steward:projects"what new projects are there", "onboard this repo"
/steward:pr-consolidation"consolidate the Dependabot PRs in owner/repo"

Run steward skills install in your own terminal, not inside a Claude Code session.

7 · Start

Five commands to a first look.

mise use -g npm:workstation-steward@<version> steward version steward init # guided setup; shows every file before writing steward doctor # read-only steward sc plan # what would be taken, held or skipped, and why

Then steward review becomes the weekly habit: seven read-only stages and one list of what needs you, each item with the command that acts on it.

8 · About this page

A suggestion, offered in good faith.

This explainer was generated from the public README, docs/guide.md and docs/architecture.md at v0.2.2. The interactive widgets illustrate documented policy; they do not run the tool. Please correct anything that is wrong. A suggested README that only adds to yours accompanies this page.