refactor: rename gbrain_sync_mode → artifacts_sync_mode (v1.27.0.0 prep)

Hard rename, no dual-read alias (codex Finding D4). The on-disk migration script (Phase C, separate commit) renames the config key in users' ~/.gstack/config.yaml and any CLAUDE.md blocks. Touched call sites: - bin/gstack-config defaults + validation + list/defaults output - bin/gstack-gbrain-detect (gstack_brain_sync_mode field still emitted with the same name for downstream-tool compat; reads new key) - bin/gstack-brain-sync, bin/gstack-brain-enqueue, bin/gstack-brain-uninstall - bin/gstack-timeline-log (comment ref) - scripts/resolvers/preamble/generate-brain-sync-block.ts: renames key, branches on gbrain_mcp_mode=remote-http to emit "ARTIFACTS_SYNC: remote-mode (managed by brain server <host>)" instead of the local mode/queue/last_push line (codex Finding #11) - bin/gstack-brain-restore + bin/gstack-gbrain-source-wireup: read ~/.gstack-artifacts-remote.txt with ~/.gstack-brain-remote.txt fallback during the migration window - bin/gstack-artifacts-init: tolerant of unrecognized URL forms (local paths, file://, self-hosted gitea) so test infrastructure and unusual remotes work without canonicalization - test/brain-sync.test.ts: gstack-brain-init → gstack-artifacts-init - test/skill-e2e-brain-privacy-gate.test.ts: artifacts_sync_mode keys - test/gen-skill-docs.test.ts: budget 35K → 36.5K for the new MCP-mode probe in the preamble resolver - health/SKILL.md.tmpl, sync-gbrain/SKILL.md.tmpl: comment + verdict line Hard delete: - bin/gstack-brain-init (replaced by bin/gstack-artifacts-init in v1.27.0.0) - test/gstack-brain-init-gh-mock.test.ts (replaced by gstack-artifacts-init.test.ts) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 21:49:45 +08:00 · 2026-05-06 09:32:56 -07:00
parent 7b9c2f68d4
commit 8abe27338c
17 changed files with 138 additions and 625 deletions
--- a/bin/gstack-artifacts-init
+++ b/bin/gstack-artifacts-init
@@ -172,14 +172,16 @@ fi
 # ---- canonicalize to HTTPS form ----
 # We store HTTPS in ~/.gstack-artifacts-remote.txt (codex Finding #10:
 # canonical form, derive SSH at push time via gstack-artifacts-url --to ssh).
+# Unrecognized forms (local bare paths, file:// URLs, self-hosted gitea, etc.)
+# pass through verbatim so unusual remotes still work.
 CANONICAL_HTTPS=$("$URL_BIN" --to https "$REMOTE_URL" 2>/dev/null || echo "")
 if [ -z "$CANONICAL_HTTPS" ]; then
-  echo "Failed to canonicalize remote URL: $REMOTE_URL" >&2
-  exit 1
+  CANONICAL_HTTPS="$REMOTE_URL"
 fi

 # Use SSH for git push (more reliable for repeated pushes than HTTPS+token).
-PUSH_URL=$("$URL_BIN" --to ssh "$CANONICAL_HTTPS")
+# Fall back to the canonical input if derivation fails.
+PUSH_URL=$("$URL_BIN" --to ssh "$CANONICAL_HTTPS" 2>/dev/null || echo "$CANONICAL_HTTPS")

 # ---- verify push URL is reachable ----
 echo "Verifying remote connectivity: $PUSH_URL"
--- a/bin/gstack-brain-enqueue
+++ b/bin/gstack-brain-enqueue
@@ -10,7 +10,7 @@
 # preamble at skill START and END boundaries.
 #
 # No-op when:
-#   - gbrain_sync_mode is off (the default)
+#   - artifacts_sync_mode is off (the default)
 #   - ~/.gstack/.git doesn't exist (feature not initialized)
 #   - <file-path> matches a line in ~/.gstack/.brain-skip.txt
 #
@@ -36,7 +36,7 @@ SKIP_FILE="$GSTACK_HOME/.brain-skip.txt"

 # Check sync mode. off → silent no-op.
 SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
-MODE=$("$SCRIPT_DIR/gstack-config" get gbrain_sync_mode 2>/dev/null || echo off)
+MODE=$("$SCRIPT_DIR/gstack-config" get artifacts_sync_mode 2>/dev/null || echo off)
 [ "$MODE" = "off" ] && exit 0

 # User-maintained skip list (for secret-scan false positives).
