Skip to content

Short README with recordings, plus the first-run fixes they exposed (3.5.0-DOC14, B132-B137) - #6

Merged
KeithRaghubar merged 15 commits into
mainfrom
docs/readme-first-screen
Oct 23, 2026
Merged

Short README with recordings, plus the first-run fixes they exposed (3.5.0-DOC14, B132-B137)#6
KeithRaghubar merged 15 commits into
mainfrom
docs/readme-first-screen

Conversation

@KeithRaghubar

@KeithRaghubar KeithRaghubar commented Oct 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

A shorter README with real recordings, the first-run bugs those recordings exposed, and two terminal-rendering fixes.

Docs

  • 3.5.0-DOC14: the README goes from about 500 lines to 86. It opens with a recording and the four Quick start commands, then gives each section one paragraph and a link. The detail moved into new guides under docs/guides/: getting-started, commands, sandbox, what-sysforge-touches, fresh-install, from-a-checkout and verifying-releases.
  • 3.5.0-DEV19: make demo-gif records three vhs tapes in a fresh Arch container (tools/demo/), with sysforge built from the branch HEAD: the Quick start (README), a repo package build (getting-started guide) and flag drift after a profile change (drift guide). make dev-deps gains a docs tier (vhs, Fira Code).
  • 3.5.0-DEV20: make readme-preview [FILE=] renders Markdown through GitHub's renderer and opens it.
  • 12-logging.md: plain-mode [PROGRESS] lines are the one deliberate use of ui() for narration.

Fixes found by following the Quick start in that container

  • 3.5.0-B134: until the sysforge group applies at your next login, the first session after install could not write the state dir. It now gets a per-user ACL.
  • 3.5.0-B135: a build sysforge could not record was a warning hidden behind -v, and update crashed with a traceback. Both are now clean errors.
  • 3.5.0-B136: the "Initial setup is incomplete" notice never cleared, because a standalone run reconfigure was never recorded as having run.
  • 3.5.0-B137: the stage lock was created 0644 by root, which silently disabled the check against overlapping runs for user runs.

Terminal rendering

  • 3.5.0-B132: the shell prompt landed on top of update's output: ?1049l restored a stale saved cursor.
  • 3.5.0-B133: in xterm.js terminals (VS Code), the first line of output overwrote the command line, because the bar scrolled while a cursor was saved.

Also included: 3.5.0-B130 (cargo progress line in the sandbox) and 3.5.0-B131 (cpu_quota/mem_limit for sandboxed builds). Both were committed on local main but not pushed, and this branch is based on them.

Filed, not fixed: 3.5.0-B138 (a failure before install leaves a stale sentinel) and 3.5.0-DEV21 (an end-to-end test tier that runs the documented paths on a fresh system).

Each fix has a test that failed before it. The B134 to B137 fixes were also verified end to end in a fresh container. Commit 51d542b0 (B134) also carries two asset moves that belong to the demo commit; the squash merge removes the split.

Checklist

  • Release-note entry in docs/release-notes/unreleased.md, led by its roadmap ID
  • If a user-facing surface changed: make surface committed, and its diff matches what I meant to change (no surface change; make check-surface passes)
  • If a name was removed or renamed: the old one is in tools/retired_names.toml (none removed)
  • The guide for this feature (docs/guides/) still describes it correctly
  • make pre-release (or make ci-local) passes locally. Not run as a whole: the full suite (7,518 passed), lint and every check-* gate passed individually.

🤖 Generated with Claude Code

KeithRaghubar and others added 15 commits October 22, 2026 19:43
@KeithRaghubar
fix(sandbox): clear cargo's progress line before the next line (3.5.0…
4f72da1 
…-B130)
@KeithRaghubar
fix(sandbox): apply cpu_quota and mem_limit to the build container (3…
4cae532 
….5.0-B131)
@KeithRaghubar @claude
fix(update): keep the cursor in place on the end-of-run terminal rese…
9150440 
…t (3.5.0-B132)

?1049l restores the saved cursor even when no alternate screen was entered
(xterm, xterm.js), and the progress bar leaves a stale DECSC behind, so the
prompt was drawn over the run's output. Save the current position first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
fix(progress): reserve the bar row without scrolling under a saved cu…
1d54870 
…rsor (3.5.0-B133)

