Skip to content

docs(Update): correct which update legs work offline - #2102

Open
hifiguy wants to merge 1 commit into
danielmiessler:mainfrom
hifiguy:docs/update-workflow-offline-steps
Open

docs(Update): correct which update legs work offline#2102
hifiguy wants to merge 1 commit into
danielmiessler:mainfrom
hifiguy:docs/update-workflow-offline-steps

Conversation

@hifiguy

@hifiguy hifiguy commented Sep 11, 2026

Copy link
Copy Markdown

Problem

Workflows/Update.md's Network unreachable branch tells the operator to
"stop after re-running the additive legs that work from the on-disk skill
(steps 4–6)", and names step 3's overlay as the one leg that needs a fetched
payload.

Steps 4 and 5 don't work offline either — and the same sentence explains why,
one clause later: on an installed system install/ is bootstrap-only.

  • Step 4, InstallHooks.ts, reads install/hooks/hooks.json
  • Step 5, ScaffoldUser.ts, reads install/USER/

Neither path exists in a bootstrap-only payload, so both exit ok: false.
Step 6, ActivateImports.ts, is the only leg that actually runs — it edits
CLAUDE.md and needs no payload.

Reproduction

Clean-room, against the shipped skill only — no install required. Extract the
v7.40.4 release, point --skill-root at the installed copy it ships
(LifeOS/install/skills/LifeOS, whose install/ holds only the five bootstrap
files), and --config-root at a scratch dir containing just a CLAUDE.md
copied from install/CLAUDE.template.md:

InstallHooks.ts    → {"ok":false,"error":"payload hooks.json not found at
                      <skillRoot>/install/hooks/hooks.json"}
ScaffoldUser.ts    → {"ok":false,"error":"template USER not found at
                      <skillRoot>/install/USER"}
ActivateImports.ts → {"ok":true,"dryRun":true,"wouldActivate":[],"wouldSkip":[...]}
OverlaySystem.ts   → {"ok":false,"blockers":["payload at <skillRoot>/install is
                      bootstrap-only (no system trees: hooks, skills, agents,
                      LIFEOS/TOOLS, ...)"]}

Three of the four steps refuse; the doc predicts only one. Step 6 is the sole
survivor, and only because it reads CLAUDE.md rather than the payload.

Why it's worth fixing

The offline branch currently sends the operator into two hard failures with no
warning that they're expected. OverlaySystem's refusal is explicitly
pre-labelled "expected, not a failure" — the other two aren't, so they read as
a broken install. An operator debugging that is likely to go looking for damage
that isn't there, or to start hand-copying payload files to make the steps pass,
which is how stale trees get created.

Fix

Documentation only, one line, no code change. The wording now:

  • names step 6 as the only leg that works offline
  • states that steps 3–5 all require the fetch
  • quotes the two additional refusal messages so they read as expected behaviour

Applied to both copies of the file, which are byte-identical on main:

  • LifeOS/Workflows/Update.md
  • LifeOS/install/skills/LifeOS/Workflows/Update.md

Notes

No existing issue or PR covers this. The nearest neighbours — #1950
(OverlaySystem's system-tree list drift) and #1770 (copyMissing can't update
system-owned files) — are both closed and describe different mechanics.


GitHub: @hifiguy · Discord: SecDude2469

Update.md's "Network unreachable" branch says to re-run "the additive legs
that work from the on-disk skill (steps 4-6)", singling out step 3 as the
only one needing a fetched payload. Steps 4 and 5 do not work either.

On an installed system install/ is bootstrap-only -- the doc says so itself
one sentence later -- and:

  - step 4, InstallHooks.ts, reads install/hooks/hooks.json
  - step 5, ScaffoldUser.ts, reads install/USER/

Neither exists in a bootstrap-only payload, so both exit ok:false. Only
step 6, ActivateImports.ts, runs offline; it reads CLAUDE.md, not the payload.

Reproduced clean-room against the v7.40.4 release alone -- skill-root set to
the installed copy it ships (LifeOS/install/skills/LifeOS), config-root a
scratch dir holding only a CLAUDE.md copied from install/CLAUDE.template.md:

  InstallHooks.ts    -> ok:false  payload hooks.json not found
  ScaffoldUser.ts    -> ok:false  template USER not found
  ActivateImports.ts -> ok:true
  OverlaySystem.ts   -> ok:false  bootstrap-only blocker

Three of the four refuse; the doc predicts one.

The wording now names step 6 as the only offline leg, says steps 3-5 all
require the fetch, and quotes the two additional refusal messages so they
read as expected behaviour rather than a broken install.

Applied to both copies of the file, byte-identical on main:
LifeOS/Workflows/Update.md and the nested installed copy at
LifeOS/install/skills/LifeOS/Workflows/Update.md.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant