docs: README demo GIFs; build: keep the venv off iCloud - #42
Conversation
Two short recordings rather than one long one: `docs/demo.gif` shows the working loop and sits under the pitch, `docs/demo-install.gif` shows `nightly init` and sits in the install section where the reader is deciding whether to run it. Both are reproducible, which is the point of scripting them instead of screen-recording by hand — `bash docs/demo-prep.sh <bare|init>` builds a throwaway repo and `vhs docs/<tape>` re-renders. They can be regenerated when the CLI output changes rather than slowly drifting out of date. Three things the recording had to get right: The loop demo transitions the task to `in_progress` before calling `nightly next`. That is not padding: `ready` is deliberately not a cascade source (only `in_progress` and an approved `blocked:` are), so a demo that skipped the transition would end on "no work — backlog is empty" — the opposite of the point. Sleeps are sized to the slowest observed run of each command. The first cut used 3s after `nightly init`, and the next command's keystrokes interleaved with init's own output mid-line, which reads as a bug. The install demo records the *per-repo* bootstrap, not `curl … | bash`. The binary install mutates the operator's own machine, which is not something a re-runnable demo should do. It ends on `ls -a` so the reader sees the entire footprint before running anything. Rendered with vhs, optimized with `gifsicle -O3 --lossy=30 --colors 64` — 40-44% smaller, and frame-checked afterwards to confirm the terminal text is still legible. 81KB and 47KB, both far under the 8MB README budget. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Under iCloud Drive every freshly written file inherits the parent's UF_HIDDEN flag, and `site.py` skips hidden `.pth` files. The editable install of the workspace packages therefore stops being applied — and the failure looks nothing like its cause. `uv sync` reports success, `uv sync --all-packages` reports success, and then all 1563 tests die with `ModuleNotFoundError: No module named 'nightly_core'` on a checkout that is completely healthy. Verified directly: every `.pth` under `.venv/lib` was flagged `hidden`. Same root cause and the same `chflags` remedy as ulmentflam/corpus-forge, which diagnosed it first. Relocating is the wider fix, so `make sync` now builds the venv under `$XDG_CACHE_HOME/nightly/venvs/<repo>-<hash>` and leaves `.venv` as a symlink to it. Nothing on the import path is under fileproviderd, which also rules out the eviction-to-`.icloud`-placeholder failure that the `chflags` fix alone would not have covered. `unhide-pth` stays as the narrower repair for anyone who runs `uv sync` directly, bypassing make. The path test mirrors `nightly_core.worktree.is_icloud_path`. Off macOS and outside iCloud, `VENV_DIR` is empty and every target behaves exactly as before — CI is untouched. `make venv-path` prints which branch is active, and `make nuke` now removes the out-of-tree venv too. Two traps worth recording, both hit while writing this: `case` cannot be used inside `$(shell …)`. make matches parentheses when it scans the function, so the unbalanced `)` closing a case arm terminates it early and the expansion silently comes back wrong — it produced the hash of an empty string. `grep` keeps every paren balanced. `.gitignore` needed a bare `.venv` alongside `.venv/`. A directory-only pattern does not match a symlink, so the relocated `.venv` showed up as untracked and would have been committed. Verified end-to-end: `make install` relocates and links, the `.pth` files come back unflagged, `import nightly_core` succeeds, and all 1563 tests pass. `nightly verify` clean on all five checks. Confirmed the non-iCloud branch separately by running the same Makefile from /tmp. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`rules.py` gained rule 12 (fleet doctrine) and rule 13 (pre-flight verification) in #39, but this repo's own AGENTS.md / CLAUDE.md were never regenerated — so Nightly running against Nightly was reading a contract two rules short of the one it ships to every other repo. `nightly update` rewrites the marker-delimited block; this is that output, committed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 42 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (8)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
1 participant
Three commits: the README demo GIFs, a build fix for iCloud checkouts, and a docs sync that fell out of #39.
Demo GIFs
Two short recordings rather than one long one —
docs/demo.gifunder the pitch,docs/demo-install.gifin the install section where a reader is deciding whether to run it.Both are reproducible, which is the point of scripting them instead of screen-recording by hand:
bash docs/demo-prep.sh <bare|init>builds a throwaway repo andvhs docs/<tape>re-renders. They can be regenerated when the CLI output changes rather than drifting out of date.Three things the recording had to get right:
in_progressbeforenightly next. Not padding:readyis deliberately not a cascade source (onlyin_progressand an approvedblocked:are), so a demo that skipped it would have ended on "no work — backlog is empty" — the opposite of the point.nightly init3s, and the next command's keystrokes interleaved with init's own output mid-line, which reads as a bug.curl … | bash. The binary install mutates the operator's own machine, which is not something a re-runnable demo should do on every render. It ends onls -aso the footprint is visible before anyone runs it.Optimized with
gifsicle -O3 --lossy=30 --colors 64— 40-44% smaller, then frame-checked to confirm terminal text is still legible. 81KB and 47KB, far under the 8MB README budget.iCloud venv fix
Under iCloud Drive every freshly written file inherits the parent's
UF_HIDDENflag, andsite.pyskips hidden.pthfiles. The editable install of the workspace packages therefore stops applying — and the failure looks nothing like its cause:uv syncreports success, then all 1563 tests die withModuleNotFoundError: No module named 'nightly_core'on a completely healthy checkout. Verified directly — every.pthunder.venv/libwas flaggedhidden.Same root cause and the same
chflagsremedy as corpus-forge, which diagnosed it first.Relocating is the wider fix:
make syncnow builds the venv under$XDG_CACHE_HOME/nightly/venvs/<repo>-<hash>and leaves.venvas a symlink. Nothing on the import path is under fileproviderd, which also rules out the eviction-to-.icloud-placeholder failure thatchflagsalone would not cover.unhide-pthremains as the narrower repair for anyone runninguv syncdirectly.Off macOS and outside iCloud,
VENV_DIRis empty and every target behaves exactly as before — CI is untouched. Confirmed by running the same Makefile from/tmp.Two traps worth recording, both hit while writing this:
casecannot be used inside$(shell …). make matches parentheses when it scans the function, so the unbalanced)closing a case arm terminates it early and the expansion silently comes back wrong — it produced the hash of an empty string.grepkeeps every paren balanced..gitignoreneeded a bare.venvalongside.venv/. A directory-only pattern does not match a symlink, so the relocated.venvshowed up untracked and would have been committed.Rules sync
rules.pygained rules 12 and 13 in #39, but this repo's ownAGENTS.md/CLAUDE.mdwere never regenerated — so Nightly running against Nightly was reading a contract two rules shorter than the one it ships everywhere else.Verification
make installrelocates and links,.pthfiles come back unflagged,import nightly_coresucceeds, 1563 tests pass,nightly verifyclean on all five checks.🤖 Generated with Claude Code