The establish sequence saved the cursor, scrolled with ESC D on the bottom row
and restored it. xterm.js restores a DECSC relative to the content, so the
cursor came back a line high and the first output line overwrote the command.
Index at the content cursor first, then save/set region/restore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
docs(design): note plain-mode progress as the one ui() narration exce…
b0e9f73 
…ption

The rubric says ui() is not progress narration, yet plain-mode [PROGRESS]
lines go through ui() on purpose so piped runs are not silent. Say so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
docs(readme): open with a demo and a "What SysForge touches" section …
bc7ae78 
…(3.5.0-DOC14, DEV19)

The first screen now shows a terminal recording (resolve flags, update drift)
and a one-line install; the makepkg/pacman relationship moves to its own
section. A new section lists what the package installs, what it writes as
the user, what it runs with sudo, and how to undo it. make demo-gif
re-records the GIF from docs/assets/demo.tape against a scratch copy of the
live config/state (tools/record-demo.sh).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
dev: make readme-preview renders Markdown as GitHub does and opens it…
0887aab 
… (3.5.0-DEV20)

GitHub's own renderer (gh api markdown, GFM), GitHub's stylesheet at the repo
page width, and a <base> at the file's directory so images and relative links
load from the working tree. FILE= previews any other Markdown file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
docs(readme): one paragraph per section, detail moved into guides (3.…
80ccb5b 
…5.0-DOC14)

The README was about 500 lines. Each section is now a short paragraph and a
link; the body moved largely unchanged into docs/guides/ (getting-started,
commands, sandbox, what-sysforge-touches, fresh-install, from-a-checkout,
verifying-releases). Links to the old README sections now point at the
guides, and the stage-numbering tests read the fresh-install guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
fix(fs_provision): grant a per-user ACL until the sysforge group appl…
51d542b 
…ies (3.5.0-B134)

usermod -aG only reaches a session at its next login, so the chgrp/chmod
repair left the state dir closed to the first session after install: builds
went unrecorded and update crashed. When the process does not hold the group
yet, grant the build user an inherited ACL on the tree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
fix(build): report an unwritable build record as an error (3.5.0-B135)
384f599 
The record site used warn(), hidden at the default verbosity, so a build that
could not be recorded looked fine while update would never maintain it.
BuildState.save now raises a RuntimeError naming the file, which update's
verb runner reports as one clean line instead of a traceback.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
fix(init): the first-install notice clears after a standalone reconfi…
541e4b7 
…gure (3.5.0-B136)

reconfigure is stateless, so run_stage_standalone never recorded it and the
notice, which waited for its status to read done, could never clear. A
stateless stage now records first_done_at only (note_completed), leaving its
status unset so run pipeline --resume still runs it; the notice asks
stage_ever_done.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
fix(lock): keep the stage lock usable by the user after a sudo run (3…
f647868 
….5.0-B137)

build_lock created the lock 0644, so once root created it no user run could
open it read-write and concurrent-run detection was silently off. Create it
0664 (fchmod past the umask) and fall back to flock on a read-only fd.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
docs(roadmap): file 3.5.0-B138, a pre-install failure leaves a stale …
c8ed827 
…sentinel

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
dev(demo): record the docs' recordings in a fresh Arch container (3.5…
a0dbaa7 
….0-DEV19, DOC14)

Three tapes: the README Quick start (an AUR package reviewed, built and
maintained), a repo package rebuilt from source (getting-started guide) and
a profile change with its flag drift and rebuild (drift guide). Each runs in
its own container from an image where sysforge is built from the branch HEAD
and the one-time setup has run (tools/demo/). make dev-deps gains a docs tier
(vhs, Fira Code).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar @claude
docs(roadmap): file 3.5.0-DEV21, an end-to-end test tier on a fresh s…
50f7a38 
…ystem

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KeithRaghubar
KeithRaghubar merged commit 933f8d4 into main Oct 23, 2026
1 check passed
@KeithRaghubar
KeithRaghubar deleted the docs/readme-first-screen branch October 23, 2026 16:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@KeithRaghubar