Updating docs/.scrolls/

docs/.scrolls/ only stays useful if it reflects reality. This skill applies the update rules STARTER.md already defines for each file — it does not invent new conventions. The point isn't to touch every file every time; it's to touch exactly the files that something actually happened to, using the update discipline that file's own convention calls for (overwrite vs. append vs. add/remove in lockstep).

It also idempotently backfills SCROLLS.md, CLAUDE.md, and AGENTS.md for a project set up before those existed — this is the command people run every session, so it's the one that closes that gap automatically, not just the one-time /scrolls-setup. See step 2.

Cross-platform

The one bundled script (step 4) ships in two forms: session_diff.sh (bash — macOS, Linux, or Windows with Git Bash/WSL) and session_diff.ps1 (PowerShell 7+ — Windows, or macOS/Linux with pwsh installed). Everything else in this skill — the flags, BASE_DIR resolution, locating the scrolls folder — is plain prose you follow directly; it only ever invokes git, which behaves identically regardless of which shell is running it, so none of that needs a shell-specific variant. Pick the script by what's actually available: try bash --version; if that succeeds, use the .sh script; otherwise use the .ps1 script via pwsh (preferred — install from https://aka.ms/powershell if missing) or, only if pwsh genuinely isn't available, the built-in Windows PowerShell powershell.exe (untested against that older version; pwsh is what this was written and verified against).

Options

Read the invocation text for these, in any order — there's no real argv parser here, so pull them out of the plain text yourself:

• -p <path> / --path=<path> / --path <path> — a custom docs folder to look in, relative to the current working directory unless given as an absolute path.
• -t / --reporoot — look under the git repository's top level ($(git rev-parse --show-toplevel)) regardless of which subdirectory you actually invoked this from. Fails with a clear message if the current directory isn't inside a git repository.
• -l / --local — look explicitly in the current working directory. This is what happens by default anyway when none of -p/-t/-l are given — the flag exists to say so on purpose, e.g. to skip the mismatch check below.
• -r / --recurse — if the scrolls folder isn't at the obvious exact location (BASE_DIR/docs/.scrolls or BASE_DIR/docs/scrolls), search recursively under BASE_DIR for one instead of giving up. Off by default — matches the usual meaning of -r on tools like grep/cp/rm.