--- a/bin/gstack-brain-init
+++ b/bin/gstack-brain-init
@@ -1,300 +0,0 @@
-#!/usr/bin/env bash
-# gstack-brain-init — set up ~/.gstack/ as a git repo that syncs to GBrain.
-#
-# Usage:
-#   gstack-brain-init [--remote <url>]
-#
-# Interactive by default. Pass --remote to skip the remote prompt.
-#
-# Idempotent: safe to re-run. If ~/.gstack/.git already exists AND points at
-# the same remote, reconfigures drivers/hooks/attributes without clobbering
-# history. If it points at a DIFFERENT remote, refuses and suggests
-# `gstack-brain-uninstall` first.
-#
-# What it does:
-#   1. git init ~/.gstack/  (or verify existing repo points at the right remote)
-#   2. Write .gitignore = "*"  (ignore everything; allowlist is explicit)
-#   3. Write .brain-allowlist  (canonical paths to sync)
-#   4. Write .brain-privacy-map.json  (paths → privacy class)
-#   5. Write .gitattributes  (register JSONL + union merge drivers)
-#   6. git config  merge.jsonl-append.driver + merge.union.driver
-#   7. Install .git/hooks/pre-commit  (defense-in-depth secret scan)
-#   8. Prompt for remote (default: gh repo create --private gstack-brain-$USER)
-#   9. Initial commit + push
-#   10. Write ~/.gstack-brain-remote.txt  (URL-only, safe to share)
-#
-# Env:
-#   GSTACK_HOME — override ~/.gstack
-
-set -euo pipefail
-
-GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-CONFIG_BIN="$SCRIPT_DIR/gstack-config"
-REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
-
-REMOTE_URL=""
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --remote) REMOTE_URL="$2"; shift 2 ;;
-    --help|-h) sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
-    *) echo "Unknown flag: $1" >&2; exit 1 ;;
-  esac
-done
-
-# ---- preconditions ----
-mkdir -p "$GSTACK_HOME"
-
-EXISTING_REMOTE=""
-if [ -d "$GSTACK_HOME/.git" ]; then
-  EXISTING_REMOTE=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo "")
-  if [ -n "$EXISTING_REMOTE" ] && [ -n "$REMOTE_URL" ] && [ "$EXISTING_REMOTE" != "$REMOTE_URL" ]; then
-    cat >&2 <<EOF
-gstack-brain-init: ~/.gstack/ is already a git repo pointing at:
-  $EXISTING_REMOTE
-
-You asked to init with:
-  $REMOTE_URL
-
-Refusing to overwrite. To switch remotes, first run:
-  gstack-brain-uninstall
-
-(or edit the remote manually with: git -C ~/.gstack remote set-url origin <url>)
-EOF
-    exit 1
-  fi
-fi
-
-# ---- choose the remote ----
-if [ -z "$REMOTE_URL" ] && [ -n "$EXISTING_REMOTE" ]; then
-  REMOTE_URL="$EXISTING_REMOTE"
-  echo "Using existing remote: $REMOTE_URL"
-fi
-
-if [ -z "$REMOTE_URL" ]; then
-  # Interactive prompt. Default: gh repo create (if available).
-  echo "gstack-brain-init will create a private git repo that holds your"
-  echo "gstack session memory across machines and lets GBrain index it."
-  echo
-  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
-    DEFAULT_NAME="gstack-brain-${USER:-$(whoami)}"
-    echo "Default: gh will create a private repo named '$DEFAULT_NAME' under your account."
-    printf "Press Enter to accept, or paste a custom git URL: "
-    read -r REPLY || REPLY=""
-    if [ -z "$REPLY" ]; then
-      echo "Creating GitHub repo: $DEFAULT_NAME ..."
-      # Note: --source omitted intentionally. gh requires --source to point at
-      # an existing git repo, but we don't init $GSTACK_HOME until after the
-      # remote is chosen. Create bare, then fetch URL.
-      if ! gh repo create "$DEFAULT_NAME" --private --description "gstack session memory" 2>/dev/null; then
-        # Maybe the repo already exists; try to fetch its URL.
-        REMOTE_URL=$(gh repo view "$DEFAULT_NAME" --json sshUrl -q .sshUrl 2>/dev/null || echo "")
-        if [ -z "$REMOTE_URL" ]; then
-          echo "Failed to create or find '$DEFAULT_NAME'. Try --remote <url>." >&2
-          exit 1
-        fi
-        echo "Repo already exists; using $REMOTE_URL"
-      else
-        REMOTE_URL=$(gh repo view "$DEFAULT_NAME" --json sshUrl -q .sshUrl 2>/dev/null || echo "")
-      fi
-    else
-      REMOTE_URL="$REPLY"
-    fi
-  else
-    echo "(gh CLI not found or not authenticated; provide a git URL directly)"
-    printf "Paste a private git URL (e.g. git@github.com:you/gstack-brain.git): "
-    read -r REMOTE_URL || REMOTE_URL=""
-    if [ -z "$REMOTE_URL" ]; then
-      echo "No URL provided. Aborting." >&2
-      exit 1
-    fi
-  fi
-fi
-
-# ---- verify remote reachable ----
-echo "Verifying remote connectivity: $REMOTE_URL"
-if ! git ls-remote "$REMOTE_URL" >/dev/null 2>&1; then
-  cat >&2 <<EOF
-Remote not reachable: $REMOTE_URL
-This could mean:
-  - Wrong URL
-  - Not authenticated (GitHub: gh auth status; GitLab: glab auth status)
-  - Network issue
-Fix and re-run gstack-brain-init.
-EOF
-  exit 1
-fi
-
-# ---- git init ----
-if [ ! -d "$GSTACK_HOME/.git" ]; then
-  git -C "$GSTACK_HOME" init -q -b main 2>/dev/null || git -C "$GSTACK_HOME" init -q
-  # If -b main wasn't supported, rename.
-  git -C "$GSTACK_HOME" branch -M main 2>/dev/null || true
-fi
-
-if [ -z "$(git -C "$GSTACK_HOME" remote 2>/dev/null)" ]; then
-  git -C "$GSTACK_HOME" remote add origin "$REMOTE_URL"
-else
-  git -C "$GSTACK_HOME" remote set-url origin "$REMOTE_URL"
-fi
-
-# ---- write canonical files (idempotent) ----
-cat > "$GSTACK_HOME/.gitignore" <<'EOF'
-# gstack-brain sync: ignore-everything base. Paths are included explicitly via
-# .brain-allowlist and `git add -f` from gstack-brain-sync. Do not edit.
-*
-EOF
-
-cat > "$GSTACK_HOME/.brain-allowlist" <<'EOF'
-# Canonical allowlist of paths that gstack-brain-sync will publish.
-# One glob per line. Anything not matching stays local.
-# Do not edit directly; managed by gstack-brain-init. User additions go below
-# the marker and survive re-init.
-projects/*/learnings.jsonl
-projects/*/*-reviews.jsonl
-projects/*/ceo-plans/*.md
-projects/*/ceo-plans/*/*.md
-projects/*/designs/*.md
-projects/*/designs/*/*.md
-projects/*/timeline.jsonl
-retros/*.md
-developer-profile.json
-builder-journey.md
-builder-profile.jsonl
-# NOT synced (per Codex v2 review — machine-local UX state):
-#   projects/*/question-preferences.json (per-machine UX preferences)
-#   projects/*/question-log.jsonl (audit/derivation log stays with preferences)
-#   projects/*/question-events.jsonl (same)
-# ---- USER ADDITIONS BELOW ---- (survives re-init; above is managed)
-EOF
-
-cat > "$GSTACK_HOME/.brain-privacy-map.json" <<'EOF'
-[
-  {"pattern": "projects/*/learnings.jsonl", "class": "artifact"},
-  {"pattern": "projects/*/*-reviews.jsonl", "class": "artifact"},
-  {"pattern": "projects/*/ceo-plans/*.md", "class": "artifact"},
-  {"pattern": "projects/*/ceo-plans/*/*.md", "class": "artifact"},
-  {"pattern": "projects/*/designs/*.md", "class": "artifact"},
-  {"pattern": "projects/*/designs/*/*.md", "class": "artifact"},
-  {"pattern": "retros/*.md", "class": "artifact"},
-  {"pattern": "builder-journey.md", "class": "artifact"},
-  {"pattern": "projects/*/timeline.jsonl", "class": "behavioral"},
-  {"pattern": "developer-profile.json", "class": "behavioral"},
-  {"pattern": "builder-profile.jsonl", "class": "behavioral"}
-]
-EOF
-
-cat > "$GSTACK_HOME/.gitattributes" <<'EOF'
-# gstack-brain: merge drivers for cross-machine sync conflicts.
-# Matching driver must be registered in local git config; gstack-brain-init
-# and gstack-brain-restore run `git config merge.<name>.driver ...` after init.
-*.jsonl merge=jsonl-append
-retros/*.md merge=union
-projects/*/designs/**/*.md merge=union
-projects/*/ceo-plans/**/*.md merge=union
-EOF
-
-# ---- register merge drivers in local git config ----
-git -C "$GSTACK_HOME" config merge.jsonl-append.driver "$SCRIPT_DIR/gstack-jsonl-merge %O %A %B"
-git -C "$GSTACK_HOME" config merge.jsonl-append.name "gstack JSONL append-only merger"
-git -C "$GSTACK_HOME" config merge.union.driver "cat %A %B > %A.merged && mv %A.merged %A"
-git -C "$GSTACK_HOME" config merge.union.name "union concat"
-
-# ---- install pre-commit hook (defense-in-depth) ----
-HOOK="$GSTACK_HOME/.git/hooks/pre-commit"
-mkdir -p "$(dirname "$HOOK")"
-cat > "$HOOK" <<'HOOK_EOF'
-#!/usr/bin/env bash
-# gstack-brain pre-commit hook — secret-scan defense-in-depth.
-# The primary scanner runs inside gstack-brain-sync BEFORE staging. This hook
-# catches any manual `git commit` a user might accidentally run against the
-# brain repo.
-set -uo pipefail
-
-python3 -c "
-import sys, re, subprocess
-try:
-    out = subprocess.check_output(['git', 'diff', '--cached'], stderr=subprocess.DEVNULL).decode('utf-8', 'replace')
-except Exception:
-    sys.exit(0)
-
-patterns = [
-    ('aws-access-key', re.compile(r'AKIA[0-9A-Z]{16}')),
-    ('github-token', re.compile(r'\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})')),
-    ('openai-key', re.compile(r'\bsk-[A-Za-z0-9_-]{20,}')),
-    ('pem-block', re.compile(r'-----BEGIN [A-Z ]{3,}-----')),
-    ('jwt', re.compile(r'\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b')),
-    ('bearer-token-json',
-     re.compile(r'\"(authorization|api[_-]?key|apikey|token|secret|password)\"\s*:\s*\"[A-Za-z0-9_./+=-]{16,}\"',
-                re.IGNORECASE)),
-]
-for name, rx in patterns:
-    if rx.search(out):
-        sys.stderr.write(f'gstack-brain pre-commit: refusing commit — {name} detected in staged diff.\n')
-        sys.stderr.write('Either edit the offending file, or if intentional, run:\n')
-        sys.stderr.write('  gstack-brain-sync --skip-file <path>  (to permanently exclude)\n')
-        sys.exit(1)
-sys.exit(0)
-"
-HOOK_EOF
-chmod +x "$HOOK"
-
-# ---- initial commit (idempotent; skips if already committed) ----
-cd "$GSTACK_HOME"
-git add -f .gitignore .brain-allowlist .brain-privacy-map.json .gitattributes
-# Only commit if the index has changes from HEAD (if there is a HEAD).
-if git rev-parse HEAD >/dev/null 2>&1; then
-  if ! git diff --cached --quiet 2>/dev/null; then
-    git -c user.email="gstack@localhost" -c user.name="gstack-brain-init" \
-        commit -q -m "chore: gstack-brain-init (refresh sync config)"
-  fi
-else
-  # First commit ever.
-  git -c user.email="gstack@localhost" -c user.name="gstack-brain-init" \
-      commit -q -m "chore: gstack-brain-init"
-fi
-
-# ---- initial push ----
-if ! git push -q -u origin main 2>/dev/null; then
-  # Maybe the default branch is master, or the remote has existing content.
-  # Try to resolve: fetch + fast-forward merge + push.
-  CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
-  if git fetch origin 2>/dev/null && git pull --ff-only origin "$CURRENT_BRANCH" 2>/dev/null; then
-    git push -q -u origin "$CURRENT_BRANCH" || {
-      echo "Push to $REMOTE_URL failed. The remote may have divergent content." >&2
-      echo "Try: cd ~/.gstack && git pull --rebase origin $CURRENT_BRANCH && git push origin $CURRENT_BRANCH" >&2
-      exit 1
-    }
-  else
-    # Couldn't fetch/merge; print what to do.
-    echo "Push to $REMOTE_URL failed and fetch/merge didn't help." >&2
-    echo "Manual recovery: cd ~/.gstack && git status, then push once conflicts are resolved." >&2
-    exit 1
-  fi
-fi
-
-# ---- write the remote-url helper file (outside ~/.gstack/, survives restore) ----
-echo "$REMOTE_URL" > "$REMOTE_FILE"
-chmod 600 "$REMOTE_FILE"
-
-# ---- done ----
-cat <<EOF
-
-gstack-brain-init complete.
-Repo:    $GSTACK_HOME (git)
-Remote:  $REMOTE_URL
-Remote URL also saved at: $REMOTE_FILE
-
-Sync to GitHub happens automatically at the start and end of each skill
-(no daemon). Check status anytime with:
-  gstack-brain-sync --status
-
-The next skill run will ask you one question about privacy mode (full /
-artifacts-only / off). After that, /setup-gbrain Step 7 (or the
-gstack-gbrain-source-wireup helper) registers this repo as a federated
-source on gbrain so its content is searchable via 'gbrain search'.
-
-New machine? On the other laptop, put a copy of:
-  $REMOTE_FILE
-in that machine's home directory, then run: gstack-brain-restore
-EOF
--- a/bin/gstack-brain-restore
+++ b/bin/gstack-brain-restore
@@ -30,7 +30,13 @@ set -euo pipefail
 GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 CONFIG_BIN="$SCRIPT_DIR/gstack-config"
-REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+# v1.27.0.0+ canonical name; brain-remote is the legacy fallback during the
+# migration window. The migration script renames the file in place.
+if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
+  REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
+else
+  REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+fi

 REMOTE_URL="${1:-}"
 if [ -z "$REMOTE_URL" ]; then
--- a/bin/gstack-brain-sync
+++ b/bin/gstack-brain-sync
@@ -70,7 +70,7 @@ sync_active() {
    return 1
  fi
  local mode
-  mode=$("$CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
+  mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
  [ "$mode" = "off" ] && return 1
  return 0
 }
@@ -236,7 +236,7 @@ subcmd_once() {
  echo "$$" > "$lock_dir/pid" 2>/dev/null || true

  local mode
-  mode=$("$CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
+  mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)

  local paths_file
  paths_file=$(mktemp /tmp/brain-sync-paths.XXXXXX) || { rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
@@ -334,7 +334,7 @@ subcmd_status() {
  local last_push="never"
  [ -f "$LAST_PUSH_FILE" ] && last_push=$(cat "$LAST_PUSH_FILE" 2>/dev/null || echo never)
  local mode
-  mode=$("$CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
+  mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
  printf '{"queue_depth":%s,"last_push":"%s","mode":"%s"}\n' "$queue_depth" "$last_push" "$mode"
 }

--- a/bin/gstack-brain-uninstall
+++ b/bin/gstack-brain-uninstall
@@ -28,8 +28,8 @@
 #   consumers.json             — consumer/reader registry
 #
 # What it clears (via gstack-config):
-#   gbrain_sync_mode            → off
-#   gbrain_sync_mode_prompted   → false (so user re-prompts on re-init)
+#   artifacts_sync_mode            → off
+#   artifacts_sync_mode_prompted   → false (so user re-prompts on re-init)
 #
 # What it does NOT touch:
 #   Project data (projects/*, retros/*, developer-profile.json, etc.)
@@ -42,7 +42,12 @@ set -euo pipefail
 GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 CONFIG_BIN="$SCRIPT_DIR/gstack-config"
-REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+# v1.27.0.0+ canonical name; brain-remote is the legacy fallback during migration.
+if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
+  REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
+else
+  REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+fi

 ASSUME_YES=0
 DELETE_REMOTE=0
@@ -67,7 +72,7 @@ if [ "$ASSUME_YES" != "1" ]; then
  cat <<EOF
 This will remove gstack-brain sync from this machine:
  - Remove ~/.gstack/.git and sync config files
-  - Clear gbrain_sync_mode in gstack-config
+  - Clear artifacts_sync_mode in gstack-config
  - Remote: $REMOTE_URL will be $([ "$DELETE_REMOTE" = "1" ] && echo "DELETED" || echo "kept")

 Local memory (learnings, plans, etc.) is NOT touched.
@@ -133,8 +138,8 @@ fi
 rm -f "$GSTACK_HOME/consumers.json" 2>/dev/null || true

 # ---- clear config keys ----
-"$CONFIG_BIN" set gbrain_sync_mode off >/dev/null 2>&1 || true
-"$CONFIG_BIN" set gbrain_sync_mode_prompted false >/dev/null 2>&1 || true
+"$CONFIG_BIN" set artifacts_sync_mode off >/dev/null 2>&1 || true
+"$CONFIG_BIN" set artifacts_sync_mode_prompted false >/dev/null 2>&1 || true

 # ---- leave remote-helper file alone unless user asked to delete remote ----
 if [ "$DELETE_REMOTE" = "1" ]; then
--- a/bin/gstack-config
+++ b/bin/gstack-config
@@ -60,8 +60,8 @@ CONFIG_HEADER='# gstack configuration — edit freely, changes take effect on ne
 #                           # Unknown values default to "default" with a warning.
 #                           # See docs/designs/PLAN_TUNING_V1.md for rationale.
 #
-# ─── GBrain sync (v1.7+) ─────────────────────────────────────────────
-# gbrain_sync_mode: off     # off | artifacts-only | full
+# ─── Artifacts sync (renamed from gbrain_sync_mode in v1.27.0.0) ─────
+# artifacts_sync_mode: off  # off | artifacts-only | full
 #                           #   off            — no sync (default)
 #                           #   artifacts-only — sync plans/designs/retros/learnings only
 #                           #                    (skip behavioral data: question-log,
@@ -69,7 +69,7 @@ CONFIG_HEADER='# gstack configuration — edit freely, changes take effect on ne
 #                           #   full           — sync everything allowlisted
 #                           # Set by the first-run privacy stop-gate. See docs/gbrain-sync.md.
 #
-# gbrain_sync_mode_prompted: false
+# artifacts_sync_mode_prompted: false
 #                           # Set to true once the privacy gate has asked the user.
 #                           # Flip back to false to be re-prompted.
 #
@@ -105,8 +105,8 @@ lookup_default() {
    skip_eng_review) echo "false" ;;
    workspace_root) echo "$HOME/conductor/workspaces" ;;
    cross_project_learnings) echo "" ;; # intentionally empty → unset triggers first-time prompt
-    gbrain_sync_mode) echo "off" ;;
-    gbrain_sync_mode_prompted) echo "false" ;;
+    artifacts_sync_mode) echo "off" ;;
+    artifacts_sync_mode_prompted) echo "false" ;;
    *) echo "" ;;
  esac
 }
