v1.27.0.0 feat: /setup-gbrain Path 4 (remote MCP) + brain → artifacts rename (#1351)

* feat: gstack-gbrain-mcp-verify helper for remote MCP probe

Probes a remote gbrain MCP endpoint with bearer auth. POSTs initialize,
classifies failures into NETWORK / AUTH / MALFORMED with one-line
remediation hints, and runs a tools/list capability probe to detect
sources_add MCP support (forward-compat for when gbrain ships URL ingest).

Token consumed from GBRAIN_MCP_TOKEN env, never argv. Required to set
both 'application/json' AND 'text/event-stream' in Accept; that gotcha
costs 10 minutes of debugging when missed (regression-tested).

Live-verified against wintermute (gbrain v0.27.1).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: gstack-artifacts-init + gstack-artifacts-url helpers

artifacts-init replaces brain-init with provider choice (gh / glab /
manual), per-user gstack-artifacts-$USER repo, HTTPS-canonical storage in
~/.gstack-artifacts-remote.txt, and a "send this to your brain admin"
hookup printout. Always prints the command, never auto-executes — gbrain
v0.26.x has no admin-scope MCP probe (codex Finding #3).

artifacts-url centralizes HTTPS↔SSH/host/owner-repo conversion so callers
don't each string-mangle (codex Finding #10). The remote-conflict check in
artifacts-init compares at the canonical level so re-running with HTTPS
input doesn't trip on a stored SSH URL for the same logical repo.

The "URL form not supported" branch prints a two-line clone-then-path
form for gbrain v0.26.x; the supported branch is a one-liner with --url
ready for when gbrain ships URL ingest.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: extend gstack-gbrain-detect with mcp_mode + artifacts_remote

Adds two new fields to detect's JSON output:

- gbrain_mcp_mode: local-stdio | remote-http | none
  Resolved via 3-tier fallback (codex Finding D3): claude mcp get --json
  → claude mcp list text-grep → ~/.claude.json jq read. If Anthropic moves
  the file format, the first two tiers absorb it.

- gstack_artifacts_remote: HTTPS URL from ~/.gstack-artifacts-remote.txt
  Falls back to ~/.gstack-brain-remote.txt during the v1.27.0.0 migration
  window so detect doesn't return empty between upgrade and migration.

Existing detect tests still pass (15/15). New 19 tests cover every fallback
tier independently, plus a schema regression for /sync-gbrain compat.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: setup-gbrain Path 4 (remote MCP) + artifacts rename

Path 4 lets users paste an HTTPS MCP URL + bearer token and registers it
as an HTTP-transport MCP without needing a local gbrain CLI install. The
flow:

- Step 2 gains a fourth option (Remote gbrain MCP)
- Step 4 adds Path 4 sub-flow: collect URL, secret-read bearer, verify
  via gstack-gbrain-mcp-verify (NETWORK / AUTH / MALFORMED classifier)
- Step 5 (local doctor), Step 7.5 (transcript ingest), Step 5a's stdio
  branch all skip on Path 4
- Step 5a adds an HTTP+bearer registration form: claude mcp add
  --transport http --header "Authorization: Bearer ..."
- Step 7 renamed "session memory sync" → "artifacts sync" and now calls
  gstack-artifacts-init (which always prints the brain-admin hookup
  command — no auto-execute, codex Finding #3)
- Step 8 CLAUDE.md block branches: remote-http includes URL + server
  version (never the token); local-stdio keeps engine + config-file
- Step 9 smoke test on Path 4 prints the curl-equivalent for
  post-restart verification (MCP tools aren't visible mid-session)
- Step 10 verdict block has separate templates per mode

Idempotency: re-running with gbrain_mcp_mode=remote-http already in
detect output skips Step 2 entirely and goes to verification.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* 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>

* chore: regenerate SKILL.md files after artifacts-sync rename

Mechanical regen via \`bun run gen:skill-docs --host all\`. All */SKILL.md
files reflect the renamed config key (gbrain_sync_mode →
artifacts_sync_mode), the renamed remote-helper file
(~/.gstack-artifacts-remote.txt with brain fallback), the renamed init
script (gstack-artifacts-init), and the new ARTIFACTS_SYNC: remote-mode
status line that fires when a remote-http MCP is registered.

Golden fixtures (test/fixtures/golden/*-ship-SKILL.md) refreshed to match
the regenerated default-ship output.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: v1.27.0.0 migration — gstack-brain → gstack-artifacts rename

Journaled, interruption-safe migration. Six steps, each writes to
~/.gstack/.migrations/v1.27.0.0.journal on success; re-entry resumes
from the next un-done step. On final success, journal is replaced by
~/.gstack/.migrations/v1.27.0.0.done.

Steps:
1. gh_repo_renamed       gh/glab repo rename gstack-brain-$USER →
                         gstack-artifacts-$USER (idempotent: detects
                         already-renamed and skips)
2. remote_txt_renamed    mv ~/.gstack-brain-remote.txt → artifacts file,
                         rewriting URL path to match the new repo name
3. config_key_renamed    sed -i in ~/.gstack/config.yaml flips
                         gbrain_sync_mode → artifacts_sync_mode
4. claude_md_block       sed flips "- Memory sync:" → "- Artifacts sync:"
                         in cwd CLAUDE.md and ~/.gstack/CLAUDE.md
5. sources_swapped       gbrain sources add NEW (verify) → remove OLD
                         (codex Finding #6: add-before-remove ordering,
                         no downtime window). On remote-MCP mode, prints
                         commands for the brain admin instead of executing.
6. done                  touchfile + delete journal

User opt-out: any "n" or "skip-for-now" answer at the initial prompt
writes a marker file that prevents re-prompting; user can re-invoke
via /setup-gbrain --rerun-migration.

11 unit tests cover: nothing-to-migrate, GitHub happy path, idempotent
re-run, journal-resume mid-flight, remote-MCP print-only path,
add-before-remove ordering verification, add-fail → old source stays
registered, CLAUDE.md field rewrite.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: regression suite + E2E for v1.27.0.0 rename

Three new regression tests guard the rename's blast radius (per codex
Findings #1, #8, #9, #12):

- test/no-stale-gstack-brain-refs.test.ts: greps bin/, scripts/, *.tmpl,
  test/ for forbidden identifiers (gstack-brain-init, gbrain_sync_mode);
  fails CI if any non-allowlisted file references them.
- test/post-rename-doc-regen.test.ts: confirms gen-skill-docs output has
  no stale references in any */SKILL.md (the cross-product blind spot).
- test/setup-gbrain-path4-structure.test.ts: structural lint over the
  Path 4 prose contract — STOP gates after verify failure, never-write-
  token rules, mode-aware CLAUDE.md block, bearer always via env-var.

Two new gate-tier E2E tests (deterministic stub HTTP server, fixed inputs):

- test/skill-e2e-setup-gbrain-remote.test.ts: Path 4 happy path. Stubs
  an HTTP MCP server, drives the skill via Agent SDK with a stubbed
  bearer, asserts claude.json gets the http MCP entry, CLAUDE.md gets
  the remote-http block, the secret token NEVER leaks to CLAUDE.md.
- test/skill-e2e-setup-gbrain-bad-token.test.ts: stub server returns 401;
  asserts the AUTH classifier hint surfaces, no MCP registration occurs,
  CLAUDE.md is unchanged. Regression guard for the "verify failed → STOP"
  rule.

touchfiles.ts: setup-gbrain-remote and setup-gbrain-bad-token added at
gate-tier so CI catches Path 4 regressions on every PR.

Plus a few comment refs flipped: bin/gstack-jsonl-merge, bin/gstack-timeline-log
(legacy gstack-brain-init mentions in headers).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* release: v1.27.0.0 — /setup-gbrain Path 4 + brain → artifacts rename

Bumps VERSION 1.26.4.0 → 1.27.0.0 (MINOR per CLAUDE.md scale-aware bump
guidance: ~1500 line net change including a new path in /setup-gbrain,
two new bin helpers, a journaled migration, 59 new tests, and a config
key rename across the codebase).

CHANGELOG entry covers: Path 4 (Remote MCP) end-to-end, the brain →
artifacts rename, the journaled migration, the verify-helper error
classifier, the artifacts-init multi-host provider choice. Includes
the canonical Garry-voice headline + numbers table + audience close
per the release-summary format.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: demote setup-gbrain Path 4 E2E to periodic-tier

The Agent SDK E2E tests for Path 4 (skill-e2e-setup-gbrain-remote and
skill-e2e-setup-gbrain-bad-token) are inherently non-deterministic —
the model interprets "follow Path 4 only" prompts flexibly and can
skip Step 8 (CLAUDE.md write) or shortcut past the verify helper, which
makes the gate-tier assertions flaky.

The deterministic gate coverage for Path 4 is in
test/setup-gbrain-path4-structure.test.ts: a fast structural lint that
catches AUQ-pacing regressions and prose contract drift in <200ms with
zero token spend. That test is the right tool for catching the failure
mode the gate-tier was meant to guard against.

The Agent SDK E2E tests stay available on-demand for periodic-tier runs
(EVALS=1 EVALS_TIER=periodic bun test test/skill-e2e-setup-gbrain-*.test.ts).
Also tightened the verify-error assertion to the literal field shape
("error_class": "AUTH") instead of a substring match that false-matches
the parent claude session's "needs-auth" MCP discovery markers.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: sync package.json version to 1.27.0.0

VERSION was bumped to 1.27.0.0 in f6ec11eb but package.json was not
updated in the same commit. The gen-skill-docs.test.ts assertion
"package.json version matches VERSION file" caught the drift.

This is the DRIFT_STALE_PKG case the /ship Step 12 idempotency check
is designed for; the fix is the documented sync-only repair (no
re-bump, package.json synced to existing VERSION).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

bin/gstack-artifacts-init

@@ -0,0 +1,389 @@
+#!/usr/bin/env bash
+# gstack-artifacts-init — set up ~/.gstack/ as a git repo synced to a private
+# git host (GitHub or GitLab) so a remote gbrain can ingest your artifacts
+# (CEO plans, designs, /investigate reports) as a federated source.
+#
+# Replaces gstack-brain-init in v1.27.0.0 (per D4 hard-delete; no compat
+# shim). Existing users are migrated by gstack-upgrade/migrations/v1.27.0.0.sh.
+#
+# Usage:
+#   gstack-artifacts-init [--remote <url>] [--host github|gitlab|manual]
+#                         [--url-form-supported true|false]
+#
+# Interactive by default. Pass --remote to skip the host 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.
+#
+# 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. Provider-aware repo create (gh / glab) OR manual URL paste
+#   9. Initial commit + push
+#   10. Write ~/.gstack-artifacts-remote.txt  (HTTPS URL — canonical form)
+#   11. Print "Send this to your brain admin" hookup command
+#
+# Env:
+#   GSTACK_HOME — override ~/.gstack
+#   USER — fallback for repo naming if $USER is unset
+
+set -euo pipefail
+
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+URL_BIN="$SCRIPT_DIR/gstack-artifacts-url"
+REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
+
+REMOTE_URL=""
+HOST_PREF=""
+URL_FORM_SUPPORTED="false"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --remote) REMOTE_URL="$2"; shift 2 ;;
+    --host) HOST_PREF="$2"; shift 2 ;;
+    --url-form-supported) URL_FORM_SUPPORTED="$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" ]; then
+    # Compare at the canonical level. The stored remote is SSH (for git push),
+    # the input is usually HTTPS — same logical repo, different surface form.
+    EXISTING_HTTPS=$("$URL_BIN" --to https "$EXISTING_REMOTE" 2>/dev/null || echo "$EXISTING_REMOTE")
+    INPUT_HTTPS=$("$URL_BIN" --to https "$REMOTE_URL" 2>/dev/null || echo "$REMOTE_URL")
+    if [ "$EXISTING_HTTPS" != "$INPUT_HTTPS" ]; then
+      cat >&2 <<EOF
+gstack-artifacts-init: ~/.gstack/ is already a git repo pointing at:
+  $EXISTING_REMOTE  (canonical: $EXISTING_HTTPS)
+
+You asked to init with:
+  $REMOTE_URL  (canonical: $INPUT_HTTPS)
+
+Refusing to overwrite. To switch remotes, edit manually:
+  git -C ~/.gstack remote set-url origin <url>
+EOF
+      exit 1
+    fi
+  fi
+fi
+
+# ---- detect available providers ----
+gh_ok=false
+glab_ok=false
+if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then gh_ok=true; fi
+if command -v glab >/dev/null 2>&1 && glab auth status >/dev/null 2>&1; then glab_ok=true; fi
+
+# ---- choose remote URL ----
+if [ -z "$REMOTE_URL" ] && [ -n "$EXISTING_REMOTE" ]; then
+  REMOTE_URL="$EXISTING_REMOTE"
+  echo "Using existing remote: $REMOTE_URL"
+fi
+
+REPO_NAME="gstack-artifacts-${USER:-$(whoami)}"
+DESCRIPTION="gstack artifacts (CEO plans, designs, reports) — synced from ~/.gstack/projects/"
+
+# Decide host preference if not pinned by --host.
+if [ -z "$REMOTE_URL" ] && [ -z "$HOST_PREF" ]; then
+  if $gh_ok && $glab_ok; then
+    cat >&2 <<EOF
+
+gstack-artifacts-init: which git host?
+  1) GitHub      (gh CLI authenticated)
+  2) GitLab      (glab CLI authenticated)
+  3) Other / paste a private git URL
+
+EOF
+    printf "Choice [1]: " >&2
+    read -r CH || CH=""
+    case "$CH" in
+      ""|1) HOST_PREF="github" ;;
+      2) HOST_PREF="gitlab" ;;
+      3) HOST_PREF="manual" ;;
+      *) echo "Invalid choice: $CH" >&2; exit 1 ;;
+    esac
+  elif $gh_ok; then
+    HOST_PREF="github"
+    echo "Using GitHub (gh CLI authenticated; glab not available)" >&2
+  elif $glab_ok; then
+    HOST_PREF="gitlab"
+    echo "Using GitLab (glab CLI authenticated; gh not available)" >&2
+  else
+    HOST_PREF="manual"
+    echo "(Neither gh nor glab CLI authenticated — falling through to manual URL)" >&2
+  fi
+fi
+
+# ---- create repo on chosen host ----
+if [ -z "$REMOTE_URL" ]; then
+  case "$HOST_PREF" in
+    github)
+      echo "Creating GitHub repo: $REPO_NAME ..."
+      if ! gh repo create "$REPO_NAME" --private --description "$DESCRIPTION" 2>/dev/null; then
+        # Maybe already exists; try to fetch its URL.
+        REMOTE_URL=$(gh repo view "$REPO_NAME" --json url -q .url 2>/dev/null || echo "")
+        if [ -z "$REMOTE_URL" ]; then
+          echo "Failed to create or find '$REPO_NAME'. Try --remote <url>." >&2
+          exit 1
+        fi
+        echo "Repo already exists; using $REMOTE_URL"
+      else
+        REMOTE_URL=$(gh repo view "$REPO_NAME" --json url -q .url 2>/dev/null || echo "")
+      fi
+      ;;
+    gitlab)
+      echo "Creating GitLab repo: $REPO_NAME ..."
+      if ! glab repo create "$REPO_NAME" --private --description "$DESCRIPTION" 2>/dev/null; then
+        REMOTE_URL=$(glab repo view "$REPO_NAME" -F json 2>/dev/null | jq -r '.web_url // empty' 2>/dev/null || echo "")
+        if [ -z "$REMOTE_URL" ]; then
+          echo "Failed to create or find '$REPO_NAME'. Try --remote <url>." >&2
+          exit 1
+        fi
+        echo "Repo already exists; using $REMOTE_URL"
+      else
+        REMOTE_URL=$(glab repo view "$REPO_NAME" -F json 2>/dev/null | jq -r '.web_url // empty' 2>/dev/null || echo "")
+      fi
+      ;;
+    manual)
+      echo "(provide a private git URL)"
+      printf "Paste an HTTPS git URL (e.g. https://github.com/you/gstack-artifacts.git): " >&2
+      read -r REMOTE_URL || REMOTE_URL=""
+      if [ -z "$REMOTE_URL" ]; then
+        echo "No URL provided. Aborting." >&2
+        exit 1
+      fi
+      ;;
+    *) echo "Unknown --host: $HOST_PREF (expected github|gitlab|manual)" >&2; exit 1 ;;
+  esac
+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
+  CANONICAL_HTTPS="$REMOTE_URL"
+fi
+
+# Use SSH for git push (more reliable for repeated pushes than HTTPS+token).
+# 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"
+if ! git ls-remote "$PUSH_URL" >/dev/null 2>&1; then
+  cat >&2 <<EOF
+Remote not reachable via SSH: $PUSH_URL
+This could mean:
+  - Wrong URL
+  - SSH key not added to your git host (GitHub: gh ssh-key list; GitLab: glab ssh-key list)
+  - Network issue
+Fix and re-run gstack-artifacts-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
+  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 "$PUSH_URL"
+else
+  git -C "$GSTACK_HOME" remote set-url origin "$PUSH_URL"
+fi
+
+# ---- write canonical files (idempotent) ----
+cat > "$GSTACK_HOME/.gitignore" <<'EOF'
+# gstack-artifacts 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-artifacts-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 (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-artifacts: merge drivers for cross-machine sync conflicts.
+*.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-artifacts 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
+# artifacts 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-artifacts 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) ----
+cd "$GSTACK_HOME"
+git add -f .gitignore .brain-allowlist .brain-privacy-map.json .gitattributes
+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-artifacts-init" \
+        commit -q -m "chore: gstack-artifacts-init (refresh sync config)"
+  fi
+else
+  git -c user.email="gstack@localhost" -c user.name="gstack-artifacts-init" \
+      commit -q -m "chore: gstack-artifacts-init"
+fi
+
+# ---- initial push ----
+if ! git push -q -u origin main 2>/dev/null; then
+  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 $PUSH_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
+    echo "Push to $PUSH_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 (HTTPS canonical) ----
+echo "$CANONICAL_HTTPS" > "$REMOTE_FILE"
+chmod 600 "$REMOTE_FILE"
+
+# ---- print brain-admin hookup command (always print, never auto-execute;
+#      codex Finding #3) ----
+SOURCE_ID="gstack-artifacts-${USER:-$(whoami)}"
+cat <<EOF
+
+gstack-artifacts-init complete.
+Repo:    $GSTACK_HOME (git)
+Remote:  $CANONICAL_HTTPS  (canonical form, in ~/.gstack-artifacts-remote.txt)
+Push:    $PUSH_URL  (derived SSH form for git push)
+
+EOF
+
+cat <<EOF
+─────────────────────────────────────────────────────────────────────────
+  Send this to your brain admin (the person who runs your gbrain server)
+─────────────────────────────────────────────────────────────────────────
+EOF
+
+if [ "$URL_FORM_SUPPORTED" = "true" ]; then
+  cat <<EOF
+On the brain host, run:
+
+  gbrain sources add $SOURCE_ID --url $CANONICAL_HTTPS --federated
+
+EOF
+else
+  cat <<EOF
+On the brain host (gbrain v0.26.x doesn't accept URLs directly yet), run:
+
+  git clone $CANONICAL_HTTPS ~/$SOURCE_ID
+  gbrain sources add $SOURCE_ID --path ~/$SOURCE_ID --federated
+
+When gbrain ships --url support, this becomes a one-liner:
+  gbrain sources add $SOURCE_ID --url $CANONICAL_HTTPS --federated
+
+EOF
+fi
+
+cat <<EOF
+After that, your CEO plans / designs / reports become searchable via
+'gbrain search' from any machine pointing at this brain.
+─────────────────────────────────────────────────────────────────────────
+
+New machine? Put a copy of $REMOTE_FILE in that machine's home directory,
+then run: gstack-artifacts-init  (it'll detect the remote and re-init).
+EOF

bin/gstack-artifacts-url

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# gstack-artifacts-url — canonical-URL helper for the artifacts repo.
+#
+# We store the HTTPS URL as canonical (in ~/.gstack-artifacts-remote.txt) and
+# derive other forms on demand. Centralizes the regex so callers don't each
+# string-mangle, which is how URL-format bugs creep into branch logic
+# (codex Finding #10).
+#
+# Usage:
+#   gstack-artifacts-url --to ssh    <https-url>   # https → git@host:owner/repo.git
+#   gstack-artifacts-url --to https  <any-url>     # idempotent canonicalization
+#   gstack-artifacts-url --host      <any-url>     # extract hostname
+#   gstack-artifacts-url --owner-repo <any-url>    # extract owner/repo
+#
+# Inputs accepted:
+#   https://github.com/garrytan/gstack-artifacts-garrytan
+#   https://github.com/garrytan/gstack-artifacts-garrytan.git
+#   git@github.com:garrytan/gstack-artifacts-garrytan.git
+#   ssh://git@gitlab.com/garrytan/gstack-artifacts-garrytan.git
+#   git@gitlab.example.org:team/gstack-artifacts-team.git
+#
+# Output: the requested form on stdout. Exits non-zero on parse failure with
+# an error on stderr.
+set -euo pipefail
+
+usage() {
+  echo "Usage: gstack-artifacts-url --to {ssh|https} <url>" >&2
+  echo "       gstack-artifacts-url --host <url>" >&2
+  echo "       gstack-artifacts-url --owner-repo <url>" >&2
+  exit 2
+}
+
+[ $# -ge 2 ] || usage
+
+mode=""
+to=""
+case "$1" in
+  --to) mode="to"; to="$2"; shift 2 ;;
+  --host) mode="host"; shift ;;
+  --owner-repo) mode="owner-repo"; shift ;;
+  *) usage ;;
+esac
+
+[ $# -eq 1 ] || usage
+url="$1"
+
+# Strip trailing .git for normalization; reattach where needed.
+strip_git() {
+  echo "${1%.git}"
+}
+
+# Parse to (host, owner_repo) regardless of input shape.
+parse_url() {
+  local u="$1"
+  local host="" owner_repo=""
+  case "$u" in
+    https://*)
+      # https://host/owner/repo[.git]
+      local rest="${u#https://}"
+      host="${rest%%/*}"
+      owner_repo="${rest#*/}"
+      owner_repo=$(strip_git "$owner_repo")
+      ;;
+    ssh://*)
+      # ssh://git@host/owner/repo[.git] OR ssh://host/owner/repo[.git]
+      local rest="${u#ssh://}"
+      # Strip optional user@
+      rest="${rest#*@}"
+      host="${rest%%/*}"
+      owner_repo="${rest#*/}"
+      owner_repo=$(strip_git "$owner_repo")
+      ;;
+    git@*:*)
+      # git@host:owner/repo[.git]
+      local rest="${u#git@}"
+      host="${rest%%:*}"
+      owner_repo="${rest#*:}"
+      owner_repo=$(strip_git "$owner_repo")
+      ;;
+    *)
+      echo "gstack-artifacts-url: unrecognized URL form: $u" >&2
+      exit 3
+      ;;
+  esac
+  if [ -z "$host" ] || [ -z "$owner_repo" ] || [ "$owner_repo" = "$u" ]; then
+    echo "gstack-artifacts-url: failed to parse host/owner from: $u" >&2
+    exit 3
+  fi
+  printf '%s\n%s\n' "$host" "$owner_repo"
+}
+
+parsed=$(parse_url "$url")
+host=$(echo "$parsed" | head -1)
+owner_repo=$(echo "$parsed" | tail -1)
+
+case "$mode" in
+  to)
+    case "$to" in
+      ssh)   printf 'git@%s:%s.git\n' "$host" "$owner_repo" ;;
+      https) printf 'https://%s/%s\n' "$host" "$owner_repo" ;;
+      *) usage ;;
+    esac
+    ;;
+  host)       printf '%s\n' "$host" ;;
+  owner-repo) printf '%s\n' "$owner_repo" ;;
+esac

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).

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

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

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"
 }
 

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

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
     ;;

bin/gstack-gbrain-detect

@@ -11,8 +11,10 @@
 #     "gbrain_config_exists": true|false,
 #     "gbrain_engine": "pglite"|"postgres" | null,
 #     "gbrain_doctor_ok": true|false,
+#     "gbrain_mcp_mode": "local-stdio"|"remote-http"|"none",
 #     "gstack_brain_sync_mode": "off"|"artifacts-only"|"full",
-#     "gstack_brain_git": true|false
+#     "gstack_brain_git": true|false,
+#     "gstack_artifacts_remote": "https://..." | ""
 #   }
 #
 # The /setup-gbrain skill reads this once at startup to decide which path
@@ -78,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
@@ -92,6 +94,76 @@ if [ -d "$STATE_DIR/.git" ]; then
   gstack_brain_git=true
 fi
 
+# --- gbrain_mcp_mode: local-stdio | remote-http | none ---
+# Defense-in-depth fallback chain (intentional ordering, do not reorder):
+#   1. `claude mcp get gbrain --json` — public CLI surface, structured output
+#   2. `claude mcp list` text-grep    — older claude versions without --json
+#   3. `~/.claude.json` jq read       — last resort if `claude` isn't on PATH
+# Fallback chain logged because if Anthropic moves the file or renames keys,
+# the third tier breaks silently; the first two tiers should catch it.
+gbrain_mcp_mode="none"
+if command -v claude >/dev/null 2>&1; then
+  # Tier 1: claude mcp get --json
+  if mcp_get_json=$(claude mcp get gbrain --json 2>/dev/null); then
+    if echo "$mcp_get_json" | jq -e '.' >/dev/null 2>&1; then
+      mtype=$(echo "$mcp_get_json" | jq -r '.type // .transport // empty' 2>/dev/null)
+      mcommand=$(echo "$mcp_get_json" | jq -r '.command // empty' 2>/dev/null)
+      murl=$(echo "$mcp_get_json" | jq -r '.url // empty' 2>/dev/null)
+      case "$mtype" in
+        http|sse) gbrain_mcp_mode="remote-http" ;;
+        stdio)    gbrain_mcp_mode="local-stdio" ;;
+        *)
+          # Newer claude versions may emit just url + command; infer.
+          if [ -n "$murl" ]; then gbrain_mcp_mode="remote-http"
+          elif [ -n "$mcommand" ]; then gbrain_mcp_mode="local-stdio"
+          fi
+          ;;
+      esac
+    fi
+  fi
+  # Tier 2: claude mcp list text-grep (only if Tier 1 didn't resolve)
+  if [ "$gbrain_mcp_mode" = "none" ]; then
+    if mcp_list=$(claude mcp list 2>/dev/null); then
+      gbrain_line=$(echo "$mcp_list" | grep -E '^gbrain:' || true)
+      if [ -n "$gbrain_line" ]; then
+        if echo "$gbrain_line" | grep -q 'http\|HTTP'; then
+          gbrain_mcp_mode="remote-http"
+        else
+          gbrain_mcp_mode="local-stdio"
+        fi
+      fi
+    fi
+  fi
+fi
+# Tier 3: ~/.claude.json jq read (only if claude binary or earlier tiers failed)
+if [ "$gbrain_mcp_mode" = "none" ]; then
+  if [ -f "$HOME/.claude.json" ]; then
+    # Look for a gbrain MCP server entry. Type field disambiguates http vs stdio.
+    mtype=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
+    murl=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null)
+    mcommand=$(jq -r '.mcpServers.gbrain.command // empty' "$HOME/.claude.json" 2>/dev/null)
+    case "$mtype" in
+      url|http|sse) gbrain_mcp_mode="remote-http" ;;
+      stdio)        gbrain_mcp_mode="local-stdio" ;;
+      *)
+        if [ -n "$murl" ]; then gbrain_mcp_mode="remote-http"
+        elif [ -n "$mcommand" ]; then gbrain_mcp_mode="local-stdio"
+        fi
+        ;;
+    esac
+  fi
+fi
+
+# --- artifacts remote URL (post-rename) with brain-* fallback during the
+#     migration window (gstack-upgrade migration runs the rename). ---
+gstack_artifacts_remote=""
+if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
+  gstack_artifacts_remote=$(head -1 "$HOME/.gstack-artifacts-remote.txt" 2>/dev/null | tr -d '[:space:]' || true)
+elif [ -f "$HOME/.gstack-brain-remote.txt" ]; then
+  # Pre-migration fallback. Migration v1.27.0.0 will mv this to the new path.
+  gstack_artifacts_remote=$(head -1 "$HOME/.gstack-brain-remote.txt" 2>/dev/null | tr -d '[:space:]' || true)
+fi
+
 # Emit single-object JSON.
 jq -n \
   --argjson on_path "$gbrain_on_path" \
@@ -99,14 +171,18 @@ jq -n \
   --argjson config_exists "$gbrain_config_exists" \
   --argjson engine "$gbrain_engine" \
   --argjson doctor_ok "$gbrain_doctor_ok" \
+  --arg mcp_mode "$gbrain_mcp_mode" \
   --arg sync_mode "$gstack_brain_sync_mode" \
   --argjson brain_git "$gstack_brain_git" \
+  --arg artifacts_remote "$gstack_artifacts_remote" \
   '{
     gbrain_on_path: $on_path,
     gbrain_version: $version,
     gbrain_config_exists: $config_exists,
     gbrain_engine: $engine,
     gbrain_doctor_ok: $doctor_ok,
+    gbrain_mcp_mode: $mcp_mode,
     gstack_brain_sync_mode: $sync_mode,
-    gstack_brain_git: $brain_git
+    gstack_brain_git: $brain_git,
+    gstack_artifacts_remote: $artifacts_remote
   }'

bin/gstack-gbrain-mcp-verify

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# gstack-gbrain-mcp-verify — probe a remote gbrain MCP endpoint.
+#
+# Usage:
+#   GBRAIN_MCP_TOKEN=<bearer> gstack-gbrain-mcp-verify <url>
+#
+# Output (always valid JSON):
+#   {
+#     "status": "success" | "network" | "auth" | "malformed",
+#     "server_name": "gbrain" | null,
+#     "server_version": "0.26.8" | null,
+#     "error_class": "NETWORK" | "AUTH" | "MALFORMED" | null,
+#     "error_text": "<remediation hint + raw>" | null,
+#     "sources_add_url_supported": true | false,
+#     "raw_initialize_body": "<full body for debugging>" | null
+#   }
+#
+# Token is consumed from the GBRAIN_MCP_TOKEN env var, never argv. Prevents
+# shell-history / `ps` exposure of the bearer.
+#
+# Three error classes:
+#   NETWORK   — DNS / TCP / no HTTP response
+#   AUTH      — 401, 403, or 500 with stale-token-shaped body
+#   MALFORMED — 2xx but missing serverInfo, OR `Not Acceptable` (the dual
+#               Accept-header gotcha)
+#
+# `sources_add_url_supported` probes capability via tools/list — true iff the
+# remote exposes `mcp__gbrain__sources_add` (gbrain hasn't shipped this as
+# of v0.26.x; field is forward-compatible).
+#
+# Exit codes: 0 on success, 1 on classified failure, 2 on usage error.
+set -euo pipefail
+
+die_usage() {
+  echo "Usage: GBRAIN_MCP_TOKEN=<bearer> gstack-gbrain-mcp-verify <url>" >&2
+  exit 2
+}
+
+[ $# -eq 1 ] || die_usage
+URL="$1"
+[ -n "${GBRAIN_MCP_TOKEN:-}" ] || { echo "gstack-gbrain-mcp-verify: GBRAIN_MCP_TOKEN env var required" >&2; exit 2; }
+
+command -v curl >/dev/null 2>&1 || { echo "gstack-gbrain-mcp-verify: curl is required" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { echo "gstack-gbrain-mcp-verify: jq is required (brew install jq)" >&2; exit 2; }
+
+emit() {
+  # emit <status> <server_name> <server_version> <error_class> <error_text> <url_supported> <raw_body>
+  jq -n \
+    --arg status "$1" \
+    --arg server_name "${2:-}" \
+    --arg server_version "${3:-}" \
+    --arg error_class "${4:-}" \
+    --arg error_text "${5:-}" \
+    --argjson url_supported "${6:-false}" \
+    --arg raw "${7:-}" \
+    '{
+      status: $status,
+      server_name: (if $server_name == "" then null else $server_name end),
+      server_version: (if $server_version == "" then null else $server_version end),
+      error_class: (if $error_class == "" then null else $error_class end),
+      error_text: (if $error_text == "" then null else $error_text end),
+      sources_add_url_supported: $url_supported,
+      raw_initialize_body: (if $raw == "" then null else $raw end)
+    }'
+}
+
+# JSON-RPC initialize body. Both `application/json` AND `text/event-stream`
+# in Accept — the MCP server returns 406 Not Acceptable without both. The
+# transcript that motivated this script hit that exact failure.
+INIT_BODY='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"gstack-mcp-verify","version":"1"}}}'
+
+# Capture HTTP code + body in one pass; --max-time 10 caps total wall time.
+TMPBODY=$(mktemp -t gstack-mcp-verify.XXXXXX)
+trap 'rm -f "$TMPBODY"' EXIT
+
+set +e
+HTTP_CODE=$(curl -s -o "$TMPBODY" -w '%{http_code}' \
+  --max-time 10 \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H "Authorization: Bearer $GBRAIN_MCP_TOKEN" \
+  -d "$INIT_BODY" \
+  "$URL" 2>/dev/null)
+CURL_EXIT=$?
+set -e
+
+BODY=$(cat "$TMPBODY" 2>/dev/null || echo "")
+
+# --- NETWORK class: curl exited nonzero, no HTTP response ---
+if [ "$CURL_EXIT" -ne 0 ] || [ -z "$HTTP_CODE" ] || [ "$HTTP_CODE" = "000" ]; then
+  HOST=$(echo "$URL" | sed -E 's|^https?://([^/:]+).*|\1|')
+  emit "network" "" "" "NETWORK" "check Tailscale/DNS to ${HOST} (curl exit=${CURL_EXIT})" false "$BODY"
+  exit 1
+fi
+
+# --- AUTH class: 401, 403, or 500 with stale-token-shaped body ---
+case "$HTTP_CODE" in
+  401|403)
+    emit "auth" "" "" "AUTH" "rotate token on the brain host, re-run /setup-gbrain (HTTP $HTTP_CODE)" false "$BODY"
+    exit 1
+    ;;
+  500)
+    if echo "$BODY" | grep -qiE '"(error_description|message)":[[:space:]]*"[^"]*(auth|token|unauthorized)' 2>/dev/null; then
+      emit "auth" "" "" "AUTH" "rotate token on the brain host, re-run /setup-gbrain (HTTP 500 stale-token shape)" false "$BODY"
+      exit 1
+    fi
+    ;;
+esac
+
+# Anything not 2xx that isn't auth-shaped → MALFORMED with raw HTTP code.
+case "$HTTP_CODE" in
+  2*) ;;
+  *)
+    emit "malformed" "" "" "MALFORMED" "server returned HTTP $HTTP_CODE; verify URL + version compatibility" false "$BODY"
+    exit 1
+    ;;
+esac
+
+# --- 2xx path: body may be JSON or SSE-wrapped JSON. Strip SSE if present. ---
+# MCP servers return SSE format: `event: message\ndata: {...}\n\n`. Extract
+# just the JSON payload from the data: line, falling back to the body as-is.
+if echo "$BODY" | head -1 | grep -q '^event:'; then
+  JSON_BODY=$(echo "$BODY" | sed -n 's/^data: //p' | head -1)
+else
+  JSON_BODY="$BODY"
+fi
+
+# `Not Acceptable` is a JSON-RPC error from the MCP server itself, returned
+# with HTTP 200 if the SSE Accept header was missing. Detect it explicitly.
+if echo "$JSON_BODY" | jq -e '.error.message | test("[Nn]ot [Aa]cceptable")' >/dev/null 2>&1; then
+  emit "malformed" "" "" "MALFORMED" "Accept-header gotcha: pass both 'application/json' AND 'text/event-stream'" false "$BODY"
+  exit 1
+fi
+
+SERVER_NAME=$(echo "$JSON_BODY" | jq -r '.result.serverInfo.name // empty' 2>/dev/null)
+SERVER_VERSION=$(echo "$JSON_BODY" | jq -r '.result.serverInfo.version // empty' 2>/dev/null)
+
+if [ -z "$SERVER_NAME" ] || [ -z "$SERVER_VERSION" ]; then
+  emit "malformed" "" "" "MALFORMED" "server may be on a newer gbrain version; missing result.serverInfo. Verify with: curl -H 'Accept: application/json, text/event-stream'" false "$BODY"
+  exit 1
+fi
+
+# --- Capability probe: tools/list to detect sources_add ---
+# Best-effort. A failure here doesn't fail the verify; we just default
+# sources_add_url_supported=false. Future gbrain versions that ship
+# mcp__gbrain__sources_add will flip this true and gstack-artifacts-init
+# will print the one-liner form instead of the clone-then-path form.
+URL_SUPPORTED=false
+TOOLS_BODY_FILE=$(mktemp -t gstack-mcp-tools.XXXXXX)
+TOOLS_REQ='{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
+
+set +e
+curl -s -o "$TOOLS_BODY_FILE" \
+  --max-time 10 \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H "Authorization: Bearer $GBRAIN_MCP_TOKEN" \
+  -d "$TOOLS_REQ" \
+  "$URL" >/dev/null 2>&1
+TOOLS_EXIT=$?
+set -e
+
+if [ "$TOOLS_EXIT" -eq 0 ]; then
+  TOOLS_BODY=$(cat "$TOOLS_BODY_FILE" 2>/dev/null || echo "")
+  if echo "$TOOLS_BODY" | head -1 | grep -q '^event:'; then
+    TOOLS_JSON=$(echo "$TOOLS_BODY" | sed -n 's/^data: //p' | head -1)
+  else
+    TOOLS_JSON="$TOOLS_BODY"
+  fi
+  if echo "$TOOLS_JSON" | jq -e '.result.tools[] | select(.name | test("sources_add"))' >/dev/null 2>&1; then
+    URL_SUPPORTED=true
+  fi
+fi
+rm -f "$TOOLS_BODY_FILE"
+
+emit "success" "$SERVER_NAME" "$SERVER_VERSION" "" "" "$URL_SUPPORTED" "$BODY"
+exit 0

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"
 

bin/gstack-jsonl-merge

@@ -4,7 +4,7 @@
 # Usage (called by git, not by users):
 #   gstack-jsonl-merge <base> <ours> <theirs>
 #
-# Registered in local git config by bin/gstack-brain-init and
+# Registered in local git config by bin/gstack-artifacts-init and
 # bin/gstack-brain-restore:
 #   git config merge.jsonl-append.driver \
 #       "$GSTACK_BIN/gstack-jsonl-merge %O %A %B"

bin/gstack-timeline-log

@@ -2,9 +2,9 @@
 # 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
+# stop-gate from `gstack-artifacts-init` or the preamble — timeline events are
 # published to the user's private GBrain sync repo. See docs/gbrain-sync.md.
 # Required fields: skill, event (started|completed).
 # Optional: branch, outcome, duration_s, session, ts.