Setting up docs/.scrolls/

docs/.scrolls/ is a small set of markdown files that act as a project's working memory across sessions: what it does, what state it's in, what's known-missing and why, what's next, and what traps to avoid. A SCROLLS.md file sends every future session to docs/.scrolls/STARTER.md first, so state gets picked up instead of re-discovered from scratch each time — with a short CLAUDE.md pointer to SCROLLS.md, and a matching AGENTS.md pointer to CLAUDE.md for harnesses that read that file instead. This skill scaffolds that system for a project that doesn't have it yet.

This skill's own assets/templates/ directory holds the source templates — copy from there, never edit those files in place.

Cross-platform

Unlike the other four scrolls skills, this one has no bundled .sh/.ps1 script to choose between — nothing here needed porting. File creation happens through your own Read/Write/Edit tools (not raw shell commands), and the one external command this skill relies on (git rev-parse --show-toplevel) behaves identically whether invoked from bash or PowerShell — both support the same $(...) command-substitution syntax used throughout this file. Works the same on macOS, Linux, and Windows without any environment-specific branching.

Options

The user may pass these after /scrolls-setup as plain text, in any order — there's no real argv parser here, so read the invocation text yourself and pull out:

• -p <path> / --path=<path> / --path <path> — a custom docs folder, relative to the current working directory unless given as an absolute path (starts with /). Use this for monorepos or non-standard layouts, e.g. --path=packages/api/docs puts the scrolls at packages/api/docs/.scrolls. This is the one option where you're naming the docs folder directly rather than picking a base directory — see the SCROLLS.md/CLAUDE.md placement note in step 4 for the tradeoff that comes with going deep.
• -t / --reporoot — pin everything to 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 — there's no repo root to find.
• -l / --local — pin everything to the current working directory explicitly. This is what happens by default anyway when none of -p/-t/-l are given — the flag exists so you (or the user) can say so on purpose, e.g. to skip the mismatch check in step 1.
• -r / --recurse — before creating anything, scan recursively under BASE_DIR for a scrolls folder that already exists somewhere nearby (same bounded, pruned, STARTER.md-guarded search /scrolls-hide//scrolls-unhide use), so a duplicate isn't created by accident. Doesn't change where the new scrolls folder goes if you proceed — see step 1.
• -u / --unhide — name the scrolls folder scrolls instead of the default .scrolls, so it isn't dotfile-hidden. Omit for the default (hidden).