@@ -138,8 +138,8 @@ case "${1:-}" in
      echo "Warning: explain_level '$VALUE' not recognized. Valid values: default, terse. Using default." >&2
      VALUE="default"
    fi
-    if [ "$KEY" = "gbrain_sync_mode" ] && [ "$VALUE" != "off" ] && [ "$VALUE" != "artifacts-only" ] && [ "$VALUE" != "full" ]; then
-      echo "Warning: gbrain_sync_mode '$VALUE' not recognized. Valid values: off, artifacts-only, full. Using off." >&2
+    if [ "$KEY" = "artifacts_sync_mode" ] && [ "$VALUE" != "off" ] && [ "$VALUE" != "artifacts-only" ] && [ "$VALUE" != "full" ]; then
+      echo "Warning: artifacts_sync_mode '$VALUE' not recognized. Valid values: off, artifacts-only, full. Using off." >&2
      VALUE="off"
    fi
    mkdir -p "$STATE_DIR"
@@ -171,7 +171,7 @@ case "${1:-}" in
    for KEY in proactive routing_declined telemetry auto_upgrade update_check \
               skill_prefix checkpoint_mode checkpoint_push codex_reviews \
               gstack_contributor skip_eng_review workspace_root \
-               gbrain_sync_mode gbrain_sync_mode_prompted; do
+               artifacts_sync_mode artifacts_sync_mode_prompted; do
      VALUE=$(grep -E "^${KEY}:" "$CONFIG_FILE" 2>/dev/null | tail -1 | awk '{print $2}' | tr -d '[:space:]' || true)
      SOURCE="default"
      if [ -n "$VALUE" ]; then
@@ -187,7 +187,7 @@ case "${1:-}" in
    for KEY in proactive routing_declined telemetry auto_upgrade update_check \
               skill_prefix checkpoint_mode checkpoint_push codex_reviews \
               gstack_contributor skip_eng_review workspace_root \
-               gbrain_sync_mode gbrain_sync_mode_prompted; do
+               artifacts_sync_mode artifacts_sync_mode_prompted; do
      printf '  %-24s %s\n' "$KEY:" "$(lookup_default "$KEY")"
    done
    ;;
--- a/bin/gstack-gbrain-detect
+++ b/bin/gstack-gbrain-detect
@@ -80,10 +80,10 @@ if [ "$gbrain_on_path" = "true" ]; then
  fi
 fi

-# --- gstack-brain-sync state (memory sync, separate from gbrain itself) ---
+# --- artifacts sync state (renamed from gbrain_sync_mode in v1.27.0.0) ---
 gstack_brain_sync_mode="off"
 if [ -x "$CONFIG_BIN" ]; then
-  mode=$("$CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || true)
+  mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || true)
  case "$mode" in
    off|artifacts-only|full) gstack_brain_sync_mode="$mode" ;;
  esac
--- a/bin/gstack-gbrain-source-wireup
+++ b/bin/gstack-gbrain-source-wireup
@@ -44,7 +44,12 @@ CONFIG_BIN="$SCRIPT_DIR/gstack-config"

 GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
 WORKTREE="${GSTACK_BRAIN_WORKTREE:-$HOME/.gstack-brain-worktree}"
-REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+# v1.27.0.0+ canonical name; brain-remote is the legacy fallback during migration.
+if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
+  REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
+else
+  REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+fi
 PLIST_PATH="$HOME/Library/LaunchAgents/com.gstack.brain-sync.plist"
 GBRAIN_CONFIG="$HOME/.gbrain/config.json"

--- a/bin/gstack-timeline-log
+++ b/bin/gstack-timeline-log
@@ -2,7 +2,7 @@
 # gstack-timeline-log — append a timeline event to the project timeline
 # Usage: gstack-timeline-log '{"skill":"review","event":"started","branch":"main"}'
 #
-# Session timeline: local by default. If the user enables `gbrain_sync_mode`
+# Session timeline: local by default. If the user enables `artifacts_sync_mode`
 # with the `full` (not `artifacts-only`) privacy tier — via the first-run
 # stop-gate from `gstack-brain-init` or the preamble — timeline events are
 # published to the user's private GBrain sync repo. See docs/gbrain-sync.md.
--- a/health/SKILL.md.tmpl
+++ b/health/SKILL.md.tmpl
@@ -169,9 +169,9 @@ doctor_component: 10 if `gbrain doctor --json | jq -r .status` == "ok";
                   7 if "warnings"; 0 otherwise (or command times out after 5s).
 queue_component:   10 if ~/.gstack/.brain-queue.jsonl has <10 lines;
                    7 if 10-100; 0 if >=100 (suggests secret-scan rejections
-                    piling up). N/A if gbrain_sync_mode == off.
+                    piling up). N/A if artifacts_sync_mode == off.
 push_component:    10 if (now - mtime of ~/.gstack/.brain-last-push) < 24h;
-                    7 if <72h; 0 if >=72h. N/A if gbrain_sync_mode == off.
+                    7 if <72h; 0 if >=72h. N/A if artifacts_sync_mode == off.
 gbrain_score     = 0.5 * doctor_component + 0.3 * queue_component + 0.2 * push_component
                   (redistribute 0.3 + 0.2 into doctor when sync_mode is off:
                   gbrain_score = doctor_component in that case)
