fix(setup): render the gbrain :user variant to an out-dir — global installs stay git-clean

On a global-git install with gbrain, ./setup and 'gstack-config
gbrain-refresh' ran gen:skill-docs:user IN PLACE inside the install
checkout, rewriting ~16 TRACKED SKILL.md files. The checkout stayed
permanently dirty, every /gstack-upgrade 'git stash' saved a redundant
snapshot of generated content, and the growing stash list invited a 'git
stash pop' that would lay stale instruction markdown from an older gstack
over the current version — a quiet wrong-rules failure mode.

Fix, wired through machinery that already existed (gen-skill-docs
--out-dir + the symlink install layer): brain-aware SKILL.md now renders
into the untracked ~/.gstack/render/claude, and both Claude installers
serve the render when present — setup's link_claude_skill_dirs prefers
$GSTACK_HOME/render/claude/<skill>/SKILL.md, and bin/gstack-relink does
the same so a later config change can't silently flip skills back to the
blockless canonical source. setup wipes and rebuilds the render each run,
repoints installed skills after a successful render, and removes a stale
render (re-linking canonical) when gbrain is gone. gbrain-refresh renders
to the out-dir and repoints via relink; its 'this dirties the install's
git tree' caveat is retired because it no longer does.

A one-time upgrade migration (gstack-upgrade/migrations/v1.67.0.0.sh, F12)
restores the legacy dirt: unstaged modifications to SKILL.md / sections/
*.md files in the install checkout are git-checkout'd back to canonical;
anything outside that footprint (user edits, untracked files, staged work)
is left alone and reported. Idempotent, non-fatal, symlinked installs
skipped.

Tests: render-preference behavior for both installers, static pins that
every executable :user invocation carries --out-dir and the caveat text is
gone, migration fixture (restore/leave/idempotent/no-op matrix), and the
existing out-dir render test now asserts 'git status --porcelain' gains
zero new entries across a full :user render.

Fixes #2569

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

bin/gstack-config

@@ -440,27 +440,35 @@ case "${1:-}" in
         # treatment as "ok", matching gstack-gbrain-detect --is-ok and
         # gen-skill-docs.
         echo "Detected gbrain v$VERSION (local-status: $STATUS)."
-        # Render brain-aware blocks INTO the global install so EVERY project's
-        # Claude sessions get them (other projects read SKILL.md + sections from
-        # ~/.claude/skills/gstack via absolute paths baked at gen time). Guards
-        # (never mutate an arbitrary directory): the target must exist, not be a
-        # symlink (a symlinked install points at a dev worktree — rendering there
-        # would dirty tracked source), and look like a real gstack clone.
+        # Render brain-aware blocks into an UNTRACKED out-dir (#2569) and
+        # repoint the installed skills at it — the old in-place render wrote
+        # into TRACKED files of the global install checkout, so the checkout
+        # stayed permanently dirty and every upgrade grew a redundant stash.
+        # Guards (never mutate an arbitrary directory): the install must
+        # exist, not be a symlink (a symlinked install points at a dev
+        # worktree — bin/dev-setup owns that flow), and look like a real
+        # gstack clone.
         INSTALL_DIR="$HOME/.claude/skills/gstack"
+        RENDER_DIR="${GSTACK_USER_RENDER_DIR:-${GSTACK_HOME:-$HOME/.gstack}/render/claude}"
         if [ ! -d "$INSTALL_DIR" ]; then
           echo "No global install at $INSTALL_DIR — nothing to render. (Dev workspaces get blocks via bin/dev-setup.)"
         elif [ -L "$INSTALL_DIR" ]; then
-          echo "Skip: $INSTALL_DIR is a symlink (likely a dev worktree). Rendering there would dirty tracked source — run bin/dev-setup in that worktree instead."
+          echo "Skip: $INSTALL_DIR is a symlink (likely a dev worktree). Run bin/dev-setup in that worktree instead."
         elif [ ! -f "$INSTALL_DIR/VERSION" ] || [ ! -f "$INSTALL_DIR/package.json" ]; then
           echo "Skip: $INSTALL_DIR doesn't look like a gstack clone (missing VERSION/package.json) — refusing to modify it."
         elif ! command -v bun >/dev/null 2>&1; then
           echo "Skip: bun not on PATH — can't render. Install bun, then re-run 'gstack-config gbrain-refresh'."
-        elif ( cd "$INSTALL_DIR" && bun run gen:skill-docs:user --host claude >/dev/null 2>&1 ); then
-          echo "Rendered brain-aware blocks into $INSTALL_DIR — now live across all your projects' Claude sessions."
-          echo "Note: this dirties the install's git tree (generated blocks differ from main, by design)."
-          echo "      A 'git reset --hard origin/main' there reverts them; re-run 'gstack-config gbrain-refresh' to restore."
         else
-          echo "Warning: render failed. Run 'cd $INSTALL_DIR && bun run gen:skill-docs:user --host claude' manually to see the error."
+          rm -rf "$RENDER_DIR"
+          if ( cd "$INSTALL_DIR" && bun run gen:skill-docs:user --host claude --out-dir "$RENDER_DIR" >/dev/null 2>&1 ); then
+            # Repoint installed skills at the render — gstack-relink prefers
+            # the render dir when present.
+            "$INSTALL_DIR/bin/gstack-relink" >/dev/null 2>&1 || true
+            echo "Rendered brain-aware blocks into $RENDER_DIR — now live across all your projects' Claude sessions."
+            echo "The install checkout stays clean: upgrades no longer stash generated render dirt (#2569)."
+          else
+            echo "Warning: render failed. Run 'cd $INSTALL_DIR && bun run gen:skill-docs:user --host claude --out-dir $RENDER_DIR' manually to see the error."
+          fi
         fi
         ;;
       *)

bin/gstack-relink

@@ -36,6 +36,12 @@ SKILLS_DIR="${GSTACK_SKILLS_DIR:-$(dirname "$INSTALL_DIR")}"
 # Read prefix setting
 PREFIX=$("$GSTACK_CONFIG" get skill_prefix 2>/dev/null || echo "false")
 
+# #2569: rendered :user variants (brain-aware blocks) live in an UNTRACKED
+# out-dir instead of the tracked install checkout. When a render exists for a
+# skill, relink serves it — otherwise a config change would silently flip
+# every skill back to the canonical (blockless) source.
+RENDER_DIR="${GSTACK_USER_RENDER_DIR:-${GSTACK_HOME:-$HOME/.gstack}/render/claude}"
+
 # Helper: remove old skill entry (symlink or real directory with symlinked SKILL.md)
 _cleanup_skill_entry() {
   local entry="$1"
@@ -98,7 +104,9 @@ for skill_dir in "$INSTALL_DIR"/*/; do
   [ -L "$target" ] && rm -f "$target"
   # Create real directory with symlinked SKILL.md (absolute path)
   mkdir -p "$target"
-  ln -snf "$INSTALL_DIR/$skill/SKILL.md" "$target/SKILL.md"
+  skill_md_src="$INSTALL_DIR/$skill/SKILL.md"
+  [ -f "$RENDER_DIR/$skill/SKILL.md" ] && skill_md_src="$RENDER_DIR/$skill/SKILL.md"
+  ln -snf "$skill_md_src" "$target/SKILL.md"
   SKILL_COUNT=$((SKILL_COUNT + 1))
 done