--- a/scripts/resolvers/preamble/generate-brain-sync-block.ts
+++ b/scripts/resolvers/preamble/generate-brain-sync-block.ts
@@ -1,19 +1,24 @@
 /**
- * gbrain-sync preamble block.
+ * artifacts-sync preamble block (renamed from gbrain-sync in v1.27.0.0).
 *
 * Emits bash that runs at every skill invocation:
 *   0. Live gbrain-availability hint (per /plan-eng-review): when gbrain is
 *      configured, emit one of two variants (steady-state vs empty-corpus
 *      emergency). Zero context cost when gbrain is not configured.
- *   1. If ~/.gstack-brain-remote.txt exists AND ~/.gstack/.git is missing,
- *      surface a restore-available hint (does NOT auto-run restore).
- *   2. If sync is on, run `gstack-brain-sync --once` (drain + push).
+ *   1. If ~/.gstack-artifacts-remote.txt (or legacy ~/.gstack-brain-remote.txt
+ *      during the v1.27.0.0 migration window) exists AND ~/.gstack/.git is
+ *      missing, surface a restore-available hint (does NOT auto-run restore).
+ *   2. If sync is on, run `gstack-brain-sync --once` (drain + push). The
+ *      script keeps its old name; only the config-key + state-file names flip.
 *   3. On first skill of the day (24h cache via .brain-last-pull):
 *      `git fetch` + ff-only merge (JSONL merge driver handles conflicts).
- *   4. Emit a `BRAIN_SYNC:` status line so every skill surfaces health.
+ *   4. Emit an `ARTIFACTS_SYNC:` status line so every skill surfaces health.
+ *      In remote-MCP mode, the line reads `ARTIFACTS_SYNC: remote-mode
+ *      (managed by brain server <host>)` since this machine doesn't sync
+ *      anything locally — the brain admin's server pulls from GitHub/GitLab.
 *
 * Also emits prose instructions for the host LLM to fire a one-time privacy
- * stop-gate via AskUserQuestion when gbrain_sync_mode is unset and gbrain
+ * stop-gate via AskUserQuestion when artifacts_sync_mode is unset and gbrain
 * is available on the host.
 *
 * Block emitted across all tiers. Internal bash short-circuits when feature
@@ -26,11 +31,17 @@ import type { TemplateContext } from '../types';

 export function generateBrainSyncBlock(ctx: TemplateContext): string {
  const isBrainHost = ctx.host === 'gbrain' || ctx.host === 'hermes';
-  return `## GBrain Sync (skill start)
+  return `## Artifacts Sync (skill start)

 \`\`\`bash
 _GSTACK_HOME="\${GSTACK_HOME:-$HOME/.gstack}"
-_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
+# upgrading mid-stream before the migration script runs.
+if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
+  _BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
+else
+  _BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+fi
 _BRAIN_SYNC_BIN="${ctx.paths.binDir}/gstack-brain-sync"
 _BRAIN_CONFIG_BIN="${ctx.paths.binDir}/gstack-config"

@@ -63,13 +74,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
  fi
 fi

-_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
+_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
+
+# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
+# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
+# own cadence. Read claude.json directly to keep this preamble fast (no
+# subprocess to claude CLI on every skill start).
+_GBRAIN_MCP_MODE="none"
+if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
+  _GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
+  case "$_GBRAIN_MCP_TYPE" in
+    url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
+    stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
+  esac
+fi

 if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
  _BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
  if [ -n "$_BRAIN_NEW_URL" ]; then
-    echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
-    echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
+    echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
+    echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
  fi
 fi

@@ -89,22 +113,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
  "$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
 fi

-if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
+if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
+  # Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
+  # pulls from GitHub/GitLab). Show the user this is by design, not broken.
+  _GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\\1|')
+  echo "ARTIFACTS_SYNC: remote-mode (managed by brain server \${_GBRAIN_HOST:-remote})"
+elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
  _BRAIN_QUEUE_DEPTH=0
  [ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
  _BRAIN_LAST_PUSH="never"
  [ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
-  echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
+  echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
 else
-  echo "BRAIN_SYNC: off"
+  echo "ARTIFACTS_SYNC: off"
 fi
 \`\`\`

-${isBrainHost ? `If output shows \`BRAIN_SYNC: brain repo detected\`, offer \`gstack-brain-restore\` via AskUserQuestion; otherwise continue.` : ''}
+${isBrainHost ? `If output shows \`ARTIFACTS_SYNC: artifacts repo detected\`, offer \`gstack-brain-restore\` via AskUserQuestion; otherwise continue.` : ''}

-Privacy stop-gate: if output shows \`BRAIN_SYNC: off\`, \`gbrain_sync_mode_prompted\` is \`false\`, and gbrain is on PATH or \`gbrain doctor --fast --json\` works, ask once:
+Privacy stop-gate: if output shows \`ARTIFACTS_SYNC: off\`, \`artifacts_sync_mode_prompted\` is \`false\`, and gbrain is on PATH or \`gbrain doctor --fast --json\` works, ask once:

-> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
+> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?

 Options:
 - A) Everything allowlisted (recommended)
@@ -115,11 +144,11 @@ After answer:

 \`\`\`bash
 # Chosen mode: full | artifacts-only | off
-"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
-"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
+"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
+"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
 \`\`\`

-If A/B and \`~/.gstack/.git\` is missing, ask whether to run \`gstack-brain-init\`. Do not block the skill.
+If A/B and \`~/.gstack/.git\` is missing, ask whether to run \`gstack-artifacts-init\`. Do not block the skill.

 At skill END before telemetry:

--- a/sync-gbrain/SKILL.md.tmpl
+++ b/sync-gbrain/SKILL.md.tmpl
@@ -226,7 +226,7 @@ gbrain status: GREEN
  Capability ...... OK   write+search round-trip
  CWD source ...... OK   <gstack-code-{repo_slug}> (page_count=<N>)
  ~/.gstack source. OK   <gstack-brain-{user}> (page_count=<N>) — managed by /setup-gbrain
-  Memory sync ..... OK   <gbrain_sync_mode>
+  Memory sync ..... OK   <artifacts_sync_mode>
  CLAUDE.md ....... OK   ## GBrain Search Guidance present
  Last sync ....... OK   <last_sync from state file>

--- a/test/brain-sync.test.ts
+++ b/test/brain-sync.test.ts
@@ -6,7 +6,7 @@
 *   - bin/gstack-brain-enqueue (atomicity, skip list, no-op gates)
 *   - bin/gstack-jsonl-merge (3-way, ts-sort, hash-fallback)
 *   - bin/gstack-brain-sync --once (drain, commit, push, secret-scan, skip-file)
- *   - bin/gstack-brain-init + --restore round-trip
+ *   - bin/gstack-artifacts-init + --restore round-trip
 *   - bin/gstack-brain-uninstall preserves user data
 *   - env isolation (GSTACK_HOME never bleeds into real ~/.gstack/config.yaml)
 *
@@ -69,30 +69,30 @@ afterEach(() => {
 // Config key validation + env isolation
 // ---------------------------------------------------------------
 describe('gstack-config gbrain keys', () => {
-  test('default gbrain_sync_mode is off', () => {
-    const r = run(['gstack-config', 'get', 'gbrain_sync_mode']);
+  test('default artifacts_sync_mode is off', () => {
+    const r = run(['gstack-config', 'get', 'artifacts_sync_mode']);
    expect(r.status).toBe(0);
    expect(r.stdout.trim()).toBe('off');
  });

-  test('default gbrain_sync_mode_prompted is false', () => {
-    const r = run(['gstack-config', 'get', 'gbrain_sync_mode_prompted']);
+  test('default artifacts_sync_mode_prompted is false', () => {
+    const r = run(['gstack-config', 'get', 'artifacts_sync_mode_prompted']);
    expect(r.stdout.trim()).toBe('false');
  });

  test('accepts full / artifacts-only / off', () => {
    for (const val of ['full', 'artifacts-only', 'off']) {
-      const set = run(['gstack-config', 'set', 'gbrain_sync_mode', val]);
+      const set = run(['gstack-config', 'set', 'artifacts_sync_mode', val]);
      expect(set.status).toBe(0);
-      const get = run(['gstack-config', 'get', 'gbrain_sync_mode']);
+      const get = run(['gstack-config', 'get', 'artifacts_sync_mode']);
      expect(get.stdout.trim()).toBe(val);
    }
  });

-  test('invalid gbrain_sync_mode value warns + defaults', () => {
-    const r = run(['gstack-config', 'set', 'gbrain_sync_mode', 'bogus']);
+  test('invalid artifacts_sync_mode value warns + defaults', () => {
+    const r = run(['gstack-config', 'set', 'artifacts_sync_mode', 'bogus']);
    expect(r.stderr).toContain('not recognized');
-    const get = run(['gstack-config', 'get', 'gbrain_sync_mode']);
+    const get = run(['gstack-config', 'get', 'artifacts_sync_mode']);
    expect(get.stdout.trim()).toBe('off');
  });

@@ -102,11 +102,11 @@ describe('gstack-config gbrain keys', () => {
    const realConfig = path.join(os.homedir(), '.gstack', 'config.yaml');
    const before = fs.existsSync(realConfig) ? fs.readFileSync(realConfig, 'utf-8') : null;

-    run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
+    run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);

    // The override actually took effect — temp config got the new value.
    const tempConfig = fs.readFileSync(path.join(tmpHome, 'config.yaml'), 'utf-8');
-    expect(tempConfig).toContain('gbrain_sync_mode: full');
+    expect(tempConfig).toContain('artifacts_sync_mode: full');

    // Real ~/.gstack/config.yaml must not be touched.
    const after = fs.existsSync(realConfig) ? fs.readFileSync(realConfig, 'utf-8') : null;
@@ -133,7 +133,7 @@ describe('gstack-brain-enqueue', () => {

  test('enqueues when mode is full and .git exists', () => {
    fs.mkdirSync(path.join(tmpHome, '.git'), { recursive: true });
-    run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
+    run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
    run(['gstack-brain-enqueue', 'projects/foo/learnings.jsonl']);
    const queue = fs.readFileSync(path.join(tmpHome, '.brain-queue.jsonl'), 'utf-8');
    expect(queue).toContain('projects/foo/learnings.jsonl');
@@ -144,7 +144,7 @@ describe('gstack-brain-enqueue', () => {

  test('skip list honored', () => {
    fs.mkdirSync(path.join(tmpHome, '.git'), { recursive: true });
-    run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
+    run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
    fs.writeFileSync(path.join(tmpHome, '.brain-skip.txt'), 'projects/foo/secret.jsonl\n');
    run(['gstack-brain-enqueue', 'projects/foo/secret.jsonl']);
    run(['gstack-brain-enqueue', 'projects/foo/ok.jsonl']);
@@ -155,7 +155,7 @@ describe('gstack-brain-enqueue', () => {

  test('concurrent enqueues all land (atomic append)', async () => {
    fs.mkdirSync(path.join(tmpHome, '.git'), { recursive: true });
-    run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
+    run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
    const procs = [];
    for (let i = 0; i < 10; i++) {
      procs.push(new Promise<void>((resolve) => {
@@ -218,7 +218,7 @@ describe('gstack-jsonl-merge', () => {
 // ---------------------------------------------------------------
 describe('init + sync + restore round-trip', () => {
  test('init creates canonical files + registers drivers', () => {
-    const r = run(['gstack-brain-init', '--remote', bareRemote]);
+    const r = run(['gstack-artifacts-init', '--remote', bareRemote]);
    expect(r.status).toBe(0);
    expect(fs.existsSync(path.join(tmpHome, '.git'))).toBe(true);
    expect(fs.existsSync(path.join(tmpHome, '.gitignore'))).toBe(true);
@@ -232,18 +232,18 @@ describe('init + sync + restore round-trip', () => {
  });

  test('refuses init on different remote', () => {
-    run(['gstack-brain-init', '--remote', bareRemote]);
+    run(['gstack-artifacts-init', '--remote', bareRemote]);
    const otherRemote = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-other-'));
    spawnSync('git', ['init', '--bare', '-q', '-b', 'main', otherRemote]);
-    const r = run(['gstack-brain-init', '--remote', otherRemote]);
+    const r = run(['gstack-artifacts-init', '--remote', otherRemote]);
    expect(r.status).not.toBe(0);
    expect(r.stderr).toContain('already a git repo pointing at');
    fs.rmSync(otherRemote, { recursive: true, force: true });
  });

  test('full sync: init → enqueue → --once → commit pushed', () => {
-    run(['gstack-brain-init', '--remote', bareRemote]);
-    run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
+    run(['gstack-artifacts-init', '--remote', bareRemote]);
+    run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
    fs.mkdirSync(path.join(tmpHome, 'projects', 'p'), { recursive: true });
    fs.writeFileSync(path.join(tmpHome, 'projects/p/learnings.jsonl'),
      '{"skill":"x","insight":"y","ts":"2026-04-22T10:00:00Z"}\n');
@@ -257,8 +257,8 @@ describe('init + sync + restore round-trip', () => {

  test('restore round-trip: writes on machine A visible on machine B', () => {
    // Machine A.
-    run(['gstack-brain-init', '--remote', bareRemote]);
-    run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
+    run(['gstack-artifacts-init', '--remote', bareRemote]);
+    run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
    fs.mkdirSync(path.join(tmpHome, 'projects', 'myproj'), { recursive: true });
    const aLearning = '{"skill":"x","insight":"machine A wisdom","ts":"2026-04-22T10:00:00Z"}\n';
    fs.writeFileSync(path.join(tmpHome, 'projects/myproj/learnings.jsonl'), aLearning);
@@ -296,8 +296,8 @@ describe('gstack-brain-sync secret scan', () => {

  for (const [name, content] of SECRETS) {
    test(`blocks ${name}`, () => {
-      run(['gstack-brain-init', '--remote', bareRemote]);
-      run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
+      run(['gstack-artifacts-init', '--remote', bareRemote]);
+      run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
      fs.mkdirSync(path.join(tmpHome, 'projects', 'p'), { recursive: true });
      fs.writeFileSync(path.join(tmpHome, 'projects/p/learnings.jsonl'),
        `{"leaked":"${content}"}\n`);
@@ -314,8 +314,8 @@ describe('gstack-brain-sync secret scan', () => {
  }

  test('--skip-file unblocks specific file', () => {
-    run(['gstack-brain-init', '--remote', bareRemote]);
-    run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
+    run(['gstack-artifacts-init', '--remote', bareRemote]);
+    run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
    fs.mkdirSync(path.join(tmpHome, 'projects', 'p'), { recursive: true });
    const leakPath = 'projects/p/leaked.jsonl';
    fs.writeFileSync(path.join(tmpHome, leakPath),
@@ -335,7 +335,7 @@ describe('gstack-brain-sync secret scan', () => {
 // ---------------------------------------------------------------
 describe('gstack-brain-uninstall', () => {
  test('removes sync config but preserves learnings/project data', () => {
-    run(['gstack-brain-init', '--remote', bareRemote]);
+    run(['gstack-artifacts-init', '--remote', bareRemote]);
    fs.mkdirSync(path.join(tmpHome, 'projects', 'user-data'), { recursive: true });
    const preservedContent = '{"keep":"me","ts":"2026-04-22T12:00:00Z"}\n';
    fs.writeFileSync(path.join(tmpHome, 'projects/user-data/learnings.jsonl'), preservedContent);
@@ -349,7 +349,7 @@ describe('gstack-brain-uninstall', () => {
    const preserved = fs.readFileSync(path.join(tmpHome, 'projects/user-data/learnings.jsonl'), 'utf-8');
    expect(preserved).toBe(preservedContent);
    // Config key reset.
-    const mode = run(['gstack-config', 'get', 'gbrain_sync_mode']);
+    const mode = run(['gstack-config', 'get', 'artifacts_sync_mode']);
    expect(mode.stdout.trim()).toBe('off');
  });
 });
@@ -359,8 +359,8 @@ describe('gstack-brain-uninstall', () => {
 // ---------------------------------------------------------------
 describe('gstack-brain-sync --discover-new', () => {
  test('enqueues new allowlisted files; idempotent on re-run', () => {
-    run(['gstack-brain-init', '--remote', bareRemote]);
-    run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
+    run(['gstack-artifacts-init', '--remote', bareRemote]);
+    run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
    fs.mkdirSync(path.join(tmpHome, 'retros'), { recursive: true });
    fs.writeFileSync(path.join(tmpHome, 'retros/week-1.md'), '# retro\n');
    run(['gstack-brain-sync', '--discover-new']);
--- a/test/gen-skill-docs.test.ts
+++ b/test/gen-skill-docs.test.ts
@@ -313,15 +313,17 @@ describe('gen-skill-docs', () => {
    ];

    // Plan skills carry the same preamble surface as other tier-≥2 skills
-    // (Brain Sync, Context Recovery, Routing Injection are load-bearing
+    // (Artifacts Sync, Context Recovery, Routing Injection are load-bearing
    // functionality, not optional). Budget is set to current size + small
    // headroom; ratchet down if a future slim trims real bytes.
    // Ratcheted from 33000 → 35000 when the gbrain context-load block was
-    // added to generate-brain-sync-block.ts (per /sync-gbrain plan §4).
+    // added (per /sync-gbrain plan §4). Ratcheted 35000 → 36500 in v1.27.0.0
+    // when generate-brain-sync-block.ts gained the gbrain_mcp_mode probe +
+    // remote-mode ARTIFACTS_SYNC status line (Path 4 of /setup-gbrain).
    for (const skill of reviewSkills) {
      const content = fs.readFileSync(skill.path, 'utf-8');
      const preamble = extractPreambleBeforeWorkflow(content, skill.markers);
-      expect(Buffer.byteLength(preamble, 'utf-8')).toBeLessThan(35_000);
+      expect(Buffer.byteLength(preamble, 'utf-8')).toBeLessThan(36_500);
    }
  });

--- a/test/gstack-brain-init-gh-mock.test.ts
+++ b/test/gstack-brain-init-gh-mock.test.ts
@@ -1,236 +0,0 @@
-/**
- * gstack-brain-init — mocked-gh integration tests.
- *
- * The regular brain-sync tests pass `--remote <bare-git-url>` to skip the
- * gh-repo-creation path entirely. That left the happy path (user just
- * presses Enter, gstack-brain-init calls `gh repo create --private`)
- * with zero coverage — you'd only know it broke when a real user tried
- * it with a real GitHub account.
- *
- * These tests put a fake `gh` binary on PATH that records every call
- * into a file, then run gstack-brain-init in its non-flag interactive
- * mode and assert the fake `gh` was invoked with the expected arguments.
- *
- * No real GitHub account, no live API, deterministic per-run.
- */
-
-import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import { spawnSync } from 'child_process';
-
-const ROOT = path.resolve(import.meta.dir, '..');
-const BIN_DIR = path.join(ROOT, 'bin');
-const INIT_BIN = path.join(BIN_DIR, 'gstack-brain-init');
-
-let tmpHome: string;
-let bareRemote: string;
-let fakeBinDir: string;
-let ghCallLog: string;
-
-function makeFakeGh(opts: {
-  authStatus?: 'ok' | 'fail';
-  repoCreate?: 'success' | 'already-exists' | 'fail';
-  sshUrl?: string;
-}) {
-  const authStatus = opts.authStatus ?? 'ok';
-  const repoCreate = opts.repoCreate ?? 'success';
-  const sshUrl = opts.sshUrl ?? bareRemote;
-  const script = `#!/bin/bash
-echo "gh $@" >> "${ghCallLog}"
-case "$1" in
-  auth)
-    ${authStatus === 'ok' ? 'exit 0' : 'exit 1'}
-    ;;
-  repo)
-    shift
-    case "$1" in
-      create)
-        ${
-          repoCreate === 'success'
-            ? 'exit 0'
-            : repoCreate === 'already-exists'
-            ? 'echo "GraphQL: Name already exists on this account" >&2; exit 1'
-            : 'echo "network error" >&2; exit 1'
-        }
-        ;;
-      view)
-        # Emulate \`gh repo view <name> --json sshUrl -q .sshUrl\`
-        echo "${sshUrl}"
-        exit 0
-        ;;
-    esac
-    ;;
-esac
-exit 0
-`;
-  const ghPath = path.join(fakeBinDir, 'gh');
-  fs.writeFileSync(ghPath, script, { mode: 0o755 });
-  return ghPath;
-}
-
-function run(
-  argv: string[],
-  opts: { env?: Record<string, string>; input?: string } = {}
-) {
-  const env = {
-    // Put the fake bin dir FIRST on PATH so our mock gh wins.
-    PATH: `${fakeBinDir}:/usr/bin:/bin:/opt/homebrew/bin`,
-    GSTACK_HOME: tmpHome,
-    USER: 'testuser',
-    HOME: tmpHome,
-    ...(opts.env || {}),
-  };
-  const res = spawnSync(INIT_BIN, argv, {
-    env,
-    encoding: 'utf-8',
-    input: opts.input,
-    cwd: ROOT,
-  });
-  return {
-    stdout: res.stdout || '',
-    stderr: res.stderr || '',
-    status: res.status ?? -1,
-  };
-}
-
-function readGhCalls(): string[] {
-  if (!fs.existsSync(ghCallLog)) return [];
-  return fs.readFileSync(ghCallLog, 'utf-8').trim().split('\n').filter(Boolean);
-}
-
-beforeEach(() => {
-  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-init-gh-mock-'));
-  bareRemote = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-init-bare-'));
-  fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-init-fake-bin-'));
-  ghCallLog = path.join(fakeBinDir, 'gh-calls.log');
-  spawnSync('git', ['init', '--bare', '-q', '-b', 'main', bareRemote]);
-});
-
-afterEach(() => {
-  fs.rmSync(tmpHome, { recursive: true, force: true });
-  fs.rmSync(bareRemote, { recursive: true, force: true });
-  fs.rmSync(fakeBinDir, { recursive: true, force: true });
-  const remoteFile = path.join(os.homedir(), '.gstack-brain-remote.txt');
-  if (fs.existsSync(remoteFile)) {
-    const contents = fs.readFileSync(remoteFile, 'utf-8');
-    if (contents.includes(bareRemote)) fs.unlinkSync(remoteFile);
-  }
-});
-
-describe('gstack-brain-init uses gh CLI when present + authed', () => {
-  test('calls gh repo create --private with the computed default name', () => {
-    makeFakeGh({ authStatus: 'ok', repoCreate: 'success' });
-    // Interactive mode; pressing Enter accepts the gh default.
-    const r = run([], { input: '\n' });
-    expect(r.status).toBe(0);
-    const calls = readGhCalls();
-    // First call: auth status check
-    expect(calls.some((c) => c.startsWith('gh auth'))).toBe(true);
-    // The create call
-    const createCall = calls.find((c) => c.startsWith('gh repo create'));
-    expect(createCall).toBeDefined();
-    expect(createCall).toContain('gstack-brain-testuser');
-    expect(createCall).toContain('--private');
-    expect(createCall).toContain('--description');
-    // --source is intentionally omitted: gh requires the source dir to already
-    // be a git repo, but brain-init doesn't `git init $GSTACK_HOME` until later.
-    // Creating bare and wiring up the remote explicitly avoids that ordering bug.
-    expect(createCall).not.toContain('--source');
-  });
-
-  test('falls back to gh repo view when create reports already-exists', () => {
-    makeFakeGh({ authStatus: 'ok', repoCreate: 'already-exists' });
-    const r = run([], { input: '\n' });
-    expect(r.status).toBe(0);
-    const calls = readGhCalls();
-    // create was attempted
-    expect(calls.some((c) => c.startsWith('gh repo create'))).toBe(true);
-    // then view was called to recover the URL
-    expect(calls.some((c) => c.startsWith('gh repo view') && c.includes('gstack-brain-testuser'))).toBe(true);
-    // The view output (bareRemote URL) should have been wired up as origin.
-    const remote = spawnSync('git', ['-C', tmpHome, 'remote', 'get-url', 'origin'], {
-      encoding: 'utf-8',
-    });
-    expect(remote.stdout.trim()).toBe(bareRemote);
-  });
-
-  test('user-provided URL bypasses gh create entirely', () => {
-    makeFakeGh({ authStatus: 'ok', repoCreate: 'fail' });
-    const r = run([], { input: `${bareRemote}\n` });
-    expect(r.status).toBe(0);
-    const calls = readGhCalls();
-    // gh auth was still checked
-    expect(calls.some((c) => c.startsWith('gh auth'))).toBe(true);
-    // but create was NOT called (user bypassed the default)
-    expect(calls.some((c) => c.startsWith('gh repo create'))).toBe(false);
-  });
-});
-
-describe('gstack-brain-init without gh CLI', () => {
-  test('prompts for URL when gh is not on PATH', () => {
-    // Don't install fake gh — PATH will not have it.
-    // Use a bare-minimum PATH so nothing else shadows.
-    const stripped = `${fakeBinDir}:/usr/bin:/bin`;
-    const res = spawnSync(INIT_BIN, [], {
-      env: {
-        PATH: stripped,
-        GSTACK_HOME: tmpHome,
-        USER: 'testuser',
-        HOME: tmpHome,
-      },
-      encoding: 'utf-8',
-      input: `${bareRemote}\n`,
-      cwd: ROOT,
-    });
-    expect(res.status).toBe(0);
-    expect(res.stdout).toContain('gh CLI not found');
-    // Remote got set from the stdin paste
-    const remote = spawnSync('git', ['-C', tmpHome, 'remote', 'get-url', 'origin'], {
-      encoding: 'utf-8',
-    });
-    expect(remote.stdout.trim()).toBe(bareRemote);
-  });
-
-  test('prompts for URL when gh is present but not authed', () => {
-    makeFakeGh({ authStatus: 'fail' });
-    const r = run([], { input: `${bareRemote}\n` });
-    expect(r.status).toBe(0);
-    expect(r.stdout).toContain('gh CLI not found or not authenticated');
-    const calls = readGhCalls();
-    // Only `gh auth status` was called; no create attempt.
-    expect(calls.some((c) => c.startsWith('gh auth'))).toBe(true);
-    expect(calls.some((c) => c.startsWith('gh repo create'))).toBe(false);
-  });
-});
-
-describe('idempotency via flag', () => {
-  test('--remote <url> skips all gh calls', () => {
-    makeFakeGh({ authStatus: 'ok', repoCreate: 'success' });
-    const r = run(['--remote', bareRemote]);
-    expect(r.status).toBe(0);
-    const calls = readGhCalls();
-    // Zero calls to gh — the --remote flag short-circuits the interactive path.
-    expect(calls.length).toBe(0);
-  });
-
-  test('re-run with matching --remote is safe (no conflicting-remote error)', () => {
-    run(['--remote', bareRemote]);
-    const r2 = run(['--remote', bareRemote]);
-    expect(r2.status).toBe(0);
-  });
-
-  test('re-run with DIFFERENT --remote exits 1 with a conflict message', () => {
-    run(['--remote', bareRemote]);
-    const otherRemote = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-init-other-'));
-    spawnSync('git', ['init', '--bare', '-q', '-b', 'main', otherRemote]);
-    try {
-      const r2 = run(['--remote', otherRemote]);
-      expect(r2.status).not.toBe(0);
-      expect(r2.stderr).toContain('already a git repo');
-    } finally {
-      fs.rmSync(otherRemote, { recursive: true, force: true });
-    }
-  });
-});
--- a/test/skill-e2e-brain-privacy-gate.test.ts
+++ b/test/skill-e2e-brain-privacy-gate.test.ts
@@ -4,7 +4,7 @@
 * The gbrain-sync preamble block instructs the model to fire a one-time
 * AskUserQuestion when:
 *   - `BRAIN_SYNC: off` in the preamble echo (sync mode not on)
- *   - config `gbrain_sync_mode_prompted` is "false"
+ *   - config `artifacts_sync_mode_prompted` is "false"
 *   - gbrain is detected on the host (binary on PATH or `gbrain doctor`
 *     --fast --json succeeds)
 *
@@ -31,14 +31,14 @@ const describeE2E = shouldRun ? describe : describe.skip;

 describeE2E('gbrain-sync privacy gate fires once via preamble', () => {
  test('gstack skill preamble fires the 3-option AskUserQuestion when gbrain is detected', async () => {
-    // Stage a fresh GSTACK_HOME with gbrain_sync_mode_prompted=false.
+    // Stage a fresh GSTACK_HOME with artifacts_sync_mode_prompted=false.
    const gstackHome = fs.mkdtempSync(path.join(os.tmpdir(), 'privacy-gate-gstack-'));
    const fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'privacy-gate-bin-'));

    // Seed the config so the gate's condition passes.
    fs.writeFileSync(
      path.join(gstackHome, 'config.yaml'),
-      'gbrain_sync_mode: off\ngbrain_sync_mode_prompted: false\n',
+      'artifacts_sync_mode: off\nartifacts_sync_mode_prompted: false\n',
      { mode: 0o600 }
    );

@@ -151,14 +151,14 @@ describeE2E('gbrain-sync privacy gate fires once via preamble', () => {
    }
  }, 180_000);

-  test('privacy gate does NOT fire when gbrain_sync_mode_prompted is already true', async () => {
+  test('privacy gate does NOT fire when artifacts_sync_mode_prompted is already true', async () => {
    // Same staging, but prompted=true this time. Gate should be silent.
    const gstackHome = fs.mkdtempSync(path.join(os.tmpdir(), 'privacy-gate-off-'));
    const fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'privacy-gate-off-bin-'));

    fs.writeFileSync(
      path.join(gstackHome, 'config.yaml'),
-      'gbrain_sync_mode: off\ngbrain_sync_mode_prompted: true\n',
+      'artifacts_sync_mode: off\nartifacts_sync_mode_prompted: true\n',
      { mode: 0o600 }
    );